conf

  • Version 10.0.3
  • Published
  • 46.2 kB
  • 10 dependencies
  • MIT license

Install

npm i conf
yarn add conf
pnpm add conf

Overview

Simple config handling for your app or module

Index

Classes

class Conf

class Conf<T extends Record<string, any> = Record<string, unknown>>
implements Iterable<[keyof T, T[keyof T]]> {}

    constructor

    constructor(partialOptions?: Readonly<Partial<Options<T>>>);

      property events

      readonly events: any;

        property path

        readonly path: string;

          property size

          readonly size: number;

            property store

            store: Record<string, any>;

              method [Symbol.iterator]

              [Symbol.iterator]: () => IterableIterator<[keyof T, T[keyof T]]>;

                method clear

                clear: () => void;
                • Delete all items.

                  This resets known items to their default values, if defined by the defaults or schema option.

                method delete

                delete: <Key extends keyof T>(key: Key) => void;
                • Delete an item.

                  Parameter key

                  The key of the item to delete.

                method get

                get: {
                <Key extends keyof T>(key: Key): T[Key];
                <Key extends keyof T>(
                key: Key,
                defaultValue: Required<T>[Key]
                ): Required<T>[Key];
                <Key extends string, Value = unknown>(
                key: Exclude<Key, keyof T>,
                defaultValue?: Value
                ): Value;
                };
                • Get an item.

                  Parameter key

                  The key of the item to get.

                  Parameter defaultValue

                  The default value if the item does not exist.

                method has

                has: <Key extends keyof T>(key: Key | string) => boolean;
                • Check if an item exists.

                  Parameter key

                  The key of the item to check.

                method onDidAnyChange

                onDidAnyChange: (callback: OnDidAnyChangeCallback<T>) => Unsubscribe;
                • Watches the whole config object, calling callback on any changes.

                  Parameter callback

                  A callback function that is called on any changes. When a key is first set oldValue will be undefined, and when a key is deleted newValue will be undefined.

                  Returns

                  A function, that when called, will unsubscribe.

                method onDidChange

                onDidChange: <Key extends keyof T>(
                key: Key,
                callback: OnDidChangeCallback<T[Key]>
                ) => Unsubscribe;
                • Watches the given key, calling callback on any changes.

                  Parameter key

                  The key wo watch.

                  Parameter callback

                  A callback function that is called on any changes. When a key is first set oldValue will be undefined, and when a key is deleted newValue will be undefined.

                  Returns

                  A function, that when called, will unsubscribe.

                method reset

                reset: <Key extends keyof T>(...keys: Key[]) => void;
                • Reset items to their default values, as defined by the defaults or schema option.

                  Parameter keys

                  The keys of the items to reset.

                  See Also

                  • clear() to reset all items.

                method set

                set: {
                <Key extends keyof T>(key: Key, value?: T[Key]): void;
                (key: string, value: unknown): void;
                (object: Partial<T>): void;
                };
                • Set an item or multiple items at once.

                  Parameter

                  {key|object} - You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties. Or a hashmap of items to set at once.

                  Parameter value

                  Must be JSON serializable. Trying to set the type undefined, function, or symbol will result in a TypeError.

                Interfaces

                interface Options

                interface Options<T> {}

                  property accessPropertiesByDotNotation

                  readonly accessPropertiesByDotNotation?: boolean;
                  • Access nested properties by dot notation.

                    true

                    Example 1

                    ``` const config = new Conf();

                    config.set({ foo: { bar: { foobar: '🦄' } } });

                    console.log(config.get('foo.bar.foobar')); //=> '🦄' ```

                    Alternatively, you can set this option to false so the whole string would be treated as one key.

                    Example 2

                    ``` const config = new Conf({accessPropertiesByDotNotation: false});

                    config.set({ foo.bar.foobar: '🦄' });

                    console.log(config.get('foo.bar.foobar')); //=> '🦄' ```

                  property clearInvalidConfig

                  clearInvalidConfig?: boolean;
                  • The config is cleared if reading the config file causes a SyntaxError. This is a good behavior for unimportant data, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing.

                    false

                  property configName

                  configName?: string;
                  • Name of the config file (without extension).

                    Useful if you need multiple config files for your app or module. For example, different config files between two major versions.

                    'config'

                  property cwd

                  cwd?: string;
                  • __You most likely don't need this. Please don't use it unless you really have to.__

                    The only use-case I can think of is having the config located in the app directory or on some external storage. Default: System default user [config directory](https://github.com/sindresorhus/env-paths#pathsconfig).

                  property defaults

                  defaults?: Readonly<T>;
                  • Config used if there are no existing config.

                    *Note:** The values in defaults will overwrite the default key in the schema option.

                  property deserialize

                  readonly deserialize?: Deserialize<T>;
                  • Function to deserialize the config object from a UTF-8 string when reading the config file.

                    You would usually not need this, but it could be useful if you want to use a format other than JSON.

                    JSON.parse

                  property encryptionKey

                  encryptionKey?: string | Buffer | NodeJS.TypedArray | DataView;
                  • Note that this is __not intended for security purposes__, since the encryption key would be easily found inside a plain-text Node.js app.

                    Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.

                    It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.

                    When specified, the store will be encrypted using the [aes-256-cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) encryption algorithm.

                  property fileExtension

                  fileExtension?: string;
                  • Extension of the config file.

                    You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.

                    'json'

                  property migrations

                  migrations?: Migrations<T>;
                  • You can use migrations to perform operations to the store whenever a version is changed.

                    The migrations object should consist of a key-value pair of 'version': handler. The version can also be a [semver range](https://github.com/npm/node-semver#ranges).

                    Note: The version the migrations use refers to the __project version__ by default. If you want to change this behavior, specify the projectVersion option.

                    Example 1

                    ``` import Conf = require('conf');

                    const store = new Conf({ migrations: { '0.0.1': store => { store.set('debugPhase', true); }, '1.0.0': store => { store.delete('debugPhase'); store.set('phase', '1.0.0'); }, '1.0.2': store => { store.set('phase', '1.0.2'); }, '>=2.0.0': store => { store.set('phase', '>=2.0.0'); } } }); ```

                  property projectName

                  projectName?: string;
                  • You only need to specify this if you don't have a package.json file in your project or if it doesn't have a name defined within it.

                    Default: The name field in the package.json closest to where conf is imported.

                  property projectSuffix

                  readonly projectSuffix?: string;
                  • __You most likely don't need this. Please don't use it unless you really have to.__

                    Suffix appended to projectName during config file creation to avoid name conflicts with native apps.

                    You can pass an empty string to remove the suffix.

                    For example, on macOS, the config file will be stored in the ~/Library/Preferences/foo-nodejs directory, where foo is the projectName.

                    'nodejs'

                  property projectVersion

                  projectVersion?: string;
                  • You only need to specify this if you don't have a package.json file in your project or if it doesn't have a version defined within it.

                    Default: The name field in the package.json closest to where conf is imported.

                  property schema

                  schema?: Schema<T>;
                  • [JSON Schema](https://json-schema.org) to validate your config data.

                    Under the hood, the JSON Schema validator [ajv](https://github.com/epoberezkin/ajv) is used to validate your config. We use [JSON Schema draft-07](https://json-schema.org/latest/json-schema-validation.html) and support all [validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md) and [formats](https://github.com/epoberezkin/ajv#formats).

                    You should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property. See more [here](https://json-schema.org/understanding-json-schema/reference/object.html#properties).

                    Example 1

                    ``` import Conf = require('conf');

                    const schema = { foo: { type: 'number', maximum: 100, minimum: 1, default: 50 }, bar: { type: 'string', format: 'url' } };

                    const config = new Conf({schema});

                    console.log(config.get('foo')); //=> 50

                    config.set('foo', '1'); // [Error: Config schema violation: foo should be number] ```

                    *Note:** The default value will be overwritten by the defaults option if set.

                  property serialize

                  readonly serialize?: Serialize<T>;
                  • Function to serialize the config object to a UTF-8 string when writing the config file.

                    You would usually not need this, but it could be useful if you want to use a format other than JSON.

                    value => JSON.stringify(value, null, '\t')

                  property watch

                  readonly watch?: boolean;
                  • Watch for any changes in the config file and call the callback for onDidChange or onDidAnyChange if set. This is useful if there are multiple processes changing the same config file.

                    false

                  Type Aliases

                  type Schema

                  type Schema<T> = {
                  [Property in keyof T]: ValueSchema;
                  };

                    Package Files (2)

                    Dependencies (10)

                    Dev Dependencies (16)

                    Peer Dependencies (0)

                    No peer dependencies.

                    Badge

                    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/conf.

                    • Markdown
                      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/conf)
                    • HTML
                      <a href="https://www.jsdocs.io/package/conf"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>