LucianBuzzo/icecave

Fast and simple flat file storage for small node js projects

IceCave DB

A lightweight flat file storage system for nodejs.

Highlights

• JSON-centric: Query using JSON schema and update using JSON patch
• Lightweight: Minimal configuration means no deployment headaches
• Portable: Usable everywhere a node runtime is available

Motivation

IceCave is designed for use in applications where relatively small amounts of data (less than 10000 elements) need to be stored persistently and a dedicated external database service is impractical or overkill. IceCave stores data in-memory and periodically dumps it's contents to a JSON file. On startup it will read this file location and load any data found there.

Usage

Below is an example how to use IceCave DB:

const IceCave = require('icecave');

// Create a new storage instance that will be written to the directory './data-directory'
const db = new IceCave({
  directory: __dirname + '/data-directory',
})

// Add elements to the database
db.insert({ id: 1, name: 'Abra' })
db.insert({ id: 2, name: 'Bulbasaur' })
db.insert({ id: 3, name: 'Caterpie' })

// Find an element
const user = db.query({
  type: 'object',
  properties: {
    id: {
      type: 'string',
      const: 2
    }
  }
}) // --> { id: 2, name: 'Bulbasaur' }

// Update an element
const user = db.update({
  type: 'object',
  properties: {
    id: {
      type: 'string',
      const: 2
    }
  }
}, [
  { op: 'replace', path: '/name', value: 'Beedrill' },
  { op: 'add', path: '/type', value: [ 'bug', 'poison' ] }
]) // --> { id: 2, name: 'Beedrill', type: [ 'bug', 'poison' ] }

// Delete an element
const user = db.delete({
  type: 'object',
  properties: {
    id: {
      type: 'string',
      const: 3
    }
  }
})

Documentation

IceCave instance

Kind: global class Summary: Create an instance of IceCave Access: public

• IceCave
  • new IceCave(config)
  • .dump() ⇒ Promise.<String>
  • .insert(element)
  • .delete(query)
  • .filter(query) ⇒ Array
  • .update(query, patch)
  • .shutdown() ⇒ Promise

new IceCave(config)

Param	Type	Default	Description
config	Object		Configuration object
[config.directory]	String	./icecave-data	The directory where icecave data is stored
[config.name]	String	icecave	The name of this instance
[config.memoryOnly]	Boolean	false	Set to true to stop the db from being written to the filesystem

Example

const db = new IceCave()

iceCave.dump() ⇒ Promise.<String>

Dumps the store to a JSON file and shuts down the DB

Kind: instance method of IceCave Summary: Writes the in memory storage to a JSON file. Returns: Promise.<String> - The path of the stored JSON file Access: public Example

const db = new IceCave()

await db.dump()

iceCave.insert(element)

Insert an element into the database

Kind: instance method of IceCave Access: public

Param	Type	Description
element	Object	The element to insert

Example

const db = new IceCave()

db.insert({
  foo: 'bar',
  baz: 'buzz'
})

iceCave.delete(query)

Delete elements in the store the match a JSON schema.

Kind: instance method of IceCave Access: public

Param	Type	Description
query	Object	The JSON schema to validate against

Example

const db = new IceCave()

db.insert({
  foo: 'bar',
  baz: 'buzz'
})

db.delete({
  type: 'object',
  properties: {
    foo: {
      const: 'bar'
    }
  }
})

iceCave.filter(query) ⇒ Array

Retrieve elements in the store that match a JSON schema.

Kind: instance method of IceCave Returns: Array - An array of elements Access: public

Param	Type	Description
query	Object	The JSON schema to validate against

Example

const db = new IceCave()

db.insert({
  foo: 'bar',
  baz: 'buzz'
})

const results = db.filter({
  type: 'object',
  properties: {
    foo: {
      const: 'bar'
    }
  }
})

console.log(results)

iceCave.update(query, patch)

Select elements that match a JSON schema and update them using a JSON patch object.

Kind: instance method of IceCave Summary: Update one or more elements Access: public See: https://tools.ietf.org/html/rfc6902

Param	Type	Description
query	Object	The JSON schema to validate against
patch	Object	An RFC 6902 JSON patch object

Example

const db = new IceCave()

db.insert({
  foo: 'bar',
  baz: 'buzz'
})

db.update({
  type: 'object',
  properties: {
    foo: {
      const: 'bar'
    }
  }
},
[
  { "op": "replace", "path": "/baz", "value": "boo" }
])

iceCave.shutdown() ⇒ Promise

Dumps the store to a JSON file and shuts down the DB

Kind: instance method of IceCave Summary: Shutdown the database Access: public Example

const db = new IceCave()

await db.shutdown()