anystore

type CipherType = btree.CipherType

type Codec = btree.Codec

type Collection interface {
	// Name returns the name of the collection.
	Name() string

	// FindId finds a document by its ID.
	// Returns the document or an error if the document is not found.
	FindId(ctx context.Context, id any) (Doc, error)

	// FindIdWithParser finds a document by its ID. Uses provided anyenc parser.
	// Returns the document or an error if the document is not found.
	FindIdWithParser(ctx context.Context, p *anyenc.Parser, id any) (Doc, error)

	// Find returns a new Query object with given filter
	Find(filter any) Query

	// Insert inserts multiple documents into the collection.
	// Returns an error if the insertion fails.
	Insert(ctx context.Context, docs ...*anyenc.Value) (err error)

	// UpdateOne updates a single document in the collection.
	// Provided document must contain an id field
	// Returns an error if the update fails.
	UpdateOne(ctx context.Context, doc *anyenc.Value) (err error)

	// UpdateId updates a single document in the collection with provided modifier
	// Returns a modify result or error.
	UpdateId(ctx context.Context, id any, mod query.Modifier) (res ModifyResult, err error)

	// UpsertOne inserts a document if it does not exist, or updates it if it does.
	// Returns the ID of the upserted document or an error if the operation fails.
	UpsertOne(ctx context.Context, doc *anyenc.Value) (err error)

	// UpsertId updates a single document or creates new one
	// Returns a modify result or error.
	UpsertId(ctx context.Context, id any, mod query.Modifier) (res ModifyResult, err error)

	// DeleteId deletes a single document by its ID.
	// Returns an error if the deletion fails.
	DeleteId(ctx context.Context, id any) (err error)

	// Count returns the number of documents in the collection.
	// Returns the count of documents or an error if the operation fails.
	Count(ctx context.Context) (count int, err error)

	// CreateIndex creates a new index.
	// Returns an error if index exists or the operation fails.
	CreateIndex(ctx context.Context, info ...IndexInfo) (err error)

	// EnsureIndex ensures an index exists on the specified fields.
	// Returns an error if the operation fails.
	EnsureIndex(ctx context.Context, info ...IndexInfo) (err error)

	// DropIndex drops an index by its name.
	// Returns an error if the operation fails.
	DropIndex(ctx context.Context, indexName string) (err error)

	// GetIndexes returns a list of indexes on the collection.
	GetIndexes() (indexes []Index)

	// Stats returns the storage footprint of the collection: document count,
	// stored and uncompressed sizes, compression ratio and per-index sizes.
	// It scans the whole collection and is intended for diagnostics.
	Stats(ctx context.Context) (CollectionStats, error)

	// Rename renames the collection.
	// Returns an error if the operation fails.
	Rename(ctx context.Context, newName string) (err error)

	// Drop drops the collection.
	// Returns an error if the operation fails.
	Drop(ctx context.Context) (err error)

	// ReadTx starts a new read-only transaction. It's just a proxy to db object.
	// Returns a ReadTx or an error if there is an issue starting the transaction.
	ReadTx(ctx context.Context) (ReadTx, error)

	// WriteTx starts a new read-write transaction. It's just a proxy to db object.
	// Returns a WriteTx or an error if there is an issue starting the transaction.
	WriteTx(ctx context.Context) (WriteTx, error)

	// Close closes the collection.
	// Returns an error if the operation fails.
	Close() error
}

type CollectionOptions struct {
	// Compression overrides the database-wide compression setting for this collection.
	// Zero value inherits the database default.
	Compression Compression
}

type CollectionStats struct {
	// Name is the collection name.
	Name string

	// DocCount is the number of documents in the collection.
	DocCount int

	// StoredDocsBytes is the sum of stored document value bytes. When
	// compression is enabled this counts the compressed form.
	StoredDocsBytes int

	// UncompressedDocsBytes is the sum of document value bytes after
	// decompression. It equals StoredDocsBytes when nothing is compressed.
	UncompressedDocsBytes int

	// CompressionEnabled reports whether compression is active for this
	// collection. Individual documents below anyenc.CompressMinSize are stored
	// uncompressed even when it is enabled.
	CompressionEnabled bool

	// CompressionRatio is UncompressedDocsBytes/StoredDocsBytes. It is 1.0 when
	// nothing is compressed and grows above 1.0 as compression saves space.
	CompressionRatio float64

	// DocsSizeBytes is the physical on-disk size of the collection's document
	// B-tree (page count including overflow pages times the page size).
	DocsSizeBytes int

	// IndexesSizeBytes is the sum of SizeBytes across all indexes.
	IndexesSizeBytes int

	// TotalSizeBytes is DocsSizeBytes plus IndexesSizeBytes.
	TotalSizeBytes int

	// Indexes holds per-index statistics.
	Indexes []IndexStats
}

type Compression int

type Config struct {
	// SyncPoolElementMaxSize defines maximum size of buffer that can be returned to the syncpool
	// default value is 2MiB
	SyncPoolElementMaxSize int

	// CommitSync forces fsync on every WAL commit (like SQLite synchronous=FULL in WAL mode).
	// When false (default), fsync is deferred to checkpoint time, which reduces write latency
	// at the cost of losing the last committed transaction(s) on power loss.
	CommitSync bool

	// DisableAutoCheckpoint disables WAL auto-checkpoint entirely.
	// When true, checkpoint must be triggered manually or via durability auto-flush.
	DisableAutoCheckpoint bool

	// AutoCheckpointAfter overrides the default WAL auto-checkpoint threshold (10000 frames).
	// Only used when DisableAutoCheckpoint is false. 0 means use default.
	AutoCheckpointAfter int

	// CacheSize overrides the default per-DB page cache size (in pages,
	// default 5000). Primarily for tests that need to force pagerStress /
	// cache-spill behavior at low data volumes. Zero means use the default.
	CacheSize int

	// InMemory keeps the entire database in memory with no files on disk.
	// The database does not survive process crashes. When true, InProcess
	// and CommitSync=false are forced on automatically.
	// The path argument to Open is ignored and can be any string (e.g. ":memory:").
	InMemory bool

	// DisableCompression disables S2 compression for document values.
	// By default, objects larger than 256 bytes are compressed with S2.
	DisableCompression bool

	// UseGlobalPageBuffer opts this DB into the global pre-allocated page
	// buffer pool. The pool must be initialized beforehand via InitPageBuffer.
	// When false (default), page buffers use sync.Pool (GC-managed, like
	// SQLite's default malloc mode).
	UseGlobalPageBuffer bool

	// MmapSize enables mmap-backed reads of the database file up to the
	// given byte limit. Zero (default) disables mmap — reads use pread
	// via ReadAt, same behavior as before this feature existed.
	// Matches SQLite's PRAGMA mmap_size. Linux/darwin + amd64/arm64
	// only; no-op on other platforms.
	//
	// SAFETY WARNINGS — read before enabling:
	//
	//   - SIGBUS on unreachable storage: if the DB file becomes
	//     truncated, unlinked, or the storage device is removed while
	//     a mapping is live (USB unplug, iCloud eviction of a
	//     "dataless" file, NFS server timeout, external process
	//     truncate), accessing the mapped bytes generates SIGBUS. Go's
	//     runtime translates SIGBUS to an uncatchable "unexpected
	//     fault address" crash — the whole process dies. The pread
	//     path (MmapSize=0) returns a normal error for all of these
	//     scenarios. Only enable on paths you control: local disk,
	//     stable filesystem, single-device. Do NOT enable for DBs
	//     stored in iCloud Drive, OneDrive, Dropbox, or any network
	//     mount.
	//
	//   - Mobile / iOS: mmap'd bytes count against the per-process
	//     memory limit and can trip iOS's "jetsam" reaper on older
	//     devices. iOS may also silently purge mmap pages under
	//     memory pressure; re-faulting succeeds for local files but
	//     fails (SIGBUS) if the backing file has become unavailable
	//     (permission revocation, iCloud eviction). Recommend leaving
	//     at zero on iOS/iPadOS unless you have a measured need.
	//
	//   - Network filesystems: mmap coherence over NFS/SMB is weaker
	//     than over local disks; concurrent writes from peers may be
	//     invisible to the mapping, and reads may observe torn state.
	//     pread does not have this issue.
	//
	// Recommended when it IS safe: 64-512 MiB on workloads with
	// frequent large-blob or repeat-page reads, on stable local
	// storage, desktop/server deployments.
	MmapSize int64

	// DurabilityConfig provides configuration for crash recovery and idle auto-flush
	Durability DurabilityConfig

	// Encryption, when non-empty, enables page-level AES-256-GCM encryption
	// of the on-disk database file. Zero value means no encryption.
	Encryption EncryptionConfig

	// OnIntegrityError, when non-nil, is invoked from the read path on
	// every per-page integrity failure (XXH3 trailer mismatch in cksum
	// mode, AEAD auth-tag failure in encryption mode). Plain databases
	// never fire it.
	//
	// The callback runs synchronously on the I/O goroutine and must not
	// block. Push to a buffered channel + drain elsewhere if you need
	// retention or cross-thread delivery.
	//
	// Set this at Open time so failures discovered during the first
	// page-1 read (which happens inside Open) are observable. There is
	// no post-Open setter — the codebase favors config-at-Open over
	// runtime mutation.
	OnIntegrityError func(IntegrityError)

	// ContinueOnIntegrityError, when true, lets reads of corrupt pages
	// return their (potentially garbage) bytes instead of erroring with
	// ErrPageIntegrity. The OnIntegrityError callback still fires —
	// only the error-return is suppressed. Mirror of cksumvfs's
	// `PRAGMA checksum_verification = OFF`.
	//
	// Default (false) is the safe choice: corrupt pages cause reads to
	// fail, callers see the error, app halts or recovers. Enable only
	// for forensic dumps where you'd rather read garbage than not be
	// able to read at all.
	//
	// Honored only in checksum mode. AEAD-encrypted databases ignore
	// this flag (disabling AEAD verification would return attacker-
	// controlled plaintext, defeating the cipher).
	ContinueOnIntegrityError bool
}

type DB interface {
	// CreateCollection creates a new collection with the specified name.
	// Returns the created Collection or an error if the collection already exists.
	// Possible errors:
	// - ErrCollectionExists: if the collection already exists.
	CreateCollection(ctx context.Context, collectionName string, opts ...CollectionOptions) (Collection, error)

	// OpenCollection opens an existing collection with the specified name.
	// Returns the opened Collection or an error if the collection does not exist.
	// Possible errors:
	// - ErrCollectionNotFound: if the collection does not exist.
	OpenCollection(ctx context.Context, collectionName string) (Collection, error)

	// Collection is a convenience method to get or create a collection.
	// It first attempts to open the collection, and if it does not exist, it creates the collection.
	// Returns the Collection or an error if there is an issue creating or opening the collection.
	Collection(ctx context.Context, collectionName string, opts ...CollectionOptions) (Collection, error)

	// GetCollectionNames returns a list of all collection names in the database.
	// Returns a slice of collection names or an error if there is an issue retrieving the names.
	GetCollectionNames(ctx context.Context) ([]string, error)

	// Stats returns the statistics of the database.
	// Returns a DBStats struct containing the database statistics or an error if there is an issue retrieving the stats.
	Stats(ctx context.Context) (DBStats, error)

	// QuickCheck performs a quick integrity check. If result not ok returns error.
	QuickCheck(ctx context.Context) (err error)

	// IntegrityCheck runs the full structural btree integrity check:
	// reachable-page coverage, orphan detection, freelist consistency,
	// overflow-chain validation, key ordering, and master-page consistency.
	// Returns nil if the database is structurally consistent, or an error
	// aggregating up to 100 issues found. More expensive than QuickCheck —
	// intended for stress tests and offline diagnostics, not normal opens.
	IntegrityCheck(ctx context.Context) (err error)

	// Flush perform checkpoint on the btree database
	// When waitIdleDuration > 0, wait for waitIdleTime since the last write tx got released
	Flush(ctx context.Context, waitIdleDuration time.Duration, mode FlushMode) error

	// Backup creates a backup of the database at the specified file path.
	// Returns an error if the operation fails.
	Backup(ctx context.Context, path string) (err error)

	// ReadTx starts a new read-only transaction.
	// Returns a ReadTx or an error if there is an issue starting the transaction.
	ReadTx(ctx context.Context) (ReadTx, error)

	// WriteTx starts a new read-write transaction.
	// Returns a WriteTx or an error if there is an issue starting the transaction.
	WriteTx(ctx context.Context) (WriteTx, error)

	// Close closes the database connection.
	// Returns an error if there is an issue closing the connection.
	Close() error

	// IntegrityMode reports the page-level integrity mode of this database
	// (none / checksum / AEAD).
	IntegrityMode() IntegrityMode

	// VerifyIntegrity walks every page and verifies its per-page integrity
	// tag (XXH3-128 trailer for cksum mode, AEAD auth tag for encrypted mode).
	// Plain DBs return IntegrityNone with zero pages scanned. Mismatches are
	// returned in IntegrityReport.Errors; the function only errors on I/O or
	// context cancellation. See IntegrityConfig.
	VerifyIntegrity(ctx context.Context) (IntegrityReport, error)
}

type DBStats struct {
	// CollectionsCount is the total number of collections in the database.
	CollectionsCount int

	// IndexesCount is the total number of indexes across all collections in the database.
	IndexesCount int

	// TotalSizeBytes is the total size of the database in bytes.
	TotalSizeBytes int

	// DataSizeBytes is the total size of the data stored in the database in bytes, excluding free space.
	DataSizeBytes int

	DirtyOnOpen             bool          // indicates we have sentinel file on open
	DirtyQuickCheckDuration time.Duration // time spent in quickcheck if dirty
}

type Doc interface {
	// Value returns the document as a *anyenc.Value.
	// Important: When used in an iterator, the returned value is valid only until the next call to Next.
	Value() *anyenc.Value
}

type DurabilityConfig struct {
	// Enable auto-flush according to IdleAfter and FlushMode
	AutoFlush bool

	// IdleAfter is the duration to wait after the last write before performing autoflush
	// Default: 20s
	IdleAfter time.Duration

	// FlushMode specifies how to autoflush data during idle periods
	// Default: FlushModeCheckpointPassive
	FlushMode FlushMode

	// Sentinel enables the sentinel file (.lock) that tracks database dirty state
	// When true (default is false), the sentinel file is used to detect unclean shutdowns and perform QuickCheck on open
	Sentinel bool
}

type EncryptionConfig struct {
	// Passphrase is the user-supplied secret. Nil = no encryption.
	Passphrase []byte

	// KDFIterations overrides the PBKDF2 cost. Zero means 256,000 (the
	// SQLCipher v4 default). Ignored when Passphrase is exactly 32 bytes
	// (raw-key path). Use lower values only in tests.
	KDFIterations int

	// CipherType selects the built-in AEAD when Passphrase is set.
	// Zero value (CipherAES256GCM) is the default.
	CipherType CipherType

	// Codec, when non-nil, bypasses Passphrase / KDFIterations / CipherType
	// and is used verbatim. Use this for HSM-backed or other externally-
	// keyed codecs.
	Codec Codec
}

type Explain struct {
	Sql string

	// Rich explain output: multi-line plan with cost breakdown and candidates
	Plan string

	Indexes []IndexExplain
}

type File = btree.File

type FlushMode string

type Index interface {
	// Info returns the IndexInfo for this index.
	Info() IndexInfo

	// Len returns the length of the index.
	Len(ctx context.Context) (int, error)
}

type IndexExplain struct {
	Name string
	Cost float64 // CBO computed cost
	Used bool
}

type IndexHint struct {
	IndexName string
	Boost     int
}

type IndexInfo struct {
	// Name is the name of the index. If empty, it will be generated
	// based on the fields (e.g., "name,-createdDate").
	Name string `json:"name"`

	// Fields are the fields included in the index. Each field can specify
	// ascending (e.g., "name") or descending (e.g., "-createdDate") order.
	Fields []string `json:"fields"`

	// Unique indicates whether the index enforces a unique constraint.
	Unique bool `json:"unique"`

	// Sparse indicates whether the index is sparse, indexing only documents
	// with the specified fields.
	Sparse bool `json:"sparse"`
}

type IndexSketchInfo struct {
	Size     int      // bucket count; normally qplanner.DefaultSketchSize
	DocCount uint64   // total documents tracked by this index
	Buckets  []uint64 // per-bucket frequency counts, len == Size
}

type IndexSketchInspector interface {
	InspectIndexSketch(ctx context.Context, collName, indexName string) (IndexSketchInfo, error)
}

type IndexStats struct {
	// Name is the index name.
	Name string

	// Fields are the indexed fields, with leading '-' marking descending order.
	Fields []string

	// Unique reports whether the index enforces a unique constraint.
	Unique bool

	// Sparse reports whether the index skips documents missing the fields.
	Sparse bool

	// EntryCount is the number of entries (key/value pairs) in the index B-tree.
	EntryCount int

	// PayloadBytes is the sum of key+value byte lengths across all entries.
	PayloadBytes int

	// SizeBytes is the physical on-disk size of the index B-tree, computed as
	// its page count (including overflow pages) times the database page size.
	SizeBytes int

	// SketchDocCount is the document count tracked by the index sketch.
	SketchDocCount uint64

	// SketchSize is the number of buckets in the index sketch.
	SketchSize int

	// SketchDistribution summarizes the sketch's bucket frequency distribution.
	SketchDistribution qplanner.SketchDistribution
}

type IntegrityError struct {
	PageNo uint32
	Kind   IntegrityErrorKind
	Inner  error
}

type IntegrityErrorKind int

type IntegrityMode int

type IntegrityReport struct {
	Mode   IntegrityMode
	Pages  int
	Errors []IntegrityError
}

type Iterator interface {
	// Next advances the iterator to the next document.
	Next() bool

	// Doc returns the current document.
	Doc() (Doc, error)

	// Err returns any error encountered during the lifetime of the iterator.
	Err() error

	// Close closes the iterator and releases any associated resources.
	Close() error
}

type ModifyResult struct {
	// Matched is the number of documents matched by the query.
	Matched int

	// Modified is the number of documents that were actually modified.
	Modified int
}

type PipelinePerfCounters struct {
	Planner qplanner.PerfCounters

	DocCalls           uint64
	DocParsedHits      uint64
	DocFallbacks       uint64
	DocFallbackSeekNs  uint64
	DocFallbackParseNs uint64
}

type Query interface {

	// Limit sets the maximum number of documents to return.
	Limit(limit uint) Query

	// Offset sets the number of documents to skip before starting to return results.
	Offset(offset uint) Query

	// Sort sets the sort order for the query results.
	Sort(sort ...any) Query

	// IndexHint adds or removes boost for some indexes
	IndexHint(hints ...IndexHint) Query

	// Iter executes the query and returns an Iterator for the results.
	Iter(ctx context.Context) (Iterator, error)

	// Count returns the number of documents matching the query.
	Count(ctx context.Context) (count int, err error)

	// Update modifies documents matching the query.
	Update(ctx context.Context, modifier any) (res ModifyResult, err error)

	// Delete removes documents matching the query.
	Delete(ctx context.Context) (res ModifyResult, err error)

	// Explain provides the query execution plan.
	Explain(ctx context.Context) (explain Explain, err error)
}

type ReadTx interface {
	// Context returns the context associated with the transaction.
	Context() context.Context

	// Commit commits the transaction.
	// Returns an error if the commit fails.
	Commit() error

	// Done returns true if the transaction is completed (committed or rolled back).
	Done() bool
	// contains filtered or unexported methods
}

type VFS = btree.VFS

type WriteTx interface {
	// ReadTx is embedded to provide read-only transaction methods.
	ReadTx
	// Rollback rolls back the transaction.
	// Returns an error if the rollback fails.
	Rollback() error

	// SetModified marks the transaction as having made modifications
	// used internally for sentinel mechanism
	SetModified()
}