🎲 KeyValues Storage

📚 Summary

KeyValues Storage is a lightweight, file-based utility for managing key-value pairs using JSON. It offers intuitive methods for reading, writing, checking, and deleting values — all with support for both synchronous and asynchronous operations.

❓When Should You Use This Library?

You should consider using KeyValues Storage when you need:

✅ A simple and lightweight key-value store without the overhead of a full database.
🗂️ To persist configuration or state in local .json files.
🚀 Quick read/write operations for small or medium-sized data.
🧩 Nested object support with dot notation access ('user.profile.name').
🧪 Built-in support for both synchronous and asynchronous APIs.
🛡️ Safe and atomic writes to prevent file corruption.
📦 Minimal dependencies (just lodash and write-file-atomic).

💡 It's a great fit for:

Desktop apps (Electron, Tauri, etc.)
Low-traffic web servers or services
Caching user preferences
Storing app metadata
Configuration files
Testing and development tools
CLI Tools

🚀 Main Features

Manage key-value pairs in a persistent JSON file
Support for nested key paths
Multiple instances with different file names
Sync and async methods
Atomic writes and optional formatting

🔧 Usage

⚠Install the library:

bash

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

✏️ Example Code

// Default options
{
  atomicSave: true,
  fileName: 'keyvalues.json',
  prettify: false,
  numSpaces: 2
}

typescript

// Create a new instance of KeyValues with or without custom options
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.");
});

📚 API Reference

See the API documentation for a complete list of available functions and their signatures.

🧪 Methods

Method	Description
`constructor(options?)`	Initializes a new instance of the `KeyValues` class with optional custom options.
`file(): string`	Returns the path to the JSON file.
`resetOptions(): void`	Resets the configuration of the `KeyValues` instance to default options.
`has(keyPath): Promise<boolean>`	Checks if a key path exists asynchronously.
`hasSync(keyPath): boolean`	Checks if a key path exists synchronously.
`get<T>(keyPath?): Promise<T>`	Gets the value at a specific key path asynchronously.
`getSync<T>(keyPath?): T`	Gets the value at a specific key path synchronously.
`set<T>(...args): Promise<void>`	Sets a value at a specific key path asynchronously.
`setSync<T>(...args): void`	Sets a value at a specific key path synchronously.
`unset(keyPath?): Promise<void>`	Removes a key-value pair at a specific key path asynchronously.
`unsetSync(keyPath?): void`	Removes a key-value pair at a specific key path synchronously.

📦 Project Scripts

npm run check — runs formatter, linter and import sorting to the requested files
npm run format — run the formatter on a set of files
npm run lint — run various checks on a set of files
npm run test — run unit tests
npm run test:c — run unit tests with coverage
npm run commit - run conventional commits check
npm run release:test — dry run semantic release
npm run build — build library