DreamDB

JavaScript SDK

Version scope: Python 0.0.12 / JavaScript 0.5.4. Entity keys, progressive geometry, structured ragged/CSR and additional index capabilities are included in these releases. See feature examples and limits for the supported boundaries; older packages may not expose these methods.

@dreamlake/dreamdb is the DreamDB client for Node and the browser. It is not a JavaScript reimplementation of the protocol — it is the same Rust core the CLI and the Python SDK use, compiled to WebAssembly.

That distinction is why the package exists in this shape. A hand-written port has to reproduce BLAKE3, canonical CBOR, spatial-key encoding, bucket headers, and index layout bit for bit, forever. The previous pure-TypeScript SDK did not, and its tests stayed green throughout, because they were its own reader reading its own writer. Bytes written by this package are the bytes the Rust CLI writes.

The four classes

Space

The read side. Open a ref or manifest, query it, read typed arrays and VideoItems, and walk history.

Writer

Append records, commit, snapshot, and tombstone. Node also ingests pre-fragmented CMAF video.

Authoring

Create datasets, add layers, branch, merge, compact. Node only.

Backends

S3Backend for public reads, PresignedBackend for browser writes, or any object with get / put / head.

What it does not do

No index training. dreamdb.ivf-cosine and dreamdb.imi-cosine need training data that does not exist when a dataset is created, so Authoring refuses those algorithms. Create with the default dreamdb.lsh-cosine and attach a trained index as a layer, or build the dataset with the Python SDK or the CLI.

No authoring in the browser. Creating a dataset constructs a SpatialDispatcher, and because that is an enum, one reachable construction makes every index family's build code reachable — IVF, IMI, LSH, Vamana, AdaIVF, and codebook training with them. Measured on the published 0.5.1 tarball: 486 KB gzipped for the browser build against 609 KB with authoring included. The browser build stubs Authoring out; its methods throw with an explanation. Reading, querying, appending, and committing all work there.

Anchors are nanoseconds

Time anchors are u64 nanoseconds, and in JavaScript you pass a bigint:

js
const anchor = BigInt(Date.now()) * 1_000_000n;

A number is accepted only while it stays below Number.MAX_SAFE_INTEGER; above that the SDK throws rather than silently rounding. The retired TypeScript SDK wrote anchors in microseconds specifically to stay inside Number, and every record it produced reads as 1970 in any conformant reader.

Query results come back the other way: queryVector returns anchors as plain numbers, and tracks() returns coverage as bigints.

Where to go next

  • Install — the package, its three entry points, and bundler setup
  • Quickstart — read a dataset, query it, write to it
  • API reference — every export with its real signature
  • Browser usage — the /web entry, rendering stored bytes, and the CORS rules that bite
  • Semantic search — a text query to nearest images