icecave

IceCave DB

A lightweight flat file storage system for nodejs.

Query using JSON schema and update using JSON patch.

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()