zodvex 0.7.7 → 0.7.8-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zodvex",
-  "version": "0.7.7",
+  "version": "0.7.8-beta.0",
   "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/customization.ts

@@ -1,11 +1,41 @@
+import type { GenericDatabaseReader, GenericDatabaseWriter } from 'convex/server'
 import { ZodvexDatabaseReader, ZodvexDatabaseWriter } from './db'
 import type { ZodTableMap } from './schema'
 
+/**
+ * Resolvers for the database the codec wrapper delegates to (#92).
+ *
+ * Each resolver receives the raw Convex ctx (untouched by zodvex) and returns
+ * the db the codec reader/writer should wrap instead of `ctx.db`. This lets
+ * native-shape layers — e.g. `convex-helpers/server/triggers` — sit UNDER the
+ * codec layer: codec on top → triggers → real db. The trigger layer sees
+ * wire-format writes, exactly what it is written against.
+ *
+ * ```ts
+ * const triggers = new Triggers<DataModel>()
+ * initZodvex(schema, server, {
+ *   underlyingDb: { mutation: (ctx) => triggers.wrapDB(ctx).db }
+ * })
+ * ```
+ */
+export type ZodvexUnderlyingDb<
+  QueryCtx = any,
+  MutationCtx = any,
+  Reader extends GenericDatabaseReader<any> = GenericDatabaseReader<any>,
+  Writer extends GenericDatabaseWriter<any> = GenericDatabaseWriter<any>
+> = {
+  query?: (ctx: QueryCtx) => Reader
+  mutation?: (ctx: MutationCtx) => Writer
+}
+
 /**
  * Creates Convex Customization objects that wrap ctx.db with codec
  * readers/writers. Returns { query, mutation } for use with
  * zCustomQuery/zCustomMutation or manual composition.
  *
+ * When `options.underlyingDb` is provided, the codec wrapper delegates to the
+ * resolved db instead of `ctx.db` (see {@link ZodvexUnderlyingDb}).
+ *
  * @example
  * ```typescript
  * const codec = createZodvexCustomization(schema.__zodTableMap)
@@ -19,19 +49,28 @@ import type { ZodTableMap } from './schema'
  * })
  * ```
  */
-export function createZodvexCustomization(tableMap: ZodTableMap) {
+export function createZodvexCustomization(
+  tableMap: ZodTableMap,
+  options?: { underlyingDb?: ZodvexUnderlyingDb }
+) {
+  const resolveReaderDb = options?.underlyingDb?.query
+  const resolveWriterDb = options?.underlyingDb?.mutation
   return {
     query: {
       args: {} as Record<string, never>,
       input: async (ctx: any, _args: any, _extra?: any) => ({
-        ctx: { db: new ZodvexDatabaseReader(ctx.db, tableMap) },
+        ctx: {
+          db: new ZodvexDatabaseReader(resolveReaderDb ? resolveReaderDb(ctx) : ctx.db, tableMap)
+        },
         args: {}
       })
     },
     mutation: {
       args: {} as Record<string, never>,
       input: async (ctx: any, _args: any, _extra?: any) => ({
-        ctx: { db: new ZodvexDatabaseWriter(ctx.db, tableMap) },
+        ctx: {
+          db: new ZodvexDatabaseWriter(resolveWriterDb ? resolveWriterDb(ctx) : ctx.db, tableMap)
+        },
         args: {}
       })
     }

package/src/internal/db.ts

@@ -484,6 +484,18 @@ export class ZodvexDatabaseReader<
     return { db: this.db, tableMap: this.tableMap }
   }
 
+  /**
+   * Escape hatch (#85/#92): returns the database this codec wrapper delegates
+   * to — the composed underlying stack when `underlyingDb` is configured (e.g.
+   * a trigger-wrapped writer), the bare Convex db otherwise.
+   *
+   * The returned db is native-shape: reads are undecoded wire documents and it
+   * bypasses codec, `.withRules()`, and `.audit()` layers entirely.
+   */
+  unwrap(): GenericDatabaseReader<DataModel> {
+    return this.db
+  }
+
   normalizeId<TableName extends TableNamesInDataModel<DataModel>>(
     tableName: TableName,
     id: string
@@ -600,6 +612,18 @@ export class ZodvexDatabaseWriter<
     return { db: this.writerDb, tableMap: this.tableMap, reader: this }
   }
 
+  /**
+   * Escape hatch (#85/#92): returns the writer this codec wrapper delegates
+   * to — the composed underlying stack when `underlyingDb` is configured (e.g.
+   * a trigger-wrapped writer), the bare Convex db otherwise.
+   *
+   * The returned db is native-shape: writes must be wire-format and it
+   * bypasses codec, `.withRules()`, and `.audit()` layers entirely.
+   */
+  override unwrap(): GenericDatabaseWriter<DataModel> {
+    return this.writerDb
+  }
+
   // --- Write methods: encode before delegating ---
 
   insert<TableName extends TableNamesInDataModel<DataModel>>(

package/src/internal/init.ts

@@ -2,6 +2,8 @@ import type {
   ActionBuilder,
   FunctionVisibility,
   GenericActionCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
   GenericDataModel,
   GenericMutationCtx,
   GenericQueryCtx,
@@ -13,7 +15,7 @@ import type { z } from 'zod'
 import { createCodecCallOverrides } from './actionCtx'
 import type { CustomBuilder } from './custom'
 import { zCustomAction, zCustomMutation, zCustomQuery } from './custom'
-import { createZodvexCustomization } from './customization'
+import { createZodvexCustomization, type ZodvexUnderlyingDb } from './customization'
 import type { ZodvexDatabaseReader, ZodvexDatabaseWriter } from './db'
 import type { ZodValidator } from './mapping'
 import type { ZodTableMap } from './schema'
@@ -255,7 +257,28 @@ export function initZodvex<
     internalMutation: MutationBuilder<DM, 'internal'>
     internalAction: ActionBuilder<DM, 'internal'>
   },
-  options?: { wrapDb?: true; registry?: () => AnyRegistry }
+  options?: {
+    wrapDb?: true
+    registry?: () => AnyRegistry
+    /**
+     * Resolve the database the codec wrapper delegates to, instead of `ctx.db`.
+     * Lets native-shape layers (e.g. convex-helpers triggers) sit under the
+     * codec layer — codec on top → triggers → real db. See #92.
+     *
+     * ```ts
+     * const triggers = new Triggers<DataModel>()
+     * initZodvex(schema, server, {
+     *   underlyingDb: { mutation: (ctx) => triggers.wrapDB(ctx).db }
+     * })
+     * ```
+     */
+    underlyingDb?: ZodvexUnderlyingDb<
+      GenericQueryCtx<DM>,
+      GenericMutationCtx<DM>,
+      GenericDatabaseReader<DM>,
+      GenericDatabaseWriter<DM>
+    >
+  }
 ): {
   zq: ZodvexBuilder<'query', { db: ZodvexDatabaseReader<DM, DD> }, GenericQueryCtx<DM>, 'public'>
   zm: ZodvexBuilder<
@@ -279,11 +302,23 @@ export function initZodvex<
 export function initZodvex(
   schema: { __zodTableMap: ZodTableMap },
   server: InitServerBuilders,
-  options?: { wrapDb?: boolean; registry?: () => AnyRegistry }
+  options?: {
+    wrapDb?: boolean
+    registry?: () => AnyRegistry
+    underlyingDb?: ZodvexUnderlyingDb
+  }
 ) {
-  const codec = createZodvexCustomization(schema.__zodTableMap)
-  const noOp = createNoOpCustomization()
   const wrap = options?.wrapDb !== false
+  if (!wrap && options?.underlyingDb) {
+    throw new Error(
+      '[zodvex] initZodvex: `underlyingDb` requires the codec db wrapper — ' +
+        'remove `wrapDb: false` or drop `underlyingDb`.'
+    )
+  }
+  const codec = createZodvexCustomization(schema.__zodTableMap, {
+    underlyingDb: options?.underlyingDb
+  })
+  const noOp = createNoOpCustomization()
 
   const registryThunk = options?.registry
   const actionCust = createActionCustomization(registryThunk, noOp)

package/src/public/server/index.ts

@@ -31,7 +31,10 @@ export {
   zCustomQuery
 } from '../../internal/custom'
 // Codec customization (manual composition escape hatch)
-export { createZodvexCustomization } from '../../internal/customization'
+export {
+  createZodvexCustomization,
+  type ZodvexUnderlyingDb
+} from '../../internal/customization'
 // Database wrappers (ZodvexDatabaseReader, ZodvexDatabaseWriter, etc.)
 export {
   createZodDbReader,