conf/dist/source/index.d.ts

Simple config handling for your app or module

import { type OnDidChangeCallback, type Options, type Unsubscribe, type OnDidAnyChangeCallback, type DotNotationKeyOf, type DotNotationValueOf, type DefaultsOf, type ArrayItemsOf } from './types.js';
export default class Conf<T extends Record<string, any> = Record<string, unknown>> implements Iterable<[keyof T, T[keyof T]]> {
    #private;
    /**
    Get the path to the config file.
    */
    readonly path: string;
    /**
    Dispatches a `change` event on every write of this instance, and when the `watch` option reports a change to the config file. `onDidChange()` and `onDidAnyChange()` listen on it, and you can also listen to it directly.
    */
    readonly events: EventTarget;
    constructor(partialOptions?: Readonly<Partial<Options<T>>>);
    /**
    Get an item.

    @param key - The key of the item to get.
    @param defaultValue - The default value if the item does not exist.

    Tip: To get all items, see `.store`.
    */
    get<Key extends keyof T>(key: Key): T[Key];
    get<Key extends keyof T>(key: Key, defaultValue: Exclude<T[Key], undefined>): Exclude<T[Key], undefined>;
    get<Key extends DotNotationKeyOf<T>>(key: Key): DotNotationValueOf<T, Key>;
    get<Key extends DotNotationKeyOf<T>>(key: Key, defaultValue: Exclude<DotNotationValueOf<T, Key>, undefined>): Exclude<DotNotationValueOf<T, Key>, undefined>;
    get<Key extends string, Value = unknown>(key: Exclude<Key, DotNotationKeyOf<T>>, defaultValue?: Value): Value;
    /**
    Set an item or multiple items at once.

    @param key - The key of the item to set. You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties. Or an object of items to set at once, where each key replaces the whole value it names, and with dot notation a key can be a path, such as `{'foo.bar': 1}`.
    @param value - Must be JSON serializable. Trying to set a value of type `undefined`, `function`, or `symbol` will result in a `TypeError`, and so will a `bigint` unless you use a custom `serialize`.
    */
    set<Key extends keyof T>(key: Key, value: Exclude<T[Key], undefined>): void;
    set<Key extends DotNotationKeyOf<T>>(key: Key, value: Exclude<DotNotationValueOf<T, Key>, undefined>): void;
    set<Key extends string>(key: Key & (string extends Key ? Key : Exclude<Key, DotNotationKeyOf<T>>), value: unknown): void;
    set(object: DefaultsOf<T>): void;
    /**
    Check if an item exists.

    @param key - The key of the item to check.
    */
    has<Key extends keyof T>(key: Key): boolean;
    has<Key extends DotNotationKeyOf<T>>(key: Key): boolean;
    /**
    Append an item to an array.

    If the key doesn't exist, it will be created as an array. If the key exists and is not an array, a `TypeError` will be thrown.

    The `value` must be JSON serializable. Trying to set a value of type `undefined`, `function`, or `symbol` will result in a `TypeError`, and so will a `bigint` unless you use a custom `serialize`.

    @param key - The key of the array to append to. You can use [dot-notation](https://github.com/sindresorhus/dot-prop) to access nested properties.
    @param value - The item to append. Must be JSON serializable.

    @example
    ```
    config.set('items', [{name: 'foo'}]);
    config.appendToArray('items', {name: 'bar'});
    console.log(config.get('items'));
    //=> [{name: 'foo'}, {name: 'bar'}]

    // Creates array if key doesn't exist
    config.appendToArray('newItems', 'first');
    console.log(config.get('newItems'));
    //=> ['first']
    ```
    */
    appendToArray<Key extends keyof T>(key: Key, value: ArrayItemsOf<T[Key]>): void;
    appendToArray<Key extends DotNotationKeyOf<T>>(key: Key, value: ArrayItemsOf<DotNotationValueOf<T, Key>>): void;
    /**
    Reset items to their default values, as defined by the `defaults` or `schema` option. The `default` values of the `schema` option are not used when `ajvOptions.useDefaults` is `false`.

    With dot notation, schema defaults below an optional object with no default of its own are unavailable to `reset()` when a parent default omits that object. Include the object in the parent default to reset its descendants individually.

    @see `clear()` to reset all items.

    @param keys - The keys of the items to reset.
    */
    reset<Key extends keyof T>(...keys: Key[]): void;
    reset<Key extends DotNotationKeyOf<T>>(...keys: Key[]): void;
    /**
    Delete an item.

    @param key - The key of the item to delete.
    */
    delete<Key extends keyof T>(key: Key): void;
    delete<Key extends DotNotationKeyOf<T>>(key: Key): void;
    /**
    Delete all items.

    This resets known items to their default values, if defined by the `defaults` or `schema` option. The `default` values of the `schema` option are not used when `ajvOptions.useDefaults` is `false`.
    */
    clear(): void;
    /**
    Watches the given `key`, calling `callback` on any changes.

    A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.

    @param key - The key to watch.
    @param 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 unsubscribes when called.

    @example
    ```
    const unsubscribe = config.onDidChange(key, callback);

    unsubscribe();
    ```
    */
    onDidChange<Key extends keyof T>(key: Key, callback: OnDidChangeCallback<T[Key]>): Unsubscribe;
    onDidChange<Key extends DotNotationKeyOf<T>>(key: Key, callback: OnDidChangeCallback<DotNotationValueOf<T, Key>>): Unsubscribe;
    /**
    Watches the whole config object, calling `callback` on any changes.

    A change noticed while the config file cannot be read, for example while another process is writing it, is not reported.

    `oldValue` and `newValue` will be the config object before and after the change, respectively. You must compare `oldValue` to `newValue` to find out what changed.

    @param callback - A callback function that is called on any changes.
    @returns A function that unsubscribes when called.

    @example
    ```
    const unsubscribe = config.onDidAnyChange(callback);

    unsubscribe();
    ```
    */
    onDidAnyChange(callback: OnDidAnyChangeCallback<T>): Unsubscribe;
    /**
    Get the item count.
    */
    get size(): number;
    /**
    Get all the config as an object or replace the current config with an object.

    @example
    ```
    console.log(config.store);
    //=> [Object: null prototype] {name: 'John', age: 30}
    ```

    Unlike `set()`, a whole-store write drops a function or a symbol, like `JSON.stringify` does, instead of throwing. A `bigint` still throws, unless you use a custom `serialize`.

    @example
    ```
    config.store = {
        hello: 'world'
    };
    ```
    */
    get store(): T;
    set store(value: T);
    [Symbol.iterator](): IterableIterator<[keyof T, T[keyof T]]>;
    /**
    Close the file watcher if one exists. This is useful in tests to prevent the process from hanging.
    */
    _closeWatcher(): void;
}
export type { Options, Schema } from './types.js';