hazo_state 0.1.2

package/CHANGE_LOG.md

@@ -0,0 +1,51 @@
+# hazo_state — Change Log
+
+All notable changes to this package are documented here. Versions follow semver.
+
+## 0.1.2 — 2026-06-12
+
+### Fixed
+- **`useHazoState`: stale-closure / render-storm on inline `fallback`.**
+  When callers pass an inline literal (e.g. `fallback={[]}`), `fallback` is a
+  fresh reference every render. Including it in `useEffect`/`useCallback` deps
+  caused the GET revalidation to re-fire on every parent re-render (up to ~60fps
+  in animation loops). Fixed by storing `fallback` in a `useRef` and reading the
+  ref inside the effect — identity changes that don't affect the resource
+  (key/level/offline/endpoint) no longer trigger a new fetch.
+
+## 0.1.1 — 2026-06-12
+
+### Fixed
+- **test-app: module-not-found at runtime.** `test-app/next.config.js` aliased the
+  `hazo_state` package name to the raw `../src/*.ts` source, forcing the bundler to
+  resolve NodeNext-style `'../index.js'` imports it can't handle (`Can't resolve
+  '../index.js'`). Removed the src aliases — the test-app now consumes the built
+  `dist/` via the workspace symlink and the package `exports` map, matching the
+  workspace standard.
+- **test-app: spurious `ENOWORKSPACES` + wrong Next version.** Replaced the bare
+  `next dev` with the standard `scripts/next.mjs` launcher, which resolves the
+  package-local Next 16 (the workspace root hoists Next 14) and honors the `PORT`
+  convention (default 3300).
+
+### Changed
+- **test-app brought up to the workspace standard.** Added the `hazo_ui/test-harness`
+  shadcn sidebar (`SidebarLayout` + `AppSidebar`), an `/autotest` route
+  (`AutoTestProvider`/`AutoTestRunner`) with browser-side scenarios for the
+  client-safe surface (`resolveIds`, `ConflictError`), Tailwind v4 wiring
+  (`postcss.config.mjs` + `@source` directives), a `hazo_debug` Turbopack stub,
+  and `AGENTS.md`. Upgraded the test-app to Next 16 / React 19.
+- Docs: normalized the feature-request `INDEX.md` to the shared table format.
+
+### Added
+- `CHANGE_LOG.md` (this file), referenced by `README.md` and `package.json` `files[]`.
+
+## 0.1.0 — Initial
+
+- Generic transactional KV store (`hazo_app_state`): 4 visibility levels
+  (global / scope / user-global / user), lazy TTL expiry, optimistic CAS
+  (`version` column), atomic `append`/`increment` ops, and protected
+  (immutable-after-write) entries.
+- Turnkey Next.js route factory (`createStateRoute`) + server service (`HazoState`).
+- Client hook (`useHazoState`) with optimistic localStorage → server sync and an
+  offline-only mode.
+- PostgreSQL + SQLite migrations.

package/README.md

@@ -0,0 +1,37 @@
+# hazo_state
+
+Generic transactional KV store for the hazo ecosystem. Provides TTL, optimistic CAS (version column), four visibility levels (global / scope / user-global / user), and protected (immutable-after-write) entries.
+
+## Install
+
+```bash
+npm install hazo_state hazo_connect
+```
+
+## Setup
+
+1. Run the migration against your database:
+   - PostgreSQL: `psql -f node_modules/hazo_state/migrations/001_hazo_app_state.sql`
+   - SQLite (local dev): apply `node_modules/hazo_state/migrations/001_hazo_app_state_sqlite.sql`
+
+2. See [SETUP_CHECKLIST.md](./SETUP_CHECKLIST.md) for the full step-by-step.
+
+## Peer Dependencies
+
+| Package | Required |
+|---|---|
+| `hazo_connect` | yes |
+| `react` | optional (client entry only) |
+
+## Exports
+
+| Path | Contents |
+|---|---|
+| `hazo_state` | Main entry (server + client-safe utilities) |
+| `hazo_state/server` | Server-only entry (Node.js / Edge only) |
+| `hazo_state/client` | Client-safe entry (React hooks / browser) |
+| `hazo_state/migrations/*` | SQL migration files |
+
+## Changelog
+
+See [CHANGE_LOG.md](./CHANGE_LOG.md).

package/dist/client/index.d.ts

@@ -0,0 +1,32 @@
+import type { StateLevel } from '../index.js';
+export interface UseHazoStateOptions {
+    /** Visibility level. Default: 'global'. */
+    level?: StateLevel;
+    /** Returned while loading from server; also used if the key is unset. */
+    fallback?: unknown;
+    /** localStorage key prefix. Defaults to `hazo_state:<level>:<key>`. */
+    storagePrefix?: string;
+    /** Skip server sync; persist to localStorage only. */
+    offline?: boolean;
+    /** Override the default route endpoint. */
+    endpoint?: string;
+}
+export interface UseHazoStateResult {
+    value: unknown;
+    setValue: (newValue: unknown, opts?: {
+        expectedVersion?: number;
+    }) => Promise<void>;
+    append: (item: unknown, maxLen: number) => Promise<void>;
+    increment: (n?: number) => Promise<number>;
+    loading: boolean;
+    syncing: boolean;
+    error: Error | null;
+}
+/**
+ * Hook for reading and writing a hazo_state entry.
+ *
+ * @param key - State key
+ * @param opts - Options (level, fallback, offline, endpoint)
+ */
+export declare function useHazoState(key: string, opts?: UseHazoStateOptions): UseHazoStateResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAA;AAKzD,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AA0BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,kBAAkB,CA+K5F"}

package/dist/client/index.js

@@ -0,0 +1,217 @@
+'use client';
+/**
+ * hazo_state/client — React hook for reading and writing state via the hazo-state API route.
+ *
+ * Optimistic localStorage → server sync:
+ * 1. Hydrates synchronously from localStorage on mount.
+ * 2. Revalidates from the route on mount (and when key/level changes).
+ * 3. Writes go to the server first; localStorage is updated on success.
+ * 4. CAS conflicts on write are retried (re-read + re-apply).
+ *
+ * Offline mode (offline: true or no endpoint configured):
+ * persists to localStorage only. Useful for tests and demos without a server.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ConflictError } from '../index.js';
+const DEFAULT_ENDPOINT = '/api/hazo-state';
+function storageKey(key, level, prefix) {
+    return prefix ? `${prefix}:${key}` : `hazo_state:${level}:${key}`;
+}
+function localRead(lsKey) {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const raw = localStorage.getItem(lsKey);
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function localWrite(lsKey, entry) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.setItem(lsKey, JSON.stringify(entry));
+    }
+    catch {
+        // Quota exceeded or private browsing — silently ignore
+    }
+}
+/**
+ * Hook for reading and writing a hazo_state entry.
+ *
+ * @param key - State key
+ * @param opts - Options (level, fallback, offline, endpoint)
+ */
+export function useHazoState(key, opts = {}) {
+    const { level = 'global', fallback = null, storagePrefix, offline = false, endpoint = DEFAULT_ENDPOINT, } = opts;
+    const lsKey = storageKey(key, level, storagePrefix);
+    // Initialize from localStorage synchronously to avoid SSR mismatch
+    const [value, setValueState] = useState(() => localRead(lsKey)?.value ?? fallback);
+    const [versionRef] = useState({ current: localRead(lsKey)?.version ?? 0 });
+    const [loading, setLoading] = useState(!offline);
+    const [syncing, setSyncing] = useState(false);
+    const [error, setError] = useState(null);
+    const abortRef = useRef(null);
+    // Keep the latest `fallback` available to the revalidation effect without
+    // making it a dependency. Callers commonly pass an inline literal (e.g.
+    // `fallback: []`), which is a fresh reference every render — including it in
+    // the effect deps would re-fire the GET on every parent re-render (e.g. an
+    // animation loop calling setState ~60fps), flooding the server.
+    const fallbackRef = useRef(fallback);
+    fallbackRef.current = fallback;
+    // Server revalidation. Re-runs only when the resource identity changes
+    // (key/level/offline/endpoint/lsKey) — NOT on every render.
+    useEffect(() => {
+        if (offline)
+            return;
+        const controller = new AbortController();
+        abortRef.current = controller;
+        async function revalidate() {
+            try {
+                const url = `${endpoint}?key=${encodeURIComponent(key)}&level=${level}`;
+                const res = await fetch(url, { signal: controller.signal });
+                if (res.status === 404) {
+                    // Key doesn't exist on server — keep localStorage value or fallback
+                    setLoading(false);
+                    return;
+                }
+                if (!res.ok)
+                    throw new Error(`hazo_state: GET ${res.status}`);
+                const entry = await res.json();
+                versionRef.current = entry.version;
+                localWrite(lsKey, entry);
+                setValueState(entry.value ?? fallbackRef.current);
+            }
+            catch (err) {
+                if (err.name === 'AbortError')
+                    return;
+                setError(err instanceof Error ? err : new Error(String(err)));
+            }
+            finally {
+                setLoading(false);
+            }
+        }
+        revalidate();
+        return () => controller.abort();
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- fallback read via ref on purpose
+    }, [key, level, offline, endpoint, lsKey]);
+    const setValue = useCallback(async (newValue, setOpts) => {
+        if (offline) {
+            const entry = { value: newValue, version: versionRef.current + 1 };
+            versionRef.current = entry.version;
+            localWrite(lsKey, entry);
+            setValueState(newValue);
+            return;
+        }
+        setSyncing(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    key,
+                    level,
+                    value: newValue,
+                    expectedVersion: setOpts?.expectedVersion,
+                }),
+            });
+            if (res.status === 409) {
+                // CAS conflict — re-read and retry
+                const getRes = await fetch(`${endpoint}?key=${encodeURIComponent(key)}&level=${level}`);
+                if (getRes.ok) {
+                    const fresh = await getRes.json();
+                    versionRef.current = fresh.version;
+                    localWrite(lsKey, fresh);
+                    setValueState(fresh.value ?? fallbackRef.current);
+                }
+                throw new ConflictError(key);
+            }
+            if (!res.ok)
+                throw new Error(`hazo_state: PUT ${res.status}`);
+            const entry = await res.json();
+            versionRef.current = entry.version;
+            localWrite(lsKey, entry);
+            setValueState(newValue);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            setSyncing(false);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- fallback read via ref on purpose
+    }, [key, level, offline, endpoint, lsKey, versionRef]);
+    const append = useCallback(async (item, maxLen) => {
+        if (offline) {
+            const current = Array.isArray(value) ? value : [];
+            const newArr = [...current, item].slice(-maxLen);
+            await setValue(newArr);
+            return;
+        }
+        setSyncing(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ key, level, op: { op: 'append', value: item, maxLen } }),
+            });
+            if (!res.ok)
+                throw new Error(`hazo_state: POST append ${res.status}`);
+            // Re-read updated value
+            const getRes = await fetch(`${endpoint}?key=${encodeURIComponent(key)}&level=${level}`);
+            if (getRes.ok) {
+                const entry = await getRes.json();
+                versionRef.current = entry.version;
+                localWrite(lsKey, entry);
+                setValueState(entry.value ?? fallbackRef.current);
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            setSyncing(false);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- fallback read via ref on purpose
+    }, [key, level, offline, endpoint, lsKey, value, setValue, versionRef]);
+    const increment = useCallback(async (n = 1) => {
+        if (offline) {
+            const current = typeof value === 'number' ? value : 0;
+            const newNum = current + n;
+            await setValue(newNum);
+            return newNum;
+        }
+        setSyncing(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ key, level, op: { op: 'increment', n } }),
+            });
+            if (!res.ok)
+                throw new Error(`hazo_state: POST increment ${res.status}`);
+            const data = await res.json();
+            setValueState(data.value);
+            localWrite(lsKey, { value: data.value, version: versionRef.current + 1 });
+            versionRef.current += 1;
+            return data.value;
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            setSyncing(false);
+        }
+    }, [key, level, offline, endpoint, lsKey, value, setValue, versionRef]);
+    return { value, setValue, append, increment, loading, syncing, error };
+}

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * hazo_state — shared types and constants.
+ *
+ * Import server-side helpers from `hazo_state/server`.
+ * Import client-side hooks from `hazo_state/client`.
+ */
+/**
+ * Controls how scope_id and user_id are resolved for a state entry.
+ *
+ * | level        | scope_id   | user_id    |
+ * |--------------|------------|------------|
+ * | global       | NULL       | NULL       | platform-wide (default)
+ * | scope        | auth scope | NULL       | org-shared
+ * | user_global  | NULL       | auth user  | per-user across orgs
+ * | user         | auth scope | auth user  | personal, cross-device
+ */
+export type StateLevel = 'global' | 'scope' | 'user_global' | 'user';
+/** A single row from hazo_app_state. */
+export interface StateRecord {
+    id: string;
+    scope_id: string | null;
+    user_id: string | null;
+    state_key: string;
+    value: unknown;
+    protected: boolean;
+    version: number;
+    expires_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Minimal resolved value returned from get/set operations. */
+export interface StateEntry {
+    value: unknown;
+    version: number;
+}
+/**
+ * Thrown by `set` when an `expectedVersion` CAS guard fails.
+ * The caller should re-read and retry.
+ */
+export declare class ConflictError extends Error {
+    readonly type = "ConflictError";
+    constructor(key: string);
+}
+export type StateOp = {
+    op: 'append';
+    value: unknown;
+    maxLen: number;
+} | {
+    op: 'increment';
+    n: number;
+};
+/** GET query params */
+export interface GetParams {
+    key: string;
+    level?: StateLevel;
+}
+/** PUT body for plain set */
+export interface SetBody {
+    key: string;
+    value: unknown;
+    level?: StateLevel;
+    expectedVersion?: number;
+    expiresAt?: string;
+}
+/** POST body for atomic ops (append / increment) */
+export interface OpBody {
+    key: string;
+    level?: StateLevel;
+    op: StateOp;
+}
+/** DELETE query params */
+export interface DeleteParams {
+    key: string;
+    level?: StateLevel;
+}
+/** Auth context resolved per-request by the app's `resolveAuth`. */
+export interface ResolvedAuth {
+    scope_id: string | null;
+    user_id: string | null;
+    /** Returns true if the caller has the given permission. */
+    hasPermission(perm: string): boolean;
+}
+/** Map level → (scope_id, user_id) given resolved auth. Pure helper. */
+export declare function resolveIds(level: StateLevel | undefined, auth: Pick<ResolvedAuth, 'scope_id' | 'user_id'>): {
+    scope_id: string | null;
+    user_id: string | null;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAA;AAIpE,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAID;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,mBAAkB;gBACnB,GAAG,EAAE,MAAM;CAIxB;AAID,MAAM,MAAM,OAAO,GACf;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAElC,uBAAuB;AACvB,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAED,6BAA6B;AAC7B,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAID,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,2DAA2D;IAC3D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,YAAW,EAC5B,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC,GAC/C;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAOrD"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * hazo_state — shared types and constants.
+ *
+ * Import server-side helpers from `hazo_state/server`.
+ * Import client-side hooks from `hazo_state/client`.
+ */
+// ─── Errors ──────────────────────────────────────────────────────────────────
+/**
+ * Thrown by `set` when an `expectedVersion` CAS guard fails.
+ * The caller should re-read and retry.
+ */
+export class ConflictError extends Error {
+    constructor(key) {
+        super(`hazo_state: optimistic conflict on key "${key}" — re-read and retry`);
+        this.type = 'ConflictError';
+        this.name = 'ConflictError';
+    }
+}
+/** Map level → (scope_id, user_id) given resolved auth. Pure helper. */
+export function resolveIds(level = 'global', auth) {
+    switch (level) {
+        case 'global': return { scope_id: null, user_id: null };
+        case 'scope': return { scope_id: auth.scope_id ?? null, user_id: null };
+        case 'user_global': return { scope_id: null, user_id: auth.user_id ?? null };
+        case 'user': return { scope_id: auth.scope_id ?? null, user_id: auth.user_id ?? null };
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * hazo_state/server — server-side state service and Next.js route factory.
+ *
+ * Values are always JSON-serialized before storage so the same
+ * HazoState service works with both SQLite (TEXT column in test-apps)
+ * and PostgREST (JSONB column in production).
+ */
+import 'server-only';
+import type { HazoConnectAdapter } from 'hazo_connect/server';
+import { type StateEntry, type ResolvedAuth } from '../index.js';
+/** Specification for a key pattern that requires a permission to write. */
+export interface ProtectedKeySpec {
+    /** Exact key string, or a RegExp that is tested against the key. */
+    pattern: string | RegExp;
+    /** Permission checked via resolveAuth.hasPermission. Defaults to 'manage_global_config'. */
+    permission?: string;
+}
+export interface GetOptions {
+    scope_id?: string | null;
+    user_id?: string | null;
+}
+export interface SetOptions extends GetOptions {
+    /** When provided, acts as a CAS guard: throws ConflictError if version mismatches. */
+    expectedVersion?: number;
+    /** ISO 8601 timestamp. null clears any existing TTL. */
+    expiresAt?: string | null;
+    /** Stamp the row as protected on initial insert. Immutable after creation. */
+    isProtected?: boolean;
+}
+/**
+ * Generic KV state service backed by hazo_app_state via hazo_connect.
+ *
+ * All operations accept explicit scope_id / user_id — callers are responsible
+ * for resolving these from auth (the createStateRoute factory handles this).
+ */
+export declare class HazoState {
+    private readonly db;
+    constructor(db: HazoConnectAdapter);
+    private buildKeyQuery;
+    private _getRaw;
+    /**
+     * Get a state entry. Returns null if the key is absent or the TTL has expired (lazy).
+     */
+    get(key: string, opts?: GetOptions): Promise<StateEntry | null>;
+    /**
+     * Set a state entry.
+     *
+     * - Without expectedVersion: blind upsert (read → insert or patch).
+     * - With expectedVersion: CAS; throws ConflictError on mismatch.
+     *   Pass expectedVersion=0 to assert the key does not yet exist.
+     *
+     * Returns the new value + version.
+     */
+    set(key: string, value: unknown, opts?: SetOptions): Promise<StateEntry>;
+    /**
+     * Atomically append an item to a stored array, capping at maxLen (oldest items dropped).
+     * Uses a CAS retry loop — safe under concurrent writes.
+     */
+    appendToWindow(key: string, item: unknown, maxLen: number, opts?: GetOptions): Promise<void>;
+    /**
+     * Atomically increment a stored number by n (default 1).
+     * Uses a CAS retry loop. Returns the new value.
+     */
+    increment(key: string, n?: number, opts?: GetOptions): Promise<number>;
+    /**
+     * Delete a state entry. No-op if absent.
+     */
+    delete(key: string, opts?: GetOptions): Promise<void>;
+    /**
+     * Delete all rows where expires_at is in the past.
+     * Intended to be called from a scheduled job / cron.
+     */
+    sweepExpired(): Promise<number>;
+}
+/** Options for createStateRoute. */
+export interface StateRouteOptions {
+    /**
+     * Resolve the caller's auth context from the incoming request.
+     * The app injects this — auth is app-specific.
+     */
+    resolveAuth: (req: Request) => Promise<ResolvedAuth>;
+    /**
+     * Keys matching these specs are stamped protected=true on creation and
+     * require hasPermission(spec.permission) on write.
+     */
+    protectedKeys?: ProtectedKeySpec[];
+}
+type RouteHandlers = {
+    GET: (req: Request) => Promise<Response>;
+    PUT: (req: Request) => Promise<Response>;
+    POST: (req: Request) => Promise<Response>;
+    DELETE: (req: Request) => Promise<Response>;
+};
+/**
+ * Create Next.js route handlers for hazo_state.
+ *
+ * Mount at `app/api/hazo-state/route.ts`:
+ * ```ts
+ * const handlers = createStateRoute(getHazoConnectSingleton(), { resolveAuth, protectedKeys })
+ * export const { GET, PUT, POST, DELETE } = handlers
+ * ```
+ */
+export declare function createStateRoute(db: HazoConnectAdapter, opts: StateRouteOptions): RouteHandlers;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,aAAa,CAAA;AAOpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE7D,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAA;AAIpB,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AA8BD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAID;;;;;GAKG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,kBAAkB;IAEnD,OAAO,CAAC,aAAa;YAgBP,OAAO;IAQrB;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAOzE;;;;;;;;OAQG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAkDlF;;;OAGG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtG;;;OAGG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB3E;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;CActC;AAID,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IACpD;;;OAGG;IACH,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAA;CACnC;AAED,KAAK,aAAa,GAAG;IACnB,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxC,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxC,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACzC,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC5C,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,iBAAiB,GACtB,aAAa,CA6Hf"}

package/dist/server/index.js

@@ -0,0 +1,345 @@
+/**
+ * hazo_state/server — server-side state service and Next.js route factory.
+ *
+ * Values are always JSON-serialized before storage so the same
+ * HazoState service works with both SQLite (TEXT column in test-apps)
+ * and PostgREST (JSONB column in production).
+ */
+import 'server-only';
+import { QueryBuilder, attachExecute, parseJsonbField, } from 'hazo_connect/server';
+import { ConflictError, resolveIds, } from '../index.js';
+function matchesProtectedKey(key, specs) {
+    for (const spec of specs) {
+        if (spec.pattern instanceof RegExp) {
+            if (spec.pattern.test(key))
+                return spec;
+        }
+        else if (key === spec.pattern) {
+            return spec;
+        }
+    }
+    return null;
+}
+// ─── Value serialization ──────────────────────────────────────────────────────
+function serialize(value) {
+    return JSON.stringify({ _v: value });
+}
+function deserialize(raw) {
+    const parsed = parseJsonbField(raw);
+    if (parsed !== null && typeof parsed === 'object' && '_v' in parsed) {
+        return parsed._v;
+    }
+    // Fallback: try direct parse for legacy rows
+    return parseJsonbField(raw);
+}
+// ─── HazoState service ───────────────────────────────────────────────────────
+/**
+ * Generic KV state service backed by hazo_app_state via hazo_connect.
+ *
+ * All operations accept explicit scope_id / user_id — callers are responsible
+ * for resolving these from auth (the createStateRoute factory handles this).
+ */
+export class HazoState {
+    constructor(db) {
+        this.db = db;
+    }
+    buildKeyQuery(key, scope_id, user_id) {
+        const qb = new QueryBuilder().from('hazo_app_state');
+        qb.where('state_key', 'eq', key);
+        if (scope_id === null) {
+            qb.where('scope_id', 'is', null);
+        }
+        else if (scope_id !== undefined) {
+            qb.where('scope_id', 'eq', scope_id);
+        }
+        if (user_id === null) {
+            qb.where('user_id', 'is', null);
+        }
+        else if (user_id !== undefined) {
+            qb.where('user_id', 'eq', user_id);
+        }
+        return qb;
+    }
+    async _getRaw(key, scope_id, user_id) {
+        const qb = this.buildKeyQuery(key, scope_id, user_id);
+        const rows = await attachExecute(qb, this.db).execute('GET');
+        if (!Array.isArray(rows) || rows.length === 0)
+            return null;
+        const row = rows[0];
+        return { ...row, version: Number(row.version) };
+    }
+    /**
+     * Get a state entry. Returns null if the key is absent or the TTL has expired (lazy).
+     */
+    async get(key, opts = {}) {
+        const row = await this._getRaw(key, opts.scope_id, opts.user_id);
+        if (!row)
+            return null;
+        if (row.expires_at && new Date(row.expires_at) <= new Date())
+            return null;
+        return { value: deserialize(row.value), version: row.version };
+    }
+    /**
+     * Set a state entry.
+     *
+     * - Without expectedVersion: blind upsert (read → insert or patch).
+     * - With expectedVersion: CAS; throws ConflictError on mismatch.
+     *   Pass expectedVersion=0 to assert the key does not yet exist.
+     *
+     * Returns the new value + version.
+     */
+    async set(key, value, opts = {}) {
+        const { scope_id, user_id, expectedVersion, expiresAt, isProtected } = opts;
+        const existing = await this._getRaw(key, scope_id, user_id);
+        const now = new Date().toISOString();
+        const serialized = serialize(value);
+        if (existing) {
+            const newVersion = existing.version + 1;
+            const patch = {
+                value: serialized,
+                version: newVersion,
+                updated_at: now,
+                ...(expiresAt !== undefined ? { expires_at: expiresAt } : {}),
+            };
+            const qb = this.buildKeyQuery(key, scope_id, user_id);
+            if (expectedVersion !== undefined) {
+                qb.where('version', 'eq', expectedVersion);
+            }
+            const result = await attachExecute(qb, this.db).execute('PATCH', patch);
+            if (Array.isArray(result) && result.length === 0) {
+                throw new ConflictError(key);
+            }
+            return { value, version: newVersion };
+        }
+        // Insert new row
+        if (expectedVersion !== undefined && expectedVersion !== 0) {
+            throw new ConflictError(key);
+        }
+        const id = crypto.randomUUID();
+        await attachExecute(new QueryBuilder().from('hazo_app_state'), this.db).execute('POST', {
+            id,
+            state_key: key,
+            scope_id: scope_id ?? null,
+            user_id: user_id ?? null,
+            value: serialized,
+            protected: isProtected ? 1 : 0,
+            version: 1,
+            expires_at: expiresAt ?? null,
+            created_at: now,
+            updated_at: now,
+        });
+        return { value, version: 1 };
+    }
+    /**
+     * Atomically append an item to a stored array, capping at maxLen (oldest items dropped).
+     * Uses a CAS retry loop — safe under concurrent writes.
+     */
+    async appendToWindow(key, item, maxLen, opts = {}) {
+        const MAX_RETRIES = 10;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            const current = await this.get(key, opts);
+            const arr = Array.isArray(current?.value) ? current.value : [];
+            const newArr = [...arr, item].slice(-maxLen);
+            try {
+                await this.set(key, newArr, {
+                    ...opts,
+                    expectedVersion: current ? current.version : 0,
+                });
+                return;
+            }
+            catch (err) {
+                if (err instanceof ConflictError && attempt < MAX_RETRIES - 1)
+                    continue;
+                throw err;
+            }
+        }
+    }
+    /**
+     * Atomically increment a stored number by n (default 1).
+     * Uses a CAS retry loop. Returns the new value.
+     */
+    async increment(key, n = 1, opts = {}) {
+        const MAX_RETRIES = 10;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            const current = await this.get(key, opts);
+            const num = typeof current?.value === 'number' ? current.value : 0;
+            const newNum = num + n;
+            try {
+                await this.set(key, newNum, {
+                    ...opts,
+                    expectedVersion: current ? current.version : 0,
+                });
+                return newNum;
+            }
+            catch (err) {
+                if (err instanceof ConflictError && attempt < MAX_RETRIES - 1)
+                    continue;
+                throw err;
+            }
+        }
+        throw new ConflictError(key);
+    }
+    /**
+     * Delete a state entry. No-op if absent.
+     */
+    async delete(key, opts = {}) {
+        const qb = this.buildKeyQuery(key, opts.scope_id, opts.user_id);
+        await attachExecute(qb, this.db).execute('DELETE');
+    }
+    /**
+     * Delete all rows where expires_at is in the past.
+     * Intended to be called from a scheduled job / cron.
+     */
+    async sweepExpired() {
+        const now = new Date().toISOString();
+        const qb = new QueryBuilder().from('hazo_app_state');
+        qb.where('expires_at', 'lt', now);
+        const rows = await attachExecute(qb, this.db).execute('GET');
+        if (!Array.isArray(rows) || rows.length === 0)
+            return 0;
+        for (const row of rows) {
+            const delQb = new QueryBuilder().from('hazo_app_state').where('id', 'eq', row.id);
+            await attachExecute(delQb, this.db).execute('DELETE');
+        }
+        return rows.length;
+    }
+}
+/**
+ * Create Next.js route handlers for hazo_state.
+ *
+ * Mount at `app/api/hazo-state/route.ts`:
+ * ```ts
+ * const handlers = createStateRoute(getHazoConnectSingleton(), { resolveAuth, protectedKeys })
+ * export const { GET, PUT, POST, DELETE } = handlers
+ * ```
+ */
+export function createStateRoute(db, opts) {
+    const service = new HazoState(db);
+    const { resolveAuth, protectedKeys = [] } = opts;
+    async function resolveGetOpts(_key, level = 'global', auth) {
+        return resolveIds(level, auth);
+    }
+    async function checkProtectedWrite(key, auth) {
+        const spec = matchesProtectedKey(key, protectedKeys);
+        if (!spec)
+            return null;
+        const perm = spec.permission ?? 'manage_global_config';
+        if (!auth.hasPermission(perm)) {
+            return new Response(JSON.stringify({ error: 'Forbidden', permission: perm }), {
+                status: 403,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        return null;
+    }
+    return {
+        async GET(req) {
+            try {
+                const url = new URL(req.url);
+                const key = url.searchParams.get('key');
+                if (!key)
+                    return jsonError('key is required', 400);
+                const level = (url.searchParams.get('level') ?? 'global');
+                const auth = await resolveAuth(req);
+                const getOpts = await resolveGetOpts(key, level, auth);
+                const entry = await service.get(key, getOpts);
+                if (!entry)
+                    return new Response(null, { status: 404 });
+                return jsonOk(entry);
+            }
+            catch (err) {
+                return jsonError(errorMessage(err), 500);
+            }
+        },
+        async PUT(req) {
+            try {
+                const body = await req.json();
+                const { key, value, level = 'global', expectedVersion, expiresAt } = body;
+                if (!key)
+                    return jsonError('key is required', 400);
+                const auth = await resolveAuth(req);
+                const guardRes = await checkProtectedWrite(key, auth);
+                if (guardRes)
+                    return guardRes;
+                const getOpts = await resolveGetOpts(key, level, auth);
+                const spec = matchesProtectedKey(key, protectedKeys);
+                const entry = await service.set(key, value, {
+                    ...getOpts,
+                    expectedVersion,
+                    expiresAt,
+                    isProtected: spec !== null,
+                });
+                return jsonOk(entry);
+            }
+            catch (err) {
+                if (err instanceof ConflictError)
+                    return jsonError(err.message, 409);
+                return jsonError(errorMessage(err), 500);
+            }
+        },
+        async POST(req) {
+            try {
+                const body = await req.json();
+                const { key, level = 'global', op } = body;
+                if (!key)
+                    return jsonError('key is required', 400);
+                if (!op)
+                    return jsonError('op is required', 400);
+                const auth = await resolveAuth(req);
+                const guardRes = await checkProtectedWrite(key, auth);
+                if (guardRes)
+                    return guardRes;
+                const getOpts = await resolveGetOpts(key, level, auth);
+                if (op.op === 'append') {
+                    await service.appendToWindow(key, op.value, op.maxLen, getOpts);
+                    return jsonOk({ ok: true });
+                }
+                if (op.op === 'increment') {
+                    const newVal = await service.increment(key, op.n, getOpts);
+                    return jsonOk({ value: newVal });
+                }
+                return jsonError('unknown op', 400);
+            }
+            catch (err) {
+                if (err instanceof ConflictError)
+                    return jsonError(err.message, 409);
+                return jsonError(errorMessage(err), 500);
+            }
+        },
+        async DELETE(req) {
+            try {
+                const url = new URL(req.url);
+                const key = url.searchParams.get('key');
+                if (!key)
+                    return jsonError('key is required', 400);
+                const level = (url.searchParams.get('level') ?? 'global');
+                const auth = await resolveAuth(req);
+                const guardRes = await checkProtectedWrite(key, auth);
+                if (guardRes)
+                    return guardRes;
+                const getOpts = await resolveGetOpts(key, level, auth);
+                await service.delete(key, getOpts);
+                return new Response(null, { status: 204 });
+            }
+            catch (err) {
+                return jsonError(errorMessage(err), 500);
+            }
+        },
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function jsonOk(data) {
+    return new Response(JSON.stringify(data), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function jsonError(message, status) {
+    return new Response(JSON.stringify({ error: message }), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/migrations/001_hazo_app_state.sql

@@ -0,0 +1,33 @@
+-- hazo_app_state: generic transactional KV store for the hazo ecosystem.
+-- Supports 4 visibility levels (global/scope/user_global/user), TTL, optimistic
+-- concurrency (version column), and protected/gated-write entries.
+
+CREATE TABLE IF NOT EXISTS hazo_app_state (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  scope_id    UUID,                               -- NULL = not scope-bound
+  user_id     UUID,                               -- NULL = not user-bound
+  state_key   TEXT NOT NULL,
+  value       JSONB,
+  protected   BOOLEAN NOT NULL DEFAULT FALSE,     -- immutable after creation; gated-write
+  version     BIGINT NOT NULL DEFAULT 1,          -- optimistic-concurrency token
+  expires_at  TIMESTAMPTZ,                        -- NULL = no expiry (lazy TTL)
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Unique constraint: one entry per (scope_id, user_id, state_key) combination.
+-- NULL values in scope_id/user_id are treated as distinct levels, not wildcards.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_app_state_unique
+  ON hazo_app_state (
+    COALESCE(scope_id, '00000000-0000-0000-0000-000000000000'::uuid),
+    COALESCE(user_id,  '00000000-0000-0000-0000-000000000000'::uuid),
+    state_key
+  );
+
+-- Partial index for efficient TTL sweep.
+CREATE INDEX IF NOT EXISTS idx_hazo_app_state_expires
+  ON hazo_app_state (expires_at)
+  WHERE expires_at IS NOT NULL;
+
+-- PostgREST requires explicit grants.
+GRANT SELECT, INSERT, UPDATE, DELETE ON hazo_app_state TO api_user;

package/migrations/001_hazo_app_state_sqlite.sql

@@ -0,0 +1,26 @@
+-- SQLite-compatible variant of 001_hazo_app_state.sql for test-apps and local dev.
+-- Differences: no gen_random_uuid() (app provides id), no partial indexes, no GRANT.
+
+CREATE TABLE IF NOT EXISTS hazo_app_state (
+  id          TEXT PRIMARY KEY,
+  scope_id    TEXT,
+  user_id     TEXT,
+  state_key   TEXT NOT NULL,
+  value       TEXT,                               -- JSON stored as text in SQLite
+  protected   INTEGER NOT NULL DEFAULT 0,         -- 0=false, 1=true
+  version     INTEGER NOT NULL DEFAULT 1,
+  expires_at  TEXT,                               -- ISO 8601 string
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_app_state_unique
+  ON hazo_app_state (
+    COALESCE(scope_id, ''),
+    COALESCE(user_id, ''),
+    state_key
+  );
+
+CREATE INDEX IF NOT EXISTS idx_hazo_app_state_expires
+  ON hazo_app_state (expires_at)
+  WHERE expires_at IS NOT NULL;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "hazo_state",
+  "version": "0.1.2",
+  "description": "Generic transactional KV store for the hazo ecosystem — TTL, optimistic CAS, atomic helpers, turnkey route/client",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "migrations",
+    "CHANGE_LOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    },
+    "./migrations/*": "./migrations/*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev:test-app": "npm run build && cd test-app && npm run dev",
+    "build:test-app": "npm run build && cd test-app && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pub12/hazo_state.git"
+  },
+  "keywords": [
+    "state",
+    "kv",
+    "store",
+    "ttl",
+    "cas",
+    "hazo"
+  ],
+  "author": "Pubs Abayasiri",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "hazo_connect": "^3.5.1",
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "@types/react": "^18.3.3",
+    "typescript": "^5.7.2",
+    "vitest": "^1.6.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}