patch

type ParsedPatch struct {
	Operations        []*PatchOperation
	EstimatedCost     int
	AffectedPaths     []string
	PolicyConstraints *PatchPolicyConstraints
}

type Parser struct {
	// contains filtered or unexported fields
}

type PatchOp string

type PatchOperation struct {
	Op     PatchOp
	Path   string
	From   string
	Value  any
	Schema *PathSchema

	// Merge marks an op derived from an RFC 7396 merge patch whose value is
	// an object — it requires RECURSIVE merge semantics, not whole-value
	// replace. The apply path deep-merges via
	// internal/jsonmerge; BuildPatchSQL compiles it to json_patch on SQLite
	// and per-level jsonb construction on PostgreSQL, so sibling keys survive.
	Merge bool
}

type PatchPolicyConstraints struct {
	ForbiddenPaths   []string
	ValueConstraints map[string]*ValueConstraint
	Validators       []PatchValidator
}

type PatchSQLOption func(*patchSQLConfig)

type PatchSQLResult struct {
	// SetClause is the comma-separated `col = $N` fragment ready to drop
	// into UPDATE … SET. Empty when the patch only touches relation
	// fields (junction-only patches).
	SetClause string

	// Args are the bound values for SetClause placeholders, in $N order.
	Args []any

	// ParamCount is the number of placeholders consumed by SetClause.
	// Callers append filter params starting at startParam + ParamCount.
	ParamCount int

	// Empty is true when neither the column SET clause nor any relation
	// op produced output — the caller can short-circuit with no DB writes.
	Empty bool

	// RelationOps holds parsed-but-unrendered junction operations
	// extracted from the patch. The repository decorator
	// runs these alongside the owner UPDATE in a single transaction:
	// the UPDATE runs first (or is skipped when SetClause is empty),
	// then for each RelationOp the decorator emits a junction
	// DELETE / INSERT bound to the affected owner PKs returned by the
	// UPDATE … RETURNING clause.
	RelationOps []RelationPatchOp
}

type PatchSchema struct {
	Resource      string
	AllowedPaths  map[string]*PathSchema
	MaxOperations int
	// contains filtered or unexported fields
}

type PatchValidator func(op *PatchOperation, subject *core.PolicySubject) error

type PathSchema struct {
	AllowedOps []PatchOp
	DataType   core.FieldType
	// SQLType distinguishes declared JSON from native driver-value storage.
	SQLType core.SQLType
	// GoType is the Go type the path's value decodes into (the struct
	// field's type, pointer included). It drives parse-time validation so an
	// accepted operation always applies: numeric range
	// against the exact kind, nullability (only pointer, slice, map and
	// interface fields accept null or remove), array element types, and the
	// shape of struct / map values. nil — hand-built schemas — validates by
	// DataType alone over the widest numeric domain and admits null.
	GoType     reflect.Type
	Validators []core.Validator
	// EnumValues is the path's `enum` allowlist (also a Validator), for
	// schema discovery.
	EnumValues []string
	SQLColumn  string

	// Relation is non-nil when the path patches an M2M relation rather
	// than a scalar column. When set, BuildPatchSQL emits
	// junction INSERT/DELETE statements into PatchSQLResult.RelationOps
	// instead of touching SQLColumn (which is "" for relation paths).
	// AllowedOps for a relation path is the relation-verb subset
	// (replace / add / remove); RFC 6902's move/copy/test are rejected
	// at validation with E2117.
	Relation *core.RelationSchema
}

type RawPatchOp struct {
	Op    string `json:"op"`
	Path  string `json:"path"`
	From  string `json:"from,omitempty"`
	Value any    `json:"value,omitempty"`
	// HasValue reports that the operation carried a value member, so an
	// explicit null is told from no value at all. Parse sets it; a caller of
	// ParseOps sets it for a null value — a non-nil Value implies it.
	HasValue bool `json:"-"`
}

type RelationOwner struct {
	Table, Key, Tenant string
}

type RelationPatchOp struct {
	// Field is the filter-API field name that the patch path resolved
	// to (e.g. "tags" for path "/tags"). Used for error messages and
	// audit logs.
	Field string

	// Schema is the junction descriptor (junction table, source/target
	// columns, optional tenant column).
	Schema *core.RelationSchema

	// Verb is the membership change verb derived from the wire op.
	Verb RelationVerb

	// Values is the list of target IDs the verb applies to. Empty is
	// valid for RelationVerbReplace (clears the relation) but not for
	// add / remove.
	Values []any
}

type RelationVerb string

type RenderRelationOpOptions struct {
	// TenantValue is bound into every junction statement as the value of
	// RelationSchema.TenantColumn. Required when the schema declares a
	// TenantColumn — rendering fails without it unless Unscoped is set
	//. Ignored for unscoped junctions.
	TenantValue any
	// Unscoped deliberately renders a tenant-scoped junction without a
	// tenant predicate. Never set it on a request path.
	Unscoped bool
	// Owner names the owner table, key and tenant column. A many-to-many
	// with a target (RelationSchema.TargetTable) needs it: its inserts
	// select the owner rows and the visible target rows instead of binding
	// raw values, so no pair names a target the request cannot see.
	Owner RelationOwner
	// TargetVisible renders the predicate (starting " AND ", or "") that
	// holds the target rows under alias to those the request may relate,
	// binding values with bind (filter.VisibleRelated). Required with a
	// TargetTable: inserts pair only visible targets, and deletes remove
	// only pairs to them.
	TargetVisible func(alias string, bind func(any) string) (string, error)
}

type RenderedRelationStatement struct {
	SQL  string
	Args []any
}

type SQLDialect interface {
	dialect.Dialect
	MarshalValue(value any, t core.TypeInfo) (any, error)
}

type ValueConstraint struct {
	AllowedValues []any
	DeniedValues  []any
	Pattern       string
	Min           *float64
	Max           *float64
	// contains filtered or unexported fields
}