🎲 KeyValues Storage

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": {
        "rgb": [0, 179, 230],
        "hex": "#003BE6"
    }
}

// Set a key-values
kvs.setSync('color', color);

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

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

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');

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

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

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

Contributing

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to project!

Made with contrib.rocks.

That said, there's a bunch of ways you can contribute to this project, like by:

🪲 Reporting a bug
📄 Improving this documentation
🚨 Sharing this project and recommending it to your friends
💵 Supporting this project on GitHub Sponsors or Ko-fi
🌟 Giving a star on this repository

Donate

If you appreciate that, please consider donating to the Developer.

heliomarpm/keyvalues-storage