@heliomarpm/kvs NPM

lodash write-file-atomic

Summary

The KeyValues Storage library is a utility for managing key-value pairs and storing them in a JSON file. It provides methods for setting, getting, checking existence, and removing key-value pairs. This document provides an overview of the library and its usage.

Installation

You can install the library using npm or yarn:

npm i @heliomarpm/kvs
# or 
yarn add @heliomarpm/kvs

Example Usage

// Create a new instance of KeyValues with or or without custom options

/**
 * Default Options
 * 
 * {
 *   atomicSave: true,
 *   fileName: 'keyvalues.json',
 *   prettify: false,
 *   numSpaces: 2,
 * }
 */
const kvs = new KeyValues()
-- or --
const kvs = new KeyValues({
  fileName: 'config.json',
  prettify: true
});

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

// Set a key-value
kvs.setSync(['settings', 'language'], "pt-Br");
kvs.getSync(['settings', 'language'])	
// => 'pt-Br'

// Set/Add a key settings
kvs.setSync("settings.default", "en");
kvs.getSync("settings")
// => { "language": "pt-Br", "default": "en" }

kvs.getSync();	
// => { "settings": { "language": "pt-Br", "default": "en" } }

// replace key settings
kvs.setSync("settings", { theme: "dark"});
kvs.getSync("settings")
// => { "theme": "dark" }

// Added a new key-value
kvs.setSync("color", color);
kvs.getSync();
// => { "theme": "dark", "color": { "name": "cerulean", "code": { "rgb": [0, 179, 230], "hex": "#003BE6" } } }

// Replace all key-values
kvs.setSync(color);
kvs.getSync();
// => { "name": "cerulean", "code": { "rgb": [0, 179, 230], "hex": "#003BE6" } }

// Unset a key-value
kvs.unsetSync();
kvs.getSync();
// => {}

// Set a new key-values
kvs.setSync("color", color);
kvs.getSync();	
// => { "color": { "name": "cerulean", "code": { "rgb": [0, 179, 230], "hex": "#003BE6" } } }

kvs.getSync("color.name")
// => "cerulean"

kvs.getSync("color.code.hex")
// => "#003BE6"

kvs.getSync(["color", "code"])
-- or --
kvs.getSync("color.code")
// => { "hex": "#003BE6", "rgb": [0, 179, 230] }

kvs.getSync(["color", "hue"])
// => undefined

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

// Get the value at a specific key path
const value = await kvs.get("color.name");
// => "sapphire"

// Check if a key path exists
const exists = await kvs.has("color.name");
// => true

// Remove a key-value pair
await kvs.unset("color.name");
await kvs.get(); 
// => { "code": { "rgb": [0, 179, 230], "hex": "#003BE6" } }

const exists = kvs.hasSync("color.name");
// => false

kvs.unset().then(() => {
	console.log("All key-value pairs have been removed.");
})

Code Analysis

Main functionalities

Manage key-value pairs and store them in a JSON file
Create one or more instances for different JSON files
Set and get values at specific key paths
Check if a key path exists
Remove key-value pairs

Methods

constructor(options?: Partial<Options>): Initializes a new instance of the KeyValues class with optional custom options.
file(): string: Returns the path to the JSON file.
reset(): void: Resets the configuration of the KeyValues instance to default options.
has(keyPath: KeyPath): Promise<boolean>: Checks if a key path exists asynchronously.
hasSync(keyPath: KeyPath): boolean: Checks if a key path exists synchronously.
get<T extends valueTypes>(keyPath?: KeyPath): Promise<T>: Gets the value at a specific key path asynchronously.
getSync<T extends valueTypes>(keyPath?: KeyPath): T: Gets the value at a specific key path synchronously.
set<T extends valueTypes>(...args: [Types<T>] | [KeyPath, T]): Promise<void>: Sets a value at a specific key path asynchronously.
setSync<T extends valueTypes>(...args: [Types<T>] | [KeyPath, T]): void: Sets a value at a specific key path synchronously.
unset(keyPath?: KeyPath): Promise<void>: Removes a key-value pair at a specific key path asynchronously.
unsetSync(keyPath?: KeyPath): void: Removes a key-value pair at a specific key path synchronously.

Fields

options: Options: The configuration options for the KeyValues instance.
fnc: Functions: An instance of the Functions class used for file operations and data manipulation.

Dependencies

lodash: The Lodash library exported as Node.js modules.
write-file-atomic: Atomically and asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer