turbine-orm 0.13.3 → 0.15.0

package/dist/errors.d.ts

@@ -20,6 +20,8 @@ export declare const TurbineErrorCode: {
     readonly DEADLOCK_DETECTED: "TURBINE_E012";
     readonly SERIALIZATION_FAILURE: "TURBINE_E013";
     readonly PIPELINE: "TURBINE_E014";
+    readonly OPTIMISTIC_LOCK: "TURBINE_E015";
+    readonly EXCLUSION_VIOLATION: "TURBINE_E016";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -208,6 +210,16 @@ export declare class CheckConstraintError extends TurbineError {
         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';
@@ -251,6 +263,16 @@ export declare class PipelineError extends TurbineError {
         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;
+    });
+}
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.
@@ -260,6 +282,7 @@ export declare class PipelineError extends TurbineError {
  *   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)
  *

package/dist/errors.js

@@ -20,6 +20,8 @@ export const TurbineErrorCode = {
     DEADLOCK_DETECTED: 'TURBINE_E012',
     SERIALIZATION_FAILURE: 'TURBINE_E013',
     PIPELINE: 'TURBINE_E014',
+    OPTIMISTIC_LOCK: 'TURBINE_E015',
+    EXCLUSION_VIOLATION: 'TURBINE_E016',
 };
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
@@ -331,6 +333,25 @@ export class CheckConstraintError extends TurbineError {
         this.table = table;
     }
 }
+export class ExclusionConstraintError extends TurbineError {
+    constraint;
+    table;
+    constructor(opts = {}) {
+        const { constraint, table, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const constraintPart = constraint ? ` on ${constraint}` : '';
+            message = `[turbine] Exclusion constraint violation${constraintPart}`;
+            const detail = detailFromCause(cause);
+            if (detail)
+                message += `: ${detail}`;
+        }
+        super(TurbineErrorCode.EXCLUSION_VIOLATION, message, { cause });
+        this.name = 'ExclusionConstraintError';
+        this.constraint = constraint;
+        this.table = table;
+    }
+}
 /**
  * Thrown when a non-transactional pipeline has partial failures.
  *
@@ -371,6 +392,19 @@ export class PipelineError extends TurbineError {
         this.failedTag = failedTag;
     }
 }
+export class OptimisticLockError extends TurbineError {
+    table;
+    versionField;
+    expectedVersion;
+    constructor(opts) {
+        super(TurbineErrorCode.OPTIMISTIC_LOCK, `[turbine] Optimistic lock failed on "${opts.table}" — ` +
+            `expected ${opts.versionField} = ${opts.expectedVersion} but row was modified by another transaction`);
+        this.name = 'OptimisticLockError';
+        this.table = opts.table;
+        this.versionField = opts.versionField;
+        this.expectedVersion = opts.expectedVersion;
+    }
+}
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."
@@ -391,6 +425,7 @@ function parseColumnsFromDetail(detail) {
  *   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)
  *
@@ -430,6 +465,12 @@ export function wrapPgError(err) {
                 table: e.table,
                 cause: err,
             });
+        case '23P01':
+            return new ExclusionConstraintError({
+                constraint: e.constraint,
+                table: e.table,
+                cause: err,
+            });
         case '40P01':
             return new DeadlockError({
                 constraint: e.constraint,

package/dist/generate.js

@@ -177,6 +177,92 @@ export function generateTypes(schema) {
             }
         }
     }
+    // ---------------------------------------------------------------------------
+    // Nested write types (WhereUnique, NestedCreateInput, NestedUpdateInput,
+    // ConnectOrCreate, CreateInput, UpdateInput)
+    // ---------------------------------------------------------------------------
+    for (const table of Object.values(schema.tables)) {
+        const typeName = entityName(table.name);
+        const hasRels = Object.keys(table.relations).length > 0;
+        // WhereUnique — union of unique constraint shapes, deduplicating PK
+        const seen = new Set();
+        const uniqueSets = [];
+        // Always include the primary key first
+        const pkKey = table.primaryKey.join(',');
+        seen.add(pkKey);
+        uniqueSets.push(table.primaryKey);
+        // Add unique indexes that aren't duplicates of the PK
+        for (const uc of table.uniqueColumns) {
+            const ucKey = uc.join(',');
+            if (!seen.has(ucKey)) {
+                seen.add(ucKey);
+                uniqueSets.push(uc);
+            }
+        }
+        if (uniqueSets.length > 0) {
+            const branches = uniqueSets.map((cols) => {
+                const fields = cols.map((colName) => {
+                    const col = table.columns.find((c) => c.name === colName);
+                    const field = col?.field ?? colName;
+                    const tsType = col?.tsType ?? 'unknown';
+                    return `${field}: ${tsType}`;
+                });
+                return `{ ${fields.join('; ')} }`;
+            });
+            lines.push(`export type ${typeName}WhereUnique = ${branches.join(' | ')};`);
+            lines.push('');
+        }
+        // CreateInput / UpdateInput — extends base type with optional relation fields
+        if (hasRels) {
+            lines.push(`export type ${typeName}CreateInput = ${typeName}Create & {`);
+            for (const [relName, rel] of Object.entries(table.relations)) {
+                const targetType = entityName(rel.to);
+                lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
+            }
+            lines.push('};');
+            lines.push('');
+            lines.push(`export type ${typeName}UpdateInput = ${typeName}Update & {`);
+            for (const [relName, rel] of Object.entries(table.relations)) {
+                const targetType = entityName(rel.to);
+                if (rel.type === 'hasMany') {
+                    lines.push(`  ${relName}?: ${targetType}NestedUpdateInput;`);
+                }
+                else {
+                    lines.push(`  ${relName}?: ${targetType}NestedCreateInput;`);
+                }
+            }
+            lines.push('};');
+            lines.push('');
+        }
+    }
+    // Emit NestedCreateInput, NestedUpdateInput, ConnectOrCreate for every table
+    for (const table of Object.values(schema.tables)) {
+        const typeName = entityName(table.name);
+        const hasRels = Object.keys(table.relations).length > 0;
+        // NestedCreateInput uses *CreateInput (which includes relation fields) when
+        // the table has relations, otherwise falls back to the plain *Create type.
+        const createRefType = hasRels ? `${typeName}CreateInput` : `${typeName}Create`;
+        lines.push(`export interface ${typeName}NestedCreateInput {`);
+        lines.push(`  create?: ${createRefType} | ${createRefType}[];`);
+        lines.push(`  connect?: ${typeName}WhereUnique | ${typeName}WhereUnique[];`);
+        lines.push(`  connectOrCreate?: ${typeName}ConnectOrCreate | ${typeName}ConnectOrCreate[];`);
+        lines.push('}');
+        lines.push('');
+        lines.push(`export interface ${typeName}NestedUpdateInput {`);
+        lines.push(`  create?: ${createRefType} | ${createRefType}[];`);
+        lines.push(`  connect?: ${typeName}WhereUnique | ${typeName}WhereUnique[];`);
+        lines.push(`  connectOrCreate?: ${typeName}ConnectOrCreate | ${typeName}ConnectOrCreate[];`);
+        lines.push(`  disconnect?: ${typeName}WhereUnique | ${typeName}WhereUnique[];`);
+        lines.push(`  set?: ${typeName}WhereUnique[];`);
+        lines.push(`  delete?: ${typeName}WhereUnique | ${typeName}WhereUnique[];`);
+        lines.push('}');
+        lines.push('');
+        lines.push(`export interface ${typeName}ConnectOrCreate {`);
+        lines.push(`  where: ${typeName}WhereUnique;`);
+        lines.push(`  create: ${createRefType};`);
+        lines.push('}');
+        lines.push('');
+    }
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -214,7 +300,13 @@ function generateMetadata(schema) {
         // dateColumns
         const dateCols = [...table.dateColumns];
         lines.push(`      dateColumns: new Set([${dateCols.map((c) => `'${escSQ(c)}'`).join(', ')}]),`);
-        // pgTypes
+        // dialectTypes + pgTypes (pgTypes is kept for backwards compatibility)
+        const dialectTypes = table.dialectTypes ?? table.pgTypes;
+        lines.push('      dialectTypes: {');
+        for (const [col, dialectType] of Object.entries(dialectTypes)) {
+            lines.push(`        ${quoteIfNeeded(col)}: '${escSQ(dialectType)}',`);
+        }
+        lines.push('      },');
         lines.push('      pgTypes: {');
         for (const [col, pgType] of Object.entries(table.pgTypes)) {
             lines.push(`        ${quoteIfNeeded(col)}: '${escSQ(pgType)}',`);
@@ -388,11 +480,13 @@ function serializeColumn(col) {
     const parts = [
         `name: '${escSQ(col.name)}'`,
         `field: '${escSQ(col.field)}'`,
+        `dialectType: '${escSQ(col.dialectType ?? col.pgType)}'`,
         `pgType: '${escSQ(col.pgType)}'`,
         `tsType: '${escSQ(col.tsType)}'`,
         `nullable: ${col.nullable}`,
         `hasDefault: ${col.hasDefault}`,
         `isArray: ${col.isArray}`,
+        `arrayType: '${escSQ(col.arrayType ?? col.pgArrayType)}'`,
         `pgArrayType: '${escSQ(col.pgArrayType)}'`,
     ];
     if (col.maxLength !== undefined)

package/dist/index.d.ts

@@ -34,14 +34,15 @@
  */
 export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
-export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, } from './client.js';
+export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, withRetry, } from './client.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, UpsertStatementInput, } from './dialect.js';
 export { postgresDialect } from './dialect.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
+export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationDescriptor, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderDirection, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';

package/dist/index.js

@@ -34,14 +34,16 @@
  */
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 // Client
-export { TransactionClient, TurbineClient, } from './client.js';
+export { TransactionClient, TurbineClient, withRetry, } from './client.js';
 export { postgresDialect } from './dialect.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
 export { generate } from './generate.js';
 // Introspection
 export { introspect } from './introspect.js';
+// Nested writes
+export { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 // Pipeline
 export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder

package/dist/introspect.js

@@ -8,7 +8,8 @@
  * This is the foundation of `npx turbine generate`.
  */
 import pg from 'pg';
-import { isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
+import { postgresDialect } from './dialect.js';
+import { isDateType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
 // SQL queries (all parameterized, no interpolation)
 // ---------------------------------------------------------------------------
@@ -95,6 +96,7 @@ const SQL_ENUMS = `
 // ---------------------------------------------------------------------------
 export async function introspect(options) {
     const schema = options.schema ?? 'public';
+    const dialect = postgresDialect;
     const pool = new pg.Pool({
         connectionString: options.connectionString,
         max: 1,
@@ -131,15 +133,20 @@ export async function introspect(options) {
             const isNullable = row.is_nullable === 'YES';
             const isArray = row.data_type === 'ARRAY';
             const baseType = isArray ? row.udt_name.slice(1) : row.udt_name;
+            const dialectType = row.udt_name;
+            const arrayType = dialect.arrayType?.(baseType) ?? 'text[]';
             const col = {
                 name: row.column_name,
                 field: snakeToCamel(row.column_name),
-                pgType: row.udt_name,
-                tsType: pgTypeToTs(isArray ? row.udt_name : baseType, isNullable),
+                dialectType,
+                pgType: dialectType,
+                tsType: dialect.typeToTypeScript?.(isArray ? dialectType : baseType, isNullable) ??
+                    pgTypeToTs(isArray ? dialectType : baseType, isNullable),
                 nullable: isNullable,
                 hasDefault: row.column_default !== null,
                 isArray,
-                pgArrayType: pgArrayType(baseType),
+                arrayType,
+                pgArrayType: arrayType,
                 maxLength: row.character_maximum_length ?? undefined,
             };
             if (!columnsByTable.has(tableName))
@@ -275,14 +282,16 @@ export async function introspect(options) {
             const columnMap = {};
             const reverseColumnMap = {};
             const dateColumns = new Set();
+            const dialectTypes = {};
             const pgTypes = {};
             const allColumns = [];
             for (const col of columns) {
                 columnMap[col.field] = col.name;
                 reverseColumnMap[col.name] = col.field;
                 allColumns.push(col.name);
+                dialectTypes[col.name] = col.dialectType ?? col.pgType;
                 pgTypes[col.name] = col.pgType;
-                const baseType = col.isArray ? col.pgType.slice(1) : col.pgType;
+                const baseType = col.isArray ? (col.dialectType ?? col.pgType).slice(1) : (col.dialectType ?? col.pgType);
                 if (isDateType(baseType)) {
                     dateColumns.add(col.name);
                 }
@@ -293,6 +302,7 @@ export async function introspect(options) {
                 columnMap,
                 reverseColumnMap,
                 dateColumns,
+                dialectTypes,
                 pgTypes,
                 allColumns,
                 primaryKey: pkByTable.get(tableName) ?? [],

package/dist/nested-write.d.ts

@@ -0,0 +1,95 @@
+/**
+ * turbine-orm — Nested write engine
+ *
+ * Tree-walking create/update that resolves relation fields in `data` into
+ * batched SQL operations within a transaction. Supports create, connect,
+ * connectOrCreate, disconnect, set, and delete on related records at
+ * arbitrary depth (capped at 10).
+ *
+ * This module is imported by `query/builder.ts` when the `data` argument
+ * of `create()` or `update()` contains relation fields. It never imports
+ * `client.ts` directly — the transaction handle is passed in via
+ * `NestedWriteContext`.
+ */
+import type { RelationDef, SchemaMetadata, TableMetadata } from './schema.js';
+export interface ExtractedFields {
+    scalars: Record<string, unknown>;
+    relations: Record<string, Record<string, unknown>>;
+}
+/**
+ * Transaction context for nested write operations.
+ * Matches the subset of TransactionClient that we actually use.
+ */
+export interface NestedWriteContext {
+    schema: SchemaMetadata;
+    tx: {
+        table<T extends object>(name: string): {
+            create(args: {
+                data: Partial<T>;
+            }): Promise<T>;
+            createMany(args: {
+                data: Partial<T>[];
+            }): Promise<T[]>;
+            update(args: {
+                where: Record<string, unknown>;
+                data: Record<string, unknown>;
+            }): Promise<T>;
+            updateMany(args: {
+                where: Record<string, unknown>;
+                data: Record<string, unknown>;
+                allowFullTableScan?: boolean;
+            }): Promise<{
+                count: number;
+            }>;
+            delete(args: {
+                where: Record<string, unknown>;
+            }): Promise<T>;
+            deleteMany(args: {
+                where: Record<string, unknown>;
+            }): Promise<{
+                count: number;
+            }>;
+            findMany(args: {
+                where: Record<string, unknown>;
+            }): Promise<T[]>;
+            findUnique(args: {
+                where: Record<string, unknown>;
+                with?: Record<string, unknown>;
+            }): Promise<T | null>;
+        };
+    };
+}
+/**
+ * Separates scalar data fields from relation operation fields.
+ *
+ * A key is treated as a relation field only when:
+ * 1. It matches a relation name in `tableMeta.relations`
+ * 2. Its value is a non-null, non-array, non-Date plain object
+ *
+ * Everything else goes into `scalars`.
+ */
+export declare function extractRelationFields(data: Record<string, unknown>, tableMeta: TableMetadata): ExtractedFields;
+/**
+ * Quick check: does `data` contain any relation fields that would trigger
+ * the nested write path? Used by QueryInterface to decide whether to
+ * delegate to the nested write engine or take the fast scalar-only path.
+ */
+export declare function hasRelationFields(data: Record<string, unknown>, tableMeta: TableMetadata): boolean;
+/**
+ * Inject the parent row's PK value(s) as FK field(s) into child data.
+ * Handles composite keys. Returns a new object (does not mutate input).
+ */
+export declare function injectForeignKey(childData: Record<string, unknown>, relation: RelationDef, parentRow: Record<string, unknown>, schema: SchemaMetadata): Record<string, unknown>;
+/**
+ * Tree-walking create: inserts the parent row, then processes each relation
+ * operation (create, connect, connectOrCreate), and finally reads back the
+ * full tree using `findUnique` with an auto-built `with` clause.
+ */
+export declare function executeNestedCreate(ctx: NestedWriteContext, tableName: string, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;
+/**
+ * Tree-walking update: updates the parent row with scalar data, then
+ * processes each relation operation (create, connect, connectOrCreate,
+ * disconnect, set, delete), and reads back the full tree.
+ */
+export declare function executeNestedUpdate(ctx: NestedWriteContext, tableName: string, where: Record<string, unknown>, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;
+//# sourceMappingURL=nested-write.d.ts.map