.pref

Perfect for CLI application user preferences

Out of the box 📦⤵️ easy application encrypted preferences 👍

Highlights

• No configuration needed ❌⚙️
• Everything is configurable ✅⚙️
• Human-readable 🤓 or encrypted 🔐

Install

npm

$ npm install --save dotpref

yarn

$ yarn add dotpref

Usage

Quick start

Out of the box simple key/value store.

import Pref from 'dotpref';

Pref.set('foo', 'bar');
console.log(Pref.get('foo'));
//=> 'bar'

Pref.set('foo', { bar: 'baz' });
console.log(Pref.get('foo'));
//=> '{ bar: "baz" } '

API

Pref

The default export of the dotpref module is a singleton instance with a default configuration.

import Pref from 'dotpref';

createPref

Creates a custom instance of dotpref with custom configuration. This method can be used if you need multiple configurations.

import { createPref } from 'dotpref';

Instance

.get

Type: (key: string) => string

Get the value assigned to key in the state.

.set

Type: (key: string, value: string) => void

Set the value of key in the state. The value must serializable by the instance's serializer. For example, using the default serializer (JSON), setting a value of type undefined, function, or symbol will result in a TypeError.

.reset

Type: (key: string) => void

Reset the value assigned to key to the default state.

.write

Type: () => void

Explicitly write to disk.

.read

Type: () => void

Explicitly read from disk to state.

.filePath

Type: readonly string

Readonly absolute path to the preference file stored on disk. This property will exist even if the preference file does not.

getDefaultCrypto

Options

defaults

Type: state

An object specifying the default values of the preference state. If preferences are found, they will override the defaults in the state. If no preferences are found, defaults will be used – state will not be written to disk upon creation. Default: {}.

name

Type: string

The name of your project. This value will be used to build the filePath of the preference file stored on disk. Default: the name property of your package.json.

filename

Type: string

The filename of the preference file stored on disk. Default: config.pref

dirPath

Type: string

Absolute path determining where the preferences should be stored on disk. Default: <system config>/<name> where <system config> is the User's default system config path and <name> is the name property configuration property;

serializer

Type: state => string

A function that specifies how the state should be serialized when written to disk. Default: JSON.stringify.

deserializer

Type: string => state

The reverse of serializer. A function that specifies how the state should be deserialized when read from disk. Default: JSON.parse.

encoder

Type: string => string

A function that specifies how the state should be encrypted. Default: getDefaultCrypto.encrypt.

decoder

Type: string => string

A function that specifies how the state should be decrypted. Default: getDefaultCrypto.decrypt.

setter

Type: (state, key, value) => void

A function that takes the existing state, the key, and the value and returns a new state to be saved to disk. The state will be saved to disk if the equality function returns false. Default: (state, key, value) => { ...state, [key]: value }.

getter

Type: (state, key) => value

Reverse of setter. A function that takes the existing state and the key and returns the value. Default: (state, key) => state[key].

equality

Type: boolean | (state, newState) => boolean

Determines the equality of the old state and the new state. This method is used to determine if the state has changed since the last write. If set to true the state will write to disk on every set. When set to false the state will never write to disk on set and therefore must explicitly be written via write.

Config Paths

For each OS below <home> is calculated using NodeJS' os.homedir().

• macOS: <home>/Library/Preferences/<name>
• Windows: <home>/AppData/Roaming/<name>/Config
• Linux: <home>/.config/<name> or $XDG_CONFIG_HOME/<name>