Analytics
/

Storage Utils

Utility library for persisting data

A tiny storage utility library with fallback mechanism in 1020 bytes.

Exposes getItem, setItem, removeItem functions.

This library will work with analytics or as a standalone import in your code.

By default, @analytics/storage-utils will persist values in browser in this order:

  1. Try localStorage
  2. If no localStorage, use cookies
  3. If no cookies, use sessionStorage
  4. If no sessionStorage, use global window

If you want to specify which storage mechanism to use, use the options parameter.

See live demo.

How to install

Install @analytics/storage-utils from npm.

npm install @analytics/storage-utils

API

Below is the api for @analytics/storage-utils. You can import only what you need & the rest will be tree-shaken out of your bundle.

setItem

Set a value.

import { setItem } from '@analytics/storage-utils'

/** 
* Basic usage 
*/

/* Save value to `localStorage` or `cookies` or `global` */
setItem('key', 'value')
// { value: "value", oldValue: "old", location: "localStorage" }

/** Setting values to specific location */

/* Set value to specifically localStorage */
setItem('key', 'otherValue', { storage: 'localStorage' })
// { value: "otherValue", oldValue: "value", location: "localStorage" }

/* Set value to specifically cookie */
setItem('keyTwo', 'cookieVal',  { storage: 'cookie' })
// { value: "cookieVal", oldValue: "null", location: "cookie" }

/* Set value from specifically sessionStorage */
setItem('keyThree', 'xyz', { storage: 'sessionStorage' })
// { value: "cookieVal", oldValue: "null", location: "sessionStorage" }

/* Set value from specifically the global window (or global this in node.js) */
setItem('keyThree', 'xyz', { storage: 'global' })
// { value: "cookieVal", oldValue: "null", location: "cookie" }

getItem

Get a value.

import { getItem } from '@analytics/storage-utils'

/* Basic usage */

/* Lookup value from `localStorage` or `cookies` or `global` */
const value = getItem('key')

/** 
 * Getting values to specific locations
 */

// Get value to specifically localStorage
const getLocalStorageValue = getItem('key', { storage: 'localStorage' })

/* Get value to specifically cookie */
const getCookieValue = getItem('key', { storage: 'cookie' })

// Get value to specifically sessionStorage
const getSessionStorageValue = getItem('key', { storage: 'sessionStorage' })

/* Get value from specifically the global window (or global this in node.js) */
const getGlobalValue = getItem('key', { storage: 'global' })

/* Get value from all locations */
const valueObj = getItem('otherKey', { storage: '*' })
// { cookie: undefined, localStorage: "hahaha", global: null }

removeItem

Remote a value.

import { removeItem } from '@analytics/storage-utils'

/* Basic usage */

// Will try remove value from `localStorage` -> `cookies` -> `global`
removeItem('key')

/** Removing values to specific locations */

/* Remove value to specifically localStorage */
removeItem('key', { storage: 'localStorage' })

/* Remove value to specifically cookie */
removeItem('keyTwo', { storage: 'cookie' })

/* Remove value to specifically sessionStorage */
removeItem('key', { storage: 'sessionStorage' })

/* Remove value to specifically global */
removeItem('keyThree', { storage: 'global' })

/* Remove value from all locations */
removeItem('otherKey', { storage: '*' })