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

import { KeyValues } from '@heliomarpm/kvs';

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

// 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');
// output: 'sapphire'

// Get the nested key
const value = await keyValues.get('color');
// output: { name: 'sapphire' }

// Get all
const value = await keyValues.get();
// output: { color: { name: 'sapphire' } }

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

new KeyValues(options?): KeyValues;

Sets the configuration for KeyValues Storage's.

To reset to defaults, use [reset()].

Defaults:
{
	atomicSave: true,
	dir: 'localdb',
	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.

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

Auxiliary Methods

file()

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.

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

---

resetOptions()

resetOptions(): void;

Resets the KeyValues Storage's configuration to defaults.

Returns

void

Example

Reset configuration to defaults.

keyValues.resetOptions();

See

Options

Get Methods

get()

Call Signature

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

Gets all key values.

For sync method, use [getSync()].

Type Parameters

T

T extends ValueType

Returns

Promise<T>

A promise which resolves with all key values.

Example

Gets all key values.

const obj = await get();

Call Signature

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

Gets the value at the given key path.

For sync method, use [getSync()].

Type Parameters

T

T extends ValueType

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.

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

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

Get the value not existent at color.hue.

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

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

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

---

getSync()

Call Signature

getSync<T>(): T;

Gets all key values.

For async method, use [get()].

Type Parameters

T

T extends ValueType

Returns

T

All key values.

Example

Gets all key values.

const obj = getSync();

Call Signature

getSync<T>(keyPath): T;

Gets the value at the given key path.

For async method, use [get()].

Type Parameters

T

T extends ValueType

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.

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

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

Get the value at color.hue.

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

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

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

Get all values

 const values = keyValues.getSync();

Has Methods

has()

has(keyPath): Promise<boolean>;

Checks if the given key path exists.

For sync method, use [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.

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

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

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

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

---

hasSync()

hasSync(keyPath): boolean;

Checks if the given key path exists.

For async method, use [has()].

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.

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

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

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

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

Set Methods

set()

Call Signature

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

Sets all key values.

For sync method, use [setSync()].

Type Parameters

T

T extends ValueType

Parameters

obj

RecordType<T>

The new key value.

Returns

Promise<void>

A promise which resolves when the value have been set.

Example

Set all key values.

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

Call Signature

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

Sets the value at the given key path.

For sync method, use [setSync()].

Type Parameters

T

T extends ValueType

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.

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

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

Set the value of color.hue to bluish.

await keyValues.set(['color', 'hue'], 'bluish');

Change the value of color.code.

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

---

setSync()

Call Signature

setSync<T>(obj): void;

Sets all key values.

For async method, use [set()].

Type Parameters

T

T extends ValueType

Parameters

obj

RecordType<T>

The new key values.

Returns

void

Example

Set all key values.

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

Call Signature

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

Sets the value at the given key path.

For async method, use [set()].

Type Parameters

T

T extends ValueType

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.

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

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

Set the value of color.hue to bluish.

keyValues.setSync(['color', 'hue'], 'bluish);

Change the value of color.code.

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

Unset Methods

unset()

Call Signature

unset(): Promise<boolean>;

Unsets all key values.

For sync method, use [unsetSync()].

Returns

Promise<boolean>

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

Example

Unsets all key values.

await keyValues.unset();
await keyValues.get();
// => undefined

Call Signature

unset(keyPath): Promise<boolean>;

Unsets the property at the given key path.

For sync method, use [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.

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

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

---

unsetSync()

Call Signature

unsetSync(): boolean;

Unsets all key values.

For async method, use [unset()].

Returns

boolean

Example

Unsets all key values.

keyValues.unsetSync();

Call Signature

unsetSync(keyPath): boolean;

Unsets the property at the given key path.

For async method, use [unset()].

Parameters

keyPath

KeyPath

The key path of the property.

Returns

boolean

Examples

Unset the property color.name.

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

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