turbine-orm 0.52.0 → 0.53.0

package/dist/cjs/client.js

@@ -35,6 +35,7 @@ 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 warn_registry_js_1 = require("./query/warn-registry.js");
 const realtime_js_1 = require("./realtime.js");
 const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
@@ -61,6 +62,154 @@ async function withRetry(fn, options) {
     }
     throw lastError;
 }
+// ---------------------------------------------------------------------------
+// Unknown-config-key diagnostics
+// ---------------------------------------------------------------------------
+/**
+ * Every `TurbineConfig` key, as runtime data. TypeScript erases the interface,
+ * so the key set has to exist as a value; `Record<keyof TurbineConfig, true>`
+ * makes the compiler own it in BOTH directions: a field added to the interface
+ * fails typecheck until it is listed here, and a key listed here that is not a
+ * field fails as an excess property. So this can never drift into warning about
+ * a real option.
+ */
+const TURBINE_CONFIG_KEYS = {
+    pool: true,
+    connectionString: true,
+    host: true,
+    port: true,
+    database: true,
+    user: true,
+    password: true,
+    ssl: true,
+    poolSize: true,
+    idleTimeoutMs: true,
+    connectionTimeoutMs: true,
+    max: true,
+    idleTimeoutMillis: true,
+    connectionTimeoutMillis: true,
+    logging: true,
+    defaultLimit: true,
+    warnOnUnlimited: true,
+    utcTimestamps: true,
+    scopedConnect: true,
+    relationLoadStrategy: true,
+    stableRelationOrder: true,
+    implicitPkOrdering: true,
+    autoToOneJoinMaxRows: true,
+    autoRoundTripMs: true,
+    jsonEncoding: true,
+    errorMessages: true,
+    logQueryParams: true,
+    preparedStatements: true,
+    sqlCache: true,
+    sqlCacheSize: true,
+    dialect: true,
+    replicas: true,
+    globalFilters: true,
+};
+/**
+ * {@link TURBINE_CONFIG_KEYS} as a lookup. A `Set` rather than an `in` test on
+ * the record, so an inherited `Object.prototype` name (`toString`, `constructor`)
+ * is treated as the unknown key it is.
+ */
+const CONFIG_KEY_SET = new Set(Object.keys(TURBINE_CONFIG_KEYS));
+/**
+ * Keys that are legitimately present on a config object but are not public
+ * `TurbineConfig` fields:
+ *
+ *   - `queryInterfaceFactory`: the non-SQL-backend seam. `turbinePowDB` sets it
+ *     through a cast so `table()` builds a `PowqlInterface`; it is `@internal`,
+ *     deliberately absent from the public interface, and must not warn.
+ *   - `schema`: `turbine.config.*` files carry a Postgres schema NAME for the
+ *     CLI, and that same object is routinely spread into the client factory.
+ *     The client ignores it (its schema metadata is the second argument), and
+ *     shouting about a documented CLI field would be pure noise.
+ *   - `url`: the connection-string spelling used by the CLI config and by the
+ *     engine factories' first argument. Same story as `schema`.
+ */
+const NON_CONFIG_KEYS = new Set(['queryInterfaceFactory', 'schema', 'url']);
+/** camelCase name → its lowercased words (`logQueryParams` → log, query, params). */
+function camelWords(name) {
+    return name
+        .split(/(?=[A-Z])/)
+        .map((w) => w.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * The real config key `key` most likely meant, or null when nothing is close.
+ *
+ * {@link closestName} (the same helper the unknown-COLUMN message uses) decides
+ * first, so both diagnostics rank near-misses identically. It is bounded by edit
+ * distance, which covers typos but not the miss this warning exists for: a
+ * guessed name that omits a whole word. `logParams` is five edits from
+ * `logQueryParams`, past the bound, yet it names the same words in the same
+ * order, so a second pass accepts a candidate whose camelCase words CONTAIN the
+ * guess's words in order, preferring the one that adds fewest words.
+ */
+function suggestConfigKey(key) {
+    const direct = (0, utils_js_1.closestName)(key, CONFIG_KEY_SET);
+    if (direct)
+        return direct;
+    const wanted = camelWords(key);
+    if (wanted.length < 2)
+        return null;
+    let best = null;
+    let bestExtra = Number.POSITIVE_INFINITY;
+    for (const candidate of CONFIG_KEY_SET) {
+        const words = camelWords(candidate);
+        if (words.length <= wanted.length)
+            continue;
+        let i = 0;
+        for (const w of words)
+            if (w === wanted[i])
+                i++;
+        if (i !== wanted.length)
+            continue;
+        const extra = words.length - wanted.length;
+        if (extra < bestExtra) {
+            bestExtra = extra;
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * Dev-mode notice for a key on the config object that is not part of the config
+ * surface.
+ *
+ * An unknown key is silently ignored (JavaScript objects have no schema), which
+ * makes a typo or a wrong guess indistinguishable from a broken feature: a
+ * caller who wants query parameters in `$on('query')` events and reaches for a
+ * plausible-sounding `logParams` sees nothing happen and concludes the feature
+ * does not work, rather than that the option is spelled `logQueryParams`.
+ *
+ * Deliberately a warning, never an error. An app compiled against a NEWER
+ * turbine that passes a key this version has not heard of must keep running,
+ * and the whole check is wrapped so that a hostile / exotic config object
+ * (a Proxy whose `ownKeys` throws) cannot take down the constructor either.
+ * Dev-only (`NODE_ENV !== 'production'`) and once per key per process, like the
+ * other advisory diagnostics.
+ */
+function warnUnknownConfigKeys(config) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    try {
+        for (const key of Object.keys(config)) {
+            if (CONFIG_KEY_SET.has(key) || NON_CONFIG_KEYS.has(key))
+                continue;
+            if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.unknownConfigKey, key))
+                continue;
+            const suggestion = suggestConfigKey(key);
+            console.warn(`[turbine] Unknown option "${key}" in the config passed to TurbineClient, it is ignored.` +
+                (suggestion ? ` Did you mean "${suggestion}"?` : ''));
+        }
+    }
+    catch {
+        // Key enumeration is the only thing that can fail here, and a diagnostic
+        // must never be the reason a client fails to construct.
+    }
+}
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',
@@ -386,6 +535,9 @@ class TurbineClient {
             }
             break;
         }
+        // Name any key on the config object that is not part of the config surface
+        // (dev only, once per key, never throws). See warnUnknownConfigKeys.
+        warnUnknownConfigKeys(config);
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).

package/dist/cjs/nested-write.js

@@ -20,6 +20,7 @@ exports.createManyShapeRuns = createManyShapeRuns;
 exports.executeNestedCreate = executeNestedCreate;
 exports.executeNestedUpdate = executeNestedUpdate;
 const errors_js_1 = require("./errors.js");
+const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
@@ -83,10 +84,50 @@ function injectForeignKey(childData, relation, parentRow, schema) {
         const refCol = refs[i];
         const refField = schema.tables[relation.from]?.reverseColumnMap[refCol] ?? refCol;
         const fkField = childTable?.reverseColumnMap[fkCol] ?? fkCol;
-        result[fkField] = parentRow[refField];
+        assignByColumn(result, childTable, fkField, parentRow[refField]);
     }
     return result;
 }
+/**
+ * Set `field` on `target`, first dropping any OTHER key that names the SAME
+ * column.
+ *
+ * The engine always writes the canonical FIELD spelling, while a caller's own
+ * `data` may legally spell the same column its snake_case way (the write
+ * builders resolve both). Overwriting only the identical key left both in the
+ * object, and the INSERT/UPDATE then named one column twice, which PostgreSQL
+ * refuses (42701 "specified more than once"). Dropping the alias makes the
+ * column spelling behave exactly as the field spelling always did: the value the
+ * relation dictates wins.
+ *
+ * Only SCALAR keys are droppable. A relation is resolved to a column by the very
+ * same rule (nothing stops a schema from naming a relation the way a column is
+ * spelled), but a relation key carries a nested write rather than a value, so
+ * dropping it would discard the whole operation silently, a strictly worse
+ * outcome than the duplicate-column error this drop exists to prevent. The
+ * relation-shape test matches {@link splitData}, so a key routed to `relations`
+ * there is never treated as an alias here.
+ */
+function assignByColumn(target, meta, field, value) {
+    const column = meta && (0, utils_js_1.resolveColumnName)(meta, field);
+    if (column) {
+        for (const key of Object.keys(target)) {
+            if (key === field || isRelationEntry(meta, key, target[key]))
+                continue;
+            if ((0, utils_js_1.resolveColumnName)(meta, key) === column)
+                delete target[key];
+        }
+    }
+    target[field] = value;
+}
+/** Does `key` name a relation on `meta` AND carry a nested-write payload? */
+function isRelationEntry(meta, key, value) {
+    return (Object.hasOwn(meta.relations, key) &&
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
 /**
  * Split rows destined for `createMany` into CONTIGUOUS runs that each name the
  * same fields.
@@ -749,10 +790,15 @@ async function executeNestedCreate(ctx, tableName, data, depth = 0, path = []) {
             assertManyToManyOpsSupported(relName, rel, ops);
         }
     }
-    // Insert the parent row (scalars + resolved belongsTo foreign keys)
-    const parentRow = (await ctx.tx.table(tableName).create({
-        data: { ...scalars, ...belongsToFks },
-    }));
+    // Insert the parent row (scalars + resolved belongsTo foreign keys). The
+    // resolved keys win over a caller-supplied value for the same column under
+    // either spelling (see assignByColumn), so `{ authorId: 1, author: { connect } }`
+    // and `{ author_id: 1, author: { connect } }` both take the connected row.
+    const parentData = { ...scalars };
+    for (const [field, value] of Object.entries(belongsToFks)) {
+        assignByColumn(parentData, tableMeta, field, value);
+    }
+    const parentRow = (await ctx.tx.table(tableName).create({ data: parentData }));
     // Process hasMany / hasOne relations, their FK lives on the CHILD, so they
     // need the parent row to exist first.
     for (const [relName, ops] of Object.entries(relations)) {

package/dist/cjs/prisma-compat.d.ts

@@ -37,7 +37,15 @@
  * These cannot be faithfully translated and are not attempted; each throws or is
  * documented rather than silently returning wrong data:
  *
- * - `$extends` / client extensions, `$use` with Prisma's middleware param shape.
+ * - **`$extends` beyond `client` + `model`.** Client extensions ARE supported for
+ *   those two components (plus the `Prisma.defineExtension` callback form), and
+ *   return a new client whose delegates, `$transaction` and raw surface all
+ *   survive. The `query` (interception) and `result` (computed fields)
+ *   components, and any component this adapter does not recognize, throw an
+ *   {@link UnsupportedFeatureError} naming the component AT `$extends` TIME
+ *   rather than being accepted and quietly not applied.
+ * - `$use` with Prisma's middleware param shape (Turbine's own `client.$use` is
+ *   the supported interception seam).
  * - `instanceof PrismaClientKnownRequestError`, `.meta`/message byte parity
  *   (opt into `prismaErrorCodes` for a `.code` like `P2002`, without pretending
  *   `instanceof` identity).
@@ -197,6 +205,19 @@ export declare const Prisma: {
     raw(sql: string): Sql;
     /** An empty fragment. */
     empty: Sql;
+    /**
+     * The extension context of `this` inside a client / model extension method.
+     * Turbine binds extension members directly onto the client and delegate
+     * objects, so the context IS `this`; the identity function exists so migrated
+     * `Prisma.getExtensionContext(this).$name` call sites keep working.
+     */
+    getExtensionContext<T>(that: T): T;
+    /**
+     * Type-preserving passthrough for `Prisma.defineExtension(ext)`. Prisma uses
+     * it purely for inference; the value is returned unchanged, so both the object
+     * and the callback form reach `$extends` intact.
+     */
+    defineExtension<E>(ext: E): E;
 };
 /** Options for {@link createPrismaCompatClient}. */
 export interface PrismaCompatOptions {
@@ -269,12 +290,69 @@ export interface PrismaCompatRawSurface {
     $executeRaw(strings: TemplateStringsArray, ...values: unknown[]): Promise<number>;
     $executeRawUnsafe(sql: string, ...params: unknown[]): Promise<number>;
 }
-/** The client-level surface (`$transaction` / raw), added to the model map. */
+/**
+ * A Prisma client extension, restricted to the two components this adapter can
+ * honour faithfully.
+ *
+ * `client` members land on the returned client; `model` members land on the
+ * named model's delegate (under BOTH spellings), with `$allModels` applying to
+ * every delegate. The `query` and `result` components are declared `never` so
+ * passing one is a compile error, and {@link PrismaCompatClient.$extends} also
+ * refuses them at runtime with an {@link UnsupportedFeatureError} naming the
+ * component: an extension that was accepted and then quietly not applied would
+ * be far worse than one that is refused.
+ */
+export interface PrismaCompatExtension {
+    /** Optional extension name, accepted and otherwise unused (as in Prisma). */
+    name?: string;
+    /** Extra client-level members, e.g. `{ $healthCheck() { … } }`. */
+    client?: Record<string, unknown>;
+    /** Extra delegate members per Prisma model name, plus `$allModels`. */
+    model?: Record<string, Record<string, unknown>>;
+    /** Not supported, see {@link PrismaCompatExtension}. */
+    query?: never;
+    /** Not supported, see {@link PrismaCompatExtension}. */
+    result?: never;
+    /** Any other component is refused at runtime by name. */
+    [component: string]: unknown;
+}
+/** Members an extension contributes to the delegate for Prisma model `K`. */
+type ModelMembersOf<M, K extends string> = (K extends keyof M ? M[K] : unknown) & (Uncapitalize<K> extends keyof M ? M[Uncapitalize<K>] : unknown) & ('$allModels' extends keyof M ? M['$allModels'] : unknown);
+type ExtraModelMembers<E, K extends string> = E extends {
+    model: infer M;
+} ? ModelMembersOf<M, K> : unknown;
+/**
+ * The client {@link PrismaCompatClient.$extends} returns: the same surface with
+ * the extension's `client` members on the client and its `model` members on
+ * every matching delegate (both spellings).
+ */
+export type PrismaCompatExtendedClient<S extends Record<string, PrismaModelTypes>, E> = {
+    [K in keyof S]: PrismaModelDelegate<S[K]> & ExtraModelMembers<E, K & string>;
+} & {
+    [K in keyof S as Uncapitalize<K & string>]: PrismaModelDelegate<S[K]> & ExtraModelMembers<E, K & string>;
+} & PrismaCompatClientBase<S> & (E extends {
+    client: infer C;
+} ? C : unknown);
+/** The client-level surface (`$transaction` / raw / `$extends`), added to the model map. */
 export interface PrismaCompatClientBase<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> extends PrismaCompatRawSurface {
     $transaction<R>(fn: (tx: PrismaCompatTransactionClient<S>) => Promise<R>, options?: PrismaCompatTxOptions): Promise<R>;
     $transaction<P extends readonly PromiseLike<unknown>[]>(promises: readonly [...P]): Promise<{
         [K in keyof P]: Awaited<P[K]>;
     }>;
+    /**
+     * Prisma's callback form (`Prisma.defineExtension((client) => …)`): the
+     * function is called with this client and its return value is the result,
+     * exactly as in Prisma. Declared first so a function argument never matches
+     * the all-optional object overload below.
+     */
+    $extends<R>(extension: (client: PrismaCompatClient<S>) => R): R;
+    /**
+     * Extend the client with a {@link PrismaCompatExtension}. Returns a NEW client
+     * (this one is untouched) carrying the extension's `client` and `model`
+     * members; the returned client is itself extendable. `query` and `result`
+     * extensions throw, see {@link PrismaCompatExtension}.
+     */
+    $extends<E extends PrismaCompatExtension>(extension: E): PrismaCompatExtendedClient<S, E>;
     $connect(): Promise<void>;
     $disconnect(): Promise<void>;
 }