on-zero 0.4.22 → 0.4.24

package/src/createZeroClient.tsx

@@ -1,6 +1,6 @@
-import { defineQueries, defineQuery } from '@rocicorp/zero'
+import { defineQueries, defineQuery, Zero as ZeroClient } from '@rocicorp/zero'
 import { useConnectionState, useZero, ZeroProvider } from '@rocicorp/zero/react'
-import { createEmitter } from '@take-out/helpers'
+import { createEmitter, useEmitterValue } from '@take-out/helpers'
 import {
   createContext,
   memo,
@@ -8,11 +8,18 @@ import {
   useEffect,
   useMemo,
   useRef,
+  useState,
   type ReactNode,
 } 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'
@@ -21,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'
@@ -62,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>
@@ -176,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)
 
@@ -196,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)
 
@@ -205,50 +239,93 @@ 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
+  // consumers also remount the provider (splash -> IDE). when ZeroProvider
+  // created zero inside its own effect, every such cycle closed the live
+  // instance mid-connect ("Failed to connect / Store is closed") and built a
+  // replacement, killing in-flight queries and preloads. instead the instance
+  // is created in an effect, cached here per identity key, handed to
+  // ZeroProvider as an external `zero` (which it never closes), and the
+  // previous instance is closed only when the key truly changes — a real
+  // identity change (user, storage, server, logged in/out), never a react
+  // lifecycle artifact. single-provider assumption: one mounted ProvideZero
+  // per client (true of every consumer); two simultaneously mounted providers
+  // with different identities would thrash this slot.
+  let cachedZero: { key: string; instance: ZeroInstance } | null = null
+
+  // bumping this recreates the instance with the same options — parity with
+  // ZeroProvider's built-in onClientStateNotFound rotation. the pending flag
+  // mirrors upstream's rotationPendingRef: a storm of client-state-not-found
+  // 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${emitterScope}`,
+    0,
+  )
+  let zeroRotationPending = false
 
   const ProvideZero = ({
     children,
@@ -279,6 +356,93 @@ export function createZeroClient<
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [])
 
+    const generation = useEmitterValue(zeroInstanceGeneration)
+
+    const auth = 'auth' in props ? (props as { auth?: string | null }).auth : undefined
+    const hasAuth = typeof auth === 'string'
+
+    // identity = every primitive option except the auth token value (token
+    // changes refresh in place below; logged-in <-> logged-out still rotates
+    // via hasAuth, matching zero's documented provider semantics). function
+    // props (callbacks, logSink, batchViewUpdates) are bound at construction.
+    const instanceKey = JSON.stringify([
+      Object.entries({ kvStore: 'mem', ...props })
+        .filter(
+          ([key, value]) =>
+            key !== 'auth' && typeof value !== 'function' && value !== undefined,
+        )
+        .sort(([a], [b]) => (a < b ? -1 : 1)),
+      hasAuth,
+      generation,
+    ])
+
+    // create/rotate in an effect — commit-safe: a discarded concurrent render
+    // can never close an instance the committed tree still uses. a suspense
+    // hide/reveal re-runs this effect with an unchanged key — cache hit, no
+    // churn, no cleanup-close. children mounting one effect-tick after the
+    // provider matches ZeroProvider's internal-creation timing, which consumer
+    // boot orchestration observes.
+    const [instance, setInstance] = useState<ZeroInstance | undefined>()
+    useEffect(() => {
+      let cached = cachedZero
+      if (cached?.key !== instanceKey) {
+        cached?.instance.close()
+        const options = props as Omit<
+          ZeroOptions<Schema, ZeroMutators>,
+          'schema' | 'mutators'
+        >
+        cached = {
+          key: instanceKey,
+          instance: new ZeroClient<Schema, ZeroMutators>({
+            kvStore: 'mem',
+            ...options,
+            schema,
+            // @ts-expect-error same erasure ZeroProvider needed
+            mutators,
+            onClientStateNotFound: () => {
+              // consumer callback wins; recreate-with-same-options is the
+              // fallback, mirroring ZeroProvider's internal rotation.
+              if (options.onClientStateNotFound) {
+                try {
+                  options.onClientStateNotFound()
+                  return
+                } catch {
+                  // fall through to rotation
+                }
+              }
+              if (zeroRotationPending) return
+              zeroRotationPending = true
+              zeroInstanceGeneration.emit(zeroInstanceGeneration.value + 1)
+            },
+          }),
+        }
+        cachedZero = cached
+        zeroRotationPending = false
+      }
+      setInstance(cached.instance)
+      // identity is fully captured by instanceKey; function props are bound
+      // at construction by design.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [instanceKey])
+
+    // a changed token on the same identity refreshes auth in place — zero
+    // sends an auth update over the live connection instead of reconnecting
+    // (upstream ZeroProvider does exactly this). string <-> undefined flips
+    // rotate the instance via hasAuth in the identity key instead.
+    const prevAuthRef = useRef(auth)
+    useEffect(() => {
+      const prevAuth = prevAuthRef.current
+      prevAuthRef.current = auth
+      if (
+        instance &&
+        typeof prevAuth === 'string' &&
+        typeof auth === 'string' &&
+        prevAuth !== auth
+      ) {
+        instance.connection.connect({ auth })
+      }
+    }, [instance, auth])
+
     // for now we re-parent
     if (disable) {
       return children
@@ -286,17 +450,13 @@ export function createZeroClient<
 
     return (
       <AuthDataContext.Provider value={authData}>
-        <ZeroProvider
-          schema={schema}
-          kvStore="mem"
-          // @ts-expect-error
-          mutators={mutators}
-          {...props}
-        >
-          <SetZeroInstance />
-          <ConnectionMonitor zeroEvents={zeroEvents} />
-          {children}
-        </ZeroProvider>
+        {instance ? (
+          <ZeroProvider zero={instance}>
+            <SetZeroInstance />
+            <ConnectionMonitor zeroEvents={zeroEvents} />
+            {children}
+          </ZeroProvider>
+        ) : null}
       </AuthDataContext.Provider>
     )
   }
@@ -312,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
   }
 
@@ -398,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'

package/src/instanceRegistry.ts

@@ -0,0 +1,75 @@
+// registry mapping query/mutator namespaces to the zero client instance that
+// owns them. enables multiple createZeroClient instances on one page (e.g. a
+// control-plane instance + a per-project instance): the ambient run() and the
+// combineZeroClients facade dispatch each query/mutation to the owning
+// instance by its registered namespace instead of whichever mounted last.
+//
+// stored via globalValue so dual-loaded module copies (cjs/esm) share one map,
+// matching the package's other cross-module registries.
+
+import { globalValue } from '@take-out/helpers'
+
+import { getQueryName } from './queryRegistry'
+
+import type { ZeroRunner } from './zeroRunner'
+import type { AnyQueryRegistry } from '@rocicorp/zero'
+
+export type ZeroClientInstance = {
+  name: string
+  customQueries: AnyQueryRegistry
+  // set when the instance's provider mounts (client); stays null on the
+  // server, where the ambient transaction runner serves every instance
+  runner: ZeroRunner | null
+}
+
+const getInstancesByNamespace = () =>
+  globalValue<Map<string, ZeroClientInstance>>(
+    'on-zero:instances-by-namespace',
+    () => new Map(),
+  )
+
+export function registerClientInstance({
+  name,
+  namespaces,
+  customQueries,
+}: {
+  name: string
+  namespaces: string[]
+  customQueries: AnyQueryRegistry
+}): ZeroClientInstance {
+  const instancesByNamespace = getInstancesByNamespace()
+
+  // re-creating an instance under the same name (hmr) replaces its claims
+  for (const [namespace, owner] of instancesByNamespace) {
+    if (owner.name === name) {
+      instancesByNamespace.delete(namespace)
+    }
+  }
+
+  const instance: ZeroClientInstance = { name, customQueries, runner: null }
+
+  for (const namespace of namespaces) {
+    const existing = instancesByNamespace.get(namespace)
+    if (existing) {
+      throw new Error(
+        `[on-zero] namespace '${namespace}' is already claimed by zero client instance '${existing.name}' ` +
+          `(while creating instance '${name}'). Each query/mutator namespace must belong to exactly one createZeroClient instance.`,
+      )
+    }
+    instancesByNamespace.set(namespace, instance)
+  }
+
+  return instance
+}
+
+export function getInstanceForNamespace(
+  namespace: string,
+): ZeroClientInstance | undefined {
+  return getInstancesByNamespace().get(namespace)
+}
+
+export function getInstanceForQueryFn(fn: Function): ZeroClientInstance | undefined {
+  const queryName = getQueryName(fn)
+  if (!queryName) return undefined
+  return getInstanceForNamespace(queryName.split('.', 1)[0])
+}