@doync/react 0.1.0

package/dist/use-client-D1I3o0t5.cjs

@@ -0,0 +1 @@
+let e=require("react");function t(t,r,a){let[o,s]=(0,e.useState)(null),c=(0,e.useRef)({client:null,options:null}),l=(0,e.useRef)(r);l.current=r;let u=(0,e.useRef)(a);return u.current=a,(0,e.useLayoutEffect)(()=>{let e=c.current.options,r=t,a=c.current.client,o=l.current,d=u.current;if(r!==null&&e!==null&&a!==null){if(i(e,r,d)){c.current.options=r;return}let t=n(e,r,a,o,d);t===null?c.current.options=r:(c.current={client:t,options:r},s(t));return}if(r!==null&&(e===null||a===null)){let e=o(r);c.current={client:e,options:r},s(e);return}r===null&&a!==null&&(a.close(),c.current={client:null,options:null},s(null))}),(0,e.useLayoutEffect)(()=>()=>{c.current.client?.close(),c.current={client:null,options:null}},[]),o}function n(e,t,n,i,o){for(let n of s(o))if(o[n]===`throw`&&!a(e[n],t[n]))throw Error(`doync: useClient cannot change ${String(n)} after creation — close and recreate with the new value`);for(let r of s(o))if(o[r]===`identity`&&!a(e[r],t[r]))return n.close(),i(t);let c=r(e,t,o);c!==null&&n.setAuth(c);for(let r of s(o))if(o[r]===`logoutBehavior`&&!a(e[r],t[r])){let e=t[r];e!==void 0&&n.setLogoutBehavior(e)}return null}function r(e,t,n){let r=!1,i=!1,o=!1,c=!1,l,u,d;for(let f of s(n)){if(n[f]!==`auth`)continue;let s=f,p=s===`ctx`;a(e[f],t[f],p)||(r=!0),s===`token`?(i=!0,l=t[f]):s===`userId`?(o=!0,u=t[f]):s===`ctx`&&(c=!0,d=t[f])}if(!r)return null;let f={token:i?l??null:e.token??null,userId:o?u??null:e.userId??null};return c?f.ctx=d:`ctx`in e&&(f.ctx=e.ctx),f}function i(e,t,n){for(let r of s(n)){let i=n[r];if(i===void 0||i===`ignore`)continue;let o=i===`auth`&&r===`ctx`;if(!a(e[r],t[r],o))return!1}return!0}function a(e,t,n=!1){return n?o(e)===o(t):Object.is(e,t)}function o(e){try{return JSON.stringify(e)??`undefined`}catch{return`\0ref:${typeof e}`}}function s(e){return Object.keys(e)}Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/dist/use-client-DanwzoBF.js

@@ -0,0 +1,2 @@
+import{useLayoutEffect as e,useRef as t,useState as n}from"react";function r(r,a,s){let[c,l]=n(null),u=t({client:null,options:null}),d=t(a);d.current=a;let f=t(s);return f.current=s,e(()=>{let e=u.current.options,t=r,n=u.current.client,a=d.current,s=f.current;if(t!==null&&e!==null&&n!==null){if(o(e,t,s)){u.current.options=t;return}let r=i(e,t,n,a,s);r===null?u.current.options=t:(u.current={client:r,options:t},l(r));return}if(t!==null&&(e===null||n===null)){let e=a(t);u.current={client:e,options:t},l(e);return}t===null&&n!==null&&(n.close(),u.current={client:null,options:null},l(null))}),e(()=>()=>{u.current.client?.close(),u.current={client:null,options:null}},[]),c}function i(e,t,n,r,i){for(let n of l(i))if(i[n]===`throw`&&!s(e[n],t[n]))throw Error(`doync: useClient cannot change ${String(n)} after creation — close and recreate with the new value`);for(let a of l(i))if(i[a]===`identity`&&!s(e[a],t[a]))return n.close(),r(t);let o=a(e,t,i);o!==null&&n.setAuth(o);for(let r of l(i))if(i[r]===`logoutBehavior`&&!s(e[r],t[r])){let e=t[r];e!==void 0&&n.setLogoutBehavior(e)}return null}function a(e,t,n){let r=!1,i=!1,a=!1,o=!1,c,u,d;for(let f of l(n)){if(n[f]!==`auth`)continue;let l=f,p=l===`ctx`;s(e[f],t[f],p)||(r=!0),l===`token`?(i=!0,c=t[f]):l===`userId`?(a=!0,u=t[f]):l===`ctx`&&(o=!0,d=t[f])}if(!r)return null;let f={token:i?c??null:e.token??null,userId:a?u??null:e.userId??null};return o?f.ctx=d:`ctx`in e&&(f.ctx=e.ctx),f}function o(e,t,n){for(let r of l(n)){let i=n[r];if(i===void 0||i===`ignore`)continue;let a=i===`auth`&&r===`ctx`;if(!s(e[r],t[r],a))return!1}return!0}function s(e,t,n=!1){return n?c(e)===c(t):Object.is(e,t)}function c(e){try{return JSON.stringify(e)??`undefined`}catch{return`\0ref:${typeof e}`}}function l(e){return Object.keys(e)}export{r as t};
+//# sourceMappingURL=use-client-DanwzoBF.js.map

package/dist/use-client-DanwzoBF.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-client-DanwzoBF.js","names":[],"sources":["../src/use-client.ts"],"sourcesContent":["/**\n * Generic client lifecycle hook. Holds a client for as long as the options bag\n * is non-null and routes option changes onto `createClient` / `close` /\n * `setAuth` / `setLogoutBehavior`, or throws — never invents its own lifecycle.\n * Platform wrappers (`useMobileClient`, `useWebClient`) supply the factory and\n * a {@link ClientOptionPolicy}; this module imports no platform package.\n *\n * Options are compared by value (fresh object literals every render are fine;\n * no `useMemo` required). `ctx` is compared by JSON. StrictMode double-mount is\n * create → close → create and is safe: ownership lives in a layout-effect\n * cleanup, not in render.\n */\n\nimport type { LogoutBehavior } from '@doync/client'\n\nimport { useLayoutEffect, useRef, useState } from 'react'\n\n/**\n * Minimum call surface the hook routes onto. Platform clients (`MobileClient`,\n * `WebClient`) both satisfy this; tests inject a fake.\n */\nexport interface ClientLifecycle {\n  close(): void\n  setAuth(auth: {\n    token: string | null\n    ctx?: unknown\n    userId: string | null\n  }): void\n  setLogoutBehavior(behavior: LogoutBehavior): void\n}\n\n/**\n * How a single options-bag key is handled when its value changes between\n * renders. Keys absent from the policy are not compared (construction-only\n * values like `schema` / `queries` — module-level constants in real apps).\n *\n * - `identity` — close the old client and create a new one (e.g. a different\n *   database `name` is a different client; no in-place path).\n * - `auth` — `token` / `userId` / `ctx` feed a single `setAuth` call (`ctx` is\n *   compared by JSON).\n * - `logoutBehavior` — call `setLogoutBehavior`.\n * - `throw` — value change throws (e.g. `url`). Checked before `identity`, so a\n *   same-render name+url swap cannot silently reconnect elsewhere.\n * - `ignore` — captured at creation; later changes are ignored (e.g. web's\n *   `worker` factory, whose required inline-literal form makes the reference\n *   unstable across renders).\n */\nexport type OptionDisposition =\n  | 'identity'\n  | 'auth'\n  | 'logoutBehavior'\n  | 'throw'\n  | 'ignore'\n\n/**\n * Per-platform table mapping option keys to {@link OptionDisposition}. Keys not\n * listed are not compared; unknown keys on the options bag are ignored.\n */\nexport type ClientOptionPolicy<TOptions extends object> = {\n  readonly [K in keyof TOptions]?: OptionDisposition\n}\n\n/** Live ownership slot shared by the diff effect and the unmount cleanup. */\ninterface Owned<TOptions, TClient> {\n  client: TClient | null\n  options: TOptions | null\n}\n\n// ADR-0034 / closeio/doync#281 — routes onto create/close/setAuth/\n// setLogoutBehavior; throw-before-identity; name-swap recreates.\n/**\n * Hold a client for as long as `options` is non-null. Pass `null` until the\n * database id is known (e.g. after a create-session mutation acks). Option\n * changes route onto client verbs per `policy` — see\n * {@link OptionDisposition}.\n */\nexport function useClient<\n  TOptions extends object,\n  TClient extends ClientLifecycle,\n>(\n  options: TOptions | null,\n  createClient: (options: TOptions) => TClient,\n  policy: ClientOptionPolicy<TOptions>,\n): TClient | null {\n  const [client, setClient] = useState<TClient | null>(null)\n  // Ownership lives in a ref so the unmount cleanup and the diff path share one\n  // source of truth without putting unstable identities into effect deps.\n  const owned = useRef<Owned<TOptions, TClient>>({\n    client: null,\n    options: null,\n  })\n  const createRef = useRef(createClient)\n  createRef.current = createClient\n  const policyRef = useRef(policy)\n  policyRef.current = policy\n\n  // Diff-and-route runs after every commit. Equal-by-value options are a no-op\n  // so a fresh options literal every render neither recreates nor re-verbs.\n  // Creation/teardown ownership lives here — NOT in render — so StrictMode's\n  // double-mount is create → cleanup-close → create, and nothing leaks.\n  useLayoutEffect(() => {\n    const prev = owned.current.options\n    const next = options\n    const current = owned.current.client\n    const create = createRef.current\n    const pol = policyRef.current\n\n    if (next !== null && prev !== null && current !== null) {\n      if (optionsEqualByPolicy(prev, next, pol)) {\n        // Keep the latest reference so subsequent diffs start from what the\n        // caller last passed (in case a nested object was mutated — rare; the\n        // equality check already saw them as equal).\n        owned.current.options = next\n        return\n      }\n      const created = applyChange(prev, next, current, create, pol)\n      if (created !== null) {\n        owned.current = { client: created, options: next }\n        setClient(created)\n      } else {\n        // In-place verb path: live client kept, snapshot advances.\n        owned.current.options = next\n      }\n      return\n    }\n\n    if (next !== null && (prev === null || current === null)) {\n      // null → options (or remount after StrictMode cleanup cleared the refs).\n      const created = create(next)\n      owned.current = { client: created, options: next }\n      setClient(created)\n      return\n    }\n\n    if (next === null && current !== null) {\n      // options → null: close and drop.\n      current.close()\n      owned.current = { client: null, options: null }\n      setClient(null)\n    }\n  })\n\n  // Unmount-only cleanup. Separate effect so the diff path above can re-run on\n  // every options-change commit WITHOUT closing between equal renders.\n  useLayoutEffect(() => {\n    return () => {\n      owned.current.client?.close()\n      owned.current = { client: null, options: null }\n    }\n  }, [])\n\n  return client\n}\n\n// ── internals ──────────────────────────────────────────────────────────────\n\n/**\n * Route a non-equal options change onto existing verbs. Returns a freshly\n * created client when identity keys moved (after closing the old one); returns\n * null when the live client was kept (auth / logoutBehavior routing, or throw\n * aborted before any mutation — throw propagates).\n */\nfunction applyChange<TOptions extends object, TClient extends ClientLifecycle>(\n  prev: TOptions,\n  next: TOptions,\n  current: TClient,\n  create: (options: TOptions) => TClient,\n  policy: ClientOptionPolicy<TOptions>,\n): TClient | null {\n  // Throw-on-change FIRST (url): a config bug must never silently reconnect\n  // elsewhere, even when bundled with a name swap that would otherwise rebuild.\n  for (const key of policyKeys(policy)) {\n    if (policy[key] !== 'throw') continue\n    if (!valueEqual(prev[key], next[key])) {\n      throw new Error(\n        `doync: useClient cannot change ${String(key)} after creation — close and recreate with the new value`,\n      )\n    }\n  }\n\n  // Identity keys — a name swap is a different Client; no in-place path. Fresh\n  // create carries the full next bag (auth/logout already in the new options).\n  for (const key of policyKeys(policy)) {\n    if (policy[key] !== 'identity') continue\n    if (!valueEqual(prev[key], next[key])) {\n      current.close()\n      return create(next)\n    }\n  }\n\n  // Auth triple — one setAuth if any of token/userId/ctx drifted.\n  const auth = resolveAuthTriple(prev, next, policy)\n  if (auth !== null) current.setAuth(auth)\n\n  // logoutBehavior — only call when it actually moved.\n  for (const key of policyKeys(policy)) {\n    if (policy[key] !== 'logoutBehavior') continue\n    if (!valueEqual(prev[key], next[key])) {\n      const behavior = next[key] as LogoutBehavior | undefined\n      if (behavior !== undefined) current.setLogoutBehavior(behavior)\n    }\n  }\n\n  return null\n}\n\n/**\n * Returns the asserted auth triple when any policy-`auth` key moved, else null.\n * setAuth's contract is a full identity assert, never a patch — fall back to\n * prev for any auth key the next bag omitted.\n */\nfunction resolveAuthTriple<TOptions extends object>(\n  prev: TOptions,\n  next: TOptions,\n  policy: ClientOptionPolicy<TOptions>,\n): {\n  token: string | null\n  userId: string | null\n  ctx?: unknown\n} | null {\n  let changed = false\n  let sawToken = false\n  let sawUserId = false\n  let sawCtx = false\n  let token: unknown\n  let userId: unknown\n  let ctx: unknown\n  for (const key of policyKeys(policy)) {\n    if (policy[key] !== 'auth') continue\n    const pk = key as keyof TOptions & string\n    const serialize = pk === 'ctx'\n    if (!valueEqual(prev[key], next[key], serialize)) changed = true\n    if (pk === 'token') {\n      sawToken = true\n      token = next[key]\n    } else if (pk === 'userId') {\n      sawUserId = true\n      userId = next[key]\n    } else if (pk === 'ctx') {\n      sawCtx = true\n      ctx = next[key]\n    }\n  }\n  if (!changed) return null\n  const auth: {\n    token: string | null\n    userId: string | null\n    ctx?: unknown\n  } = {\n    token: sawToken\n      ? ((token as string | null | undefined) ?? null)\n      : ((prev as { token?: string | null }).token ?? null),\n    userId: sawUserId\n      ? ((userId as string | null | undefined) ?? null)\n      : ((prev as { userId?: string | null }).userId ?? null),\n  }\n  if (sawCtx) auth.ctx = ctx\n  else if ('ctx' in (prev as object)) {\n    auth.ctx = (prev as { ctx?: unknown }).ctx\n  }\n  return auth\n}\n\nfunction optionsEqualByPolicy<TOptions extends object>(\n  a: TOptions,\n  b: TOptions,\n  policy: ClientOptionPolicy<TOptions>,\n): boolean {\n  for (const key of policyKeys(policy)) {\n    const disposition = policy[key]\n    if (disposition === undefined || disposition === 'ignore') continue\n    const serialize = disposition === 'auth' && key === 'ctx'\n    if (!valueEqual(a[key], b[key], serialize)) return false\n  }\n  return true\n}\n\nfunction valueEqual(a: unknown, b: unknown, serialize = false): boolean {\n  // ctx compared serialized (shared-hub posture, ADR-0034) when asked.\n  if (serialize) return jsonStable(a) === jsonStable(b)\n  return Object.is(a, b)\n}\n\nfunction jsonStable(value: unknown): string {\n  try {\n    return JSON.stringify(value) ?? 'undefined'\n  } catch {\n    // Non-serializable ctx: fall back to type tag so a throw here never\n    // bubbles out of a compare. Reference identity is lost — non-JSON ctx is\n    // already outside the hub's contract.\n    return `\\0ref:${typeof value}`\n  }\n}\n\nfunction policyKeys<TOptions extends object>(\n  policy: ClientOptionPolicy<TOptions>,\n): (keyof TOptions)[] {\n  return Object.keys(policy) as (keyof TOptions)[]\n}\n"],"mappings":"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"}

package/dist/web.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./use-client-D1I3o0t5.cjs");let t=require("@doync/web");const n={name:`identity`,url:`throw`,token:`auth`,userId:`auth`,ctx:`auth`,logoutBehavior:`logoutBehavior`,worker:`ignore`};function r(r){return e.t(r,t.createWebClient,n)}exports.useWebClient=r;

package/dist/web.d.cts

@@ -0,0 +1,13 @@
+import { CreateWebClientOptions, WebClient } from "@doync/web";
+
+//#region src/web.d.ts
+/**
+* Hold a {@link WebClient} for as long as `options` is non-null. Auth and
+* logout-behavior changes apply in place; a `name` change recreates the client;
+* a `url` change throws; `worker` is fixed at creation. Pass `null` until the
+* database id is known, then hand the result to `<DoyncProvider>`.
+*/
+declare function useWebClient<TAuthData = unknown>(options: CreateWebClientOptions<TAuthData> | null): WebClient | null;
+//#endregion
+export { type CreateWebClientOptions, type WebClient, useWebClient };
+//# sourceMappingURL=web.d.cts.map

package/dist/web.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.cts","names":[],"sources":["../src/web.ts"],"mappings":";;;;;;;;;iBA4DgB,YAAA,sBACd,OAAA,EAAS,sBAAA,CAAuB,SAAA,WAC/B,SAAA"}

package/dist/web.d.ts

@@ -0,0 +1,13 @@
+import { CreateWebClientOptions, WebClient } from "@doync/web";
+
+//#region src/web.d.ts
+/**
+* Hold a {@link WebClient} for as long as `options` is non-null. Auth and
+* logout-behavior changes apply in place; a `name` change recreates the client;
+* a `url` change throws; `worker` is fixed at creation. Pass `null` until the
+* database id is known, then hand the result to `<DoyncProvider>`.
+*/
+declare function useWebClient<TAuthData = unknown>(options: CreateWebClientOptions<TAuthData> | null): WebClient | null;
+//#endregion
+export { type CreateWebClientOptions, type WebClient, useWebClient };
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","names":[],"sources":["../src/web.ts"],"mappings":";;;;;;;;;iBA4DgB,YAAA,sBACd,OAAA,EAAS,sBAAA,CAAuB,SAAA,WAC/B,SAAA"}

package/dist/web.js

@@ -0,0 +1,2 @@
+import{t as e}from"./use-client-DanwzoBF.js";import{createWebClient as t}from"@doync/web";const n={name:`identity`,url:`throw`,token:`auth`,userId:`auth`,ctx:`auth`,logoutBehavior:`logoutBehavior`,worker:`ignore`};function r(r){return e(r,t,n)}export{r as useWebClient};
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","names":[],"sources":["../src/web.ts"],"sourcesContent":["/**\n * `@doync/react/web` — {@link useWebClient}, a thin wrapper around\n * {@link useClient} that supplies `createWebClient` and the web option policy.\n * Imports `@doync/web` as an optional peer of `@doync/react`, so a mobile-only\n * app never pulls it in.\n *\n * ```ts\n * import { useWebClient } from '@doync/react/web'\n *\n * const client = useWebClient(\n *   id\n *     ? {\n *         name: id,\n *         worker: () =>\n *           new Worker(new URL('./worker.ts', import.meta.url), {\n *             type: 'module',\n *           }),\n *         url: 'wss://example.com/sync',\n *         token,\n *         userId,\n *         ctx,\n *       }\n *     : null,\n * )\n * // pass client to <DoyncProvider> once non-null\n * ```\n */\n\nimport type { CreateWebClientOptions, WebClient } from '@doync/web'\n\nimport { createWebClient } from '@doync/web'\n\nimport { useClient, type ClientOptionPolicy } from './use-client'\n\n/**\n * Web option dispositions (ADR-0034). Schema / queries / mutations (and any\n * monorepo-only injects on `CreateWebClientOptionsForTest`) are construction-\n * time constants — the hook does not police them (absent from the policy = not\n * compared).\n *\n * `url` is throw-on-change: a config bug cannot silently reconnect elsewhere.\n * `worker` is IGNORE: captured at creation; later changes are ignored — its\n * required inline-literal form makes the reference unstable across renders.\n */\nconst WEB_CLIENT_POLICY: ClientOptionPolicy<CreateWebClientOptions> = {\n  name: 'identity',\n  url: 'throw',\n  token: 'auth',\n  userId: 'auth',\n  ctx: 'auth',\n  logoutBehavior: 'logoutBehavior',\n  worker: 'ignore',\n}\n\n/**\n * Hold a {@link WebClient} for as long as `options` is non-null. Auth and\n * logout-behavior changes apply in place; a `name` change recreates the client;\n * a `url` change throws; `worker` is fixed at creation. Pass `null` until the\n * database id is known, then hand the result to `<DoyncProvider>`.\n */\nexport function useWebClient<TAuthData = unknown>(\n  options: CreateWebClientOptions<TAuthData> | null,\n): WebClient | null {\n  return useClient(\n    options as CreateWebClientOptions | null,\n    createWebClient,\n    WEB_CLIENT_POLICY as ClientOptionPolicy<CreateWebClientOptions>,\n  )\n}\n\nexport type { CreateWebClientOptions, WebClient }\n"],"mappings":"0FA4CA,MAAM,EAAgE,CACpE,KAAM,WACN,IAAK,QACL,MAAO,OACP,OAAQ,OACR,IAAK,OACL,eAAgB,iBAChB,OAAQ,QACV,EAQA,SAAgB,EACd,EACkB,CAClB,OAAO,EACL,EACA,EACA,CACF,CACF"}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@doync/react",
+  "version": "0.1.0",
+  "description": "doync React adapter: thin useQuery / useQueryOnce / useLocalQuery / useMutation hooks over the client call surface",
+  "keywords": [
+    "doync",
+    "hooks",
+    "local-first",
+    "react",
+    "sync-engine"
+  ],
+  "license": "MIT",
+  "author": "Vitor Buzinaro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/closeio/doync.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./web": {
+      "import": {
+        "types": "./dist/web.d.ts",
+        "default": "./dist/web.js"
+      },
+      "require": {
+        "types": "./dist/web.d.cts",
+        "default": "./dist/web.cjs"
+      }
+    },
+    "./mobile": {
+      "import": {
+        "types": "./dist/mobile.d.ts",
+        "default": "./dist/mobile.js"
+      },
+      "require": {
+        "types": "./dist/mobile.d.cts",
+        "default": "./dist/mobile.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "require": {
+        "types": "./dist/internal.d.cts",
+        "default": "./dist/internal.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@doync/client": "0.1.0",
+    "@doync/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.22.3",
+    "typescript": "^7.0.2",
+    "vitest": "4.1.9",
+    "@doync/mobile": "0.1.0",
+    "@doync/web": "0.1.0"
+  },
+  "peerDependencies": {
+    "@doync/mobile": "0.x",
+    "@doync/web": "0.x",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@doync/mobile": {
+      "optional": true
+    },
+    "@doync/web": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/hooks.tsx

@@ -0,0 +1,442 @@
+import type {
+  ConnectionStatus,
+  FalsyQuery,
+  MutationOptions,
+  MutationResult,
+  OnceView,
+  SchemaEvent,
+  SubscribeOptions,
+  View,
+  ViewStatus,
+} from '@doync/client'
+import type {
+  BoundQuery,
+  MutationDefinition,
+  QueryDefinition,
+  SqlValue,
+} from '@doync/core'
+
+import { isBoundQuery } from '@doync/core/internal'
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+
+import { useDoyncClient } from './provider'
+
+// ── useQuery (subscribe — the norm) ───────────────────────────────────────
+
+/**
+ * Options for {@link useQuery}: `ttl` (server warm-grace after unmount) and
+ * `skip`. One-ness is inferred from the bound query — there is no `one`
+ * option.
+ */
+export type UseQueryOptions = SubscribeOptions
+
+/**
+ * Live subscription to a bound query. Pass `queries.issues.open(args)`. Returns
+ * `[rows, status]` and updates as local writes and server sync move the rows.
+ *
+ * - Multi-row queries → `[readonly Row[], status]`
+ * - One-row (`` sql.one`…` `` / `findFirst`) → `[Row | undefined, status]`
+ * - Falsy (`cond && bound`) → `[undefined, { status: 'unknown' }]` (stable hooks)
+ * - `skip: true` → empty shaped like the query (`[]` or `undefined`), status
+ *   `unknown`
+ *
+ * Status runs `unknown` → `complete` on first confirmation, or `error` if the
+ * subscribe fails. Mount retains the shared handle; unmount releases it.
+ */
+
+// Non-falsy one-query.
+export function useQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, true>,
+  options?: UseQueryOptions,
+): [Row | undefined, ViewStatus]
+// Non-falsy multi-row.
+export function useQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, false>,
+  options?: UseQueryOptions,
+): [readonly Row[], ViewStatus]
+// Maybe one-query (argument can be falsy) — `| undefined` only here.
+export function useQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, true> | FalsyQuery,
+  options?: UseQueryOptions,
+): [Row | undefined, ViewStatus]
+// Maybe multi-row — rows themselves gain `| undefined` when no query.
+export function useQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, false> | FalsyQuery,
+  options?: UseQueryOptions,
+): [readonly Row[] | undefined, ViewStatus]
+// Implementation (boolean One + maybe).
+export function useQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, boolean> | FalsyQuery,
+  options?: UseQueryOptions,
+): [readonly Row[] | (Row | undefined) | undefined, ViewStatus] {
+  const client = useDoyncClient()
+  const skip = options?.skip ?? false
+  const falsy = isFalsyQuery(query)
+  // Falsy+skip in the key so toggles swap Views without reordering hooks.
+  // Creation pure (ADR-0023/Q3); bind pure (ADR-0027) — key name+JSON args.
+  const key = falsy
+    ? `|ttl=${options?.ttl ?? ''}|skip=${skip}|falsy=1`
+    : `${boundQueryKey(query)}|ttl=${options?.ttl ?? ''}|skip=${skip}|falsy=0`
+  const view = useMemo((): View<Row> => {
+    if (falsy) return INERT_VIEW as unknown as View<Row>
+    // BoundQuery through (ADR-0027 / #200); reject truthy impostors.
+    const bound = requireBoundQuery(query, 'useQuery')
+    return client.subscribe(bound as BoundQuery<Row, boolean>, {
+      ttl: options?.ttl,
+      skip,
+    }) as View<Row>
+    // identity is `key`, not object identity
+  }, [client, key])
+  useEffect(() => {
+    view.retain()
+    return () => view.release()
+  }, [view])
+  const rows = useViewRows(view)
+  const status = useViewStatus(view)
+  // One-ness inferred (#115): resolve locally for immediate shape (topology
+  // view.one is late; skipped never resolves). Falsy keep slot only.
+  const resolvedOne = useMemo(() => {
+    if (falsy) return false
+    const bound = query as BoundQuery<Row, boolean>
+    return resolvedOneness(bound.query, bound.args)
+  }, [key])
+
+  // Falsy (ADR-0027): rows undefined for both shapes; after hooks for order.
+  // Distinct from skip (shape-preserving empties with a bound query).
+  if (falsy) {
+    return [undefined, status]
+  }
+
+  // view.one is authoritative once known — must agree with local resolve or the
+  // resolve boundary disagrees (throw). LIMITATION: mixed resolvers
+  // (`args.x ? sql.one : sql`) have type-level One=false but runtime agreement,
+  // so this guard cannot fire; prefer pure sql.one/findFirst.
+  if (view.one !== undefined && view.one !== resolvedOne) {
+    throw new Error(
+      view.one
+        ? 'doync: the subscribed statement is a one-query (sql.one / findFirst) but this client resolved it as multi-row — the query definition disagrees across the resolve boundary'
+        : 'doync: the subscribed statement is multi-row but this client resolved it as a one-query — the query definition disagrees across the resolve boundary',
+    )
+  }
+  const one = view.one ?? resolvedOne
+  const value = one ? (rows.length > 0 ? (rows[0] as Row) : undefined) : rows
+  return [value, status]
+}
+
+/**
+ * Local one-ness (#115): same resolve the engine does at subscribe so shape is
+ * known before topology `view.one`. Unresolvable args ⇒ false (defer to
+ * view.one).
+ */
+function resolvedOneness(
+  query: QueryDefinition<unknown, unknown, boolean>,
+  args: unknown,
+): boolean {
+  try {
+    return query.resolve({ args })?.one ?? false
+  } catch {
+    return false
+  }
+}
+
+// ── useQueryOnce (cache-and-network Once) ─────────────────────────────
+
+/**
+ * Network half of a {@link useQueryOnce} read: `loading` → `success` / `error`,
+ * or `skipped` when the argument is falsy (no request started).
+ */
+export type OnceStatus = 'loading' | 'success' | 'error' | 'skipped'
+
+/**
+ * One-shot cache-and-network read. Rows come from the local replica
+ * immediately, then update when the server answer lands. `status` tracks the
+ * network half. Falsy argument → `[undefined, { status: 'skipped' }]` with
+ * stable hooks. StrictMode-safe (remount keeps the in-flight request).
+ */
+// Non-falsy: today's exact rows type.
+export function useQueryOnce<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, boolean>,
+): [readonly Row[], { readonly status: OnceStatus }]
+// Maybe (argument can be falsy) — rows gain `| undefined` only here.
+export function useQueryOnce<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, boolean> | FalsyQuery,
+): [readonly Row[] | undefined, { readonly status: OnceStatus }]
+export function useQueryOnce<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  query: BoundQuery<Row, boolean> | FalsyQuery,
+): [readonly Row[] | undefined, { readonly status: OnceStatus }] {
+  const client = useDoyncClient()
+  const falsy = isFalsyQuery(query)
+  const key = falsy ? 'falsy=1' : `${boundQueryKey(query)}|falsy=0`
+  const view = useMemo((): OnceView<Row> => {
+    if (falsy) return INERT_ONCE as unknown as OnceView<Row>
+    // BoundQuery through (ADR-0027 / #200).
+    const bound = requireBoundQuery(query, 'useQueryOnce')
+    return client.once(bound as BoundQuery<Row, boolean>) as OnceView<Row>
+  }, [client, key])
+  // Live network status; falsy returns skipped sync so bound→falsy never flash
+  // stale success/error (#197).
+  const [liveStatus, setLiveStatus] =
+    useState<Exclude<OnceStatus, 'skipped'>>('loading')
+  useEffect(() => {
+    // Commit owns Once (Q7). Falsy → nothing. Live starts network (cancels
+    // StrictMode dispose arm). Cleanup = Warm-tick dispose.
+    if (falsy) return
+    let active = true
+    setLiveStatus('loading')
+    view.server.then(
+      () => {
+        if (active) setLiveStatus('success')
+      },
+      () => {
+        if (active) setLiveStatus('error')
+      },
+    )
+    return () => {
+      active = false
+      view.dispose()
+    }
+  }, [view, falsy])
+  const status: OnceStatus = falsy ? 'skipped' : liveStatus
+  // Always read store (hook order); falsy → undefined.
+  const rows = useViewRows(view)
+  return [falsy ? undefined : rows, { status }]
+}
+
+// ── useLocalQuery (arbitrary SQL over the replica) ─────────────────────────
+
+/**
+ * SQL source for {@link useLocalQuery}: a string, `{ sql, params }`, a callback
+ * returning either, or falsy ("no local read").
+ */
+export type LocalSource =
+  | string
+  | { readonly sql: string; readonly params?: readonly SqlValue[] }
+  | (() =>
+      | string
+      | { readonly sql: string; readonly params?: readonly SqlValue[] })
+
+/**
+ * Run arbitrary SQL over the local replica reactively (aggregates, joins, …).
+ * Re-runs on local commits; never registered with the server — offline-capable
+ * and free to the Mirror. Falsy source → `[undefined, { status: 'unknown' }]`.
+ */
+export function useLocalQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  source: LocalSource,
+  params?: readonly SqlValue[],
+): [readonly Row[], ViewStatus]
+export function useLocalQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  source: LocalSource | FalsyQuery,
+  params?: readonly SqlValue[],
+): [readonly Row[] | undefined, ViewStatus]
+export function useLocalQuery<
+  Row extends Record<string, unknown> = Record<string, SqlValue>,
+>(
+  source: LocalSource | FalsyQuery,
+  params: readonly SqlValue[] = [],
+): [readonly Row[] | undefined, ViewStatus] {
+  const client = useDoyncClient()
+  const falsy = isFalsyQuery(source)
+  const resolved = falsy
+    ? null
+    : typeof source === 'function'
+      ? source()
+      : source
+  const sql =
+    resolved === null
+      ? ''
+      : typeof resolved === 'string'
+        ? resolved
+        : resolved.sql
+  const sqlParams =
+    resolved === null
+      ? params
+      : typeof resolved === 'string'
+        ? params
+        : (resolved.params ?? [])
+  const key = falsy ? 'falsy=1' : `${sql}|${JSON.stringify(sqlParams)}|falsy=0`
+  const view = useMemo((): View<Row> => {
+    if (falsy) return INERT_VIEW as unknown as View<Row>
+    return client.local<Row>(sql, ...sqlParams)
+  }, [client, key])
+  useEffect(() => {
+    view.retain()
+    return () => view.release()
+  }, [view])
+  // Both stores always (hook order). Live Local is always complete (#104).
+  const rows = useViewRows(view)
+  const status = useViewStatus(view)
+  if (falsy) return [undefined, status]
+  return [rows, status]
+}
+
+// ── useConnectionStatus (topology socket health) ──────────────────────────
+
+/**
+ * Live {@link ConnectionStatus} to the Mirror: `connecting` / `connected` /
+ * `disconnected` / `error` / `needs-auth`. Re-renders on every transition — use
+ * for a status pill, offline banner, or needs-auth → logout flow.
+ */
+export function useConnectionStatus(): ConnectionStatus {
+  const client = useDoyncClient()
+  return useSyncExternalStore(
+    useCallback(
+      (onChange: () => void) => client.onConnectionChange(onChange),
+      [client],
+    ),
+    () => client.connectionStatus,
+    () => client.connectionStatus,
+  )
+}
+
+// ── useMutation ────────────────────────────────────────────────────────────
+
+/**
+ * Registered mutation as a callable. Call with `args` to apply optimistically
+ * and push; returns `{ client, server }` — paint from `client`, await `server`
+ * for Origin confirmation.
+ */
+export function useMutation<Input = unknown>(
+  mutation: MutationDefinition<Input>,
+): (args: Input, options?: MutationOptions) => MutationResult {
+  const client = useDoyncClient()
+  return useCallback(
+    (args: Input, options?: MutationOptions) =>
+      client.mutate(mutation, args, options),
+    [client, mutation],
+  )
+}
+
+// ── useSchemaStatus ───────────────────────────────────────────────────────
+
+/**
+ * Current schema/recovery state, or `null` when nominal. Use for a deploy-skew
+ * / recovery banner — re-renders when the state clears too (a one-shot
+ * `onSchemaEvent` callback alone would stick after recovery).
+ */
+export function useSchemaStatus(): SchemaEvent | null {
+  const client = useDoyncClient()
+  return useSyncExternalStore(
+    useCallback(
+      (onChange: () => void) => client.onSchemaChange(onChange),
+      [client],
+    ),
+    () => client.schemaStatus,
+    () => client.schemaStatus,
+  )
+}
+
+// ── shared internals ───────────────────────────────────────────────────────
+
+/** Stable empty snapshots (fresh ones tear the store). */
+const EMPTY_ROWS: readonly Record<string, unknown>[] = Object.freeze([])
+const UNKNOWN_STATUS: ViewStatus = Object.freeze({ status: 'unknown' })
+
+/**
+ * Inert View for falsy useQuery/useLocalQuery (ADR-0027): no desire, empty,
+ * unknown, no-op retain. Hook adds undefined-rows (vs skip's shape-preserving
+ * empty). Module-stable.
+ */
+const INERT_VIEW: View<Record<string, unknown>> = {
+  current: () => EMPTY_ROWS,
+  status: () => UNKNOWN_STATUS,
+  onChange: () => () => {},
+  retain: () => {},
+  release: () => {},
+}
+
+/**
+ * Inert Once for falsy useQueryOnce (ADR-0027): no network. Hook reports
+ * skipped; never awaits server (does not settle).
+ */
+const INERT_ONCE: OnceView<Record<string, unknown>> = {
+  current: () => EMPTY_ROWS,
+  onChange: () => () => {},
+  dispose: () => {},
+  // Never settles — unused for the skipped status path.
+  server: new Promise(() => {}),
+}
+
+/** Track View rows via useSyncExternalStore (stable current() until change). */
+function useViewRows<Row extends Record<string, unknown>>(
+  view: View<Row> | OnceView<Row>,
+): readonly Row[] {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => view.onChange(onStoreChange),
+    [view],
+  )
+  const getSnapshot = useCallback(() => view.current(), [view])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/**
+ * Track {@link ViewStatus} via useSyncExternalStore (#105): same onChange as
+ * rows; stable until visible status changes.
+ */
+function useViewStatus<Row extends Record<string, unknown>>(
+  view: View<Row>,
+): ViewStatus {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => view.onChange(onStoreChange),
+    [view],
+  )
+  const getSnapshot = useCallback(() => view.status(), [view])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Dedup key for a bound-query call (name + args). */
+function boundQueryKey(bound: {
+  readonly query: { readonly name?: string }
+  readonly args: unknown
+}): string {
+  return `${bound.query.name ?? ''}|${JSON.stringify(bound.args ?? null)}`
+}
+
+/** `false | null | undefined` — the "no query" sentinel (ADR-0027). */
+function isFalsyQuery(value: unknown): value is FalsyQuery {
+  return value === false || value === null || value === undefined
+}
+
+/**
+ * BoundQuery check at the react surface (ADR-0027). Bare function → forget-
+ * to-call wording.
+ */
+function requireBoundQuery(
+  value: unknown,
+  surface: 'useQuery' | 'useQueryOnce',
+): BoundQuery {
+  if (isBoundQuery(value)) return value
+  if (typeof value === 'function') {
+    throw new Error(
+      `doync: ${surface} expected a BoundQuery — received a function; did you forget to call it?`,
+    )
+  }
+  throw new Error(
+    `doync: ${surface} expected a BoundQuery (produced by queries.…(args)), got ${typeof value === 'object' && value !== null ? 'an object' : String(value)}`,
+  )
+}