ShoulDB

Use localStorage as a small database with schemas, auto-increment IDs, and a fluent API. Works in the browser and in Node (with a storage mock). Safe when localStorage is missing (e.g. SSR).

• Node: >=18.0.0

Install

npm install shouldb

Quick start

const ShoulDB = require('shouldb');  // or: import ShoulDB from 'shouldb'
const db = new ShoulDB();

// 1. Define a model (schema = default fields for new records)
db.create('users', { name: '', age: 0, role: 'user' });

// 2. Fluent API: insert, get by id, find by filter
db.should('users').be({ name: 'Alice', age: 30 });   // insert → { __sdbKey: 1, name: 'Alice', age: 30, role: 'user' }
db.should('users').be({ name: 'Bob', role: 'admin' }); // insert → { __sdbKey: 2, name: 'Bob', age: 0, role: 'admin' }

db.should('users').have(1);                          // get by id → { __sdbKey: 1, name: 'Alice', ... }
db.should('users').find({ role: 'admin' });         // filter → [ { __sdbKey: 2, name: 'Bob', role: 'admin', ... } ]

// 3. Direct API (same thing)
db.insert('users', { name: 'Carol' });
db.select('users', 3);
db.find('users', { role: 'user' });

// 4. Wipe everything
db.clear();

API

Method	Description
create(model, schemaObj)	Define a model and default field values for new records.
should(model)	Fluent API: returns { be(obj), have(id), find(filter) }.
insert(model, obj)	Insert a record; merges with schema defaults and assigns __sdbKey.
select(model, id)	Get one record by __sdbKey; returns null if not found.
find(model, filter)	Get all records where every filter key matches the record.
clear()	Wipe the database and all schemas.
getDB(model?)	Raw DB object or one model’s array.
getSchema(model)	Get { schema, lastId } for a model.

Records always get an auto-increment __sdbKey. Schema defaults are applied on insert; you can override or omit fields.

Tests

npm test

Uses a simple console.assert test suite; in Node, localStorage is mocked so tests run without a browser.

License

MIT