velxodb library

velxodb — an embedded, pure-Dart document database.

The public surface is intentionally small and layered:

  • package:velxodb/velxodb.dart — database, collections, queries.
  • package:velxodb/serde.dart — the zero-copy VXS binary format.
  • package:velxodb/storage.dart — the storage engine building blocks.
  • package:velxodb/testing.dart — conformance kits for custom backends.

Classes

BackupReport
Summary of a backup or restore.
Catalog
Maps collection names to stable numeric prefixes and records indexes.
Collection
A named namespace of documents inside a database.
CollectionCatalog
Everything a Collection needs from the catalog.
CollectionCursor
Streaming, ordered cursor over one collection's key range.
CollectionEntry
One collection registered in the catalog.
DocumentSchema<T>
Maps a model type to a VXS document and declares its fields.
Field
One field of a typed document.
GraphEdge
One stored edge.
GraphStore
Typed, bidirectional edges on top of the key/value engine.
IndexCatalog
Declares which catalog entity owns an index definition.
IndexDefinition
A secondary index on one field of one collection.
MigrationReport
Outcome of one migration run or page.
MigrationStep
Turns one schema version into the next.
NgramTokenizer
Sliding n-gram tokenizer, useful for CJK text without word boundaries.
NodeRef
A node in the graph: a document identified by collection and key.
Predicate
A predicate over a decoded document.
Query
A query: optional predicate, optional key range, and a limit.
QueryPlan
The chosen execution plan.
ReferenceCatalog
Catalog capabilities needed by reference bindings.
ReferenceDefinition
A reference binding: source.fieldId holds the key of a document in targetCollectionId.
ReferenceIssue
One dangling reference found by Collection.validateReferences.
RelationCatalog
Resolves relation names to stable namespace ids.
RelationDefinition
A named relation (edge type) registered in the catalog.
TextIndexDefinition
One full-text index on a collection field.
Tokenizer
Splits text into search terms.
TypedCollection<T>
A collection paired with typed encode/decode functions.
UpgradeJournal
An in-place undo journal for an A-major upgrade.
Velxo
Entry point for opening an embedded database.
VelxoDatabase
An embedded database: one directory, one engine, many collections.
VelxoWebDatabase
Async Web database over OPFS.
VelxoWorker
Web stub: isolates are not available, so the worker facade is unsupported.
WebCollection
Async collection: CRUD, ordered scan, pagination and secondary indexes.
WebGraph
Async typed graph over OPFS.
WebTransaction
Buffered writes over an object store.
WordTokenizer
Unicode word tokenizer: letters and digits, lowercased.
WorkerCheck
Result of VelxoWorker.check.

Enums

EdgeDirection
Direction of an edge relative to a node.
OnDelete
What happens to referring documents when the target is deleted.
ScanStrategy
How a query will be executed.
TextQueryMode
How multiple query terms combine.

Extensions

CollectionMigration on Collection
Version-aware migration on top of a Collection.

Constants

formatFileName → const String
Name of the root format stamp.
formatMagic → const List<int>
Magic bytes of the format stamp.
formatMajor → const int
On-disk format major version.
formatMinor → const int
On-disk format minor version.
formatTempFileName → const String
Temporary file used to replace the stamp atomically.
upgradeJournalFileName → const String
Name of the in-place upgrade undo journal.
velxodbVersion → const String
Semantic version of the package.

Functions

checkFormatCompatibility(SyncStorageDirectory directory, {required bool readOnly}) → void
Enforces the version policy before a database is opened.
copyDatabase(SyncStorageDirectory source, SyncStorageDirectory target) → BackupReport
Copies every database file from source into the empty target.
copyFields(DocView old, DocBuilder out, {Set<int> skip = const <int>{}, int? fromId, int? toId}) → void
Copies fields of old into out, in stored (ascending id) order.
decodeFormatStamp(Uint8List bytes) → ({int major, int minor})
Decodes a format stamp, validating its length, magic and checksum.
encodeFormatStamp() → Uint8List
Encodes the current format stamp as 12 bytes.
readFormatStamp(SyncStorageDirectory directory) → ({int major, int minor})?
Reads the format stamp, or null when the database predates stamping.
writeFormatStamp(SyncStorageDirectory directory) → void
Writes the current format stamp atomically.

Typedefs

ScanEntry = ({Uint8List key, Bytes value})
One key/value pair returned by a scan or a cursor.
ScanPage = ({List<ScanEntry> entries, Uint8List? next})
A page of results plus the key to start after for the next page.
WebEntry = ({Uint8List key, Bytes value})
One document returned by WebCollection.scan and index lookups.
WorkerEntry = ({Uint8List key, Uint8List value})
One key/value pair returned by VelxoWorker.page.
WorkerPage = ({List<WorkerEntry> entries, Uint8List? next})
One page of results plus the key to resume after.

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).