defuss-dbsonl runs on Node.js, Bun and in dedicated browser workers. Batches and transactions publish all of their changes or none, snapshots keep reading the state they opened on, and several processes or workers can share one database.
DSON is typed JSON that keeps Map and SetDate and RegExpbiginttyped arraysundefined and NaNcyclic references
The demos run the packaged library in your tab. Three use memory storage; one keeps a counter in your browser's origin private file system (OPFS).
import { openDbsonl } from 'defuss-dbsonl';import { createFileBackend } from 'defuss-dbsonl/server';const db = await openDbsonl<number>( await createFileBackend('./data'), 'accounts', { create: true });const before = await db.beginRead();await db.transaction(async tx => { const alice = (await tx.get('alice')).value!; const bob = (await tx.get('bob')).value!; tx.put('alice', alice - 20); tx.put('bob', bob + 20); // both or neither});await before.get('alice'); // still the old balanceawait before.close();before keeps its root while the transaction commits.Values are stored as DSON, typed JSON from defuss-dson: Map, Set, Date, RegExp, bigint, typed arrays, undefined, NaN and cyclic references come back as they went in. JSON turns a Map into {} and a date into a string, and throws on a bigint.
A snapshot pins one immutable root of the tree. Commits keep publishing while it reads, and it sees none of them until you open a new one.
A batch or a transaction becomes visible as one revision. A transaction fails with CONFLICT when any other commit published after its snapshot, which rules out write skew.
A log-based store replays its log on open, so startup slows as data grows. defuss-dbsonl reads a small header that points at the current tree, not the stored data; the benchmark reopened a database in 0.52 ms on Node.js. Memory is capped by the page cache budget, not by the number of keys.
Servers coordinate through kernel file locks, browser workers through Web Locks. A process that dies releases its locks, and no lock expires on a timer, so a paused writer never loses ownership.
Every frame carries a CRC32C checksum, and verify() walks every reachable value and index page. Nothing repairs data by guessing, because a guessed repair can turn damage into silent data loss.
defuss-dbsonl is designed as the backing store and API of defuss-dataview. It turns the byte I/O of defuss-storage into a transactional key-value store and encodes every value with defuss-dson.
Each card runs defuss-dbsonl in this tab, built from the same package entries you install. The demos send no network requests.
Isolation without read locks
The left side reads the latest commit. The right side reads a snapshot, opened when the page loaded or when you last opened a new one. Each transfer is a transaction that moves 20 from alice to bob in one commit.
Optimistic concurrency, no silent retry
Transaction A reads visits and waits. Writer B commits in between. When A publishes, its snapshot is stale, so it fails with CONFLICT. The library does not retry, because a retry would run your callback and its side effects again.
0visits
DSON instead of JSON
The button stores one object with a date, bytes, a bigint, an undefined property and a reference to itself, then reads it back and checks each field.
| Field | Read back | Result |
|---|---|---|
| Not stored yet. | ||
OPFS in a dedicated worker
This counter lives in a database in your browser's origin private file system. Reload the page and it keeps its value. Open the page in a second tab: both tabs' workers write the same database, and Web Locks order their commits.
0revision 0
Starting the worker.
Fanout 32. A commit rewrites the path from leaf to root and never changes a written page.
Every revision is a root. A snapshot pins one and reads it while new roots are published.
Two checksummed 4 KiB slots name the current root. Writers alternate between them; the newest valid slot wins.
Values and index pages are DSON frames with a length, a header CRC32C and a payload CRC32C.
Decoded index pages stay in an LRU cache limited by bytes and page count. Values are always read fresh.
Commit lock, then generation pin, then I/O lock. Kernel locks on servers, Web Locks in browsers, no timeouts.
A commit writes next to the old data, never over it, and switches with one small write at the end.
Each card names the design in use, the obvious alternative, why the alternative lost and what the choice costs.
Persistent B+tree with fanout 32 and a bounded page cache
Instead of an in-memory key map rebuilt from a log
Immutable roots, pinned per snapshot
Instead of read locks that block commits
Two checksummed head slots, written alternately
Instead of writing a new file, then renaming it
OS whole-file locks or Web Locks, held per commit
Instead of one process that owns the database
One revision check for the whole database
Instead of per-key conflict detection
Explicit compact() and collect()
Instead of in-place updates or a background vacuum
Kernel locks, released when a process dies
Instead of lock files that expire after a timeout
defuss-dbsonl 0.4.0 with native asynchronous I/O on an Apple M5 Max under macOS, Node.js 24.22.1 and Bun 1.4.3. Each figure is the median of three runs; every run takes the median of seven rounds over 1000 records after two warmups and checks every returned value.
get(), head checked on every call
get() on an open snapshot
per row, in key order
1000 writes in one flushed commit
1000 live records copied
indexed open of an existing database
| Runtime | Storage | Point read | Snapshot read | Scan | Batch | Compaction | Reopen |
|---|---|---|---|---|---|---|---|
| Node.js | native async | 31.14 | 12.98 | 5.55 | 18.68 | 24.65 | 0.52 |
| Node.js | native sync | 13.85 | 5.17 | 3.76 | 17.60 | 23.00 | 0.42 |
| Node.js | memory | 11.21 | 4.81 | 4.34 | 9.18 | 10.98 | 0.03 |
| Bun | native async | 41.10 | 17.35 | 9.37 | 12.84 | 19.37 | 0.31 |
| Bun | native sync | 28.45 | 8.24 | 6.86 | 12.54 | 16.81 | 0.32 |
| Bun | memory | 23.50 | 7.56 | 6.76 | 10.03 | 13.26 | 0.03 |
Synchronous I/O is opt-in and blocks its thread, including during flushes; use it in a worker or CLI. Batch, compaction and reopen are per workload, not per operation.
Three runs with a warm file cache on a busy machine (load average 4.6 to 8.3). They do not measure cold-disk latency or power-loss behavior. Raw samples are in validation/bench-macos-arm64.json, and make bench repeats the run on your machine.
The tests run against real memory and native storage, real kernel locks and real browser workers, with no mocks: the defects that matter here, such as partial reads, torn slots and lock lifetimes, live inside the subsystems a mock would replace.
Every tree result is compared with an independent Map, alongside atomic batches, snapshots, conflicts, phantoms and quota failures.
mvcc.test.tsTorn head slots, truncated and damaged data, publication boundaries and an interrupted create, written as real byte images.
v2-recovery.test.tsIndependent native backends contend for real OS locks and hit real permission failures.
native-v2.test.tsDescriptor limits, stale roots after another client compacts, partial reads and writes, large binary values.
native-performance.test.tsShared pins, try-locks, cancelled waits and pinned generations through the browser backend.
web-locks.test.tsNode.js, Bun, ESM, CommonJS and types from the tarball; v0.2.0 and current writers killed mid-batch; Chromium workers; every demo on this page.
make e2eA batch or transaction becomes visible at once, as one revision, or not at all.
A transaction commits only if no other commit published after its snapshot; otherwise it fails with CONFLICT instead of running your callback again.
A snapshot reads the same root until you close it, while writers keep committing.
Values and index pages reach the device before a head slot points at them. On servers, directory metadata is synced too.
Two checksummed slots survive an interrupted write of either one. A writer reuses the unpublished tail of a failed commit.
Corrupt published data fails its checksum or verify(); nothing is repaired by guessing.
Kernel locks and Web Locks are released when their process or worker ends, never by a clock.
The platforms these guarantees were tested on, and the ones they were not, are listed in the README.
The package needs Node.js 20.19 or newer, Bun, or a dedicated worker in a browser with OPFS and Web Locks.
bun add defuss-dbsonl
The /server entry adds kernel file locks and directory sync. Every process that opens the same directory joins the same lock protocol.
import { openDbsonl } from 'defuss-dbsonl';import { createFileBackend } from 'defuss-dbsonl/server';const db = await openDbsonl(await createFileBackend('./data'), 'orders', { create: true });await db.batch([ { operation: 'put', key: 'order:1', value: { placed: new Date(), total: 4200n } }, { operation: 'delete', key: 'cart:1' },]);await db.close();OPFS grants synchronous access handles only to dedicated workers, so the database runs in one. Every worker that reaches the same files must use the same namespace, because the namespace names their shared Web Locks.
import { createOPFSStorage } from 'defuss-storage/opfs';import { createBrowserBackend } from 'defuss-dbsonl/browser';import { openDbsonl } from 'defuss-dbsonl';const storage = await createOPFSStorage({ name: 'my-app' });const backend = createBrowserBackend(storage, 'my-app', navigator.locks);const db = await openDbsonl(backend, 'documents', { create: true });await db.put('hello', { bytes: new Uint8Array([42]), time: new Date() });Memory storage needs no platform entry. Clients coordinate only when they share the same backend object, which suits tests and short-lived caches.
import { createMemoryBackend, openDbsonl } from 'defuss-dbsonl';const db = await openDbsonl(createMemoryBackend(), 'example', { create: true });const snapshot = await db.beginRead();for await (const row of snapshot.scan({ gte: 'a', lt: 'n' })) console.log(row.key);await snapshot.close();ARCH.md documents the lock order, the crash cases and reclamation. The test suite runs them against real files, kernel locks, killed processes and browser workers.
MIT license.