backend

type AggregateOp string

type Backend interface {
	Get(ctx context.Context, collection, id string) ([]byte, error)
	Put(ctx context.Context, collection, id string, data []byte) error
	Delete(ctx context.Context, collection, id string) error

	Query(ctx context.Context, collection string, q *Query) (Iterator, error)
	Count(ctx context.Context, collection string, q *Query) (int64, error)
	Exists(ctx context.Context, collection string, q *Query) (bool, error)
	Aggregate(ctx context.Context, collection string, op AggregateOp, field string, q *Query) (*float64, error)
	GroupBy(ctx context.Context, collection string, groupFields []string, aggs []GroupByAgg, q *Query) ([]GroupByRow, error)

	EnsureIndex(ctx context.Context, collection string, idx IndexDefinition) error
	DropIndex(ctx context.Context, collection string, name string) error
	ListRecordedIndexes(ctx context.Context, collection string) ([]RecordedIndex, error)

	EnsureCollection(ctx context.Context, name string, meta CollectionMeta) error
	DropCollection(ctx context.Context, name string) error

	Begin(ctx context.Context) (Transaction, error)

	Ping(ctx context.Context) error
	Close() error
}

type CollectionMeta struct {
	Name              string
	Fields            []FieldMeta
	Indexes           []IndexDefinition
	HasSoftDelete     bool
	HasRevision       bool
	HasChangeTracking bool
}

type FieldMeta struct {
	Name      string
	GoName    string
	Type      string
	Indexed   bool
	Unique    bool
	FTS       bool
	IsPointer bool
}

type GroupByAgg struct {
	Op    AggregateOp
	Field string // source field (ignored for OpCount)
}

type GroupByRow struct {
	Keys   []string  // group key values (text representation), one per group field
	Values []float64 // aggregate values, matching GroupByAgg order
}

type GroupBySortEntry struct {
	Op    AggregateOp
	Field string
	Dir   SortDirection
}

type IndexDefinition struct {
	Name   string
	Fields []string
	Unique bool
}

type Iterator interface {
	Next() bool
	Bytes() []byte
	ID() string
	Err() error
	Close() error
}

type LinkFieldMeta struct {
	JSONName         string       // JSON key of the field
	GoName           string       // Go struct field name
	Slice            bool         // true for []Link[T], false for Link[T]
	Eager            bool         // true when tagged den:"eager"
	TargetCollection string       // collection of T; "" if T is not registered
	TargetType       reflect.Type // T in Link[T]
}

type LockMode int

type Query struct {
	Collection string
	Conditions []where.Condition
	SortFields []SortEntry
	LimitN     int // 0 = no limit
	SkipN      int // 0 = no skip
	AfterID    string
	BeforeID   string
	// Lock requests a row-level lock on every matching row (PostgreSQL
	// only; SQLite ignores it because IMMEDIATE tx already serializes
	// writers). nil means no lock; a non-nil pointer's value selects the
	// lock mode. The pointer form rules out the previously-possible
	// invalid pair of (ForUpdate=false, LockMode!=LockDefault).
	Lock *LockMode

	// GroupBySort carries ORDER BY entries that target aggregates in a
	// GROUP BY query. SortFields are used for group-key ordering; aggregate
	// ordering needs the (Op, Field) tuple because no source-field name
	// identifies a synthetic aggregate column. Only consumed by GroupBy
	// paths — other terminals ignore this slice.
	GroupBySort []GroupBySortEntry
}

type ReadWriter interface {
	Get(ctx context.Context, collection, id string) ([]byte, error)
	Put(ctx context.Context, collection, id string, data []byte) error
	Delete(ctx context.Context, collection, id string) error
	Query(ctx context.Context, collection string, q *Query) (Iterator, error)
	Count(ctx context.Context, collection string, q *Query) (int64, error)
	Exists(ctx context.Context, collection string, q *Query) (bool, error)
	Aggregate(ctx context.Context, collection string, op AggregateOp, field string, q *Query) (*float64, error)
	GroupBy(ctx context.Context, collection string, groupFields []string, aggs []GroupByAgg, q *Query) ([]GroupByRow, error)
}

type RecordedIndex struct {
	Name   string
	Fields []string
	Unique bool
}

type SortDirection int

type SortEntry struct {
	Field string
	Dir   SortDirection
}

type Transaction interface {
	ReadWriter
	Commit() error
	Rollback() error

	// GetForUpdate reads a document and acquires a row-level lock that
	// persists until the transaction commits or rolls back. On PostgreSQL
	// this maps to SELECT ... FOR UPDATE, optionally with SKIP LOCKED or
	// NOWAIT. On SQLite it is a no-op because IMMEDIATE transactions
	// already serialize writers; the mode parameter is ignored.
	GetForUpdate(ctx context.Context, collection, id string, mode LockMode) ([]byte, error)

	// AdvisoryLock acquires an application-defined lock identified by key
	// that persists until the transaction commits or rolls back. Concurrent
	// transactions attempting to acquire the same key block until the holder
	// ends. Unlike GetForUpdate this does not require a row to exist, so it
	// is suitable for bootstrap paths like coordinating concurrent migration
	// starters before any state row has been written.
	//
	// On PostgreSQL this maps to pg_advisory_xact_lock. On SQLite it is a
	// no-op because IMMEDIATE transactions already serialize writers on the
	// whole database.
	AdvisoryLock(ctx context.Context, key int64) error
}