Show HN: Ls-service – minimal, namespaced, and typed localStorage wrapper

Minimal, namespaced, and typed localStorage wrapper.

pnpm

pnpm add ls-service

npm

npm install ls-service

yarn

yarn add ls-service

Examples

Load or Initialize

const settings = storage.getOrSet("settings", () => ({ theme: "dark", lang: "en", }));

Counters and Read-Modify-Write

storage.update("visits", (n) => n + 1, 0); // 1, then 2, ...

storage.update("settings", (s) => ({ ...s, theme: "light" }));

Lists

storage.update("todos", (list) => [...list, { id: 2, text: "Ship it" }], []);

Inspect and Export a Namespace

storage.keys(); // ['settings', 'visits'] storage.keys(true); // ['my-app:settings', 'my-app:visits']

storage.entries(); // [['settings', {...}], ['visits', 3]] Object.fromEntries(storage.entries()); // plain object snapshot

storage.size(); // 2

Isolated Namespaces

const auth = new LocalStorageService("auth"); const ui = new LocalStorageService("ui");

auth.set("token", "abc"); ui.set("token", "xyz"); // no collision

ui.clear(); // auth:token is untouched

TypeScript

Pass type arguments to type the result:

import { LocalStorageService } from "ls-service";

interface User { id: number; name: string; }

const storage = new LocalStorageService("my-app");

storage.set("user", { id: 1, name: "Ada" });

const user = storage.get<User>("user"); // User | null const safe = storage.get<User>("user", defaultUser); // User (fallback given) const theme = storage.getOrSet<string>("theme", () => "dark"); // string const count = storage.update<number>("count", (n) => (n ?? 0) + 1, 0); // number const all = storage.entries<User>(); // [string, User | null][]

The type is a compile-time assertion only; stored data is not validated at runtime, so treat it as untrusted if its shape may have changed between releases.

Storage problems always throw; there is no in-memory fallback.

import { LocalStorageService } from "ls-service";

try { const storage = new LocalStorageService("my-app"); storage.set("big", data); } catch (error) { if (error.message.includes("unavailable")) { // localStorage blocked or missing; check error.cause for details } else if (error.name === "QuotaExceededError") { // storage limit reached } else { throw error; } }

API

For more detailed documentation, please view the API Reference.

If you have suggestions for how this project could be improved, or want to report a bug, feel free to open an issue! We welcome all contributions.

Likewise, before contributing please read the contribution guide.

After implementing this simple service wrapper across several client-side projects, I decided to publish it as a public package rather than repeatedly copying the code.

Changelog

Code of Conduct

Contributing

Security

API Reference

License

MIT