turbine-orm 0.14.0 → 0.16.0

package/dist/cjs/observe.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * turbine-orm — Observability module
+ *
+ * Buffers query metrics in memory (keyed by model:action per minute bucket),
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
+ * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
+ * so metrics writes never contend with the application pool.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObserveEngine = void 0;
+exports.floorToMinute = floorToMinute;
+exports.percentile = percentile;
+const pg_1 = __importDefault(require("pg"));
+function floorToMinute(date) {
+    const d = new Date(date);
+    d.setSeconds(0, 0);
+    return d;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(p * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+// ---------------------------------------------------------------------------
+// Schema DDL
+// ---------------------------------------------------------------------------
+const SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS _turbine_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  bucket      TIMESTAMPTZ NOT NULL,
+  model       TEXT NOT NULL,
+  action      TEXT NOT NULL,
+  count       INTEGER NOT NULL DEFAULT 0,
+  avg_ms      REAL NOT NULL DEFAULT 0,
+  p50_ms      REAL NOT NULL DEFAULT 0,
+  p95_ms      REAL NOT NULL DEFAULT 0,
+  p99_ms      REAL NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(bucket, model, action)
+);
+CREATE INDEX IF NOT EXISTS idx_turbine_metrics_bucket ON _turbine_metrics(bucket);
+`;
+const UPSERT_SQL = `
+INSERT INTO _turbine_metrics (bucket, model, action, count, avg_ms, p50_ms, p95_ms, p99_ms, error_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+ON CONFLICT (bucket, model, action) DO UPDATE SET
+  count = _turbine_metrics.count + EXCLUDED.count,
+  avg_ms = (_turbine_metrics.avg_ms * _turbine_metrics.count + EXCLUDED.avg_ms * EXCLUDED.count)
+           / (_turbine_metrics.count + EXCLUDED.count),
+  p50_ms = EXCLUDED.p50_ms,
+  p95_ms = EXCLUDED.p95_ms,
+  p99_ms = EXCLUDED.p99_ms,
+  error_count = _turbine_metrics.error_count + EXCLUDED.error_count
+`;
+const RETENTION_SQL = `DELETE FROM _turbine_metrics WHERE bucket < NOW() - INTERVAL '1 day' * $1`;
+// ---------------------------------------------------------------------------
+// Observe engine
+// ---------------------------------------------------------------------------
+class ObserveEngine {
+    pool;
+    buffer = new Map();
+    currentBucket;
+    flushIntervalMs;
+    retentionDays;
+    timer;
+    listener;
+    stopped = false;
+    constructor(config) {
+        this.pool = new pg_1.default.Pool({ connectionString: config.connectionString, max: 1 });
+        this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
+        this.retentionDays = config.retentionDays ?? 30;
+        this.currentBucket = floorToMinute(new Date());
+        this.listener = (event) => {
+            if (this.stopped)
+                return;
+            const nowBucket = floorToMinute(new Date());
+            if (nowBucket.getTime() !== this.currentBucket.getTime()) {
+                this.currentBucket = nowBucket;
+            }
+            const key = `${event.model}:${event.action}`;
+            let entry = this.buffer.get(key);
+            if (!entry) {
+                entry = { durations: [], errors: 0 };
+                this.buffer.set(key, entry);
+            }
+            entry.durations.push(event.duration);
+            if (event.error)
+                entry.errors++;
+        };
+    }
+    getListener() {
+        return this.listener;
+    }
+    async init() {
+        await this.pool.query(SCHEMA_DDL);
+        this.timer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        // Unref so it doesn't keep the process alive
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    async flush() {
+        if (this.buffer.size === 0)
+            return;
+        const bucket = this.currentBucket;
+        const entries = new Map(this.buffer);
+        this.buffer.clear();
+        for (const [key, entry] of entries) {
+            const [model, action] = key.split(':');
+            const sorted = entry.durations.slice().sort((a, b) => a - b);
+            const count = sorted.length;
+            const avg = sorted.reduce((s, v) => s + v, 0) / count;
+            const p50 = percentile(sorted, 0.5);
+            const p95 = percentile(sorted, 0.95);
+            const p99 = percentile(sorted, 0.99);
+            try {
+                await this.pool.query(UPSERT_SQL, [bucket, model, action, count, avg, p50, p95, p99, entry.errors]);
+            }
+            catch {
+                // Fire-and-forget — never throw from flush
+            }
+        }
+        try {
+            await this.pool.query(RETENTION_SQL, [this.retentionDays]);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+        await this.pool.end();
+    }
+}
+exports.ObserveEngine = ObserveEngine;

package/dist/cjs/query/builder.js

@@ -11,10 +11,44 @@
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata — nothing is hardcoded.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = void 0;
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
+const nested_write_js_1 = require("../nested-write.js");
 const schema_js_1 = require("../schema.js");
 const utils_js_1 = require("./utils.js");
 // ---------------------------------------------------------------------------
@@ -100,6 +134,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
 class QueryInterface {
     pool;
@@ -131,6 +187,12 @@ 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;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    currentAction = 'raw';
     constructor(pool, table, schema, middlewares, options) {
         this.pool = pool;
         this.table = table;
@@ -149,6 +211,8 @@ class QueryInterface {
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         this.sqlCacheEnabled = options?.sqlCache !== false;
         this.dialect = options?.dialect ?? dialect_js_1.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();
@@ -210,12 +274,25 @@ class QueryInterface {
     resetUnlimitedWarnings() {
         this.warnedTables.clear();
     }
+    emitQueryEvent(sql, params, duration, action, rows, error) {
+        const onQuery = this.options?._onQuery;
+        if (!onQuery)
+            return;
+        try {
+            onQuery({ sql, params, duration, model: this.table, action, rows, timestamp: new Date(), error });
+        }
+        catch {
+            // Listener errors must never crash a query
+        }
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
     async queryWithTimeout(sql, params, timeout, preparedName) {
+        const start = performance.now();
+        const action = this.currentAction;
         // Build the query argument — use object form with `name` for prepared
         // statements, or the plain (text, values) form otherwise.
         const usePrepared = preparedName && this.preparedStatementsEnabled;
@@ -224,10 +301,14 @@ class QueryInterface {
             : this.pool.query(sql, params);
         if (!timeout) {
             try {
-                return await exec;
+                const result = await exec;
+                this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+                return result;
             }
             catch (err) {
-                throw (0, errors_js_1.wrapPgError)(err);
+                const wrapped = (0, errors_js_1.wrapPgError)(err);
+                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+                throw wrapped;
             }
         }
         let timer;
@@ -235,10 +316,14 @@ class QueryInterface {
             timer = setTimeout(() => reject(new errors_js_1.TimeoutError(timeout)), timeout);
         });
         try {
-            return await Promise.race([exec, timeoutPromise]);
+            const result = await Promise.race([exec, timeoutPromise]);
+            this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+            return result;
         }
         catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
+            const wrapped = (0, errors_js_1.wrapPgError)(err);
+            this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+            throw wrapped;
         }
         finally {
             clearTimeout(timer);
@@ -254,6 +339,7 @@ class QueryInterface {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     async executeWithMiddleware(action, args, executor) {
+        this.currentAction = action;
         if (this.middlewares.length === 0) {
             return executor();
         }
@@ -273,7 +359,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUnique
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
             const deferred = this.buildFindUnique(args);
@@ -377,7 +462,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findMany
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findMany(args) {
         this.maybeWarnUnlimited(args);
         // Dev-only: warn on deeply nested with clauses
@@ -579,7 +663,6 @@ class QueryInterface {
      * }
      * ```
      */
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async *findManyStream(args) {
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         const hasRelations = !!args?.with;
@@ -588,6 +671,7 @@ class QueryInterface {
             ...args,
             limit: batchSize + 1,
         });
+        this.currentAction = 'findManyStream';
         const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
         if (speculativeResult.rows.length <= batchSize) {
             // Small drain — yield all rows and return, no cursor needed
@@ -636,7 +720,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirst — like findMany but returns a single row or null
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             const deferred = this.buildFindFirst(args);
@@ -662,7 +745,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirstOrThrow — like findFirst but throws if no record found
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
@@ -693,7 +775,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUniqueOrThrow — like findUnique but throws if no record found
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
@@ -726,6 +807,9 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     async create(args) {
         return this.executeWithMiddleware('create', args, async () => {
+            if ((0, nested_write_js_1.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);
@@ -808,6 +892,9 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     async update(args) {
         return this.executeWithMiddleware('update', args, async () => {
+            if ((0, nested_write_js_1.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);
@@ -816,32 +903,62 @@ 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);
+            }
+        }
+        else {
+            sql = buildSql();
         }
-        // Collect params: SET first, then WHERE (same order as fresh build)
+        // 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 errors_js_1.OptimisticLockError({
+                            table: this.table,
+                            versionField: lock.field,
+                            expectedVersion: lock.expected,
+                        });
+                    }
                     throw new errors_js_1.NotFoundError({
                         table: this.table,
                         where: args.where,
@@ -851,7 +968,75 @@ 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 (0, nested_write_js_1.executeNestedCreate)(ctx, this.table, data);
+        }
+        return this.runInImplicitTx(async (ctx) => {
+            const result = await (0, nested_write_js_1.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 (0, nested_write_js_1.executeNestedUpdate)(ctx, this.table, where, data);
+        }
+        return this.runInImplicitTx(async (ctx) => {
+            const result = await (0, nested_write_js_1.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 Promise.resolve().then(() => __importStar(require('../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),
         };
     }
     // -------------------------------------------------------------------------
@@ -1503,7 +1688,11 @@ class QueryInterface {
             const relDef = this.tableMeta.relations[key];
             if (relDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     const relParts = [];
                     if (filterObj.some !== undefined)
                         relParts.push(`some(${this.fingerprintRelFilter(relDef.to, filterObj.some)})`);
@@ -1511,6 +1700,10 @@ class QueryInterface {
                         relParts.push(`every(${this.fingerprintRelFilter(relDef.to, filterObj.every)})`);
                     if (filterObj.none !== undefined)
                         relParts.push(`none(${this.fingerprintRelFilter(relDef.to, filterObj.none)})`);
+                    if (filterObj.is !== undefined)
+                        relParts.push(`is(${this.fingerprintRelFilter(relDef.to, filterObj.is)})`);
+                    if (filterObj.isNot !== undefined)
+                        relParts.push(`isNot(${this.fingerprintRelFilter(relDef.to, filterObj.isNot)})`);
                     parts.push(`${key}:{${relParts.join(',')}}`);
                     continue;
                 }
@@ -1541,6 +1734,12 @@ 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`);
         }
@@ -1626,13 +1825,21 @@ class QueryInterface {
             const relationDef = this.tableMeta.relations[key];
             if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     if (filterObj.some !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.some, params);
                     if (filterObj.none !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.none, params);
                     if (filterObj.every !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.every, params);
+                    if (filterObj.is !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.is, params);
+                    if (filterObj.isNot !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.isNot, params);
                     continue;
                 }
             }
@@ -1656,6 +1863,11 @@ 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);
@@ -1980,7 +2192,11 @@ class QueryInterface {
             if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
                 // Check if this is a relation filter (has some/every/none keys)
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     const relClause = this.buildRelationFilter(key, relationDef, filterObj, params);
                     if (relClause)
                         andClauses.push(relClause);
@@ -2030,6 +2246,12 @@ 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);
@@ -2091,6 +2313,20 @@ class QueryInterface {
                 // "every" with empty filter = true (all match trivially)
             }
         }
+        // "is": EXISTS — for to-one relations (same SQL as "some")
+        if (filterObj.is !== undefined) {
+            const subWhere = filterObj.is;
+            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
+            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
+            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+        }
+        // "isNot": NOT EXISTS — for to-one relations (same SQL as "none")
+        if (filterObj.isNot !== undefined) {
+            const subWhere = filterObj.isNot;
+            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
+            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+        }
         return clauses.length > 0 ? clauses.join(' AND ') : null;
     }
     /**
@@ -2672,6 +2908,18 @@ 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 errors_js_1.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/cli/index.d.ts

@@ -13,6 +13,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine studio                — Launch local read-only web UI
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate