Storage Async

Lightweight, asynchronous, key-value JSON storage for Node.js applications. Supports TTL, atomic updates, self-repairing and more.

This module aims to provide relatively lightweight and reliable way of locally storing JSON data, such as cache, preferences or temporary settings.

Highlights

• Lightweight. About 30kB (minified and gzipped). Only 3 dependencies.
• Reliable. Uses atomic file updates and can self-repair from invalid manual changes.
• Temporary. Supports TTL (time-to-live).
• Familiar API. Uses the same API as the Map object.
• Well tested. To make sure it handles various use cases correctly.
• Written in TypeScript.

Install

$ npm install storage-async

Usage

import {createStore} from 'storage-async';

(async () => {
	const store = await createStore();

	await store.set('name', 'John');
	await store.set('age', 20);

	await store.has('name'); //=> true

	await store.delete('age');

	await store.get('name'); //=> 'John'

	await store.clear();
})();

API

createStore(options)

Creates a new store, which features the following API:

interface Handlers {
	set: (key: string, value: unknown) => Promise<void>;
	get: (key: string) => Promise<unknown>;
	has: (key: string) => Promise<boolean>;
	delete: (key: string) => Promise<void>;
	clear: () => Promise<void>;
}

options

Type: Options

Storage options:

interface Options {
	path?: string;				// defaults to './store.json
	ttl?: number;				// defaults to 900000ms (15 minutes)
	resetOnFailure?: boolean;	// whether to reset the store if it couldn't be repaired
}

How it works?

1. When the store file (./store.json by default) does not exist, it will be created automatically.
2. If the file can't be read (possibly due to invalid format), the module will attempt to repair it (to avoid data loss).
3. If the repairing process can't finish, the module will delete it and create a new one (possibly resulting in data loss).
4. If the file is valid and contains the information about TTL and creation time, the module will check whether the TTL hasn't yet expired.
5. The module will now be able to read/write data. Writing is done atomically, so that unexpected shutdowns won't corrupt the store file.

License

MIT © Antoni Kepinski