turbine-orm 0.14.0 → 0.15.0

package/dist/query/builder.js

@@ -11,7 +11,8 @@
  * metadata — nothing is hardcoded.
  */
 import { postgresDialect } from '../dialect.js';
-import { CircularRelationError, NotFoundError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
+import { CircularRelationError, NotFoundError, OptimisticLockError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
+import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, sqlToPreparedName } from './utils.js';
 // ---------------------------------------------------------------------------
@@ -97,6 +98,28 @@ function findArrayUniqueKey(value) {
     }
     return null;
 }
+/** Known text search operator keys */
+const TEXT_SEARCH_KEYS = new Set(['search', 'config']);
+/** Check if a value is a TextSearchFilter object */
+function isTextSearchFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    // Must have 'search' key and only known text search keys
+    return keys.includes('search') && keys.every((k) => TEXT_SEARCH_KEYS.has(k));
+}
+/**
+ * Validate a text search config name. Only alphanumeric characters and
+ * underscores are allowed to prevent SQL injection via the config parameter.
+ */
+function validateTextSearchConfig(config) {
+    return /^[a-zA-Z0-9_]+$/.test(config);
+}
 // biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
@@ -128,6 +151,10 @@ export class QueryInterface {
     columnArrayTypeMap;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     deepWithWarned = new Set();
+    /** True when this QI runs inside an active transaction (set via _txScoped option). */
+    txScoped;
+    /** Original options reference — forwarded to child QIs in nested writes. */
+    options;
     constructor(pool, table, schema, middlewares, options) {
         this.pool = pool;
         this.table = table;
@@ -146,6 +173,8 @@ export class QueryInterface {
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
         this.dialect = options?.dialect ?? postgresDialect;
+        this.txScoped = options?._txScoped ?? false;
+        this.options = options;
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
@@ -723,6 +752,9 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async create(args) {
         return this.executeWithMiddleware('create', args, async () => {
+            if (hasRelationFields(args.data, this.tableMeta)) {
+                return this.nestedCreate(args);
+            }
             const deferred = this.buildCreate(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
@@ -805,6 +837,9 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async update(args) {
         return this.executeWithMiddleware('update', args, async () => {
+            if (hasRelationFields(args.data, this.tableMeta)) {
+                return this.nestedUpdate(args);
+            }
             const deferred = this.buildUpdate(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
             return deferred.transform(result);
@@ -813,32 +848,62 @@ export class QueryInterface {
     buildUpdate(args) {
         const dataObj = args.data;
         const whereObj = args.where;
+        const lock = args.optimisticLock;
         const setFp = this.fingerprintSet(dataObj);
         const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `u:${setFp}|${whereFp}`;
+        const ck = lock ? null : `u:${setFp}|${whereFp}`;
         const params = [];
-        const entry = this.acquireSql(ck, () => {
+        const buildSql = () => {
             const freshParams = [];
             const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
             const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
+            if (lock) {
+                const versionCol = this.toSqlColumn(lock.field);
+                setClauses.push(`${versionCol} = ${versionCol} + 1`);
+            }
             const whereClause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+            let whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+            if (lock) {
+                const versionCol = this.toSqlColumn(lock.field);
+                freshParams.push(lock.expected);
+                const versionCheck = `${versionCol} = ${this.p(freshParams.length)}`;
+                whereSql = whereSql ? `${whereSql} AND ${versionCheck}` : ` WHERE ${versionCheck}`;
+            }
             this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
             return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}${this.dialect.buildReturningClause('*')}`;
-        });
-        // On cache hit, validate predicate
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('update', '', args.allowFullTableScan);
+        };
+        let sql;
+        let preparedName;
+        if (ck) {
+            const entry = this.acquireSql(ck, buildSql);
+            sql = entry.sql;
+            preparedName = entry.name;
+            if (whereFp === '') {
+                this.assertMutationHasPredicate('update', '', args.allowFullTableScan);
+            }
         }
-        // Collect params: SET first, then WHERE (same order as fresh build)
+        else {
+            sql = buildSql();
+        }
+        // Collect params: SET first, then WHERE, then version check (same order as fresh build)
         this.collectSetParams(dataObj, params);
         this.collectWhereParams(whereObj, params);
+        if (lock) {
+            params.push(lock.expected);
+        }
         return {
-            sql: entry.sql,
+            sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
                 if (!row) {
+                    if (lock) {
+                        throw new OptimisticLockError({
+                            table: this.table,
+                            versionField: lock.field,
+                            expectedVersion: lock.expected,
+                        });
+                    }
                     throw new NotFoundError({
                         table: this.table,
                         where: args.where,
@@ -848,7 +913,75 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.update`,
-            preparedName: entry.name,
+            preparedName,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Nested write helpers (shared by create + update)
+    // -------------------------------------------------------------------------
+    async nestedCreate(args) {
+        const data = args.data;
+        if (this.txScoped) {
+            const ctx = this.buildNestedCtx();
+            return executeNestedCreate(ctx, this.table, data);
+        }
+        return this.runInImplicitTx(async (ctx) => {
+            const result = await executeNestedCreate(ctx, this.table, data);
+            return result;
+        });
+    }
+    async nestedUpdate(args) {
+        const data = args.data;
+        const where = args.where;
+        if (this.txScoped) {
+            const ctx = this.buildNestedCtx();
+            return executeNestedUpdate(ctx, this.table, where, data);
+        }
+        return this.runInImplicitTx(async (ctx) => {
+            const result = await executeNestedUpdate(ctx, this.table, where, data);
+            return result;
+        });
+    }
+    async runInImplicitTx(fn) {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            const { TransactionClient } = await import('../client.js');
+            // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
+            // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
+            const ctx = { schema: this.schema, tx: tx };
+            const result = await fn(ctx);
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                // Best-effort rollback — connection may have died.
+            }
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    buildNestedCtx() {
+        const pool = this.pool;
+        const schema = this.schema;
+        const middlewares = this.middlewares;
+        const opts = { ...this.options, _txScoped: true };
+        return {
+            schema,
+            tx: this.makeTxProxy(pool, schema, middlewares, opts),
+        };
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: bridges MiddlewareFn[] ↔ Middleware[] and QI ↔ NestedWriteContext type gap
+    makeTxProxy(pool, schema, middlewares, opts) {
+        return {
+            table: (name) => new QueryInterface(pool, name, schema, middlewares, opts),
         };
     }
     // -------------------------------------------------------------------------
@@ -1538,6 +1671,12 @@ export class QueryInterface {
                 parts.push(`${key}:arr(${this.fingerprintArrayFilter(value)})`);
                 continue;
             }
+            // Text search filter
+            if (typeof value === 'object' && !Array.isArray(value) && isTextSearchFilter(value)) {
+                const cfg = value.config ?? 'english';
+                parts.push(`${key}:fts(${cfg})`);
+                continue;
+            }
             // Plain equality
             parts.push(`${key}:eq`);
         }
@@ -1653,6 +1792,11 @@ export class QueryInterface {
                     continue;
                 }
             }
+            // Text search filter
+            if (typeof value === 'object' && !Array.isArray(value) && isTextSearchFilter(value)) {
+                params.push(value.search);
+                continue;
+            }
             // Operator objects
             if (isWhereOperator(value)) {
                 this.collectOperatorParams(value, params);
@@ -2027,6 +2171,12 @@ export class QueryInterface {
                         `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
                 }
             }
+            // Handle full-text search filter
+            if (typeof value === 'object' && !Array.isArray(value) && isTextSearchFilter(value)) {
+                const tsClause = this.buildTextSearchClause(column, value, params);
+                andClauses.push(tsClause);
+                continue;
+            }
             // Handle operator objects
             if (isWhereOperator(value)) {
                 const opClauses = this.buildOperatorClauses(column, value, params);
@@ -2669,6 +2819,18 @@ export class QueryInterface {
         }
         return clauses;
     }
+    /**
+     * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
+     * The config name is validated to prevent injection (only alphanumeric + underscore).
+     */
+    buildTextSearchClause(column, filter, params) {
+        const config = filter.config ?? 'english';
+        if (!validateTextSearchConfig(config)) {
+            throw new ValidationError(`[turbine] Invalid text search config "${config}": only alphanumeric characters and underscores are allowed.`);
+        }
+        params.push(filter.search);
+        return `to_tsvector('${config}', ${column}) @@ to_tsquery('${config}', ${this.p(params.length)})`;
+    }
     /**
      * Get the Postgres array type for a column (used by UNNEST in createMany).
      * Uses pre-computed Map for O(1) lookup instead of linear scan.

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, JsonFilter, OrderDirection, RelationDescriptor, RelationFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, JsonFilter, NestedCreateOp, NestedUpdateOp, OmitResult, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/types.d.ts

@@ -26,8 +26,9 @@ export interface WhereOperator<V = unknown> {
  * - An operator object ({ gt: 5, lte: 10 })
  * - A JSONB filter object ({ contains, equals, path, hasKey })
  * - An array filter object ({ has, hasEvery, hasSome, isEmpty })
+ * - A text search filter object ({ search, config? })
  */
-export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | null;
+export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | null;
 /**
  * Where clause type: each field can be a plain value, null, or operator object.
  * Special keys: OR for disjunctive conditions.
@@ -162,18 +163,40 @@ export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T :
         with?: infer NestedW;
     } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
 } : T;
-export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
+/** Extract keys from a boolean record where the value is `true`. */
+type TrueKeys<S extends Record<string, boolean>> = {
+    [K in keyof S]: S[K] extends true ? K : never;
+}[keyof S];
+/** Pick only the fields from T that are selected (value = true) in S. */
+export type SelectResult<T, S extends Record<string, boolean> | undefined> = S extends Record<string, boolean> ? Pick<T, Extract<keyof T, TrueKeys<S>>> : T;
+/** Omit the fields from T that are marked (value = true) in O. */
+export type OmitResult<T, O extends Record<string, boolean> | undefined> = O extends Record<string, boolean> ? Omit<T, Extract<keyof T, TrueKeys<O>>> : T;
+/**
+ * Apply select or omit field narrowing to a base type. Select takes priority —
+ * when both are provided, only select is applied (matching runtime behavior).
+ */
+export type FieldResult<T, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends Record<string, boolean> ? SelectResult<T, S> : OmitResult<T, O>;
+/**
+ * Compute the full query result type: apply field narrowing to the base entity,
+ * then add relation additions from the `with` clause. Relations are unaffected
+ * by select/omit (they are separate JSON subqueries at the SQL level).
+ *
+ * Short-circuits to plain WithResult when neither select nor omit is provided,
+ * preserving exact type equality with the pre-narrowing era.
+ */
+export type QueryResult<T, R extends object, W, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends undefined ? O extends undefined ? WithResult<T, R, W> : O extends Record<string, boolean> ? Omit<WithResult<T, R, W>, Extract<keyof T, TrueKeys<O>>> : WithResult<T, R, W> : S extends Record<string, boolean> ? Pick<WithResult<T, R, W>, Extract<keyof T, TrueKeys<S>> | Exclude<keyof WithResult<T, R, W>, keyof T>> : WithResult<T, R, W>;
+export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where: WhereClause<T>;
-    select?: Record<string, boolean>;
-    omit?: Record<string, boolean>;
+    select?: S;
+    omit?: O;
     with?: W;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
-export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
+export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where?: WhereClause<T>;
-    select?: Record<string, boolean>;
-    omit?: Record<string, boolean>;
+    select?: S;
+    omit?: O;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
     offset?: number;
@@ -187,7 +210,7 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
-export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> extends FindManyArgs<T, R, W> {
+export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
      * Number of rows to fetch per internal FETCH batch (default: 1000).
      *
@@ -256,6 +279,27 @@ export interface UpdateArgs<T> {
      * when an unconditional mutation is the intended behaviour.
      */
     allowFullTableScan?: boolean;
+    /**
+     * Optimistic locking — prevents lost updates in concurrent scenarios.
+     * Specify the version field and its expected value. The update adds a
+     * WHERE check on the version and auto-increments it. If the row was
+     * modified by another transaction, throws `OptimisticLockError`.
+     *
+     * @example
+     * ```ts
+     * await db.posts.update({
+     *   where: { id: 1 },
+     *   data: { title: 'new title' },
+     *   optimisticLock: { field: 'version', expected: 3 },
+     * });
+     * // Generates: UPDATE posts SET title=$1, version=version+1
+     * //            WHERE id=$2 AND version=$3 RETURNING *
+     * ```
+     */
+    optimisticLock?: {
+        field: keyof T & string;
+        expected: number;
+    };
 }
 export interface UpdateManyArgs<T> {
     where: WhereClause<T>;
@@ -286,6 +330,23 @@ export interface UpsertArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+export interface ConnectOrCreateOp<T> {
+    where: Partial<T>;
+    create: Partial<T>;
+}
+export interface NestedCreateOp<T> {
+    create?: Partial<T> | Partial<T>[];
+    connect?: Partial<T> | Partial<T>[];
+    connectOrCreate?: ConnectOrCreateOp<T> | ConnectOrCreateOp<T>[];
+}
+export interface NestedUpdateOp<T> {
+    create?: Partial<T> | Partial<T>[];
+    connect?: Partial<T> | Partial<T>[];
+    connectOrCreate?: ConnectOrCreateOp<T> | ConnectOrCreateOp<T>[];
+    disconnect?: Partial<T> | Partial<T>[];
+    set?: Partial<T>[];
+    delete?: Partial<T> | Partial<T>[];
+}
 export interface CountArgs<T> {
     where?: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -361,5 +422,12 @@ export interface ArrayFilter {
     /** Check if array is empty: array_length(column, 1) IS NULL */
     isEmpty?: boolean;
 }
+/** Full-text search filter using PostgreSQL to_tsvector / to_tsquery */
+export interface TextSearchFilter {
+    /** The search query string passed to to_tsquery */
+    search: string;
+    /** PostgreSQL text search configuration name (defaults to 'english') */
+    config?: string;
+}
 export {};
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. 1 dependency, ~110KB",
   "type": "module",
   "exports": {
@@ -49,7 +49,7 @@
     "status": "tsx src/cli/index.ts status",
     "examples": "tsx examples/examples.ts",
     "test": "tsx --test src/test/*.test.ts",
-    "test:unit": "tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/dialect.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts src/test/cockroachdb-adapter.test.ts src/test/yugabytedb-adapter.test.ts src/test/pg-compat.test.ts src/test/relation-filter-validation.test.ts src/test/client-coverage.test.ts src/test/schema-diff.test.ts src/test/composite-fk.test.ts",
+    "test:unit": "tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/dialect.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts src/test/cockroachdb-adapter.test.ts src/test/yugabytedb-adapter.test.ts src/test/pg-compat.test.ts src/test/relation-filter-validation.test.ts src/test/client-coverage.test.ts src/test/schema-diff.test.ts src/test/composite-fk.test.ts src/test/retry.test.ts src/test/text-search.test.ts src/test/optimistic-lock.test.ts src/test/sql-safety-property.test.ts",
     "test:coverage": "c8 tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/dialect.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",