on-zero 0.4.36 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "on-zero",
-  "version": "0.4.36",
+  "version": "0.4.37",
   "description": "A typed layer over @rocicorp/zero with queries, mutations, and permissions",
   "sideEffects": false,
   "source": "src/index.ts",
@@ -65,6 +65,12 @@
       "import": "./dist/esm/vite-plugin.mjs",
       "require": "./dist/cjs/vite-plugin.cjs"
     },
+    "./multi": {
+      "react-native": "./dist/esm/multi.native.js",
+      "types": "./types/multi.d.ts",
+      "import": "./dist/esm/multi.mjs",
+      "require": "./dist/cjs/multi.cjs"
+    },
     "./drizzle": {
       "types": "./types/createSchemaFromDrizzle.d.ts",
       "import": "./dist/esm/createSchemaFromDrizzle.mjs",
@@ -77,7 +83,7 @@
     }
   },
   "dependencies": {
-    "@take-out/helpers": "0.4.36",
+    "@take-out/helpers": "0.4.37",
     "chokidar": "^4.0.3",
     "citty": "^0.1.6",
     "valibot": "^1.1.0"

package/readme.md

@@ -526,9 +526,10 @@ exactly one instance — duplicate claims throw at create time. then combine
 them into one consumer surface:
 
 ```tsx
-import { combineZeroClients, createZeroClient } from 'on-zero'
+import { createZeroClient } from 'on-zero'
+import { combineZeroClients, createZeroClientWithDirectQueries } from 'on-zero/multi'
 
-const control = createZeroClient({
+const control = createZeroClientWithDirectQueries({
   schema,
   models: controlModels,
   groupedQueries: controlQueries,
@@ -551,8 +552,8 @@ export const { useQuery, zero, run, preload, getQuery, zeroEvents } =
 // client passed to combineZeroClients (or the `inner` option) must be the
 // INNERMOST provider — zero-react's useQuery resolves the nearest provider's
 // instance from context, so only the inner instance rides that path. all
-// other instances' useQuery/usePermission go through a context-free direct
-// materialize on their own mounted zero.
+// other instances must opt into the context-free direct adapter through
+// createZeroClientWithDirectQueries.
 ;<control.ProvideZero server={controlUrl} userID={user.id}>
   <project.ProvideZero server={projectUrl} userID={`${user.id}:${projectId}`}>
     <App />
@@ -565,11 +566,12 @@ constraints:
 - each instance needs its own client-group identity (separate `userID` /
   storage key / server url) — never swap the backing namespace under a live
   instance.
+- most apps should use plain `createZeroClient`; the `on-zero/multi` entrypoint
+  is only for this nested-provider edge case.
 - give the INNER slot to the instance owning the bulk of the subscriptions —
-  inner queries keep zero-react's viewStore dedup + ttl. outer instances use
-  the direct path, which has no cross-component view dedup (each hook
-  materializes its own view), so keep outer instances on bounded, tiny
-  queries (current user, settings, directories).
+  inner queries use zero-react's native context path. outer instances use the
+  direct adapter on their own mounted zero, so keep those instances on bounded,
+  low-fanout queries (current user, settings, directories).
 - a mutator may only read/write tables owned by its own instance. its
   transaction runs on that instance alone; cross-instance writes are not
   detectable at registration and will silently miss the other store.

package/src/combineZeroClients.tsx

@@ -19,12 +19,10 @@ import type { ReactNode } from 'react'
 // provider is mounted INNERMOST — may use the upstream context path. by
 // default that is the LAST client passed here (override via the `inner`
 // option); the first client is primary and its provider is expected OUTER.
-// the inner instance's queries ride zero-react's useQuery unchanged, keeping
-// viewStore dedup + ttl — give that slot to the instance owning the bulk of
-// the subscriptions. every other instance's useQuery/usePermission route
-// through the context-free direct hooks (useQueryDirect), which materialize
-// on the owning instance but skip view dedup — keep those instances on
-// bounded, tiny queries.
+// the inner instance's queries ride zero-react's useQuery unchanged. every
+// other instance must be created through `createZeroClientWithDirectQueries`
+// from `on-zero/multi`, which opts into the context-free adapter for this
+// nested-provider edge case. keep those non-inner instances bounded.
 
 type ControlQueriesProps = {
   children: ReactNode

package/src/createUseQuery.tsx

@@ -1,13 +1,5 @@
 import { useQuery as zeroUseQuery } from '@rocicorp/zero/react'
-import { useEmitterValue, type Emitter } from '@take-out/helpers'
-import {
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useSyncExternalStore,
-  type Context,
-} from 'react'
+import { useContext, useMemo, useRef, type Context } from 'react'
 
 import { useZeroDebug } from './helpers/useZeroDebug'
 import { resolveQuery, type PlainQueryFn } from './resolveQuery'
@@ -50,7 +42,7 @@ export type UseQueryHook<Schema extends ZeroSchema> = {
 const EMPTY_RESPONSE = [null, { type: 'unknown' }] as never
 
 // determine if useQuery-style args are (fn, params, options) or (fn, options)
-function parseUseQueryArgs(paramsOrOptions: any, optionsArg: any) {
+export function parseUseQueryArgs(paramsOrOptions: any, optionsArg: any) {
   const hasParams =
     optionsArg !== undefined ||
     (paramsOrOptions &&
@@ -105,182 +97,3 @@ export function createUseQuery<Schema extends ZeroSchema>({
 
   return useQuery as UseQueryHook<Schema>
 }
-
-// --- direct (context-free) query path -------------------------------------
-
-// zero-react's useQuery resolves its zero instance via useZero() → react
-// context, i.e. the NEAREST mounted ZeroProvider. with multiple client
-// instances nested on one page, every context-path query would materialize
-// against the innermost provider's instance regardless of which instance owns
-// the query. this hook is the context-free counterpart: it materializes the
-// resolved query directly on the owning instance's mounted zero.
-//
-// tradeoffs vs the context path (acceptable for the bounded, tiny queries the
-// non-inner instances own — see combineZeroClients):
-//  - no cross-component view dedup (zero-react's viewStore): each hook
-//    instance materializes its own view.
-//  - no strict-mode double-render protection: a discarded render's view is
-//    not destroyed until the owning zero closes.
-
-const DISABLED_SUBSCRIBE = () => () => {}
-// upstream zero-react returns [undefined, {type:'unknown'}] when disabled
-const DISABLED_SNAPSHOT: readonly [undefined, { type: 'unknown' }] = [
-  undefined,
-  { type: 'unknown' },
-]
-const getDisabledSnapshot = () => DISABLED_SNAPSHOT
-
-type DirectView = {
-  subscribe: (notify: () => void) => () => void
-  getSnapshot: () => readonly [unknown, { type: string }]
-  destroy: () => void
-}
-
-// method syntax for bivariant param checks — the real Zero['materialize']
-// generic signature must remain assignable to this structural slice. ttl is
-// untyped pass-through here, matching the context path (zeroUseQuery's
-// options are equally unchecked against upstream's TTL type).
-type MaterializableZero = {
-  materialize(
-    query: any,
-    options?: { ttl?: any },
-  ): {
-    addListener(cb: (data: any, resultType: string) => void): void
-    destroy(): void
-  }
-}
-
-function createDirectView(
-  getZero: () => MaterializableZero | null,
-  queryRequest: unknown,
-  ttl: UseQueryOptions['ttl'],
-): DirectView {
-  let snapshot: readonly [unknown, { type: string }] = DISABLED_SNAPSHOT
-  const listeners = new Set<() => void>()
-  let view: { destroy(): void } | null = null
-
-  const materialize = () => {
-    const zero = getZero()
-    if (!zero) return
-    // zero.materialize accepts a QueryRequest (it applies the instance context
-    // itself) — the same public api the upstream ViewWrapper uses
-    const next = zero.materialize(queryRequest, ttl === undefined ? undefined : { ttl })
-    view = next
-
-    // addListener fires immediately with current data, so the snapshot is
-    // populated before react's first getSnapshot. data must be cloned: the
-    // underlying view mutates it in place, and useSyncExternalStore requires
-    // immutable snapshots to detect changes.
-    next.addListener((data, resultType) => {
-      snapshot = [
-        data === undefined ? undefined : structuredClone(data),
-        { type: resultType },
-      ]
-      for (const listener of listeners) {
-        listener()
-      }
-    })
-  }
-
-  // eager: snapshot is warm before react's first getSnapshot
-  materialize()
-
-  return {
-    subscribe: (notify) => {
-      listeners.add(notify)
-      // react runs effect cleanup + re-setup with unchanged deps under
-      // StrictMode double-invoke and suspense hide/reveal — the cleanup
-      // destroyed the view while this memoized store survived, so the
-      // resubscribe must re-materialize or the snapshot freezes forever
-      if (view === null) {
-        materialize()
-      }
-      return () => listeners.delete(notify)
-    },
-    getSnapshot: () => snapshot,
-    destroy: () => {
-      const current = view
-      view = null
-      if (!current) return
-      // identity rotation closes the owning zero before react runs this
-      // cleanup (the version bump that swaps the view is post-commit) — the
-      // closed instance already removed the view's ttl connection record, so
-      // zero's destroy asserts ("Connection not found"). destroy-after-close
-      // is semantically a no-op; swallow it instead of killing the route.
-      try {
-        current.destroy()
-      } catch {
-        // instance closed first — nothing left to tear down
-      }
-    },
-  }
-}
-
-export function createUseQueryDirect<Schema extends ZeroSchema>({
-  DisabledContext,
-  customQueries,
-  getZero,
-  zeroVersion,
-}: {
-  DisabledContext: Context<QueryControlMode>
-  customQueries: AnyQueryRegistry
-  // the owning instance's mounted zero (null before its provider mounts)
-  getZero: () => MaterializableZero | null
-  // bumps after commit whenever the mounted zero changes (mount, rotation)
-  zeroVersion: Emitter<number>
-}): UseQueryHook<Schema> {
-  function useQueryDirect(...args: any[]): any {
-    const disableMode = useContext(DisabledContext)
-    const lastRef = useRef<any>(EMPTY_RESPONSE)
-    const [fn, paramsOrOptions, optionsArg] = args
-
-    const version = useEmitterValue(zeroVersion)
-    const { params, options } = parseUseQueryArgs(paramsOrOptions, optionsArg)
-
-    let enabled = true
-    let ttl: UseQueryOptions['ttl']
-    if (typeof options === 'boolean') {
-      enabled = options
-    } else if (options) {
-      enabled = options.enabled !== false
-      ttl = options.ttl
-    }
-
-    // key the view by VALUE (serialized params), not params object identity —
-    // there is no view dedup on this path, so an unstable inline params object
-    // must not re-materialize every render
-    const paramsKey = params === undefined ? '' : JSON.stringify(params)
-
-    const view = useMemo((): DirectView | null => {
-      if (!enabled || !getZero()) return null
-      const queryRequest = resolveQuery({ customQueries, fn, params })
-      return createDirectView(getZero, queryRequest, ttl)
-      // params is keyed by paramsKey; version re-materializes on a new zero
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [fn, paramsKey, enabled, ttl, version])
-
-    useEffect(() => {
-      if (!view) return
-      return () => view.destroy()
-    }, [view])
-
-    const out = useSyncExternalStore(
-      view ? view.subscribe : DISABLED_SUBSCRIBE,
-      view ? view.getSnapshot : getDisabledSnapshot,
-      view ? view.getSnapshot : getDisabledSnapshot,
-    )
-
-    if (!disableMode) {
-      lastRef.current = out
-      return out
-    }
-
-    if (disableMode === 'last-value') {
-      return lastRef.current
-    }
-
-    return EMPTY_RESPONSE
-  }
-
-  return useQueryDirect as UseQueryHook<Schema>
-}

package/src/createUseQueryDirect.tsx

@@ -0,0 +1,307 @@
+import {
+  addContextToQuery,
+  asQueryInternals,
+  DEFAULT_TTL_MS,
+  deepClone,
+} from '@rocicorp/zero/bindings'
+import { useEmitterValue, type Emitter } from '@take-out/helpers'
+import { useContext, useMemo, useRef, useSyncExternalStore, type Context } from 'react'
+
+import {
+  parseUseQueryArgs,
+  type QueryControlMode,
+  type UseQueryHook,
+  type UseQueryOptions,
+} from './createUseQuery'
+import { resolveQuery } from './resolveQuery'
+
+import type {
+  AnyQueryRegistry,
+  ReadonlyJSONValue,
+  Schema as ZeroSchema,
+} from '@rocicorp/zero'
+
+// optional multi-instance adapter. normal apps should use zero-react's native
+// useQuery path via createZeroClient; this exists only for nested providers
+// where a non-innermost instance cannot be selected through react context.
+
+const EMPTY_RESPONSE = [null, { type: 'unknown' }] as never
+const DISABLED_SUBSCRIBE = () => () => {}
+const DISABLED_SNAPSHOT: readonly [undefined, { type: 'unknown' }] = [
+  undefined,
+  { type: 'unknown' },
+]
+const getDisabledSnapshot = () => DISABLED_SNAPSHOT
+
+type DirectSnapshot = readonly [unknown, { type: string }]
+
+type DirectView = {
+  subscribe: (notify: () => void) => () => void
+  getSnapshot: () => DirectSnapshot
+}
+
+export type MaterializableZero = {
+  clientID: string
+  context: unknown
+  materialize(
+    query: any,
+    options?: { ttl?: any },
+  ): {
+    addListener(
+      cb: (data: any, resultType: string, error?: DirectQueryError) => void,
+    ): void
+    destroy(): void
+    updateTTL(ttl: any): void
+  }
+}
+
+export type CreateUseQueryDirect<Schema extends ZeroSchema> = (props: {
+  DisabledContext: Context<QueryControlMode>
+  customQueries: AnyQueryRegistry
+  getZero: () => MaterializableZero | null
+  zeroVersion: Emitter<number>
+}) => UseQueryHook<Schema>
+
+type DirectResultType = 'unknown' | 'complete' | 'error'
+type DirectQueryError = {
+  error: 'app' | 'parse'
+  message?: string
+  details?: unknown
+}
+
+const emptyArray: readonly unknown[] = []
+const resultTypeUnknown = { type: 'unknown' } as const
+const resultTypeComplete = { type: 'complete' } as const
+const resultTypeError = { type: 'error' } as const
+const emptySnapshotSingularUnknown: DirectSnapshot = [undefined, resultTypeUnknown]
+const emptySnapshotSingularComplete: DirectSnapshot = [undefined, resultTypeComplete]
+const emptySnapshotSingularError: DirectSnapshot = [undefined, resultTypeError]
+const emptySnapshotPluralUnknown: DirectSnapshot = [emptyArray, resultTypeUnknown]
+const emptySnapshotPluralComplete: DirectSnapshot = [emptyArray, resultTypeComplete]
+const emptySnapshotPluralError: DirectSnapshot = [emptyArray, resultTypeError]
+
+function getDefaultSnapshot(singular: boolean) {
+  return singular ? emptySnapshotSingularUnknown : emptySnapshotPluralUnknown
+}
+
+function makeError(retry: () => void, error?: DirectQueryError) {
+  const message = error?.message ?? 'An unknown error occurred'
+  return {
+    type: 'error',
+    retry,
+    refetch: retry,
+    error: {
+      type: error?.error ?? 'app',
+      message,
+      ...(error?.details ? { details: error.details } : {}),
+    },
+  } as const
+}
+
+function getSnapshot(
+  singular: boolean,
+  data: unknown,
+  resultType: DirectResultType,
+  retry: () => void,
+  error?: DirectQueryError,
+): DirectSnapshot {
+  if (singular && data === undefined) {
+    if (resultType === 'complete') return emptySnapshotSingularComplete
+    if (resultType === 'error')
+      return error ? [undefined, makeError(retry, error)] : emptySnapshotSingularError
+    return emptySnapshotSingularUnknown
+  }
+
+  if (!singular && Array.isArray(data) && data.length === 0) {
+    if (resultType === 'complete') return emptySnapshotPluralComplete
+    if (resultType === 'error')
+      return error ? [emptyArray, makeError(retry, error)] : emptySnapshotPluralError
+    return emptySnapshotPluralUnknown
+  }
+
+  if (resultType === 'complete') return [data, resultTypeComplete]
+  if (resultType === 'error') return [data, makeError(retry, error)]
+  return [data, resultTypeUnknown]
+}
+
+class DirectViewWrapper implements DirectView {
+  private view: ReturnType<MaterializableZero['materialize']> | undefined
+  private snapshot: DirectSnapshot
+  private readonly listeners = new Set<() => void>()
+  private destroyTimer: ReturnType<typeof setTimeout> | undefined
+
+  constructor(
+    private readonly query: any,
+    private readonly zero: MaterializableZero,
+    private ttl: UseQueryOptions['ttl'] | number,
+    private readonly singular: boolean,
+    private readonly onDematerialized: (view: DirectViewWrapper) => void,
+  ) {
+    this.snapshot = getDefaultSnapshot(singular)
+    this.materializeIfNeeded()
+  }
+
+  private onData = (data: unknown, resultType: string, error?: DirectQueryError) => {
+    const cloned = data === undefined ? undefined : deepClone(data as ReadonlyJSONValue)
+    this.snapshot = getSnapshot(
+      this.singular,
+      cloned,
+      resultType as DirectResultType,
+      this.retry,
+      error,
+    )
+    for (const listener of this.listeners) {
+      listener()
+    }
+  }
+
+  private retry = () => {
+    this.destroyView()
+    this.materializeIfNeeded()
+  }
+
+  private materializeIfNeeded() {
+    if (this.view) return
+    this.view = this.zero.materialize(this.query, { ttl: this.ttl })
+    this.view.addListener(this.onData)
+  }
+
+  private destroyView() {
+    const current = this.view
+    this.view = undefined
+    if (!current) return
+    try {
+      current.destroy()
+    } catch {
+      // the owning zero can close before react unsubscribes during rotation
+    }
+  }
+
+  updateTTL(ttl: UseQueryOptions['ttl'] | number) {
+    this.ttl = ttl
+    this.view?.updateTTL(ttl)
+  }
+
+  subscribe = (notify: () => void) => {
+    this.listeners.add(notify)
+    if (this.destroyTimer !== undefined) {
+      clearTimeout(this.destroyTimer)
+      this.destroyTimer = undefined
+    }
+    this.materializeIfNeeded()
+
+    return () => {
+      this.listeners.delete(notify)
+      if (this.listeners.size === 0) {
+        this.destroyTimer = setTimeout(() => {
+          this.destroyTimer = undefined
+          if (this.listeners.size > 0) return
+          this.destroyView()
+          this.onDematerialized(this)
+        }, 10)
+      }
+    }
+  }
+
+  getSnapshot = () => this.snapshot
+}
+
+class DirectViewStore {
+  private readonly views = new Map<string, DirectViewWrapper>()
+
+  getView(
+    zero: MaterializableZero,
+    queryRequest: unknown,
+    enabled: boolean,
+    ttl: UseQueryOptions['ttl'] | number,
+  ): DirectView {
+    const query = addContextToQuery(queryRequest as any, zero.context as any)
+    const queryInternals = asQueryInternals(query)
+
+    if (!enabled) {
+      const snapshot = getDefaultSnapshot(queryInternals.format.singular)
+      return {
+        subscribe: DISABLED_SUBSCRIBE,
+        getSnapshot: () => snapshot,
+      }
+    }
+
+    const hash = `${zero.clientID}:${queryInternals.hash()}`
+    let view = this.views.get(hash)
+    if (!view) {
+      view = new DirectViewWrapper(
+        query,
+        zero,
+        ttl,
+        queryInternals.format.singular,
+        (dematerialized) => {
+          if (this.views.get(hash) === dematerialized) {
+            this.views.delete(hash)
+          }
+        },
+      )
+      this.views.set(hash, view)
+    } else {
+      view.updateTTL(ttl)
+    }
+
+    return view
+  }
+}
+
+export function createUseQueryDirect<Schema extends ZeroSchema>({
+  DisabledContext,
+  customQueries,
+  getZero,
+  zeroVersion,
+}: Parameters<CreateUseQueryDirect<Schema>>[0]): UseQueryHook<Schema> {
+  const directViewStore = new DirectViewStore()
+
+  function useQueryDirect(...args: any[]): any {
+    const disableMode = useContext(DisabledContext)
+    const lastRef = useRef<any>(EMPTY_RESPONSE)
+    const [fn, paramsOrOptions, optionsArg] = args
+
+    const version = useEmitterValue(zeroVersion)
+    const { params, options } = parseUseQueryArgs(paramsOrOptions, optionsArg)
+
+    let enabled = true
+    let ttl: UseQueryOptions['ttl'] | number = DEFAULT_TTL_MS
+    if (typeof options === 'boolean') {
+      enabled = options
+    } else if (options) {
+      enabled = options.enabled !== false
+      ttl = options.ttl ?? DEFAULT_TTL_MS
+    }
+
+    const paramsKey = params === undefined ? '' : JSON.stringify(params)
+
+    const view = useMemo((): DirectView | null => {
+      const zero = getZero()
+      if (!zero) return null
+      const queryRequest = resolveQuery({ customQueries, fn, params })
+      return directViewStore.getView(zero, queryRequest, enabled, ttl)
+      // params is keyed by paramsKey; version re-materializes on a new zero
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fn, paramsKey, enabled, ttl, version])
+
+    const out = useSyncExternalStore(
+      view ? view.subscribe : DISABLED_SUBSCRIBE,
+      view ? view.getSnapshot : getDisabledSnapshot,
+      view ? view.getSnapshot : getDisabledSnapshot,
+    )
+
+    if (!disableMode) {
+      lastRef.current = out
+      return out
+    }
+
+    if (disableMode === 'last-value') {
+      return lastRef.current
+    }
+
+    return EMPTY_RESPONSE
+  }
+
+  return useQueryDirect as UseQueryHook<Schema>
+}