• What: A filesystem-based pico-NoSQL-DB that allows mutations by filesystem operations while running to co-exist with API state changes.
• Why: For every project that needs commerical-scale and -robustness on millions of rows, there's several 'our business runs on XLS and manual labor' automatable projects who's data would easily fit in the microcontroller in my garage door opener. Some of these use cases also need the kind of history-tracking that git would give me. So I built an extremely KISS storage layer that allows me to use unixy tools to do bulk record maintenance.
• How: using chokidar to to monitor the filesystem kept the complexity of this library to a minimum.

const chokdb = require('@ashnazg/chok-db');
const client = await chokdb({path: 'folder_of_jsons/'});

client.create({a:1,b:2}); // autoassigns new ID
client.update(1, {a:2,b:1});
console.log(client.read(1));
client.del(1);

The three mutators return promise({db, id}) as a convenience.

Want to just grab the whole map of rows? Skip the ID param on read().

const map = client.read();

(Both usages of read() are synchronous.)

fast or write-guaranteed?

All mutators complete the work in-memory synchronously, and then asynchronously write to disk.

If you await the create/update/del call before responding to caller, you're in write-guaranteed mode.

if you want the ID that create() used without waiting for the file write, just check client.last_id_created synchronously right after create() returns.

(Regardless of fast vs safe usage, client.last_id_created is always zero when the service initializes and not retained between runs.)

Customize Behavior

The chokdb({path}) function takes several other inputs; you could swap JSON for YAML or turn on verbose logging:

const yaml_backed_client = await chokdb({path: 'myyamls/', parser: string2yaml, serializer: yaml2string});

// here's all the current debug/log hooks:
const client = await chokdb({
	path,
	log: {
		write(id, body) { console.log("writing", id, body); },
		evt(chok_event_name, row_filename) { console.log("chokidar event", chok_event_name, row_filename); },
		parseErr(filename, error) { console.error('got', error, 'when I parsed', filename); }, // if you don't provide a parseErr, it just throws the error to chokidar instead.
	}
});

stream of events

Want to be notified of changes?

I wanted a way to push updates to websocket clients, so once the data's persisted to disk, these optional hooks are called:

const client = await chokdb({
	path,
	onadd(dying_record) {}
	onchange(altered_record) {}
	onunlink(new_record) {} // this is the only hook that happens _before_ the memory DB is updated.
});

Pico-Validation

Want to see if a user-provided value is a safe and present row ID?

client.validate(id); // throws on any 404 or unsanitary input.

ID field

Like SQLite, chokdb rows expose the internal auto increment to you. (This makes it easy for me to pass the row from DB/FE/UI/sub-UI and back again.)

But the ID field in the row is not changable; attempts will be reset next time you update().

Nor is there a way through this API to renumber a row. (But since the memory DB tracks changes on disk, this is trivial from the filesystem: mv 1.json 5.json)

Release 1.0.3

• fixed: To be fully unixy, row files' last line also has a '\n'
• new: .write(id) and .update(id) now support the idea that the second (body) param is optional -- in that mode, just save the mutations made directly to the memory copy.

Release 1.0.2

Just fixed this README

Release 1.0.1

• bugfix: catastrophic typo in unlink handler
• feature: chokdb will now mkdir the path you give it if it doesn't exist. (Make sure the base already exists; this isn't mkdir -p.)
• tweak: unused IDs are now routinely reused. (I know how classic RDBS's do it, but I think that if your data integrity doctrine depends on this instead of foreign-keys/cascades, you've already lost.)