SmartStore

Smart node.js store with persistence. Works just like a regular object, except it auto-persists to HDD. Useful for tiny project with basic persistence needs. Fire & forget.

Usage

npm install smartstore

const SmartStore = require('smartstore');

// There are also async methods, using promises
const store = SmartStore.openSync('/path/to/my/file.dat');

// Access the store like any other object
store.users = [];

// Yes, just like this. Changes will be detected.
store.users.push({
    username: 'mike'
});

// This will push out any pending changes and make sure you can no longer mutate it
store.closeSync();

const store2 = SmartStore.openSync('/path/to/my/file.dat');

console.log(store2.users[0].username); // mike

This is pretty much all the API you need to know. Just use it as you would any other object. It will persist automatically every 50-500 milliseconds (configurable).

Design goals

There are many "simple store" projects out there. What makes this one different?

✓ Access data like any other POJO object (no getters/setters)
✓ Persist only when touched / changed (no set interval)
✓ Does not mutate objects that are placed into the store (so, no adding special accessor properties or stuff like that)
✓ Persist regex and date objects
✓ Reasonably efficient (only writes when needed, caching)

Trade-offs

In order to achieve this, SmartStore uses a combination of ES6 Proxy objects and shallow-ish dirty checking. The benefits of this approach are listed above. Here are the downsides and ways to mitigate them:

✕ Less efficient with large object graphs. If you have perf concerns, set multiple keys instead of grouping everything as one object. Example:

Bad | Good| -----|-----| store.data = {a: ..., b: ...} | store.a = ...; store.b = ...

✕ Can't detect changes if you mutate the data outside the store. Example:

const users = store.users;
// ... later ...
users.push({username: 'carl'}); // Not detected

To tell the store users have changed, do this:

store.users = users;

✕ Getting the data triggers dirty check, even if you don't mutate it. You can use the trick above to prevent dirty checks.

✕ The API is convenient, but you might find it hard to later transition the project to a real database. If you think you might ever need to expand, I suggest you wrap the store into an async facade. Example:

module.exports = function DataStore(path) {
	const store = SmartStore.openSyn(path);

	this.getUsers = () => {
		return Promise.resolve(store.users);
	};
}

Stability

I will use SmartStore in a smallish personal project for now. It has sparse test coverage and no other production deployments.

I do not deem it stable enough for usage in projects with serious data persistence needs

Then again, if you had one of those, you'd probably use a real database anyway.

Changelog

|Version|Changes| |-------|-------| |0.2.1 |Fixed strict mode breakage| |0.3.0 |We are now checking that store db is accessible during init. Also fixed background flush bug where db location is not writeable. Added prettier. Better JSDocs.|

License

MIT