kache

kache is a browser-friendly utility for managing localStorage with extra helpers like expiry, batch operations, backup/restore, and lightweight client-side encryption.

What It Does

• Saves structured data into localStorage
• Reads values back as real JavaScript objects
• Supports TTL and expiry checks
• Provides batch helpers like setMany() and getMany()
• Searches managed keys with regex
• Exports and restores data as JSON
• Works with a custom storage adapter for testing or SSR

Installation

npm install

Quick Example

const storage = require("./index");

storage.set("user", { name: "Ali", role: "admin" });
storage.setWithExpiry("otp", "123456", 30000);
storage.setEncrypted("token", { value: "secret-token" });

console.log(storage.get("user"));
console.log(storage.getRemainingTime("otp"));
console.log(storage.getEncrypted("token"));

Browser Use

By default, the package uses window.localStorage when it exists.

const storage = require("./index");

storage.set("theme", "dark");
console.log(storage.get("theme"));

Custom Instance

You can create isolated instances with a custom prefix, secret key, storage adapter, or size limit.

const { createStorage } = require("./index");

const storage = createStorage({
  prefix: "app:",
  secretKey: "my-secret",
  maxSizeKB: 2048,
});

API

Core

| Method | Description | | --- | --- | | set(key, value) | Save a value into localStorage. | | get(key) | Read a value. Returns null if missing or expired. | | remove(key) | Remove a single key. | | clear() | Remove all keys managed by this util instance. | | all() | Return all managed values as an object. | | has(key) | Check whether a key exists and is active. |

Expiry

| Method | Description | | --- | --- | | setWithExpiry(key, value, ttlMs) | Save a value with a TTL in milliseconds. | | isExpired(key) | Check whether a key is expired. | | getRemainingTime(key) | Get remaining TTL in milliseconds. | | refreshExpiry(key, ttlMs) | Reset TTL for an existing key. |

Security

| Method | Description | | --- | --- | | setEncrypted(key, value) | Save a value with lightweight client-side encryption. | | getEncrypted(key) | Read and decrypt a value saved with setEncrypted(). | | obfuscate(value) | Return a masked base64 form of serialized data. |

Stats

| Method | Description | | --- | --- | | length() | Count of managed active keys. | | size() | Approximate used size in KB. | | getUsedSpace() | Returns { bytes, kb }. | | getFreeSpace() | Returns { bytes, kb, limitKB } using the configured limit. |

Batch Operations

| Method | Description | | --- | --- | | setMany(entries) | Save many values from an object, array, or Map. | | getMany(keys) | Read many keys as an object. | | removeMany(keys) | Remove many keys. | | update(key, patch) | Update a stored plain object with a patch or updater function. |

Search

| Method | Description | | --- | --- | | find(pattern) | Find keys by regex or pattern string. | | keys() | Return all managed keys. | | values() | Return all managed values. |

Backup

| Method | Description | | --- | --- | | backup(pretty = true) | Export managed data as JSON. | | restore(backupData) | Replace current managed data from a backup object or JSON string. | | migrate(legacyData, mapper) | Import old data into the new format. |

Examples

Batch Save

storage.setMany({
  name: "Ali",
  age: 24,
  settings: {
    language: "az",
  },
});

Update an Object

storage.set("profile", {
  name: "Ali",
  settings: {
    theme: "light",
  },
});

storage.update("profile", {
  settings: {
    theme: "dark",
  },
});

Backup and Restore

const backup = storage.backup();

storage.clear();
storage.restore(backup);

Prefix for Isolation

const appStorage = createStorage({ prefix: "my-app:" });

appStorage.set("token", "abc123");
appStorage.set("user", { id: 7 });

Notes

• This package is designed for browser localStorage.
• Only data created by this util is read by methods like all(), keys(), and clear().
• Encryption here is lightweight client-side protection, not a replacement for real secure storage.
• In non-browser environments, you can pass a custom storage adapter.

Exports

const storage = require("./index");
const { StorageUtil, createStorage, createMemoryStorage } = require("./index");

License

ISC