core

type Bounds struct {
	// MinLen and MaxLen are the fewest and most characters; nil is
	// unbounded.
	MinLen, MaxLen *int
	// Min and Max are the least and greatest number as canonical decimal
	// text (DecimalText); empty is unbounded.
	Min, Max string
	// MinItems and MaxItems are the fewest and most elements of an array;
	// nil is unbounded.
	MinItems, MaxItems *int
}

type Capabilities struct {
	Filter, Sort, Patch, Search, Facet, Include, Server bool
	Excluded                                            bool
}

type Code string

type Codec interface {
	Encode(v any) ([]byte, error)
	Decode(data []byte, v any) error
}

type ConstraintError struct {
	Constraint string
	Limit      string
	// contains filtered or unexported fields
}

type Date string

type Decimal interface {
	Coefficient() *big.Int
	Exponent() int32
}

type Field struct {
	// GoName is the Go field name.
	GoName string
	// Type is the field's declared type.
	Type reflect.Type
	// Route is the index path from the walked type to the field, through
	// the embedded structs it is promoted from.
	Route []int
	// External is the field's name under the field-name tag, by
	// encoding/json's rule (the tag's name, else the Go name). It is empty
	// when the tag hides the field, or the embedded struct it is promoted
	// from (`json:"-"`).
	External string
	// Tags are the field's annotations, parsed once.
	Tags Tags
}

type FieldType string

type GeneratorOption func(*GeneratorOptions)

type GeneratorOptions struct {
	// SQLTableName overrides the derived table name for this specific type.
	// Takes precedence over TableConvention.
	SQLTableName string

	// ColumnTypes declares physical storage independently of Go field shape.
	ColumnTypes map[string]SQLType

	// ColumnMapper provides full control over column expression generation.
	// Takes precedence over ColumnConvention and ColumnTag.
	ColumnMapper SQLColumnMapper

	// ColumnConvention transforms field names to SQL column names.
	// Default: SnakeCase. Ignored when ColumnMapper is set.
	ColumnConvention NamingConvention

	// TableNameConvention transforms type names to SQL table names.
	// Default: PluralSnake ("Product" → "products").
	// Ignored when SQLTableName is set.
	TableNameConvention TableConvention

	// FieldNameTag is the struct tag to read for external field names.
	// Default: "json". Set to "bson", "yaml", etc. for non-JSON APIs.
	FieldNameTag string

	// ColumnTag is the struct tag to read for SQL column names.
	// Default: "db". Set to "sql", "column", etc. for your ORM.
	ColumnTag string

	// DefaultFilterOps maps FieldType to default filter operators when the
	// filter_ops tag is omitted.
	DefaultFilterOps map[FieldType][]string

	// DefaultPatchOps maps FieldType to default patch operations when the
	// patch_ops tag is omitted.
	DefaultPatchOps map[FieldType][]string

	// SortMaxFields caps how many sort fields a generated SortSchema accepts.
	// Zero means the default of 3.
	SortMaxFields int

	// SearchParam is the query-string parameter name a generated SearchSchema
	// advertises for its free-text search box. Empty means "search", the
	// parameter list handlers read (filter.ParamSearch).
	SearchParam string
}

type NamingConvention func(string) string

type Option func(*ParserConfig)

type ParseError struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Kind    ParseErrorKind `json:"kind"`
	Path    string         `json:"path,omitempty"`
	Index   *int           `json:"index,omitempty"` // pointer so op index 0 survives the wire
	Details map[string]any `json:"details,omitempty"`
	Cause   error          `json:"-"`
}

type ParseErrorKind string

type ParserConfig struct {
	// MaxDepth bounds request structure depth: filter boolean nesting,
	// JSON filter document nesting and patch JSON Pointer segments.
	MaxDepth int
	// MaxCost bounds a filter's estimated cost: about 1 per indexed
	// condition, 10 per unindexed one, more for documents, relations,
	// unanchored patterns and $or.
	MaxCost int
	// MaxInputSize bounds a filter or patch body in bytes.
	MaxInputSize int
	// MaxConditions bounds a filter's leaf conditions.
	MaxConditions int
	// MaxArraySize bounds $in / $nin members, array $contains elements and
	// the values in a JSON filter document.
	MaxArraySize int
	// MaxPatchCopyBytes bounds the total bytes a patch's copy operations may
	// add to a document during typed apply (copy amplification guard).
	MaxPatchCopyBytes int64
	GeneratorOpts     []GeneratorOption
	Codec             Codec            // Wire format codec. Nil = encoding/json fallback.
	Clock             func() time.Time // Relative-time anchor (`now-7d`). Nil = time.Now().UTC.
}

type PolicySubject struct {
	ID          string
	TenantID    string
	TenantPath  string
	Roles       []string
	Groups      []string
	Permissions []string
	Attributes  map[string]any
}

type RelationKind string

type RelationSchema struct {
	// Kind is the relation's cardinality.
	Kind RelationKind

	// JoinTable is the name of the junction table (e.g. "widget_tags").
	JoinTable string

	// SourceColumn is the column on JoinTable that holds the owner's PK
	// (e.g. "widget_id").
	SourceColumn string

	// TargetColumn is the column on JoinTable that holds the related
	// entity's PK (e.g. "tag_id").
	TargetColumn string

	// PrimaryKey is the owner entity's PK column (defaults to "id" when
	// empty).
	PrimaryKey string

	// TenantColumn names a tenant-scope column on the junction (typically
	// "tenant_id"). When non-empty, every junction statement parse emits —
	// filter, facet, include and relation patch — binds it to the caller's
	// tenant, and a builder without a bound tenant fails closed unless the
	// caller opts into unscoped relations explicitly. Empty
	// means the junction is not tenant-scoped (a globally shared table).
	TenantColumn string

	// DeletedColumn is JoinTable's soft-delete column: a row with it set
	// is not related.
	DeletedColumn string

	// TargetTable, when set, is the target table a many-to-many joins
	// through its pair table (on TargetTable.TargetKey = JoinTable.TargetColumn)
	// so predicates reach the target's columns; TargetTenant and
	// TargetDeleted scope its rows as TenantColumn and DeletedColumn scope
	// JoinTable's. Empty for a pair table compared by key alone.
	TargetTable   string
	TargetKey     string
	TargetTenant  string
	TargetDeleted string

	// Policy scopes the related target rows by the server's policy for the
	// target table instead of the tenant column.
	Policy bool
}

type SQLColumnMapper interface {
	MapColumn(table, field string, fieldType FieldType) string
}

type SQLType string

type SchemaGenerator struct {
	Opts *GeneratorOptions
}

type StdlibJSON struct{}

type StructFields struct {
	// Type is the walked struct type.
	Type reflect.Type
	// Fields holds the fields in declaration order, an embedded struct's
	// promoted fields in place of it.
	Fields []*Field
	// contains filtered or unexported fields
}

type TableConvention func(string) string

type Tags struct {
	// Parse is the field's parse capabilities.
	Parse Capabilities
	// Column is the column tag's text: empty when absent, "-" for a field
	// that is not a column.
	Column string
	// FieldNameOptions are the field-name tag's options (omitempty, ...).
	FieldNameOptions string

	Relation, RelationName string
	FilterOps, PatchOps    string
	Enum                   []string
	Bounds                 Bounds
	Facet                  string
	Paths, Elements        string
	Storage                string
	Geo, GeoSRID           string
	GeoLat, GeoLon         string
	Indexed, Immutable     bool
	Label, Description     string
	Group, Order           string
	SortDefault            string
	SearchWeight           string
}

type TypeInfo struct {
	Type FieldType
	// SQLType is the explicit storage declaration, empty for Go-only inference.
	SQLType SQLType
	// Elem is the element type of a FieldTypeArray; empty otherwise.
	Elem FieldType
	// NumberKind is the Go numeric kind of Type, or of Elem for an array;
	// reflect.Invalid when not numeric.
	NumberKind reflect.Kind
}

type Validator func(value any) error