@sifrr/storage
v0.0.9
Published
Frontend key-value(JSON to JSON) persisted storage library
Downloads
67
Maintainers
Readme
sifrr-storage ·
Browser key-value(JSON) storage library with cow powers. ~2KB alternative to localForage
Size
| Type | Size |
| :----------------------------------------------- | :--------------------------------------------------------: |
| Minified (dist/sifrr.storage.min.js
) | |
| Minified + Gzipped (dist/sifrr.storage.min.js
) | |
Types of storages available (in default priority order)
- IndexedDB (Persisted - on page refresh or open/close)
- WebSQL (Persisted - on page refresh or open/close)
- LocalStorage (Persisted - on page refresh or open/close)
- Cookies (Persisted - on page refresh or open/close), Sent to server with every request
- JsonStorage (In memory - deleted on page refresh or open/close)
How to use
Directly in Browser using standalone distribution
Add script tag in your website.
<script src="https://unpkg.com/@sifrr/storage@{version}/dist/sifrr.storage.min.js"></script>
// Adds window.Sifrr.Storage
Browser API support needed
| APIs | caniuse | polyfills | | :----------- | :-------------------------------------------- | :-------------------------------------------- | | Promises API | https://caniuse.com/#feat=promises | https://github.com/stefanpenner/es6-promise | | IndexedDB | https://caniuse.com/#feat=indexeddb | N/A | | WebSQL | https://caniuse.com/#feat=sql-storage | N/A | | LocalStorage | https://caniuse.com/#feat=namevalue-storage | N/A | | Cookies | 100% | N/A |
Using npm
Do npm i @sifrr/storage
or yarn add @sifrr/storage
or add the package to your package.json
file.
example, put in your frontend js module (compatible with webpack/rollup/etc):
Commonjs
const Storage = require('@sifrr/storage');
ES modules
import { getStorage } from '@sifrr/storage';
// or Sifrr.Storage.getStorage (script tag)
// or Storage.getStorage (node js import)
// or
// if you want to use one type of store without support checking based on priority
import { IndexedDB, WebSQL, LocalStorage, Cookies, JsonStorage } from '@sifrr/storage';
API
Sifrr.Storage uses Promises.
Initialization
- Initialize a storage with a type
let storage = getStorage(type);
where type is one of indexeddb
, websql
, localstorage
, cookies
, jsonstorage
.
Note: If that type is not supported in the browser, then first supported storage will be selected based on priority order.
- Initialize with options
// Options with default values
let options = {
priority: ['indexeddb', 'websql', 'localstorage', 'cookies', 'jsonstorage'], // Priority Array of type of storages to use
name: 'SifrrStorage', // name of table (treat this as a variable name, i.e. no Spaces or special characters allowed)
version: 1, // version number (integer / float / string), 1 is treated same as '1'
desciption: 'Sifrr Storage', // description (text)
size: 5 * 1024 * 1024, // Max db size in bytes only for websql (integer)
ttl: 0 // Time to live/expire for data in table (in ms), 0 = forever, data will expire ttl ms after saving
};
storage = getStorage(options);
Initializing with same priority, name and version will give same instance.
Details
storage.type; // type of storage
storage.name; // name of storage
storage.version; // version number
Setting key-value
// insert single key-value
let key = 'key';
let value = { value: 'value' };
storage.set(key, value).then(() => {
/* Do something here */
});
// insert multiple key-values
let data = { a: 'b', c: { d: 'e' } };
storage.set(data).then(() => {
/* Do something here */
});
// inserting with different ttl (30 seconds in example) than set in options
storage.set(key, { value, ttl: 30 * 1000 ).then(() => {
/* Do something here */
});
Note Cookies are trucated after ~628 characters in chrome (total of key + value characters), other browsers may tructae at other values as well. Use cookies for small data only
Set cookie that can be sent
storage.store = `key=value; expires=...; path=/`;
Getting value
// get single key-value
storage.get('key').then(value => console.log(value)); // > { key: { value: 'value' } }
// get multiple key-values
storage.get(['a', 'c']).then(value => console.log(value)); // > { a: 'b', c: { d: 'e' } }
Deleting a key
// delete single key-value
storage.del('key').then(() => {
/* Do something here */
});
// delete multiple key-values
storage.del(['a', 'c']).then(() => {
/* Do something here */
});
Updating a key
.set()
will update the value as well.
Get all data in table
storage.all().then(data => console.log(data)); // > { key: { value: 'value' }, a: 'b', c: { d: 'e' } }
Get all keys in table
storage.keys().then(keys => console.log(keys)); // > ['key', 'a', 'c']
Clear table
storage.clear().then(() => {
// checking if data is deleted
storage.all().then(data => console.log(data)); // > {}
});
Use for memoization or any function
function some(a, b, c, d) {
// expensive computation
return 'a';
}
const memoizedSome = storage.memoize(some); // cache key is unique for unique first function argument
// custom cache key function, should return string
function cacheKeyFunction(a, b, c, d) {
return JSON.stringify(c);
}
const memoizedSomeCustomCache = storage.memoize(some, cacheKeyFunction);
Get all created storage instances
Sifrr.Storage.all;
Types of data supported
key
should be string
value
can be any of these types:
Array
,ArrayBuffer
,Blob
,Float32Array
,Float64Array
,Int8Array
,Int16Array
,Int32Array
,Number
,Object
,Uint8Array
,Uint16Array
,Uint32Array
,Uint8ClampedArray
,String
Gotchas
- When using localStorage, websql or cookies, binary data will be serialized before being saved (and retrieved). This serialization will incur a size increase when binary data is saved, and might affect performance.
- Since object[key] is
undefined
when key is not present in the object,undefined
is not supported as a value. null
value has buggy behaviour in localstorage, as it returnsnull
when value is not present.- If you want to save falsy values, you can save
false
or0
which are supported by all storages.