qiwi
@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
setTimeoutfor 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-storageJS/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') // undefinedCommon aliases were also added for convenience:
put=setdel=removeclear=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 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
localStorageAPI.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.