2.0.1 • Published 10 months ago
@qiwi/primitive-storage v2.0.1
@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 is good enough, but
setTimeout
for each entry set looks redundant (0.2.0) - data-store — very nice, but only synchronous saving is supported, no debouncing, no ttl (2.0.1)
- node-cache — pretty OK. Callbacks and events are supported. But no JSON.stringify handling, no persistency out of box (4.2.0)
- 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
npm i @qiwi/primitive-storage
yarn add @qiwi/primitive-storage
JS/TS API
interface IStorage {
get(key: string): any,
set(key: string, value: any, ttl?: number): void,
remove(key: string): void,
reset(): void
}
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 ttlfor 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 invocationIf 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.
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
2.0.1
10 months ago
2.0.0
10 months ago
1.4.14
1 year ago
1.4.9
1 year ago
1.4.11
1 year ago
1.4.8
1 year ago
1.4.10
1 year ago
1.4.7
1 year ago
1.4.13
1 year ago
1.4.12
1 year ago
1.4.6
3 years ago
1.4.5
3 years ago
1.4.4
4 years ago
1.4.3
4 years ago
1.4.2
5 years ago
1.4.1
5 years ago
1.4.0
5 years ago
1.3.0
5 years ago
1.2.2
5 years ago
1.2.1
5 years ago
1.2.0
6 years ago
1.1.1
6 years ago
1.1.0
6 years ago
1.0.0
6 years ago