Browser-Storage

Install

Usage

// Global
// <script src="./dist/release/browser-storage.js"></script>
// NodeJS Module
const { BrowserStorage } = require("@semibold/browser-storage");
// ES-next Module
import { BrowserStorage } from "@semibold/browser-storage";

Support

Instance & API

/**
 * @param {"localStorage"|"sessionStorage"} areaName
 * @param {Object} [options]
 * @param {string} [options.prefix = ""] - The prefix of storage keys. Using the
 * Browser-Storage API to store, retrieve user data from
 * localStorage/sessionStorage will be limited to a certain area.
 * e.g: `bs.clear()` will only clear keys prefixed with `media_` which your
 * previous set in `options.prefix`.
 * @param {Function} [options.parse = (text: string): any => JSON.parse(text)]
 * Use this function to parse text before the text returns.
 * @param {Function} [options.stringify = (vaule: any): string => JSON.stringify(value)]
 * Use this function to stringify value before setting the value.
 */
const bs = new BrowserStorage(areaName, options);
/**
 * @typedef {Object} Metadata
 * @property {string} name
 * @property {string} version
 * @property {string} revision
 * @property {boolean} production
 * @property {string} lastCompiled
 * @return {Metadata}
 */
BrowserStorage.metadata;
/**
 * @readonly
 * @return {Storage} - localStorage/sessionStorage
 */
bs.storage;
/**
 * @desc To be able to use storage, we should first verify that
 * it is supported and available in the current browsing session
 * @return {boolean}
 */
bs.available();
/**
 * @desc Gets one or more items from storage.
 * @desc A single key to get, list of keys to get, or a dictionary specifying default
 * values. An empty list or object will return an empty result object. Pass in
 * null to get the entire contents of storage.
 *
 * @param {null|string|string[]|Object} keys
 * @return {Object}
 */
bs.get(keys);
/**
 * @desc Gets the amount of space (in bytes) being used by one or more items.
 * @desc A single key or list of keys to get the total usage for. An empty list will
 * return 0. Pass in null to get the total usage of all of storage.
 *
 * @param {null|string|string[]} keys
 * @return {number} - approximate value
 */
bs.getBytesInUse(keys);
/**
 * @desc Sets multiple items.
 * @desc An object which gives each key/value pair to update storage with. Any other
 * key/value pairs in storage will not be affected.
 * @desc The `set()` may throw an exception if the storage is full.
 *
 * @param {Object} items
 */
bs.set(items);
/**
 * @desc Removes one or more items from storage.
 * @desc A single key or a list of keys for items to remove.
 *
 * @param {string|string[]} keys
 */
bs.remove(keys);
/**
 * @desc Removes all items from storage.
 */
bs.clear();

Example

const bs1 = new BrowserStorage("localStorage");
const bs2 = new BrowserStorage("localStorage", { prefix: "test." });
if (bs1.available()) {
 bs2.set({ abc: 12358 });
 const abc1 = bs1.get("test.abc")["test.abc"];
 const abc2 = bs2.get(["abc"])["abc"];
 console.log(abc1 === abc2); // true
 console.log(abc1 === 12358); // true
 const value = "should be return this statement";
 const __inexistent_value__ = bs1.get({ __inexistent_key__: value }).__inexistent_key__;
 console.log(value === __inexistent_value__); // true
}

Reference