dict

type CommitResult int

type Config struct {
	// Driver names the registered driver to instantiate.
	Driver string `koanf:"driver"`
	// Settings is the driver-specific configuration tree. Keys and
	// types are defined by each driver's documentation.
	Settings map[string]any `koanf:"settings"`
}

type Dict interface {
	// Lookup returns every value bound to key, plus found=true when at
	// least one value exists. The values slice is nil when found=false.
	// Drivers that store at most one value per key return a 1-element
	// slice. Honour ctx for cancellation.
	Lookup(ctx context.Context, set *OpSettings, key string) (values [][]byte, found bool, err error)

	// Iterate returns an Iterator over keys under path. The flags
	// bitmask controls recursion, sorting, value-skipping and exact-key
	// mode. The iterator MUST be Closed even when iteration stops early.
	Iterate(ctx context.Context, set *OpSettings, path string, flags IterFlag) (Iterator, error)

	// Begin opens a new transaction context. Mutations are buffered in
	// the Tx and applied atomically on Commit. Drivers that lack native
	// atomic multi-key writes simulate them via locking or write-ahead.
	Begin(ctx context.Context, set *OpSettings) (Tx, error)

	// ExpireScan asks the driver to drop expired entries. Drivers
	// without TTL support return nil (a no-op). Long-running drivers
	// (SQL) MAY do this in chunks bounded by ctx.
	ExpireScan(ctx context.Context) error

	// Wait blocks until every async operation kicked off by this Dict
	// has finished. Sync drivers (file, memory, fail) return nil
	// immediately. Reserved for the future redis async-pipeline path.
	Wait(ctx context.Context) error

	// Close releases all resources (open files, network connections,
	// background goroutines). Idempotent.
	Close() error

	// Name returns the driver name this Dict was opened with. Useful
	// for diagnostics and logging.
	Name() string
}

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

type InitFunc func(cfg Config) (Dict, error)

type IterFlag uint32

type Iterator interface {
	// Next advances to the next row. Returns false when iteration ends
	// (Err may carry an error in that case) or when ctx was cancelled.
	Next() bool
	// Key returns the current row's key. Valid only after a true Next().
	Key() string
	// Values returns every value for the current key. Single-value
	// drivers return a 1-element slice. Nil when IterNoValue was set.
	Values() [][]byte
	// Err returns the first iteration error, or nil if iteration ended
	// cleanly. Always check after the loop.
	Err() error
	// Close releases resources. Idempotent. Safe to call before Next()
	// returns false (early-exit iteration).
	Close() error
}

type MemoryTx struct {
	Ops []TxOp
}

type OpSettings struct {
	// Username of the operation's owner. Required by drivers that
	// scope keys per-user (e.g. file path "%h/.metadata" relies on it).
	Username string
	// HomeDir of the user, if known. Used for "%h" expansion in the
	// file driver's path; left empty when the caller does not have it.
	HomeDir string
	// ExpireSecs, when non-zero, asks the driver to add a TTL of this
	// many seconds to every key written by the transaction or set call.
	// Drivers without TTL support silently ignore it.
	ExpireSecs uint32
	// NoSlownessWarning suppresses the driver's slow-commit warning log.
	// Set for transactions whose latency does not matter (e.g. best-
	// effort metadata writes).
	NoSlownessWarning bool
	// HideLogValues redacts values from any debug/trace logs the driver
	// might emit. Set when values contain sensitive data.
	HideLogValues bool
}

type Tx interface {
	// Set assigns value to key. Overwrites any prior value.
	// For multi-value drivers (SQL), appends to the value list when
	// the driver-specific "append" flag is enabled; otherwise replaces.
	Set(key string, value []byte) error
	// Unset removes key (and all its values for multi-value drivers).
	// Unsetting a missing key is not an error.
	Unset(key string) error
	// AtomicInc atomically adds delta (positive or negative) to the
	// integer value of key. If key is missing at commit time, Commit
	// returns CommitNotFound. Values are stored as decimal strings.
	AtomicInc(key string, delta int64) error
	// Commit flushes the buffered mutations. Returns CommitOK on
	// success; see CommitResult docs for the other values.
	Commit() (CommitResult, error)
	// Rollback discards every buffered mutation. Idempotent.
	Rollback() error
}

type TxOp struct {
	Kind  TxOpKind
	Key   string
	Value []byte
	Delta int64
}

type TxOpKind int