leaf-db
v10.1.0
Published
Small file-based database for node.js
Downloads
44
Maintainers
Readme
Features
- Strong-typed documents and queries.
- Easy to embed as it does not require an HTTP server to run.
- Uses JSON documents.
Table of Contents
Getting Started
Installation
npm i leaf-db
Example
Create a database using file storage with strong-typed documents:
import LeafDB, { Draft } from 'leaf-db';
interface Document extends Draft {
title: string
name: string
}
// Use process.cwd() + 'db' as database root
const db = new LeafDB<Document>('db');
db.open();
db.insert([
{ title: 'Lady', name: 'Mipha' },
{ title: 'Young Rito Warrior', name: 'Tulin' }
]);
// [{ _id: <string>, title: 'Lady', name: 'Mipha' }]
const characters = db.select({ title: 'Lady' });
Concepts
Document
Leaf-db stores data as JSON documents.
Keys
Document keys must be of type string
and cannot start with $
.
Every document is required to have an _id
field. Leaf-db automatically creates an _id
if the field does not exist on insertion. Keys have the following restrictions:
_id
cannot be mutated once created._id
must be unique.
Values
Leaf-db only supports JSON values, which are:
object
array
string
number
true
false
null
Persistence
Leaf-db stores the database in memory by default. To make use of persistence, simply provide a path in the constructor and open the database.
import LeafDB from 'leaf-db';
/**
* Create a new database under process.cwd()
* This will create `db.txt` in process.cwd()
*/
const db = new LeafDB('db');
db.open();
Corruption
When opening a database from storage, leaf-db will return any documents that are corrupt. These documents will be deleted once opened.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// []
const corrupt = db.open();
Queries
Leaf-db supports both literal values and operators. Example:
/**
* Literal query where value must equal the query value
* { name: 'tulin' } // No match
* { name: 'Mipha' } // No match
*/
const a = { name: 'Tulin' };
/**
* Objects and arrays must be equal for it to match:
* { eras: [] } // No match
* { eras: ['era of the wilds'] } // No match
* { eras: ['Era of the Wilds', 'Sky Era'] } // No match
*/
const b = { eras: ['Era of the Wilds'] }
Operators
Operators allow for more complex queries. Operators must always be used in combination with values. For example:
/**
* Operator query where values must be greater than number
*/
const a = { age: { $gt: 3 } }
Number operators:
String operators:
Array operators:
Logic operators:
$not
- Does not equal literal
API
id()
Generate a new, unique id.
import LeafDB from 'leaf-db';
const id = LeafDB.id();
open()
Open persistent storage.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Draft[]
const corrupted = db.open();
close()
Close persistent storage.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
db.open();
db.close();
insert()
Insert document(s) into the database. Will throw an error if duplicate _id
's are found.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// [{ _id: <string>, name: 'Tulin' }, { _id: <string>, name: 'Mipha' }]
const docs = db.insert([{ name: 'Tulin', }, { name: 'Mipha' }]);
select()
Find document(s) based on query. Multiple queries can be used.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Return docs where `name` is equal to `Mipha`
const docs = db.select({ name: 'Mipha' });
// Return docs where `name` is equal to `Mipha` or where `name` is equal to `Tulin`
const docs = db.select({ name: 'Mipha' }, { name: 'Tulin' });
selectById()
Find document(s) based on _id
. Multiple ids can be used.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Return docs where `_id` is equal to `Mipha`
const docs = db.selectById('Mipha');
// Return docs where `_id` is equal to `Mipha` or where `_id` is equal to `Tulin`
const docs = db.selectById('Mipha', 'Tulin');
update()
Update document(s) based on query. Multiple queries can be used. Updated document cannot change shape.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Update docs where `name` is equal to `Tulin` and replace `name` with `Mipha`
const docs = db.update({ name: 'Mipha' }, { name: 'Tulin' });
delete()
Delete document(s) based on query.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Delete docs where `name` is equal to `Mipha`
const docs = db.delete({ name: 'Mipha' });
drop()
Delete all documents in the database.
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
db.drop();
Acknowledgements
- This project is inspired by louischatriot/nedb.