dal

type Adapter interface {

	// Name of the dalgo adapter
	Name() string

	// Version of the name if applicable
	Version() string
}

type AggregateFunc interface {
	Expression
	FuncName() string
	FuncArgs() []Expression
}

type Array struct {
	Value any `json:"value"`
}

type Backend interface {

	// ID is an identifier provided at time of DB creation
	ID() string

	// Adapter provides information about underlying name to access data
	Adapter() Adapter

	// Schema provides schema for the DB - for example, how keys are mapped to columns
	Schema() Schema

	// TransactionCoordinator provides shortcut methods to work with transactions
	// without opening a connection explicitly.
	TransactionCoordinator

	// ReadSession implements a virtual read session that opens connection/session for each read call on DB level
	// TODO: consider to sacrifice some simplicity for the sake of interoperability?
	ReadSession

	// ConcurrencyAware reports whether this backend supports concurrent
	// open connections. Drivers should embed NoConcurrency or
	// ConcurrencyAvailable in their concrete type to satisfy this.
	ConcurrencyAware
}

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

type Collection[K comparable, T any] interface {
	// GetData returns the record stored at id decoded as a T. On not-found it
	// returns the zero T and the not-found error from the session Get call (use
	// record.IsNotFound to test it).
	GetData(ctx context.Context, s ReadSession, id K) (T, error)

	// Get is a deprecated alias for GetData.
	//
	// Deprecated: use GetData.
	Get(ctx context.Context, s ReadSession, id K) (T, error)

	// GetRecord returns the underlying record.Record stored at id, with its Data set to
	// a *T. On not-found it returns the record (Exists() == false) together with
	// the not-found error from the session Get call.
	GetRecord(ctx context.Context, s ReadSession, id K) (record.Record, error)

	// GetRecordWithID reads id and returns a typed record.WithID[K] (id + key +
	// record, no typed data). On not-found it returns the zero value and the
	// session's not-found error.
	GetRecordWithID(ctx context.Context, s ReadSession, id K) (record.WithID[K], error)

	// GetRecordWithDataAndID reads id and returns a record.DataWithID[K, *T]
	// whose Data is the decoded *T (the same pointer held by the record.Record). On
	// not-found it returns the zero value and the session's not-found error.
	GetRecordWithDataAndID(ctx context.Context, s ReadSession, id K) (record.DataWithID[K, *T], error)

	// All returns every record in the collection, each decoded into a freshly
	// allocated value so results never alias. It surfaces ErrNotSupported from
	// backends that cannot run the query.
	All(ctx context.Context, s ReadSession) ([]T, error)

	// Count returns the number of records in the collection. It surfaces
	// ErrNotSupported from backends that cannot run the underlying query rather
	// than a silent 0.
	Count(ctx context.Context, s ReadSession) (int, error)

	// Exists reports whether a record exists at id. A not-found result maps to
	// (false, nil); any other failure is returned as (false, err).
	Exists(ctx context.Context, s ReadSession, id K) (bool, error)

	// First returns the first record in the collection (an underlying limit-1
	// query). An empty collection yields (zero T, false, nil); an incapable
	// backend surfaces ErrNotSupported.
	First(ctx context.Context, s ReadSession) (value T, found bool, err error)

	// Insert inserts value under a GENERATED id and returns the assigned key.
	// When opts is empty a default generator (WithRandomStringKey) is injected.
	// Only this terminal accepts InsertOption — generators cannot reach the
	// id-taking terminals.
	Insert(ctx context.Context, s WriteSession, value T, opts ...InsertOption) (*record.Key, error)

	// InsertWithID inserts value at a known id and returns the record's key.
	InsertWithID(ctx context.Context, s WriteSession, id K, value T) (*record.Key, error)

	// InsertRecord inserts a caller-built record. It is the shared primitive the
	// other inserts delegate to; opts carry an id generator for generated inserts.
	InsertRecord(ctx context.Context, s WriteSession, r record.Record, opts ...InsertOption) error

	// SetByID stores (upserts) value at id.
	SetByID(ctx context.Context, s WriteSession, id K, value T) error

	// Set is a deprecated alias for SetByID.
	//
	// Deprecated: use SetByID.
	Set(ctx context.Context, s WriteSession, id K, value T) error

	// SetRecord stores (upserts) a caller-built record.
	SetRecord(ctx context.Context, s WriteSession, r record.Record) error

	// UpdateByID applies field-level updates to the record at id.
	UpdateByID(ctx context.Context, s WriteSession, id K, updates []update.Update, preconditions ...Precondition) error

	// Update is a deprecated alias for UpdateByID.
	//
	// Deprecated: use UpdateByID.
	Update(ctx context.Context, s WriteSession, id K, updates []update.Update, preconditions ...Precondition) error

	// UpdateByKey applies field-level updates to the record at an explicit key.
	UpdateByKey(ctx context.Context, s WriteSession, k *record.Key, updates []update.Update, preconditions ...Precondition) error

	// DeleteByID deletes the record at id.
	DeleteByID(ctx context.Context, s WriteSession, id K) error

	// Delete is a deprecated alias for DeleteByID.
	//
	// Deprecated: use DeleteByID.
	Delete(ctx context.Context, s WriteSession, id K) error

	// DeleteByKey deletes the record at an explicit key.
	DeleteByKey(ctx context.Context, s WriteSession, k *record.Key) error

	// In returns a handle scoped under parent (one level of nesting).
	In(parent *record.Key) Collection[K, T]
}

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

type CollectionNamer interface {
	CollectionName() string
}

type CollectionOption func(*collectionOptions)

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

type Column struct {
	Alias      string     `json:"Alias"`
	Expression Expression `json:"expression"`
}

type Comparison struct {
	Operator Operator
	Left     Expression
	Right    Expression
}

type ConcurrencyAvailable struct{}

type ConcurrencyAware interface {
	// SupportsConcurrentConnections reports whether the underlying
	// backend tolerates more than one open connection from a single
	// client process at the same time. See [ConcurrencyAware] for the
	// stability and asymmetry contract.
	SupportsConcurrentConnections() bool
}

type Condition interface {
	fmt.Stringer
}

type Constant struct {
	Value any `json:"value"`
}

type Cursor string

type DB interface {
	Backend
	// contains filtered or unexported methods
}

type DataToKeyFunc func(incompleteKey *record.Key, data any) (key *record.Key, err error)

type DataWrapper interface {
	Data() any
}

type Deleter interface {

	// Delete deletes a single record from database by key
	Delete(ctx context.Context, key *record.Key) error
}

type EmptyReader struct{}

type ErrDuplicateUser struct {
	// TODO: Should it be moved out of this package to strongo/app/user?
	SearchCriteria   string
	DuplicateUserIDs []string
}

type ErrNotFoundByKey interface {
	Key() *record.Key
	Cause() error
	error
}

type Expression interface {
	fmt.Stringer
}

type ExtraField interface {
	Name() string
	Value() any
}

type FieldName string

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

type FromSource interface {
	Base() RecordsetSource
	Join(joint JoinedSource) FromSource
	Joins() []JoinedSource
	NewQuery() *QueryBuilder
}

type Getter interface {

	// Get gets a single record from a database by key
	Get(ctx context.Context, record record.Record) error

	// Exists returns true if a record with the given key exists
	Exists(ctx context.Context, key *record.Key) (bool, error)
}

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

type IDGenerator = func(ctx context.Context, record record.Record) error

type IQueryBuilder interface {
	Clone() IQueryBuilder
	Offset(int) IQueryBuilder
	Limit(int) IQueryBuilder
	Where(conditions ...Condition) IQueryBuilder
	WhereField(name string, operator Operator, v any) IQueryBuilder
	WhereInArrayField(name string, v any) IQueryBuilder
	WhereArrayContains(name string, v any) IQueryBuilder
	WhereArrayContainsAny(name string, values any) IQueryBuilder
	GroupBy(expressions ...Expression) IQueryBuilder
	Having(conditions ...Condition) IQueryBuilder
	OrderBy(expressions ...OrderExpression) IQueryBuilder
	SelectIntoRecord(func() record.Record) StructuredQuery
	SelectIntoRecordset(options ...recordset.Option) StructuredQuery
	SelectKeysOnly(idKind reflect.Kind) StructuredQuery
	SelectColumns(columns ...Column) StructuredQuery
	StartFrom(cursor Cursor) IQueryBuilder
}

type InsertOption func(options *insertOptions)

type InsertOptions interface {
	IDGenerator() IDGenerator

	// PreferAdapterGeneratedID reports whether WithAdapterGeneratedID was passed.
	// See WithAdapterGeneratedID for the contract adapters must follow.
	PreferAdapterGeneratedID() bool
}

type Inserter interface {

	// Insert inserts a single record intoRecord a database
	Insert(ctx context.Context, record record.Record, opts ...InsertOption) error
}

type Item[K comparable, T any] struct {
	ID    K
	Value T
}

type JoinType string

type JoinedSource struct {
	RecordsetSource
	// contains filtered or unexported fields
}

type KeyToFieldsFunc func(key *record.Key, data any) (fields []ExtraField, err error)

type ManyInserter[K comparable, T any] interface {
	// InsertMany inserts each item at its known id and returns the keys in
	// input order.
	InsertMany(ctx context.Context, s WriteSession, items ...Item[K, T]) (keys []*record.Key, err error)
}

type MultiDeleter interface {

	// DeleteMulti deletes multiple records from database by keys
	DeleteMulti(ctx context.Context, keys []*record.Key) error
}

type MultiGetter interface {

	// GetMulti gets multiple records from a database by keys
	GetMulti(ctx context.Context, records []record.Record) error
}

type MultiInserter interface {
	// InsertMulti inserts multiple record intoRecord a database at once if possible, or fallback to batch of single inserts
	InsertMulti(ctx context.Context, records []record.Record, opts ...InsertOption) error
}

type MultiSetter interface {

	// SetMulti stores multiples records intoRecord database by keys
	SetMulti(ctx context.Context, records []record.Record) error
}

type MultiUpdater interface {

	// UpdateMulti updates multiples records in database by keys
	UpdateMulti(ctx context.Context, keys []*record.Key, updates []update.Update, preconditions ...Precondition) error
}

type NoConcurrency struct{}

type Operator string

type OrderExpression interface {
	fmt.Stringer
	Expression() Expression
	Descending() bool
}

type Precondition interface {
	// contains filtered or unexported methods
}

type Preconditions interface {
	Exists() bool
	LastUpdateTime() time.Time
}

type Query interface {
	String() string

	// Offset specifies the number of records to skip
	Offset() int

	// Limit specifies the maximum number of records to be returned
	Limit() int

	GetRecordsReader(ctx context.Context, qe QueryExecutor) (reader RecordsReader, err error)
	GetRecordsetReader(ctx context.Context, qe QueryExecutor) (reader RecordsetReader, err error)
}

type QueryArg struct {
	Name  string
	Value any
}

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

type QueryExecutor interface {

	// ExecuteQueryToRecordsReader returns a reader for the given query to read records 1 by 1 sequentially.
	// The RecordsReader.Next() method returns ErrNoMoreRecords when there are no more records.
	ExecuteQueryToRecordsReader(ctx context.Context, query Query) (RecordsReader, error)

	// ExecuteQueryToRecordsetReader returns a RecordsetReader for the given query, allowing sequential read of records into the provided recordset.
	ExecuteQueryToRecordsetReader(ctx context.Context, query Query, options ...recordset.Option) (RecordsetReader, error)
}

type ROTxWorker = func(ctx context.Context, tx ReadTransaction) error

type RWTxWorker = func(ctx context.Context, tx ReadwriteTransaction) error

type RandomStringOptions interface {
	Prefix() string
	Length() int
}

type ReadSession interface {
	Getter
	MultiGetter
	QueryExecutor
}

type ReadTransaction interface {
	Transaction
	ReadSession
}

type ReadTransactionCoordinator interface {

	// RunReadonlyTransaction starts readonly transaction
	RunReadonlyTransaction(ctx context.Context, f ROTxWorker, options ...TransactionOption) error
}

type Reader interface {
	// Cursor points to a position in the result set. This can be used for pagination.
	Cursor() (string, error)

	// Close closes the reader
	Close() error
}

type ReaderOption = func(ro *ReaderOptions)

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

type ReadwriteSession interface {
	ReadSession
	WriteSession
}

type ReadwriteTransaction interface {

	// ID returns a unique ID of a transaction if it is supported by the underlying DB client
	ID() string

	Transaction
	ReadwriteSession
}

type ReadwriteTransactionCoordinator interface {

	// RunReadwriteTransaction starts read-write transaction
	RunReadwriteTransaction(ctx context.Context, f RWTxWorker, options ...TransactionOption) error
}

type RecordAfterLoadHook interface {
	AfterLoad(ctx context.Context, key *record.Key) (err error)
}

type RecordBeforeSaveHook interface {
	BeforeSave(ctx context.Context, key *record.Key) (err error)
}

type RecordDataHook = func(ctx context.Context, db DB, key *record.Key, data any) (err error)

type RecordDataOption = func(rd *recordData)

type RecordHook = func(ctx context.Context, record record.Record) error

type RecordsReader interface {
	Reader
	// Next returns the next record for a query.
	// If no more records, a nil record and ErrNoMoreRecords are returned.
	Next() (record.Record, error)
}

type RecordsetReader interface {
	Reader
	Recordset() recordset.Recordset
	Next() (row recordset.Row, rs recordset.Recordset, err error)
}

type RecordsetSource interface {
	Name() string
	Alias() string
	// contains filtered or unexported methods
}

type Schema interface {
	DataToKey(incompleteKey *record.Key, data any) (key *record.Key, err error)
	KeyToFields(key *record.Key, data any) (fields []ExtraField, err error)
}

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

type Setter interface {

	// Set stores a single record intoRecord database by key
	Set(ctx context.Context, record record.Record) error
}

type SingleSource interface {
	Where(conditions ...Condition) IQueryBuilder
}

type StructuredQuery interface {
	Query

	// From - defines target table/recordsetSource
	From() FromSource

	// Where defines filter condition
	Where() Condition

	// GroupBy defines expressions to group by
	GroupBy() []Expression

	// Having defines a post-aggregation filter condition
	Having() Condition

	// OrderBy defines expressions to order by
	OrderBy() []OrderExpression

	// Columns specifies columns to return
	Columns() []Column

	// IntoRecord provides a function that creates a record for a new row
	IntoRecord() record.Record // TODO: Should this be moved into Query.GetRecordsReader ?

	// IDKind defines the type of the ID
	IDKind() reflect.Kind // TODO: what about composite keys?

	// StartFrom specifies the startCursor/point to start from
	StartFrom() Cursor
}

type TextQuery interface {
	Query
	Text() string
	Args() []QueryArg
}

type TimeStampAccuracy int

type Transaction interface {
	// Options indicates parameters that were requested at time of transaction creation.
	// The message field is mutable during execution via TransactionOptions.SetMessage();
	// implementations should return options by shared reference so the update is observed.
	Options() TransactionOptions
}

type TransactionCoordinator interface {

	// ReadTransactionCoordinator can start a readonly transaction
	ReadTransactionCoordinator

	// ReadwriteTransactionCoordinator can start a readwrite transaction
	ReadwriteTransactionCoordinator
}

type TransactionOption func(options *txOptions)

type TransactionOptions interface {

	// Message returns an optional human-readable message describing the transaction.
	// Backends may surface it (e.g. dalgo2ingitdb uses it as a git commit message)
	// or include it in logs. It returns an empty string when no message was set.
	Message() string

	// SetMessage sets (replaces) the transaction message. It can be used at
	// transaction start via TxWithMessage, or during transaction execution.
	// It is available on both readonly and read-write transactions.
	SetMessage(message string)

	// IsolationLevel indicates requested isolation level
	IsolationLevel() TxIsolationLevel

	// IsReadonly indicates a readonly transaction
	IsReadonly() bool

	// IsCrossGroup indicates a cross-group transaction. Makes sense for Google App Engine.
	IsCrossGroup() bool

	// Attempts returns number of attempts to execute a transaction. This is used in Google Datastore for example.
	Attempts() int
}

type Transform interface {

	// Name returns Name of a transform
	Name() string

	// Value returns arguments of transform
	Value() any
}

type TxIsolationLevel int

type Updater interface {

	// Update updates a single record in a database by key
	Update(ctx context.Context, key *record.Key, updates []update.Update, preconditions ...Precondition) error

	// UpdateRecord updates a single record in a database.
	// For example, this is useful in case if we want to put the record.Data to memcache.
	// See https://github.com/dal-go/dalgo-memcache-appengine
	// A regular DB adapter should call update(record.Key()) inside this method.
	UpdateRecord(ctx context.Context, record record.Record, updates []update.Update, preconditions ...Precondition) error
}

type ValidatableRecord interface {
	Validate() error
}

type WriteSession interface {
	Setter
	MultiSetter
	Deleter
	MultiDeleter
	Updater
	MultiUpdater
	Inserter
	MultiInserter
}