docstore

type Announcer interface {
	// OnWrite registers fn to be told the key of every document Put, Insert,
	// Replace, Update or Restore stored, and returns the function that removes
	// the registration. A nil fn registers nothing. A panic in fn reaches the
	// writer after its write stood.
	OnWrite(fn func(key string)) (remove func())
	// OnDelete registers fn to be told the key of every document Delete or
	// Trash removed, on the same terms as OnWrite.
	OnDelete(fn func(key string)) (remove func())
}

type Collection[T any] interface {
	Announcer
	// Get returns the document stored under key, or DOCUMENT_NOT_FOUND.
	Get(key string) (T, error)
	// List returns every document, in key order.
	List() ([]T, error)
	// Filter returns the documents keep accepts, in key order. It decodes
	// every document; an index is the way not to.
	Filter(keep func(T) bool) ([]T, error)
	// Entries returns up to limit stored documents as JSON, in key order —
	// every one when limit is not positive — each a copy the caller owns.
	Entries(limit int) ([]EntryValue, error)
	// Lookup returns the document holding key in the unique index named
	// index: DOCUMENT_NOT_FOUND when none does, INDEX_UNKNOWN for an index the
	// store never declared, INDEX_NOT_UNIQUE for one that may file several.
	Lookup(index, key string) (T, error)
	// Find returns the documents filed under key in the index named index, in
	// store-key order. It reads any index, unique or not, and no document is
	// an empty slice, not an error.
	Find(index, key string) ([]T, error)
	// Put stores v under its key, creating it or replacing whatever was there.
	Put(v T) error
	// Insert stores v, which must be new: DOCUMENT_EXISTS when its key is
	// taken.
	Insert(v T) error
	// Replace stores v over the document already under its key:
	// DOCUMENT_NOT_FOUND when there is none, so a document deleted meanwhile
	// is never brought back.
	Replace(v T) error
	// Update applies fn to a copy of the document stored under key and stores
	// the result, atomically with respect to every other write, and returns
	// it. An error from fn is returned as it is and changes nothing, and so
	// does a result whose key is not key (DOCUMENT_KEY_CHANGED). fn may read
	// the store and must not write to it.
	Update(key string, fn func(*T) error) (T, error)
	// Delete removes the document stored under key, or returns
	// DOCUMENT_NOT_FOUND. Its versions go with it.
	Delete(key string) error
}

type CollectionContext[T any] interface {
	Announcer
	// Get is Collection.Get under ctx.
	Get(ctx context.Context, key string) (T, error)
	// List is Collection.List under ctx.
	List(ctx context.Context) ([]T, error)
	// Filter is Collection.Filter under ctx.
	Filter(ctx context.Context, keep func(T) bool) ([]T, error)
	// Entries is Collection.Entries under ctx.
	Entries(ctx context.Context, limit int) ([]EntryValue, error)
	// Lookup is Collection.Lookup under ctx.
	Lookup(ctx context.Context, index, key string) (T, error)
	// Find is Collection.Find under ctx.
	Find(ctx context.Context, index, key string) ([]T, error)
	// Put is Collection.Put under ctx.
	Put(ctx context.Context, v T) error
	// Insert is Collection.Insert under ctx.
	Insert(ctx context.Context, v T) error
	// Replace is Collection.Replace under ctx.
	Replace(ctx context.Context, v T) error
	// Update is Collection.Update under ctx: fn runs inside the write's
	// transaction, and must not write the document it updates.
	Update(ctx context.Context, key string, fn func(*T) error) (T, error)
	// Delete is Collection.Delete under ctx.
	Delete(ctx context.Context, key string) error
}

type EntryValue struct {
	// Key is the document's key.
	Key string
	// JSON is the document, a copy the caller owns.
	JSON json.RawMessage
}

type IndexSpec[T any] struct {
	// Keys returns a document's keys in the index. Empty keys are not
	// indexed, and a key listed twice is filed once.
	Keys func(T) []string
	// Name reads the index in Lookup and Find, and names it in a refusal.
	Name string
	// Unique refuses a write that would file two documents under one key.
	Unique bool
}

type KeyLister interface {
	// Keys yields the key of every document the store holds that sorts after
	// after — every key when after is empty — in key order, byte order as Go
	// compares strings, and no document. Stopping early is allowed, and
	// after is where a later call resumes. A failure is yielded once, with
	// an empty key, and ends the listing; a closed store yields
	// STORE_CLOSED.
	Keys(after string) iter.Seq2[string, error]
}

type KeyListerContext interface {
	// Keys is KeyLister.Keys under ctx: each step that reads runs on the
	// transaction ctx carries for the store's database, and on the pool
	// otherwise.
	Keys(ctx context.Context, after string) iter.Seq2[string, error]
}

type StampValue struct {
	// Meta is kept with the version the write makes — who made it, which
	// command — and read back with it. The store copies it and never reads
	// it.
	Meta map[string]string
	// InPlace makes the write change the document without making a version:
	// the current version keeps its number, its instant and its Meta, and
	// holds the new document. A framework stamps so a workflow's transition,
	// which its journal already records. A creation is version 1 all the
	// same.
	InPlace bool
}

type TombstoneValue struct {
	// Key is the trashed document's key.
	Key string
	// At is when the document was trashed, in UTC, read from the store's
	// clock and kept to the nanosecond, as a version's instant is.
	At time.Time
}

type Trashable interface {
	// Trash moves the document stored under key to the trash: it is gone from
	// every read and its index keys are freed, while its versions are kept
	// and the trash records the instant. It calls OnDelete.
	// DOCUMENT_NOT_FOUND when no document is stored under key.
	Trash(key string) error
	// Restore brings the document trashed under key back, exactly as it was
	// — the same JSON, the same current version — and files it again. It
	// calls OnWrite. DOCUMENT_NOT_TRASHED when no document is trashed under
	// key, UNIQUE_KEY_TAKEN when another document took one of its unique
	// keys meanwhile, which then stays in the trash.
	Restore(key string) error
	// Purge empties the trash of the document trashed under key: the
	// trashed document and every version it kept go, and a document written
	// later under the key starts again at version 1. It calls no hook — the
	// document already left every read — and asks no hold, as Delete does
	// not. DOCUMENT_NOT_TRASHED when no document is trashed under key.
	Purge(key string) error
	// Tombstones returns every document in the trash, in key order: its key
	// and when it was trashed, for a caller that empties the trash after a
	// while.
	Tombstones() ([]TombstoneValue, error)
}

type TrashableContext interface {
	// Trash is Trashable.Trash under ctx.
	Trash(ctx context.Context, key string) error
	// Restore is Trashable.Restore under ctx.
	Restore(ctx context.Context, key string) error
	// Purge is Trashable.Purge under ctx.
	Purge(ctx context.Context, key string) error
	// Tombstones is Trashable.Tombstones under ctx.
	Tombstones(ctx context.Context) ([]TombstoneValue, error)
}

type VersionValue struct {
	// At is when the write that made the version ran, in UTC, read from the
	// store's clock and kept to the nanosecond — by the file engine for the
	// years 0 to 9999, which RFC 3339 writes, and by the SQL engine for any
	// instant. It is zero for the first version of a document the store held
	// before it kept versions: when that one was written is not known.
	At time.Time
	// Meta is what the write's caller said about it — who made it, which
	// command — as its [StampValue] gave it; nil when it said nothing. The
	// store keeps it and never reads it.
	Meta map[string]string
	// JSON is the document as the version holds it, compact, a copy the
	// caller owns. The newest version's is the document itself.
	JSON json.RawMessage
	// Number counts a document's versions from 1. No number is given twice
	// while the document exists or is in the trash, pruning included; a
	// document deleted, or purged from the trash, and written again is a new
	// document, and starts again at 1.
	Number uint64
}

type VersionWeigher interface {
	// VersionWeight reports what the store keeps beyond its documents: how
	// many former versions, how many documents in the trash, and the bytes
	// of the JSON they hold. A closed store answers STORE_CLOSED.
	VersionWeight() (VersionWeightValue, error)
}

type VersionWeigherContext interface {
	// VersionWeight is VersionWeigher.VersionWeight under ctx, read in one
	// statement on the transaction ctx carries for the store's database, and
	// on the pool otherwise.
	VersionWeight(ctx context.Context) (VersionWeightValue, error)
}

type VersionWeightValue struct {
	// Former is how many former versions the store keeps, every document's
	// — a trashed one's included.
	Former int
	// Trashed is how many documents are in the trash ([Trashable]).
	Trashed int
	// Bytes is what the former versions and the trashed documents weigh:
	// the length of the JSON each holds, compact, as both engines keep it.
	// The instants and the metadata they carry are not counted.
	Bytes int64
}

type VersionWriter interface {
	// PutDocument writes the document key with versions, newest first as
	// [Versioned].Versions returns them: the current version — the document
	// itself — then the former ones, each kept as given, its number, its
	// instant (zero for a version 1 made before its store kept versions),
	// its metadata and its JSON, compacted and HTML-escaped as json.Marshal
	// writes a document. With trashedAt zero the document is stored and
	// filed in every index, and OnWrite is told; with trashedAt set, the
	// document is put in the trash at that instant, filed nowhere, and no
	// hook is told. Read back, Versions and Tombstones answer what was
	// given.
	//
	// Nothing may be under key: a document, a trashed one, or versions —
	// DOCUMENT_EXISTS otherwise. VERSIONS_INVALID, its "problem" field
	// naming which, refuses no version, a number 0, numbers that do not
	// strictly decrease, an unknown instant on a version other than 1, a
	// version that is not JSON, and a current document whose own key is not
	// key; DOCUMENT_UNDECODABLE one the store's type does not decode, and
	// UNIQUE_KEY_TAKEN a stored document whose unique key another holds. It
	// asks Held nothing and prunes nothing: the versions are written as
	// given, and the next write prunes as every write does. A refusal
	// writes nothing.
	PutDocument(key string, versions []VersionValue, trashedAt time.Time) error
}

type VersionWriterContext interface {
	// PutDocument is VersionWriter.PutDocument under ctx, in one transaction
	// — a savepoint of the one ctx carries for the store's database — so the
	// document, its index rows and its versions exist if and only if that
	// transaction commits; OnWrite is told once it has.
	PutDocument(ctx context.Context, key string, versions []VersionValue, trashedAt time.Time) error
}

type Versioned[T any] interface {
	// PutStamped is Put, with what the write says about the version it makes.
	PutStamped(v T, stamp StampValue) error
	// InsertStamped is Insert, with what the write says about the version it
	// makes: version 1, whatever stamp.InPlace says — or, under the key of a
	// document in the trash, a write over that document.
	InsertStamped(v T, stamp StampValue) error
	// ReplaceStamped is Replace, with what the write says about the version it
	// makes.
	ReplaceStamped(v T, stamp StampValue) error
	// UpdateStamped is Update, with what the write says about the version it
	// makes.
	UpdateStamped(key string, stamp StampValue, fn func(*T) error) (T, error)
	// Versions returns the versions kept of the document stored under key,
	// newest first: the current one — the document as it is now — then the
	// former ones. A document in the trash answers the versions it kept, the
	// trashed document first. DOCUMENT_NOT_FOUND when no document is stored
	// or trashed under key.
	Versions(key string) ([]VersionValue, error)
	// Version returns the version numbered number of the document stored
	// under key: VERSION_NOT_FOUND when the document keeps none of that
	// number — never made, or pruned.
	Version(key string, number uint64) (VersionValue, error)
	// RewriteVersions rewrites the former versions of the document stored
	// under key in one durable write: fn receives copies of them, newest
	// first, and returns those to keep, in the same order. It may drop a
	// version and change what one holds and what its writer said, and nothing
	// else — VERSIONS_REWRITE_REFUSED otherwise. An error from fn is returned
	// as it is and changes nothing. It calls no hook: the document did not
	// change.
	RewriteVersions(key string, fn func(former []VersionValue) ([]VersionValue, error)) error
}

type VersionedContext[T any] interface {
	// PutStamped is Versioned.PutStamped under ctx.
	PutStamped(ctx context.Context, v T, stamp StampValue) error
	// InsertStamped is Versioned.InsertStamped under ctx.
	InsertStamped(ctx context.Context, v T, stamp StampValue) error
	// ReplaceStamped is Versioned.ReplaceStamped under ctx.
	ReplaceStamped(ctx context.Context, v T, stamp StampValue) error
	// UpdateStamped is Versioned.UpdateStamped under ctx.
	UpdateStamped(ctx context.Context, key string, stamp StampValue, fn func(*T) error) (T, error)
	// Versions is Versioned.Versions under ctx.
	Versions(ctx context.Context, key string) ([]VersionValue, error)
	// Version is Versioned.Version under ctx.
	Version(ctx context.Context, key string, number uint64) (VersionValue, error)
	// RewriteVersions is Versioned.RewriteVersions under ctx.
	RewriteVersions(ctx context.Context, key string, fn func(former []VersionValue) ([]VersionValue, error)) error
}