turbine-orm 0.16.0 → 0.19.0

package/dist/cjs/cli/studio.js

@@ -75,7 +75,11 @@ async function startStudio(options) {
     const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
     const stateDir = (0, node_path_1.resolve)(options.stateDir ?? '.turbine');
     const statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
-        sql: `SET LOCAL statement_timeout = $1`,
+        // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
+        // syntax error). `set_config(name, value, is_local=true)` is the
+        // parameterizable, transaction-local equivalent and works on every
+        // Postgres-compatible engine.
+        sql: `SELECT set_config('statement_timeout', $1, true)`,
         params: ['30s'],
     };
     const rateLimiter = new Map();
@@ -151,6 +155,13 @@ async function handleRequest(req, res, ctx) {
         sendHtml(res, 200, studio_ui_generated_js_1.STUDIO_HTML);
         return;
     }
+    // Favicon — answered before the auth gate so the browser's automatic request
+    // doesn't 401/404 on every load. No icon body needed (204).
+    if (pathname === '/favicon.ico') {
+        res.writeHead(204, { 'Content-Length': '0' });
+        res.end();
+        return;
+    }
     // API routes — all require auth.
     if (!isAuthorized(req, ctx.authToken)) {
         sendJson(res, 401, { error: 'unauthorized — use the URL printed in the terminal' });
@@ -171,9 +182,6 @@ async function handleRequest(req, res, ctx) {
         const rawName = decodeURIComponent(pathname.slice('/api/tables/'.length));
         return apiTableRows(res, ctx, rawName, url.searchParams);
     }
-    if (pathname === '/api/query' && req.method === 'POST') {
-        return apiQuery(req, res, ctx);
-    }
     if (pathname === '/api/builder' && req.method === 'POST') {
         return apiBuilder(req, res, ctx);
     }
@@ -233,6 +241,15 @@ function constantTimeEqual(a, b) {
     }
     return result === 0;
 }
+/**
+ * Build a helpful "unknown table" error that lists the available tables so the
+ * caller can spot a typo or schema mismatch immediately.
+ */
+function unknownTableMessage(name, ctx) {
+    const available = Object.keys(ctx.metadata.tables);
+    const list = available.length ? available.join(', ') : '(none)';
+    return `[turbine] Unknown table "${name}" in schema "${ctx.options.schema}". Available: ${list}`;
+}
 // ---------------------------------------------------------------------------
 // API: /api/schema
 // ---------------------------------------------------------------------------
@@ -265,7 +282,9 @@ async function apiSchema(res, ctx) {
      WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
     const counts = new Map();
     for (const row of countsResult.rows) {
-        counts.set(row.relname, Number(row.reltuples));
+        // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
+        // sidebar never shows a negative estimate.
+        counts.set(row.relname, Math.max(0, Number(row.reltuples)));
     }
     sendJson(res, 200, {
         schema: ctx.options.schema,
@@ -279,7 +298,7 @@ async function apiSchema(res, ctx) {
 async function apiTableRows(res, ctx, rawTableName, params) {
     const table = ctx.metadata.tables[rawTableName];
     if (!table) {
-        sendJson(res, 404, { error: `unknown table: ${rawTableName}` });
+        sendJson(res, 404, { error: unknownTableMessage(rawTableName, ctx) });
         return;
     }
     const limit = clampInt(params.get('limit'), 50, 1, 500);
@@ -374,54 +393,6 @@ function escapeLikePattern(s) {
     return s.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
 }
 // ---------------------------------------------------------------------------
-// API: /api/query — read-only SELECT/WITH runner
-// ---------------------------------------------------------------------------
-async function apiQuery(req, res, ctx) {
-    const body = await readJsonBody(req);
-    const rawSql = typeof body?.sql === 'string' ? body.sql.trim() : '';
-    if (!rawSql) {
-        sendJson(res, 400, { error: 'missing sql' });
-        return;
-    }
-    if (rawSql.length > 10_000) {
-        sendJson(res, 400, { error: 'query too long — maximum 10,000 characters allowed' });
-        return;
-    }
-    if (!isReadOnlyStatement(rawSql)) {
-        sendJson(res, 400, {
-            error: 'only SELECT / WITH statements are allowed in Studio — use the CLI for writes',
-        });
-        return;
-    }
-    const client = await ctx.pool.connect();
-    try {
-        await client.query('BEGIN READ ONLY');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-        const started = Date.now();
-        const result = await client.query(rawSql);
-        const elapsedMs = Date.now() - started;
-        await client.query('COMMIT');
-        sendJson(res, 200, {
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
-            rowCount: result.rowCount ?? result.rows.length,
-            elapsedMs,
-        });
-    }
-    catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
-        }
-        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
-    }
-    finally {
-        client.release();
-    }
-}
-// ---------------------------------------------------------------------------
 // API: /api/builder — Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
 async function apiBuilder(req, res, ctx) {
@@ -429,7 +400,7 @@ async function apiBuilder(req, res, ctx) {
     const tableName = typeof body?.table === 'string' ? body.table : '';
     const args = (body?.args ?? {});
     if (!tableName || !ctx.metadata.tables[tableName]) {
-        sendJson(res, 400, { error: `unknown table: ${tableName}` });
+        sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
     let deferred;
@@ -486,7 +457,9 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        return { version: 1, queries: parsed.queries };
+        // Drop any legacy raw-SQL entries — Studio is builder-only now.
+        const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        return { version: 1, queries };
     }
     catch {
         return { version: 1, queries: [] };
@@ -509,27 +482,17 @@ async function apiCreateSavedQuery(req, res, ctx) {
     const body = await readJsonBody(req);
     const table = typeof body?.table === 'string' ? body.table : '';
     const name = typeof body?.name === 'string' ? body.name.trim() : '';
-    const kind = body?.kind === 'builder' ? 'builder' : body?.kind === 'sql' ? 'sql' : null;
     if (!table || !ctx.metadata.tables[table]) {
-        sendJson(res, 400, { error: `unknown table: ${table}` });
+        sendJson(res, 400, { error: unknownTableMessage(table, ctx) });
         return;
     }
     if (!name) {
         sendJson(res, 400, { error: 'name is required' });
         return;
     }
-    if (!kind) {
-        sendJson(res, 400, { error: 'kind must be "sql" or "builder"' });
-        return;
-    }
-    const sql = kind === 'sql' && typeof body?.sql === 'string' ? body.sql : undefined;
-    const args = kind === 'builder' ? body?.args : undefined;
-    if (kind === 'sql' && !sql) {
-        sendJson(res, 400, { error: 'sql is required for kind=sql' });
-        return;
-    }
-    if (kind === 'sql' && sql && !isReadOnlyStatement(sql)) {
-        sendJson(res, 400, { error: 'saved sql must be SELECT/WITH only' });
+    // Studio only persists visual-builder queries (no raw SQL surface).
+    if (body?.kind !== 'builder') {
+        sendJson(res, 400, { error: 'kind must be "builder"' });
         return;
     }
     const data = loadSavedQueries(ctx);
@@ -537,9 +500,8 @@ async function apiCreateSavedQuery(req, res, ctx) {
         id: (0, node_crypto_1.randomUUID)(),
         table,
         name,
-        kind,
-        sql,
-        args,
+        kind: 'builder',
+        args: body?.args,
         createdAt: new Date().toISOString(),
     };
     data.queries.push(entry);

package/dist/cjs/client.js

@@ -33,6 +33,9 @@ const errors_js_1 = require("./errors.js");
 const observe_js_1 = require("./observe.js");
 const pipeline_js_1 = require("./pipeline.js");
 const index_js_1 = require("./query/index.js");
+const utils_js_1 = require("./query/utils.js");
+const realtime_js_1 = require("./realtime.js");
+const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const baseDelay = options?.baseDelay ?? 50;
@@ -64,6 +67,13 @@ const ISOLATION_LEVELS = {
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
 };
+/**
+ * Strict GUC (session variable) name: an optionally namespaced identifier such
+ * as `app.current_tenant` or `search_path`. Even though the name is passed as a
+ * bound parameter to `set_config`, a malformed name is a programmer error worth
+ * rejecting loudly before it reaches the database.
+ */
+const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 // ---------------------------------------------------------------------------
 // TransactionClient — provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
@@ -197,6 +207,8 @@ class TurbineClient {
     errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     ownsPool = true;
+    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    activeSubscriptions = new Set();
     constructor(config = {}, schema) {
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
@@ -468,6 +480,40 @@ class TurbineClient {
             throw (0, errors_js_1.wrapPgError)(err);
         }
     }
+    /**
+     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     *
+     * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
+     * (never string-concatenated), so it is injection-safe by construction. The
+     * difference is the caller-supplied row type and the chainable result: the
+     * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
+     * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
+     *
+     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * columns in SQL if you want camelCase keys.
+     *
+     * @example
+     * ```ts
+     * // rows
+     * const rows = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     *
+     * // single row or null
+     * const user = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE id = ${userId}
+     * `.one();
+     *
+     * // scalar
+     * const total = await db.sql<{ count: number }>`
+     *   SELECT COUNT(*)::int AS count FROM users
+     * `.scalar();
+     * ```
+     */
+    sql(strings, ...values) {
+        const { sql, params } = (0, typed_sql_js_1.buildTypedSql)(strings, values);
+        return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging);
+    }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
     // -------------------------------------------------------------------------
@@ -550,6 +596,21 @@ class TurbineClient {
                     beginSQL += ` ISOLATION LEVEL ${level}`;
             }
             await client.query(beginSQL);
+            // Apply transaction-local session context (RLS / multi-tenant GUCs).
+            // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
+            // user fn. Any error here propagates to the catch below and rolls back
+            // like any other transaction failure. We use set_config(name, value,
+            // is_local=true) — the parameterizable, transaction-scoped equivalent of
+            // SET LOCAL — so both name and value are BOUND params, never interpolated.
+            if (options?.sessionContext) {
+                for (const [name, value] of Object.entries(options.sessionContext)) {
+                    if (!GUC_NAME_REGEX.test(name)) {
+                        throw new errors_js_1.ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
+                            '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
+                    }
+                    await client.query('SELECT set_config($1, $2, true)', [name, String(value)]);
+                }
+            }
             // Create the transaction client with typed table accessors
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
             // Dynamically attach table accessors to tx
@@ -621,6 +682,94 @@ class TurbineClient {
             releaseOnce();
         }
     }
+    /**
+     * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
+     * runs `fn` inside a transaction with the given session GUCs applied via
+     * `set_config(..., is_local=true)`. Equivalent to
+     * `$transaction(fn, { sessionContext: context })`.
+     *
+     * @example
+     * ```ts
+     * const invoices = await db.$withSession(
+     *   { 'app.current_tenant': tenantId },
+     *   (tx) => tx.invoices.findMany(),
+     * );
+     * ```
+     */
+    async $withSession(context, fn) {
+        return this.$transaction(fn, { sessionContext: context });
+    }
+    // -------------------------------------------------------------------------
+    // LISTEN / NOTIFY — Postgres realtime pub/sub
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to a Postgres NOTIFY channel. The handler fires with each
+     * notification's payload string (the empty string when a payload-less
+     * NOTIFY is sent) for as long as the subscription is active.
+     *
+     * Each `$listen` checks out its OWN dedicated long-lived connection from the
+     * pool and runs `LISTEN "channel"` on it; `subscription.unsubscribe()`
+     * UNLISTENs, detaches the handler, and releases that connection. Active
+     * subscriptions are tracked and force-released on `disconnect()` so shutdown
+     * never hangs.
+     *
+     * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
+     * error), so it is validated against a strict identifier regex AND quoted via
+     * `quoteIdent` before interpolation — it is the only identifier this method
+     * places into SQL text.
+     *
+     * **Serverless caveat:** LISTEN needs a persistent connection that can push
+     * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
+     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * `$notify` works on every driver.
+     *
+     * @example
+     * ```ts
+     * const sub = await db.$listen('order_created', (payload) => {
+     *   const order = JSON.parse(payload);
+     *   console.log('new order', order.id);
+     * });
+     * // ...later
+     * await sub.unsubscribe();
+     * ```
+     */
+    async $listen(channel, handler) {
+        (0, realtime_js_1.validateChannel)(channel);
+        const quoted = (0, utils_js_1.quoteIdent)(channel);
+        if (this.logging) {
+            console.log(`[turbine] LISTEN ${quoted}`);
+        }
+        const sub = await (0, realtime_js_1.createSubscription)(this.pool, channel, quoted, handler, (closed) => {
+            this.activeSubscriptions.delete(closed);
+        });
+        this.activeSubscriptions.add(sub);
+        return sub;
+    }
+    /**
+     * Send a Postgres NOTIFY on `channel` with an optional payload string.
+     *
+     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * BOUND parameters (no quoting/injection concern). The channel is still
+     * validated against the identifier regex for parity with `$listen` and to
+     * catch typos loudly. Works on every driver, including serverless HTTP pools.
+     *
+     * @example
+     * ```ts
+     * await db.$notify('order_created', JSON.stringify({ id: 7 }));
+     * ```
+     */
+    async $notify(channel, payload) {
+        (0, realtime_js_1.validateChannel)(channel);
+        if (this.logging) {
+            console.log(`[turbine] NOTIFY ${channel}`);
+        }
+        try {
+            await this.pool.query('SELECT pg_notify($1, $2)', [channel, payload ?? '']);
+        }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
+    }
     // -------------------------------------------------------------------------
     // Retry — automatic retry for retryable errors (deadlock, serialization)
     // -------------------------------------------------------------------------
@@ -668,6 +817,21 @@ class TurbineClient {
      * method is a no-op — the caller is responsible for the pool's lifecycle.
      */
     async disconnect() {
+        // Tear down any live LISTEN subscriptions first. Each holds a dedicated
+        // pooled connection checked out; if we ended the pool (or returned for an
+        // external pool) without releasing them, pool.end() would wait forever for
+        // those connections to return. _forceRelease() detaches the handler and
+        // releases the client WITHOUT issuing UNLISTEN (pointless if we're ending
+        // the pool / the connection is going away anyway). This runs for both
+        // owned and external pools so subscriptions never leak.
+        if (this.activeSubscriptions.size > 0) {
+            // _forceRelease mutates activeSubscriptions via the onClosed callback,
+            // so iterate a snapshot.
+            for (const sub of [...this.activeSubscriptions]) {
+                sub._forceRelease();
+            }
+            this.activeSubscriptions.clear();
+        }
         if (!this.ownsPool) {
             if (this.logging) {
                 console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');

package/dist/cjs/errors.js

@@ -211,7 +211,13 @@ class UniqueConstraintError extends TurbineError {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             const columnsPart = columns && columns.length > 0 ? ` (${columns.join(', ')})` : '';
             message = `[turbine] Unique constraint violation${constraintPart}${columnsPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -233,7 +239,13 @@ class ForeignKeyError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Foreign key constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -254,7 +266,13 @@ class NotNullViolationError extends TurbineError {
         if (!message) {
             const columnPart = column ? ` on column "${column}"` : '';
             message = `[turbine] NOT NULL constraint violation${columnPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -342,7 +360,13 @@ class CheckConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Check constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -362,7 +386,13 @@ class ExclusionConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Exclusion constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }

package/dist/cjs/generate.js

@@ -156,7 +156,8 @@ function generateTypes(schema) {
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                // manyToMany is a collection too → 'many' cardinality (same as hasMany).
+                const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
                 const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
                 lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
@@ -165,7 +166,7 @@ function generateTypes(schema) {
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
+                if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
                     lines.push(`export interface ${typeName}With${(0, schema_js_1.snakeToPascal)(relName)} extends ${typeName} {`);
                     lines.push(`  ${relName}: ${targetType}[];`);
@@ -332,7 +333,17 @@ function generateMetadata(schema) {
             const refLiteral = Array.isArray(rel.referenceKey)
                 ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
                 : `'${escSQ(rel.referenceKey)}'`;
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
+            // manyToMany relations carry a `through` junction descriptor — emit it so
+            // the runtime query builder can JOIN through the junction table.
+            let throughLiteral = '';
+            if (rel.through) {
+                const keyLiteral = (k) => Array.isArray(k) ? `[${k.map((c) => `'${escSQ(c)}'`).join(', ')}]` : `'${escSQ(k)}'`;
+                throughLiteral =
+                    `, through: { table: '${escSQ(rel.through.table)}', ` +
+                        `sourceKey: ${keyLiteral(rel.through.sourceKey)}, ` +
+                        `targetKey: ${keyLiteral(rel.through.targetKey)} }`;
+            }
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral}${throughLiteral} },`);
         }
         lines.push('      },');
         // indexes

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.table = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = void 0;
+exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -90,6 +90,9 @@ Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: fun
 // Query builder
 var index_js_2 = require("./query/index.js");
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
+// Realtime — LISTEN/NOTIFY pub/sub
+var realtime_js_1 = require("./realtime.js");
+Object.defineProperty(exports, "validateChannel", { enumerable: true, get: function () { return realtime_js_1.validateChannel; } });
 // Schema utilities
 var schema_js_1 = require("./schema.js");
 Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });
@@ -102,6 +105,7 @@ Object.defineProperty(exports, "snakeToCamel", { enumerable: true, get: function
 Object.defineProperty(exports, "snakeToPascal", { enumerable: true, get: function () { return schema_js_1.snakeToPascal; } });
 // Schema builder — define schemas in TypeScript
 var schema_builder_js_1 = require("./schema-builder.js");
+Object.defineProperty(exports, "applyManyToManyRelations", { enumerable: true, get: function () { return schema_builder_js_1.applyManyToManyRelations; } });
 Object.defineProperty(exports, "ColumnBuilder", { enumerable: true, get: function () { return schema_builder_js_1.ColumnBuilder; } });
 Object.defineProperty(exports, "column", { enumerable: true, get: function () { return schema_builder_js_1.column; } });
 Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
@@ -116,3 +120,7 @@ Object.defineProperty(exports, "schemaToSQLString", { enumerable: true, get: fun
 // Serverless / edge factory
 var serverless_js_1 = require("./serverless.js");
 Object.defineProperty(exports, "turbineHttp", { enumerable: true, get: function () { return serverless_js_1.turbineHttp; } });
+// Typed raw SQL — Turbine's TypedSQL escape hatch
+var typed_sql_js_1 = require("./typed-sql.js");
+Object.defineProperty(exports, "buildTypedSql", { enumerable: true, get: function () { return typed_sql_js_1.buildTypedSql; } });
+Object.defineProperty(exports, "TypedSqlQuery", { enumerable: true, get: function () { return typed_sql_js_1.TypedSqlQuery; } });

package/dist/cjs/introspect.js

@@ -281,6 +281,87 @@ async function introspect(options) {
                 referenceKey,
             };
         }
+        // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
+        //
+        // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
+        // junction, but a `enrollments(student_id, course_id, grade, enrolled_at)`
+        // table is a first-class entity, not a join table. Prisma and Drizzle both
+        // require explicit m2m declaration for exactly this reason.
+        //
+        // We only treat a table J as a PURE junction when ALL of these hold:
+        //   1. J's primary key is exactly two columns.
+        //   2. J has exactly two FKs, each single-column.
+        //   3. Each FK's source column is one of J's two PK columns (the PK *is* the
+        //      two FK columns — no surrogate PK, no extra identity).
+        //   4. The two FKs target two DISTINCT tables (A and B).
+        //   5. J has no columns beyond those two FK/PK columns (no payload columns
+        //      like `grade` or `created_at`).
+        //
+        // For such a J linking A and B we ADD a `manyToMany` relation on A → B and
+        // symmetrically on B → A, both routed `through` J. The existing belongsTo /
+        // hasMany relations derived from J's FKs are left untouched — this block
+        // never removes or renames anything. If the chosen relation name already
+        // exists on the source table (e.g. another relation grabbed it), we SKIP to
+        // stay additive.
+        for (const tableName of tableNames) {
+            const pk = pkByTable.get(tableName) ?? [];
+            if (pk.length !== 2)
+                continue;
+            // FKs whose source is this table.
+            const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
+            if (tableFks.length !== 2)
+                continue;
+            // Both FKs must be single-column.
+            if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
+                continue;
+            const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
+            const pkSet = new Set(pk);
+            // Both FK columns must be the PK columns (and vice-versa).
+            if (!fkCols.every((c) => pkSet.has(c)))
+                continue;
+            if (new Set(fkCols).size !== 2)
+                continue;
+            // Two DISTINCT target tables.
+            const [fkA, fkB] = tableFks;
+            if (fkA.targetTable === fkB.targetTable)
+                continue;
+            // No payload columns: J's columns are exactly the two FK/PK columns.
+            const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
+            if (jCols.length !== 2)
+                continue;
+            // For each direction, the m2m `referenceKey` is the *targeted* table's
+            // referenced column(s); the junction's sourceKey is the FK column pointing
+            // to that table; the targetKey is the FK column pointing to the OTHER table.
+            const addM2M = (self, other) => {
+                const sourceTbl = self.targetTable; // A
+                const targetTbl = other.targetTable; // B
+                const relName = (0, schema_js_1.snakeToCamel)(targetTbl); // plural table name → e.g. "tags"
+                if (!relationsByTable.has(sourceTbl))
+                    relationsByTable.set(sourceTbl, {});
+                const existing = relationsByTable.get(sourceTbl);
+                // Additive-only: never clobber an existing relation name.
+                if (existing[relName])
+                    return;
+                existing[relName] = {
+                    type: 'manyToMany',
+                    name: relName,
+                    from: sourceTbl,
+                    to: targetTbl,
+                    // referenceKey = A's referenced column(s) that J's sourceKey points at.
+                    referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                    // foreignKey is unused for m2m correlation but kept for shape parity
+                    // (mirrors the source-side reference for back-compat consumers).
+                    foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                    through: {
+                        table: tableName,
+                        sourceKey: self.sourceColumns[0], // J col → A
+                        targetKey: other.sourceColumns[0], // J col → B
+                    },
+                };
+            };
+            addM2M(fkA, fkB); // A → B
+            addM2M(fkB, fkA); // B → A
+        }
         // ----- Assemble TableMetadata for each table -----
         const tables = {};
         for (const tableName of tableNames) {