@wuyuchentr/localforage-plus

A lightweight wrapper around localforage adding TTL expiration, namespaces, and batch operations.

Install

npm install @wuyuchentr/localforage-plus localforage

Usage

import create from '@wuyuchentr/localforage-plus';

const storage = create();
// or with a dedicated instance:
const storage = create({ name: 'myapp' });

TTL / Expiration

await storage.set('token', 'abc123', { expires: 3600 });
//         ↓ key   ↓ value      ↓ expires in 3600 seconds (1 hour)

const token = await storage.get('token');
// returns null after 1 hour (auto-cleaned)

Namespaces

await storage           .set('name', 'Alice');   // key: "name"
await storage.namespace('user').set('name', 'Bob'); // key: "user:name"

storage.get('name');        // → 'Alice'
storage.namespace('user').get('name'); // → 'Bob'

// Nested namespaces
storage.namespace('a').namespace('b').set('x', 1); // key: "a:b:x"

Batch operations

await storage.bulkSet([
  { key: 'a', val: 1 },
  { key: 'b', val: 2 },
]);

const items = await storage.bulkGet(['a', 'b']);
// → [{ key: 'a', val: 1 }, { key: 'b', val: 2 }]

await storage.bulkRemove(['a', 'b']);

Clear scoped

await storage.namespace('user').clear();
// only removes keys prefixed with "user:"
// other keys (e.g. "settings:theme") are untouched

await storage.clear();
// removes everything

API

| Method | Description | |--------|-------------| | set(key, value, {expires?}) | Store a value with optional TTL (seconds) | | get(key) | Retrieve a value (returns null if expired/missing) | | remove(key) | Delete a key | | clear() | Clear all keys, or only keys in current namespace | | keys() | List all keys (scoped to namespace) | | namespace(prefix) | Create a scoped instance | | bulkSet(entries[]) | Batch set [{key, val, expires?}] | | bulkGet(keys[]) | Batch get → [{key, val}][] | | bulkRemove(keys[]) | Batch remove |

How it works

• Uses localforage under the hood (IndexedDB / WebSQL / localStorage)
• TTL stores a e field (expiry timestamp) alongside the value
• Namespace prepends prefix: to keys (can nest infinitely)
• Expired keys are lazily cleaned on get() — no background timers