🎲 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:

1. ✅ A simple and lightweight key-value store without the overhead of a full database.
2. 🗂️ To persist configuration or state in local .json files.
3. 🚀 Quick read/write operations for small or medium-sized data.
4. 🧩 Nested object support with dot notation access ('user.profile.name').
5. 🧪 Built-in support for both synchronous and asynchronous APIs.
6. 🛡️ Safe and atomic writes to prevent file corruption.
7. 📦 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:

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

✏️ Example Code

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

// 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.
reset(): 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

📦 Dependencies

• Utility functions for working with objects and arrays.
• Ensures file writes are safe and atomic.

🤝 Contributing

We welcome contributions! Please read:

• Code of Conduct
• Contributing Guide

Thank you to everyone who has already contributed to the project!

Made with contrib.rocks.

❤️ Support this project

If this project helped you in any way, there are several ways to contribute.
Help us maintain and improve this template:

⭐ Starring the repository
🐞 Reporting bugs
💡 Suggest features
🧾 Improving the documentation
📢 Share with others

💵 Supporting via GitHub Sponsors, Ko-fi, Paypal or Liberapay, you decide. 😉

📝 License

MIT © Heliomar P. Marques 🔝

---