icecave
v2.0.0
Published
Fast and simple flat file storage for small projects
Downloads
13
Maintainers
Readme
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()