https://github.com/qiwi/primitive-storage
Basic storage implementations.
https://github.com/qiwi/primitive-storage
js-platform
Last synced: 5 days ago
JSON representation
Basic storage implementations.
- Host: GitHub
- URL: https://github.com/qiwi/primitive-storage
- Owner: qiwi
- License: mit
- Created: 2018-05-01T19:09:29.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-15T18:11:55.000Z (about 2 months ago)
- Last Synced: 2025-04-16T04:47:15.121Z (17 days ago)
- Topics: js-platform
- Language: TypeScript
- Size: 7.74 MB
- Stars: 5
- Watchers: 11
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @qiwi/primitive-storage
[](https://github.com/qiwi/primitive-storage/actions/workflows/ci.yaml)
[](https://codeclimate.com/github/qiwi/primitive-storage/maintainability)
[](https://codeclimate.com/github/qiwi/primitive-storage/test_coverage)
[](https://www.npmjs.com/package/@qiwi/primitive-storage)
> kv storage for basic purposes
## Motivation
In ~~2018~~ 2023 it's easier to write own storage implementation than to find a suitable one.
* [memory-cache](https://www.npmjs.com/package/memory-cache) is good enough, but `setTimeout` for each entry set looks redundant (0.2.0)
* [data-store](https://www.npmjs.com/package/data-store) — very nice, but only synchronous saving is supported, no debouncing, no ttl (2.0.1)
* [node-cache](https://www.npmjs.com/package/node-cache) — pretty OK. Callbacks and events are supported. But no JSON.stringify handling, no persistency out of box (4.2.0)
* [CacheFactory](https://github.com/jmdobry/CacheFactory) — brilliant. localStorage, api, docs — everything is ok, but there's no file saving mechanism.
#### What's needed
* Key-Value scheme
* Optional TTL with scheduled compaction
* Optional value cloning
* Cycled refs handling (`JSON.safeStringify`, you know)
* Sync throttling
* Both browser and server runtimes support
## Install
```bash
npm i @qiwi/primitive-storage
yarn add @qiwi/primitive-storage
```
### JS/TS API
```ts
interface IStorage {
get(key: string): any,
set(key: string, value: any, ttl?: number): void,
remove(key: string): void,
reset(): void
}
```
```ts
import factory from '@antongolub/primitive-storage'
const storage = factory({defaultTtl: 60000})
storage.set('foo', 'bar')
storage.get('foo') // 'bar'
// A minute later
storage.get('foo') // undefined
```
Common aliases were also added for convenience:
* `put` = `set`
* `del` = `remove`
* `clear` = `reset`
### Configuration
| Option | Type | Def | Description |
|----------------|---------|---------|--------------------------------------------------------|
| `defaultTtl` | number | - | If defined, the value would be applied as default ttl
for every `set()` call |
| `debounce` | Object | - | Options for persistent storage sync debounce.
If empty no delay processed. IDebounceOpts:
{
delay: number,
maxDelay?: number,
leading?: boolean
trailing?: boolean
}|
| `path` | string | - | Filepath (NodeJS) or localStorage scope (Browser) |
| `compactTimer` | number | - | Period (ms) of automated `compact` method invocation
If undefined, no periodic task is running |
| `clone` | bool/fn | false | `true` means that values are copied to storage on set.
Default copier (JSON.parse(JSON.str(...))) may be replaced
with custom. |
#### Persistent data
It's very simple: if `path` property declared in opts, the data is being persisted:
* In case of NodeJS runtime, the data would be saved as json file.
* Browser relies on `localStorage` API.
```javascript
const storage = factory({path: './data.json'})
```
#### Compaction
Current impl is dumb: every `n` milliseconds the job filters out expired entries from the storage.
You're able to set `compactTimer` in storage opts, or just trigger `compact` method by hand.
## License
[MIT](./LICENSE)