hawk-fox-terrier

Intro

First of all I want to start with a disclaimer. This is a not a BIG database that you have to use into production. The idea behind this is to have small data storage library to use into small pet projects. Without the need to install standalone database or use online storage.

In few words - small prototyping tool to test your idea fast without adding overhead.

WARNING The API is still work in progress so things may change. Will try to keep it as stable as I can. Thanks in advance!

Installation

To install it just use NPM for the task:

$ npm i database

Usage

const Database = require('database')
const db = new Database()
 
// Add my first record
db.collection('users').insert({ username: 'batman', status: 'active' })
 
// Get it back
let batman = db.collection('users').find((record) => record.username === 'batman').first()
 
/*
{
  _id: 'xxx',
  username: 'batman',
  status: 'active',
  created_at: <JavaScript Date object>,
  updated_at: <JavaScript Date object>,
  _version: 0
}
*/
 

There is combined insert/update function called Collection#upsert - this will insert or update the record inside collection if it already exist. So in practice Record that have the same _id will match the search pattern.

let record = { name: 'John Doe' }
db.collection('users').upsert(record)
// => insert

let record = { _id: 'xxx', name: 'John Doe' }
db.collection('users').upsert(record)
// => update record with _id = xxx

KeyValue

In general the database store records inside collections. And this could be useful in some cases. But you may need a way to keep key/value storage for example: System settings or counters.

For this case there is HashTable implementation that you could use.

const Database = require('database')
const db = new Database()
 
db.hash('counters').set('liked', 1)
let liked_count = db.hash('counters').get('liked')
// => 1
 

You could also get list of all keys in HashTable

let keys = db.hash('counters').keys()
// => ['liked', 'shared', 'visited']

There is one more method that could be in use, HashTable#all

let hash = db.hash('counters').all()
// => { liked: 1, shared: 2, visited: 0 }

Storage

Storage is made to be abstract - so you could pass a 'class' and store or load data.

const db = new Database({ storage: new Memory() })

this is the default storage. In practice everything is stored into javascript runtime object. When you application restat the data is lost.

There are few storages that are available

• Memory Storage
• LocalFile Storage
• *LocalStorage (Browser only)
• *MongoDB Storage

NOTE Storages with a star are not implemented yet.

Every storage have implement few methods so it could be used. Storage#load, Storage#save, Storage#export

Schemes

Schemes are a way to extend the Collection & Record on runtime without the need to write on the Database code.

• Statics: are attached to the Collection and are accessible when requesting data or saving it.
• Virtuals: are attached to the Record so they could be fields or way to midify existing fields

All Schems need to know for which collections are they assigned

db.addScheme('users', {
  statics: {
    activeUsers: (collection) => collection.filter((user) => user.status === 'active')
  },
  virtuals: {
    fullname: (record) => `${record.first_name} ${record.last_name}`
  }
})

Now you will have attached activeUsers as method to the Collection

let record = db.collection('users').activeUsers().first()
 
// and
 
let fullname = record.fullname()
// => John Doe

Test

All test are writen with Jest and are located into __test__ directory.

If you have jest installed globaly run:

$ jest

or you could use NPM for that

$ npm run test

NOTE: jest is development dependancy

Compile

To compile the source code into single file to be used outside the Node, we use webpack for the task.

Again if you have webpack installed globaly try:

$ webpack

or ask NPM to do it for you

$ npm run build

You will get new directory dist with bundle source as a library to use inside browser.

Keep in mind that some part of the Storages are not competable inside browser. For example, FileStorage is only for NodeJS.