.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 🔐

  .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>