storage-deck

library2.1.4jsnpmunverified

A TypeScript library that provides a robust abstraction over browser localStorage and sessionStorage, with automatic in-memory fallback when storage is unavailable or quota is exceeded. Version 2.1.4 (last released) is stable and maintained on GitHub. Key differentiators: seamless overflow handling, custom global storage objects that can hold non-string data (e.g., File objects), and searchable keys with StartWith/EndsWith/Includes support via the Searchable type. Lightweight (~5KB minified), no dependencies, and includes full TypeScript definitions.

storage

npm install storage-deck

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STORAGE-DECK

storage-deck

storagejavascriptv2.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

addToLocalStorage

✓ import { addToLocalStorage } from 'storage-deck'

✗ import addToLocalStorage from 'storage-deck'

Named imports only; no default export.

retrieveFromLocalStorage

✓ import { retrieveFromLocalStorage } from 'storage-deck'

✗ const { retrieveFromLocalStorage } = require('storage-deck')

ESM-only; CommonJS require is not supported.

SearchType

✓ import { SearchType } from 'storage-deck'

TypeScript type export available; import for type usage.

StorageKeyValuePair

✓ import type { StorageKeyValuePair } from 'storage-deck'

TypeScript type export; prefer 'import type' for type-only imports.

Shows adding, retrieving, searching (with SearchType), removing, and clearing items using localStorage.

import { addToLocalStorage, retrieveFromLocalStorage, clearLocalStorage, removeFromLocalStorage, SearchType } from 'storage-deck'; addToLocalStorage({ key: 'username', value: 'alice' }); addToLocalStorage([ { key: 'theme', value: 'dark' }, { key: 'language', value: 'en' } ]); console.log(retrieveFromLocalStorage('username')); // 'alice' // Find keys starting with 'us' const results = retrieveFromLocalStorage({ searchTerm: 'us', searchType: SearchType.StartsWith }); console.log(results); // [ { key: 'username', value: 'alice' } ] // Remove by regex removeFromLocalStorage(/^user/); clearLocalStorage();

Debug

Known issues

gotchaWhen using Searchable keys, searchType must be a valid SearchType enum value; using an invalid string will throw at runtime.

fix

Import SearchType from 'storage-deck' and use SearchType.EndsWith, SearchType.Includes, or SearchType.StartsWith.

affects: >=2.1.0

gotcharetrieveFromLocalStorage with a string key returns null if the key does not exist; do not expect an empty array.

fix

Check for null before using the result as a string.

affects: >=0.0.0

breakingIn version 2.0.0, the function signatures changed: addToLocalStorage now accepts an object or array of StorageKeyValuePair objects, not (key, value) pairs.

fix

Update calls from addToLocalStorage('key', 'value') to addToLocalStorage({ key: 'key', value: 'value' }).

affects: >=2.0.0 <3.0.0

gotchaIn-memory fallback storage is not persistent across page reloads; only use it for transient data.

fix

Design your app to handle data loss if fallback is used (e.g., re-fetch from server).

affects: >=0.0.0

gotchaSession storage functions (addToSessionStorage, etc.) only affect sessionStorage; do not mix with localStorage functions.

fix

Use the appropriate function group for your storage need.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: addToLocalStorage is not a function

Using default import instead of named import.

fix

import { addToLocalStorage } from 'storage-deck';

Cannot find module 'storage-deck'

Package not installed or not in node_modules.

fix

npm install storage-deck

TypeError: Cannot read properties of undefined (reading 'searchTerm')

Using an object without searchTerm property as a Searchable.

fix

Use { searchTerm: 'value', searchType: SearchType.Includes }.

Uncaught ReferenceError: SearchType is not defined

Forgot to import SearchType enum.

fix

import { SearchType } from 'storage-deck';

Upgrade

Version history

2.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubgit://github.com/pseudosma/storage-deck ↗

packagestorage-deck ↗

homepagehttps://github.com/pseudosma/storage-deck ↗