on-zero 0.1.39 → 0.1.41

package/readme.md

@@ -338,6 +338,8 @@ generates all files needed to connect your models and queries:
 - `tables.ts` - exports table schemas (separate to avoid circular types)
 - `syncedQueries.ts` - generates synced query definitions with valibot
   validators
+- `syncedMutations.ts` - generates valibot validators for mutation args
+  (auto-validation on server)
 
 **options:**
 
@@ -411,8 +413,12 @@ the generator:
 3. parses TypeScript AST to extract parameter types
 4. converts types to valibot schemas using typebox-codegen
 5. wraps query functions in `syncedQuery()` with validators
-6. handles special cases (void params, user → userPublic mapping)
-7. groups query imports by source file
+6. extracts mutation handler param types using the TS type checker (resolves
+   imports, aliases, and cross-file references)
+7. generates `syncedMutations.ts` with valibot validators for CRUD and custom
+   mutation args
+8. handles special cases (void params, user → userPublic mapping)
+9. groups query imports by source file
 
 queries with no parameters get wrapped in `v.parser(v.tuple([]))` while queries
 with params get validators like `v.parser(v.tuple([v.object({ ... })]))`.
@@ -451,12 +457,14 @@ server:
 ```ts
 import { createZeroServer } from 'on-zero/server'
 import { syncedQueries } from '~/data/generated/syncedQueries'
+import { mutationValidators } from '~/data/generated/syncedMutations'
 
 export const zeroServer = createZeroServer({
   schema,
   models,
   database: process.env.DATABASE_URL,
   queries: syncedQueries, // required for synced queries / pull endpoint
+  mutations: mutationValidators, // auto-validates mutation args with valibot
   createServerActions: () => ({
     sendEmail: async (to, subject, body) => { ... }
   })
@@ -522,6 +530,56 @@ export const zeroServer = createZeroServer({
 })
 ```
 
+### mutation arg validation
+
+on-zero can auto-generate valibot validators for all mutation arguments. the
+generator uses the TypeScript type checker to deeply resolve param types -
+including imported types, aliases, and cross-file references - then converts them
+to valibot schemas.
+
+pass the generated `mutationValidators` to `createZeroServer`:
+
+```ts
+import { mutationValidators } from '~/data/generated/syncedMutations'
+
+export const zeroServer = createZeroServer({
+  // ...
+  mutations: mutationValidators,
+})
+```
+
+this auto-validates args before every mutation runs. for a model like:
+
+```ts
+export const mutate = mutations(schema, permissions, {
+  async send(ctx, props: { content: string; channelId: string }) {
+    // ...
+  },
+})
+```
+
+the generator produces validators for both the CRUD operations (derived from the
+schema columns) and custom mutations (derived from handler param types). if
+validation fails, the mutation throws before executing.
+
+the generated `syncedMutations.ts` looks like:
+
+```ts
+import * as v from 'valibot'
+
+export const mutationValidators = {
+  message: {
+    insert: v.object({ id: v.string(), content: v.string(), ... }),
+    update: v.object({ id: v.string(), content: v.optional(v.string()), ... }),
+    delete: v.object({ id: v.string() }),
+    send: v.object({ content: v.string(), channelId: v.string() }),
+  },
+}
+```
+
+validation runs before the `validateMutation` hook, so both layers stack:
+valibot validates shape/types, then your custom hook can add business logic.
+
 type augmentation:
 
 ```ts
@@ -648,6 +706,23 @@ on-zero run is smart:
 - on server, uses server `zero.run()`
 - in a mutation, uses `tx.run()`
 
+**getQuery — resolve a query object directly:**
+
+use `getQuery` when you need the raw zero query object rather than subscribing via `useQuery`. useful for passing to third-party hooks that accept zero query objects directly (e.g. virtualized list hooks):
+
+```ts
+import { getQuery } from '~/zero/client'
+import { postById } from '~/data/queries/post'
+
+// returns the zero query object — same as what useQuery resolves internally
+const query = getQuery(postById, { postId: '123' })
+
+// pass to any hook that accepts a zero query directly
+const [rows] = useRows(getQuery(feedPosts, { limit: 50 }))
+```
+
+same signature as `useQuery` — `getQuery(fn, params?)`.
+
 **preloading data (client only):**
 
 preload query results into cache without subscribing:
@@ -674,6 +749,39 @@ for ad-hoc queries that don't use query functions:
 const user = await zeroServer.query((q) => q.user.where('id', userId).one())
 ```
 
+**controlling queries with `ControlQueries`:**
+
+disable all `useQuery` and `usePermission` calls within a subtree. useful for
+hiding screens, background tabs, or any UI where you want to pause syncing:
+
+```tsx
+import { ControlQueries } from '~/zero/client'
+
+// disable queries, returns null for all useQuery/usePermission calls
+<ControlQueries action="disable">
+  <ExpensiveScreen />
+</ControlQueries>
+
+// disable but keep returning the last value (no flash to empty)
+<ControlQueries action="disable" whenDisabled="last-value">
+  <ExpensiveScreen />
+</ControlQueries>
+
+// re-enable inside a disabled subtree
+<ControlQueries action="disable" whenDisabled="last-value">
+  <ControlQueries action="enable">
+    <AlwaysLiveWidget />
+  </ControlQueries>
+</ControlQueries>
+```
+
+props:
+
+- `action` — `'enable' | 'disable'` (default `'disable'`)
+- `whenDisabled` — `'empty' | 'last-value'` (default `'empty'`)
+  - `'empty'` — queries return `[null, { type: 'unknown' }]`
+  - `'last-value'` — queries return their most recent result
+
 **batch processing:**
 
 ```ts

package/src/createUseQuery.tsx

@@ -1,5 +1,5 @@
 import { useQuery as zeroUseQuery } from '@rocicorp/zero/react'
-import { use, useMemo, type Context } from 'react'
+import { use, useMemo, useRef, type Context } from 'react'
 
 import { useZeroDebug } from './helpers/useZeroDebug'
 import { resolveQuery, type PlainQueryFn } from './resolveQuery'
@@ -11,6 +11,9 @@ import type {
   Schema as ZeroSchema,
 } from '@rocicorp/zero'
 
+// false = enabled, 'empty' = disabled (return null), 'last-value' = disabled (return cached)
+export type QueryControlMode = false | 'empty' | 'last-value'
+
 export type UseQueryOptions = {
   enabled?: boolean | undefined
   ttl?: 'always' | 'never' | number | undefined
@@ -42,11 +45,12 @@ export function createUseQuery<Schema extends ZeroSchema>({
   DisabledContext,
   customQueries,
 }: {
-  DisabledContext: Context<boolean>
+  DisabledContext: Context<QueryControlMode>
   customQueries: AnyQueryRegistry
 }): UseQueryHook<Schema> {
   function useQuery(...args: any[]): any {
-    const disabled = use(DisabledContext)
+    const disableMode = use(DisabledContext)
+    const lastRef = useRef<any>(EMPTY_RESPONSE)
     const [fn, paramsOrOptions, optionsArg] = args
 
     const { queryRequest, options } = useMemo(() => {
@@ -74,11 +78,16 @@ export function createUseQuery<Schema extends ZeroSchema>({
         useZeroDebug(queryRequest, options, out)
     }
 
-    if (disabled) {
-      return EMPTY_RESPONSE
+    if (!disableMode) {
+      lastRef.current = out
+      return out
+    }
+
+    if (disableMode === 'last-value') {
+      return lastRef.current
     }
 
-    return out
+    return EMPTY_RESPONSE
   }
 
   return useQuery as UseQueryHook<Schema>

package/src/createZeroClient.tsx

@@ -12,7 +12,7 @@ import {
 } from 'react'
 
 import { createPermissions } from './createPermissions'
-import { createUseQuery } from './createUseQuery'
+import { createUseQuery, type QueryControlMode } from './createUseQuery'
 import { createMutators } from './helpers/createMutators'
 import { getAuth } from './helpers/getAuth'
 import { getAllMutationsPermissions, getMutationsPermissions } from './modelRegistry'
@@ -156,7 +156,7 @@ export function createZeroClient<
   // register for global run() helper
   setCustomQueries(customQueries)
 
-  const DisabledContext = createContext(false)
+  const DisabledContext = createContext<QueryControlMode>(false)
 
   let latestZeroInstance: ZeroInstance | null = null
 
@@ -190,14 +190,15 @@ export function createZeroClient<
     enabled = typeof objOrId !== 'undefined',
     debug = false
   ): boolean | null {
-    const disabled = use(DisabledContext)
+    const disableMode = use(DisabledContext)
+    const lastRef = useRef<boolean | null>(null)
     const tableStr = table as string
     const checkFn = permissionCheckFns[tableStr]
 
     const [data, status] = useQuery(
       checkFn as any,
       { objOrId: objOrId as any },
-      { enabled: Boolean(!disabled && enabled && objOrId && checkFn) }
+      { enabled: Boolean(!disableMode && enabled && objOrId && checkFn) }
     )
 
     if (debug) {
@@ -207,9 +208,18 @@ export function createZeroClient<
     if (!objOrId) return false
 
     // null while loading, then server's authoritative answer
-    if (status.type === 'unknown') return null
+    const result = status.type === 'unknown' ? null : Boolean(data)
 
-    return Boolean(data)
+    if (!disableMode) {
+      lastRef.current = result
+      return result
+    }
+
+    if (disableMode === 'last-value') {
+      return lastRef.current
+    }
+
+    return null
   }
 
   const ProvideZero = ({
@@ -334,12 +344,38 @@ export function createZeroClient<
     return zero.preload(queryRequest as any, options)
   }
 
+  function getQuery<TArg, TTable extends keyof Schema['tables'] & string, TReturn>(
+    fn: PlainQueryFn<TArg, Query<TTable, Schema, TReturn>>,
+    params: TArg
+  ): ReturnType<typeof resolveQuery<Schema>>
+  function getQuery<TTable extends keyof Schema['tables'] & string, TReturn>(
+    fn: PlainQueryFn<void, Query<TTable, Schema, TReturn>>
+  ): ReturnType<typeof resolveQuery<Schema>>
+  function getQuery(fn: any, params?: any) {
+    return resolveQuery({ customQueries, fn, params })
+  }
+
+  function ControlQueries({
+    children,
+    action = 'disable',
+    whenDisabled = 'empty',
+  }: {
+    children: ReactNode
+    action?: 'enable' | 'disable'
+    whenDisabled?: 'empty' | 'last-value'
+  }) {
+    const mode: QueryControlMode = action === 'enable' ? false : whenDisabled
+    return <DisabledContext.Provider value={mode}>{children}</DisabledContext.Provider>
+  }
+
   return {
     zeroEvents,
     ProvideZero,
+    ControlQueries,
     useQuery,
     usePermission,
     zero,
     preload,
+    getQuery,
   }
 }

package/src/createZeroServer.ts

@@ -75,6 +75,7 @@ export function createZeroServer<
   schema,
   models,
   queries,
+  mutations: mutationValidators,
   validateQuery,
   validateMutation,
   defaultAllowAdminRole = 'all',
@@ -88,6 +89,12 @@ export function createZeroServer<
   models: Models
   createServerActions: () => ServerActions
   queries?: AnyQueryRegistry
+  /**
+   * Generated valibot validators for mutation args, keyed by model.mutationName.
+   * Pass the `mutationValidators` export from generated syncedMutations.ts.
+   * Args are auto-validated before running the mutation.
+   */
+  mutations?: Record<string, Record<string, any>>
   /**
    * Hook to validate queries before execution. Throw to reject.
    * Must be synchronous.
@@ -163,6 +170,7 @@ export function createZeroServer<
       models,
       authData,
       validateMutation,
+      mutationValidators,
     })
 
     // @ts-expect-error type is ok but config in monorepo
@@ -274,6 +282,7 @@ export function createZeroServer<
       createServerActions,
       can: permissions.can,
       validateMutation,
+      mutationValidators,
     })
 
     const modelMutators = mutators[modelName as keyof typeof mutators] as Record<

package/src/generate.test.ts

@@ -199,3 +199,343 @@ export const allPosts = () => zero.query.post
     expect(second.filesChanged).toBe(0)
   })
 })
+
+describe('mutations', () => {
+  test('generates validators for inline mutation param types', async () => {
+    writeFileSync(
+      join(testDir, 'models/post.ts'),
+      `
+import { table, string } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+
+export const schema = table('post').columns({
+  id: string(),
+  title: string(),
+}).primaryKey('id')
+
+const perm = serverWhere('post', () => true)
+
+export const mutate = mutations(schema, perm, {
+  archive: async ({ tx }, { id, reason }: { id: string; reason: string }) => {
+    await tx.mutate.post.update({ id, archived: true })
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    expect(result.mutationCount).toBeGreaterThan(0)
+    expect(existsSync(join(testDir, 'generated/syncedMutations.ts'))).toBe(true)
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    expect(content).toContain('archive')
+    expect(content).toContain('v.object')
+    expect(content).toContain('v.string()')
+  })
+
+  test('generates CRUD validators from schema columns', async () => {
+    writeFileSync(
+      join(testDir, 'models/task.ts'),
+      `
+import { table, string, number, boolean } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+
+export const schema = table('task').columns({
+  id: string(),
+  title: string(),
+  priority: number(),
+  done: boolean(),
+  note: string().optional(),
+}).primaryKey('id')
+
+const perm = serverWhere('task', () => true)
+
+export const mutate = mutations(schema, perm)
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+
+    // insert: all columns present
+    expect(content).toContain('insert:')
+    expect(content).toMatch(/insert:.*v\.object/)
+
+    // update: id required, rest optional
+    expect(content).toContain('update:')
+
+    // delete: only PK
+    expect(content).toContain('delete:')
+  })
+
+  test('skips models without export const mutate', async () => {
+    writeFileSync(
+      join(testDir, 'models/readonly.ts'),
+      `
+import { table, string } from 'on-zero'
+
+export const schema = table('readonly').columns({
+  id: string(),
+  name: string(),
+}).primaryKey('id')
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+    expect(result.mutationCount).toBe(0)
+  })
+
+  test('extracts custom mutations from bare mutations({})', async () => {
+    writeFileSync(
+      join(testDir, 'models/admin.ts'),
+      `
+import { mutations } from 'on-zero'
+
+export const mutate = mutations({
+  reset: async ({ tx }, { targetId }: { targetId: string }) => {
+    await tx.mutate.admin.delete({ id: targetId })
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    expect(content).toContain('reset')
+    expect(content).toContain('v.string()')
+  })
+
+  test('handles mutations with only context param (void)', async () => {
+    writeFileSync(
+      join(testDir, 'models/user.ts'),
+      `
+import { table, string } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+
+export const schema = table('user').columns({
+  id: string(),
+  name: string(),
+}).primaryKey('id')
+
+const perm = serverWhere('user', () => true)
+
+export const mutate = mutations(schema, perm, {
+  finishOnboarding: async ({ tx }) => {
+    // no second param
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    // should not crash, void mutations get no validator
+    expect(content).toContain('finishOnboarding')
+  })
+
+  test('handles primitive param type', async () => {
+    writeFileSync(
+      join(testDir, 'models/user.ts'),
+      `
+import { table, string } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+
+export const schema = table('user').columns({
+  id: string(),
+  name: string(),
+}).primaryKey('id')
+
+const perm = serverWhere('user', () => true)
+
+export const mutate = mutations(schema, perm, {
+  completeSignup: async ({ tx }, userId: string) => {
+    await tx.mutate.user.update({ id: userId })
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    expect(content).toContain('completeSignup')
+    expect(content).toContain('v.string()')
+  })
+
+  test('handles array param type', async () => {
+    writeFileSync(
+      join(testDir, 'models/batch.ts'),
+      `
+import { mutations } from 'on-zero'
+
+export const mutate = mutations({
+  bulkDelete: async ({ tx }, ids: Array<{ id: string }>) => {
+    for (const { id } of ids) await tx.mutate.batch.delete({ id })
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    expect(content).toContain('bulkDelete')
+    expect(content).toContain('v.array')
+  })
+
+  test('populates mutationCount and caching works', async () => {
+    writeFileSync(
+      join(testDir, 'models/item.ts'),
+      `
+import { table, string } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+
+export const schema = table('item').columns({
+  id: string(),
+  name: string(),
+}).primaryKey('id')
+
+const perm = serverWhere('item', () => true)
+
+export const mutate = mutations(schema, perm, {
+  rename: async ({ tx }, { id, name }: { id: string; name: string }) => {
+    await tx.mutate.item.update({ id, name })
+  },
+})
+`
+    )
+
+    const first = await generate({ dir: testDir, silent: true })
+    expect(first.mutationCount).toBeGreaterThan(0)
+
+    const second = await generate({ dir: testDir, silent: true })
+    expect(second.filesChanged).toBe(0)
+    expect(second.mutationCount).toBe(first.mutationCount)
+  })
+})
+
+describe('type resolution', () => {
+  test('resolves imported type references for mutations', async () => {
+    // types file that the model imports from
+    writeFileSync(
+      join(testDir, 'models/types.ts'),
+      `
+export type ArchiveParams = {
+  id: string
+  reason: string
+  archived: boolean
+}
+`
+    )
+
+    writeFileSync(
+      join(testDir, 'models/post.ts'),
+      `
+import { table, string, boolean } from 'on-zero'
+import { mutations } from 'on-zero'
+import type { ArchiveParams } from './types'
+
+export const mutate = mutations({
+  archive: async ({ tx }, params: ArchiveParams) => {
+    await tx.mutate.post.update(params)
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    // the imported ArchiveParams type should be resolved to its fields
+    expect(content).toContain('v.string()')
+    expect(content).toContain('v.boolean()')
+    expect(content).toContain('reason')
+    expect(content).toContain('archived')
+  })
+
+  test('resolves utility types like Pick', async () => {
+    writeFileSync(
+      join(testDir, 'models/types.ts'),
+      `
+export type Item = {
+  id: string
+  name: string
+  description: string
+  count: number
+}
+`
+    )
+
+    writeFileSync(
+      join(testDir, 'models/item.ts'),
+      `
+import { table, string, number } from 'on-zero'
+import { mutations, serverWhere } from 'on-zero'
+import type { Item } from './types'
+
+export const schema = table('item').columns({
+  id: string(),
+  name: string(),
+  description: string(),
+  count: number(),
+}).primaryKey('id')
+
+const perm = serverWhere('item', () => true)
+
+export const mutate = mutations(schema, perm, {
+  rename: async ({ tx }, updates: Pick<Item, 'id' | 'name'>) => {
+    await tx.mutate.item.update(updates)
+  },
+})
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedMutations.ts'), 'utf-8')
+    // Pick should resolve to only id and name
+    expect(content).toContain('id')
+    expect(content).toContain('name')
+    // description and count should NOT be in the rename validator
+    expect(content).not.toMatch(/rename:[\s\S]*description/)
+    expect(content).not.toMatch(/rename:[\s\S]*count/)
+  })
+
+  test('resolves imported types in query params', async () => {
+    writeFileSync(
+      join(testDir, 'models/post.ts'),
+      `export const schema = table('post', { id: string() })`
+    )
+
+    writeFileSync(
+      join(testDir, 'queries/types.ts'),
+      `
+export type PostFilter = {
+  authorId: string
+  published: boolean
+}
+`
+    )
+
+    writeFileSync(
+      join(testDir, 'queries/post.ts'),
+      `
+import type { PostFilter } from './types'
+
+export const filteredPosts = (filter: PostFilter) => zero.query.post
+`
+    )
+
+    const result = await generate({ dir: testDir, silent: true })
+
+    const content = readFileSync(join(testDir, 'generated/syncedQueries.ts'), 'utf-8')
+    expect(content).toContain('filteredPosts')
+    expect(content).toContain('v.object')
+    expect(content).toContain('authorId')
+    expect(content).toContain('v.boolean()')
+  })
+})