turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/utils.js

@@ -8,7 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JSON_WIRE_COERCION_OIDS = exports.OPERATOR_KEYS = exports.LRUCache = exports.INTERNAL_COMBINATOR = void 0;
+exports.JSON_WIRE_COERCION_OIDS = exports.OPERATOR_KEYS = exports.PREPARED_STATEMENT_BUDGET = exports.LRUCache = exports.INTERNAL_COMBINATOR = void 0;
 exports.quoteIdent = quoteIdent;
 exports.ownLookup = ownLookup;
 exports.resolveColumnName = resolveColumnName;
@@ -22,12 +22,23 @@ exports.escSingleQuote = escSingleQuote;
 exports.escapeLike = escapeLike;
 exports.fnv1a64Hex = fnv1a64Hex;
 exports.sqlToPreparedName = sqlToPreparedName;
+exports.boundedPreparedName = boundedPreparedName;
+exports.claimPreparedName = claimPreparedName;
+exports.resetPreparedNameBudget = resetPreparedNameBudget;
+exports.readOnlyMiddlewareParams = readOnlyMiddlewareParams;
+exports.assertMiddlewareArgsKept = assertMiddlewareArgsKept;
+exports.isNodePostgresPool = isNodePostgresPool;
+exports.canCancelBackend = canCancelBackend;
+exports.sendCancelRequest = sendCancelRequest;
 exports.buildCorrelation = buildCorrelation;
 exports.toTimeOfDayLiteral = toTimeOfDayLiteral;
 exports.toLocalDateTimeLiteral = toLocalDateTimeLiteral;
 exports.temporalBindKind = temporalBindKind;
 exports.coerceTemporalValue = coerceTemporalValue;
 exports.parseDbDate = parseDbDate;
+exports.readJsonFloat = readJsonFloat;
+exports.readJsonFloatArray = readJsonFloatArray;
+exports.readTextArray = readTextArray;
 exports.isTemporalInfinity = isTemporalInfinity;
 exports.createUtcDateParser = createUtcDateParser;
 exports.createUtcDateParserGeneral = createUtcDateParserGeneral;
@@ -53,6 +64,7 @@ exports.selectOmitExclusiveMessage = selectOmitExclusiveMessage;
 exports.normalizePagination = normalizePagination;
 const _pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("../errors.js");
+const logger_js_1 = require("../logger.js");
 const schema_js_1 = require("../schema.js");
 const warn_registry_js_1 = require("./warn-registry.js");
 // ---------------------------------------------------------------------------
@@ -307,9 +319,15 @@ function canonicalWriteEntries(meta, entries) {
  * where walker enumerates) never sees it and no emitted SQL can change.
  */
 exports.INTERNAL_COMBINATOR = Symbol.for('turbine.internalCombinator');
+/** Shared by every brand: a frozen descriptor saves an allocation per branded where. */
+const INTERNAL_COMBINATOR_DESCRIPTOR = Object.freeze({
+    value: true,
+    enumerable: false,
+    configurable: true,
+});
 /** Tag `where` as carrying a Turbine-synthesized combinator, and return it. */
 function markInternalCombinator(where) {
-    Object.defineProperty(where, exports.INTERNAL_COMBINATOR, { value: true, enumerable: false, configurable: true });
+    Object.defineProperty(where, exports.INTERNAL_COMBINATOR, INTERNAL_COMBINATOR_DESCRIPTOR);
     return where;
 }
 /** Was this WHERE object's combinator synthesized by Turbine? */
@@ -323,12 +341,17 @@ function isInternalCombinator(where) {
 function escSingleQuote(s) {
     return s.replace(/'/g, "''");
 }
+const LIKE_META = /[\\%_]/;
+const LIKE_META_G = /[\\%_]/g;
 /**
  * Escape LIKE pattern metacharacters: %, _, and \.
  * Must be used with `ESCAPE '\'` in the LIKE clause.
  */
 function escapeLike(value) {
-    return value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+    // One pass, and none at all for the common operand with no metacharacter.
+    // Identical output to escaping `\` then `%` then `_` in turn: the backslashes
+    // the first step adds are never `%` or `_`, so the steps never interact.
+    return LIKE_META.test(value) ? value.replace(LIKE_META_G, '\\$&') : value;
 }
 // ---------------------------------------------------------------------------
 // LRU cache, bounded SQL template cache to prevent memory leaks
@@ -415,6 +438,307 @@ function fnv1a64Hex(s) {
 function sqlToPreparedName(sql) {
     return `t_${fnv1a64Hex(sql)}`;
 }
+/**
+ * How many distinct statement names one process hands out. Every connection
+ * keeps each named statement it has prepared, at 9 to 45 KB of server memory
+ * apiece, until the connection closes, so the number of names is what bounds
+ * that memory. A statement past the budget is sent unnamed: parsed on every
+ * execution and never kept, which costs a few microseconds on a cheap query.
+ */
+exports.PREPARED_STATEMENT_BUDGET = 200;
+/** `Symbol.for` so the ESM and CJS copies of this module share one budget. */
+const PREPARED_NAMES = Symbol.for('turbine.preparedStatementNames');
+function preparedNames() {
+    const holder = globalThis;
+    let names = holder[PREPARED_NAMES];
+    if (!names) {
+        names = new Set();
+        holder[PREPARED_NAMES] = names;
+    }
+    return names;
+}
+/**
+ * The prepared-statement name for `sql`, or `''` (send it unnamed) once the
+ * process has named {@link PREPARED_STATEMENT_BUDGET} other statements.
+ *
+ * The first shapes a process runs keep their names for its lifetime, which in
+ * practice are its hot shapes. A server-side `DEALLOCATE` cannot replace this:
+ * a pooled query does not know which connection it will run on, and a
+ * connection keeps every name it ever prepared.
+ */
+function boundedPreparedName(sql) {
+    return claimPreparedName(sqlToPreparedName(sql));
+}
+/**
+ * Claim an already derived statement name from the same budget as
+ * {@link boundedPreparedName}: `name` itself, or `''` (send it unnamed) once
+ * the budget is spent. `sqlComment`'s `c_` names (query/sql-comment.ts) are
+ * claimed here, so a commented statement costs one slot like any other.
+ */
+function claimPreparedName(name) {
+    const names = preparedNames();
+    if (names.has(name))
+        return name;
+    if (names.size >= exports.PREPARED_STATEMENT_BUDGET)
+        return '';
+    names.add(name);
+    return name;
+}
+/** @internal Tests only: forget every name handed out. */
+function resetPreparedNameBudget() {
+    preparedNames().clear();
+}
+function argsRewriteError(model, action, path) {
+    return new TypeError(`[turbine] middleware cannot change \`params.${path}\` on ${model}.${action}: the query is compiled from the ` +
+        'arguments the caller passed, so a change made in middleware would not reliably reach it. Put the ' +
+        'condition in the query itself, or use `globalFilters` for a filter that applies to every query.');
+}
+/** Plain objects and arrays are copied; a Date, Buffer, class instance or other value is shared as it is. */
+function isPlainContainer(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Nesting past this is shared, not copied, so a cyclic object cannot recurse without end. */
+const MIDDLEWARE_ARGS_MAX_DEPTH = 100;
+/**
+ * A copy of `value` that middleware may read, spread, serialize or
+ * `structuredClone`: plain objects and arrays are copied at every depth, and
+ * everything else (Date, Buffer, bigint, symbol, class instance) is shared.
+ * Symbol-keyed properties are copied by descriptor, so the markers the
+ * pipeline reads (the internal-combinator brand, the inclusive-cursor flag,
+ * column and expression brands) are on the copy exactly as on the original,
+ * non-enumerable ones included.
+ */
+function copyArgs(value, depth) {
+    if (depth > MIDDLEWARE_ARGS_MAX_DEPTH || !isPlainContainer(value))
+        return value;
+    let out;
+    if (Array.isArray(value)) {
+        const items = new Array(value.length);
+        // A long list of ids is the common big argument; keep its scalars off the call path.
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            items[i] = item !== null && typeof item === 'object' ? copyArgs(item, depth + 1) : item;
+        }
+        out = items;
+    }
+    else {
+        out = Object.getPrototypeOf(value) === null ? Object.create(null) : {};
+        for (const key of Object.keys(value)) {
+            const item = value[key];
+            const copied = item !== null && typeof item === 'object' ? copyArgs(item, depth + 1) : item;
+            // `__proto__` from JSON.parse is an own key; assigning it would set the prototype.
+            if (key === '__proto__')
+                Object.defineProperty(out, key, { value: copied, enumerable: true, writable: true, configurable: true });
+            else
+                out[key] = copied;
+        }
+    }
+    for (const sym of Object.getOwnPropertySymbols(value)) {
+        Object.defineProperty(out, sym, Object.getOwnPropertyDescriptor(value, sym));
+    }
+    return out;
+}
+/**
+ * Where `b` first differs from `a`, as a path suffix (`.where.id`, or `''` for
+ * the values themselves), or undefined when they are structurally equal. The
+ * suffix is built on the way back out, so an equal pair costs no string work.
+ */
+function argsDifference(a, b, depth) {
+    if (Object.is(a, b))
+        return undefined;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object')
+        return '';
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && Object.is(a.getTime(), b.getTime()) ? undefined : '';
+    }
+    if (ArrayBuffer.isView(a) || ArrayBuffer.isView(b)) {
+        if (!(ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) || a.byteLength !== b.byteLength)
+            return '';
+        const x = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+        const y = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+        for (let i = 0; i < x.length; i++)
+            if (x[i] !== y[i])
+                return '';
+        return undefined;
+    }
+    if (a instanceof RegExp || b instanceof RegExp)
+        return String(a) === String(b) ? undefined : '';
+    if (a instanceof Map || a instanceof Set || b instanceof Map || b instanceof Set)
+        return '';
+    if (Array.isArray(a) !== Array.isArray(b) || depth > MIDDLEWARE_ARGS_MAX_DEPTH)
+        return '';
+    if (Array.isArray(a)) {
+        const other = b;
+        const shared = Math.min(a.length, other.length);
+        for (let i = 0; i < shared; i++) {
+            if (Object.is(a[i], other[i]))
+                continue;
+            const inner = argsDifference(a[i], other[i], depth + 1);
+            if (inner !== undefined)
+                return `.${i}${inner}`;
+        }
+        return a.length === other.length ? undefined : `.${shared}`;
+    }
+    const left = a;
+    const right = b;
+    for (const key of Object.keys(left)) {
+        if (!Object.hasOwn(right, key))
+            return `.${key}`;
+        const inner = argsDifference(left[key], right[key], depth + 1);
+        if (inner !== undefined)
+            return `.${key}${inner}`;
+    }
+    for (const key of Object.keys(right))
+        if (!Object.hasOwn(left, key))
+            return `.${key}`;
+    return undefined;
+}
+const MIDDLEWARE_ARGS = new WeakMap();
+/** The key Node's `util.inspect` looks for, from the global registry so no `node:` import is needed. */
+const NODE_INSPECT = Symbol.for('nodejs.util.inspect.custom');
+/** Makes `console.log(params)` show the values rather than an accessor. Not own, so a spread of `params` never carries it. */
+const MIDDLEWARE_PARAMS_PROTOTYPE = Object.defineProperty({}, NODE_INSPECT, {
+    value(_depth, options, inspect) {
+        return inspect({ model: this.model, action: this.action, args: this.args }, options);
+    },
+});
+/**
+ * The `params` a middleware receives. `params.args` is a plain copy of the
+ * caller's args, made when it is first read, so middleware can read it, spread
+ * it, serialize it and `structuredClone` it, and one that never reads it pays
+ * nothing.
+ *
+ * It is a copy because the query is compiled from the caller's args, not from
+ * what middleware sees. A change to the copy would never reach the query, so
+ * {@link assertMiddlewareArgsKept} refuses it, naming the path, when the
+ * middleware calls `next`. That check compares contents, which is why the copy
+ * is not frozen: a frozen object ignores a write silently in a script that is
+ * not in strict mode, and a filter added there would be dropped without a word.
+ * Assigning to `params.args` itself throws at once.
+ */
+function readOnlyMiddlewareParams(model, action, args) {
+    const state = { model, action, original: args, copy: undefined };
+    const params = {
+        __proto__: MIDDLEWARE_PARAMS_PROTOTYPE,
+        model,
+        action,
+        get args() {
+            if (state.copy === undefined)
+                state.copy = copyArgs(args, 0);
+            return state.copy;
+        },
+        set args(_replacement) {
+            throw argsRewriteError(model, action, 'args');
+        },
+    };
+    MIDDLEWARE_ARGS.set(params, state);
+    return params;
+}
+/**
+ * Refuse a `next(p)` whose `p.args` is not the caller's args: one that
+ * middleware changed in place, or replaced with an object that differs from
+ * them. A copy that is structurally equal passes (`structuredClone(params.args)`,
+ * `{ ...params.args }`), because nothing it would change is lost. Throws a
+ * TypeError naming the first path that differs.
+ */
+function assertMiddlewareArgsKept(handedOut, passed) {
+    const state = MIDDLEWARE_ARGS.get(handedOut);
+    if (passed === handedOut) {
+        if (handedOut.model !== state.model)
+            throw argsRewriteError(state.model, state.action, 'model');
+        if (handedOut.action !== state.action)
+            throw argsRewriteError(state.model, state.action, 'action');
+        // Nothing has read the args, so nothing could have changed them.
+        if (state.copy === undefined)
+            return;
+    }
+    const given = passed?.args;
+    if (given === state.original)
+        return;
+    const changed = argsDifference(state.original, given, 0);
+    if (changed !== undefined)
+        throw argsRewriteError(state.model, state.action, `args${changed}`);
+}
+/** Whether `pool` is a node-postgres `Pool`, whose checkouts are real backend connections. */
+function isNodePostgresPool(pool) {
+    const Pool = _pg_1.default.Pool;
+    return typeof Pool === 'function' && pool instanceof Pool;
+}
+/** Whether `client` is a node-postgres connection a cancel request can reach. */
+function canCancelBackend(client) {
+    const c = client;
+    return (typeof _pg_1.default.Connection === 'function' &&
+        !!c &&
+        typeof c.processID === 'number' &&
+        typeof c.secretKey === 'number' &&
+        (typeof c.port === 'number' || typeof c.port === 'string'));
+}
+/**
+ * Ask the server to cancel whatever `client`'s backend is running, with the
+ * protocol's CancelRequest: a separate short connection carrying the backend's
+ * process id and secret key. No login, no session state, and a pooler forwards
+ * it to the right server backend, which `pg_cancel_backend(pid)` through a
+ * pooler would not.
+ *
+ * Resolves `true` once the server has closed the cancel connection, i.e. has
+ * signalled the backend; `false` when the request could not be delivered
+ * within `waitMs`. A cancel that arrives after the statement finished is
+ * ignored by the server.
+ */
+function sendCancelRequest(client, waitMs) {
+    if (!canCancelBackend(client))
+        return Promise.resolve(false);
+    const target = client;
+    const Connection = _pg_1.default.Connection;
+    return new Promise((resolve) => {
+        let con;
+        let sent = false;
+        let done = false;
+        const finish = (delivered) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                con?.stream?.destroy?.();
+            }
+            catch {
+                // already closed
+            }
+            resolve(delivered);
+        };
+        const timer = setTimeout(() => finish(false), waitMs);
+        try {
+            con = new Connection({ ssl: target.ssl, sslNegotiation: target.sslNegotiation });
+            const send = () => {
+                sent = true;
+                con?.cancel(target.processID, target.secretKey);
+            };
+            con.on('error', () => finish(false));
+            con.on('end', () => finish(sent));
+            con.on('connect', () => {
+                if (!target.ssl)
+                    send();
+                else if (target.sslNegotiation !== 'direct')
+                    con?.requestSsl();
+            });
+            con.on('sslconnect', send);
+            const host = typeof target.host === 'string' ? target.host : undefined;
+            if (host?.startsWith('/'))
+                con.connect(`${host}/.s.PGSQL.${String(target.port)}`);
+            else
+                con.connect(target.port, host);
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
 /** Known operator keys, used to detect operator objects vs plain values */
 exports.OPERATOR_KEYS = new Set([
     'equals',
@@ -576,6 +900,12 @@ const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
  * as-is.
  */
 function parseDbDate(value) {
+    const date = parseDbDateCommon(value);
+    // The shapes JS cannot parse (a BC year, an offset with seconds, a year past
+    // 9999) come out invalid; only those pay for the general parse.
+    return Number.isNaN(date.getTime()) ? (parseDbDateGeneral(value) ?? date) : date;
+}
+function parseDbDateCommon(value) {
     // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
     // have no time to zone-pin, and their `-07` tail must not be read as an
     // offset. JS parses bare ISO dates as UTC midnight already.
@@ -590,6 +920,79 @@ function parseDbDate(value) {
     // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
     return new Date(`${value.replace(' ', 'T')}Z`);
 }
+const DB_DATE_GENERAL_RE = /^(\d{4,})-(\d\d)-(\d\d)(?:[T ](\d\d):(\d\d):(\d\d)(\.\d+)?)?(?:(Z)|([+-])(\d\d)(?::?(\d\d))?(?::?(\d\d))?)?( BC)?$/;
+/**
+ * The Postgres renderings JS `Date` cannot parse: a ` BC` suffix, a
+ * local-mean-time offset with seconds (`-04:56:02`, any zone before about
+ * 1900), and years of five or more digits. Offset-less text is read as UTC,
+ * as in {@link parseDbDate}. `undefined` when the text is none of these.
+ */
+function parseDbDateGeneral(value) {
+    const m = DB_DATE_GENERAL_RE.exec(value);
+    if (!m)
+        return undefined;
+    let year = Number(m[1]);
+    if (m[13])
+        year = 1 - year;
+    const month = Number(m[2]) - 1;
+    const ms = m[7] ? Math.trunc(1000 * Number(`0${m[7]}`)) : 0;
+    const date = new Date(Date.UTC(2000, month, Number(m[3]), Number(m[4] ?? 0), Number(m[5] ?? 0), Number(m[6] ?? 0), ms));
+    // setUTCFullYear, not Date.UTC: Date.UTC reads years 0-99 as 1900-1999.
+    date.setUTCFullYear(year, month, Number(m[3]));
+    if (m[9]) {
+        const offset = Number(m[10]) * 3600 + Number(m[11] ?? 0) * 60 + Number(m[12] ?? 0);
+        return new Date(date.getTime() - (m[9] === '-' ? -offset : offset) * 1000);
+    }
+    return date;
+}
+/**
+ * A float column's value as the driver reads it. JSON has no NaN or infinity,
+ * so `json_build_object` renders them as the strings "NaN", "Infinity" and
+ * "-Infinity"; every other value passes through.
+ */
+function readJsonFloat(value) {
+    if (typeof value !== 'string')
+        return value;
+    if (value === 'NaN')
+        return Number.NaN;
+    if (value === 'Infinity')
+        return Number.POSITIVE_INFINITY;
+    if (value === '-Infinity')
+        return Number.NEGATIVE_INFINITY;
+    return value;
+}
+/** {@link readJsonFloat} over a float array (at any depth); the input when nothing changes. */
+function readJsonFloatArray(value) {
+    if (!Array.isArray(value))
+        return value;
+    let out;
+    for (let i = 0; i < value.length; i++) {
+        const el = value[i];
+        const read = Array.isArray(el) ? readJsonFloatArray(el) : readJsonFloat(el);
+        if (read !== el) {
+            out ??= value.slice();
+            out[i] = read;
+        }
+    }
+    return out ?? value;
+}
+let textArrayParser;
+/**
+ * An array column the driver has no parser for (an enum array) arrives as
+ * Postgres array text, `{ok,sad}`; read it into an array of strings, as the
+ * same column reads through a relation. The input when it cannot be parsed.
+ */
+function readTextArray(value) {
+    if (typeof value !== 'string' || value.charCodeAt(0) !== 123)
+        return value;
+    try {
+        textArrayParser ??= createPgArrayParser((text) => text);
+        return textArrayParser(value) ?? value;
+    }
+    catch {
+        return value;
+    }
+}
 /**
  * Is `value` one of the two representations a Postgres temporal `infinity` /
  * `-infinity` reaches the ORM row parser in?
@@ -1128,7 +1531,7 @@ function isDefaultTextParser(oid, parser) {
  * construction, and only when somebody else's non-default parser is actually
  * being replaced.
  */
-function warnParserOverwrite(oid, typeName) {
+function warnParserOverwrite(oid, typeName, logger = logger_js_1.consoleLogger) {
     const getParser = _pg_1.default.types.getTypeParser;
     const current = getParser(oid, 'text');
     // Turbine's own earlier registration is not a third party's expectation.
@@ -1147,13 +1550,13 @@ function warnParserOverwrite(oid, typeName) {
     const remedy = TEMPORAL_PARSER_OIDS.has(oid)
         ? ' `utcTimestamps: false` leaves the six temporal OIDs (1114, 1082, 1115, 1182, 1184, 1185) alone entirely.'
         : ' There is no opt-out for this OID: Turbine registers it so bigint values come back as numbers.';
-    console.warn(`[turbine] pg type parser for OID ${oid} (${typeName}) was already customized by something else in this ` +
+    (0, logger_js_1.logTo)(logger, 'warn', `pg type parser for OID ${oid} (${typeName}) was already customized by something else in this ` +
         'process, and Turbine is replacing it. `pg.types.setTypeParser` is process-global and takes effect ' +
         'immediately for EVERY pg.Pool in the process, including pools that already exist and are already ' +
         'querying, so whatever set that parser will now read this column differently. If yours should win, ' +
         `register it AFTER constructing the client.${remedy} This warning fires under \`NODE_ENV=production\` ` +
         'too: which parser wins depends on module evaluation order, so a process can be clean in dev and wrong ' +
-        'in production from import order alone.');
+        'in production from import order alone.', { code: 'parser-overwrite', oid, type: typeName });
 }
 /**
  * Register Turbine's temporal text parsers on the pg module. SIX OIDs, doing
@@ -1189,16 +1592,16 @@ function warnParserOverwrite(oid, typeName) {
  * per row at decode time, not captured per pool). If any of the four OIDs is
  * already on a NON-default parser, {@link warnParserOverwrite} says so once.
  */
-function registerUtcTemporalParsers() {
+function registerUtcTemporalParsers(logger) {
     // pg-types declares get/setTypeParser over its own OID enum, which lists the
     // scalar types only. The array OIDs are just as real, so both calls are
     // retyped over a plain number rather than the incomplete enum.
     const getParser = _pg_1.default.types.getTypeParser;
     const setParser = _pg_1.default.types.setTypeParser;
-    warnParserOverwrite(1114, 'timestamp');
-    warnParserOverwrite(1082, 'date');
-    warnParserOverwrite(1115, 'timestamp[]');
-    warnParserOverwrite(1182, 'date[]');
+    warnParserOverwrite(1114, 'timestamp', logger);
+    warnParserOverwrite(1082, 'date', logger);
+    warnParserOverwrite(1115, 'timestamp[]', logger);
+    warnParserOverwrite(1182, 'date[]', logger);
     const parseDate = createUtcDateParser(getParser(1082, 'text'));
     const parseTimestamp = createUtcTimestampParser(getParser(1114, 'text'));
     setParser(1114, markTurbineParser(parseTimestamp));
@@ -1367,8 +1770,11 @@ function nameCloseness(input, candidate) {
     const b = candidate.toLowerCase();
     if (a === b)
         return 1000;
-    if (a.includes(b) || b.includes(a))
+    // Containment only between names of 3+ characters: `id` sits inside almost
+    // any name, so `tenentId` must reach `tenantId` by edit distance instead.
+    if (Math.min(a.length, b.length) >= 3 && (a.includes(b) || b.includes(a))) {
         return 500 + Math.min(a.length, b.length);
+    }
     // Levenshtein, bounded: only near-misses are worth suggesting.
     const rows = a.length + 1;
     const cols = b.length + 1;
@@ -1508,7 +1914,7 @@ function relationInProjectionMessage(table, field, clause) {
             ' out of the result.';
 }
 /**
- * Dev-only advisory for a sort/grouping term Turbine dropped as redundant
+ * Advice (`diagnostics.advice`) for a sort/grouping term Turbine dropped as redundant
  * (`filters.ts` `dedupeOrderEntries` / `dedupeColumnList`).
  *
  * Deliberately a WARNING and not an error, and deliberately not silent either.
@@ -1517,15 +1923,16 @@ function relationInProjectionMessage(table, field, clause) {
  * plus an unconditional primary-key tiebreak, which collide exactly when the
  * caller sorts by the primary key). But a caller who wrote the duplicate by
  * hand, or who believes a second key is doing something, should hear about it
- * once. Dev-only for the usual reason: it describes the QUERY the application
+ * once. Advice for the usual reason: it describes the QUERY the application
  * sends, which does not vary with the environment, so a production process
- * learns nothing from repeating it.
+ * learns nothing from repeating it. The caller passes its advice logger, or
+ * `undefined` when advice is off.
  *
  * Keyed per dropped key, so a sort assembled per request from the same UI says
  * it once rather than once per request.
  */
-function warnRedundantSortTerm(table, clause, dropped) {
-    if (process.env.NODE_ENV === 'production')
+function warnRedundantSortTerm(advice, table, clause, dropped) {
+    if (!advice)
         return;
     for (const d of dropped) {
         if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.redundantSortTerm, `${table}|${clause}|${d.key}`))
@@ -1533,9 +1940,9 @@ function warnRedundantSortTerm(table, clause, dropped) {
         const how = d.first === d.key
             ? `"${d.key}" is named twice`
             : `"${d.key}" and the earlier "${d.first}" both target ${d.resolved}`;
-        console.warn(`[turbine] ${clause} on table "${table}": ${how}, so the later one was dropped. It could not have ` +
+        (0, logger_js_1.logTo)(advice, 'warn', `${clause} on table "${table}": ${how}, so the later one was dropped. It could not have ` +
             'changed the result (the earlier term already orders those rows), and dropping it keeps the query on ' +
-            'a shared prepared statement. Remove it to silence this.');
+            'a shared prepared statement. Remove it to silence this.', { code: 'redundant-sort-term', table, clause, key: d.key });
     }
 }
 /**

package/dist/cjs/query/warn-registry.d.ts

@@ -127,6 +127,17 @@ export declare const WARN_NS: {
      * Keyed on the requested mode.
      */
     readonly planCacheModeIgnored: "planCacheModeIgnored";
+    /**
+     * `statementTimeoutMs` or `maxLifetimeSeconds` was set on a client given an
+     * EXTERNAL pool, whose connections Turbine never opens (client.ts
+     * `warnExternalPoolOptions`). Keyed on the option name.
+     */
+    readonly connectionOptionIgnored: "connectionOptionIgnored";
+    /**
+     * `preparedStatements: true` on a connection string that names a connection
+     * pooler (client.ts `warnPreparedOnPooler`). Keyed on `host:port`.
+     */
+    readonly preparedStatementsOnPooler: "preparedStatementsOnPooler";
     /**
      * A relation's JSON payload could not be parsed in `parseNestedRow`
      * (relations.ts). Keyed on `table.relation`, so a page of 10,000 rows whose
@@ -134,4 +145,11 @@ export declare const WARN_NS: {
      * warn sits in the per-relation loop, which runs once per row per relation.
      */
     readonly relationParseFailure: "relationParseFailure";
+    /**
+     * `findMany` with no row limit (builder.ts `maybeWarnUnlimited`, powql.ts).
+     * Keyed on the table and process-wide: every `$transaction` builds its own
+     * query interfaces, so a dedupe held on the interface said it again in
+     * every transaction.
+     */
+    readonly unlimitedFindMany: "unlimitedFindMany";
 };

package/dist/cjs/query/warn-registry.js

@@ -168,6 +168,17 @@ exports.WARN_NS = {
      * Keyed on the requested mode.
      */
     planCacheModeIgnored: 'planCacheModeIgnored',
+    /**
+     * `statementTimeoutMs` or `maxLifetimeSeconds` was set on a client given an
+     * EXTERNAL pool, whose connections Turbine never opens (client.ts
+     * `warnExternalPoolOptions`). Keyed on the option name.
+     */
+    connectionOptionIgnored: 'connectionOptionIgnored',
+    /**
+     * `preparedStatements: true` on a connection string that names a connection
+     * pooler (client.ts `warnPreparedOnPooler`). Keyed on `host:port`.
+     */
+    preparedStatementsOnPooler: 'preparedStatementsOnPooler',
     /**
      * A relation's JSON payload could not be parsed in `parseNestedRow`
      * (relations.ts). Keyed on `table.relation`, so a page of 10,000 rows whose
@@ -175,4 +186,11 @@ exports.WARN_NS = {
      * warn sits in the per-relation loop, which runs once per row per relation.
      */
     relationParseFailure: 'relationParseFailure',
+    /**
+     * `findMany` with no row limit (builder.ts `maybeWarnUnlimited`, powql.ts).
+     * Keyed on the table and process-wide: every `$transaction` builds its own
+     * query interfaces, so a dedupe held on the interface said it again in
+     * every transaction.
+     */
+    unlimitedFindMany: 'unlimitedFindMany',
 };