zodvex 0.7.4 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zodvex",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Codec-first Zod v4 integration for Convex -- type-safe validation, encoding, DB wrapping, and codegen.",
   "keywords": ["zod", "convex", "validators", "codec", "mapping", "schema", "validation"],
   "homepage": "https://github.com/panzacoder/zodvex#readme",

package/src/internal/actionCtx.ts

@@ -1,14 +1,83 @@
-import type { GenericActionCtx, GenericDataModel } from 'convex/server'
-import type { BoundaryHelpersOptions } from './boundaryHelpers'
+import type { GenericActionCtx, GenericDataModel, Scheduler } from 'convex/server'
+import type { BoundaryHelpers, BoundaryHelpersOptions } from './boundaryHelpers'
 import { createBoundaryHelpers } from './boundaryHelpers'
 import type { AnyRegistry } from './types'
 
 /**
- * Wraps an action context's runQuery/runMutation with automatic
+ * Wraps a `runQuery`/`runMutation` function so it encodes codec args
+ * (runtime -> wire) before the call and decodes the result (wire -> runtime)
+ * after. Functions not in the registry pass through unchanged.
+ */
+function wrapRun(fn: (ref: any, ...rest: any[]) => Promise<any>, codec: BoundaryHelpers) {
+  return async (ref: any, ...restArgs: any[]) => {
+    const wireArgs = codec.encodeArgs(ref, restArgs[0])
+    const wireResult = await fn(ref, wireArgs)
+    return codec.decodeResult(ref, wireResult)
+  }
+}
+
+/**
+ * Wraps a {@link Scheduler} so `runAfter`/`runAt` encode codec args to wire
+ * before scheduling.
+ *
+ * A scheduled function crosses the Convex boundary exactly like `runMutation`:
+ * the caller holds *decoded* (runtime) values, but Convex serializes the args
+ * against the target's *wire* validator. A non-serializable runtime value (e.g.
+ * a Symbol-valued codec field) cannot cross at all, and branded/`SensitiveField`
+ * codecs are the wrong shape — so the args must be encoded first.
+ *
+ * Return values are NOT decoded: the scheduler returns the scheduled-function
+ * id, not the target's result. Other members (e.g. `cancel`) pass through.
+ */
+function wrapScheduler(scheduler: Scheduler, codec: BoundaryHelpers): Scheduler {
+  const wrapped: any = { ...scheduler }
+  wrapped.runAfter = (delayMs: number, ref: any, ...restArgs: any[]) => {
+    const wireArgs = codec.encodeArgs(ref, restArgs[0])
+    return (scheduler.runAfter as any)(delayMs, ref, ...(restArgs.length ? [wireArgs] : []))
+  }
+  wrapped.runAt = (timestamp: number | Date, ref: any, ...restArgs: any[]) => {
+    const wireArgs = codec.encodeArgs(ref, restArgs[0])
+    return (scheduler.runAt as any)(timestamp, ref, ...(restArgs.length ? [wireArgs] : []))
+  }
+  return wrapped as Scheduler
+}
+
+/**
+ * Builds ctx overrides that auto-encode codec args at outbound call sites:
+ * - `runQuery` / `runMutation`: encode args, decode result.
+ * - `scheduler.runAfter` / `scheduler.runAt`: encode args.
+ *
+ * Only the members present on the given ctx are included, so this serves both
+ * action ctx (run* + scheduler) and mutation ctx (scheduler only).
+ *
+ * @internal Used by initZodvex when the `registry` option is provided.
+ */
+export function createCodecCallOverrides(
+  registry: AnyRegistry,
+  ctx: { runQuery?: unknown; runMutation?: unknown; scheduler?: Scheduler },
+  options?: BoundaryHelpersOptions
+): Record<string, unknown> {
+  const codec = createBoundaryHelpers(registry, options)
+  const overrides: Record<string, unknown> = {}
+  if (typeof ctx.runQuery === 'function') {
+    overrides.runQuery = wrapRun(ctx.runQuery as any, codec)
+  }
+  if (typeof ctx.runMutation === 'function') {
+    overrides.runMutation = wrapRun(ctx.runMutation as any, codec)
+  }
+  if (ctx.scheduler) {
+    overrides.scheduler = wrapScheduler(ctx.scheduler, codec)
+  }
+  return overrides
+}
+
+/**
+ * Wraps an action context's runQuery/runMutation and scheduler with automatic
  * codec transforms via the zodvex registry.
  *
  * - Args are encoded (runtime -> wire) before calling the inner function
  * - Results are decoded (wire -> runtime) before returning to the handler
+ *   (runQuery/runMutation only — the scheduler returns a scheduled-function id)
  * - Functions not in the registry pass through unchanged
  *
  * @internal Used by initZodvex when registry option is provided.
@@ -18,19 +87,5 @@ export function createZodvexActionCtx<DM extends GenericDataModel>(
   ctx: GenericActionCtx<DM>,
   options?: BoundaryHelpersOptions
 ): GenericActionCtx<DM> {
-  const codec = createBoundaryHelpers(registry, options)
-
-  return {
-    ...ctx,
-    runQuery: async (ref: any, ...restArgs: any[]) => {
-      const wireArgs = codec.encodeArgs(ref, restArgs[0])
-      const wireResult = await ctx.runQuery(ref, wireArgs)
-      return codec.decodeResult(ref, wireResult)
-    },
-    runMutation: async (ref: any, ...restArgs: any[]) => {
-      const wireArgs = codec.encodeArgs(ref, restArgs[0])
-      const wireResult = await ctx.runMutation(ref, wireArgs)
-      return codec.decodeResult(ref, wireResult)
-    }
-  } as GenericActionCtx<DM>
+  return { ...ctx, ...createCodecCallOverrides(registry, ctx, options) } as GenericActionCtx<DM>
 }

package/src/internal/init.ts

@@ -10,7 +10,7 @@ import type {
 } from 'convex/server'
 import { NoOp } from 'convex-helpers/server/customFunctions'
 import type { z } from 'zod'
-import { createZodvexActionCtx } from './actionCtx'
+import { createCodecCallOverrides } from './actionCtx'
 import type { CustomBuilder } from './custom'
 import { zCustomAction, zCustomMutation, zCustomQuery } from './custom'
 import { createZodvexCustomization } from './customization'
@@ -285,10 +285,11 @@ export function initZodvex(
   const noOp = createNoOpCustomization()
   const wrap = options?.wrapDb !== false
 
-  const actionCust = createActionCustomization(options?.registry, noOp)
+  const registryThunk = options?.registry
+  const actionCust = createActionCustomization(registryThunk, noOp)
   const customizations = {
     query: wrap ? codec.query : noOp,
-    mutation: wrap ? codec.mutation : noOp,
+    mutation: createMutationCustomization(wrap ? codec.mutation : noOp, registryThunk),
     action: actionCust
   }
 
@@ -309,10 +310,38 @@ function createActionCustomization(
 
   return {
     args: {} as Record<string, never>,
-    input: async (ctx: any) => {
-      const wrapped = createZodvexActionCtx(registryThunk(), ctx)
+    input: async (ctx: any) => ({
+      // Auto-encode codec args at outbound call sites: runQuery/runMutation
+      // (encode args, decode result) and scheduler.runAfter/runAt (encode args).
+      ctx: createCodecCallOverrides(registryThunk(), ctx),
+      args: {}
+    })
+  }
+}
+
+/**
+ * Composes the codec DB customization with outbound codec-arg encoding for the
+ * mutation builders. Mutations expose `ctx.scheduler` (runAfter/runAt), so when
+ * a registry is provided those calls auto-encode decoded codec args to wire —
+ * symmetric with the inbound decode the receiving function already performs.
+ *
+ * Without a registry, the DB customization is returned unchanged.
+ */
+function createMutationCustomization(
+  dbCust: InternalCustomization,
+  registryThunk: (() => AnyRegistry) | undefined
+): InternalCustomization {
+  if (!registryThunk) {
+    return dbCust
+  }
+
+  return {
+    args: {} as Record<string, never>,
+    input: async (ctx: any, _args: any, extra?: any) => {
+      const dbResult = await dbCust.input(ctx, {}, extra)
+      const callOverrides = createCodecCallOverrides(registryThunk(), ctx)
       return {
-        ctx: { runQuery: wrapped.runQuery, runMutation: wrapped.runMutation },
+        ctx: { ...dbResult.ctx, ...callOverrides },
         args: {}
       }
     }

package/src/public/client/zodvexClient.ts

@@ -1,4 +1,4 @@
-import type { AuthTokenFetcher } from 'convex/browser'
+import type { AuthTokenFetcher, ConnectionState, MutationOptions } from 'convex/browser'
 import { ConvexClient } from 'convex/browser'
 import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server'
 import type { BoundaryHelpersOptions } from '../../internal/boundaryHelpers'
@@ -21,6 +21,7 @@ export class ZodvexClient<R extends AnyRegistry = AnyRegistry> {
   private innerClient?: ConvexClient
   private url?: string
   private pendingAuthFetcher?: AuthTokenFetcher
+  private pendingAuthOnChange?: (isAuthenticated: boolean) => void
 
   constructor(registry: R, options: ZodvexClientOptions) {
     this.codec = createBoundaryHelpers(registry, { onDecodeError: options.onDecodeError })
@@ -42,7 +43,7 @@ export class ZodvexClient<R extends AnyRegistry = AnyRegistry> {
 
     const client = new ConvexClient(this.getUrl())
     if (this.pendingAuthFetcher) {
-      client.setAuth(this.pendingAuthFetcher)
+      client.setAuth(this.pendingAuthFetcher, this.pendingAuthOnChange)
     }
     this.innerClient = client
     return client
@@ -65,11 +66,33 @@ export class ZodvexClient<R extends AnyRegistry = AnyRegistry> {
 
   async mutate<M extends FunctionReference<'mutation', any, any, any>>(
     ref: M,
-    args: M['_args']
+    args: M['_args'],
+    options?: MutationOptions
   ): Promise<M['_returnType']> {
     const wireResult = await this.getConvex().mutation(
       ref,
-      this.codec.encodeArgs(ref, args) as FunctionArgs<M>
+      this.codec.encodeArgs(ref, args) as FunctionArgs<M>,
+      options
+    )
+    return this.codec.decodeResult(ref, wireResult)
+  }
+
+  /** Alias for {@link mutate} — matches `ConvexClient.mutation` / `ZodvexReactClient.mutation`. */
+  mutation<M extends FunctionReference<'mutation', any, any, any>>(
+    ref: M,
+    args: M['_args'],
+    options?: MutationOptions
+  ): Promise<M['_returnType']> {
+    return this.mutate(ref, args, options)
+  }
+
+  async action<A extends FunctionReference<'action', any, any, any>>(
+    ref: A,
+    args: A['_args']
+  ): Promise<A['_returnType']> {
+    const wireResult = await this.getConvex().action(
+      ref,
+      this.codec.encodeArgs(ref, args) as FunctionArgs<A>
     )
     return this.codec.decodeResult(ref, wireResult)
   }
@@ -77,22 +100,104 @@ export class ZodvexClient<R extends AnyRegistry = AnyRegistry> {
   subscribe<Q extends FunctionReference<'query', any, any, any>>(
     ref: Q,
     args: Q['_args'],
-    callback: (result: Q['_returnType']) => void
+    callback: (result: Q['_returnType']) => void,
+    onError?: (e: Error) => void
+  ): () => void {
+    const wireArgs = this.codec.encodeArgs(ref, args) as FunctionArgs<Q>
+    return this.getConvex().onUpdate(
+      ref,
+      wireArgs,
+      (wireResult: FunctionReturnType<Q>) => {
+        callback(this.codec.decodeResult(ref, wireResult))
+      },
+      onError
+    )
+  }
+
+  /** Alias for {@link subscribe} — matches `ConvexClient.onUpdate`. */
+  onUpdate<Q extends FunctionReference<'query', any, any, any>>(
+    ref: Q,
+    args: Q['_args'],
+    callback: (result: Q['_returnType']) => void,
+    onError?: (e: Error) => void
   ): () => void {
+    return this.subscribe(ref, args, callback, onError)
+  }
+
+  /**
+   * Experimental paginated subscription. Encodes args to wire and decodes each
+   * page item through the registry, mirroring {@link subscribe}.
+   */
+  onPaginatedUpdate_experimental<Q extends FunctionReference<'query', any, any, any>>(
+    ref: Q,
+    args: Q['_args'],
+    options: { initialNumItems: number },
+    callback: (result: {
+      page: Q['_returnType'][]
+      isDone: boolean
+      continueCursor: string
+      [key: string]: unknown
+    }) => void,
+    onError?: (e: Error) => void
+  ): ReturnType<ConvexClient['onPaginatedUpdate_experimental']> {
     const wireArgs = this.codec.encodeArgs(ref, args) as FunctionArgs<Q>
-    return this.getConvex().onUpdate(ref, wireArgs, (wireResult: FunctionReturnType<Q>) => {
-      callback(this.codec.decodeResult(ref, wireResult))
-    })
+    return this.getConvex().onPaginatedUpdate_experimental(
+      ref,
+      wireArgs,
+      options,
+      (wireResult: any) => {
+        callback({
+          ...wireResult,
+          page: wireResult.page.map((item: any) => this.codec.decodeResult(ref, item))
+        })
+      },
+      onError
+    ) as ReturnType<ConvexClient['onPaginatedUpdate_experimental']>
   }
 
-  setAuth(token: string | null) {
-    const fetcher = async () => token
+  /**
+   * Set the auth token. Accepts either a raw token string (convenience) or a
+   * Convex `AuthTokenFetcher` plus optional `onChange` callback (parity with
+   * `ConvexClient.setAuth`).
+   */
+  setAuth(token: string | null): void
+  setAuth(fetchToken: AuthTokenFetcher, onChange?: (isAuthenticated: boolean) => void): void
+  setAuth(
+    tokenOrFetcher: string | null | AuthTokenFetcher,
+    onChange?: (isAuthenticated: boolean) => void
+  ): void {
+    const fetcher: AuthTokenFetcher =
+      typeof tokenOrFetcher === 'function' ? tokenOrFetcher : async () => tokenOrFetcher
     this.pendingAuthFetcher = fetcher
+    this.pendingAuthOnChange = onChange
     if (this.innerClient) {
-      this.innerClient.setAuth(fetcher)
+      this.innerClient.setAuth(fetcher, onChange)
     }
   }
 
+  /** Returns the current auth token and its decoded claims, if authenticated. */
+  getAuth(): { token: string; decoded: Record<string, any> } | undefined {
+    return this.getConvex().getAuth()
+  }
+
+  /** Whether this client has been closed. False before the inner client is created. */
+  get closed(): boolean {
+    return this.innerClient?.closed ?? false
+  }
+
+  /** Whether this client is disabled. False before the inner client is created. */
+  get disabled(): boolean {
+    return this.innerClient?.disabled ?? false
+  }
+
+  connectionState(): ConnectionState {
+    return this.getConvex().connectionState()
+  }
+
+  subscribeToConnectionState(cb: (state: ConnectionState) => void): () => void {
+    return this.getConvex().subscribeToConnectionState(cb)
+  }
+
   async close() {
     await this.getConvex().close()
   }

package/src/public/react/zodvexReactClient.ts

@@ -84,6 +84,19 @@ export class ZodvexReactClient<R extends AnyRegistry = AnyRegistry> {
     return this.codec.decodeResult(ref, wireResult)
   }
 
+  /**
+   * Indicates likely future interest in a query subscription. Encodes args to
+   * wire before delegating, mirroring {@link watchQuery}.
+   */
+  prewarmQuery<Q extends FunctionReference<'query', any, any, any>>(queryOptions: {
+    query: Q
+    args: Q['_args']
+    extendSubscriptionFor?: number
+  }): void {
+    const wireArgs = this.codec.encodeArgs(queryOptions.query, queryOptions.args) as FunctionArgs<Q>
+    this.getConvex().prewarmQuery({ ...queryOptions, args: wireArgs })
+  }
+
   watchQuery<Q extends FunctionReference<'query', any, any, any>>(
     ref: Q,
     args: Q['_args'],
@@ -139,6 +152,10 @@ export class ZodvexReactClient<R extends AnyRegistry = AnyRegistry> {
     return this.getUrl()
   }
 
+  get logger(): ConvexReactClient['logger'] {
+    return this.getConvex().logger
+  }
+
   connectionState() {
     return this.getConvex().connectionState()
   }