⚡ Sub-millisecond reads 🔒 ACID-safe single file 📦 Lightweight

Enterprise-grade performance (with tradeoffs)

Benchmarks show exceptional indexed-read performance and predictable write characteristics. Numbers below come from our benchmark runs; explanations + limitations right after the graphs.

Read Performance Scaling

Write Performance & Updates

⚙️

Test Machine

Intel i5-8350U • 8GB RAM • NVMe SSD

🧪

Measurement

High-res timers (process.hrtime.bigint()), isolated Node process

📊

Workload

50k / 100k / 1M datasets • indexed reads • bulk write • single-record update

Quick analysis

• Indexed reads are effectively O(1) and stay sub-ms as data grows — clutch for read-heavy stuff (caches, sessions, CLIs).
• Single-record updates rewrite the file to stay ACID, so cost scales with file size — update-heavy apps should prefer a write-optimized DB.
• Initial bulk writes are tuned for ingestion and scale predictably with dataset size.

Reference-only: these results reflect our specific machine, OS and dataset shape. Yours can differ. Treat this as guidance, not a guarantee.

When to use it

Use json-database-st when your workload is ≥95% reads with occasional updates, you want ultra-fast local lookups, and deploying a server is overkill. Think config stores, session/state caches, local CLIs, embedded tools, or ephemeral micro-services.

When not to

If you do frequent single-record updates on big files, or need multi-writer concurrency, pick a write-optimized engine (SQLite, server DB). If you need full-text search, complex queries, or replication, consider PouchDB/CouchDB or an embedded analytic DB.

Tuning tips

Batch writes where possible (group updates → rewrite once).
Keep hot keys in the index; avoid wide JSON blobs for per-request reads.
Prefer append-style change logs + periodic compaction for heavy ingest sessions.
Put the DB file on NVMe/SSD; spinning disks will hurt update latency.

Raw numbers

Dataset Size	File Size	Initial Write (ms)	Indexed Read (ms)	Single Update (ms)	Read Efficiency

Competition — reference patterns

These charts compare expected complexity trends for offline JSON-style stores. Values are normalized (relative), not from our benchmark runs. They’re for orientation, not proof.

Reference: Read pattern comparison (normalized)

Lower is better • 50k set = 1× baseline

Reference: Update pattern comparison (normalized)

Lower is better • relative cost by dataset size

Labels: json-database-st (indexed O(1)); LowDB / plain JSON (linear scan O(n)); NeDB / PouchDB (indexed) (≈O(log n)). Exact numbers vary by disk, cache, GC, and query shape.

Market Position & Alternatives

For context only — general roles, not strict benchmarks. Pick based on workload.

Solution	Architecture	Strengths	Best for
json-database-st	Single-file JSON + index	Sub-ms reads • simple deploy	Read-heavy microservices, CLIs, embedded
LowDB	JSON wrapper (scan)	Simplicity	Tiny datasets, simple configs
NeDB (archived)	Document store + B-tree idx	Indexed queries	Small apps needing simple indexing
PouchDB	Doc store + indexes + sync	Offline-first, replication	PWAs needing CouchDB sync
Redis (server)	In-memory KV	Ultra-fast	Caching/realtime (server required)
DuckDB	Embedded columnar	Analytics	On-device OLAP-ish queries