turbine-orm 0.81.0 → 0.90.0

package/dist/introspect.js

@@ -10,6 +10,7 @@
 import pg from '#pg';
 import { postgresDialect } from './dialect.js';
 import { ValidationError } from './errors.js';
+import { consoleLogger, logTo } from './logger.js';
 import { isDateType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
 /**
  * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
@@ -328,6 +329,58 @@ export function defaultExcludedTablesPresent(names, options = {}) {
  */
 // biome-ignore lint/suspicious/noControlCharactersInRegex: detecting control characters is this pattern's purpose
 const UNSAFE_CATALOG_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+ * Characters that must not reach a terminal or a log verbatim: everything in
+ * {@link UNSAFE_CATALOG_CHARS} (an ESC starts an ANSI sequence, a carriage
+ * return overwrites the line), plus the bidirectional controls that reorder how
+ * a name is displayed without changing what it is.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: neutralizing control characters is this pattern's purpose
+const TERMINAL_UNSAFE_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/**
+ * 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 function printableCatalogName(name) {
+    return name.replace(TERMINAL_UNSAFE_CHARS, (ch) => {
+        if (ch === '\n')
+            return '\\n';
+        if (ch === '\r')
+            return '\\r';
+        if (ch === '\t')
+            return '\\t';
+        return `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`;
+    });
+}
+/**
+ * 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 function nullRecord() {
+    return Object.create(null);
+}
+/**
+ * The TypeScript type for a catalog type name. A user-defined type can be named
+ * after an `Object.prototype` member (`toString`, `constructor`, `valueOf`),
+ * which a plain-object type table answers with a function instead of nothing, so
+ * that case is pinned to `unknown` here, before any type table is consulted,
+ * rather than emitted as function source. `lookup` is the dialect's own mapping
+ * for every other name.
+ */
+function tsTypeForCatalogType(typeName, nullable, lookup = pgTypeToTs) {
+    const isArray = typeName.startsWith('_');
+    if ((isArray ? typeName.slice(1) : typeName) in Object.prototype) {
+        const unknownType = isArray ? 'unknown[]' : 'unknown';
+        return nullable ? `${unknownType} | null` : unknownType;
+    }
+    return lookup(typeName, nullable);
+}
 /**
  * Refuse one catalog identifier carrying a character from
  * {@link UNSAFE_CATALOG_CHARS}. `subject` names the object in the error.
@@ -337,7 +390,7 @@ export function assertSafeCatalogIdentifier(name, subject) {
     if (match === null)
         return;
     const code = match[0].charCodeAt(0).toString(16).padStart(4, '0');
-    throw new ValidationError(`Refusing to introspect ${subject}: its name contains the control character U+${code.toUpperCase()} ` +
+    throw new ValidationError(`Refusing to introspect ${printableCatalogName(subject)}: its name contains the control character U+${code.toUpperCase()} ` +
         `at position ${match.index}. Such a name cannot be safely emitted into generated code, SQL comments, or ` +
         `tooling output. Rename the database object, or exclude it from introspection.`);
 }
@@ -397,14 +450,15 @@ export function assertSafeCatalogSchema(schema) {
 /**
  * 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 async function introspect(options) {
     const dialect = options.dialect ?? postgresDialect;
     const introspector = dialect.introspector;
     const schema = introspector
         ? await introspector.introspect(options)
-        : // Dialects without an introspector fall back to the Postgres catalog reader.
+        : // PostgreSQL, and any dialect without an introspector, reads the Postgres catalog.
             await introspectPostgresCatalog(options);
     // Applied here rather than inside each introspector so every engine gets it.
     const renamed = options.relationNames ? applyRelationRenames(schema, options.relationNames) : schema;
@@ -430,18 +484,18 @@ export async function introspect(options) {
  * means the call sites it was supposed to fix break at runtime instead.
  */
 export function applyRelationRenames(schema, renames) {
-    const tables = { ...schema.tables };
+    const tables = Object.assign(nullRecord(), schema.tables);
     for (const [table, mapping] of Object.entries(renames)) {
-        const meta = tables[table];
+        const meta = Object.hasOwn(tables, table) ? tables[table] : undefined;
         if (!meta) {
-            throw new ValidationError(`relationNames: unknown table "${table}". Known tables: ${Object.keys(tables).join(', ')}.`);
+            throw new ValidationError(`relationNames: unknown table "${printableCatalogName(table)}". Known tables: ${Object.keys(tables).map(printableCatalogName).join(', ')}.`);
         }
-        const relations = { ...meta.relations };
+        const relations = Object.assign(nullRecord(), meta.relations);
         const columnFields = new Set(Object.values(meta.columnMap));
         for (const [from, to] of Object.entries(mapping)) {
             if (!Object.hasOwn(relations, from)) {
-                throw new ValidationError(`relationNames: table "${table}" has no relation "${from}". ` +
-                    `Derived relations: ${Object.keys(relations).join(', ') || '(none)'}.`);
+                throw new ValidationError(`relationNames: table "${printableCatalogName(table)}" has no relation "${printableCatalogName(from)}". ` +
+                    `Derived relations: ${Object.keys(relations).map(printableCatalogName).join(', ') || '(none)'}.`);
             }
             if (from === to)
                 continue;
@@ -494,21 +548,21 @@ export function assertDistinctColumnFields(tableName, columns) {
     for (const [field, names] of columnsByField) {
         if (names.length < 2)
             continue;
-        const quoted = names.map((n) => `"${n}"`);
+        const quoted = names.map((n) => `"${printableCatalogName(n)}"`);
         const list = `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`;
-        collisions.push(`columns ${list} ${names.length === 2 ? 'both' : 'all'} resolve to the field "${field}"`);
+        collisions.push(`columns ${list} ${names.length === 2 ? 'both' : 'all'} resolve to the field "${printableCatalogName(field)}"`);
     }
     if (collisions.length === 0)
         return;
-    throw new ValidationError(`Field collision on table "${tableName}": ${collisions.join('; ')}. A client addresses one column per field, ` +
+    throw new ValidationError(`Field collision on table "${printableCatalogName(tableName)}": ${collisions.join('; ')}. A client addresses one column per field, ` +
         'so reads would fold the colliding columns into one property and a write to that field would reach only ' +
         'one of them. Rename one of the columns, or set `keepColumnNames: true` in turbine.config.ts ' +
         '(`turbine generate --keep-column-names`) so every field is its raw column name.');
 }
 /**
  * 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 async function introspectPostgresCatalog(options) {
     const schema = options.schema ?? 'public';
@@ -581,8 +635,7 @@ export async function introspectPostgresCatalog(options) {
                 field: options.keepColumnNames ? row.column_name : snakeToCamel(row.column_name),
                 dialectType,
                 pgType: dialectType,
-                tsType: dialect.typeToTypeScript?.(isArray ? dialectType : baseType, isNullable) ??
-                    pgTypeToTs(isArray ? dialectType : baseType, isNullable),
+                tsType: tsTypeForCatalogType(isArray ? dialectType : baseType, isNullable, dialect.typeToTypeScript?.bind(dialect) ?? pgTypeToTs),
                 nullable: isNullable,
                 hasDefault: row.column_default !== null,
                 // Server-generated = a sequence default (serial/BIGSERIAL → nextval(…))
@@ -678,9 +731,9 @@ export async function introspectPostgresCatalog(options) {
             });
         }
         // ----- Collect enums -----
-        const enums = {};
+        const enums = nullRecord();
         for (const row of enumResult.rows) {
-            if (!enums[row.typname])
+            if (!Object.hasOwn(enums, row.typname))
                 enums[row.typname] = [];
             enums[row.typname].push(row.enumlabel);
         }
@@ -726,9 +779,9 @@ export async function introspectPostgresCatalog(options) {
         }
         const foreignKeys = Array.from(fkGroups.values());
         if (crossSchemaRefs.length > 0) {
-            console.warn(`[turbine] Skipped ${crossSchemaRefs.length} foreign key(s) referencing a table outside schema "${schema}": ` +
-                `${crossSchemaRefs.join(', ')}. Generated clients address tables by bare name within one schema, so no ` +
-                `relation is emitted for these. Introspect the other schema separately, or add the target table to this one.`);
+            logTo(options.logger ?? consoleLogger, 'warn', `Skipped ${crossSchemaRefs.length} foreign key(s) referencing a table outside schema "${printableCatalogName(schema)}": ` +
+                `${crossSchemaRefs.map(printableCatalogName).join(', ')}. Generated clients address tables by bare name within one schema, so no ` +
+                `relation is emitted for these. Introspect the other schema separately, or add the target table to this one.`, { code: 'introspect-cross-schema-fk', schema, references: crossSchemaRefs.length });
         }
         // Referential actions (ON DELETE / ON UPDATE) per constraint. Keyed
         // "<table>::<constraint>" because the NAME alone is not unique (the same
@@ -761,16 +814,17 @@ export async function introspectPostgresCatalog(options) {
             enums,
             fkActions,
             legacyToManyUniques: options.legacyToManyUniques,
+            ...(options.logger !== undefined ? { logger: options.logger } : {}),
         });
         // ----- Assemble TableMetadata for each table -----
-        const tables = {};
+        const tables = nullRecord();
         for (const tableName of tableNames) {
             const columns = columnsByTable.get(tableName) ?? [];
-            const columnMap = {};
-            const reverseColumnMap = {};
+            const columnMap = nullRecord();
+            const reverseColumnMap = nullRecord();
             const dateColumns = new Set();
-            const dialectTypes = {};
-            const pgTypes = {};
+            const dialectTypes = nullRecord();
+            const pgTypes = nullRecord();
             const allColumns = [];
             for (const col of columns) {
                 columnMap[col.field] = col.name;
@@ -794,7 +848,7 @@ export async function introspectPostgresCatalog(options) {
                 allColumns,
                 primaryKey: pkByTable.get(tableName) ?? [],
                 uniqueColumns: uniqueByTable.get(tableName) ?? [],
-                relations: relationsByTable.get(tableName) ?? {},
+                relations: relationsByTable.get(tableName) ?? nullRecord(),
                 indexes: indexesByTable.get(tableName) ?? [],
                 checks: checksByTable.get(tableName) ?? [],
                 ...(viewNameSet.has(tableName) ? { isView: true } : {}),
@@ -1181,13 +1235,13 @@ export function detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTa
  * colliding name would otherwise shadow a column field and generate types
  * that fail `tsc --strict` (TS2430/TS2322).
  */
-function resolveRelationNameCollision(candidate, taken, table, source) {
+function resolveRelationNameCollision(candidate, taken, table, source, logger) {
     if (!taken.has(candidate))
         return candidate;
     let name = `${candidate}Rel`;
     for (let i = 2; taken.has(name); i++)
         name = `${candidate}Rel${i}`;
-    console.warn(`[turbine] Relation name "${candidate}" on table "${table}" (from ${source}) collides with an existing column or relation, using "${name}" instead.`);
+    logTo(logger, 'warn', printableCatalogName(`Relation name "${candidate}" on table "${table}" (from ${source}) collides with an existing column or relation, using "${name}" instead.`), { code: 'introspect-relation-renamed', table, relation: name, wanted: candidate });
     return name;
 }
 /**
@@ -1229,7 +1283,7 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
  *   engine introspectors and `defineSchema` path do) to keep every reverse
  *   relation `hasMany`.
  */
-export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable) {
+export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable, logger = consoleLogger) {
     // Count FKs per (source, target) pair for disambiguation.
     const fkCounts = new Map();
     for (const fk of foreignKeys) {
@@ -1265,18 +1319,19 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         const taken = takenFor(table);
         if (!taken.has(legacy))
             return legacy;
-        // Historical json/jsonb shadow: previously worked at runtime AND compiled
-        // (tsType `unknown` absorbs the relation payload). Keep the name, warn -
-        // typeSafeRelations() keeps the generated type layer sound.
+        // A relation named like a json/jsonb column keeps that name: it works at
+        // runtime and compiles (the column's `unknown` type absorbs the relation
+        // payload). Keep it and warn; typeSafeRelations() keeps the generated types
+        // sound.
         if (!assignedFor(table).has(legacy) && unknownTypedFieldsByTable?.get(table)?.has(legacy)) {
-            console.warn(`[turbine] Relation "${legacy}" on table "${table}" (from ${source}) shadows the json/jsonb column ` +
+            logTo(logger, 'warn', printableCatalogName(`Relation "${legacy}" on table "${table}" (from ${source}) shadows the json/jsonb column ` +
                 `"${legacy}", keeping the historical name for runtime compatibility; the relation is omitted from ` +
-                `the generated types. Rename the column to expose it.`);
+                `the generated types. Rename the column to expose it.`), { code: 'introspect-relation-shadows-json', table, relation: legacy });
             return legacy;
         }
         if (modern !== null && modern !== legacy && !taken.has(modern))
             return modern;
-        return resolveRelationNameCollision(modern ?? legacy, taken, table, source);
+        return resolveRelationNameCollision(modern ?? legacy, taken, table, source, logger);
     };
     for (const fk of foreignKeys) {
         const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
@@ -1325,7 +1380,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         if (actions?.onUpdate && actions.onUpdate !== 'no action')
             actionFields.onUpdate = actions.onUpdate;
         if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
+            relationsByTable.set(fk.sourceTable, nullRecord());
         relationsByTable.get(fk.sourceTable)[belongsToName] = {
             type: 'belongsTo',
             name: belongsToName,
@@ -1366,7 +1421,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         takenFor(fk.targetTable).add(reverseName);
         assignedFor(fk.targetTable).add(reverseName);
         if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
+            relationsByTable.set(fk.targetTable, nullRecord());
         relationsByTable.get(fk.targetTable)[reverseName] = {
             type: reverseType,
             name: reverseName,
@@ -1405,7 +1460,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
  *   - a shadowed concrete-typed column → deterministic `Rel` suffix + warn
  *     instead of silently dropping the relation.
  */
-export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, uniqueIndexColsByTable) {
+export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, uniqueIndexColsByTable, logger = consoleLogger) {
     for (const tableName of tableNames) {
         // FKs whose source is this table, both must be single-column.
         const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
@@ -1451,22 +1506,22 @@ export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, c
             const targetTbl = other.targetTable; // B
             let relName = snakeToCamel(targetTbl); // plural table name → e.g. "tags"
             if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
+                relationsByTable.set(sourceTbl, nullRecord());
             const existing = relationsByTable.get(sourceTbl);
             // Additive-only: never clobber an existing relation name.
-            if (existing[relName])
+            if (Object.hasOwn(existing, relName))
                 return;
             const columnFields = columnFieldsByTable?.get(sourceTbl);
             if (columnFields?.has(relName)) {
                 if (unknownTypedFieldsByTable?.get(sourceTbl)?.has(relName)) {
-                    // Historical json/jsonb shadow, worked at runtime, compiled fine.
-                    console.warn(`[turbine] Relation "${relName}" on table "${sourceTbl}" (junction ${tableName}) shadows the ` +
+                    // Same json/jsonb shadow as above: keep the name and warn.
+                    logTo(logger, 'warn', printableCatalogName(`Relation "${relName}" on table "${sourceTbl}" (junction ${tableName}) shadows the ` +
                         `json/jsonb column "${relName}", keeping the historical name for runtime compatibility; ` +
-                        `the relation is omitted from the generated types.`);
+                        `the relation is omitted from the generated types.`), { code: 'introspect-relation-shadows-json', table: sourceTbl, relation: relName });
                 }
                 else {
                     const taken = new Set([...columnFields, ...Object.keys(existing)]);
-                    relName = resolveRelationNameCollision(relName, taken, sourceTbl, `junction ${tableName}`);
+                    relName = resolveRelationNameCollision(relName, taken, sourceTbl, `junction ${tableName}`, logger);
                 }
             }
             existing[relName] = {
@@ -1530,7 +1585,8 @@ export function deriveCatalogRelations(inputs) {
     const uniqueSetsByTable = inputs.legacyToManyUniques
         ? undefined
         : detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTable);
-    const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, inputs.fkActions, unknownTypedFieldsByTable, uniqueSetsByTable);
+    const logger = inputs.logger ?? consoleLogger;
+    const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, inputs.fkActions, unknownTypedFieldsByTable, uniqueSetsByTable, logger);
     // Prisma's implicit m2m junctions have no primary key (just a two-column
     // UNIQUE index over the FK columns), so pass the introspected two-column
     // unique indexes as the fallback junction-key source.
@@ -1559,7 +1615,7 @@ export function deriveCatalogRelations(inputs) {
         if (twoColUniques.length > 0)
             uniqueIndexColsByTable.set(tbl, twoColUniques);
     }
-    addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, uniqueIndexColsByTable);
+    addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, uniqueIndexColsByTable, logger);
     return relationsByTable;
 }
 /**
@@ -1571,7 +1627,7 @@ export function deriveCatalogRelations(inputs) {
  * relation names for the same logical schema (the engines previously carried
  * stale copies of a retired naming scheme).
  */
-export function deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable) {
+export function deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable, logger = consoleLogger) {
     const tableSet = new Set(tableNames);
     const fks = foreignKeys.filter((fk) => tableSet.has(fk.sourceTable) && tableSet.has(fk.targetTable));
     const columnFieldsByTable = new Map();
@@ -1580,7 +1636,7 @@ export function deriveEngineRelations(tableNames, foreignKeys, pkByTable, column
         columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
         unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType)).map((c) => c.field)));
     }
-    const relationsByTable = buildRelationsFromForeignKeys(fks, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
-    addAutoManyToManyRelations(tableNames, fks, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable);
+    const relationsByTable = buildRelationsFromForeignKeys(fks, columnFieldsByTable, undefined, unknownTypedFieldsByTable, undefined, logger);
+    addAutoManyToManyRelations(tableNames, fks, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, undefined, logger);
     return relationsByTable;
 }

package/dist/log-codes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * turbine-orm, every `code` a Turbine log line can carry.
+ *
+ * A log line's TEXT is not a stable contract; its `code` is. This list is the
+ * whole set. Library code imports it as a TYPE only (see `TurbineLogCode` in
+ * logger.ts), so an emitter cannot use a code that is not here and the list
+ * itself never reaches a bundle. The tests import the runtime array: one test
+ * per code, and a source scan that fails on a code nothing emits.
+ */
+export declare const LOG_CODES: readonly ["unknown-config-key", "plan-cache-mode-ignored", "prepared-statements-on-pooler", "connection-option-ignored", "pool-error", "query-listener-error", "pool-listener-error", "replica-close-error", "external-pool", "pool-created", "replicas-configured", "pipeline", "raw-sql", "transaction-committed", "transaction-rolled-back", "listen", "notify", "connection-verified", "disconnect-skipped", "pool-disconnected", "typed-sql", "listen-reconnecting", "listen-lost", "parser-overwrite", "untyped-columns", "unordered-page", "auto-strategy", "deep-with", "flatten-blocked", "redundant-sort-term", "unknown-query-option", "unlimited-find-many", "temporal-infinity", "cache-mismatch", "stream-idle-timeout", "sql-comment-dropped", "relation-payload-json", "flatten-fallback", "unindexed-relation", "prisma-compat-unknown-option", "prisma-compat-native-spelling", "prisma-map-stale", "prisma-compat-junction-collision", "powdb-link-collision", "powdb-link-drift", "powdb-introspect-no-primary-key", "introspect-cross-schema-fk", "introspect-relation-renamed", "introspect-relation-shadows-json", "generate-relation-shadows-column"];
+/** A stable, machine-readable log line id. */
+export type TurbineLogCode = (typeof LOG_CODES)[number];

package/dist/log-codes.js

@@ -0,0 +1,74 @@
+/**
+ * turbine-orm, every `code` a Turbine log line can carry.
+ *
+ * A log line's TEXT is not a stable contract; its `code` is. This list is the
+ * whole set. Library code imports it as a TYPE only (see `TurbineLogCode` in
+ * logger.ts), so an emitter cannot use a code that is not here and the list
+ * itself never reaches a bundle. The tests import the runtime array: one test
+ * per code, and a source scan that fails on a code nothing emits.
+ */
+export const LOG_CODES = [
+    // client.ts, construction (always on)
+    'unknown-config-key',
+    'plan-cache-mode-ignored',
+    'prepared-statements-on-pooler',
+    'connection-option-ignored',
+    // client.ts, runtime errors
+    'pool-error',
+    'query-listener-error',
+    'pool-listener-error',
+    'replica-close-error',
+    // client.ts, `logging: true` lifecycle lines
+    'external-pool',
+    'pool-created',
+    'replicas-configured',
+    'pipeline',
+    'raw-sql',
+    'transaction-committed',
+    'transaction-rolled-back',
+    'listen',
+    'notify',
+    'connection-verified',
+    'disconnect-skipped',
+    'pool-disconnected',
+    // typed-sql.ts
+    'typed-sql',
+    // realtime.ts
+    'listen-reconnecting',
+    'listen-lost',
+    // query/utils.ts, a pg type parser replaced (client construction, always on)
+    'parser-overwrite',
+    // query/builder.ts, query/utils.ts, query/option-surface.ts: per-query advice
+    'untyped-columns',
+    'unordered-page',
+    'auto-strategy',
+    'deep-with',
+    'flatten-blocked',
+    'redundant-sort-term',
+    'unknown-query-option',
+    // query/builder.ts, always on
+    'unlimited-find-many',
+    'temporal-infinity',
+    'cache-mismatch',
+    'stream-idle-timeout',
+    // query/sql-comment.ts, always on (a sqlComment.dynamic value left out)
+    'sql-comment-dropped',
+    // query/relations.ts, per-query advice
+    'relation-payload-json',
+    'flatten-fallback',
+    'unindexed-relation',
+    // prisma-compat.ts
+    'prisma-compat-unknown-option',
+    'prisma-compat-native-spelling',
+    'prisma-map-stale',
+    'prisma-compat-junction-collision',
+    // powdb.ts, powdb-introspect.ts
+    'powdb-link-collision',
+    'powdb-link-drift',
+    'powdb-introspect-no-primary-key',
+    // introspect.ts, generate.ts
+    'introspect-cross-schema-fk',
+    'introspect-relation-renamed',
+    'introspect-relation-shadows-json',
+    'generate-relation-shadows-column',
+];

package/dist/logger.d.ts

@@ -0,0 +1,87 @@
+/**
+ * turbine-orm, the pluggable logger.
+ *
+ * Every line Turbine writes goes through a {@link TurbineLogger}: the client's
+ * `logger` option, or {@link consoleLogger} when none is set. Each line is a
+ * human message plus a {@link TurbineLogEntry} whose `code` is stable and
+ * machine-readable; the message text is not a stable contract.
+ *
+ * No log line carries a bound parameter value or a row value, whatever
+ * `logQueryParams` says: that option governs `$on('query')` events only. An
+ * entry about a where clause names its keys, never its values.
+ *
+ * This module and `seed.ts` (a CLI-driven runner) are the only library modules
+ * that call `console` directly; a source scan fails the build on another.
+ */
+import type { ResolvedDiagnostics } from './diagnostics.js';
+import type { TurbineLogCode } from './log-codes.js';
+export type { TurbineLogCode } from './log-codes.js';
+/** The structured half of a log line. */
+export interface TurbineLogEntry {
+    /** Stable, machine-readable id of the line, e.g. `'pool-error'`, `'unknown-config-key'`. */
+    code: string;
+    /** The table the line is about, when there is one. */
+    table?: string;
+    /** The operation the line is about (`'findMany'`, `'$transaction'`), when there is one. */
+    operation?: string;
+    /** The error the line reports, when it reports one. */
+    error?: unknown;
+    [field: string]: unknown;
+}
+/**
+ * Where Turbine's log lines go. Every method is optional, and a missing method
+ * drops that level, so `{}` silences Turbine entirely. The argument order,
+ * `(message, entry)`, matches `console` and winston; pino and bunyan take
+ * `(object, message)` and need a two-line adapter.
+ *
+ * A method that throws is ignored: logging never fails the operation that
+ * logged.
+ */
+export interface TurbineLogger {
+    debug?(message: string, entry: TurbineLogEntry): void;
+    info?(message: string, entry: TurbineLogEntry): void;
+    warn?(message: string, entry: TurbineLogEntry): void;
+    error?(message: string, entry: TurbineLogEntry): void;
+}
+/** One of the four {@link TurbineLogger} levels. */
+export type TurbineLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * The logger a client uses when `logger` is not set. `console` is looked up
+ * on every call, not captured, so anything that replaces `console.warn` (a
+ * test, an APM agent) sees Turbine's lines.
+ */
+export declare const consoleLogger: TurbineLogger;
+/**
+ * Validate the `logger` option: unset means {@link consoleLogger}; otherwise an
+ * object whose `debug` / `info` / `warn` / `error` members, where present, are
+ * functions. Other members are ignored, so a pino, winston or console object is
+ * accepted as it is. Throws `ValidationError` (E003) otherwise.
+ */
+export declare function resolveLogger(logger: unknown): TurbineLogger;
+/** An entry as Turbine's own emitters build it: the code is one of {@link TurbineLogCode}. */
+export interface InternalLogEntry extends TurbineLogEntry {
+    code: TurbineLogCode;
+}
+/**
+ * Send one line to `logger` at `level`. A logger without that level drops it;
+ * a logger that throws is ignored. Called as a method, so a class-based
+ * logger keeps its `this`.
+ *
+ * Callers build `message` only once they know the line is wanted (behind the
+ * `logging` flag, the advice gate, or the warn-once registry), so a silenced
+ * line costs nothing.
+ */
+export declare function logTo(logger: TurbineLogger, level: TurbineLogLevel, message: string, entry: InternalLogEntry): void;
+/**
+ * What a client hands to code that wraps it (prisma-compat) or runs on its
+ * behalf: its logger and its resolved diagnostics.
+ */
+export interface ClientLogContext {
+    readonly logger: TurbineLogger;
+    readonly diagnostics: ResolvedDiagnostics;
+}
+/**
+ * The key a `TurbineClient` exposes its {@link ClientLogContext} under.
+ * `Symbol.for`, so an ESM and a CJS copy of the package agree on it.
+ */
+export declare const CLIENT_LOG_CONTEXT: unique symbol;

package/dist/logger.js

@@ -0,0 +1,93 @@
+/**
+ * turbine-orm, the pluggable logger.
+ *
+ * Every line Turbine writes goes through a {@link TurbineLogger}: the client's
+ * `logger` option, or {@link consoleLogger} when none is set. Each line is a
+ * human message plus a {@link TurbineLogEntry} whose `code` is stable and
+ * machine-readable; the message text is not a stable contract.
+ *
+ * No log line carries a bound parameter value or a row value, whatever
+ * `logQueryParams` says: that option governs `$on('query')` events only. An
+ * entry about a where clause names its keys, never its values.
+ *
+ * This module and `seed.ts` (a CLI-driven runner) are the only library modules
+ * that call `console` directly; a source scan fails the build on another.
+ */
+import { ValidationError } from './errors.js';
+const LEVELS = ['debug', 'info', 'warn', 'error'];
+/**
+ * What the default logger prints for one line: `[turbine] <message>`, plus the
+ * entry's error as a second argument when the message ends with a colon. Such
+ * a message names a failure and the error completes it (`Query listener error:`
+ * followed by the error and its stack); every other message is complete on its
+ * own and already carries what it needs from the error.
+ */
+function consoleArgs(message, entry) {
+    // turbine-prefix-ok: this line only ever reaches the console.* calls in consoleLogger, never an Error.
+    const line = `[turbine] ${message}`;
+    return entry.error !== undefined && message.endsWith(':') ? [line, entry.error] : [line];
+}
+/**
+ * The logger a client uses when `logger` is not set. `console` is looked up
+ * on every call, not captured, so anything that replaces `console.warn` (a
+ * test, an APM agent) sees Turbine's lines.
+ */
+export const consoleLogger = Object.freeze({
+    debug(message, entry) {
+        console.log(...consoleArgs(message, entry));
+    },
+    info(message, entry) {
+        console.info(...consoleArgs(message, entry));
+    },
+    warn(message, entry) {
+        console.warn(...consoleArgs(message, entry));
+    },
+    error(message, entry) {
+        console.error(...consoleArgs(message, entry));
+    },
+});
+/**
+ * Validate the `logger` option: unset means {@link consoleLogger}; otherwise an
+ * object whose `debug` / `info` / `warn` / `error` members, where present, are
+ * functions. Other members are ignored, so a pino, winston or console object is
+ * accepted as it is. Throws `ValidationError` (E003) otherwise.
+ */
+export function resolveLogger(logger) {
+    if (logger === undefined)
+        return consoleLogger;
+    if ((typeof logger !== 'object' && typeof logger !== 'function') || logger === null || Array.isArray(logger)) {
+        throw new ValidationError(`Invalid logger option: expected an object with optional debug, info, warn and error methods, got ${logger === null ? 'null' : Array.isArray(logger) ? 'an array' : typeof logger}. Pass {} to silence Turbine, or leave the option unset for console.`);
+    }
+    for (const level of LEVELS) {
+        const member = logger[level];
+        if (member !== undefined && typeof member !== 'function') {
+            throw new ValidationError(`Invalid logger option: logger.${level} must be a function (message, entry) or absent, got ${typeof member}.`);
+        }
+    }
+    return logger;
+}
+/**
+ * Send one line to `logger` at `level`. A logger without that level drops it;
+ * a logger that throws is ignored. Called as a method, so a class-based
+ * logger keeps its `this`.
+ *
+ * Callers build `message` only once they know the line is wanted (behind the
+ * `logging` flag, the advice gate, or the warn-once registry), so a silenced
+ * line costs nothing.
+ */
+export function logTo(logger, level, message, entry) {
+    const method = logger[level];
+    if (typeof method !== 'function')
+        return;
+    try {
+        method.call(logger, message, entry);
+    }
+    catch {
+        // A logging failure must never become the caller's failure.
+    }
+}
+/**
+ * The key a `TurbineClient` exposes its {@link ClientLogContext} under.
+ * `Symbol.for`, so an ESM and a CJS copy of the package agree on it.
+ */
+export const CLIENT_LOG_CONTEXT = Symbol.for('turbine-orm.clientLogContext');