on-zero 0.4.39 → 0.4.41

package/src/createUseQueryDirect.tsx

@@ -8,6 +8,7 @@ import { useEmitterValue, type Emitter } from '@take-out/helpers'
 import { useContext, useMemo, useRef, useSyncExternalStore, type Context } from 'react'
 
 import {
+  emptyResponseFor,
   parseUseQueryArgs,
   type QueryControlMode,
   type UseQueryHook,
@@ -25,13 +26,10 @@ import type {
 // 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
+// see createUseQuery.tsx — empty responses must match the typed contract:
+// plural queries get [], singular get undefined. returning null breaks the
+// obvious .filter / .find / .length on first render.
 const DISABLED_SUBSCRIBE = () => () => {}
-const DISABLED_SNAPSHOT: readonly [undefined, { type: 'unknown' }] = [
-  undefined,
-  { type: 'unknown' },
-]
-const getDisabledSnapshot = () => DISABLED_SNAPSHOT
 
 type DirectSnapshot = readonly [unknown, { type: string }]
 
@@ -255,16 +253,17 @@ export function createUseQueryDirect<Schema extends ZeroSchema>({
   getZero,
   zeroVersion,
 }: Parameters<CreateUseQueryDirect<Schema>>[0]): UseQueryHook<Schema> {
-  // SSG: return an inert hook — see createUseQuery for the rationale.
+  // SSG: return an inert hook — see createUseQuery for the rationale. default
+  // to the plural empty shape (most queries are plural; a singular caller can
+  // tolerate [] better than the non-singular caller can tolerate null/undefined).
   if (typeof window === 'undefined') {
-    return (() => EMPTY_RESPONSE) as UseQueryHook<Schema>
+    return ((_fn: any) => emptyResponseFor(undefined)) as 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)
@@ -281,19 +280,32 @@ export function createUseQueryDirect<Schema extends ZeroSchema>({
 
     const paramsKey = params === undefined ? '' : JSON.stringify(params)
 
+    // resolve the query once so we know its singular/plural format up front —
+    // the no-zero / disabled snapshot needs to match that format so .filter /
+    // .find / .length is safe on first render.
+    const queryRequest = useMemo(
+      () => resolveQuery({ customQueries, fn, params }),
+      // params is keyed by paramsKey
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [fn, paramsKey],
+    )
+
+    const emptyForQuery = useMemo(() => emptyResponseFor(queryRequest), [queryRequest])
+    const lastRef = useRef<any>(emptyForQuery)
+
     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
+      // version re-materializes on a new zero
       // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [fn, paramsKey, enabled, ttl, version])
+    }, [queryRequest, enabled, ttl, version])
 
+    const getEmpty = () => emptyForQuery as DirectSnapshot
     const out = useSyncExternalStore(
       view ? view.subscribe : DISABLED_SUBSCRIBE,
-      view ? view.getSnapshot : getDisabledSnapshot,
-      view ? view.getSnapshot : getDisabledSnapshot,
+      view ? view.getSnapshot : getEmpty,
+      view ? view.getSnapshot : getEmpty,
     )
 
     if (!disableMode) {
@@ -305,7 +317,7 @@ export function createUseQueryDirect<Schema extends ZeroSchema>({
       return lastRef.current
     }
 
-    return EMPTY_RESPONSE
+    return emptyForQuery
   }
 
   return useQueryDirect as UseQueryHook<Schema>

package/src/useQuery.empty.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+//
+// useQuery's typed contract is `[T[], info]` for plural queries. The empty /
+// loading / disabled response MUST therefore be `[[], info]` — returning
+// `[null, info]` (the old EMPTY_RESPONSE constant) broke any caller that does
+// the obvious .filter / .find / .length / for-of on first render. Singular
+// queries get `[undefined, info]` instead (the established zero-react shape).
+
+import { createSchema, number, string, table } from '@rocicorp/zero'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, expect, test } from 'vitest'
+
+import { createZeroClient } from './createZeroClient'
+import { zql } from './zql'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+
+const todoTable = table('todo')
+  .columns({ id: string(), title: string(), createdAt: number() })
+  .primaryKey('id')
+const schema = createSchema({ tables: [todoTable] })
+
+// real plain query functions backed by zql so resolveQuery returns a real
+// QueryRequest (asQueryInternals(...).format.singular works).
+const allTodos = (_args: void) =>
+  (zql as unknown as { todo: { orderBy: (k: string, d: string) => any } }).todo.orderBy(
+    'createdAt',
+    'desc',
+  )
+const oneTodo = (args: { id: string }) =>
+  (zql as unknown as { todo: { where: (k: string, v: string) => any } }).todo
+    .where('id', args.id)
+    .one()
+
+const client = createZeroClient({
+  schema,
+  models: {},
+  groupedQueries: {
+    todo: { allTodos, oneTodo },
+  },
+  instanceName: 'empty-shape-test',
+})
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  container = document.createElement('div')
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+})
+
+function renderWithDisabled<T>(useHook: () => T): T {
+  let captured: T | undefined
+  const Probe = () => {
+    captured = useHook()
+    return null
+  }
+  act(() => {
+    // disable=true mounts the stable shell with DisabledContext='empty' + a
+    // stub Zero — this is exactly the path that used to return [null, ...]
+    // for every query.
+    root.render(
+      <client.ProvideZero authData={{}} userID="anon" disable>
+        <Probe />
+      </client.ProvideZero>,
+    )
+  })
+  if (captured === undefined) throw new Error('Probe did not render')
+  return captured
+}
+
+// regression: previously this returned [null, ...] which crashed downstream
+// .filter / .find / .length. now it must return [[], ...] for plural queries.
+test('useQuery returns [] (not null) for plural queries under DisabledContext', () => {
+  const [data, info] = renderWithDisabled(() => client.useQuery(allTodos))
+  expect(Array.isArray(data)).toBe(true)
+  expect((data as unknown[]).length).toBe(0)
+  // method calls that previously crashed must not crash
+  expect((data as unknown[]).filter(() => true)).toEqual([])
+  expect((data as unknown[]).find(() => true)).toBeUndefined()
+  expect(info?.type).toBe('unknown')
+})
+
+test('useQuery returns undefined (not null) for singular queries under DisabledContext', () => {
+  const [data, info] = renderWithDisabled(() => client.useQuery(oneTodo, { id: 'x' }))
+  // singular queries match zero-react: data is undefined while loading/disabled.
+  expect(data).toBeUndefined()
+  expect(info?.type).toBe('unknown')
+})

package/types/createUseQuery.d.ts

@@ -14,6 +14,9 @@ export type UseQueryHook<Schema extends ZeroSchema> = {
     <TArg, TTable extends keyof Schema['tables'] & string, TReturn>(fn: PlainQueryFn<TArg, Query<TTable, Schema, TReturn>>, params: TArg, options?: UseQueryOptions | boolean): QueryResult<TReturn>;
     <TTable extends keyof Schema['tables'] & string, TReturn>(fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>, options?: UseQueryOptions | boolean): QueryResult<TReturn>;
 };
+export declare function emptyResponseFor(queryRequest: unknown): readonly [unknown, {
+    type: string;
+}];
 export declare function parseUseQueryArgs(paramsOrOptions: any, optionsArg: any): {
     params: any;
     options: any;

package/types/createUseQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createUseQuery.d.ts","sourceRoot":"","sources":["../src/createUseQuery.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAGjE,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAEhE,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,KAAK,EACL,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAGvB,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,CAAA;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5D,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAA;AAExF,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,UAAU,IAAI;IAEpD,CAAC,IAAI,EAAE,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC5D,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,MAAM,EAAE,IAAI,EACZ,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAC;IAGxB,CAAC,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EACtD,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAA;CACxB,CAAA;AAKD,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG;;;EAYtE;AAED,wBAAgB,cAAc,CAAC,MAAM,SAAS,UAAU,EAAE,EACxD,eAAe,EACf,aAAa,GACd,EAAE;IACD,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;CAChC,GAAG,YAAY,CAAC,MAAM,CAAC,CAuDvB"}
+{"version":3,"file":"createUseQuery.d.ts","sourceRoot":"","sources":["../src/createUseQuery.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE/D,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAGjE,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAEhE,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,KAAK,EACL,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAGvB,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,CAAA;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5D,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAA;AAExF,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,UAAU,IAAI;IAEpD,CAAC,IAAI,EAAE,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC5D,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,MAAM,EAAE,IAAI,EACZ,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAC;IAGxB,CAAC,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EACtD,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAA;CACxB,CAAA;AAiBD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5F;AAGD,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG;;;EAYtE;AAED,wBAAgB,cAAc,CAAC,MAAM,SAAS,UAAU,EAAE,EACxD,eAAe,EACf,aAAa,GACd,EAAE;IACD,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;CAChC,GAAG,YAAY,CAAC,MAAM,CAAC,CAgEvB"}

package/types/createUseQueryDirect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createUseQueryDirect.d.ts","sourceRoot":"","sources":["../src/createUseQueryDirect.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAqD,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAEvF,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAqBvB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CACT,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,GACtB;QACD,WAAW,CACT,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,IAAI,GACpE,IAAI,CAAA;QACP,OAAO,IAAI,IAAI,CAAA;QACf,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;KAC1B,CAAA;CACF,CAAA;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,UAAU,IAAI,CAAC,KAAK,EAAE;IACpE,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;IAC/B,OAAO,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAG1B,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAsLD,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,EAAE,EAC9D,eAAe,EACf,aAAa,EACb,OAAO,EACP,WAAW,GACZ,EAAE,UAAU,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAuDpE"}
+{"version":3,"file":"createUseQueryDirect.d.ts","sourceRoot":"","sources":["../src/createUseQueryDirect.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAqD,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAEvF,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAkBvB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CACT,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,GACtB;QACD,WAAW,CACT,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,IAAI,GACpE,IAAI,CAAA;QACP,OAAO,IAAI,IAAI,CAAA;QACf,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;KAC1B,CAAA;CACF,CAAA;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,UAAU,IAAI,CAAC,KAAK,EAAE;IACpE,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;IAC/B,OAAO,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAG1B,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAsLD,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,EAAE,EAC9D,eAAe,EACf,aAAa,EACb,OAAO,EACP,WAAW,GACZ,EAAE,UAAU,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAqEpE"}

package/types/useQuery.empty.test.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+export {};
+//# sourceMappingURL=useQuery.empty.test.d.ts.map

package/types/useQuery.empty.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuery.empty.test.d.ts","sourceRoot":"","sources":["../src/useQuery.empty.test.tsx"],"names":[],"mappings":"AAgBA,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,wBAAwB,EAAE,OAAO,GAAG,SAAS,CAAA;CAClD"}