Make Typed Storage Usage

make-typed-storage Usage Guide

API

makeTypedStorage(storageKey, schema, storage)

Core function. Accepts any StorageLike backend.

makeLocalStorage(storageKey, schema)

Convenience wrapper using globalThis.localStorage.

makeSessionStorage(storageKey, schema)

Convenience wrapper using globalThis.sessionStorage.

TypedStorage<T> Methods

Key Distinctions

• get vs strictGet: get is fast (no validation), returns undefined if missing. strictGet validates the full object, throws if invalid.
• set vs setAll: set writes one key without validation (incremental building). setAll validates the entire object before writing.
• getAll vs toJSON: Identical behavior. toJSON is an alias for getAll.
• merge: Reads existing data, shallow-merges, validates the result, writes back. Throws if invalid.

StorageValidationError

Custom error with structured data:

try {
  typed.strictGet("name");
} catch (error) {
  if (error instanceof StorageValidationError) {
    error.storageKey; // "user-prefs"
    error.issues; // [{ message: "Expected string" }]
  }
}

StorageLike Interface

interface StorageLike {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}

Usage Patterns

1. Basic localStorage usage

import { makeLocalStorage } from "make-typed-storage";
import { z } from "zod";

const prefs = makeLocalStorage(
  "prefs",
  z.object({ theme: z.enum(["light", "dark"]), lang: z.string() }),
);

prefs.set("theme", "dark");
prefs.get("theme"); // "dark"

2. Custom storage backend (cookies, in-memory)

import { makeTypedStorage, type StorageLike } from "make-typed-storage";

const cookieStorage: StorageLike = {
  getItem: (key) => cookies.get(key) ?? null,
  setItem: (key, value) => cookies.set(key, value),
  removeItem: (key) => cookies.delete(key),
};

const prefs = makeTypedStorage("prefs", schema, cookieStorage);

3. Writing complete data with validation

prefs.setAll({ theme: "dark", lang: "en" });
// Validates before writing — throws StorageValidationError if invalid

4. Partial updates with merge

prefs.setAll({ theme: "dark", lang: "en" });
prefs.merge({ lang: "pt" });
// Result: { theme: "dark", lang: "pt" }

5. Validated reads

const theme = prefs.strictGet("theme");
// Validates entire object, throws if invalid, returns T[K]

6. Check existence

if (prefs.isSet) {
  const data = prefs.getAll();
}

7. Schema libraries

// Zod
makeTypedStorage("key", z.object({ name: z.string() }), localStorage);

// Valibot
makeTypedStorage("key", v.object({ name: v.string() }), localStorage);

// ArkType
makeTypedStorage("key", type({ name: "string" }), localStorage);

Important Constraints

• Async schemas are not supported — throws TypeError
• set does NOT validate (use setAll or merge for validated writes)
• getAll and toJSON return undefined on validation failure (no throw)
• strictGet, setAll, and merge throw StorageValidationError on failure
• Data is stored as JSON — values must be JSON-serializable