turbine-orm 0.15.0 → 0.16.0

package/dist/nested-write.js

@@ -3,8 +3,8 @@
  *
  * 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).
+ * connectOrCreate, disconnect, set, delete, update, and upsert 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
@@ -15,7 +15,7 @@ import { CircularRelationError, RelationError, ValidationError } from './errors.
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
-const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete']);
+const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete', 'update', 'upsert']);
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -93,7 +93,7 @@ function validateOps(relationName, ops, isUpdate) {
     for (const opName of Object.keys(ops)) {
         if (!CREATE_ONLY_OPS.has(opName) && !UPDATE_ONLY_OPS.has(opName)) {
             throw new ValidationError(`[turbine] Unknown nested write operation "${opName}" on relation "${relationName}". ` +
-                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete' : ''}.`);
+                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete, update, upsert' : ''}.`);
         }
         if (!isUpdate && UPDATE_ONLY_OPS.has(opName)) {
             throw new ValidationError(`[turbine] Operation "${opName}" on relation "${relationName}" is only valid inside update(), not create().`);
@@ -216,9 +216,25 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             if (ops.delete !== undefined) {
                 await processDelete(ctx, rel, ops.delete);
             }
+            // update
+            if (ops.update !== undefined) {
+                await processNestedUpdate(ctx, rel, ops.update);
+            }
+            // upsert
+            if (ops.upsert !== undefined) {
+                await processNestedUpsert(ctx, rel, ops.upsert, parentRow);
+            }
         }
         else if (rel.type === 'belongsTo') {
             await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
+            // update (belongsTo — derive where from parent FK)
+            if (ops.update !== undefined) {
+                await processBelongsToUpdate(ctx, rel, ops.update, parentRow, tableName);
+            }
+            // upsert (belongsTo)
+            if (ops.upsert !== undefined) {
+                await processBelongsToUpsert(ctx, rel, ops.upsert, parentRow, tableName);
+            }
             if (ops.disconnect !== undefined) {
                 // For belongsTo disconnect, null out the FK on the parent
                 const fks = normalizeKeyColumns(rel.foreignKey);
@@ -452,6 +468,80 @@ async function processSet(ctx, rel, setItems, parentRow) {
         await ctx.tx.table(rel.to).update({ where: target, data: updateData });
     }
 }
+// ---------------------------------------------------------------------------
+// update / upsert operations (update-context only)
+// ---------------------------------------------------------------------------
+async function processNestedUpdate(ctx, rel, updateArg) {
+    const items = toArray(updateArg);
+    for (const item of items) {
+        if (!item.where || !item.data) {
+            throw new ValidationError(`[turbine] Nested update on "${rel.name}" requires both "where" and "data" fields.`);
+        }
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.data });
+    }
+}
+async function processNestedUpsert(ctx, rel, upsertArg, parentRow) {
+    const items = toArray(upsertArg);
+    for (const item of items) {
+        if (!item.where || !item.create || !item.update) {
+            throw new ValidationError(`[turbine] Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
+        }
+        const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+        if (existing) {
+            await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        }
+        else {
+            const injected = injectForeignKey(item.create, rel, parentRow, ctx.schema);
+            await ctx.tx.table(rel.to).create({ data: injected });
+        }
+    }
+}
+async function processBelongsToUpdate(ctx, rel, updateArg, parentRow, parentTable) {
+    const item = updateArg;
+    if (!item.data) {
+        throw new ValidationError(`[turbine] Nested update on belongsTo "${rel.name}" requires a "data" field.`);
+    }
+    // Derive where from parent's FK values
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        where[refField] = parentRow[fkField];
+    }
+    await ctx.tx.table(rel.to).update({ where, data: item.data });
+}
+async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTable) {
+    const item = upsertArg;
+    if (!item.where || !item.create || !item.update) {
+        throw new ValidationError(`[turbine] Nested upsert on belongsTo "${rel.name}" requires "where", "create", and "update" fields.`);
+    }
+    const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+    if (existing) {
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+    }
+    else {
+        // Create the related row, then update parent's FK to point at it
+        const createdRow = (await ctx.tx.table(rel.to).create({ data: item.create }));
+        const fks = normalizeKeyColumns(rel.foreignKey);
+        const refs = normalizeKeyColumns(rel.referenceKey);
+        const parentMeta = ctx.schema.tables[parentTable];
+        const relatedTable = ctx.schema.tables[rel.to];
+        const updateData = {};
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            updateData[fkField] = createdRow[refField];
+        }
+        await ctx.tx.table(parentTable).update({
+            where: pkWhere(parentMeta, parentRow),
+            data: updateData,
+        });
+    }
+}
 async function processDelete(ctx, rel, deleteArg) {
     const items = toArray(deleteArg);
     for (const target of items) {

package/dist/observe.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import type { QueryEventListener } from './query/index.js';
+export interface ObserveConfig {
+    connectionString: string;
+    flushIntervalMs?: number;
+    retentionDays?: number;
+}
+export interface ObserveHandle {
+    stop(): Promise<void>;
+}
+declare function floorToMinute(date: Date): Date;
+declare function percentile(sorted: number[], p: number): number;
+export declare class ObserveEngine {
+    private readonly pool;
+    private readonly buffer;
+    private currentBucket;
+    private readonly flushIntervalMs;
+    private readonly retentionDays;
+    private timer;
+    private readonly listener;
+    private stopped;
+    constructor(config: ObserveConfig);
+    getListener(): QueryEventListener;
+    init(): Promise<void>;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+}
+export { floorToMinute, percentile };
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.js

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+import pg from '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
+// ---------------------------------------------------------------------------
+export class ObserveEngine {
+    pool;
+    buffer = new Map();
+    currentBucket;
+    flushIntervalMs;
+    retentionDays;
+    timer;
+    listener;
+    stopped = false;
+    constructor(config) {
+        this.pool = new pg.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();
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported helpers for testing
+// ---------------------------------------------------------------------------
+export { floorToMinute, percentile };
+//# sourceMappingURL=observe.js.map

package/dist/query/builder.d.ts

@@ -36,6 +36,18 @@ export type MiddlewareFn = (params: {
     action: string;
     args: Record<string, unknown>;
 }) => Promise<unknown>) => Promise<unknown>;
+/** Emitted after every query execution (success or failure). */
+export interface QueryEvent {
+    sql: string;
+    params: unknown[];
+    duration: number;
+    model: string;
+    action: string;
+    rows: number;
+    timestamp: Date;
+    error?: Error;
+}
+export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
@@ -69,6 +81,8 @@ export interface QueryInterfaceOptions {
     dialect?: Dialect;
     /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
     _txScoped?: boolean;
+    /** @internal Callback from TurbineClient for query event emission. */
+    _onQuery?: (event: QueryEvent) => void;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -104,6 +118,8 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly txScoped;
     /** Original options reference — forwarded to child QIs in nested writes. */
     private readonly options?;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    private currentAction;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Quote an identifier through the active SQL dialect. */
     private q;
@@ -133,6 +149,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * exactly once per table without bleeding state between assertions.
      */
     resetUnlimitedWarnings(): void;
+    private emitQueryEvent;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.

package/dist/query/builder.js

@@ -155,6 +155,8 @@ export class QueryInterface {
     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;
@@ -236,12 +238,25 @@ export 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;
@@ -250,10 +265,14 @@ export 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 wrapPgError(err);
+                const wrapped = wrapPgError(err);
+                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+                throw wrapped;
             }
         }
         let timer;
@@ -261,10 +280,14 @@ export class QueryInterface {
             timer = setTimeout(() => reject(new 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 wrapPgError(err);
+            const wrapped = wrapPgError(err);
+            this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+            throw wrapped;
         }
         finally {
             clearTimeout(timer);
@@ -280,6 +303,7 @@ export 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();
         }
@@ -299,7 +323,6 @@ export 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);
@@ -403,7 +426,6 @@ export 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
@@ -605,7 +627,6 @@ export 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;
@@ -614,6 +635,7 @@ export 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
@@ -662,7 +684,6 @@ export 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);
@@ -688,7 +709,6 @@ export 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);
@@ -719,7 +739,6 @@ export 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);
@@ -1633,7 +1652,11 @@ export 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)})`);
@@ -1641,6 +1664,10 @@ export 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;
                 }
@@ -1762,13 +1789,21 @@ export 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;
                 }
             }
@@ -2121,7 +2156,11 @@ export 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);
@@ -2238,6 +2277,20 @@ export 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;
     }
     /**

package/dist/query/index.d.ts

@@ -10,6 +10,6 @@ export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, C
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
-export type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './builder.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions } from './builder.js';
 export { QueryInterface } from './builder.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.15.0",
+  "version": "0.16.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 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: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 src/test/nested-write.test.ts src/test/nested-write-update-upsert.test.ts src/test/cursor-pagination.test.ts src/test/client-branches.test.ts src/test/is-isNot-filter.test.ts src/test/event-emitter.test.ts src/test/observe.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/",