KeyValues Storage

Appearance

Class: KeyValues ​

KeyValues is a class that provides a simple key-value storage system. It allows you to set, get, check existence, and remove key-value pairs in a JSON file. It supports nested keys and complex data types, and provides both asynchronous and synchronous methods

It is designed to be used in Node.js applications and can be easily configured to use a custom directory and file name for storing key-value pairs.

Author ​

Heliomar Marques

Example ​

ts
// Create a new instance of KeyValues with custom options
const keyValues = new KeyValues({
  fileName: 'config.json',
  prettify: true
});

// Set a key-value pair
await keyValues.set('color.name', 'sapphire');

// Get the value at a specific key path
const value = await keyValues.get('color.name');

// Check if a key path exists
const exists = await keyValues.has('color.name');

// Remove a key-value pair
await keyValues.unset('color.name');

Constructors ​

Constructor ​

ts
new KeyValues(options?): KeyValues;

Sets the configuration for KeyValues Storage's. To reset to defaults, use [[reset|reset()]].

js
Defaults:
    {
      atomicSave: true,
      fileName: 'keyvalues.json',
      numSpaces: 2,
      prettify: false
    }

Parameters ​

options? ​

Partial<Options>

Options The custom configuration to use.

Returns ​

KeyValues

Example ​

Update the filename to config.json and prettify the output.

js
    new KeyValues({
      fileName: 'config.json',
      prettify: true
    });

Methods ​

file() ​

ts
file(): string;

Returns the path to the json file.

In general, the json file is stored in then install location of your app's user data directory in a file called keyvalues.json. The default user data directory varies by system.

  • macOS - ~/Library/Application\ Support/<Your App>
  • Windows - %LOCALAPPDATA%/PROGRAMS/<Your App>
  • Linux - Either $XDG_CONFIG_HOME/<Your App> or ~/.config/<Your App>

Although it is not recommended, you may change the name or location of the keyvalues file using

new KeyValye({dir: 'newpath'})

Returns ​

string

The path to the keyvalues file. *

Example ​

Get the path to the keyvalues file.

js
    keyValues.file();
    // => c:/users/<userprofile>/appdata/local/programs/<AppName>/keyvalues.json

get() ​

Call Signature ​

ts
get<T>(): Promise<T>;

Gets all key values. For sync, use [[getSync|getSync()]].

Type Parameters ​
T ​

T extends valueTypes

Returns ​

Promise<T>

A promise which resolves with all key values.

Example ​

Gets all key values.

js
    const obj = await get();

Call Signature ​

ts
get<T>(keyPath): Promise<T>;

Gets the value at the given key path. For sync, use [[getSync|getSync()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
keyPath ​

KeyPath

The key path of the property.

Returns ​

Promise<T>

A promise which resolves with the value at the given key path.

Examples ​

Get the value at color.name.

js
    // Given:
    {
       "color": {
         "name": "cerulean",
         "code": {
           "rgb": [0, 179, 230],
           "hex": "#003BE6"
         }
       }
    }

    const value = await keyValues.get('color.name');
    // => "cerulean"

Get the value at color.code.hex.

js
    const hex = await keyValues.get('color.color.hex');
    // => "#003BE6"

Get the value at color.hue.

js
    const h = 'hue';
    const value = await keyValues.get(['color', h]);
    // => undefined

Get the value at color.code.rgb[1].

js
    const h = 'hue';
    const value = await keyValues.get('color.code.rgb[1]');
    // => 179

getSync() ​

Call Signature ​

ts
getSync<T>(): T;

Gets all key values. For async, use [[get|get()]].

Type Parameters ​
T ​

T extends valueTypes

Returns ​

T

All key values.

Example ​

Gets all key values.

js
    const obj = getSync();

Call Signature ​

ts
getSync<T>(keyPath): T;

Gets the value at the given key path. For async, use [[get|get()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
keyPath ​

KeyPath

The key path of the property.

Returns ​

T

The value at the given key path.

Examples ​

Get the value at color.name.

js
    // Given:
    {
       "color": {
         "name": "cerulean",
         "code": {
           "rgb": [0, 179, 230],
           "hex": "#003BE6"
         }
       }
    }

    const value = keyValues.getSync('color.name');
    // => "cerulean"

Get the value at color.code.hex.

js
    const hex = keyValues.getSync('color.color.hex');
    // => "#003BE6"

Get the value at color.hue.

js
    const h = 'hue';
    const value = keyValues.getSync(['color', h]);
    // => undefined

Get the value at color.code.rgb[1].

js
    const h = 'hue';
    const value = keyValues.getSync('color.code.rgb[1]');
    // => 179

has() ​

ts
has(keyPath): Promise<boolean>;

Checks if the given key path exists. For sync, use [[hasSync|hasSync()]].

Parameters ​

keyPath ​

KeyPath

The key path to check.

Returns ​

Promise<boolean>

A promise which resolves to true if the keyPath exists, else false.

Examples ​

Check if the value at color.name exists.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    const exists = await keyValues.has('color.name');
    // => true

Check if the value at color.hue exists.

js
    const h = 'hue';
    const exists = await keyValues.has(['color', h]);
    // => false

Check if the value at color.code.rgb[1] exists.

js
    const exists = await keyValues.has(color.code.rgb[1]);
    // => true

hasSync() ​

ts
hasSync(keyPath): boolean;

Checks if the given key path exists. For async, use [[hasSync|hasSync()]].

Parameters ​

keyPath ​

KeyPath

The key path to check.

Returns ​

boolean

true if the keyPath exists, else false.

Examples ​

Check if the value at color.name exists.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    const exists = keyValues.hasSync('color.name');
    // => true

Check if the value at color.hue exists.

js
    const h = 'hue';
    const exists = keyValues.hasSync(['color', h]);
    // => false

Check if the value at color.code.rgb[1] exists.

js
    const exists = keyValues.hasSync(color.code.rgb[1]);
    // => true

reset() ​

ts
reset(): void;

Resets the KeyValues Storage's configuration to defaults.

Returns ​

void

Example ​

Reset configuration to defaults.

js
    keyValues.reset();

set() ​

Call Signature ​

ts
set<T>(obj): Promise<void>;

Sets all key values. For sync, use [[setSync|setSync()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
obj ​

Types<T>

The new key value.

Returns ​

Promise<void>

A promise which resolves when the value have been set.

Example ​

Set all key values.

js
    await keyValues.set({ aqpw: 'nice' });

Call Signature ​

ts
set<T>(keyPath, value): Promise<void>;

Sets the value at the given key path. For sync, use [[setSync|setSync()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
keyPath ​

KeyPath

The key path of the property.

value ​

T

The value to set.

Returns ​

Promise<void>

A promise which resolves when the setting has been set.

Examples ​

Change the value at color.name to sapphire.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    await keyValues.set('color.name', 'sapphire');

Set the value of color.hue to blue-ish.

js
    const h = 'hue';
    await keyValues.set(['color', h], 'blue-ish);

Change the value of color.code.

js
    await keyValues.set('color.code', {
      rgb: [16, 31, 134],
      hex: '#101F86'
    });

setSync() ​

Call Signature ​

ts
setSync<T>(obj): void;

Sets all key values. For async, use [[set|set()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
obj ​

Types<T>

The new key values.

Returns ​

void

Example ​

Set all key values.

js
    keyValues.setSync({ aqpw: 'nice' });

Call Signature ​

ts
setSync<T>(keyPath, value): void;

Sets the value at the given key path. For async, use [[set|set()]].

Type Parameters ​
T ​

T extends valueTypes

Parameters ​
keyPath ​

KeyPath

The key path of the property.

value ​

T

The value to set.

Returns ​

void

Examples ​

Change the value at color.name to sapphire.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    keyValues.setSync('color.name', 'sapphire');

Set the value of color.hue to blue-ish.

js
    const h = 'hue';
    keyValues.setSync(['color', h], 'blue-ish);

Change the value of color.code.

js
    keyValues.setSync('color.code', {
      rgb: [16, 31, 134],
      hex: '#101F86'
    });

unset() ​

Call Signature ​

ts
unset(): Promise<boolean>;

Unsets all key values. For sync, use [unsetSync()].

Returns ​

Promise<boolean>

A promise which resolves when the key values have been unset.

Example ​

Unsets all key values.

js
    await keyValues.unset();

Call Signature ​

ts
unset(keyPath): Promise<boolean>;

Unsets the property at the given key path. For sync, use [[unsetSync|unsetSync()]].

Parameters ​
keyPath ​

KeyPath

The key path of the property.

Returns ​

Promise<boolean>

A promise which resolves when the setting has been unset.

Examples ​

Unset the property color.name.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    await keyValues.unset('color.name');

    await keyValues.get('color.name');
    // => undefined

Unset the property color.code.rgba[1].

js
    await keyValues.unset('color.code.rgba[1]');

    await keyValues.get('color.code.rgb');
    // => [0, null, 230]

unsetSync() ​

Call Signature ​

ts
unsetSync(): boolean;

Unsets all key values. For async, use [unset()].

Returns ​

boolean

Example ​

Unsets all key values.

js
    keyValues.unsetSync();

Call Signature ​

ts
unsetSync(keyPath): boolean;

Unsets the property at the given key path. For async, use [[unset|unset()]].

Parameters ​
keyPath ​

KeyPath

The key path of the property.

Returns ​

boolean

Examples ​

Unset the property color.name.

js
    // Given:
    //
    // {
    //   "color": {
    //     "name": "cerulean",
    //     "code": {
    //       "rgb": [0, 179, 230],
    //       "hex": "#003BE6"
    //     }
    //   }
    // }

    keyValues.unsetSync('color.name');

    keyValues.getSync('color.name');
    // => undefined

Unset the property color.code.rgba[1].

js
    keyValues.unsetSync('color.code.rgba[1]');

    keyValues.getSync('color.code.rgb');
    // => [0, null, 230]