README.md

leaf-db

leaf-db is a simple NoSQL embeddable database for Node.js.

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
• Concepts
  • Document
    • Keys
    • Values
  • Persistence
  • Corruption
  • Queries
    • Operators
• API
  • id()
  • open()
  • close()
  • insert()
  • select()
  • selectById()
  • update()
  • delete()
  • drop()

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:

• $gt - Is greater than
• $gte - Is greater or equal than
• $lt - Is less than
• $lte - Is less or equal than

String operators:

• $text - Includes string (case insensitive)
• $regex - Matches RegExp

Array operators:

• $has - Has value
• $size - Equal to size

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

• Icon made by Freepik from www.flaticon.com
• This project is inspired by louischatriot/nedb.