datastore

type AtomicOp struct {
	// Key addresses the item the operation applies to.
	Key Key
	// Item is what a put writes.
	Item any
	// Updates are the mutations an update applies.
	Updates []Update
	// Options are the preconditions the operation is subject to.
	Options WriteOptions
	// contains filtered or unexported fields
}

type BatchOp struct {
	// Key addresses the item the operation applies to.
	Key Key
	// Item is what a put writes, and is nil for a delete.
	Item any
	// contains filtered or unexported fields
}

type Client interface {
	// Get fills out with the item under the key and returns its revision, for
	// a later write that must require the item has not changed since.
	Get(ctx context.Context, key Key, out any) (Revision, error)
	// Put writes an item, replacing whatever was under the key.
	//
	// [If] makes it conditional, which a handler that read, decided and is
	// writing back needs. Without one, two invocations running at the same time
	// silently lose an update.
	//
	// Returns the item's new revision, so a sequence of writes needs no read
	// between them.
	Put(ctx context.Context, key Key, item any, opts ...WriteOption) (Revision, error)
	// Delete removes an item, and is idempotent. [If] makes it conditional.
	Delete(ctx context.Context, key Key, opts ...WriteOption) error
	// Query fills out with one page of the items under a partition, and
	// returns the cursor to resume from. Use [Items] to read a query to the
	// end.
	Query(ctx context.Context, q Query, out any) (Cursor, error)
	// Scan fills out with one page of the whole store, and returns the cursor
	// to resume from. Use [Scanned] to read a scan to the end.
	//
	// A scan reads every item; a query reads one partition. Reach for this only
	// for genuinely whole-store work, such as an export or a backfill.
	Scan(ctx context.Context, s Scan, out any) (Cursor, error)
	// BatchGet fills out with the items under the keys, in as few requests as
	// the store allows, and returns the keys it could not fetch.
	//
	// Items come back in no particular order, and a key that holds nothing is
	// simply absent rather than an error, so match items to keys by key and
	// never by position.
	BatchGet(ctx context.Context, keys []Key, out any) ([]Key, error)
	// Update mutates parts of an item that already exists, leaving the rest
	// alone, and returns the item's new revision.
	//
	// Built with [Set], [Remove] and [Increment], at most [MaxUpdates] of them.
	// The item has to be there: an update of a key that holds nothing reports
	// [ErrNotFound] rather than creating it. Use [Client.Put] to create.
	//
	// Preconditions apply as they do to a put, so an update can be partial and
	// conditional in the same request.
	Update(ctx context.Context, key Key, updates []Update, opts ...WriteOption) (Revision, error)
	// BatchWrite applies puts and deletes, in as few requests as the store
	// allows, and returns the operations it could not apply.
	//
	// This is not atomic. Some operations may succeed while others fail, on every
	// store, so a caller that needs all or none cannot build it out of this.
	//
	// This only supports Puts and deletes. A batch write does not carry update on the stores this
	// has to work on. To change part of each of many items, call [Client.Update]
	// per item, or [Client.Atomically] where they share a partition and
	// all-or-none is wanted as well.
	//
	// A [BatchOp] carries no preconditions, for the same reason: no store takes
	// one on a batch write.
	BatchWrite(ctx context.Context, ops []BatchOp) ([]BatchOp, error)
	// Atomically applies every operation or none of them.
	//
	// Built with [AtomicPut], [AtomicUpdate] and [AtomicDelete], at most
	// [MaxAtomicOps] of them, each able to carry its own preconditions. A
	// precondition that does not hold refuses the whole write with
	// [ErrConditionFailed] and nothing is applied.
	//
	// Every operation has to address the partition named here, which is a
	// parameter rather than inferred from the operations so that the
	// one-partition rule cannot be broken by accident.
	//
	// There is no reading inside. For read-modify-write, take the revision from
	// an earlier read and pass it as [IfUnchanged] on the operation that needs
	// it.
	//
	// Reports [ErrNotSupported] on a store with no multi-item transactions.
	Atomically(ctx context.Context, partition string, ops []AtomicOp) error
}

type Condition struct {
	// Op is the test. Always set; a zero Condition is refused by the provider
	// rather than quietly matching everything.
	Op Operator
	// Name is the attribute tested, and is empty for [All] and [Any].
	Name string
	// Value is what the attribute is tested against, and is unset for
	// [Exists], [NotExists], [All] and [Any].
	Value any
	// High is the upper bound of [Between], whose lower bound is Value.
	High any
	// Of are the conditions [All] and [Any] combine, and nest as deeply as
	// they are written.
	Of []Condition
}

type Cursor string

type Key struct {
	Partition string
	Sort      string
}

type Operator string

type Query struct {
	// Partition is the value every matching item shares.
	Partition string
	// Sort narrows the query to part of the partition. Nil reads all of it.
	//
	// Built with [SortBetween] and the other Sort functions. This is what the
	// store uses to read less, rather than reading the partition and discarding
	// what does not match, so a partition that grows can still be queried
	// efficiently.
	Sort *SortCondition
	// Filter narrows the page to items matching a condition on their own
	// fields. Nil applies none.
	//
	// Applied by the store after the items are read, so it reduces what crosses
	// the network and not what the query costs. [Query.Sort] is what reduces the
	// cost, so prefer it where the data model allows.
	Filter *Condition
	// Index names a secondary index to query rather than the table itself.
	Index string
	// Project lists the fields to return. Empty returns whole items.
	//
	// The key fields are always returned whether or not they are listed. Like a
	// filter, this reduces what crosses the network rather than what the query
	// costs.
	Project []string
	// Descending reads the partition from the end of the sort order rather than
	// the start, which with a timestamp sort key is how the newest items are
	// read without reading the partition through.
	Descending bool
	// Limit is the most items one page holds. Zero leaves it to the store.
	Limit int
	// Cursor resumes a query where an earlier one stopped. See [Cursor].
	Cursor string
}

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

type RevisionReceiver interface {
	SetRevision(Revision)
}

type Scan struct {
	// Filter drops items that do not match a condition on their own fields.
	// Nil applies none.
	//
	// Applied by the store after the items are read, so every item is still
	// read and paid for. A filter makes a scan easier to receive, but not
	// cheaper to run.
	Filter *Condition
	// Project lists the fields to return. Empty returns whole items. The key
	// fields are always returned whether or not they are listed.
	Project []string
	// Limit is the most items one page holds. Zero leaves it to the store.
	Limit int
	// Cursor resumes a scan where an earlier one stopped. See [Cursor].
	Cursor string
}

type SortCondition struct {
	// Op is the test, and is one of equal, the four comparisons, between and
	// starts-with.
	Op Operator
	// Value is what the sort key is tested against, and the lower bound of
	// [SortBetween].
	Value string
	// High is the upper bound of [SortBetween].
	High string
}

type Update struct {
	Kind UpdateKind
	// Path names the field, with a dot between the segments of a nested one:
	// "status", or "profile.theme".
	//
	// Object fields only. An array element cannot be addressed, since not every
	// store can change one by index. To change an array, read the item and
	// write it back with [IfUnchanged].
	//
	// A field whose own name contains a dot is not addressable either: it
	// cannot be told apart from a path.
	Path string
	// Value is what [Set] writes. Unused by the other two.
	Value any
	// By is what [Increment] adds. Unused by the other two.
	By float64
}

type UpdateKind string

type WriteOption func(*WriteOptions)

type WriteOptions struct {
	// Condition that has to be true of the item already there, or the write is refused.
	Condition *Condition
	// Revision is the revision the item has to still carry, or the write is
	// refused. Nil when the write is not conditional on one.
	Revision *Revision
}