noop(); pop(); map();

    kstor
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.10 • Public • Published

    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: 'mwaddams@mail.com'
      }
    };
    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.

    NameDirectoryResult
    undefinedundefined/$HOME/.kstor/APP_NAME/config.json
    customundefined/$HOME/.kstor/APP_NAME/custom.json
    .customrcundefined/$HOME/.kstor/APP_NAME/.customrc
    mydir/conf.jsonundefined/$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

    TypeString
    Defaultnull

    dir

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

    TypeString
    Defaultnull

    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 */ }
    }
    TypeString
    Defaultnull

    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.

    TypeString
    Defaultnull

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

    API

    has

    Checks if config has a given property.

    Arguments(key: string)
    Returnsany

    get

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

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

    set

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

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

    del

    Deletes a key from the config.

    Arguments(key: string)
    ReturnsKStor

    clear

    Clears the config to an empty object.

    Arguments()
    ReturnsKStor

    snapshot

    Creates and returns a clone of your config.

    Arguments()
    Returnsobject

    db (get)

    Gets the entire config using getter.

    const data = this.db;
    Getter
    Returnsobject

    db (set)

    Sets the entire config using setter.

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

    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: 'mwaddams@mail.com'
      }
    }
     
    // In the above size would be 5
    // as it counts only the top
    // level keys.
    const size = store.size;
    Getter
    Returnsnumber

    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
    ReturnsIterable

    Docs

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

    Change

    See CHANGE.md

    License

    See LICENSE.md

    Keywords

    none

    Install

    npm i kstor

    DownloadsWeekly Downloads

    5

    Version

    1.0.10

    License

    ISC

    Unpacked Size

    707 kB

    Total Files

    53

    Last publish

    Collaborators

    • blujedis
    • origin1tech