README

Local Storage Fallback

Universal localStorage fallback. Saves your time by fixing Private Mode error writing in web browser and auto serialization that not included in localStorage by default.

Install

npm i fallback-local-storage

Include

Require CommonJS.

const FallbackLocalStorage = require("fallback-local-storage");

Import as ECMAScript module.

import FallbackLocalStorage from "fallback-local-storage";

CDN.

<script src="https://unpkg.com/fallback-local-storage"></script>

Creating an instance

Creating instance with little check.

let appStorage;
if (FallbackLocalStorage.getStorage().includes("localStorage")) {
    // Here we don't have any problems
    // with writing to `window.localStorage`
    appStorage = globalThis.localStorage;
} else {
    // Looks like we have some troubles.
    // Browser has disable `window.localStorage` support.
    // Or browser is in `Private Mode`
    // which disables localStorage completely.
    appStorage = new FallbackLocalStorage();
}

Recommended way of using instance.

globalThis.appStorage = appStorage;
self.appStorage = appStorage;

Not recommended. Only if you have troubles with Private Mode and other libraries.

globalThis.localStorage = new FallbackLocalStorage();
self.localStorage = new FallbackLocalStorage();

// Toggle debug information output.
const DEBUG = false;
// Allow iteration over instance.
// Disable if you don't want be compatible with localStorage.
const ITERABLE = true;
// Serialize data before save and retrieve. VERY RECOMMENDED.
const AUTO_SERIALIZE = true;
// Custom serializer for values.
const CUSTOM_SERIALIZER = null;
const appStorage = new FallbackLocalStorage(
  DEBUG, ITERABLE, AUTO_SERIALIZE, CUSTOM_SERIALIZER
);

API

All basic methods of localStorage are included.

appStorage.setItem("hash", { name: "John" });
appStorage.getItem("isTurnedOn", false);
appStorage.removeItem("hash");
appStorage.hasItem("hash");
appStorage.keys();
appStorage.values();
appStorage.entries();
appStorage.forEach();
appStorage.toString();
appStorage.toJSON();
appStorage.length;
appStorage.clear();

static getStorage (): Array

Return list of available storage

FallbackLocalStorage.getStorage();
// ["localStorage", "sessionStorage", "fallbackStorage"]

Examples

const appStorage = new FallbackLocalStorage();
// FallbackLocalStorage. Start using [localStorage].

const array = ["ONE", "TWO", "THREE"];
appStorage.setItem("array", array);
// If auto-serialize is disabled
// Value for key "array" will be converted to string: "ONE,TWO,THREE"
// If auto-serialize is enabled
// ["ONE", "TWO", "THREE"]

const object = { "1": "ONE", "2": "TWO", "3": "THREE" };
appStorage.setItem("object", object);
// If auto-serialize is disabled
// Value for key "object" will be converted to string: "[object Object]"
// If auto-serialize is enabled
// { 1: "ONE", 2: "TWO", 3: "THREE" }

const map = new Map([[1, "ONE"], [2, "TWO"], [3, "THREE"]]);
appStorage.setItem("map", map);
// If auto-serialize is disabled
// Value for key "map" will be converted to string: "[object Map]"
// If auto-serialize is enabled
// { 1: "ONE", 2: "TWO", 3: "THREE" }

const set = new Set(["ONE", "TWO", "THREE"]);
appStorage.setItem("set", set);
// If auto-serialize is disabled
// Value for key "set" will be converted to string: "[object Set]"
// If auto-serialize is enabled
// ["ONE", "TWO", "THREE"]

fallback-local-storage

Usage no npm install needed!