json-portable-db

High-performance file-backed JSON database with memory-first reads and atomic writes.

Stores all data as a single JSON file on disk. All reads are served from an in-memory Map (O(1) by id); writes are debounced and persisted atomically via tmp + rename.

Motivation

Why choose this?

In modern development, we often fall into the "Infrastructure Botnet" trap: small applications that require a complex network of external services (DBaaS, cloud clusters, managed providers) just to function. This introduces unnecessary network latency, hidden costs, and fragility.

• O(1) Reads: Serving data from an in-memory Map provides effectively zero latency (~0ms), outperforming any networked database.
• Zero Infra: No servers, no configurations, no ports. Your database is a single, human-readable JSON file.
• Total Portability: Perfect for local tools, CLIs, and apps where simplicity and speed are priority.

Install

npm install json-portable-db

Quick start

import { JsonPortableDB } from "json-portable-db";

type Repo = { id: number; name: string; status: string };

const db = new JsonPortableDB({ path: "./data/db.json", backup: true });
await db.connect();

const repos = db.collection<Repo>("repos");

repos.insert({ id: 1, name: "my-repo", status: "pending" });

await repos.upsert(1, { status: "completed" });

const repo = repos.get(1);         // O(1) by id
const found = repos.findOne(1);    // same, via overload
const byName = repos.findOne(r => r.name === "my-repo"); // O(n) scan

await db.flush();       // force immediate write
await db.disconnect();  // flushes pending changes before closing

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | path | string | — | Path to the JSON file (created if missing). | | backup | boolean | false | Keep up to 5 rotating backups (*.bak.1 … *.bak.5). | | debounceMs | number | 200 | Debounce interval for deferred writes (ms). |

API

JsonPortableDB

new JsonPortableDB(options: JsonPortableDBOptions)

Extends EventEmitter. Emits:

• "saved" — { path: string } after each successful persist.
• "error" — on I/O or serialization failures.

| Method | Description | |--------|-------------| | connect() | Loads the file (or starts empty). Must be called before collection(). | | collection<T>(name) | Returns a typed Collection<T>. Requires connect() first. | | flush() | Forces an immediate write if there are pending changes. | | disconnect() | Cancels the pending debounce and flushes before marking as disconnected. |

Collection<T extends { id: number }>

| Method / Prop | Description | |---------------|-------------| | insert(doc) | Inserts a shallow copy of doc. Throws on duplicate id. | | get(id) | O(1) lookup by primary key. | | findOne(id) | O(1) lookup by primary key (overload). | | findOne(predicate) | O(n) scan when no index applies. | | upsert(id, patch) | In-place Object.assign if exists; creates { id, ...patch } otherwise. | | entries() | Iterator over all rows (no clone). | | size | Number of rows in memory. |

Scale limits

| 🛡️ Current Status | | :--- | | Works correctly (Durable & Anti-Race Conditions). The performance limits are affirmed strictly by the number of elements. We are currently avoiding discussions regarding record sizes or the number of fields. |

[!IMPORTANT] The performance ranges below are based strictly on the number of elements (record count). We are currently avoiding considerations regarding the size of individual records or the number of fields.

| Range | Behavior | |-------|----------| | ≤ 10 000 records | Comfortable zone for connect, Map reads, and periodic flush. | | 10k – 50k | Still viable; a console.warn is emitted to monitor load and serialization times. | | > ~50 000 | High risk of memory pressure and slow JSON.stringify/parse; a warning recommends migrating to SQLite. |

When you need multiple indexes, partial queries without loading everything, or concurrent writers, consider SQLite (better-sqlite3, sql.js, etc.).

See PERFORMANCE.md for a detailed rationale of the design decisions.

Requirements

• Node.js ≥ 18

License

MIT