npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

leaf-db

v10.1.0

Published

Small file-based database for node.js

Downloads

44

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:

  • $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:

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