reflectutil

Documentation

Overview

Package reflectutil provides a thread-safe, allocation-amortized reflection cache. Models are parsed once on first use; subsequent accesses are O(1).

It is the single source of truth for: column name resolution, primary-key discovery, soft-delete column detection, fillable/hidden lists, cast tags, and embedded base-model handling.

Index

• func IndirectValue(v reflect.Value) reflect.Value
• type Field
• type Schema
  • func Parse(v any) *Schema
  • func ParseType(t reflect.Type) *Schema
  • func (s *Schema) Columns() []string
  • func (s *Schema) FieldByColumn(col string) *Field
  • func (s *Schema) FieldByName(name string) *Field
  • func (s *Schema) InsertableColumns(v reflect.Value) ([]string, []any)

Functions

func IndirectValue

func IndirectValue(v reflect.Value) reflect.Value

IndirectValue dereferences a Value through pointers.

Types

type Field

type Field struct {
	// Name is the Go struct field name (e.g. "CreatedAt").
	Name string
	// Column is the database column name (e.g. "created_at"), resolved from
	// `column:"..."` tag or snake_case of Name.
	Column string
	// Index is the index path for reflect.Value.FieldByIndex.
	Index []int
	// Type is the field's Go type.
	Type reflect.Type
	// IsPrimary indicates the field is (part of) the primary key.
	IsPrimary bool
	// IsAutoIncrement marks an integer primary key as auto-increment.
	IsAutoIncrement bool
	// IsCreatedAt / IsUpdatedAt / IsDeletedAt mark timestamp columns.
	IsCreatedAt bool
	IsUpdatedAt bool
	IsDeletedAt bool
	// IsZeroOnInsert means "send NULL/skip when zero on insert".
	IsZeroOnInsert bool
	// Hidden columns are never serialized via ToMap.
	Hidden bool
	// Fillable indicates the column accepts mass assignment.
	Fillable bool
	// Cast is the registered cast name (e.g. "json", "date", "bool").
	Cast string
	// HasDefault is true when the column has a struct-tag default.
	HasDefault bool
	// Default is the literal default value as written in the tag.
	Default string
	// Nullable as declared on the field tag.
	Nullable bool
	// Skip means: ignore this field for persistence (`column:"-"`).
	Skip bool
	// IsRelation marks the field as a relation (slice of struct / pointer to
	// struct) discovered automatically; relations are not persisted as columns.
	IsRelation bool
}

Field describes one persistent struct field.

type Schema

type Schema struct {
	Type   reflect.Type
	Table  string
	Fields []*Field

	PrimaryKey  *Field
	CreatedAt   *Field
	UpdatedAt   *Field
	DeletedAt   *Field
	SoftDeletes bool
	// contains filtered or unexported fields
}

Schema describes a parsed model type.

func Parse

func Parse(v any) *Schema

Parse returns the cached Schema for v's underlying struct type. It transparently dereferences pointers and slices.

func ParseType

func ParseType(t reflect.Type) *Schema

ParseType returns the cached Schema for a reflect.Type directly.

func (*Schema) Columns

func (s *Schema) Columns() []string

Columns returns all persistent column names (excludes relations & skips).

func (*Schema) FieldByColumn

func (s *Schema) FieldByColumn(col string) *Field

FieldByColumn returns the Field with matching column name, or nil.

func (*Schema) FieldByName

func (s *Schema) FieldByName(name string) *Field

FieldByName returns the Field with matching Go name, or nil.

func (*Schema) InsertableColumns

func (s *Schema) InsertableColumns(v reflect.Value) ([]string, []any)

InsertableColumns returns columns to include on insert (skips relations, skip-marked, and zero-valued auto fields).