Lockr: LocalStorage Wrapper

Common errors

• ReferenceError: localStorage is not defined

  cause Attempting to use Lockr in a non-browser environment (e.g., Node.js, server-side rendering) where the global `localStorage` object is not available.
  fix Ensure your code only runs Lockr in a browser context. For SSR, conditionally import/execute Lockr or use a `localStorage` polyfill for Node.js if necessary for testing purposes.

• DOMException: QuotaExceededError

  cause The application has attempted to store more data than the browser's `localStorage` quota allows (typically 5-10MB per origin).
  fix Review the data being stored and reduce its size. Consider compressing data before storing, or use alternative storage solutions like IndexedDB for larger datasets.

• Lockr.get('key') returns undefined instead of null for non-existent keys.

  cause Developers accustomed to native `localStorage.getItem('key')` which returns `null` for non-existent keys might expect the same from Lockr. `Lockr.get` returns `undefined`.
  fix Adjust your code to check for `undefined` instead of `null` when retrieving potentially non-existent keys with `Lockr.get`. Alternatively, use the second argument of `Lockr.get(key, defaultValue)` to provide a fallback.

• Data saved with Lockr.set is not accessible via localStorage.getItem() directly.

  cause Lockr serializes objects and arrays to JSON strings and often stores them with internal metadata (e.g., `{"data": "value"}`). If `Lockr.prefix` is set, the key stored in `localStorage` will also be different.
  fix Always retrieve data using `Lockr.get(key)` to ensure proper deserialization and key prefix handling. Avoid directly accessing `localStorage.getItem()` for data managed by Lockr unless you understand its internal storage format.

Warnings

• gotcha The package is currently in a beta release (0.9.0-beta.2). While functional, it may contain bugs or introduce breaking changes before a stable 1.0.0 release. It is generally not recommended for critical production systems without thorough testing.
  Fix: Monitor the project's GitHub repository for updates and release notes. Consider pinning to a specific beta version and conducting comprehensive regression testing if used in production.
• gotcha When `Lockr.prefix` is set, methods like `Lockr.flush()` and `Lockr.getAll()` will *only* operate on keys that match the configured prefix. Keys stored without the prefix (e.g., via direct `localStorage.setItem` or before the prefix was set) will be ignored by these operations.
  Fix: Ensure consistent use of `Lockr.prefix` across your application. If you need to manage all `localStorage` keys, including non-prefixed ones, you might need to interact directly with the native `localStorage` API for those keys.
• gotcha Lockr relies on the browser's native `localStorage` API. If `localStorage` is unavailable (e.g., in private browsing mode, some older browsers, or when running in a Node.js environment without a `localStorage` polyfill), Lockr operations will fail or throw errors without graceful degradation.
  Fix: Implement checks for `typeof localStorage !== 'undefined'` before using Lockr in environments where `localStorage` might be absent. Consider using a polyfill or providing a fallback storage mechanism for broader compatibility.
• gotcha Lockr (and native `localStorage`) operates synchronously, which can block the main thread for large data operations. It also has limited storage capacity (typically 5-10MB per origin) and stores data as strings, requiring serialization/deserialization.
  Fix: For larger datasets, asynchronous operations, or more complex storage needs, consider alternative storage solutions like IndexedDB or Web SQL. Be mindful of the performance implications when storing or retrieving large objects synchronously.

Install

• npm install lockr npm
• yarn add lockr yarn
• pnpm add lockr pnpm

Imports

• Lockr
  wrong:

  import { Lockr } from 'lockr'

  correct:

  import Lockr from 'lockr'

  Lockr is typically used as a default export, providing a global-like API.
• Lockr (CommonJS)

  const Lockr = require('lockr')

  For CommonJS environments, the entire API is exposed via the module export.
• Lockr (Namespace Import)

  import * as Lockr from 'lockr'

  Can also be imported as a namespace, though direct default import is more common.

Quickstart

Demonstrates setting a key prefix, storing various data types (strings, numbers, objects, arrays), retrieving them, performing set-like operations, and removing keys.

import Lockr from 'lockr';

// Set a prefix for all keys (optional, but good practice)
Lockr.prefix = 'my_app_data_';

// Store various data types. Lockr automatically serializes objects and arrays.
Lockr.set('username', 'Alice Smith');
Lockr.set('userId', 42);
Lockr.set('settings', { theme: 'dark', notifications: true });
Lockr.set('favoriteFruits', ['apple', 'banana', 'cherry']);

// Retrieve values. Lockr automatically deserializes them.
console.log('Username:', Lockr.get('username'));
// Expected: Username: Alice Smith

console.log('Settings:', Lockr.get('settings'));
// Expected: Settings: { theme: 'dark', notifications: true }

// Use Redis-like set operations (sadd, smembers)
Lockr.sadd('uniqueTags', 'javascript');
Lockr.sadd('uniqueTags', 'typescript');
Lockr.sadd('uniqueTags', 'javascript'); // Adding again has no effect

console.log('Unique Tags:', Lockr.smembers('uniqueTags'));
// Expected: Unique Tags: [ 'javascript', 'typescript' ]

// Remove a key
Lockr.rm('username');
console.log('Username after removal:', Lockr.get('username', 'Guest'));
// Expected: Username after removal: Guest (demonstrating default value)

// Get all values (only prefixed ones if prefix is set)
console.log('All stored values:', Lockr.getAll());