Nanananananananana.. Pat Man!

    @sifrr/storage
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.9 • Public • Published

    sifrr-storage · npm version Doscify

    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 returns null when value is not present.
    • If you want to save falsy values, you can save false or 0 which are supported by all storages.

    Install

    npm i @sifrr/storage

    DownloadsWeekly Downloads

    42

    Version

    0.0.9

    License

    MIT

    Unpacked Size

    196 kB

    Total Files

    31

    Last publish

    Collaborators

    • aadityataparia