https://github.com/heliomarpm/keyvalues-storage
A simple and robust KeyValues Storage's library
https://github.com/heliomarpm/keyvalues-storage
app-library config data db json json-db keyvalues localdb settings storage store
Last synced: about 1 year ago
JSON representation
A simple and robust KeyValues Storage's library
- Host: GitHub
- URL: https://github.com/heliomarpm/keyvalues-storage
- Owner: heliomarpm
- License: mit
- Created: 2023-04-15T14:52:45.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-18T21:35:18.000Z (almost 2 years ago)
- Last Synced: 2025-03-25T20:15:43.720Z (about 1 year ago)
- Topics: app-library, config, data, db, json, json-db, keyvalues, localdb, settings, storage, store
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@heliomarpm/kvs
- Size: 336 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
🎲 KeyValues Storage
[![DeepScan grade][url-deepscan-badge]][url-deepscan]
[![CodeFactor][url-codefactor-badge]][url-codefactor]
![CodeQL][url-codeql] [![NPM version][url-npm-badge]][url-npm]
[![Downloads][url-downloads-badge]][url-downloads]
## 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`:
```bash
npm i @heliomarpm/kvs
# or
yarn add @heliomarpm/kvs
```
## Example Usage
```javascript
// 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)`: 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`: Checks if a key path exists asynchronously.
- `hasSync(keyPath: KeyPath): boolean`: Checks if a key path exists synchronously.
- `get(keyPath?: KeyPath): Promise`: Gets the value at a specific key path asynchronously.
- `getSync(keyPath?: KeyPath): T`: Gets the value at a specific key path synchronously.
- `set(...args: [Types] | [KeyPath, T]): Promise`: Sets a value at a specific key path asynchronously.
- `setSync(...args: [Types] | [KeyPath, T]): void`: Sets a value at a specific key path synchronously.
- `unset(keyPath?: KeyPath): Promise`: 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](https://lodash.com/): The Lodash library exported as Node.js modules.
- [write-file-atomic](https://github.com/npm/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](docs/CONTRIBUTING.md) before making a pull request.
Thank you to all the people who already contributed to project!
###### Made with [contrib.rocks](https://contrib.rocks).
That said, there's a bunch of ways you can contribute to this project, like by:
- :beetle: Reporting a bug
- :page_facing_up: Improving this documentation
- :rotating_light: Sharing this project and recommending it to your friends
- :dollar: Supporting this project on GitHub Sponsors or Ko-fi
- :star2: Giving a star on this repository
## Donate
If you appreciate that, please consider donating to the Developer.
## License
[MIT © Heliomar P. Marques](LICENSE) 🔝
----
[url-npm]: https://www.npmjs.com/package/@heliomarpm/kvs
[url-npm-badge]: https://img.shields.io/npm/v/@heliomarpm/kvs.svg
[url-downloads-badge]: https://img.shields.io/npm/dm/@heliomarpm/kvs.svg
[url-downloads]: http://badge.fury.io/js/@heliomarpm/kvs.svg
[url-deepscan-badge]: https://deepscan.io/api/teams/19612/projects/25344/branches/791226/badge/grade.svg
[url-deepscan]: https://deepscan.io/dashboard#view=project&tid=19612&pid=25344&bid=791226
[url-codefactor-badge]: https://www.codefactor.io/repository/github/heliomarpm/keyvalues-storage/badge
[url-codefactor]: https://www.codefactor.io/repository/github/heliomarpm/keyvalues-storage
[url-codeql]: https://github.com/heliomarpm/keyvalues-storage/actions/workflows/codeql.yml/badge.svg
[url-publish]: https://github.com/heliomarpm/keyvalues-storage/actions/workflows/publish.yml/badge.svg