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.

Getting started
Concepts
- Document
  - Keys
  - Values
- Persistence
- Corruption
- Queries
  - Operators
API
- id()
- open()
- close()
- insert()
- select()
- 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' });

`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.

chronodave / leaf-db Goto Github PK

leaf-db's Introduction

leaf-db

Features

Table of Contents

Getting Started

Installation

Example

Concepts

Document

Keys

Values

Persistence

Corruption

Queries

Operators

API

id()

open()

close()

insert()

select()

update()

delete()

drop()

Acknowledgements

leaf-db's People

Contributors

Stargazers

Watchers

leaf-db's Issues

Recommend Projects

Recommend Topics

Recommend Org