Perseverant

An asynchronous, persistent, localForage inspired, filesystem based storage solution for NodeJS.

Concept

Each key will be stored as regular file with optionally encrypted serialized data.

By default, everything is kept super simple so whatever value will be saved as JSON.

It is possible to create a new instance with a different name, folder, encryption or serialization.

API

Following the meta description of the API.

const perseverant = require('perseverant');
// or import perseverant from 'perseverant';

// by default, the name of the storage is 'global' but
// it is highly suggested to use your own project name instead
const storage = perseverant.createInstance('my-project'):Perseverant

// or ...
const storage = perseverant.createInstance({
  name,       // by default 'global'
  folder,     // by default $HOME/.config/perseverant
  serializer, // by default JSON
  password,   // if provided, it's used to encrypt
  salt        // if there is a password is used as salt
              // by default it's perseverant
}):Perseverant

// retrieve a key (read key file)
storage.getItem(
  key
  [,callback(value || null)]
):Promise<value || null>

// store a key (write key file)
storage.setItem(
  key,
  value
  [, callback(value)]
):Promise<value>

// remove a key (unlink key file)
storage.removeItem(
  key
  [, callback]
):Promise

// clear all keys for the named storage (rm -rf folder and its files)
// WARNING: if you call this on global name, it'll clean it all
storage.clear([callback]):Promise

// returns the length of keys, from 0 to N
storage.length([callback(length)]):Promise<length>

// returns all keys
storage.keys([callback(keys[])]):Promise<keys[]>

Things to consider

This project is not a database replacement, neither a secure way to store credentials, passwords, or any relevant data if you do not provide at least a password.

// insecure!
const storage = require('perseverant');

// secure \o/
const storage = require('perseverant').createInstance({
  name: process.env.APP_NAME,
  password: process.env.APP_SECRET
});

By default, everything is indeed stored as plain JSON, and in a location any other software can reach.

The goal of this project is to provide, specially to NodeJS CLI, a way to persist data in any kind of device.

Technically speaking

• each key is converted into its base64 or encrypted counterpart, and its value stored via JSON.stringify
• if you provide your own serializer, you can also store recursive data or buffers and binaries, currently not supported in core (to keep it simple)