Skip to main content

Getting started

LioranDB Embedded is a file-based JSON document database for Node.js (backed by a write-ahead log).

1) Install​

npm i @liorandb/core

2) Your first database (hello world)​

This example does all the basics:

  • create a LioranManager (the "owner" of the root folder on disk)
  • open a LioranDB by name
  • open a Collection
  • write a document
  • read it back
  • close cleanly
import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  // optional: where databases live on disk
  // rootPath: "./data",
});

const db = await manager.db("app");
const users = db.collection<{ _id?: string; email: string; plan: "free" | "pro" }>("users");

await users.insertOne({ email: "a@b.com", plan: "free" });

const found = await users.findOne({ email: "a@b.com" });
console.log(found);

await manager.close();
Sandbox output (example)
{ _id: "b2c6b5d8-6f3f-4d4b-8d52-2a1c6f6f9b0e", email: "a@b.com", plan: "free", __v: 1 }

3) A slightly bigger example (update + query + paging)​

This shows common patterns you'll use in real apps:

  • use $inc updates
  • filter with operators like $gte
  • page results with { limit, offset }
import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });
const db = await manager.db("shop");
const items = db.collection<{ _id?: string; sku: string; qty: number }>("items");

await items.insertMany([
  { sku: "A", qty: 10 },
  { sku: "B", qty: 2 },
  { sku: "C", qty: 25 },
]);

await items.updateOne({ sku: "B" }, { $inc: { qty: 5 } });

const page1 = await items.find({ qty: { $gte: 5 } }, { limit: 2, offset: 0 });
console.log(page1.map(x => ({ sku: x.sku, qty: x.qty })));

await manager.close();
Sandbox output (example)
[ { sku: "A", qty: 10 }, { sku: "B", qty: 7 } ]

What gets created on disk?​

  • A root folder containing one folder per database name.
  • Each collection is stored in its own directory (file-based storage).

By default, @liorandb/core uses:

  • process.env.LIORANDB_PATH if set, otherwise
  • ~/LioranDB/db (created automatically)

If you want a project-local folder, pass rootPath to new LioranManager({ rootPath }).