on-zero 0.4.22 → 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>
+}