🎲 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

📦 Installation

Install the library using npm or yarn:

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

🔧 Example Usage

// 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.");
});

🚀 Main functionalities

• 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

🧪 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.

📦 Dependencies

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

🤝 Contributing

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

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. Please consider supporting it!

• ⭐ Starring the repository
• 🐞 Reporting bugs
• 🧾 Improving the documentation
• 🚨 Telling others about it
• 💰 Supporting via GitHub Sponsors, Ko-fi, Paypal, LiberaPay

📝 License

MIT © Heliomar P. Marques 🔝

---