on-zero 0.5.1 → 0.6.1

package/src/createZeroClient.recovery.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+
+import { createSchema, string, table } from '@rocicorp/zero'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+const fakeZero = vi.hoisted(() => {
+  class FakeZero {
+    readonly context = {}
+    readonly connection = {
+      state: {
+        current: { name: 'closed' },
+        subscribe: () => () => {},
+      },
+      connect: vi.fn(),
+    }
+    readonly delete = vi.fn(async () => ({ errors: [] }))
+    readonly close = vi.fn()
+    readonly run = vi.fn(async () => [])
+    readonly preload = vi.fn(() => ({
+      cleanup: () => {},
+      complete: Promise.resolve(),
+    }))
+
+    constructor() {
+      instances.push(this)
+    }
+  }
+
+  const instances: FakeZero[] = []
+  return { FakeZero, instances }
+})
+
+vi.mock('@rocicorp/zero', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@rocicorp/zero')>()
+  return {
+    ...actual,
+    Zero: fakeZero.FakeZero,
+  }
+})
+
+import { createZeroClient } from './createZeroClient'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+
+const noteTable = table('note').columns({ id: string(), body: string() }).primaryKey('id')
+const schema = createSchema({ tables: [noteTable] })
+
+const client = createZeroClient({
+  schema,
+  models: {},
+  groupedQueries: {},
+  instanceName: 'recovery-cache-test',
+})
+
+let container: HTMLDivElement
+let root: Root | null
+
+beforeEach(() => {
+  fakeZero.instances.length = 0
+  container = document.createElement('div')
+  root = null
+})
+
+afterEach(() => {
+  if (root) act(() => root?.unmount())
+})
+
+async function mount() {
+  root = createRoot(container)
+  await act(async () => {
+    root?.render(
+      <client.ProvideZero cacheURL="http://127.0.0.1:7777/zero" userID="agentbus">
+        <span>ok</span>
+      </client.ProvideZero>,
+    )
+    await Promise.resolve()
+  })
+}
+
+test('zero.delete invalidates cached instance before a remount recovery', async () => {
+  await mount()
+  const first = fakeZero.instances[0]
+  expect(first).toBeDefined()
+
+  const deleteZero = client.zero.delete
+  await act(async () => {
+    await deleteZero()
+  })
+
+  expect(first?.delete).toHaveBeenCalledTimes(1)
+  expect(first?.close).toHaveBeenCalledTimes(1)
+
+  act(() => root?.unmount())
+  await mount()
+
+  expect(fakeZero.instances).toHaveLength(2)
+  expect(fakeZero.instances[1]).not.toBe(first)
+})

package/src/createZeroClient.tsx

@@ -5,7 +5,7 @@ import {
   ZeroContext,
   ZeroProvider,
 } from '@rocicorp/zero/react'
-import { createEmitter, type Emitter } from '@take-out/helpers'
+import { createEmitter, IS_SERVER_RUNTIME, type Emitter } from '@take-out/helpers'
 import {
   createContext,
   memo,
@@ -264,6 +264,10 @@ export function createZeroClientInternal<
           `Zero instance not initialized. Ensure ZeroProvider is mounted before accessing 'zero'.`,
         )
       }
+      if (key === 'delete') {
+        const instanceToDelete = latestZeroInstance
+        return () => deleteZeroInstance(instanceToDelete)
+      }
       return getZeroProxyValue(latestZeroInstance, key)
     },
   })
@@ -303,7 +307,7 @@ export function createZeroClientInternal<
   // here (factory-time) instead of per-call keeps hook order stable so
   // rules-of-hooks stays happy.
   const createUsePermission = (useQueryImpl: UseQueryHook<Schema>) => {
-    if (typeof window === 'undefined') {
+    if (IS_SERVER_RUNTIME) {
       return (() => null) as (
         table: TableName | (string & {}),
         objOrId: string | Partial<Row<any>> | undefined,
@@ -373,6 +377,35 @@ export function createZeroClientInternal<
   // with different identities would thrash this slot.
   let cachedZero: { key: string; instance: ZeroInstance } | null = null
 
+  function invalidateZeroInstance(instanceToInvalidate: ZeroInstance | null): void {
+    if (!instanceToInvalidate) return
+
+    if (cachedZero?.instance === instanceToInvalidate) {
+      cachedZero = null
+    }
+    if (latestZeroInstance === instanceToInvalidate) {
+      latestZeroInstance = null
+      instance.runner = null
+      setRunner(null)
+      zeroInstanceVersion?.emit(zeroInstanceVersion.value + 1)
+    }
+    try {
+      instanceToInvalidate.close()
+    } catch {
+      // a deleted client is already unusable; close is best-effort cleanup.
+    }
+  }
+
+  async function deleteZeroInstance(
+    instanceToDelete: ZeroInstance | null,
+  ): Promise<unknown> {
+    try {
+      return await instanceToDelete?.delete()
+    } finally {
+      invalidateZeroInstance(instanceToDelete)
+    }
+  }
+
   // when ProvideZero is rendered without a real Zero instance (SSG, disable=true,
   // or transiently while the active path is still creating its first instance),
   // we want descendants' useZero() / useConnectionState() / on-zero useQuery to
@@ -401,7 +434,10 @@ export function createZeroClientInternal<
     connection: { state: DISABLED_ZERO_STUB_CONNECTION_STATE },
   } as unknown as ZeroInstance
 
-  type ProvideZeroProps = Omit<ZeroOptions<Schema, ZeroMutators>, 'schema' | 'mutators'> & {
+  type ProvideZeroProps = Omit<
+    ZeroOptions<Schema, ZeroMutators>,
+    'schema' | 'mutators'
+  > & {
     children: ReactNode
     authData?: AuthData | null
     // when true, ProvideZero renders a stable shell with stub Zero — no real
@@ -425,32 +461,33 @@ export function createZeroClientInternal<
     beforeReload?: () => Promise<void>
   }
 
-  // ProvideZero is ONE component (no inner ProvideZeroActive wrapper). a
-  // single component shape on both SSR and client means React's useId() —
-  // which keys on the consuming fiber's tree position — produces identical
-  // ids on both sides for every descendant. an extra wrapper fiber (the
-  // previous shape: SSR returned the 3 providers directly while the client
-  // wrapped them in a ProvideZeroActive intermediate) shifted every
-  // descendant's tree id by a step and broke hydration on every useId
-  // consumer (SVG ids, form ids, etc).
-  //
-  // SSR path: EARLY-RETURN before any hook call. on-zero's hooks
-  // (useRef/useState/useEffect) call through a React copy whose hook
-  // dispatcher is null on the SSG runtime (because react isn't deduplicated
-  // across the build's bundle for on-zero's slot), so any hook call here
-  // throws "Cannot read properties of null (reading 'useRef')". the SSR
-  // shell renders the same 3-provider 3-child shape as the client.
-  //
-  // CLIENT path: hooks ALWAYS run, regardless of `disable`. only the
-  // returned JSX changes when `disable` flips — so a caller can toggle
-  // active ↔ inert at runtime without violating rules-of-hooks (no
-  // remount, no key-rotation needed). this is the structural guarantee
-  // consumers like soot's ProjectZeroGate depend on to flip from
-  // disable=true (anon-ssr hydration first render) to disable=false
-  // (active project mounted) without re-parenting children — children
-  // stay at the same fiber position whether the wrapper is inert or
-  // active.
-  const ProvideZero = ({
+  // providezero keeps the same provider/fiber layout on ssr and client so
+  // useId() stays stable across hydration. the server implementation has no
+  // hooks because the ssg runtime can load on-zero through a non-deduped react
+  // copy whose dispatcher is null; the client implementation always calls its
+  // hooks, regardless of `disable`.
+  const ProvideZeroServer = ({ children, authData: authDataIn }: ProvideZeroProps) => {
+    return (
+      <AuthDataContext.Provider value={(authDataIn ?? {}) as AuthData}>
+        <DisabledContext.Provider value="empty">
+          <ZeroContext.Provider value={DISABLED_ZERO_STUB as any}>
+            {/* match the active path's 3-child layout exactly so descendant
+                useId() lands at the same fiber index in both branches. the
+                two leading nulls reserve the SetZeroInstance + ConnectionMonitor
+                slots; the active path puts those components there only once
+                an instance exists. without these placeholder slots, children
+                would sit at child index 0 here but index 2 in the active
+                path, shifting every descendant useId. */}
+            {null}
+            {null}
+            {children}
+          </ZeroContext.Provider>
+        </DisabledContext.Provider>
+      </AuthDataContext.Provider>
+    )
+  }
+
+  const ProvideZeroClient = ({
     children,
     authData: authDataIn,
     transport,
@@ -459,27 +496,6 @@ export function createZeroClientInternal<
     disable,
     ...props
   }: ProvideZeroProps) => {
-    if (typeof window === 'undefined') {
-      return (
-        <AuthDataContext.Provider value={(authDataIn ?? {}) as AuthData}>
-          <DisabledContext.Provider value="empty">
-            <ZeroContext.Provider value={DISABLED_ZERO_STUB as any}>
-              {/* match the active path's 3-child layout EXACTLY so descendant
-                  useId() lands at the same fiber index in both branches. the
-                  two leading nulls reserve the SetZeroInstance + ConnectionMonitor
-                  slots; the active path puts those components there only once
-                  an instance exists. without these placeholder slots, children
-                  would sit at child index 0 here but index 2 in the active
-                  path, shifting every descendant useId. */}
-              {null}
-              {null}
-              {children}
-            </ZeroContext.Provider>
-          </DisabledContext.Provider>
-        </AuthDataContext.Provider>
-      )
-    }
-
     // resolve the auth token first: a real logout (token gone) must clear
     // authData so client mutators don't keep running as the old user, while a
     // transient authData blip with the token still present (session refresh, tab
@@ -570,7 +586,7 @@ export function createZeroClientInternal<
         // the handlers only fire post-mount).
         const instanceRef: { current: ZeroInstance | null } = { current: null }
         const recoveryDeps: ZeroRecoveryDeps = {
-          deleteLocalState: () => instanceRef.current?.delete() ?? Promise.resolve(),
+          deleteLocalState: () => deleteZeroInstance(instanceRef.current),
           zeroEvents,
           beforeReload,
         }
@@ -645,6 +661,8 @@ export function createZeroClientInternal<
     )
   }
 
+  const ProvideZero = IS_SERVER_RUNTIME ? ProvideZeroServer : ProvideZeroClient
+
   const SetZeroInstance = () => {
     const zeroInstance = useZero<Schema, ZeroMutators>()
 

package/src/createZeroServer.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from 'vitest'
+
+import { createZeroServer } from './createZeroServer'
+import { zeroHttpFixtureSchema } from './httpPull/fixtureSchema'
+
+class FakePgClient {
+  lastMutationID = 0
+  pendingLastMutationID: number | undefined
+  mutationResultInserts: unknown[][] = []
+
+  async query(sql: string, params: unknown[] = []) {
+    if (sql === 'BEGIN') {
+      this.pendingLastMutationID = undefined
+      return { rows: [] }
+    }
+
+    if (sql === 'COMMIT') {
+      if (this.pendingLastMutationID !== undefined) {
+        this.lastMutationID = this.pendingLastMutationID
+      }
+      this.pendingLastMutationID = undefined
+      return { rows: [] }
+    }
+
+    if (sql === 'ROLLBACK') {
+      this.pendingLastMutationID = undefined
+      return { rows: [] }
+    }
+
+    if (sql.includes('.clients') && sql.includes('RETURNING "lastMutationID"')) {
+      const nextMutationID = this.lastMutationID + 1
+      this.pendingLastMutationID = nextMutationID
+      return { rows: [{ lastMutationID: nextMutationID }] }
+    }
+
+    if (sql.includes('information_schema.columns')) {
+      return {
+        rows: [
+          ...schemaRows('user', ['id', 'name']),
+          ...schemaRows('project', ['id', 'ownerId', 'name']),
+          ...schemaRows('member', ['id', 'projectId', 'userId']),
+        ],
+      }
+    }
+
+    if (sql.includes('INSERT INTO "zero_0"."mutations"')) {
+      this.mutationResultInserts.push(params)
+      return { rows: [] }
+    }
+
+    throw new Error(`unexpected fake pg query: ${sql}`)
+  }
+}
+
+function schemaRows(table: string, columns: string[]) {
+  return columns.map((column) => ({
+    schema: 'public',
+    table,
+    column,
+    dataType: 'text',
+    length: null,
+    precision: null,
+    scale: null,
+    typtype: 'b',
+    typename: 'text',
+    elemTyptype: null,
+    elemTypname: null,
+  }))
+}
+
+function pushRequest(mutationIDs: number | number[]) {
+  const ids = Array.isArray(mutationIDs) ? mutationIDs : [mutationIDs]
+  return new Request('http://localhost/push?schema=zero_0&appID=zero', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      clientGroupID: 'cg1',
+      mutations: ids.map((mutationID) => ({
+        type: 'custom',
+        id: mutationID,
+        clientID: 'client-a',
+        name: 'project.touch',
+        args: [{}],
+        timestamp: 1,
+      })),
+      pushVersion: 1,
+      timestamp: 1,
+      requestID: `req-${ids.join('-')}`,
+    }),
+  })
+}
+
+describe('createZeroServer mutation recovery', () => {
+  test('persists alreadyProcessed duplicate results for zero-cache recovery rows', async () => {
+    const pg = new FakePgClient()
+    const zeroServer = createZeroServer({
+      schema: zeroHttpFixtureSchema,
+      models: {
+        project: {
+          mutate: {
+            touch: async () => {},
+          },
+        },
+      },
+      createServerActions: () => ({}),
+      pool: pg as any,
+    })
+
+    const first = await zeroServer.handleMutationRequest({
+      authData: null,
+      request: pushRequest(1),
+    })
+
+    expect((first.response as any).mutations[0].result).toEqual({})
+    expect(pg.lastMutationID).toBe(1)
+    expect(pg.mutationResultInserts).toEqual([])
+
+    const duplicate = await zeroServer.handleMutationRequest({
+      authData: null,
+      request: pushRequest(1),
+    })
+
+    const duplicateResult = (duplicate.response as any).mutations[0].result
+    expect(duplicateResult.error).toBe('alreadyProcessed')
+    expect(pg.lastMutationID).toBe(1)
+    expect(pg.mutationResultInserts).toEqual([
+      [
+        'cg1',
+        'client-a',
+        1,
+        JSON.stringify({
+          error: 'alreadyProcessed',
+          details: duplicateResult.details,
+        }),
+      ],
+    ])
+  })
+
+  test('persists only alreadyProcessed results in a mixed recovery push', async () => {
+    const pg = new FakePgClient()
+    const zeroServer = createZeroServer({
+      schema: zeroHttpFixtureSchema,
+      models: {
+        project: {
+          mutate: {
+            touch: async () => {},
+          },
+        },
+      },
+      createServerActions: () => ({}),
+      pool: pg as any,
+    })
+
+    await zeroServer.handleMutationRequest({
+      authData: null,
+      request: pushRequest(1),
+    })
+
+    const mixed = await zeroServer.handleMutationRequest({
+      authData: null,
+      request: pushRequest([1, 2]),
+    })
+
+    const results = (mixed.response as any).mutations.map((mutation: any) => ({
+      id: mutation.id.id,
+      result: mutation.result,
+    }))
+    expect(results[0].result.error).toBe('alreadyProcessed')
+    expect(results[1]).toEqual({ id: 2, result: {} })
+    expect(pg.lastMutationID).toBe(2)
+    expect(pg.mutationResultInserts).toEqual([
+      [
+        'cg1',
+        'client-a',
+        1,
+        JSON.stringify({
+          error: 'alreadyProcessed',
+          details: results[0].result.details,
+        }),
+      ],
+    ])
+  })
+})

package/src/createZeroServer.ts

@@ -44,6 +44,21 @@ type MutateOptions = {
   awaitEffects?: boolean
 }
 
+type AlreadyProcessedMutation = {
+  id: {
+    clientID: string
+    id: number
+  }
+  result: {
+    error: 'alreadyProcessed'
+    details?: unknown
+  }
+}
+
+type PushRequestBody = {
+  clientGroupID?: unknown
+}
+
 type ServerMutate<Models extends GenericModels> = {
   [Key in keyof Models]: {
     [K in keyof Models[Key]['mutate']]: Models[Key]['mutate'][K] extends (
@@ -179,6 +194,7 @@ export function createZeroServer<
   }) => {
     // since mutations do DB work in transaction, avoid any async tasks during
     const asyncTasks: AsyncAction[] = []
+    const recoveryRequest = request.clone()
 
     const mutators = createMutators({
       asyncTasks,
@@ -193,6 +209,7 @@ export function createZeroServer<
 
     // @ts-expect-error type is ok but config in monorepo
     const response = await processor.process(mutators, request)
+    await persistAlreadyProcessedMutationResults(pool, recoveryRequest, response)
 
     // now finish
     if (!skipAsyncTasks && asyncTasks.length) {
@@ -416,3 +433,64 @@ export function createZeroServer<
     query,
   }
 }
+
+function alreadyProcessedMutations(response: unknown): AlreadyProcessedMutation[] {
+  if (!response || typeof response !== 'object') return []
+  const mutations = (response as { mutations?: unknown }).mutations
+  if (!Array.isArray(mutations)) return []
+
+  return mutations.filter((mutation): mutation is AlreadyProcessedMutation => {
+    if (!mutation || typeof mutation !== 'object') return false
+    const id = (mutation as { id?: unknown }).id
+    const result = (mutation as { result?: unknown }).result
+    return (
+      !!id &&
+      typeof id === 'object' &&
+      typeof (id as { clientID?: unknown }).clientID === 'string' &&
+      typeof (id as { id?: unknown }).id === 'number' &&
+      !!result &&
+      typeof result === 'object' &&
+      (result as { error?: unknown }).error === 'alreadyProcessed'
+    )
+  })
+}
+
+async function persistAlreadyProcessedMutationResults(
+  pool: NodePgTransaction,
+  request: Request,
+  response: unknown,
+) {
+  const mutations = alreadyProcessedMutations(response)
+  if (mutations.length === 0) return
+
+  const schema = new URL(request.url).searchParams.get('schema')
+  if (!schema) return
+
+  const body = (await request.json()) as PushRequestBody
+  if (typeof body.clientGroupID !== 'string') return
+
+  const table = `${quotePgIdentifier(schema)}."mutations"`
+  const values = mutations
+    .map((_, index) => {
+      const offset = index * 4
+      return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}::json)`
+    })
+    .join(', ')
+  const params = mutations.flatMap((mutation) => [
+    body.clientGroupID,
+    mutation.id.clientID,
+    mutation.id.id,
+    JSON.stringify(mutation.result),
+  ])
+
+  await pool.query(
+    `INSERT INTO ${table} ("clientGroupID", "clientID", "mutationID", "result")
+     VALUES ${values}
+     ON CONFLICT ("clientGroupID", "clientID", "mutationID") DO NOTHING`,
+    params,
+  )
+}
+
+function quotePgIdentifier(value: string) {
+  return `"${value.replaceAll('"', '""')}"`
+}

package/src/httpPull/transport.test.ts

@@ -480,9 +480,7 @@ describe('zero-http transport', () => {
     install(fetch)
     const onClientStateNotFound = vi.fn()
     createZero({ onClientStateNotFound })
-    await vi.waitFor(() => expect(onClientStateNotFound).toHaveBeenCalled(), {
-      timeout: 5_000,
-    })
+    await eventually(() => expect(onClientStateNotFound).toHaveBeenCalled(), 5_000)
   })
 })
 

package/src/mutations.ts

@@ -1,4 +1,4 @@
-import { isServer } from './constants'
+import { IS_SERVER_RUNTIME } from '@take-out/helpers'
 import { getDidRunPermissionCheck } from './helpers/didRunPermissionCheck'
 import { setMutationsPermissions } from './modelRegistry'
 
@@ -170,7 +170,7 @@ export function mutations<
           }
 
           // only validate on the server
-          if (isServer) {
+          if (IS_SERVER_RUNTIME) {
             await ctx.can(permissions, obj)
           }
         }

package/src/provideZero.hydration.test.tsx

@@ -17,13 +17,16 @@
 // stability is what keeps useId stable.
 
 import { createSchema, string, table } from '@rocicorp/zero'
+import { IS_SERVER, IS_SERVER_RUNTIME } from '@take-out/helpers'
 import { useId, type ReactNode } from 'react'
 import { renderToString } from 'react-dom/server'
 import { expect, test } from 'vitest'
 
 import { createZeroClient } from './createZeroClient'
 
-const todoTable = table('todo').columns({ id: string(), title: string() }).primaryKey('id')
+const todoTable = table('todo')
+  .columns({ id: string(), title: string() })
+  .primaryKey('id')
 const schema = createSchema({ tables: [todoTable] })
 
 const client = createZeroClient({
@@ -38,13 +41,7 @@ function IdProbe({ name }: { name: string }) {
   return <span data-name={name} data-probe-id={id} />
 }
 
-function Tree({
-  children,
-  disable,
-}: {
-  children?: ReactNode
-  disable?: boolean
-}) {
+function Tree({ children, disable }: { children?: ReactNode; disable?: boolean }) {
   return (
     <client.ProvideZero authData={{}} userID="anon" disable={disable}>
       <IdProbe name="a" />
@@ -69,6 +66,11 @@ function readIds(html: string): Record<string, string> {
   return out
 }
 
+test('test environment loads on-zero client runtime', () => {
+  expect(IS_SERVER_RUNTIME).toBe(false)
+  expect(IS_SERVER).toBe(false)
+})
+
 test('useId is stable across active vs disabled ProvideZero renders', () => {
   const active = readIds(renderToString(<Tree />))
   const disabled = readIds(renderToString(<Tree disable />))

package/src/testSetup.ts

@@ -1,3 +1,22 @@
+import { afterAll, vi } from 'vitest'
+
+const isJsdomRuntime = typeof window !== 'undefined' && typeof document !== 'undefined'
+const previousViteEnvironment = process.env.VITE_ENVIRONMENT
+
+if (isJsdomRuntime) {
+  process.env.VITE_ENVIRONMENT = 'client'
+  vi.resetModules()
+}
+
+afterAll(() => {
+  if (!isJsdomRuntime) return
+  if (previousViteEnvironment === undefined) {
+    delete process.env.VITE_ENVIRONMENT
+  } else {
+    process.env.VITE_ENVIRONMENT = previousViteEnvironment
+  }
+})
+
 if (typeof globalThis.localStorage?.getItem !== 'function') {
   const store = new Map<string, string>()
   Object.defineProperty(globalThis, 'localStorage', {

package/src/useQuery.empty.test.tsx

@@ -7,6 +7,7 @@
 // queries get `[undefined, info]` instead (the established zero-react shape).
 
 import { createSchema, number, string, table } from '@rocicorp/zero'
+import { IS_SERVER, IS_SERVER_RUNTIME } from '@take-out/helpers'
 import { act } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, expect, test } from 'vitest'
@@ -78,6 +79,11 @@ function renderWithDisabled<T>(useHook: () => T): T {
   return captured
 }
 
+test('test environment loads on-zero client runtime', () => {
+  expect(IS_SERVER_RUNTIME).toBe(false)
+  expect(IS_SERVER).toBe(false)
+})
+
 // 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', () => {