keeparray

A zero dependency tiny datastore/database that looks and works like an array. Use regular array methods, while KeepArray automatically tracks changes and saves a JSON file for you.

Install

npm install keeparray

const KeepArray = require('keeparray')

Usage

Create a KeepArray

Create a datastore with KeepArray.create()

let data = KeepArray.create('data-table')

That's it, you've created a KeepArray datastore!

Use your array

You can use any array method to manipulate your datastore:

// Create a datastore
let data = KeepArray.create('fruit')
 
// Example array methods
data.push('apple', 'banana', 'cherry')  
data = data.map(fruit => fruit.toUpperCase()) // Returns a connected KeepArray
 
console.log(data) // ['APPLE', 'BANANA', 'CHERRY']

All array methods that return an array are supported. By default, the code above would save a JSON datastore to datastore/fruit.json

Connect to an existing KeepArray

Connect to an existing datastore with KeepArray.connect()

// Connect to a datastore
let data = KeepArray.connect('names')
 
// Example array methods
const list = ['Adam', 'Ben', 'Christian']
data.push(...list)
data = data.filter(name => name.length < 5) // Returns a connected KeepArray
 
console.log(data) // ['Adam', 'Ben']

By default, connect() will create a new datastore if one can not be found.

Write to disk

Force a datastore to be immediately written to disk with KeepArray.write()

// Create new store
let data = KeepArray.create('places', ['London', 'Paris', 'Berlin'])
 
// Instantly write to disk
KeepArray.write('places')

Modify default options

Modify the default options with KeepArray.options()

// Example
KeepArray.options({
  defaultPath: 'database',
  writeTime: 2
})

More info on options at the bottom of the page.

API

Methods

Name	Description	Syntax	Parameters
KeepArray.create()	Creates a new KeepArray datastore, and returns the linked array.	.create(name, array, path)	name (String, required) The name of the new datastore. array (Array, optional) The contents of the newly created array. path (String, optional) The directory of the new datastore.
KeepArray.connect()	Loads a KeepArray datastore and returns the linked array.	.connect(name, canCreate, path)	name (String, required) The name of the existing datastore. canCreate (Boolean, optional) Allow creation of a new KeepArray, if datastore does not exist. path (String, optional) The directory of the existing datastore.
KeepArray.disconnect()	Disconnects an array from KeepArray, and returns it as a regular array.	.disconnect(name, path)	name (String, required) The name of the connected datastore. path (String, optional) The directory of the connected datastore.
KeepArray.write()	Forces the KeepArray to be written to disk. Returns true if successful, false if not.	.write(name, path)	name (String, required) The name of the connected datastore. path (String, optional) The directory of the datastore.
KeepArray.exists()	Checks if KeepArray datastore exists. Returns true if it exists, false if not.	.exists(name, path)	name (String, required) The name of the datastore. path (String, optional) The directory of the datastore.
KeepArray.delete()	Permanently deletes a KeepArray datastore. Returns true if it exists, false if not.	.delete(name, path)	name (String, required) The name of the datastore. path (String, optional) The directory of the datastore.
KeepArray.options()	Modifiy the default options. The input is merged with the default options. Returns all options.	.options(optionObject)	optionObject (Object, optional) The options applied (see section below).

Options

Name	Description	Default
defaultPath	Default directory of the datastore.	'datastore'
connectCanCreate	Specifies whether KeepArray.connect() will create a new datastore (instead of throwing an error) when an existing KeepArray is not found.	true
saveOnExit	Automatically write all open KeepArray datastores to disk when Node is exited.	true
saveOnCrash	Automatically write all open KeepArray datastores to disk on unhandledExceptions and unhandledRejections.	false
writeTime	Debounce time. Minimum time (in seconds) between disk writes, if a KeepArray has changed.	5
delayTime	Throttle time. Time (in seconds) before saving to disk, after a KeepArray change.	1
loop	Use debouncing and throttling to limit disk writes (recommended to leave this true).	true