unitdb

A lightweight SQLite-backed JSON document database for Node.js with a minimal API and multi-process safety. All persistence, locking, durability, and recovery are delegated entirely to SQLite.

unitdb keeps the same simple query and mutation model as sysdb, but uses SQLite as the sole source of truth, making it safe for multiple processes, workers, and restarts.

Features

• SQLite-backed: Disk is authoritative.
• Multi-process safe: Concurrent readers and writers supported.
• Crash safe: SQLite journaling and recovery.
• Mongo-style Queries: $gt, $lt, $gte, $lte, $ne, $in, $nin, $regex.
• JSON Documents: Schema-less records stored as JSON.
• Atomic Writes: Each mutation is fully committed or rolled back.
• Pagination: Built-in limit and skip.
• Minimal API: Only get() and set().

Installation

npm i unitdb

Node.js v22+ required (uses built-in node:sqlite).

Usage

var unitdb = require('unitdb')
var db = unitdb('./unitdb.sqlite')

Usage Examples

1. Inserting Data

Passing a single object inserts a new document. A UUID id is generated automatically if missing.

await db.set({
  name: 'Project Alpha',
  status: 'pending',
  priority: 1,
  createdAt: new Date()
})

2. Querying with Operators

// Find high priority tasks
var tasks = db.get({
  priority: { $gte: 5 },
  status: { $ne: 'archived' }
})

// Regex and array operators
var results = db.get({
  name: { $regex: /^Project/i },
  tags: { $in: ['urgent', 'active'] }
})

3. Updating Data

// Update all pending tasks
await db.set({ status: 'pending' }, { status: 'active' })

// Update by ID
await db.set({ id: 'some-uuid' }, { progress: 100 })

4. Deleting Data

// Delete one record
await db.set({ id: 'some-uuid' }, null)

// Delete all completed tasks
await db.set({ status: 'completed' }, null)

5. Pagination

var page = db.get({ type: 'log' }, {
  limit: 10,
  skip: 10
})

Data Model

Internally, unitdb uses:

• One SQLite database file

• One table:

  • id TEXT PRIMARY KEY
  • json TEXT (serialized document)

No schema migrations are required.

Concurrency Model

• Multiple processes can read and write safely
• SQLite enforces locking and ordering
• Readers never see partial writes
• Writers are serialized automatically

Comparison with sysdb

| Feature | sysdb | unitdb | | ------------------ | ----------------- | --------------- | | Source of truth | Memory | SQLite | | Multi-process safe | No | Yes | | Crash recovery | Optional snapshot | SQLite | | Read latency | Lower | Slightly higher | | Write durability | Eventual | Immediate | | API surface | Minimal | Minimal |

API Reference

| Method | Description | | ----------------------- | ------------------------------------------------------------- | | get(query, [options]) | Returns matching documents. Supports { limit, skip, sort }. | | set(query, [values]) | Insert, update, or delete documents. |

License

ISC.

Acknowledgements

Created by Vidar Eldøy, Tekki AS.