Kstor

Key value store for configs or simple local databases. Includes file encryption as a deterent to users modifying your config.

Install

$ npm install kstor

Usage

Using ES6

import { KStor } from 'kstor';
const defaults = {
  name: 'app',
  description: 'My application description.',
  version: '1.0.0',
  keywords: [
    'todos',
    'notes',
    'messages'
  ],
  author: {
    name: 'Milton Waddams',
    email: '[e-mail]'
  }
};
const store = new KStor('myconfig', defaults);
// or new KStor({ /* options here */}, defaults);
 
// Getting a value.
// returns > 'app'
const name = store.get('name');
 
// Setting a value.
store.set('version', '1.0.1');
 
// Getting a nested value from indexed array.
// returns > 'notes'
const keyword = store.get('keywords[1]');
 
// Getting nested value from object.
const email = store.get('author.email');
 
// Check if has value.
// returns > true
const desc = store.has('description');

Storage Paths

The storage path for your config is very flexible. Here are the majority of examples you might encounter.

APP_NAME denotes the directory name of your module or the package.json name of your module. HOME denotes the home directory for your system. For example on mac /Users/YOUR_NAME.

Name	Directory	Result
undefined	undefined	/$HOME/.kstor/APP_NAME/config.json
custom	undefined	/$HOME/.kstor/APP_NAME/custom.json
.customrc	undefined	/$HOME/.kstor/APP_NAME/.customrc
mydir/conf.json	undefined	/$HOME/.kstor/mydir/conf.json
conf.json	./.configs	./.configs/conf.json (basically relative to local dir)
conf.json	/absolute/path	/absolute/path/conf.json

Options

For most use cases you will not need to set any options. By default the "name" and "dir" options are set automatically. When "dir" is specified the default directory is overriden.

By default configs are saved to "$HOME/kstor/configs". The file name will be your specified "name" option or the name of the directory from which you instantiated.

name

Filename when not specified is named as your_directory_name.json

Type	String
Default	null

dir

Dir when not specified defaults to $HOME/kstor/configs

Type	String
Default	null

entrypoint

When an entrypoint is specified the store is mapped to this key. There are use cases where this can be handy.

const defaults = {
  blogs: {
    blog1: { /* props here */ },
    blog2: { /* props here */ }
  }
}
const options = {
  entrypoint: 'blogs'
}

Which would result in your store essentially being the following data structure, allowing your gets and sets to ignore the top level "blogs" property key.

// Your store basically thinks or sees this even
// though the entire structure is still present.
const result = {
    blog1: { /* props here */ },
    blog2: { /* props here */ }
}

Type	String
Default	null

encryptionKey

When an encryption key is specified it will encrypt your config. Since you are passing your encrypting key in plain text this doesn't secure the file however if the typical user were to open the config it deters them from making changes.

Type	String
Default	null

transform

When data is loaded you can run the data through a transform which is useful for ensuring types. You must return a value.

// IMPORTANT: your data structure may be different!!
 
// Ensure date is of type Date.
const options2 = {
  transform: (k, v) => {
    for (const key in v) {
      if (key === 'date' && !(v[key] instanceof Date))
        v[key] = new Date(v[key]);
    }
    return v;
  }
}

Arguments	(key: string, value: any)
Returns	any

API

has

Checks if config has a given property.

Arguments	(key: string)
Returns	any

get

Gets a value from the given by property path with optionally passing a default value to be set.

Arguments	(key: string, def?: any)
Returns	any

set

Sets a value by property path or iterates an object setting each property.

Arguments	(key: string | object, value?: any)
Returns	KStor

del

Deletes a key from the config.

Arguments	(key: string)
Returns	KStor

clear

Clears the config to an empty object.

Arguments	()
Returns	KStor

snapshot

Creates and returns a clone of your config.

Arguments	()
Returns	object

db (get)

Gets the entire config using getter.

const data = this.db;

Getter
Returns	object

db (set)

Sets the entire config using setter.

this.db = { /* your new object */ }

Setter
Returns	object

size

Returns the size of the configuration.

const defaults = {
  name: 'app',
  description: 'My application description.',
  version: '1.0.0',
  keywords: [
    'todos',
    'notes',
    'messages'
  ],
  author: {
    name: 'Milton Waddams',
    email: '[e-mail]'
  }
}
 
// In the above size would be 5
// as it counts only the top
// level keys.
const size = store.size;

Getter
Returns	number

iterable

Gets an iterable instance for performing forEach etc... See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators

The KStor instance is also an iterable class, hence you can perform for of operations as well.

// Consider this data structure.
const teams = {
  jets: { city: 'New York' },
  eagles: { city: 'Philadelphia' },
  patriots: { city: 'New England' }
};
 
for(const item of store) {
  const key = item.key // this would be: jets, eagles, patriots.
  const value = item.value // would be each object ex: { city: 'New York' }
}
 
// OR
const iterator = [...store];
 
iterator.forEach(function(item) {
  // do something.
});

Getter
Returns	Iterable

Docs

See https://blujedis.github.io/kstor/

Change

See CHANGE.md

License

See LICENSE.md