on-zero 0.4.35 → 0.4.37

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>
+}

package/src/createZeroClient.tsx

@@ -1,6 +1,6 @@
 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, type Emitter } from '@take-out/helpers'
 import {
   createContext,
   memo,
@@ -9,6 +9,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type Context,
   type ReactNode,
 } from 'react'
 
@@ -16,7 +17,6 @@ import { createPermissions } from './createPermissions'
 import { ensureHttpPullTransport } from './httpPullTransport'
 import {
   createUseQuery,
-  createUseQueryDirect,
   type QueryControlMode,
   type UseQueryHook,
 } from './createUseQuery'
@@ -38,7 +38,14 @@ import { setRunner, type ZeroRunner } from './zeroRunner'
 import { zql } from './zql'
 
 import type { AuthData, GenericModels, GetZeroMutators, ZeroEvent } from './types'
-import type { Query, Row, Zero, ZeroOptions, Schema as ZeroSchema } from '@rocicorp/zero'
+import type {
+  AnyQueryRegistry,
+  Query,
+  Row,
+  Zero,
+  ZeroOptions,
+  Schema as ZeroSchema,
+} from '@rocicorp/zero'
 
 type PreloadOptions = { ttl?: 'always' | 'never' | number | undefined }
 
@@ -50,6 +57,27 @@ export type GroupedQueries = Record<string, Record<string, (...args: any[]) => a
 //  - 'optimistic-allow': return true until server confirms
 export type PermissionStrategy = 'optimistic' | 'optimistic-deny' | 'optimistic-allow'
 
+export type CreateZeroClientOptions<
+  Schema extends ZeroSchema,
+  Models extends GenericModels,
+> = {
+  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
+}
+
+export type DirectQueryAdapter<Schema extends ZeroSchema> = (props: {
+  DisabledContext: Context<QueryControlMode>
+  customQueries: AnyQueryRegistry
+  getZero: () => any
+  zeroVersion: Emitter<number>
+}) => UseQueryHook<Schema>
+
 function getZeroProxyValue(instance: object, key: PropertyKey) {
   const value = Reflect.get(instance, key, instance)
   if (typeof value !== 'function') return value
@@ -67,7 +95,25 @@ function getZeroProxyValue(instance: object, key: PropertyKey) {
   return bound
 }
 
-export function createZeroClient<
+function createUnavailableDirectUseQuery<
+  Schema extends ZeroSchema,
+>(): UseQueryHook<Schema> {
+  function useQueryDirect(): never {
+    throw new Error(
+      `[on-zero] direct queries are optional. Import createZeroClientWithDirectQueries from 'on-zero/multi' for clients used outside the innermost ZeroProvider.`,
+    )
+  }
+
+  return useQueryDirect as UseQueryHook<Schema>
+}
+
+export function createZeroClient<Schema extends ZeroSchema, Models extends GenericModels>(
+  options: CreateZeroClientOptions<Schema, Models>,
+) {
+  return createZeroClientInternal(options)
+}
+
+export function createZeroClientInternal<
   Schema extends ZeroSchema,
   Models extends GenericModels,
 >({
@@ -76,15 +122,9 @@ export function createZeroClient<
   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
+  createDirectUseQuery,
+}: CreateZeroClientOptions<Schema, Models> & {
+  createDirectUseQuery?: DirectQueryAdapter<Schema>
 }) {
   type ZeroMutators = GetZeroMutators<Models>
   type ZeroInstance = Zero<Schema, ZeroMutators>
@@ -230,13 +270,9 @@ export function createZeroClient<
 
   const zeroEvents = createEmitter<ZeroEvent | null>(`zero${emitterScope}`, null)
 
-  // bumped after commit whenever the mounted zero instance changes (first
-  // mount, identity change) — the direct query path re-materializes its views
-  // against the new instance
-  const zeroInstanceVersion = createEmitter<number>(
-    `zero-instance-version${emitterScope}`,
-    0,
-  )
+  const zeroInstanceVersion = createDirectUseQuery
+    ? createEmitter<number>(`zero-instance-version${emitterScope}`, 0)
+    : null
 
   const AuthDataContext = createContext<AuthData>({} as AuthData)
 
@@ -245,15 +281,14 @@ 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,
-  })
+  const useQueryDirect = createDirectUseQuery
+    ? createDirectUseQuery({
+        DisabledContext,
+        customQueries,
+        getZero: () => latestZeroInstance,
+        zeroVersion: zeroInstanceVersion!,
+      })
+    : createUnavailableDirectUseQuery<Schema>()
 
   // permission check uses a per-model synced query so server is authoritative
   // permissionStrategy controls client behavior before server responds.
@@ -515,10 +550,8 @@ export function createZeroClient<
       setRunner(runner)
     }
 
-    // notify direct-path views after commit (emitting during render would
-    // setState other components mid-render)
     useEffect(() => {
-      zeroInstanceVersion.emit(zeroInstanceVersion.value + 1)
+      zeroInstanceVersion?.emit(zeroInstanceVersion.value + 1)
     }, [zeroInstance])
 
     return null

package/src/helpers/recoverZeroClient.test.ts

@@ -177,7 +177,10 @@ describe('zero recovery', () => {
   // remount. previously crashed as an unhandled rejection.
   test('default reload path is a safe no-op when location is absent', async () => {
     const events: ZeroEvent[] = []
-    const zeroEvents = createEmitter<ZeroEvent | null>(`test-recover-${emitterSeq++}`, null)
+    const zeroEvents = createEmitter<ZeroEvent | null>(
+      `test-recover-${emitterSeq++}`,
+      null,
+    )
     zeroEvents.listen((event) => {
       if (event) events.push(event)
     })
@@ -200,6 +203,9 @@ describe('zero recovery', () => {
       })
     }
     expect(deleteLocalState).toHaveBeenCalledTimes(1)
-    expect(events).toContainEqual({ type: 'recovering', reason: 'client state not found' })
+    expect(events).toContainEqual({
+      type: 'recovering',
+      reason: 'client state not found',
+    })
   })
 })

package/src/index.ts

@@ -8,8 +8,12 @@ export * from './helpers/useMutation'
 export { ensureAuth, getAuth } from './helpers/getAuth'
 export { setAuthData, setEnvironment } from './state'
 
-export * from './combineZeroClients'
-export * from './createZeroClient'
+export {
+  createZeroClient,
+  type CreateZeroClientOptions,
+  type GroupedQueries,
+  type PermissionStrategy,
+} from './createZeroClient'
 export * from './httpPullTransport'
 export * from './createUseQuery'
 export * from './resolveQuery'

package/src/multi.ts

@@ -0,0 +1,24 @@
+import {
+  createZeroClientInternal,
+  type DirectQueryAdapter,
+  type CreateZeroClientOptions,
+} from './createZeroClient'
+import { createUseQueryDirect } from './createUseQueryDirect'
+
+import type { GenericModels } from './types'
+import type { Schema as ZeroSchema } from '@rocicorp/zero'
+
+export * from './combineZeroClients'
+
+export function createZeroClientWithDirectQueries<
+  Schema extends ZeroSchema,
+  Models extends GenericModels,
+>(
+  options: CreateZeroClientOptions<Schema, Models>,
+): ReturnType<typeof createZeroClientInternal<Schema, Models>> {
+  const createDirectUseQuery: DirectQueryAdapter<Schema> = createUseQueryDirect
+  return createZeroClientInternal<Schema, Models>({
+    ...options,
+    createDirectUseQuery,
+  })
+}

package/src/multiInstance.test.tsx

@@ -4,10 +4,12 @@ import { describe, expect, test, vi } from 'vitest'
 
 import { combineZeroClients } from './combineZeroClients'
 import { createZeroClient } from './createZeroClient'
+import { runWithContext } from './helpers/mutatorContext'
 import { getInstanceForNamespace, registerClientInstance } from './instanceRegistry'
 import { registerQuery } from './queryRegistry'
 import { run } from './run'
 import { setRunner, type ZeroRunner } from './zeroRunner'
+import { zql } from './zql'
 
 import type { ZeroEvent } from './types'
 import type { AnyQueryRegistry, Query } from '@rocicorp/zero'
@@ -89,6 +91,73 @@ describe('multi-instance namespace dispatch', () => {
     expect(request.query.queryName).toBe('runUser.byId')
   })
 
+  test('run() rejects named queries inside server mutation context', async () => {
+    const { byId } = makeClient('run-ctx-owner', 'runCtxThing')
+    const ownerRunner = vi.fn(async (..._args: unknown[]) => ({ from: 'owner' }))
+    getInstanceForNamespace('runCtxThing')!.runner = ownerRunner as ZeroRunner
+    const txRun = vi.fn(async (..._args: unknown[]) => ({ from: 'tx' }))
+
+    await expect(
+      runWithContext(
+        {
+          authData: null,
+          environment: 'server',
+          can: async () => {},
+          tx: { run: txRun },
+        } as any,
+        () => run(byId, { id: '1' }),
+      ),
+    ).rejects.toThrow(/run\(namedQuery\) cannot be used inside a Zero mutation/)
+
+    expect(ownerRunner).not.toHaveBeenCalled()
+    expect(txRun).not.toHaveBeenCalled()
+  })
+
+  test('run() keeps named queries on their owning client runner when browser context leaks', async () => {
+    const { byId } = makeClient('run-client-leak-owner', 'runClientLeakThing')
+    const ownerRunner = vi.fn(async (..._args: unknown[]) => ({ from: 'owner' }))
+    getInstanceForNamespace('runClientLeakThing')!.runner = ownerRunner as ZeroRunner
+    const txRun = vi.fn(async (..._args: unknown[]) => ({ from: 'tx' }))
+
+    await expect(
+      runWithContext(
+        {
+          authData: null,
+          environment: 'client',
+          can: async () => {},
+          tx: { run: txRun },
+        } as any,
+        () => run(byId, { id: '1' }),
+      ),
+    ).resolves.toEqual({ from: 'owner' })
+
+    expect(ownerRunner).toHaveBeenCalledTimes(1)
+    expect(txRun).not.toHaveBeenCalled()
+  })
+
+  test('run() keeps inline zql on the active transaction runner', async () => {
+    makeClient('run-inline-context', 'runInlineThing')
+    const ambientRunner = vi.fn(async (..._args: unknown[]) => ({ from: 'ambient' }))
+    setRunner(ambientRunner as ZeroRunner)
+    const txRun = vi.fn(async (..._args: unknown[]) => ({ from: 'tx' }))
+    const query = zql.user.where('id', '1')
+
+    await expect(
+      runWithContext(
+        {
+          authData: null,
+          environment: 'client',
+          can: async () => {},
+          tx: { run: txRun },
+        } as any,
+        () => run(query),
+      ),
+    ).resolves.toEqual({ from: 'tx' })
+
+    expect(txRun).toHaveBeenCalledWith(query, undefined)
+    expect(ambientRunner).not.toHaveBeenCalled()
+  })
+
   test('a claimed namespace with an unmounted instance uses the ambient runner (server path)', async () => {
     const { byId } = makeClient('srv-instance', 'srvThing')
     const ambient = vi.fn(async (..._args: unknown[]) => ({ from: 'ambient' }))