on-zero 0.4.23 → 0.4.24

package/src/combineZeroClients.tsx

@@ -0,0 +1,186 @@
+import { createEmitter, type Emitter } from '@take-out/helpers'
+
+import { getInstanceForNamespace, getInstanceForQueryFn } from './instanceRegistry'
+import { run } from './run'
+
+import type { ZeroEvent } from './types'
+import type { ReactNode } from 'react'
+
+// combines multiple createZeroClient instances into one consumer surface:
+// useQuery/run/preload/getQuery dispatch to the instance that claimed the
+// query fn's namespace, zero.mutate.<namespace> dispatches by model
+// namespace, and everything unclaimed (plus non-mutate zero access like
+// userID/clientID) goes to the FIRST client — the primary. consumers render
+// each client's ProvideZero themselves; this facade does not use react
+// context, matching the existing global-zero-import style.
+//
+// PROVIDER NESTING CONTRACT: zero-react's useQuery resolves its instance from
+// the NEAREST ZeroProvider context, so only ONE instance — the one whose
+// 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.
+
+type ControlQueriesProps = {
+  children: ReactNode
+  action?: 'enable' | 'disable'
+  whenDisabled?: 'empty' | 'last-value'
+}
+
+// the minimal structural surface the facade dispatches over — the const
+// generic captures each client's real types, this only constrains shape
+type CombinableZeroClient = {
+  instanceName: string
+  useQuery: (...args: any[]) => any
+  useQueryDirect: (...args: any[]) => any
+  usePermission: (...args: any[]) => any
+  usePermissionDirect: (...args: any[]) => any
+  zero: any
+  preload: (...args: any[]) => any
+  getQuery: (...args: any[]) => any
+  zeroEvents: Emitter<ZeroEvent | null>
+  ControlQueries: (props: ControlQueriesProps) => ReactNode
+}
+
+export type CombineZeroClientsOptions = {
+  // instanceName of the client whose ProvideZero is mounted INNERMOST.
+  // defaults to the last client passed.
+  inner?: string
+}
+
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (
+  x: infer I,
+) => void
+  ? I
+  : never
+
+export type CombinedZeroClients<Clients extends readonly CombinableZeroClient[]> = {
+  useQuery: UnionToIntersection<Clients[number]['useQuery']>
+  usePermission: UnionToIntersection<Clients[number]['usePermission']>
+  zero: UnionToIntersection<Clients[number]['zero']>
+  preload: UnionToIntersection<Clients[number]['preload']>
+  getQuery: UnionToIntersection<Clients[number]['getQuery']>
+  run: typeof run
+  zeroEvents: Emitter<ZeroEvent | null>
+  ControlQueries: (props: ControlQueriesProps) => ReactNode
+}
+
+export function combineZeroClients<
+  const Clients extends readonly [CombinableZeroClient, ...CombinableZeroClient[]],
+>(
+  ...clientsAndOptions: [...Clients] | [...Clients, CombineZeroClientsOptions]
+): CombinedZeroClients<Clients> {
+  const last = clientsAndOptions[clientsAndOptions.length - 1]
+  const hasOptions = typeof (last as { instanceName?: unknown }).instanceName !== 'string'
+  // boundary narrow: everything before a trailing options object is a client
+  const clients = (hasOptions
+    ? clientsAndOptions.slice(0, -1)
+    : clientsAndOptions) as unknown as Clients
+  const options: CombineZeroClientsOptions = hasOptions
+    ? (last as CombineZeroClientsOptions)
+    : {}
+
+  const primary = clients[0]
+  const innerName = options.inner ?? clients[clients.length - 1]!.instanceName
+  const clientsByName = new Map(clients.map((client) => [client.instanceName, client]))
+
+  if (!clientsByName.has(innerName)) {
+    throw new Error(
+      `[on-zero] combineZeroClients inner instance '${innerName}' is not one of the passed clients`,
+    )
+  }
+
+  const ownerOfNamespace = (namespace: string): CombinableZeroClient => {
+    const owner = getInstanceForNamespace(namespace)
+    return (owner && clientsByName.get(owner.name)) || primary
+  }
+
+  const ownerOfQueryFn = (fn: Function): CombinableZeroClient => {
+    const owner = getInstanceForQueryFn(fn)
+    return (owner && clientsByName.get(owner.name)) || primary
+  }
+
+  // hooks: a given call site always passes the same query fn / table, so the
+  // dispatched hook target is stable across renders (no conditional hooks).
+  // only the inner instance may use the upstream context path — its provider
+  // is the nearest one, so useZero() resolves to it. everyone else goes
+  // through the context-free direct hooks.
+  function useQuery(...args: any[]) {
+    const owner = ownerOfQueryFn(args[0])
+    return owner.instanceName === innerName
+      ? owner.useQuery(...args)
+      : owner.useQueryDirect(...args)
+  }
+
+  function usePermission(...args: any[]) {
+    // model namespaces are table-named, so the table arg picks the owner;
+    // permission checks follow the same context vs direct path as the
+    // table's other queries
+    const owner = ownerOfNamespace(String(args[0]))
+    return owner.instanceName === innerName
+      ? owner.usePermission(...args)
+      : owner.usePermissionDirect(...args)
+  }
+
+  const mutate = new Proxy({} as never, {
+    get(_, key) {
+      if (typeof key !== 'string') return undefined
+      return ownerOfNamespace(key).zero.mutate[key]
+    },
+  })
+
+  const zero = new Proxy({} as never, {
+    get(_, key) {
+      if (key === 'mutate') {
+        return mutate
+      }
+      // non-mutate access (userID, clientID, close, …) forwards to primary
+      return primary.zero[key]
+    },
+  })
+
+  function preload(...args: any[]) {
+    return ownerOfQueryFn(args[0]).preload(...args)
+  }
+
+  function getQuery(...args: any[]) {
+    return ownerOfQueryFn(args[0]).getQuery(...args)
+  }
+
+  // one events stream relaying every instance's emitter
+  const zeroEvents = createEmitter<ZeroEvent | null>(
+    `zero:combined(${clients.map((client) => client.instanceName).join('+')})`,
+    null,
+  )
+  for (const client of clients) {
+    client.zeroEvents.listen((event) => zeroEvents.emit(event))
+  }
+
+  const ControlQueries = ({ children, ...props }: ControlQueriesProps) =>
+    clients.reduceRight(
+      (inner: ReactNode, client) => (
+        <client.ControlQueries {...props}>{inner}</client.ControlQueries>
+      ),
+      children,
+    )
+
+  const combined = {
+    useQuery,
+    usePermission,
+    zero,
+    preload,
+    getQuery,
+    run,
+    zeroEvents,
+    ControlQueries,
+  }
+
+  // boundary assertion: the dispatching wrappers are untyped internally; the
+  // combined type re-applies each client's real surface
+  return combined as unknown as CombinedZeroClients<Clients>
+}

package/src/createUseQuery.tsx

@@ -1,5 +1,13 @@
 import { useQuery as zeroUseQuery } from '@rocicorp/zero/react'
-import { useContext, useMemo, useRef, type Context } from 'react'
+import { useEmitterValue, type Emitter } from '@take-out/helpers'
+import {
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type Context,
+} from 'react'
 
 import { useZeroDebug } from './helpers/useZeroDebug'
 import { resolveQuery, type PlainQueryFn } from './resolveQuery'
@@ -41,6 +49,21 @@ 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) {
+  const hasParams =
+    optionsArg !== undefined ||
+    (paramsOrOptions &&
+      typeof paramsOrOptions === 'object' &&
+      !('enabled' in paramsOrOptions) &&
+      !('ttl' in paramsOrOptions))
+
+  return {
+    params: hasParams ? paramsOrOptions : undefined,
+    options: hasParams ? optionsArg : paramsOrOptions,
+  }
+}
+
 export function createUseQuery<Schema extends ZeroSchema>({
   DisabledContext,
   customQueries,
@@ -54,17 +77,7 @@ export function createUseQuery<Schema extends ZeroSchema>({
     const [fn, paramsOrOptions, optionsArg] = args
 
     const { queryRequest, options } = useMemo(() => {
-      // determine if this is with params or no params
-      const hasParams =
-        optionsArg !== undefined ||
-        (paramsOrOptions &&
-          typeof paramsOrOptions === 'object' &&
-          !('enabled' in paramsOrOptions) &&
-          !('ttl' in paramsOrOptions))
-
-      const params = hasParams ? paramsOrOptions : undefined
-      const opts = hasParams ? optionsArg : paramsOrOptions
-
+      const { params, options: opts } = parseUseQueryArgs(paramsOrOptions, optionsArg)
       const queryRequest = resolveQuery({ customQueries, fn, params })
 
       return { queryRequest, options: opts }
@@ -92,3 +105,153 @@ 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(
+  zero: MaterializableZero,
+  queryRequest: unknown,
+  ttl: UseQueryOptions['ttl'],
+): DirectView {
+  let snapshot: readonly [unknown, { type: string }] = DISABLED_SNAPSHOT
+  const listeners = new Set<() => void>()
+
+  // zero.materialize accepts a QueryRequest (it applies the instance context
+  // itself) — the same public api the upstream ViewWrapper uses
+  const view = zero.materialize(queryRequest, ttl === undefined ? undefined : { ttl })
+
+  // 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.
+  view.addListener((data, resultType) => {
+    snapshot = [
+      data === undefined ? undefined : structuredClone(data),
+      { type: resultType },
+    ]
+    for (const listener of listeners) {
+      listener()
+    }
+  })
+
+  return {
+    subscribe: (notify) => {
+      listeners.add(notify)
+      return () => listeners.delete(notify)
+    },
+    getSnapshot: () => snapshot,
+    destroy: () => view.destroy(),
+  }
+}
+
+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 => {
+      const zero = getZero()
+      if (!enabled || !zero) return null
+      const queryRequest = resolveQuery({ customQueries, fn, params })
+      return createDirectView(zero, 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/createZeroClient.tsx

@@ -13,7 +13,13 @@ import {
 } from 'react'
 
 import { createPermissions } from './createPermissions'
-import { createUseQuery, type QueryControlMode } from './createUseQuery'
+import {
+  createUseQuery,
+  createUseQueryDirect,
+  type QueryControlMode,
+  type UseQueryHook,
+} from './createUseQuery'
+import { registerClientInstance } from './instanceRegistry'
 import { createMutators } from './helpers/createMutators'
 import { getAuth } from './helpers/getAuth'
 import { getAllMutationsPermissions, getMutationsPermissions } from './modelRegistry'
@@ -22,7 +28,7 @@ import { resolveQuery, type PlainQueryFn } from './resolveQuery'
 import { setCustomQueries } from './run'
 import { getEnvironment, setAuthData, setEnvironment, setSchema } from './state'
 import { getRawWhere, setEvaluatingPermission } from './where'
-import { setRunner } from './zeroRunner'
+import { setRunner, type ZeroRunner } from './zeroRunner'
 import { zql } from './zql'
 
 import type { AuthData, GenericModels, GetZeroMutators, ZeroEvent } from './types'
@@ -63,11 +69,16 @@ export function createZeroClient<
   models,
   groupedQueries,
   permissionStrategy = 'optimistic',
+  instanceName = 'default',
 }: {
   schema: Schema
   models: Models
   groupedQueries: GroupedQueries
   permissionStrategy?: PermissionStrategy
+  // names this client instance so multiple instances can coexist on one page.
+  // each query/mutator namespace is claimed by exactly one instance, and the
+  // ambient run() + the combineZeroClients facade dispatch by that claim.
+  instanceName?: string
 }) {
   type ZeroMutators = GetZeroMutators<Models>
   type ZeroInstance = Zero<Schema, ZeroMutators>
@@ -177,6 +188,15 @@ export function createZeroClient<
   // create the single shared CustomQuery registry
   const customQueries = defineQueries(wrappedNamespaces)
 
+  // claim this instance's query/mutator namespaces so the ambient run() and
+  // the combineZeroClients facade dispatch to the owning instance. the
+  // auto-generated 'permission' namespace stays unclaimed (per-instance).
+  const instance = registerClientInstance({
+    name: instanceName,
+    namespaces: Object.keys({ ...groupedQueries, ...models }),
+    customQueries,
+  })
+
   // register for global run() helper
   setCustomQueries(customQueries)
 
@@ -197,7 +217,20 @@ export function createZeroClient<
     },
   })
 
-  const zeroEvents = createEmitter<ZeroEvent | null>('zero', null)
+  // emitter names are global keys (dev hmr cache) — scope them per instance
+  // so two instances never share cached values. the default name stays
+  // unchanged for single-instance back-compat.
+  const emitterScope = instanceName === 'default' ? '' : `:${instanceName}`
+
+  const zeroEvents = createEmitter<ZeroEvent | null>(`zero${emitterScope}`, null)
+
+  // bumped after commit whenever the mounted zero instance changes (first
+  // mount, identity change, client-state-not-found rotation) — the direct
+  // query path re-materializes its views against the new instance
+  const zeroInstanceVersion = createEmitter<number>(
+    `zero-instance-version${emitterScope}`,
+    0,
+  )
 
   const AuthDataContext = createContext<AuthData>({} as AuthData)
 
@@ -206,50 +239,66 @@ export function createZeroClient<
     customQueries,
   })
 
+  // context-free counterpart: materializes directly on THIS instance's
+  // mounted zero instead of the nearest ZeroProvider context. used by
+  // combineZeroClients for instances whose provider is not innermost.
+  const useQueryDirect = createUseQueryDirect<Schema>({
+    DisabledContext,
+    customQueries,
+    getZero: () => latestZeroInstance,
+    zeroVersion: zeroInstanceVersion,
+  })
+
   // permission check uses a per-model synced query so server is authoritative
-  // permissionStrategy controls client behavior before server responds
-  function usePermission(
-    table: TableName | (string & {}),
-    objOrId: string | Partial<Row<any>> | undefined,
-    enabled = typeof objOrId !== 'undefined',
-    debug = false,
-  ): boolean | null {
-    const disableMode = useContext(DisabledContext)
-    const lastRef = useRef<boolean | null>(null)
-    const tableStr = table as string
-    const checkFn = permissionCheckFns[tableStr]
-
-    // include auth user ID in query args so zero-cache creates per-user
-    // permission views (prevents dedup across different auth contexts)
-    const auth = getAuth()
-    const _uid = auth?.id || 'anon'
-
-    const [data, status] = useQuery(
-      checkFn as any,
-      { objOrId: objOrId as any, _uid },
-      { enabled: Boolean(!disableMode && enabled && objOrId && checkFn) },
-    )
+  // permissionStrategy controls client behavior before server responds.
+  // built over a query hook so the facade can route permission checks down
+  // the same context vs direct path as the table's other queries.
+  const createUsePermission = (useQueryImpl: UseQueryHook<Schema>) =>
+    function usePermission(
+      table: TableName | (string & {}),
+      objOrId: string | Partial<Row<any>> | undefined,
+      enabled = typeof objOrId !== 'undefined',
+      debug = false,
+    ): boolean | null {
+      const disableMode = useContext(DisabledContext)
+      const lastRef = useRef<boolean | null>(null)
+      const tableStr = table as string
+      const checkFn = permissionCheckFns[tableStr]
+
+      // include auth user ID in query args so zero-cache creates per-user
+      // permission views (prevents dedup across different auth contexts)
+      const auth = getAuth()
+      const _uid = auth?.id || 'anon'
+
+      const [data, status] = useQueryImpl(
+        checkFn as any,
+        { objOrId: objOrId as any, _uid },
+        { enabled: Boolean(!disableMode && enabled && objOrId && checkFn) },
+      )
 
-    if (debug) {
-      console.info(`usePermission()`, { table, objOrId, data, status })
-    }
+      if (debug) {
+        console.info(`usePermission()`, { table, objOrId, data, status })
+      }
 
-    if (!objOrId) return false
+      if (!objOrId) return false
 
-    // null while loading, then server's authoritative answer
-    const result = status.type === 'unknown' ? null : Boolean(data)
+      // null while loading, then server's authoritative answer
+      const result = status.type === 'unknown' ? null : Boolean(data)
 
-    if (!disableMode) {
-      lastRef.current = result
-      return result
-    }
+      if (!disableMode) {
+        lastRef.current = result
+        return result
+      }
+
+      if (disableMode === 'last-value') {
+        return lastRef.current
+      }
 
-    if (disableMode === 'last-value') {
-      return lastRef.current
+      return null
     }
 
-    return null
-  }
+  const usePermission = createUsePermission(useQuery)
+  const usePermissionDirect = createUsePermission(useQueryDirect)
 
   // the zero instance lives OUTSIDE the react lifecycle. react destroys and
   // re-fires the effects of a committed tree on any suspense hide/reveal, and
@@ -272,7 +321,10 @@ export function createZeroClient<
   // callbacks coalesces into ONE rotation, re-armed when the fresh instance
   // is created — without it a new instance that immediately re-fires the
   // callback rotation-loops forever.
-  const zeroInstanceGeneration = createEmitter<number>('zero-instance-generation', 0)
+  const zeroInstanceGeneration = createEmitter<number>(
+    `zero-instance-generation${emitterScope}`,
+    0,
+  )
   let zeroRotationPending = false
 
   const ProvideZero = ({
@@ -420,10 +472,20 @@ export function createZeroClient<
     // we'll need to add that soon
     if (zeroInstance !== latestZeroInstance) {
       latestZeroInstance = zeroInstance
-      // register runner for global run() helper
-      setRunner((query, options) => zeroInstance.run(query as any, options))
+      const runner: ZeroRunner = (query, options) =>
+        zeroInstance.run(query as any, options)
+      // the instance-keyed runner is what run() dispatches owned namespaces
+      // to; the global runner stays as the ambient fallback (inline zql)
+      instance.runner = runner
+      setRunner(runner)
     }
 
+    // notify direct-path views after commit (emitting during render would
+    // setState other components mid-render)
+    useEffect(() => {
+      zeroInstanceVersion.emit(zeroInstanceVersion.value + 1)
+    }, [zeroInstance])
+
     return null
   }
 
@@ -506,11 +568,14 @@ export function createZeroClient<
   }
 
   return {
+    instanceName,
     zeroEvents,
     ProvideZero,
     ControlQueries,
     useQuery,
+    useQueryDirect,
     usePermission,
+    usePermissionDirect,
     zero,
     preload,
     getQuery,

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './helpers/useMutation'
 export { ensureAuth, getAuth } from './helpers/getAuth'
 export { setAuthData, setEnvironment } from './state'
 
+export * from './combineZeroClients'
 export * from './createZeroClient'
 export * from './createUseQuery'
 export * from './resolveQuery'