turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/errors.d.ts

@@ -0,0 +1,370 @@
+/**
+ * turbine-orm — Error types
+ *
+ * Typed errors with error codes for programmatic handling.
+ * All Turbine errors extend TurbineError which includes a `code` property.
+ */
+/** Error codes for all Turbine errors */
+export declare const TurbineErrorCode: {
+    readonly NOT_FOUND: "TURBINE_E001";
+    readonly TIMEOUT: "TURBINE_E002";
+    readonly VALIDATION: "TURBINE_E003";
+    readonly CONNECTION: "TURBINE_E004";
+    readonly RELATION: "TURBINE_E005";
+    readonly MIGRATION: "TURBINE_E006";
+    readonly CIRCULAR_RELATION: "TURBINE_E007";
+    readonly UNIQUE_VIOLATION: "TURBINE_E008";
+    readonly FOREIGN_KEY_VIOLATION: "TURBINE_E009";
+    readonly NOT_NULL_VIOLATION: "TURBINE_E010";
+    readonly CHECK_VIOLATION: "TURBINE_E011";
+    readonly DEADLOCK_DETECTED: "TURBINE_E012";
+    readonly SERIALIZATION_FAILURE: "TURBINE_E013";
+    readonly PIPELINE: "TURBINE_E014";
+    readonly OPTIMISTIC_LOCK: "TURBINE_E015";
+    readonly EXCLUSION_VIOLATION: "TURBINE_E016";
+    readonly UNSUPPORTED_FEATURE: "TURBINE_E017";
+    readonly READ_ONLY: "TURBINE_E018";
+};
+export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
+/** Base error class for all Turbine errors */
+export declare class TurbineError extends Error {
+    readonly code: TurbineErrorCode;
+    constructor(code: TurbineErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Controls whether NotFoundError messages include the actual `where` values
+ * (`'verbose'`) or only the where-clause keys (`'safe'`, the default).
+ *
+ * Defaults to `'safe'` to avoid leaking PII into error logs (Sentry, Datadog,
+ * etc.). The full `where` object is always available as `err.where` for
+ * programmatic access — only the human-readable message is redacted.
+ *
+ * Set via `setErrorMessageMode('verbose')` or by constructing TurbineClient
+ * with `{ errorMessages: 'verbose' }`.
+ */
+export type ErrorMessageMode = 'safe' | 'verbose';
+/**
+ * Set the global NotFoundError message mode. Called from the TurbineClient
+ * constructor when `TurbineConfig.errorMessages` is provided.
+ *
+ *   - `'safe'`    (default): the message includes only the keys of the where
+ *     clause (e.g. `where: { id, email }`). Values are redacted.
+ *   - `'verbose'`: the message includes the full JSON-serialized where
+ *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ */
+export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
+/** Returns the current NotFoundError message mode. Exported for tests. */
+export declare function getErrorMessageMode(): ErrorMessageMode;
+/**
+ * Render a user-supplied `where` / `connect` target for a "no row found" error
+ * message, honoring the global {@link ErrorMessageMode}. In 'safe' mode (the
+ * default) only the key names are shown (`keys [email, id]`) so that PII values
+ * never leak into logs; in 'verbose' mode the full JSON serialization is used.
+ *
+ * This mirrors {@link NotFoundError}'s redaction so that every "no row found"
+ * message in the library follows one convention, including the nested-write
+ * connect/update failures which historically embedded the raw values.
+ */
+export declare function describeTargetForMessage(target: unknown): string;
+/**
+ * Thrown when a record is not found (findUniqueOrThrow, findFirstOrThrow,
+ * update/delete against a non-matching row, etc.)
+ *
+ * Supports two call styles for back-compat:
+ *   - `new NotFoundError()` / `new NotFoundError('custom message')`
+ *   - `new NotFoundError({ table, where, operation, cause, message })`
+ *
+ * When called with an options object and no explicit `message`, a Prisma-style
+ * message is built automatically. By default, only the where-clause keys are
+ * shown to avoid leaking PII into logs:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: { id }`
+ *
+ * Set `setErrorMessageMode('verbose')` (or pass `errorMessages: 'verbose'` to
+ * the TurbineClient constructor) to include the full where values:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: {"id":1}`
+ *
+ * The full `where` object, `table`, and `operation` are always available as
+ * structured properties on the error instance regardless of mode.
+ */
+export declare class NotFoundError extends TurbineError {
+    readonly table?: string;
+    readonly where?: unknown;
+    readonly operation?: string;
+    constructor(input?: string | {
+        table?: string;
+        where?: unknown;
+        operation?: string;
+        cause?: unknown;
+        message?: string;
+    });
+}
+/** Thrown when a query or transaction exceeds the configured timeout */
+export declare class TimeoutError extends TurbineError {
+    readonly timeoutMs: number;
+    /**
+     * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
+     *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
+     *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
+     * @param context human label for the operation ("Query", "Transaction").
+     * @param options optional `message` override and pg `cause` to preserve, used
+     *   when wrapping a driver error rather than a client-side timer expiry.
+     */
+    constructor(timeoutMs: number, context?: string, options?: {
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Thrown when query arguments fail validation (unknown column, invalid operator, etc.) */
+export declare class ValidationError extends TurbineError {
+    constructor(message: string);
+}
+/** Thrown when a database connection fails */
+export declare class ConnectionError extends TurbineError {
+    /**
+     * @param message human-readable connection failure description.
+     * @param options optional pg/driver `cause` to preserve, used when wrapping a
+     *   connection-class driver error via `wrapPgError`.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a relation reference is invalid */
+export declare class RelationError extends TurbineError {
+    constructor(message: string);
+}
+/** Thrown when a migration operation fails */
+export declare class MigrationError extends TurbineError {
+    constructor(message: string);
+}
+/** Thrown when circular relation nesting is detected */
+export declare class CircularRelationError extends TurbineError {
+    readonly path: string[];
+    constructor(path: string[]);
+}
+/** Thrown when a UNIQUE constraint is violated (pg code 23505) */
+export declare class UniqueConstraintError extends TurbineError {
+    readonly constraint?: string;
+    readonly columns?: string[];
+    readonly table?: string;
+    constructor(opts?: {
+        constraint?: string;
+        columns?: string[];
+        table?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Thrown when a FOREIGN KEY constraint is violated (pg code 23503) */
+export declare class ForeignKeyError extends TurbineError {
+    readonly constraint?: string;
+    readonly table?: string;
+    constructor(opts?: {
+        constraint?: string;
+        table?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Thrown when a NOT NULL constraint is violated (pg code 23502) */
+export declare class NotNullViolationError extends TurbineError {
+    readonly column?: string;
+    readonly table?: string;
+    constructor(opts?: {
+        column?: string;
+        table?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when Postgres detects a deadlock (pg code 40P01).
+ *
+ * This error is **retryable** — when caught, callers can safely retry the
+ * transaction (typically with backoff). Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... });
+ * } catch (err) {
+ *   if (err instanceof DeadlockError) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export declare class DeadlockError extends TurbineError {
+    /** Marks this error as safe to retry */
+    readonly isRetryable: true;
+    readonly constraint?: string;
+    constructor(opts?: {
+        message?: string;
+        constraint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a Serializable transaction fails due to a serialization
+ * conflict (pg code 40001 — `could not serialize access due to ...`).
+ *
+ * This error is **retryable** — by Postgres documentation, the recommended
+ * response is to re-run the entire transaction. Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... }, { isolationLevel: 'Serializable' });
+ * } catch (err) {
+ *   if (err instanceof SerializationFailureError) {
+ *     // safe to retry the whole transaction
+ *   }
+ * }
+ * ```
+ */
+export declare class SerializationFailureError extends TurbineError {
+    /** Marks this error as safe to retry */
+    readonly isRetryable: true;
+    constructor(opts?: {
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Thrown when a CHECK constraint is violated (pg code 23514) */
+export declare class CheckConstraintError extends TurbineError {
+    readonly constraint?: string;
+    readonly table?: string;
+    constructor(opts?: {
+        constraint?: string;
+        table?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+export declare class ExclusionConstraintError extends TurbineError {
+    readonly constraint?: string;
+    readonly table?: string;
+    constructor(opts?: {
+        constraint?: string;
+        table?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Result slot for a single query in a non-transactional pipeline */
+export type PipelineResultSlot = {
+    status: 'ok';
+    value: unknown;
+} | {
+    status: 'error';
+    error: Error;
+};
+/**
+ * Thrown when a non-transactional pipeline has partial failures.
+ *
+ * In non-transactional mode (`{ transactional: false }`), each query executes
+ * independently. If one or more queries fail, the pipeline rejects with a
+ * `PipelineError` that carries per-query results so callers can inspect which
+ * succeeded and which failed.
+ *
+ * ```ts
+ * try {
+ *   await db.pipeline([q1, q2, q3], { transactional: false });
+ * } catch (err) {
+ *   if (err instanceof PipelineError) {
+ *     for (const slot of err.results) {
+ *       if (slot.status === 'error') console.error(slot.error);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class PipelineError extends TurbineError {
+    /** Per-query results: each slot is either `{status:'ok', value}` or `{status:'error', error}` */
+    readonly results: PipelineResultSlot[];
+    /** Zero-based index of the first query that failed */
+    readonly failedIndex?: number;
+    /** Tag of the first query that failed (from DeferredQuery.tag) */
+    readonly failedTag?: string;
+    constructor(opts: {
+        message?: string;
+        results: PipelineResultSlot[];
+        failedIndex?: number;
+        failedTag?: string;
+        cause?: unknown;
+    });
+}
+export declare class OptimisticLockError extends TurbineError {
+    readonly table: string;
+    readonly versionField: string;
+    readonly expectedVersion: unknown;
+    constructor(opts: {
+        table: string;
+        versionField: string;
+        expectedVersion: unknown;
+    });
+}
+/**
+ * Thrown when a Postgres-only feature (pgvector distance ops, LISTEN/NOTIFY
+ * realtime, RLS session GUCs, advisory-lock migration locking, ...) is invoked
+ * on a dialect/engine whose capability flag reports it unsupported. Surfaces a
+ * clear `unsupported on <engine>` message instead of generating broken SQL.
+ */
+export declare class UnsupportedFeatureError extends TurbineError {
+    readonly feature: string;
+    readonly dialect: string;
+    constructor(feature: string, dialect: string, hint?: string);
+}
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+export declare class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    readonly reason: 'snapshot' | 'rbac';
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail: string, options?: {
+        cause?: unknown;
+        reason?: 'snapshot' | 'rbac';
+    });
+}
+/**
+ * Translate a pg driver error into a typed Turbine error.
+ * If the error doesn't match a known constraint code, returns it unchanged.
+ *
+ * Maps:
+ *   23505 (unique_violation)      -> UniqueConstraintError
+ *   23503 (foreign_key_violation) -> ForeignKeyError
+ *   23502 (not_null_violation)    -> NotNullViolationError
+ *   23514 (check_violation)       -> CheckConstraintError
+ *   23P01 (exclusion_violation)   -> ExclusionConstraintError
+ *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
+ *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
+ *
+ * The original pg error is preserved as `.cause` on the wrapped error.
+ */
+export declare function wrapPgError(err: unknown): unknown;

package/dist/cjs/generate.d.ts

@@ -0,0 +1,137 @@
+/**
+ * turbine-orm — Code generator
+ *
+ * Takes an IntrospectedSchema and emits TypeScript files:
+ *   - types.ts     — Entity interfaces, Create/Update input types
+ *   - metadata.ts  — Runtime schema metadata (column maps, relations, etc.)
+ *   - index.ts     — Configured TurbineClient with typed table accessors
+ *
+ * Output goes to the specified directory (default: ./generated/turbine/).
+ */
+import { type PrismaCompatMap, type SchemaMetadata } from './schema.js';
+export interface GenerateOptions {
+    /** The introspected schema to generate from */
+    schema: SchemaMetadata;
+    /** Output directory (default: './generated/turbine') */
+    outDir?: string;
+    /** Redact connection string from generated comments */
+    connectionString?: string;
+    /**
+     * Also emit `zod.ts` with per-table `XSchema` / `XCreateSchema` /
+     * `XUpdateSchema` Zod validators (H1). The file imports the user-side `zod`
+     * package — it is never imported by Turbine's runtime, so Zod stays out of the
+     * library's dependency graph. Default: `false`.
+     */
+    zod?: boolean;
+    /**
+     * Omit the `Generated at: <ISO timestamp>` line from every generated file
+     * header (T-8b — reproducible codegen). With this set, byte-identical
+     * schemas regenerate to byte-identical output, so regens produce empty
+     * diffs. Default: `false` (timestamp included, unchanged behavior).
+     */
+    noTimestamp?: boolean;
+    /**
+     * Which extension the generated `index.ts` uses on its sibling import
+     * specifiers (`./types`, `./metadata`). F3.
+     *
+     *   - `'js'`: always `./types.js` (required by NodeNext `tsc` and by
+     *     tsc-compiled ESM run on Node; the pre-0.41 behavior).
+     *   - `'none'`: always `./types` (correct for bundlers / `moduleResolution
+     *     bundler | node10`: webpack, Next.js/SWC, Vite/esbuild).
+     *   - `'auto'` (default): walk up from `outDir` to the nearest `tsconfig.json`
+     *     (extends chains are NOT followed) and emit `'.js'` when its `module` /
+     *     `moduleResolution` is `node16`/`nodenext`, `''` when both are present and
+     *     neither is, and fall back to `'.js'` when the tsconfig is missing,
+     *     unparseable, or ambiguous (so NodeNext consumers can never regress).
+     */
+    importExtension?: 'js' | 'none' | 'auto';
+    /**
+     * Rewrite generated column FIELD names to the raw database column names
+     * (snake_case) instead of camelCase (F4). Opt-in; when unset the output is
+     * byte-identical to before. Implemented as the pure generate-time
+     * {@link withDbFieldNames} transform (identity `columnMap`/`reverseColumnMap`,
+     * zero runtime changes). Relation names, table accessors, and entity type
+     * names are unaffected.
+     */
+    keepColumnNames?: boolean;
+}
+/** Per-file generator options (subset of {@link GenerateOptions} the emitters need). */
+export interface GenerateFileOptions {
+    /** Omit the `Generated at:` header line for reproducible output. */
+    noTimestamp?: boolean;
+    /**
+     * Resolved sibling-import extension for `generateIndex` (`'.js'` or `''`).
+     * Defaults to `'.js'` when unset so direct callers stay byte-stable.
+     */
+    importExt?: string;
+    /** Human-readable resolved import mode, recorded as a comment in `index.ts`. */
+    importMode?: string;
+}
+export declare function generate(options: GenerateOptions): {
+    outDir: string;
+    files: string[];
+};
+/**
+ * Resolve the requested {@link GenerateOptions.importExtension} to the concrete
+ * extension string used on `index.ts`'s sibling imports plus a human-readable
+ * mode label for the generated comment.
+ *
+ *   - `'js'`   → `.js`
+ *   - `'none'` → `''`
+ *   - `'auto'` → tsconfig-driven ({@link detectTsconfigExtension}); falls back
+ *     to `.js` (the pre-0.41 default) when detection is uncertain, so NodeNext
+ *     consumers can never regress.
+ */
+export declare function resolveImportExtension(outDir: string, requested: 'js' | 'none' | 'auto'): {
+    ext: string;
+    mode: string;
+};
+/**
+ * Walk up from `startDir` to the nearest `tsconfig.json` and classify its module
+ * resolution. Does NOT follow `extends` chains (a monorepo whose base config
+ * sets `moduleResolution` needs the explicit flag). Returns:
+ *   - `'js'`: `module`/`moduleResolution` is `node16`/`nodenext`;
+ *   - `'none'`: both fields present and neither is node16/nodenext (bundler,
+ *     node, node10, classic, esnext, commonjs, preserve);
+ *   - `null`: no tsconfig found, unparseable, or the fields are absent
+ *     (possibly hidden behind `extends`) → caller falls back to `.js`.
+ */
+export declare function detectTsconfigExtension(startDir: string): 'js' | 'none' | null;
+/**
+ * Classify a tsconfig's `compilerOptions.module` / `moduleResolution` (see
+ * {@link detectTsconfigExtension}). Tolerant of `//` and block comments and
+ * trailing commas (real-world tsconfigs use JSONC).
+ */
+export declare function classifyTsconfig(text: string): 'js' | 'none' | null;
+/**
+ * Strip `//` line comments and block comments from JSONC text, leaving anything
+ * inside a double-quoted string untouched. Trailing commas are then removed so
+ * `JSON.parse` accepts the result.
+ */
+export declare function stripJsonComments(text: string): string;
+/**
+ * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
+ * and *Relations brand-field interfaces). Exported so tests can pin the
+ * generator output without writing files to disk.
+ */
+export declare function generateTypes(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+/**
+ * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
+ * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
+ * generated columns omitted), and `XUpdateSchema` (PK + STORED generated
+ * columns omitted, every remaining column optional). Exported so tests can pin
+ * the output without writing files.
+ */
+export declare function generateZod(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateMetadata(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+export declare function generateIndex(schema: SchemaMetadata, options?: GenerateFileOptions): string;
+/**
+ * Serialize a resolved {@link PrismaCompatMap} into a `prisma-map.ts` module
+ * that exports `export const PRISMA_MAP: PrismaCompatMap = {...}`. Written next
+ * to the generated client by `turbine migrate-from-prisma`; consumed later by
+ * the phase-2 `turbine-orm/prisma-compat` runtime adapter.
+ *
+ * Deterministic: uses the same reproducible header as the other emitters, so a
+ * stable input regenerates byte-identical output under `noTimestamp`.
+ */
+export declare function generatePrismaMap(map: PrismaCompatMap, options?: GenerateFileOptions): string;

package/dist/cjs/generate.js

@@ -45,6 +45,30 @@ function columnTsType(col, enums) {
     }
     return col.tsType;
 }
+/**
+ * Resolve the TypeScript type a column accepts on the WRITE path (the `*Create`
+ * / `*Update` input types), which is wider than the row type for time-of-day
+ * columns.
+ *
+ * A `time` / `timetz` column reads back as a `string` (`'09:00:00'`), so the
+ * row type stays `string`. On write the runtime also accepts a JS `Date` and
+ * narrows it to its UTC time of day (see `coerceWriteValue` in
+ * query/writes.ts), matching Prisma, which types a `DateTime @db.Time(6)`
+ * field as a `Date`. Consumers porting from Prisma pass Dates, so the input
+ * type has to admit them. Every other column is unchanged.
+ */
+function writeColumnTsType(col, enums) {
+    const tsType = columnTsType(col, enums);
+    const dt = col.dialectType ?? col.pgType;
+    const isArray = col.isArray || dt.startsWith('_');
+    const base = isArray && dt.startsWith('_') ? dt.slice(1) : dt;
+    if (!(0, schema_js_1.timeOfDayKind)(base))
+        return tsType;
+    // A `time[]` column accepts a Date per element (the bind rewrite runs
+    // element-wise, see coerceTemporalValue in query/utils.ts).
+    const widened = isArray ? '(string | Date)[]' : 'string | Date';
+    return col.nullable ? `${widened} | null` : widened;
+}
 /** Escape a value for embedding in a single-quoted TypeScript string literal */
 function escSQ(value) {
     return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
@@ -345,10 +369,10 @@ function generateTypes(schema, options) {
             if (isOptional) {
                 const reason = isPk ? 'auto-generated' : col.hasDefault ? 'has default' : 'nullable';
                 lines.push(`  /** Optional: ${reason} */`);
-                lines.push(`  ${quoteIfNeeded(col.field)}?: ${columnTsType(col, schema.enums)};`);
+                lines.push(`  ${quoteIfNeeded(col.field)}?: ${writeColumnTsType(col, schema.enums)};`);
             }
             else {
-                lines.push(`  ${quoteIfNeeded(col.field)}: ${columnTsType(col, schema.enums)};`);
+                lines.push(`  ${quoteIfNeeded(col.field)}: ${writeColumnTsType(col, schema.enums)};`);
             }
         }
         lines.push('};');
@@ -360,7 +384,7 @@ function generateTypes(schema, options) {
         lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
         lines.push(`export type ${typeName}Update = {`);
         for (const col of nonPkCols) {
-            lines.push(`  ${quoteIfNeeded(col.field)}?: ${updateFieldType(columnTsType(col, schema.enums))};`);
+            lines.push(`  ${quoteIfNeeded(col.field)}?: ${updateFieldType(writeColumnTsType(col, schema.enums))};`);
         }
         lines.push('};');
         lines.push('');
@@ -578,8 +602,14 @@ function zodScalar(ts) {
  * Base Zod expression for a column, resolving enums → `z.enum([...])`, arrays →
  * `.array()`, and vectors → `z.array(z.number())`. Does NOT append
  * `.nullable()` / `.optional()` — callers layer those on per-schema.
+ *
+ * `forWrite` mirrors {@link writeColumnTsType}: the Create/Update schemas
+ * validate WRITE input, where a `time` / `timetz` column also accepts a JS
+ * `Date` (narrowed to its UTC time of day at bind time), so a bare
+ * `z.string()` there would reject a value the runtime happily writes. The
+ * full-row schema keeps `z.string()`, because that is what a read returns.
  */
-function zodBaseType(col, enums) {
+function zodBaseType(col, enums, forWrite = false) {
     const dt = col.dialectType ?? col.pgType;
     const isArray = col.isArray || dt.startsWith('_');
     const base = isArray && dt.startsWith('_') ? dt.slice(1) : dt;
@@ -587,6 +617,9 @@ function zodBaseType(col, enums) {
     if (Object.hasOwn(enums, base)) {
         expr = `z.enum([${enums[base].map((l) => `'${escSQ(l)}'`).join(', ')}])`;
     }
+    else if (forWrite && (0, schema_js_1.timeOfDayKind)(base)) {
+        expr = 'z.union([z.string(), z.date()])';
+    }
     else {
         expr = zodScalar((0, schema_js_1.pgTypeToTs)(base, false));
     }
@@ -628,7 +661,7 @@ function generateZod(schema, options) {
             if (col.isGeneratedStored)
                 continue;
             const isPk = table.primaryKey.includes(col.name);
-            let expr = zodBaseType(col, schema.enums);
+            let expr = zodBaseType(col, schema.enums, true);
             if (col.nullable)
                 expr += '.nullable()';
             if (col.hasDefault || col.nullable || isPk)
@@ -645,7 +678,7 @@ function generateZod(schema, options) {
                 continue;
             if (table.primaryKey.includes(col.name))
                 continue;
-            let expr = zodBaseType(col, schema.enums);
+            let expr = zodBaseType(col, schema.enums, true);
             if (col.nullable)
                 expr += '.nullable()';
             expr += '.optional()';