Skip to content

Alex-Werner/TyrDB

Repository files navigation

TyrDB

NPM Version Build Status Release Date standard-readme compliant

Fast in-memory database for node and browser that is portable and easy to use

The goal of TyrDB is to provide a fast, easy and instant to use database.
It aims at getting close to the performance and features you could find in your modern NoSQL DB solutions.
For that, a subset of the Mongo query syntax is being used, so the production switch from TyrDB dev env to MongoDB would be as fast as possible.

TyrDB is intended for bootstrapping project or small backend servers.
Due to the use of a modified B+Tree system, performance stays at service without the need to load everything in memory as you can encounter with many Node DB out-there.

N.B : Fields are indexed by default. Specifically exclude field that might be too lengthy as otherwise might have heavy performance effect (see more on BTree to understand).
Uniques field are also available.
TyrDB relies on SBTree as it's main dependencies for data.

Table of Contents

Installation

npm install tyrdb

Usage

mkdir myproject
cd myproject
npm init
npm install tyrdb
touch index.js

And there just use that snipets to start playing ! :

const TyrDB = require('tyrdb');
const {MemoryAdapter} = require('tyrdb/adapters')

const adapter = new MemoryAdapter();
const client = new TyrDB({adapter});

async function start(){
 await client.connect();
 console.log('In sync with the adapter/server');
 const db = await client.db('myproject');
  
 const doc = {
  name: 'Jean',
  age: 33,
  nestedObject:{isNested:true}
}
  // Allow to pass along SBTree options
 const opts = {};
 const col = await db.collection('users', opts);

 const insertedDoc = await col.insert(doc);
 const search = await col.find({age:33}); //[{name:"Jean",age:33, nestedObject:{isNested:true}]
 const [jean] = search;
  jean.age = 34;
 await col.replace(jean);

 await client.close();
}
start();

Alternatively, you might prefer to wait for the DB to be ready (as it will autoconnect by default)

const TyrDB = require('tyrdb');
const {MemoryAdapter} = require('tyrdb/adapters')

const adapter = new MemoryAdapter();
const client = new TyrDB({adapter});
const dbName = 'myproject';

async function start(){
 const db = await client.db(dbName);
 await client.close();
}
db.on('ready',start);

Documentation

Documents Metadata

  • Document have an _id by default, the format is 1-to-1 with the specification of MongoDB ObjectID
  • They also have a _meta which hold the current version of the file and it's creation date.

Adapters

  • MemoryAdapter : Default adapter. Set Store inMemory. Limited by heap memory available (good enough).
const {MemoryAdapter} = require('tyrdb/adapters')
const adapter = new MemoryAdapter();
const client = new TyrDB({adapter});
  • FsAdapter : FileSystem adapter. Default path will be .db. Path and options should be passed in TyrDB constructor.

Storage will be optimized therefore not planned to be easily browsable or openable (big files). Each collection have a set of .dat and .meta.json file. Keep both are meta is needed to find the data in the data file :).

const {FsAdapter} = require('tyrdb/adapters')
const adapter = new MemoryAdapter();
const client = new TyrDB({path:'.db/mydbpath',adapter});
  • IndexedAdapter : Persist in web browser indexed db storage : TODO
  • LocalStorageAdapter : Persist in web browser local storage : TODO

FAQ :

Q : Is it a definitive API ?

Any move we might take will be in the direction of matching more carefully the mongo syntax. So you should be good on that.
No promises, I tend to love breaking things to move on.

Q : Why another one ?

The in-memory things. It's annoying, I need to be able to have as much as big documents as I would love without hitting that much the performance. So it uses a B+Tree modified architecture for storing. You can see the dependency here SBTree.

Q : Any drowback of this library ?

Right now, you are limited in the abilities of querying as we only support ($eq, $neq, $lt, $lte, $gt, $gte, $in, $nin), there is not yet all the fancyness from the MongoDB or anything yet (especially $regex).
It also might never come, dependings of if I need them myself or have extra time and demands for it, so mind opening an issue if it is your case in the SBTree repository :).

Also, if your document has it's own _id value, then it should be a valid mongodb ObjectId value. Post an issue if that is colliding with your own data, we can change it.

Q : Difference between .serialize() and .export()

TyrDB by default do not hold any data, only refs and indexes. Data are handled by adapters. Therefore every element is caracterized by it's own metadata and data. .export() fetches the metadata elements. .serialize() the json representation of the elements.

Q : How much work is needed to switch to mongodb afterwards :

TL;DR : Very few, especially by creating an adapter in TyrDB that would override uses of SBTree for a Mongoose or similar interface.
TODO : Feature
TODO STEP BY STEP.

Q : Why the name

It's a tribute to LokiDB existing with similar purpose (with limitation that weren't suiting my needs). Therefore TyrDB.

Q : Links ?