turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/global-filters-config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * turbine-orm, `globalFilters` checked when the client is constructed
+ *
+ * A global filter is a tenancy or soft-delete boundary, so a filter that
+ * silently applies to nothing is the worst way for it to fail: a key naming no
+ * table (a typo, a renamed table), or a key the query builder does not look
+ * up. The builder looks filters up by TABLE name, while the config docs key
+ * them by client ACCESSOR (`blogPosts` for `blog_posts`).
+ *
+ * {@link normalizeGlobalFilters} maps each key to its table name, refuses a key
+ * that names no table and a static filter whose keys name no column or
+ * relation, and returns the map the query builder reads. Given the client's
+ * dialect it also compiles each static filter once, so a value the compiler
+ * refuses fails when the client is built rather than on the first query.
+ * Function filters are kept as they are: what they return is checked per query
+ * by the resolver, which also refuses a filter that resolves to `undefined`.
+ */
+import type { Dialect } from './dialect.js';
+import type { QueryInterface } from './query/builder.js';
+import type { GlobalFilters } from './query/index.js';
+import type { SchemaMetadata } from './schema.js';
+/** The accessor a table gets on the client (`blog_posts` -> `blogPosts`). The one place it is derived. */
+export declare function tableAccessorName(tableName: string): string;
+/**
+ * Whether a `skipGlobalFilters: [UNSAFE, ...names]` list names `table`, by its
+ * table name or by its client accessor, the two spellings `globalFilters` keys
+ * accept. With `tables` (the schema's table map), an accessor spelling that is
+ * itself another table's name refers to that other table only.
+ */
+export declare function skipListNamesTable(names: readonly string[], table: string, tables?: Readonly<Record<string, unknown>>): boolean;
+/**
+ * Refuse a `skipGlobalFilters` list entry that names no table, by table name or
+ * accessor: a misspelled entry skips nothing, so the filter the caller meant to
+ * lift stays on and the query quietly returns fewer rows than intended.
+ */
+export declare function assertSkipListNames(names: readonly string[], tables: Readonly<Record<string, unknown>>): void;
+/**
+ * The client options a static filter is compiled with at construction: the
+ * ones that decide whether a where clause compiles, and to what.
+ */
+export interface StaticFilterCompileOptions {
+    /**
+     * The SQL query builder. Passed in rather than imported: the query modules
+     * import this one, so a value import back would be an import cycle.
+     */
+    QueryInterface: typeof QueryInterface;
+    dialect?: Dialect | undefined;
+    utcTimestamps?: boolean | undefined;
+}
+/**
+ * Validate `globalFilters` against the schema and key it by table name.
+ * Throws `ValidationError` (E003) naming the bad key and the closest valid one.
+ *
+ * With `compile` (the client passes it for every SQL engine), each static
+ * filter is also compiled once with that dialect, so an operand the compiler
+ * refuses, a column misspelled inside a relation filter or a feature the
+ * engine lacks (E017) fails here and not on the first query.
+ */
+export declare function normalizeGlobalFilters(filters: GlobalFilters | undefined | null, schema: SchemaMetadata, compile?: StaticFilterCompileOptions): GlobalFilters | undefined;

package/dist/cjs/global-filters-config.js

@@ -0,0 +1,367 @@
+"use strict";
+/**
+ * turbine-orm, `globalFilters` checked when the client is constructed
+ *
+ * A global filter is a tenancy or soft-delete boundary, so a filter that
+ * silently applies to nothing is the worst way for it to fail: a key naming no
+ * table (a typo, a renamed table), or a key the query builder does not look
+ * up. The builder looks filters up by TABLE name, while the config docs key
+ * them by client ACCESSOR (`blogPosts` for `blog_posts`).
+ *
+ * {@link normalizeGlobalFilters} maps each key to its table name, refuses a key
+ * that names no table and a static filter whose keys name no column or
+ * relation, and returns the map the query builder reads. Given the client's
+ * dialect it also compiles each static filter once, so a value the compiler
+ * refuses fails when the client is built rather than on the first query.
+ * Function filters are kept as they are: what they return is checked per query
+ * by the resolver, which also refuses a filter that resolves to `undefined`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tableAccessorName = tableAccessorName;
+exports.skipListNamesTable = skipListNamesTable;
+exports.assertSkipListNames = assertSkipListNames;
+exports.normalizeGlobalFilters = normalizeGlobalFilters;
+const errors_js_1 = require("./errors.js");
+const filters_js_1 = require("./query/filters.js");
+const utils_js_1 = require("./query/utils.js");
+const where_compile_js_1 = require("./query/where-compile.js");
+/** The accessor a table gets on the client (`blog_posts` -> `blogPosts`). The one place it is derived. */
+function tableAccessorName(tableName) {
+    return tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Whether a `skipGlobalFilters: [UNSAFE, ...names]` list names `table`, by its
+ * table name or by its client accessor, the two spellings `globalFilters` keys
+ * accept. With `tables` (the schema's table map), an accessor spelling that is
+ * itself another table's name refers to that other table only.
+ */
+function skipListNamesTable(names, table, tables) {
+    if (names.includes(table))
+        return true;
+    const accessor = tableAccessorName(table);
+    if (accessor === table || (tables !== undefined && Object.hasOwn(tables, accessor)))
+        return false;
+    return names.includes(accessor);
+}
+/**
+ * Refuse a `skipGlobalFilters` list entry that names no table, by table name or
+ * accessor: a misspelled entry skips nothing, so the filter the caller meant to
+ * lift stays on and the query quietly returns fewer rows than intended.
+ */
+function assertSkipListNames(names, tables) {
+    for (const name of names) {
+        if (Object.hasOwn(tables, name))
+            continue;
+        if (Object.keys(tables).some((table) => skipListNamesTable([name], table, tables)))
+            continue;
+        const candidates = Object.keys(tables).flatMap((table) => [table, tableAccessorName(table)]);
+        const hint = nearestName(name, candidates);
+        throw new errors_js_1.ValidationError(`skipGlobalFilters names "${name}", which is not a table in the schema${hint ? `. Did you mean "${hint}"?` : '.'} ` +
+            'An entry that names no table skips nothing. List tables by table name (`blog_posts`) or client accessor (`blogPosts`).');
+    }
+}
+const COMBINATORS = new Set(['AND', 'OR', 'NOT']);
+/** How a non-plain-object config value reads in an error message. */
+function describeShape(value) {
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    if (typeof value !== 'object')
+        return typeof value;
+    const name = Object.getPrototypeOf(value)?.constructor?.name;
+    return `an instance of ${name || 'a class'}, not a plain object`;
+}
+/**
+ * Validate `globalFilters` against the schema and key it by table name.
+ * Throws `ValidationError` (E003) naming the bad key and the closest valid one.
+ *
+ * With `compile` (the client passes it for every SQL engine), each static
+ * filter is also compiled once with that dialect, so an operand the compiler
+ * refuses, a column misspelled inside a relation filter or a feature the
+ * engine lacks (E017) fails here and not on the first query.
+ */
+function normalizeGlobalFilters(filters, schema, compile) {
+    if (filters === undefined || filters === null)
+        return undefined;
+    if (!(0, filters_js_1.isPlainRecord)(filters)) {
+        throw new errors_js_1.ValidationError(`globalFilters must be an object keyed by table, for example \`{ posts: { deletedAt: null } }\`; received ${describeShape(filters)}.`);
+    }
+    const byAccessor = new Map();
+    for (const table of Object.keys(schema.tables)) {
+        const accessor = tableAccessorName(table);
+        if (accessor !== table && !Object.hasOwn(schema.tables, accessor))
+            byAccessor.set(accessor, table);
+    }
+    const normalized = {};
+    const keyFor = new Map();
+    for (const key of Object.keys(filters)) {
+        const table = Object.hasOwn(schema.tables, key) ? key : byAccessor.get(key);
+        if (table === undefined) {
+            const hint = nearestName(key, [...Object.keys(schema.tables), ...byAccessor.keys()]);
+            throw new errors_js_1.ValidationError(`globalFilters: "${key}" names no table in the schema${hint ? `. Did you mean "${hint}"?` : '.'} ` +
+                'A filter under a name that matches no table is never applied, so the rows it was meant to hide ' +
+                'would be returned. Key each filter by table name (`blog_posts`) or by its client accessor (`blogPosts`).');
+        }
+        const earlier = keyFor.get(table);
+        if (earlier !== undefined) {
+            throw new errors_js_1.ValidationError(`globalFilters: "${earlier}" and "${key}" both name table "${table}". Keep one filter per table, ` +
+                'combining the conditions with `AND: [...]` if both are needed.');
+        }
+        keyFor.set(table, key);
+        const value = filters[key];
+        if (typeof value === 'function' || value === null) {
+            (0, filters_js_1.setOwn)(normalized, table, value);
+            continue;
+        }
+        if (!(0, filters_js_1.isPlainRecord)(value)) {
+            throw new errors_js_1.ValidationError(`globalFilters["${key}"] must be a where object or a function returning one; received ${describeShape(value)}. An undefined filter usually means the value it was built from was not available yet: pass a ` +
+                'function, which is evaluated per query, for anything that depends on the current request.');
+        }
+        assertFilterNamesExist(value, schema.tables, schema.tables[table], key, '', 0);
+        // The query path refuses a filter holding `undefined` on every query (it
+        // may be a tenant id that was not set); a static filter is read once, so
+        // say so now, with the fix that applies to a static filter.
+        const hole = (0, filters_js_1.holdsUndefinedValue)(value, 0) ? (0, filters_js_1.findUndefinedPath)(value, '', 0) : null;
+        if (hole !== null) {
+            throw new errors_js_1.ValidationError(`globalFilters["${key}"] has an undefined value at "${hole}". A static filter is read once, when the ` +
+                'client is constructed, so a value that was not available then stays undefined, and every query on ' +
+                'the table would be refused. Pass a function, which is evaluated per query, for anything that depends ' +
+                'on the current request.');
+        }
+        // The whole clause shape at every depth (relation quantifier values among
+        // it), checked here rather than at the first query that reads this table.
+        try {
+            (0, where_compile_js_1.foldWhereFor)(schema.tables, table, value);
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.ValidationError)
+                throw new errors_js_1.ValidationError(`globalFilters["${key}"]: ${reasonOf(err)}`);
+            throw err;
+        }
+        (0, filters_js_1.setOwn)(normalized, table, value);
+    }
+    assertNoFilterCycle(normalized, schema, keyFor);
+    if (compile !== undefined)
+        assertStaticFiltersCompile(normalized, schema, keyFor, compile);
+    return normalized;
+}
+/** An error's own text, without the code tag and docs link a TurbineError message carries. */
+function reasonOf(err) {
+    return err.message.replace(/^\[TURBINE_E\d+\] /, '').replace(/ \(https:\/\/\S+\)$/, '');
+}
+/** Swallows every line: a construction-time compile is a check, not a query. */
+const SILENT_LOGGER = Object.freeze({});
+/**
+ * Compile every static filter with the client's dialect, through the query
+ * builder the queries use, so each value is checked by the same code that
+ * will bind it. First each table with only its own filter (so an error names
+ * the filter that holds it), then each table with every static filter, which
+ * also compiles the filters a relation filter reaches. Function filters are
+ * never called here: they may read request state that does not exist yet.
+ */
+function assertStaticFiltersCompile(filters, schema, keyFor, options) {
+    const staticFilters = {};
+    for (const table of Object.keys(filters)) {
+        const filter = filters[table];
+        if ((0, filters_js_1.isPlainRecord)(filter))
+            (0, filters_js_1.setOwn)(staticFilters, table, filter);
+    }
+    const compileOn = (table, applied) => {
+        try {
+            new options.QueryInterface(null, table, schema, [], {
+                dialect: options.dialect,
+                utcTimestamps: options.utcTimestamps,
+                globalFilters: applied,
+                sqlCache: false,
+                logger: SILENT_LOGGER,
+                diagnostics: { mode: 'production', advice: false },
+            }).buildFindMany({});
+        }
+        catch (err) {
+            throw labelledFilterError(err, keyFor.get(table) ?? table);
+        }
+    };
+    for (const table of Object.keys(staticFilters)) {
+        compileOn(table, { [table]: staticFilters[table] });
+    }
+    for (const table of Object.keys(staticFilters))
+        compileOn(table, staticFilters);
+}
+/** The compiler's refusal, named after the filter it came from, in its own class. */
+function labelledFilterError(err, key) {
+    if (err instanceof errors_js_1.UnsupportedFeatureError) {
+        const head = `${err.feature} is unsupported on "${err.dialect}".`;
+        const reason = reasonOf(err);
+        const hint = reason.startsWith(head) ? reason.slice(head.length).trim() : '';
+        return new errors_js_1.UnsupportedFeatureError(`globalFilters["${key}"]: ${err.feature}`, err.dialect, hint || undefined);
+    }
+    if (err instanceof errors_js_1.ValidationError)
+        return new errors_js_1.ValidationError(`globalFilters["${key}"]: ${reasonOf(err)}`);
+    return err;
+}
+/**
+ * Refuse static filters that reach their own table through relations, directly
+ * (`comments: { parent: { is: {...} } }`) or through another table's filter
+ * (`posts: { user: {...} }` beside `users: { posts: {...} }`). A table's
+ * filter applies to every row a relation filter reaches, the rows reached from
+ * inside another table's filter included, so such filters would apply each
+ * other without end. Function filters are not inspected here; the query path
+ * applies each table's filter once per chain for them.
+ */
+function assertNoFilterCycle(filters, schema, keyFor) {
+    const edges = new Map();
+    for (const table of Object.keys(filters)) {
+        const filter = filters[table];
+        if (!(0, filters_js_1.isPlainRecord)(filter))
+            continue;
+        const reached = [];
+        collectReachedTables(schema, table, table, filter, reached, 0);
+        edges.set(table, reached);
+    }
+    // Depth-first over tables with a static filter; `path[i]` is the table
+    // `chain[i]` leaves from, so a step back onto `path[k]` closes the cycle
+    // `chain[k..]`.
+    const done = new Set();
+    const visit = (table, chain, path) => {
+        if (done.has(table))
+            return;
+        for (const edge of edges.get(table) ?? []) {
+            const k = path.indexOf(edge.to);
+            if (k !== -1)
+                throw filterCycleError([...chain.slice(k), edge], keyFor);
+            if (edges.has(edge.to))
+                visit(edge.to, [...chain, edge], [...path, edge.to]);
+        }
+        done.add(table);
+    };
+    for (const table of edges.keys())
+        visit(table, [], [table]);
+}
+/** Every relation a where on `table` names, at any depth, as edges from `owner`'s filter. */
+function collectReachedTables(schema, owner, table, where, out, depth) {
+    const meta = Object.hasOwn(schema.tables, table) ? schema.tables[table] : undefined;
+    if (!meta || depth > where_compile_js_1.MAX_WHERE_DEPTH)
+        return;
+    for (const event of (0, where_compile_js_1.walkWhere)((0, where_compile_js_1.metadataWhereHost)(meta), where)) {
+        if (event.kind === 'or' || event.kind === 'and') {
+            for (const branch of event.conditions)
+                collectReachedTables(schema, owner, table, branch, out, depth + 1);
+        }
+        else if (event.kind === 'not') {
+            collectReachedTables(schema, owner, table, event.condition, out, depth + 1);
+        }
+        else if (event.kind === 'relation') {
+            out.push({ from: owner, to: event.relDef.to, relation: `${table}.${event.key}` });
+            for (const wrapper of filters_js_1.RELATION_FILTER_WRAPPERS) {
+                const sub = event.filterObj[wrapper];
+                if ((0, filters_js_1.isPlainRecord)(sub))
+                    collectReachedTables(schema, owner, event.relDef.to, sub, out, depth + 1);
+            }
+        }
+    }
+}
+function filterCycleError(cycle, keyFor) {
+    const steps = cycle.map((edge) => `the filter for "${keyFor.get(edge.from) ?? edge.from}" reaches "${edge.to}" through "${edge.relation}"`);
+    return new errors_js_1.ValidationError(`globalFilters: ${steps.join(', and ')}. A global filter applies to every row a relation filter reaches, ` +
+        "including the rows reached from inside another table's filter, so these filters would apply each other " +
+        'without end. Remove the relation filter from one of them, or write that condition into the queries that ' +
+        'need it.');
+}
+/**
+ * Every key of a static filter (of its AND/OR/NOT branches, and of the where
+ * objects its relation filters hold, against the related table) must be a
+ * column or relation, and every combinator must have a shape the query
+ * compiler reads: one it cannot read would apply no condition, so a tenant
+ * filter written as `OR: { ... }` would match every row.
+ */
+function assertFilterNamesExist(filter, tables, meta, key, path, depth) {
+    if (depth > where_compile_js_1.MAX_WHERE_DEPTH)
+        return;
+    for (const field of Object.keys(filter)) {
+        const at = path ? `${path}.${field}` : field;
+        if (COMBINATORS.has(field)) {
+            const branch = filter[field];
+            try {
+                (0, where_compile_js_1.combinatorBranches)(field, branch, meta.name);
+            }
+            catch (err) {
+                if (!(err instanceof errors_js_1.ValidationError))
+                    throw err;
+                throw new errors_js_1.ValidationError(`globalFilters["${key}"]: "${at}" is refused. ${reasonOf(err)}`);
+            }
+            if (Array.isArray(branch)) {
+                branch.forEach((b, i) => {
+                    if (b !== undefined) {
+                        assertFilterNamesExist(b, tables, meta, key, `${at}[${i}]`, depth + 1);
+                    }
+                });
+            }
+            else if (branch !== undefined) {
+                assertFilterNamesExist(branch, tables, meta, key, at, depth + 1);
+            }
+            continue;
+        }
+        if ((0, utils_js_1.resolveColumnName)(meta, field) !== undefined)
+            continue;
+        const relation = (0, utils_js_1.resolveRelation)(meta.relations ?? {}, field);
+        if (relation !== undefined) {
+            const value = filter[field];
+            const target = Object.hasOwn(tables, relation.def.to) ? tables[relation.def.to] : undefined;
+            if (target === undefined || !(0, filters_js_1.isPlainRecord)(value))
+                continue;
+            const wrapped = filters_js_1.RELATION_FILTER_WRAPPERS.some((wrapper) => wrapper in value);
+            if (!wrapped) {
+                // A bare where object on a to-one relation (an implicit `is`).
+                assertFilterNamesExist(value, tables, target, key, at, depth + 1);
+                continue;
+            }
+            for (const wrapper of filters_js_1.RELATION_FILTER_WRAPPERS) {
+                const sub = value[wrapper];
+                if ((0, filters_js_1.isPlainRecord)(sub))
+                    assertFilterNamesExist(sub, tables, target, key, `${at}.${wrapper}`, depth + 1);
+            }
+            continue;
+        }
+        const candidates = [...Object.keys(meta.columnMap), ...Object.keys(meta.relations ?? {})];
+        const hint = nearestName(field, candidates);
+        throw new errors_js_1.ValidationError(`globalFilters["${key}"]: "${at}" is not a column or relation of "${meta.name}"` +
+            `${hint ? `. Did you mean "${hint}"?` : '.'} The filter would fail on every query against this table.`);
+    }
+}
+/** Levenshtein distance between two strings. */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/**
+ * The candidate a mistyped name most likely meant, by edit distance with case
+ * and underscores ignored (so `tenent_id` and `tenentID` both reach
+ * `tenantId`), ties broken by the raw spelling. Not substring containment: a
+ * short name inside the typo (`id` in `tenentId`) is not what was meant.
+ */
+function nearestName(input, candidates) {
+    const fold = (name) => name.toLowerCase().replace(/_/g, '');
+    const wanted = fold(input);
+    let best = null;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const folded = fold(candidate);
+        const distance = editDistance(wanted, folded);
+        if (distance > Math.max(2, Math.floor(Math.max(wanted.length, folded.length) / 3)))
+            continue;
+        const score = distance * 1000 + editDistance(input, candidate);
+        if (score < bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}

package/dist/cjs/index.d.ts

@@ -34,17 +34,22 @@
  */
 export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
-export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type PlanCacheMode, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
-export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
+export { type ConnectionLostEvent, type DisconnectOptions, type DisconnectResult, type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type PlanCacheMode, type PoolErrorEvent, type PoolEvent, type PoolEventOrigin, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
+export type { CacheCheckMode, DiagnosticsConfig, DiagnosticsMode, DiagnosticsOptions, ResolvedDiagnostics, } from './diagnostics.js';
+export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, EngineCapabilities, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
 export { postgresDialect } from './dialect.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, REDACTED_DETAIL, ReadOnlyError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, InvariantError, LockNotAvailableError, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, REDACTED_DETAIL, ReadOnlyError, type ReadOnlyReason, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, type TimeoutOutcome, TransactionRolledBackError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
+export type { TurbineLogCode, TurbineLogEntry, TurbineLogger, TurbineLogLevel } from './logger.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type MetricsFlushRow, type ObserveConfig, type ObserveHandle, type ObserveSink, PgMetricsSink, type PgMetricsSinkOptions, } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { type CaseArm, type ExprOperand, expr, type NumericOperand } from './query/expr.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, col, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type JsonValue, jsonValue, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export type { SqlCommentOptions } from './query/sql-comment.js';
+export type { AggregateResultOf, ConflictTarget, ConflictUpdateData, CreateManyOnConflict, DefaultInputTypes, ExcludedRef, GlobalFilter, NestedToOneCreateOp, NestedToOneUpdateOp, OptionalInput, PercentileMethod, PercentileSpec, RelationKind, RowLock, RowLockMode, SqlExpr, SqlExprKind, TableInputTypes, } from './query/types.js';
 export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 export { type ActiveSubscription, type ListenOptions, type ListenReconnectOptions, type NotificationHandler, type Subscription, validateChannel, } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.fingerprintPrismaSchema = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.REDACTED_DETAIL = 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.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.RAW_QUERY_MODEL = exports.MAX_QUERY_TAG_LENGTH = exports.UNSAFE = void 0;
+exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.expr = exports.fingerprintPrismaSchema = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TransactionRolledBackError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.REDACTED_DETAIL = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.LockNotAvailableError = exports.InvariantError = 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.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.RAW_QUERY_MODEL = exports.MAX_QUERY_TAG_LENGTH = exports.UNSAFE = exports.QueryInterface = exports.jsonValue = exports.col = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = 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; } });
@@ -58,6 +58,8 @@ Object.defineProperty(exports, "DeadlockError", { enumerable: true, get: functio
 Object.defineProperty(exports, "ExclusionConstraintError", { enumerable: true, get: function () { return errors_js_1.ExclusionConstraintError; } });
 Object.defineProperty(exports, "ForeignKeyError", { enumerable: true, get: function () { return errors_js_1.ForeignKeyError; } });
 Object.defineProperty(exports, "getErrorMessageMode", { enumerable: true, get: function () { return errors_js_1.getErrorMessageMode; } });
+Object.defineProperty(exports, "InvariantError", { enumerable: true, get: function () { return errors_js_1.InvariantError; } });
+Object.defineProperty(exports, "LockNotAvailableError", { enumerable: true, get: function () { return errors_js_1.LockNotAvailableError; } });
 Object.defineProperty(exports, "MigrationError", { enumerable: true, get: function () { return errors_js_1.MigrationError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
 Object.defineProperty(exports, "NotNullViolationError", { enumerable: true, get: function () { return errors_js_1.NotNullViolationError; } });
@@ -69,6 +71,7 @@ Object.defineProperty(exports, "RelationError", { enumerable: true, get: functio
 Object.defineProperty(exports, "SerializationFailureError", { enumerable: true, get: function () { return errors_js_1.SerializationFailureError; } });
 Object.defineProperty(exports, "setErrorMessageMode", { enumerable: true, get: function () { return errors_js_1.setErrorMessageMode; } });
 Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "TransactionRolledBackError", { enumerable: true, get: function () { return errors_js_1.TransactionRolledBackError; } });
 Object.defineProperty(exports, "TurbineError", { enumerable: true, get: function () { return errors_js_1.TurbineError; } });
 Object.defineProperty(exports, "TurbineErrorCode", { enumerable: true, get: function () { return errors_js_1.TurbineErrorCode; } });
 Object.defineProperty(exports, "UniqueConstraintError", { enumerable: true, get: function () { return errors_js_1.UniqueConstraintError; } });
@@ -97,6 +100,9 @@ Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: fun
 // Prisma-schema fingerprint (provenance on a generated PRISMA_MAP)
 var prisma_schema_fingerprint_js_1 = require("./prisma-schema-fingerprint.js");
 Object.defineProperty(exports, "fingerprintPrismaSchema", { enumerable: true, get: function () { return prisma_schema_fingerprint_js_1.fingerprintPrismaSchema; } });
+// Update expressions: `expr.add(col('n'), 1)`, `expr.excluded('name')`, ...
+var expr_js_1 = require("./query/expr.js");
+Object.defineProperty(exports, "expr", { enumerable: true, get: function () { return expr_js_1.expr; } });
 // Query builder
 // The privilege sentinel. `skipGlobalFilters` / `includePii` /
 // `allowFullTableScan` are unlocked by THIS VALUE and nothing else, so a
@@ -108,6 +114,8 @@ Object.defineProperty(exports, "AUTO_JOIN_PENALTY_MS_PER_ROW", { enumerable: tru
 Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_MAX_ROWS", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_MAX_ROWS; } });
 Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MAX", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MAX; } });
 Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MIN", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MIN; } });
+Object.defineProperty(exports, "col", { enumerable: true, get: function () { return index_js_2.col; } });
+Object.defineProperty(exports, "jsonValue", { enumerable: true, get: function () { return index_js_2.jsonValue; } });
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
 Object.defineProperty(exports, "UNSAFE", { enumerable: true, get: function () { return index_js_2.UNSAFE; } });
 // $on('query') event metadata: raw-statement model name, $tag() label limit

package/dist/cjs/introspect.d.ts

@@ -8,6 +8,7 @@
  * This is the foundation of `npx turbine generate`.
  */
 import { type Dialect } from './dialect.js';
+import { type TurbineLogger } from './logger.js';
 import { type ColumnMetadata, type IndexMetadata, type ReferentialAction, type RelationDef, type SchemaMetadata } from './schema.js';
 /**
  * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
@@ -116,7 +117,28 @@ export interface IntrospectOptions {
      * here so `introspect()` works across databases.
      */
     dialect?: Dialect;
+    /**
+     * Where introspection notes go (a skipped cross-schema foreign key, a
+     * renamed or shadowing relation). Defaults to the console logger.
+     */
+    logger?: TurbineLogger;
 }
+/**
+ * A catalog name made safe to PRINT. Every diagnostic that quotes a table,
+ * column, enum, relation or constraint name goes through this, because Postgres
+ * lets anyone with CREATE privilege pick any characters for those, and an
+ * unescaped name in an error message is a way to write escape sequences to the
+ * developer's terminal. Control and bidi characters become visible escapes
+ * (`\n`, `\u001b`); everything else, including non-ASCII letters, is untouched.
+ */
+export declare function printableCatalogName(name: string): string;
+/**
+ * An empty record for something keyed by catalog names. Prototype-less on
+ * purpose: a plain `{}` turns a table named `__proto__` into a prototype
+ * assignment (the table silently disappears), and makes `enums['constructor']`
+ * truthy before any enum was ever added.
+ */
+export declare function nullRecord<T>(): Record<string, T>;
 /**
  * Refuse one catalog identifier carrying a character from
  * {@link UNSAFE_CATALOG_CHARS}. `subject` names the object in the error.
@@ -137,7 +159,8 @@ export declare function assertSafeCatalogSchema(schema: SchemaMetadata): void;
 /**
  * Introspect a database into {@link SchemaMetadata}, routing through the active
  * dialect's {@link Dialect.introspector} so each engine can override the catalog
- * SQL. PostgreSQL is driven by {@link introspectPostgresCatalog}.
+ * SQL. A dialect with none, PostgreSQL included, is read by
+ * {@link introspectPostgresCatalog}.
  */
 export declare function introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
 /**
@@ -180,8 +203,8 @@ export declare function applyRelationRenames(schema: SchemaMetadata, renames: Re
 export declare function assertDistinctColumnFields(tableName: string, columns: readonly ColumnMetadata[]): void;
 /**
  * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
- * produces {@link SchemaMetadata}. This is the implementation wrapped by
- * `postgresDialect.introspector`; call {@link introspect} for dialect routing.
+ * produces {@link SchemaMetadata}. {@link introspect} calls it for PostgreSQL;
+ * call {@link introspect} for dialect routing.
  */
 export declare function introspectPostgresCatalog(options: IntrospectOptions): Promise<SchemaMetadata>;
 /**
@@ -401,7 +424,7 @@ export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string
 export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEntry[], columnFieldsByTable: Map<string, Set<string>>, fkActions?: Map<string, {
     onDelete: ReferentialAction;
     onUpdate: ReferentialAction;
-}>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueSetsByTable?: Map<string, string[][]>): Map<string, Record<string, RelationDef>>;
+}>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueSetsByTable?: Map<string, string[][]>, logger?: TurbineLogger): Map<string, Record<string, RelationDef>>;
 /**
  * Conservative auto-`manyToMany` detection over pure junction tables, shared
  * by the Postgres introspector, the engine introspectors (SQLite / MySQL /
@@ -428,7 +451,7 @@ export declare function buildRelationsFromForeignKeys(foreignKeys: ForeignKeyEnt
  *   - a shadowed concrete-typed column → deterministic `Rel` suffix + warn
  *     instead of silently dropping the relation.
  */
-export declare function addAutoManyToManyRelations(tableNames: Iterable<string>, foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnNamesByTable: Map<string, string[]>, relationsByTable: Map<string, Record<string, RelationDef>>, columnFieldsByTable?: Map<string, Set<string>>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueIndexColsByTable?: Map<string, string[][]>): void;
+export declare function addAutoManyToManyRelations(tableNames: Iterable<string>, foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnNamesByTable: Map<string, string[]>, relationsByTable: Map<string, Record<string, RelationDef>>, columnFieldsByTable?: Map<string, Set<string>>, unknownTypedFieldsByTable?: Map<string, Set<string>>, uniqueIndexColsByTable?: Map<string, string[][]>, logger?: TurbineLogger): void;
 /** Everything the catalog relation derivation reads. See {@link deriveCatalogRelations}. */
 export interface CatalogRelationInputs {
     /** The introspected table set, post include/exclude filtering. */
@@ -452,6 +475,8 @@ export interface CatalogRelationInputs {
     }>;
     /** Opt out of the unique-FK → `hasOne` flip (F2), see {@link IntrospectOptions.legacyToManyUniques}. */
     legacyToManyUniques?: boolean;
+    /** Where relation-naming notes go. Defaults to the console logger. */
+    logger?: TurbineLogger;
 }
 /**
  * One-stop relation derivation for every surface that reads a live PostgreSQL
@@ -486,4 +511,4 @@ export declare function deriveCatalogRelations(inputs: CatalogRelationInputs): M
  * relation names for the same logical schema (the engines previously carried
  * stale copies of a retired naming scheme).
  */
-export declare function deriveEngineRelations(tableNames: string[], foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnsByTable: Map<string, Pick<ColumnMetadata, 'name' | 'field' | 'tsType'>[]>): Map<string, Record<string, RelationDef>>;
+export declare function deriveEngineRelations(tableNames: string[], foreignKeys: ForeignKeyEntry[], pkByTable: Map<string, string[]>, columnsByTable: Map<string, Pick<ColumnMetadata, 'name' | 'field' | 'tsType'>[]>, logger?: TurbineLogger): Map<string, Record<string, RelationDef>>;