Awesome
jsonl-db
Simple JSONL-based key-value store. Uses an append-only file to store the data. With support for database dumps and compressing the db file.
Usage
Load the module:
import { DB } from "@alcalzone/jsonl-db";
Open or create a database file and use it like a Map
// Open
const db = new DB("/path/to/file");
await db.open();
// db.isOpen is now true
// and use it
db.set("key", value);
db.delete("key");
db.clear();
if (db.has("key")) {
result = db.get("key");
}
// ...forEach, keys(), entries(), values(), ...
Handling invalid data
If corrupt data is encountered while opening the DB, the call to open()
will be rejected. If this is to be expected, use the options parameter on the constructor to turn on forgiving behavior:
const db = new DB("/path/to/file", { ignoreReadErrors: true });
await db.open();
Warning: This may result in inconsistent data since invalid lines are silently ignored.
Support custom objects/values
You can optionally transform the parsed values by passing a reviver function. This allows storing non-primitive objects in the database if those can be transformed to JSON (e.g. by overwriting the toJSON
method). To control the transformation values before they are saved to the database, use the serializer function. This is necessary for Map
s, Set
s, WeakMap
s and WeakSet
s.
function reviver(key: string, serializedValue: any) {
// MUST return a value. If you don't want to transform `serializedValue`, return it.
}
function serializer(key: string, value: any) {
// MUST return a value. If you don't want to transform `value`, return it.
}
const db = new DB("/path/to/file", { reviver, serializer });
await db.open();
Closing the database
Data written to the DB is persisted asynchronously. Be sure to call close()
when you no longer need the database in order to flush all pending writes and close all files:
await db.close();
Now, db.isOpen
is false
. While the db is not open, any calls that access the data will throw an error.
Controlling file system access
By default, the database immediately writes to the database file. You can throttle the write accesses using the throttleFS
constructor option. Be aware that buffered data will be lost in case the process crashes.
const db = new DB("/path/to/file", { throttleFS: { /* throttle options */ } });
The following options exist:
Option | Default | Description |
---|---|---|
intervalMs | 0 | Write to the database file no more than every intervalMs milliseconds. |
maxBufferedCommands | +Infinity | Force a write after maxBufferedCommands have been buffered. This reduces memory consumption and data loss in case of a crash. |
To create a compressed copy of the database in /path/to/file.dump
, use the dump()
method. If any data is written to the db during the dump, it is appended to the dump but most likely compressed.
Lockfile-related options
A lockfile is used to avoid concurrent access to the DB file. Multiple options exist to control where this lockfile is created and how it is accessed:
const db = new DB("/path/to/file", { lockfile: { /* lockfile options */ } });
Option | Default | Description |
---|---|---|
directory | - | Change where the lockfile is created, e.g. to put the lockfile into a tmpfs . By default the lockfile is created in the same directory as the DB file. If the directory does not exist, it will be created when opening the DB. |
staleMs | 10000 | Duration after which the lock is considered stale. Minimum: 2000 |
updateMs | staleMs/2 | The interval in which the lockfile's mtime will be updated. Range: 1000 ... staleMs/2 |
retries | 0 | How often to retry acquiring a lock before giving up. The retries progressively wait longer with an exponential backoff strategy. |
retryMinTimeoutMs | updateMs/2 or 1000 | The start interval used for retries. Minimum: 100 |
Copying and compressing the database
await db.dump(); // To use the default dump filename `/path/to/file.dump`
await db.dump("/somewhere/else.jsonl"); // To use a different filename
After a while, the main db file may contain unnecessary entries. The raw number of entries can be read using the uncompressedSize
property. To remove unnecessary entries, use the compress()
method.
await db.compress();
Note: During this call, /path/to/file.dump
is overwritten and then renamed, /path/to/file.bak
is overwritten and then deleted. So make sure you don't have any important data in these files.
The database can automatically compress the database file under some conditions. To do so, use the autoCompress
parameter of the constructor options:
const db = new DB("/path/to/file", { autoCompress: { /* auto compress options */ }});
The following options exist (all optional) and can be combined:
Option | Default | Description |
---|---|---|
sizeFactor | +Infinity | Compress when uncompressedSize >= size * sizeFactor |
sizeFactorMinimumSize | 0 | Configure the minimum size necessary for auto-compression based on size |
intervalMs | +Infinity | Compress after a certain time has passed |
intervalMinChanges | 1 | Configure the minimum count of changes for auto-compression based on time |
onClose | false | Compress when closing the DB |
onOpen | false | Compress after opening the DB |
Keeping track of timestamps
The DB can automatically keep track of the last time a key was written. To do so, set the enableTimestamps
option to true
. Every set
call will then update the timestamp of a value, which can be retrieved using getTimestamp(key)
. To opt out of this behavior for individual writes, pass false
as the 3rd argument to set
.
db.set("key", "value", false); // Don't update the timestamp
Note Recording timestamps decreases the DB throughput by ~10...30% depending on how it is used.
Import / Export
Importing JSON files can be done this way:
// pass a filename, the import will be asynchronous
await db.importJson(filename);
// pass the object directly, the import will be synchronous
db.importJson({key: "value"});
In both cases, existing entries in the DB will not be deleted but will be overwritten if they exist.
Exporting JSON files is also possible:
await db.exportJson(filename[, options]);
The file will be overwritten if it exists. The 2nd options argument can be used to control the file formatting. Since fs-extra
's writeJson
is used under the hood, take a look at that method documentation for details on the options object.
Changelog
<!-- Placeholder for next release: ### __WORK IN PROGRESS__ -->3.1.1 (2024-01-25)
- Reduced CPU load while idle (#475)
3.1.0 (2023-03-15)
- Support opt-out of updating timestamps for individual set calls (#415)
3.0.0 (2023-03-09)
- Support recording timestamps for each value (#413)
- Drop support for Node.js 12 (#414)
2.5.3 (2022-09-06)
- Consider lockfiles from the future to be stale (#371)
2.5.2 (2022-05-02)
- Dependency updates
2.5.1 (2022-02-13)
- Allow setting minimum retry timeout
- Correct minimum value for the lockfile's stale timeout
2.5.0 (2022-02-13)
- Add the ability to control the lockfile's stale/update timeouts and retrying acquiring a lock
2.4.3 (2022-02-09)
- Errors while automatically compressing the DB are now caught
2.4.2 (2022-02-09)
- Errors while automatically restoring the DB from a backup or dump are now caught
- Simplified and decoupled the persistence code. Individual commands like
dump
andcompress
are now properly sequenced and should no longer conflict with each other. - Increased throughput for primitive entries by ~2x
2.4.1 (2021-12-30)
- Individual writes are now collected in a string and written at once, increasing throughput for larger entries by ~10x.
2.4.0 (2021-12-27)
- Stringifying the individual lines now happens lazily and only when actually necessary, increasing the throughput by 30...50x.
2.3.0 (2021-12-19)
- Add the ability to dump the database to a different location
2.2.0 (2021-10-15)
- Add the ability to specify where the lockfile is created
2.1.0 (2021-06-22)
- When opening the DB, recover from crashes that happened while compressing the DB
- Ensure that the DB files are flushed to disk when closing or renaming files
- Tests now work with the real filesystem instead of
mock-fs
, which breaks in Node.js16.3+
- Modernized TypeScript build output
2.0.0 (2021-06-19)
Update dependencies and drop support for Node.js 10
1.2.5 (2021-05-29)
Prevent opening one DB file in multiple instances of the DB using lockfiles
1.2.4 (2021-02-15)
Reduced the work done while opening a DB
1.2.3 (2021-01-02)
Fixed a crash that happens while compressing the DB when the .bak
file exists
1.2.2 (2020-10-16)
When consuming this library without skipLibCheck
, @types/fs-extra
is no longer required
1.2.1 (2020-08-20)
Update dependencies
1.2.0 (2020-05-25)
Added an optional serializer function to transform non-primitive objects before writing to the DB file
1.1.2 (2020-05-11)
Fixed a timeout leak that would prevent Node.js from exiting
1.1.1 (2020-05-07)
Leading directories are now created if they don't exist
1.1.0 (2020-05-02)
Added functionality to throttle write accesses
1.0.1 (2020-04-29)
Export JsonlDBOptions
from the main entry point
1.0.0 (2020-04-29)
Added auto-compress functionality
0.5.1 (2020-04-28)
Fix: The main export no longer exports JsonlDB
as DB
.
0.5.0 (2020-04-27)
Added an optional reviver function to transform non-primitive objects while loading the DB
0.4.0 (2020-04-27)
- Renamed the
DB
class toJsonlDB
open()
now skips empty linesopen()
throws an error with the line number when it encounters an invalid line. These errors can be ignored using the new constructor options argument.
0.3.0 (2020-04-26)
- Added
importJson
andexportJson
methods
0.2.0 (2020-04-25)
- Added
isOpen
property
0.1.3 (2020-04-25)
- Writes that happen while
compress()
replaces files are now persisted
0.1.2 (2020-04-25)
compress()
no longer overwrites the main file while the DB is being closed
0.1.1 (2020-04-25)
- Fixed some race conditions
0.1.0 (2020-04-25)
First official release