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](#getting-started)
- [Concepts](#concepts)
- [Document](#document)
- [Keys](#keys)
- [Values](#values)
- [Persistence](#persistence)
- [Corruption](#corruption)
- [Queries](#queries)
- [Operators](#operators)
- [API](#api)
- [`id()`](#open)
- [`open()`](#open)
- [`close()`](#close)
- [`insert()`](#insert)
- [`select()`](#select)
- [`selectById()`](#select-by-id)
- [`update()`](#update)
- [`delete()`](#delete)
- [`drop()`](#drop)
## Getting Started
### Installation
```sh
npm i leaf-db
```
### Example
Create a database using file storage with strong-typed documents:
```TS
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('db');
db.open();
db.insert([
{ title: 'Lady', name: 'Mipha' },
{ title: 'Young Rito Warrior', name: 'Tulin' }
]);
// [{ _id: , title: 'Lady', name: 'Mipha' }]
const characters = db.select({ title: 'Lady' });
```
## Concepts
### Document
Leaf-db stores data as [JSON](https://www.json.org/json-en.html) 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.
```TS
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.
```TS
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// []
const corrupt = db.open();
```
### Queries
Leaf-db supports both literal values and [operators](#operators). Example:
```TS
/**
* 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:
```TS
/**
* Operator query where values must be greater than number
*/
const a = { age: { $gt: 3 } }
```
Number operators:
- [`$gt`](#gt) - Is greater than
- [`$gte`](#gte) - Is greater or equal than
- [`$lt`](#lt) - Is less than
- [`$lte`](#lte) - Is less or equal than
String operators:
- [`$text`](#text) - Includes string (case insensitive)
- [`$regex`](#regex) - Matches RegExp
Array operators:
- [`$has`](#has) - Has value
- [`$size`](#size) - Equal to size
Logic operators:
- [`$not`](#not) - Does not equal literal
## API
### `id()`
Generate a new, unique id.
```TS
import LeafDB from 'leaf-db';
const id = LeafDB.id();
```
### `open()`
Open persistent storage.
```TS
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// Draft[]
const corrupted = db.open();
```
### `close()`
Close persistent storage.
```TS
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.
```TS
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
// [{ _id: , name: 'Tulin' }, { _id: , name: 'Mipha' }]
const docs = db.insert([{ name: 'Tulin', }, { name: 'Mipha' }]);
```
### `select()`
Find document(s) based on [query](#queries). Multiple queries can be used.
```TS
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.
```TS
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](#queries). Multiple queries can be used. Updated document cannot change shape.
```TS
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](#queries).
```TS
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.
```TS
import LeafDB from 'leaf-db';
const db = new LeafDB('db');
db.drop();
```
## Acknowledgements
-
- This project is inspired by [louischatriot/nedb](https://github.com/louischatriot/nedb).
