@bb-labs/local-db 0.0.1

package/README.md

@@ -0,0 +1,179 @@
+## Introduction
+
+A tiny **client-side React hook** for **persistent state**, backed by **IndexedDB**, with:
+
+- ✅ Zod-based schema validation
+- ✅ Cross-tab synchronization (BroadcastChannel)
+- ✅ Repair of invalid persisted data
+- ✅ SSR-safe hydration (`value: undefined` while loading)
+- ✅ No external state library required
+- ✅ Per-hook database & store targeting
+- ✅ Deduplicated shared store per key (`useSyncExternalStore`)
+
+Perfect for saving **user settings, UI state, drafts, local preferences**, or anything that should persist across reloads and sync across tabs.
+
+---
+
+## Installation
+
+```bash
+npm install @bigbang-sdk/local-db
+# or
+yarn add @bigbang-sdk/local-db
+# or
+pnpm add @bigbang-sdk/local-db
+# or
+bun add @bigbang-sdk/local-db
+```
+
+Requires React 18+.
+
+---
+
+## Quick Example
+
+```tsx
+import { useLocalDb } from "@bigbang-sdk/local-db";
+import { z } from "zod";
+
+const SettingsSchema = z.object({
+  fontSize: z.number().min(10).max(32),
+});
+
+export default function SettingsPanel() {
+  const { value, setValue } = useLocalDb({
+    key: "settings",
+    schema: SettingsSchema,
+    initialValue: { fontSize: 16 },
+  });
+
+  if (value === undefined) return <div>Loading…</div>; // hydrating
+
+  return (
+    <div>
+      <div>Font size: {value.fontSize}px</div>
+      <button onClick={() => setValue({ fontSize: value.fontSize + 1 })}>Increase</button>
+      <button onClick={() => setValue({ fontSize: value.fontSize - 1 })}>Decrease</button>
+    </div>
+  );
+}
+```
+
+---
+
+## API
+
+### `useLocalDb(options)`
+
+| Option         | Type             | Default      | Description                                                                 |
+| -------------- | ---------------- | ------------ | --------------------------------------------------------------------------- |
+| `key`          | `string`         | **required** | The logical key used in IndexedDB & cross-tab sync.                         |
+| `schema`       | `z.ZodSchema<T>` | **required** | Validates and repairs stored values.                                        |
+| `initialValue` | `T \| null`      | `null`       | Used if no data exists or persisted data is invalid. Captured on first use. |
+| `dbName`       | `string`         | `"local-db"` | Optional database name override.                                            |
+| `storeName`    | `string`         | `"local-db"` | Optional object store name override.                                        |
+
+### Returns
+
+```ts
+{
+  value: T | null | undefined;
+  setValue(next: T | null): void;
+}
+```
+
+- **`value === undefined`** → still hydrating from IndexedDB
+- **`value === null`** → no stored value
+- **`value === T`** → validated, ready to use
+
+---
+
+## Cross-Tab Sync
+
+Updates propagate instantly across open browser tabs/windows:
+
+- Automatically via **BroadcastChannel**
+- Repairs apply consistently across all tabs
+- No unnecessary re-renders (deep-equality guarded)
+
+---
+
+## Validation & Repair
+
+Every read and write is validated using your Zod schema.
+
+If data is corrupted or has an outdated shape:
+
+```diff
+Persisted Data → schema.safeParse() → ✅ valid → used
+Persisted Data → schema.safeParse() → ❌ invalid → repaired to initialValue
+```
+
+The repaired value is **automatically written back** to IndexedDB.
+
+---
+
+## SSR Behavior (Next.js Friendly)
+
+This hook is designed for **client components**.
+
+- It does **not** access `window`, `indexedDB` or `BroadcastChannel` on the server.
+- `value` begins as **`undefined`** so server and client HTML always match.
+- Hydration + IDB read happens **only in the browser**.
+
+---
+
+## Using Multiple Databases / Stores
+
+```ts
+const { value, setValue } = useLocalDb({
+  key: "draft",
+  schema: DraftSchema,
+  initialValue: null,
+  dbName: "editor-db",
+  storeName: "drafts",
+});
+```
+
+Tabs will **only sync if both `dbName` and `storeName` match**.
+
+---
+
+## Performance
+
+- No-op writes are skipped using deep-equality.
+- Broadcasts are only emitted on real changes.
+- Hydration is lazy-per-key with `useSyncExternalStore`.
+- UI remains responsive even if IndexedDB is slow.
+
+### If you expect _high-frequency updates_ (e.g., live typing):
+
+Consider batching or debouncing writes:
+
+```ts
+setValue(next);
+```
+
+---
+
+## Why not localStorage?
+
+| Feature                  | localStorage       | @bigbang-sdk/local-db             |
+| ------------------------ | ------------------ | --------------------------------- |
+| Large data               | ❌ slow / capped   | ✅ stores MBs efficiently         |
+| Cross-tab sync           | ⚠️ yes, but coarse | ✅ fine-grained, structured clone |
+| Validation               | ❌ no              | ✅ Zod                            |
+| React state sync         | ❌ manual          | ✅ automatic                      |
+| Safe corruption handling | ❌ none            | ✅ self-repair                    |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+PRs welcome!

package/dist/app/components/broadcast.d.ts

@@ -0,0 +1,4 @@
+export declare function getBroadcastChannel(opts?: {
+    dbName?: string;
+    storeName?: string;
+}): BroadcastChannel | null;

package/dist/app/components/broadcast.js

@@ -0,0 +1,28 @@
+import { DEFAULT_DB, DEFAULT_STORE } from "./idb";
+const bcCache = new Map();
+function nsKey(dbName, storeName) {
+    return `${dbName}/${storeName}`;
+}
+function channelName(dbName, storeName) {
+    // Namespaced channel; safe across multiple store pairs
+    return `local-db:${dbName}:${storeName}`;
+}
+export function getBroadcastChannel(opts) {
+    if (typeof window === "undefined")
+        return null;
+    const db = opts?.dbName ?? DEFAULT_DB;
+    const st = opts?.storeName ?? DEFAULT_STORE;
+    const k = nsKey(db, st);
+    const cached = bcCache.get(k);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const bc = new BroadcastChannel(channelName(db, st));
+        bcCache.set(k, bc);
+        return bc;
+    }
+    catch {
+        bcCache.set(k, null);
+        return null;
+    }
+}

package/dist/app/components/idb.d.ts

@@ -0,0 +1,12 @@
+import { type UseStore } from "idb-keyval";
+export declare const DEFAULT_DB = "local-db";
+export declare const DEFAULT_STORE = "local-db";
+export declare function getOrCreateIdbStore(dbName?: string, storeName?: string): UseStore | null;
+export declare function idbGet<T>(key: string, opts?: {
+    dbName?: string;
+    storeName?: string;
+}): Promise<T | undefined>;
+export declare function idbSet<T>(key: string, value: T | null, opts?: {
+    dbName?: string;
+    storeName?: string;
+}): Promise<void>;

package/dist/app/components/idb.js

@@ -0,0 +1,45 @@
+import { createStore, del, get, set } from "idb-keyval";
+export const DEFAULT_DB = "local-db";
+export const DEFAULT_STORE = "local-db";
+const storeCache = new Map();
+function keyFor(dbName, storeName) {
+    return `${dbName}/${storeName}`;
+}
+export function getOrCreateIdbStore(dbName = DEFAULT_DB, storeName = DEFAULT_STORE) {
+    if (typeof indexedDB === "undefined")
+        return null;
+    const k = keyFor(dbName, storeName);
+    if (storeCache.has(k))
+        return storeCache.get(k);
+    try {
+        const s = createStore(dbName, storeName);
+        storeCache.set(k, s);
+        return s;
+    }
+    catch {
+        storeCache.set(k, null);
+        return null;
+    }
+}
+export async function idbGet(key, opts) {
+    const s = getOrCreateIdbStore(opts?.dbName, opts?.storeName);
+    if (!s)
+        return undefined;
+    try {
+        return await get(key, s);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function idbSet(key, value, opts) {
+    const s = getOrCreateIdbStore(opts?.dbName, opts?.storeName);
+    if (!s)
+        return;
+    try {
+        value === null ? await del(key, s) : await set(key, value, s);
+    }
+    catch {
+        /* swallow to keep UI responsive */
+    }
+}

package/dist/app/components/store-registry.d.ts

@@ -0,0 +1,17 @@
+export type StoreState<T> = {
+    value: T | null | undefined;
+    repairTo: T | null;
+    hydrated: boolean;
+    listeners: Set<() => void>;
+};
+type Ns = {
+    dbName?: string;
+    storeName?: string;
+};
+type T_GetStore<T> = StoreState<T> & {
+    hydrate: () => void;
+    setValue: (next: T | null) => void;
+    isEqual: (a: unknown, b: unknown) => boolean;
+};
+export declare function getStore<T>(key: string, initial: T | null, isValid: (v: T | null) => boolean, isEqual: (a: T | null | undefined, b: T | null | undefined) => boolean, ns?: Ns): T_GetStore<T>;
+export {};

package/dist/app/components/store-registry.js

@@ -0,0 +1,87 @@
+import { getBroadcastChannel } from "./broadcast";
+import { DEFAULT_DB, DEFAULT_STORE, idbGet, idbSet } from "./idb";
+// Composite registry key: namespace + logical key
+function regKey(key, ns) {
+    const db = ns.dbName ?? DEFAULT_DB;
+    const st = ns.storeName ?? DEFAULT_STORE;
+    return `${db}/${st}|${key}`;
+}
+const stores = new Map();
+export function getStore(key, initial, isValid, isEqual, ns) {
+    const k = regKey(key, ns ?? {});
+    if (stores.has(k))
+        return stores.get(k);
+    const state = {
+        value: undefined,
+        repairTo: initial,
+        hydrated: false,
+        listeners: new Set(),
+    };
+    const notify = () => {
+        for (const fn of state.listeners)
+            fn();
+    };
+    const persist = async (val) => {
+        await idbSet(key, val, ns);
+    };
+    const setValue = (next) => {
+        const safe = isValid(next) ? next : state.repairTo;
+        if (isEqual(state.value, safe))
+            return;
+        state.value = safe;
+        (async () => {
+            await persist(safe);
+            getBroadcastChannel(ns)?.postMessage({
+                key,
+                value: safe,
+                removed: safe === null,
+            });
+        })();
+        notify();
+    };
+    const hydrate = () => {
+        if (state.hydrated)
+            return;
+        state.hydrated = true;
+        // client-only work; on server this early return avoids starting async tasks
+        if (typeof window === "undefined")
+            return;
+        (async () => {
+            const persisted = (await idbGet(key, ns)) ?? state.repairTo;
+            const finalVal = isValid(persisted) ? persisted : state.repairTo;
+            state.value = finalVal;
+            if (!isEqual(persisted, finalVal)) {
+                try {
+                    await persist(finalVal);
+                }
+                catch {
+                    /* noop */
+                }
+            }
+            notify();
+        })();
+        const bc = getBroadcastChannel(ns);
+        if (bc) {
+            const handler = (event) => {
+                const d = event?.data;
+                if (!d || d.key !== key)
+                    return;
+                const incoming = d.removed ? state.repairTo : d.value;
+                const safe = isValid(incoming) ? incoming : state.repairTo;
+                if (!isEqual(state.value, safe)) {
+                    state.value = safe;
+                    notify();
+                }
+            };
+            bc.addEventListener("message", handler);
+            // no teardown needed for app lifetime; add resetStores() if you need HMR/test cleanup
+        }
+    };
+    const store = Object.assign(state, {
+        hydrate,
+        setValue: (n) => setValue(n),
+        isEqual: (a, b) => isEqual(a, b),
+    });
+    stores.set(k, store);
+    return store;
+}

package/dist/app/use-local-db.d.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+export type T_UseLocalDb<T> = {
+    key: string;
+    schema: z.ZodSchema<T>;
+    initialValue?: T | null;
+    /** Optional: choose a specific IndexedDB database & object store */
+    dbName?: string;
+    storeName?: string;
+};
+export type UseLocalDbReturn<T> = {
+    value: T | null | undefined;
+    setValue: (next: T | null) => void;
+};
+export declare const validateWithSchema: <T>(schema: z.ZodSchema<T>, val: T | null) => boolean;
+export declare function useLocalDb<T>({ key, schema, initialValue, dbName, storeName }: T_UseLocalDb<T>): UseLocalDbReturn<T>;

package/dist/app/use-local-db.js

@@ -0,0 +1,29 @@
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { getStore } from "./components/store-registry";
+import { isDeepEqual } from "@bb-labs/deep-equal";
+export const validateWithSchema = (schema, val) => {
+    return val === null ? true : schema.safeParse(val).success;
+};
+export function useLocalDb({ key, schema, initialValue = null, dbName, storeName }) {
+    const initialRef = useRef(initialValue);
+    const ns = useMemo(() => ({ dbName, storeName }), [dbName, storeName]);
+    const isValid = useCallback((val) => validateWithSchema(schema, val), [schema]);
+    const isEqual = isDeepEqual;
+    const store = useMemo(() => getStore(key, initialRef.current, isValid, isEqual, ns), [key, isValid, isEqual, ns]);
+    const subscribe = useCallback((listener) => {
+        store.listeners.add(listener);
+        return () => store.listeners.delete(listener);
+    }, [store]);
+    const getSnapshot = useCallback(() => store.value, [store]);
+    const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const setValue = useCallback((next) => {
+        if (store.isEqual(value, next))
+            return;
+        const safe = isValid(next) ? next : store.repairTo;
+        store.setValue(safe);
+    }, [store, value, isValid]);
+    useEffect(() => {
+        store.hydrate();
+    }, [store]);
+    return { value, setValue };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./app/use-local-db";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./app/use-local-db";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bb-labs/local-db",
+  "version": "0.0.1",
+  "description": "A library for local database using IndexedDB and Zod for React",
+  "homepage": "https://github.com/beepbop-labs/local-db",
+  "keywords": [
+    "local-db",
+    "indexeddb",
+    "keyval",
+    "zod",
+    "react",
+    "javascript",
+    "typescript",
+    "js",
+    "ts"
+  ],
+  "author": "Beepbop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beepbop-labs/local-db.git"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "pack": "npm run build && npm pack --pack-destination ./archive/"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.7"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@bb-labs/deep-equal": "^0.0.1",
+    "fast-deep-equal": "^3.1.3",
+    "idb-keyval": "^6.2.2",
+    "zod": "^4.1.12"
+  }
+}