Atomic by default
Every commit uses a temporary file, disk flush, and atomic rename so interrupted writes never leave half a document behind.
draft→temp→flush→rename
Embedded JSON database for Node.js
Your local state,
stored safely.
Atomic writes, deterministic concurrency, schema migrations, backups, and crash recovery—wrapped in a tiny, type-safe API with zero runtime dependencies.
$
npm install @homielab/jsonlet
0runtime dependencies
3durability modes
18+Node.js support
100%typed public API
Designed for failure
Plain JSON.
Plain JSON.
Production-grade safety.
Keep the simplicity of a file without accepting fragile write behavior.
Concurrency you can reason about
Sequential in-process queues and heartbeat-based cross-process locks protect updates from racing each other.
Immutable reads
Deep-frozen cached snapshots make accidental mutations obvious and keep every change inside a transaction.
Recovery built in
Rotating backups, corrupt-file quarantine, stale-lock detection, and automatic recovery cover the ugly edge cases.
Your schema, your validator
Bring Zod or any parser, then evolve data safely through ordered, versioned migrations.
A small, predictable API
Open. Read.
Open. Read.
Update. Close.
Jsonlet stays out of the way. Reads are synchronous, writes are queued, and TypeScript knows the exact shape of your state.
Explore the API →database.ts
import { Jsonlet } from "@homielab/jsonlet";
const db = new Jsonlet("./data/db.json", {
defaults: { counter: 0, users: [] },
});
await db.open();
await db.update((draft) => {
draft.counter += 1;
});
console.log(db.read());
await db.close();
Use the right tool
Built for local state,
Built for local state,
not every workload.
✓ A great fit
- CLI state and caches
- Desktop application settings
- Local automation data
- Low-to-moderate write frequency
× Choose a server database
- Concurrent remote clients
- High-throughput event logging
- Documents larger than 50 MB
- Queries, indexes, or relational joins
Keep JSON simple.
Make persistence safe.
Install Jsonlet and ship local state without the usual file-handling traps.