@doync/react 0.1.0

package/src/index.tsx

@@ -0,0 +1,61 @@
+/**
+ * `@doync/react` — thin hooks over the {@link DoyncClient} call surface
+ * (`subscribe` / `once` / `local` / `mutate`), plus the platform-agnostic
+ * {@link useClient} lifecycle hook. Render may compute (mint a handle — pure
+ * and discardable); only commit may own (`retain` in a mount effect, `release`
+ * on cleanup). Row and status subscriptions use `useSyncExternalStore` over a
+ * handle whose `current()` returns a stable array reference until the rows
+ * move. StrictMode and abandoned renders own nothing by construction.
+ *
+ * Environment packages stay out of this entry: `useMobileClient` and
+ * `useWebClient` live on `@doync/react/mobile` and `@doync/react/web` with
+ * `@doync/mobile` / `@doync/web` as optional peers. Pass any
+ * {@link DoyncClient} (or the lifecycle hook's return) to `<DoyncProvider>`.
+ *
+ * Query-taking hooks accept a {@link BoundQuery} (or falsy = "no query"):
+ * `useQuery(queries.issues.open(args))`. Binding is pure — a fresh BoundQuery
+ * per render does not bust memoization (the key is name + JSON args). Falsy
+ * keeps stable hook order with no subscription.
+ */
+
+export {
+  DoyncProvider,
+  type DoyncProviderProps,
+  useDoyncClient,
+} from './provider'
+export {
+  type LocalSource,
+  type OnceStatus,
+  useConnectionStatus,
+  useLocalQuery,
+  useMutation,
+  useQuery,
+  useQueryOnce,
+  useSchemaStatus,
+  type UseQueryOptions,
+} from './hooks'
+export {
+  useClient,
+  type ClientLifecycle,
+  type ClientOptionPolicy,
+  type OptionDisposition,
+} from './use-client'
+// Client call-surface family — apps import from here, never `@doync/client` (#269).
+export type {
+  ConnectionStatus,
+  DoyncClient,
+  FalsyQuery,
+  LogoutBehavior,
+  MutationOptions,
+  MutationResult,
+  OnceView,
+  PreloadHandle,
+  PreloadOptions,
+  QueryStatus,
+  SchemaEvent,
+  SchemaEventKind,
+  SubscribeOptions,
+  View,
+  ViewStatus,
+} from '@doync/client'
+export type { BoundQuery } from '@doync/core'

package/src/internal.ts

@@ -0,0 +1,11 @@
+/**
+ * `@doync/react/internal` (ADR-0033): placeholder entry — the current public
+ * surface stands. Kept so the nine-package `./internal` contract is uniform.
+ * May break in any release. Import React hooks/types from `@doync/react`.
+ *
+ * Main entry is `index.tsx` (TSX adapter); this file is extension-less so tsc
+ * resolves it the same way sibling imports do (allowImportingTsExtensions is
+ * off).
+ */
+
+export {}

package/src/mobile.ts

@@ -0,0 +1,68 @@
+/**
+ * `@doync/react/mobile` — {@link useMobileClient}, a thin wrapper around
+ * {@link useClient} that supplies `createMobileClient` and the mobile option
+ * policy. Imports `@doync/mobile` as an optional peer of `@doync/react`, so a
+ * web-only app never pulls it in.
+ *
+ * ```ts
+ * import { useMobileClient } from '@doync/react/mobile'
+ *
+ * const client = useMobileClient(
+ *   id
+ *     ? {
+ *         name: id,
+ *         schema,
+ *         queries,
+ *         mutations,
+ *         url: 'wss://example.com/sync',
+ *         token,
+ *         userId,
+ *         ctx,
+ *       }
+ *     : null,
+ * )
+ * // pass client to <DoyncProvider> once non-null
+ * ```
+ */
+
+import type { CreateMobileClientOptions, MobileClient } from '@doync/mobile'
+
+import { createMobileClient } from '@doync/mobile'
+
+import { useClient, type ClientOptionPolicy } from './use-client'
+
+/**
+ * Mobile option dispositions (ADR-0034). Schema / queries / mutations (and any
+ * monorepo-only injects on `CreateMobileClientOptionsForTest`) are
+ * construction- time constants — the hook does not police them (absent from the
+ * policy = not compared).
+ *
+ * `url` is throw-on-change: a config bug cannot silently reconnect elsewhere.
+ * There is no `worker` on mobile (single process).
+ */
+const MOBILE_CLIENT_POLICY: ClientOptionPolicy<CreateMobileClientOptions> = {
+  name: 'identity',
+  url: 'throw',
+  token: 'auth',
+  userId: 'auth',
+  ctx: 'auth',
+  logoutBehavior: 'logoutBehavior',
+}
+
+/**
+ * Hold a {@link MobileClient} 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. Pass `null` until the database id is known, then hand
+ * the result to `<DoyncProvider>`.
+ */
+export function useMobileClient<TAuthData = unknown>(
+  options: CreateMobileClientOptions<TAuthData> | null,
+): MobileClient | null {
+  return useClient(
+    options as CreateMobileClientOptions | null,
+    createMobileClient,
+    MOBILE_CLIENT_POLICY as ClientOptionPolicy<CreateMobileClientOptions>,
+  )
+}
+
+export type { CreateMobileClientOptions, MobileClient }

package/src/provider.tsx

@@ -0,0 +1,35 @@
+import type { DoyncClient } from '@doync/client'
+import type { ReactElement, ReactNode } from 'react'
+
+import { createContext, useContext } from 'react'
+
+const DoyncContext = createContext<DoyncClient | null>(null)
+
+/** Props for {@link DoyncProvider}. */
+export interface DoyncProviderProps {
+  /** Client from `createWebClient` / `createMobileClient` (or a test double). */
+  readonly client: DoyncClient
+  readonly children: ReactNode
+}
+
+/** Provide a {@link DoyncClient} to `useQuery`, `useMutation`, and siblings. */
+export function DoyncProvider({
+  client,
+  children,
+}: DoyncProviderProps): ReactElement {
+  return (
+    <DoyncContext.Provider value={client}>{children}</DoyncContext.Provider>
+  )
+}
+
+/**
+ * {@link DoyncClient} from the nearest {@link DoyncProvider}. Throws if used
+ * outside a provider.
+ */
+export function useDoyncClient(): DoyncClient {
+  const client = useContext(DoyncContext)
+  if (client === null) {
+    throw new Error('doync: a doync hook was used outside a <DoyncProvider>')
+  }
+  return client
+}

package/src/use-client.ts

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

package/src/web.ts

@@ -0,0 +1,71 @@
+/**
+ * `@doync/react/web` — {@link useWebClient}, a thin wrapper around
+ * {@link useClient} that supplies `createWebClient` and the web option policy.
+ * Imports `@doync/web` as an optional peer of `@doync/react`, so a mobile-only
+ * app never pulls it in.
+ *
+ * ```ts
+ * import { useWebClient } from '@doync/react/web'
+ *
+ * const client = useWebClient(
+ *   id
+ *     ? {
+ *         name: id,
+ *         worker: () =>
+ *           new Worker(new URL('./worker.ts', import.meta.url), {
+ *             type: 'module',
+ *           }),
+ *         url: 'wss://example.com/sync',
+ *         token,
+ *         userId,
+ *         ctx,
+ *       }
+ *     : null,
+ * )
+ * // pass client to <DoyncProvider> once non-null
+ * ```
+ */
+
+import type { CreateWebClientOptions, WebClient } from '@doync/web'
+
+import { createWebClient } from '@doync/web'
+
+import { useClient, type ClientOptionPolicy } from './use-client'
+
+/**
+ * Web option dispositions (ADR-0034). Schema / queries / mutations (and any
+ * monorepo-only injects on `CreateWebClientOptionsForTest`) are construction-
+ * time constants — the hook does not police them (absent from the policy = not
+ * compared).
+ *
+ * `url` is throw-on-change: a config bug cannot silently reconnect elsewhere.
+ * `worker` is IGNORE: captured at creation; later changes are ignored — its
+ * required inline-literal form makes the reference unstable across renders.
+ */
+const WEB_CLIENT_POLICY: ClientOptionPolicy<CreateWebClientOptions> = {
+  name: 'identity',
+  url: 'throw',
+  token: 'auth',
+  userId: 'auth',
+  ctx: 'auth',
+  logoutBehavior: 'logoutBehavior',
+  worker: 'ignore',
+}
+
+/**
+ * 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>`.
+ */
+export function useWebClient<TAuthData = unknown>(
+  options: CreateWebClientOptions<TAuthData> | null,
+): WebClient | null {
+  return useClient(
+    options as CreateWebClientOptions | null,
+    createWebClient,
+    WEB_CLIENT_POLICY as ClientOptionPolicy<CreateWebClientOptions>,
+  )
+}
+
+export type { CreateWebClientOptions, WebClient }