SencilloDB: an embedded JSON document store for Node.js

Install

npm install sencillodb

import { SencilloDB } from "sencillodb";

const db = new SencilloDB({ file: "./app.json" });

const user = await db.transaction(async (tx) => {
  await tx.ensureIndex({ collection: "users", field: "email", unique: true });
  return tx.create({
    collection: "users",
    data: { name: "Alice", email: "alice@example.com", age: 30 },
  });
});

ESM only, Node 18 or later, TypeScript types included.

What it is

• Serialized, all-or-nothing transactions. A throw inside the callback discards every change.
• Queries with $eq, $ne, $gt, $in, $regex, $exists, $and, $or and more, with dot paths, sorting, limit and skip.
• Secondary indexes with optional unique constraints, used for equality, $in and range lookups.
• Three storage modes: one file, one file per collection, or one file per index bucket for large collections.
• Durability options: atomic fsynced writes, a checksummed append-only log, and a cross-process lock with ownership tokens and heartbeats.
• Operations: export, import, snapshots, versioned migrations, TTL expiry, change events, gzip compression, and stats(), explain(), validate() and repair().
• Typed access through SencilloDB<AppSchema> collection handles, cursor pages and async-iterable streams.

Status

Pre-1.0, published, and narrow on purpose. 0.8.0 is an audit-hardening release. Its changelog records 102 tests and a production dependency audit with zero vulnerabilities.

The project's own use-cases guide names the boundary:

• One writer process is the simplest correct setup. A lock exists for more, at a cost.
• Data sized to what you can scan and back up as JSON. Each file or shard has to fit in memory while it is parsed.
• No server-side access control, replication or remote sync.
• Not for network filesystems such as NFS or SMB, where atomic rename and lock files are not dependable.

Past that boundary, SQLite, Postgres or MongoDB is the right tool.

Changelog

From the project's CHANGELOG.md, the npm publish dates, and the git history.

• 0.8.0 August 28, 2026 Audit hardening. Breaking: documents are normalized to JSON before mutation, unknown query operators throw, and append-only log records use a checksummed envelope that older versions cannot read. Blocks prototype pollution, adds lock ownership tokens and heartbeats, rewrites only dirty shards, and adds typed collection handles, page(), stream(), stats(), explain(), validate() and repair(). Drops the last runtime dependency. Tag v0.8.0.
• 0.7.0 August 10, 2026 Implements an August 10 audit and splits the source into modules. Returned documents are copies, and it adds updateMany and destroyMany, partial updates, unique constraints, index-backed range queries, multi-process locking, change events, export and import, TTL, schema v2 and migrations. Tag v0.7.0.
• 0.6.0 November 28, 2025 LRU cache, gzip compression, stream processing and sharding.
• 0.3.0 to 0.5.0 November 27 and 28, 2025 Published to npm with no changelog entries.
• 0.1.x January 2023 The first releases: transactions, TypeScript bindings, quickTx, collection and index drops, rewriteCollection, resource managers, and load and save hooks.

Upgrading from 0.7? Existing append-only logs stay readable, but read the 0.8.0 breaking changes before you deploy.