:man: Sir

Sir.DB -- A simple database on the file system.

JSON files organised into subdirectories for each table.

Like SirDB? You'll probably love ServeData! ServeData is a powerful yet simple server for SirDB with baked-in schemas, users, groups, permissions, authentication, authorization and payments.

overview

With this library you can make databases that are:

human-readable
git-diffable, and therefore versionable, and
text-based. Everything is a JSON file, including the database meta information.

Sir.DB:

is written in literate, tested JavaScript,
is permissively licensed, and
is around 500 lines of code and 6.6Kb gzipped.

features

Human readable
Store any JSON-able object
Index on any property (for nested objects, only index top-level properties)
Auto ID or custom ID
Diffable by git
All records, indexes and table information are JSON files
1 file per record, 1 file per unique index value, 1 file per table info
1 sub-directory per table, 1 sub-directory (nested inside table) per indexed property

All in all this makes the database easy to understand and inspect. As well as making the code easy to read and maintain.

roadmap

<PageableTable>.getPage
Transactions
ACID guarantee (as long as accessed by single node thread)
Can expand ACID to multi-threaded access with a request queue.

get

npm i --save sirdb

add git, make diffable.

Just cd into your DB root path (the root path given to config()) and type git init. Or do it at any ancestor directory.

repository guide

This repository has around 500 lines of code and 2 dependencies (esm and discohash), and is organized as follows:

api.js: the main file (config, dropTable, getTable and getIndexedTable)
table.js: Table and IndexedTable classes
stats/: see the source-code stats

api

There's only a couple of handful of calls in this api: config, dropTable, getIndexedTable, getTable, put, get, getAllMatchingKeysFromIndex and getAllMatchingRecordsFromIndex

config({root: path})

Configure the root directory of your database.

dropTable(name: string)

Deletes a table.

getTable(name: string): Table

Creates a table (if it doesn't exist) and returns it.

getIndexedTable(name: string, indexed_properties: string[]): IndexedTable

Creates a table (if it doesn't exist) that has indexes for the given properties, and returns it.

<Table>.put(key: string, value: any, greenlights?: function | function[] | Evaluator)

Adds (or updates) an item to the table by key.

<Table>.get(key: string, greenlights?: function | function[] | Evaluator)

Gets an item from the table by key.

<IndexedTable>.getAllMatchingKeysFromIndex(prop: string, value: any): string[]

Gets all item keys from the table that have a property prop that matches value, if that property is indexed.

<IndexedTable>.getAllMatchingRecordsFromIndex(prop: string, value: any): any[]

Gets all items from the table that have a property prop that matches value, if that property is indexed.

<Table>.getAll(): any[]

Gets all items from the table.

<PageableTable>.getPage(cursor: string, count?: int): any[]

Get count (default 10) items from the table, starting at the first item after cursor. Note: not yet implemented.

examples

See below for how the api calls are used:

import path from 'path';
import assert from 'assert';
import fs from 'fs';

import {getTable, getIndexedTable, dropTable, config} from './api.js';

testGetTable();
testGetIndexedTable();
testDropTable();
testPut();
testIndexedPut();
testGet();
testGetAll();

function testGetTable() {
  const root = path.resolve(__dirname, "test-get-table");
  config({root});

  dropTable("users");
  dropTable("subscriptions");

  getTable("users");
  getTable("subscriptions");

  assert.strictEqual(fs.existsSync(path.resolve(root, "users", "tableInfo.json")), true);
  assert.strictEqual(fs.existsSync(path.resolve(root, "subscriptions", "tableInfo.json")), true);

  fs.rmdirSync(root, {recursive:true});
}

function testGetIndexedTable() {
  const root = path.resolve(__dirname, "test-get-indexed-table");
  config({root});

  dropTable("users");
  dropTable("subscriptions");

  getIndexedTable("users", ["username", "email"]);
  getIndexedTable("subscriptions", ["email"]);

  try {
    assert.strictEqual(fs.existsSync(path.resolve(root, "users", "tableInfo.json")), true);
    assert.strictEqual(fs.existsSync(path.resolve(root, "subscriptions", "tableInfo.json")), true);

    assert.strictEqual(fs.existsSync(path.resolve(root, "users", "_indexes", "username", "indexInfo.json")), true);
    assert.strictEqual(fs.existsSync(path.resolve(root, "users", "_indexes", "email", "indexInfo.json")), true);
    assert.strictEqual(fs.existsSync(path.resolve(root, "subscriptions", "_indexes", "email", "indexInfo.json")), true);
  } catch(e) {
    console.error(e);
  }

  fs.rmdirSync(root, {recursive:true});
}

function testDropTable() {
  const root = path.resolve(__dirname, "test-drop-table");
  config({root});

  getTable("users");
  getTable("subscriptions");

  dropTable("users");
  dropTable("subscriptions");

  assert.strictEqual(fs.existsSync(path.resolve(root, "users", "tableInfo.json")), false);
  assert.strictEqual(fs.existsSync(path.resolve(root, "subscriptions", "tableInfo.json")), false);

  fs.rmdirSync(root, {recursive:true});
}

function testPut() {
  const root = path.resolve(__dirname, "test-get-table");
  const errors = [];
  let gotItems;
  let key = 1;

  config({root});

  dropTable("items");

  const Items = getTable("items");
  const items = [
    {
      key: `key${key++}`,
      name: 'Apple',
      type: 'fruit',
      grams: 325
    },
    {
      key: `key${key++}`,
      name: 'Pear',
      type: 'fruit',
      grams: 410
    },
    {
      key: `key${key++}`,
      name: 'Soledado',
      type: 'career',
      grams: null,
      qualities_of_winners: [
        "devisiveness",
        "rationality",
        "aggression",
        "calmness"
      ]
    },
  ];
  
  try {
    items.forEach(item => Items.put(item.key, item));
  } catch(e) {
    errors.push(e);
  }

  assert.strictEqual(errors.length, 0);

  try {
    gotItems = items.map(item => Items.get(item.key));
  } catch(e) {
    errors.push(e);
  }

  assert.strictEqual(errors.length, 0);

  assert.strictEqual(JSON.stringify(items), JSON.stringify(gotItems));

  fs.rmdirSync(root, {recursive:true});
}

function testIndexedPut() {
  const root = path.resolve(__dirname, "test-indexed-put-table");
  const errors = [];
  let gotItems1 = [], gotItems2 = [], gotItems3 = [];
  let key = 1;

  config({root});

  dropTable("items");

  const Items = getIndexedTable("items", ["name", "type"]);
  const items = [
    {
      key: `key${key++}`,
      name:

Sirdb

Install / Use

README