Skip to content

heliomarpm/keyvalues-storage

Repository files navigation


🎲 KeyValues Storage

DeepScan grade CodeFactor CodeQL NPM version Downloads

lodash write-file-atomic

pixme url paypal url kofi url liberapay url releases url license url

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.

pixme url paypal url kofi url liberapay url github sponsors url

License

MIT © Heliomar P. Marques 🔝