storage library

Storage engine building blocks.

Layering, from the bottom up:

  • StorageFile — the only file abstraction the log needs.
  • block — packs self-delimiting VXS documents into immutable blocks.
  • wal — framed, checksummed, crash-recoverable append log.
  • memtable — open-addressed in-memory table of key → value reference.
  • arena — append-only chunked document store with stable views.
  • engine — composes WAL, arena and memtable into the write path.

Nothing here imports dart:io; the layers are pure byte codecs plus one minimal async file interface.

Classes

BlockReader
Reads and validates a block of VXS documents.
BlockWriter
Packs VXS documents into self-delimiting blocks.
BloomFilter
Bloom filter used to skip segments that cannot contain a key.
CheckIssue
One finding from CheckReport.
CheckReport
Result of an integrity check.
DocArena
Append-only byte store for encoded documents.
LocalStorageDirectory
Web build placeholder for the local engine's directory.
LocalStorageFile
Web build placeholder for a local file.
MaintenanceScheduler
Runs maintenance work (flush, compaction) outside the write that triggered it.
Manifest
Immutable description of the database contents.
ManifestStore
Stores the manifest in two alternating slots.
MappedFile
A read-only mapping of a whole file.
MemoryStorageDirectory
In-memory directory used by tests and benchmarks.
MemoryStorageFile
In-memory file implementing both the sync and async interfaces.
MemTable
In-memory table of key -> value reference.
MicrotaskMaintenanceScheduler
Defers maintenance to a microtask after the current write returns.
ObjectStore
Minimal object-store contract.
ObjectStoreEngine
Object-store backed engine (S3-style): segments and the manifest are objects, and every write batch appends one small WAL object.
ObjectStoreStats
Request and byte counters for one phase of object-store work.
OpfsObjectStore
Web-only store; the VM build cannot reach this implementation.
SegmentBuilder
Builds an immutable segment: blocks of documents plus a sorted primary index.
SegmentEntryCursor
Forward cursor over a segment's index entries, ascending by key.
SegmentInfo
One immutable segment referenced by a manifest.
SegmentReader
Reads a segment.
SimulatedObjectStore
In-memory object store that counts every request and byte.
StorageEngine
Local storage engine: WAL → memtable → immutable segments.
StorageFile
Minimal file abstraction used by the write-ahead log.
SyncStorageDirectory
Minimal directory abstraction for the local engine.
SyncStorageFile
Synchronous companion used by the local engine core.
Wal
Append-only write-ahead log over a SyncStorageFile.
WalBatch
Encodes and decodes the payload of one WAL frame: a batch of operations.
WalFrame
Encodes and decodes WAL frames.
WalOp
One operation inside a WAL batch.

Enums

CheckSeverity
Severity of one check finding.
Durability
How long a committed write may stay in the OS page cache.
WalOpKind
Operation kinds stored in a WAL batch.

Constants

blockFlagCrc32c → const int
The block carries a CRC-32C trailer.
blockHeaderSize → const int
Header size of a block.
blockMagic → const int
First byte of a block.
blockVersion → const int
Block format version understood by this implementation.
manifestMagic → const int
First byte of a manifest.
manifestVersion → const int
Manifest format version.
segmentFooterMagic → const int
Magic value stored in the segment footer.
segmentFooterSize → const int
Footer size of a segment.
segmentHeaderSize → const int
Header size of a segment.
segmentMagic → const int
First byte of a segment file.
segmentTombstone → const int
docOffset value marking a tombstone entry.
segmentVersion → const int
Segment format version.
walHeaderSize → const int
Size of a WAL frame header: payload length + checksum.

Functions

buildSegmentFromBatch(Uint8List batch, int blockTargetSize) → Uint8List
Builds a segment from a WalBatch payload.
buildSegmentInBackground(Uint8List batch, int blockTargetSize) → Future<Uint8List>
Web fallback: no isolates, so the segment is built inline.

Typedefs

MemRef = ({int chunk, int length, int offset})
Reference to the bytes of one value stored outside the memtable.
SegmentBuildFunction = Future<Uint8List> Function(Uint8List batch, int blockTargetSize)
Builds a segment from a WalBatch payload.

Exceptions / Errors

VelxoClosedException
The engine or database has been closed.
VelxoConflictException
A conflict with the current transaction state (for example nesting).
VelxoConstraintException
A write violated a declared constraint, such as a reference binding.
VelxoCorruptException
On-disk data could not be decoded or failed a checksum.
VelxoException
Base type for every velxodb error.
VelxoIncompatibleException
The database was created by a newer major format and cannot be read.
VelxoLockedException
The database directory is already open by another writer.
VelxoNotFoundException
A requested resource (index, text index, target collection) is missing.
VelxoReadOnlyException
A write was attempted on a read-only database.
VelxoUpgradeRequiredException
The database uses an older major format and needs an explicit upgrade.
VelxoWorkerException
A failure crossing the worker-isolate boundary (transport, or an error the worker could not classify).