turbine-orm 0.81.0 → 0.90.0

package/dist/query/row-lock.js

@@ -0,0 +1,131 @@
+/**
+ * turbine-orm: the `lock` read option (`SELECT ... FOR UPDATE OF "t"`).
+ *
+ * {@link resolveRowLock} is the one place a `lock` value is validated and
+ * rendered. The SQL build and the cache key both read its result, so the two
+ * cannot disagree about which lock a statement carries.
+ *
+ * The clause always names the queried table (`OF "t"`). That keeps the lock on
+ * the returned rows of that table and nothing else, on every relation
+ * strategy: correlated `with` subqueries are never locked anyway, and without
+ * `OF` PostgreSQL refuses the `flatten` and lateral-pick plans (their outer
+ * joins would put a table on the nullable side of the lock).
+ */
+import { UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { tableAccessorName } from '../global-filters-config.js';
+import { suggestKey } from './utils.js';
+const MODES = ['update', 'noKeyUpdate', 'share', 'keyShare'];
+const MODE_SQL = {
+    update: 'UPDATE',
+    noKeyUpdate: 'NO KEY UPDATE',
+    share: 'SHARE',
+    keyShare: 'KEY SHARE',
+};
+/** One letter per mode for the SQL-template cache key. */
+const MODE_FP = { update: 'u', noKeyUpdate: 'n', share: 's', keyShare: 'k' };
+const LOCK_KEYS = ['mode', 'noWait', 'skipLocked'];
+/** Why an engine refuses a lock mode, keyed by dialect name. */
+const ENGINE_HINT = {
+    sqlite: 'SQLite has no row locks: a write transaction locks the whole database. Remove `lock`; inside ' +
+        '$transaction on SQLite, writes are already serialized.',
+    mysql: "MySQL supports lock: 'update' and lock: 'share' only. Use 'update' (stronger) or 'share' (weaker).",
+    mssql: "Row locks are not available on SQL Server in this release. Use $transaction({ isolationLevel: 'RepeatableRead' }) " +
+        'or a raw query with table hints.',
+    powdb: 'PowDB has no row locks: a transaction holds the single writer gate.',
+};
+/**
+ * Validate `lock` for a read on `table` and render its clause.
+ *
+ * `undefined` means no lock. Anything that is not a mode string or a
+ * `{ mode, noWait?, skipLocked? }` object is `ValidationError` (E003), and so
+ * is asking for both wait policies at once. A mode the dialect does not list in
+ * {@link Dialect.rowLockModes} is `UnsupportedFeatureError` (E017).
+ */
+export function resolveRowLock(lock, dialect, table) {
+    if (lock === undefined)
+        return undefined;
+    let mode;
+    let noWait;
+    let skipLocked;
+    if (typeof lock === 'string') {
+        mode = lock;
+    }
+    else if (typeof lock === 'object' && lock !== null && !Array.isArray(lock)) {
+        for (const key of Object.keys(lock)) {
+            if (!LOCK_KEYS.includes(key)) {
+                const hint = suggestKey(key, LOCK_KEYS);
+                throw new ValidationError(`lock on "${table}": unknown key "${key}".${hint ? ` Did you mean "${hint}"?` : ''} ` +
+                    'A lock is a mode, or { mode, noWait: true } or { mode, skipLocked: true }.');
+            }
+        }
+        ({ mode, noWait, skipLocked } = lock);
+        assertFlag(noWait, 'noWait', table);
+        assertFlag(skipLocked, 'skipLocked', table);
+        if (noWait === true && skipLocked === true) {
+            throw new ValidationError(`lock on "${table}": noWait and skipLocked cannot be combined. noWait fails at once when a row is ` +
+                'locked by another transaction; skipLocked leaves that row out of the result. Pick one.');
+        }
+    }
+    else {
+        throw new ValidationError(`lock on "${table}" must be a mode ('update', 'noKeyUpdate', 'share' or 'keyShare') or ` +
+            `{ mode, noWait?, skipLocked? }, received ${describe(lock)}. Leave it out for an unlocked read.`);
+    }
+    if (typeof mode !== 'string' || !MODES.includes(mode)) {
+        const hint = typeof mode === 'string' ? suggestKey(mode, MODES) : null;
+        throw new ValidationError(`lock on "${table}": unknown mode ${describe(mode)}.${hint ? ` Did you mean '${hint}'?` : ''} ` +
+            "Use 'update', 'noKeyUpdate', 'share' or 'keyShare'.");
+    }
+    const m = mode;
+    if (!(dialect.rowLockModes ?? []).includes(m)) {
+        throw new UnsupportedFeatureError(`lock: '${m}'`, dialect.name, ENGINE_HINT[dialect.name] ?? 'This engine has no row-locking clause Turbine can emit.');
+    }
+    const wait = noWait === true ? ' NOWAIT' : skipLocked === true ? ' SKIP LOCKED' : '';
+    return {
+        sql: ` FOR ${MODE_SQL[m]} OF ${dialect.quoteIdentifier(table)}${wait}`,
+        fp: `${MODE_FP[m]}${noWait === true ? '.nw' : skipLocked === true ? '.sl' : ''}`,
+    };
+}
+/**
+ * The refusal for a locking read outside a transaction. In autocommit the lock
+ * is released when the statement ends, before the caller sees the rows, so a
+ * `skipLocked` queue claim outside a transaction claims nothing, silently.
+ */
+export function lockOutsideTransactionMessage(table, operation) {
+    return (`lock on "${table}".${operation}() needs a transaction: outside one the rows are unlocked again before ` +
+        `the call returns. Use db.$transaction(async (tx) => tx.${tableAccessorName(table)}.${operation}({ ..., lock })).`);
+}
+/** The refusal for `lock` on a streaming read. */
+export function lockOnStreamMessage(table, operation) {
+    return (`lock is not supported on "${table}".${operation}(): a stream is not a locking read. Page with ` +
+        'findMany({ lock, limit }) inside the transaction instead.');
+}
+/** The refusal for `lock` together with `distinct`. */
+export function lockWithDistinctMessage(table) {
+    return (`lock on "${table}" cannot be combined with distinct: PostgreSQL does not lock rows of a DISTINCT query. ` +
+        'Lock first (findMany with lock), then de-duplicate.');
+}
+/**
+ * Refuse a locking read in a pipeline that runs each statement in autocommit
+ * (`pipeline(..., { transactional: false })`). A transactional pipeline, and
+ * `$transaction([...])`, keep the lock for the rest of the batch.
+ */
+export function assertNoLockInAutocommitPipeline(queries) {
+    const at = queries.findIndex((q) => q.rowLock === true);
+    if (at === -1)
+        return;
+    throw new ValidationError(`pipeline query ${at} (${queries[at]?.tag ?? 'a read'}) is a locking read, and { transactional: false } runs ` +
+        'it in autocommit, which releases the lock before the call returns. Drop transactional: false, or run the ' +
+        'batch with db.$transaction([...]).');
+}
+function assertFlag(value, name, table) {
+    if (value === undefined || typeof value === 'boolean')
+        return;
+    throw new ValidationError(`lock on "${table}": ${name} must be true or false, received ${describe(value)}.`);
+}
+function describe(value) {
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (value === null || typeof value !== 'object')
+        return String(value);
+    return Array.isArray(value) ? 'an array' : 'an object';
+}

package/dist/query/sql-comment.d.ts

@@ -0,0 +1,161 @@
+/**
+ * turbine-orm: `sqlComment`, sqlcommenter-style key/values on each statement
+ * Turbine builds, so `pg_stat_activity`, the server log, `auto_explain` and
+ * database APM tools can attribute a statement to a service, a model, a feature
+ * or a trace.
+ *
+ *   SELECT ... LIMIT $2 /*action='findMany',application='billing',model='users'*\/
+ *
+ * FORMAT (the sqlcommenter spec): keys sorted, each value URL-encoded with
+ * `encodeURIComponent` and then `'` escaped as `\'`, each pair `key='value'`,
+ * pairs joined by commas, the whole comment appended after the statement with
+ * one space before it.
+ *
+ * WHY A VALUE CANNOT ESCAPE THE COMMENT. `encodeURIComponent` encodes `/`, so a
+ * value can hold neither `*\/` (the comment's end) nor `/*` (PostgreSQL and SQL
+ * Server nest block comments, so an opener would swallow the rest of the
+ * text). It also encodes every character a driver-side placeholder rewrite
+ * looks for (`$`, `?`, `:`, `@`) and `;`. Keys must match
+ * {@link SQL_COMMENT_KEY_PATTERN}, whose first-character rule also rules out
+ * MySQL's executable `/*!` and optimizer-hint `/*+` comments.
+ *
+ * WHERE IT IS APPENDED: at the execute seam, AFTER the SQL-template cache. The
+ * cache stores commentless text, so its keys, its hit rate and the lockstep
+ * checks are untouched by any comment, and a per-request value can never grow
+ * it. `$on('query')` events keep `sql` commentless and carry the comment in
+ * their own field.
+ *
+ * PREPARED-STATEMENT NAMES. node-postgres refuses to reuse a statement name for
+ * different text on one connection, and every name a connection prepares stays
+ * on the server until the connection closes. So:
+ *
+ *   - no comment: the template's own name, as before;
+ *   - static, model, action and tag only (constant per call site and label):
+ *     `c_<16 hex>`, a hash of the template name and the comment, claimed from
+ *     the same process-wide budget as every other name
+ *     (`PREPARED_STATEMENT_BUDGET`), so the server-side cost stays bounded
+ *     however many labels there are;
+ *   - any dynamic value (a trace id, unique per request): unnamed, parsed on
+ *     every execution and never kept. A per-request value under a name would
+ *     prepare a new statement on every pooled connection for every request.
+ *
+ * Leaf apart from errors.ts, logger.ts, query-events.ts (the `$tag` scope) and
+ * utils.ts (the name budget); nothing here is Node-only.
+ */
+import { type TurbineLogger } from '../logger.js';
+import type { DeferredQuery } from './deferred.js';
+/** `TurbineConfig.sqlComment`. */
+export interface SqlCommentOptions {
+    /** Constant key/values on every statement this client builds: `{ application: 'billing' }`. */
+    static?: Readonly<Record<string, string>> | undefined;
+    /** Add `model` (the table) and `action` (`'findMany'`, `'update'`, ...) of the operation. */
+    model?: boolean | undefined;
+    /** Add the label of the innermost `db.$tag(label, fn)` scope as `tag`. */
+    tag?: boolean | undefined;
+    /**
+     * Per-statement values, computed in the caller's async context (for example
+     * a W3C `traceparent`). A key whose value is `undefined` is left out. A
+     * statement carrying any dynamic value is sent unnamed: parsed on every
+     * execution, never kept as a prepared statement. A key or value this
+     * function returns that cannot be used is dropped with a warning
+     * (`sql-comment-dropped`), and a throw drops all of them: a tracing hook
+     * never fails a query.
+     */
+    dynamic?: (() => Readonly<Record<string, string | undefined>> | undefined | null) | undefined;
+}
+/** What a comment key must look like. Lower case, so it can never open `/*!` or `/*+`. */
+export declare const SQL_COMMENT_KEY_PATTERN: RegExp;
+/** Longest value accepted, in characters before encoding. */
+export declare const MAX_SQL_COMMENT_VALUE_LENGTH = 256;
+/** One statement's comment. */
+export interface StatementComment {
+    /** The comment exactly as appended, without the space before it: `/*key='value',...*\/`. */
+    readonly comment: string;
+    /** It carries a dynamic value, so the statement goes out unnamed. */
+    readonly dynamic: boolean;
+}
+/**
+ * Builds the comment for each statement and the name it is sent under. One per
+ * client, shared by every table accessor and transaction of that client.
+ */
+export declare class SqlCommenter {
+    private readonly logger;
+    /** Static pairs, encoded and sorted. */
+    private readonly staticPairs;
+    /** Keys a dynamic value may not take: the static ones and the ones model / tag fill in. */
+    private readonly reservedKeys;
+    private readonly withModel;
+    private readonly withTag;
+    private readonly dynamic;
+    /** The comment when it depends on nothing per statement (no model, no tag). */
+    private readonly constant;
+    /** Rendered model / action / tag comments. Bounded: tags may come from data. */
+    private readonly rendered;
+    /** Claimed `c_` names by template name and comment. Holds only claimed names, so the budget bounds it. */
+    private readonly names;
+    /**
+     * Every statement gets a comment (a static key, or the model and action),
+     * so a template's own name is never sent and need not be claimed from the
+     * budget; the commented name is claimed instead.
+     */
+    readonly alwaysComments: boolean;
+    constructor(staticPairs: ReadonlyArray<readonly [string, string]>, withModel: boolean, withTag: boolean, dynamic: SqlCommentOptions['dynamic'], logger: TurbineLogger);
+    /**
+     * The comment for one statement of operation `action` on `model`, or
+     * `undefined` when it carries none. Reads the `$tag` scope and calls
+     * `dynamic` in the caller's async context, so call it where the statement
+     * is sent.
+     */
+    commentFor(model: string, action: string): StatementComment | undefined;
+    /**
+     * The name a statement with comment `c` is sent under, given its template's
+     * name. A template sent unnamed stays unnamed; a dynamic comment is unnamed;
+     * anything else gets a stable `c_` name from the process-wide budget, or
+     * goes unnamed once that is spent.
+     */
+    preparedName(templateName: string | undefined, c: StatementComment): string | undefined;
+    /** The usable dynamic pairs, encoded, or `undefined` when there are none. */
+    private dynamicPairs;
+    /** Why a dynamic key or value cannot be used, as [warning key, sentence], or `undefined`. */
+    private refusal;
+    /** One warning per reason and key, so a hook that misbehaves on every statement says it once. */
+    private dropped;
+}
+/**
+ * Validate `TurbineConfig.sqlComment` and build its commenter, or `undefined`
+ * when there is nothing to add. Throws `ValidationError` (E003) for a malformed
+ * option, and `UnsupportedFeatureError` (E017) where it cannot be honoured:
+ *
+ *   - a backend that builds no SQL (PowDB, which injects its own query
+ *     interface) has nothing to comment;
+ *   - `dynamic` on an engine that prepares every statement text
+ *     (`preparesEveryStatement`), which is MySQL: the MySQL engine sends each
+ *     parameterized statement through mysql2's `execute()`, which keeps one
+ *     SERVER-side prepared
+ *     statement per distinct text per connection (up to 16,000 each), and the
+ *     server caps the total across every client at `max_prepared_stmt_count`
+ *     (16,382 by default). A value unique per request makes every text
+ *     distinct, so a busy pool reaches that cap (error 1461) and every client
+ *     of the server then fails to prepare.
+ */
+export declare function resolveSqlComment(value: unknown, logger: TurbineLogger, engine: {
+    readonly dialect: string;
+    readonly preparesEveryStatement: boolean;
+    readonly buildsSql: boolean;
+}): SqlCommenter | undefined;
+/**
+ * `sql` with a comment Turbine appended removed, for code that reads statement
+ * text to decide how to run it (an engine shim telling a row-returning
+ * statement from a change count). A value can never contain `/*` (it is
+ * URL-encoded), so the last ` /*` of a statement ending in `*\/` is the
+ * comment's own opener; text Turbine did not comment is returned unchanged
+ * unless it, too, ends in a block comment, which is equally not code.
+ */
+export declare function withoutTrailingComment(sql: string): string;
+/**
+ * `q` as sent with `comment`: its statement, and every statement of its
+ * reselect plan (MySQL), carry the comment. Everything else on the query is
+ * kept. Used by the batch paths (`pipeline`, `$transaction([...])`), which run
+ * deferred queries without going through a query interface.
+ */
+export declare function commentDeferred<T>(q: DeferredQuery<T>, comment: string | undefined): DeferredQuery<T>;

package/dist/query/sql-comment.js

@@ -0,0 +1,374 @@
+/**
+ * turbine-orm: `sqlComment`, sqlcommenter-style key/values on each statement
+ * Turbine builds, so `pg_stat_activity`, the server log, `auto_explain` and
+ * database APM tools can attribute a statement to a service, a model, a feature
+ * or a trace.
+ *
+ *   SELECT ... LIMIT $2 /*action='findMany',application='billing',model='users'*\/
+ *
+ * FORMAT (the sqlcommenter spec): keys sorted, each value URL-encoded with
+ * `encodeURIComponent` and then `'` escaped as `\'`, each pair `key='value'`,
+ * pairs joined by commas, the whole comment appended after the statement with
+ * one space before it.
+ *
+ * WHY A VALUE CANNOT ESCAPE THE COMMENT. `encodeURIComponent` encodes `/`, so a
+ * value can hold neither `*\/` (the comment's end) nor `/*` (PostgreSQL and SQL
+ * Server nest block comments, so an opener would swallow the rest of the
+ * text). It also encodes every character a driver-side placeholder rewrite
+ * looks for (`$`, `?`, `:`, `@`) and `;`. Keys must match
+ * {@link SQL_COMMENT_KEY_PATTERN}, whose first-character rule also rules out
+ * MySQL's executable `/*!` and optimizer-hint `/*+` comments.
+ *
+ * WHERE IT IS APPENDED: at the execute seam, AFTER the SQL-template cache. The
+ * cache stores commentless text, so its keys, its hit rate and the lockstep
+ * checks are untouched by any comment, and a per-request value can never grow
+ * it. `$on('query')` events keep `sql` commentless and carry the comment in
+ * their own field.
+ *
+ * PREPARED-STATEMENT NAMES. node-postgres refuses to reuse a statement name for
+ * different text on one connection, and every name a connection prepares stays
+ * on the server until the connection closes. So:
+ *
+ *   - no comment: the template's own name, as before;
+ *   - static, model, action and tag only (constant per call site and label):
+ *     `c_<16 hex>`, a hash of the template name and the comment, claimed from
+ *     the same process-wide budget as every other name
+ *     (`PREPARED_STATEMENT_BUDGET`), so the server-side cost stays bounded
+ *     however many labels there are;
+ *   - any dynamic value (a trace id, unique per request): unnamed, parsed on
+ *     every execution and never kept. A per-request value under a name would
+ *     prepare a new statement on every pooled connection for every request.
+ *
+ * Leaf apart from errors.ts, logger.ts, query-events.ts (the `$tag` scope) and
+ * utils.ts (the name budget); nothing here is Node-only.
+ */
+import { UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { logTo } from '../logger.js';
+import { currentQueryTag } from '../query-events.js';
+import { claimPreparedName, fnv1a64Hex, LRUCache } from './utils.js';
+import { shouldWarnOnce } from './warn-registry.js';
+/** What a comment key must look like. Lower case, so it can never open `/*!` or `/*+`. */
+export const SQL_COMMENT_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Longest value accepted, in characters before encoding. */
+export const MAX_SQL_COMMENT_VALUE_LENGTH = 256;
+/** The keys `model: true` and `tag: true` fill in. */
+const MODEL_KEYS = ['action', 'model'];
+const TAG_KEY = 'tag';
+const OPTION_KEYS = new Set(['static', 'model', 'tag', 'dynamic']);
+/** Once-only warning namespace for dropped dynamic values. */
+const DROPPED_WARN_NS = 'sqlCommentDropped';
+/**
+ * `value` URL-encoded with `'` escaped, or `undefined` when it cannot be encoded
+ * (a lone surrogate). `encodeURIComponent` leaves `'` as is and never emits a
+ * backslash; the escape covers both anyway, so it stays complete on its own.
+ */
+function encodeValue(value) {
+    try {
+        return encodeURIComponent(value).replace(/[\\']/g, '\\$&');
+    }
+    catch {
+        return undefined;
+    }
+}
+function render(pairs) {
+    let out = '/*';
+    for (let i = 0; i < pairs.length; i++) {
+        const [key, value] = pairs[i];
+        out += `${i === 0 ? '' : ','}${key}='${value}'`;
+    }
+    return `${out}*/`;
+}
+function byKey(a, b) {
+    return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** A short, printable rendering of a caller's key for a message. */
+function describeKey(key) {
+    return JSON.stringify(key.length > 64 ? `${key.slice(0, 64)}...` : key);
+}
+/**
+ * Builds the comment for each statement and the name it is sent under. One per
+ * client, shared by every table accessor and transaction of that client.
+ */
+export class SqlCommenter {
+    logger;
+    /** Static pairs, encoded and sorted. */
+    staticPairs;
+    /** Keys a dynamic value may not take: the static ones and the ones model / tag fill in. */
+    reservedKeys;
+    withModel;
+    withTag;
+    dynamic;
+    /** The comment when it depends on nothing per statement (no model, no tag). */
+    constant;
+    /** Rendered model / action / tag comments. Bounded: tags may come from data. */
+    rendered = new LRUCache(1000);
+    /** Claimed `c_` names by template name and comment. Holds only claimed names, so the budget bounds it. */
+    names = new Map();
+    /**
+     * Every statement gets a comment (a static key, or the model and action),
+     * so a template's own name is never sent and need not be claimed from the
+     * budget; the commented name is claimed instead.
+     */
+    alwaysComments;
+    constructor(staticPairs, withModel, withTag, dynamic, logger) {
+        this.logger = logger;
+        this.staticPairs = [...staticPairs].sort(byKey);
+        this.withModel = withModel;
+        this.withTag = withTag;
+        this.dynamic = dynamic;
+        const reserved = new Set(this.staticPairs.map(([k]) => k));
+        if (withModel)
+            for (const k of MODEL_KEYS)
+                reserved.add(k);
+        if (withTag)
+            reserved.add(TAG_KEY);
+        this.reservedKeys = reserved;
+        this.alwaysComments = this.staticPairs.length > 0 || withModel;
+        this.constant =
+            !withModel && !withTag && this.staticPairs.length > 0
+                ? { comment: render(this.staticPairs), dynamic: false }
+                : undefined;
+    }
+    /**
+     * The comment for one statement of operation `action` on `model`, or
+     * `undefined` when it carries none. Reads the `$tag` scope and calls
+     * `dynamic` in the caller's async context, so call it where the statement
+     * is sent.
+     */
+    commentFor(model, action) {
+        let pairs;
+        let base;
+        if (this.withModel || this.withTag) {
+            const tag = this.withTag ? currentQueryTag() : undefined;
+            const key = `${model}\u0000${action}\u0000${tag ?? ''}`;
+            let hit = this.rendered.get(key);
+            if (hit === undefined) {
+                const built = [...this.staticPairs];
+                if (this.withModel) {
+                    built.push(['action', encodeValue(action) ?? ''], ['model', encodeValue(model) ?? '']);
+                }
+                // A `$tag` label is 1 to 128 characters, checked when the scope opens.
+                const encodedTag = tag === undefined ? undefined : encodeValue(tag);
+                if (encodedTag !== undefined)
+                    built.push([TAG_KEY, encodedTag]);
+                built.sort(byKey);
+                hit = { pairs: built, comment: built.length > 0 ? render(built) : '' };
+                this.rendered.set(key, hit);
+            }
+            pairs = hit.pairs;
+            base = hit.comment === '' ? undefined : { comment: hit.comment, dynamic: false };
+        }
+        else {
+            pairs = this.staticPairs;
+            base = this.constant;
+        }
+        if (this.dynamic === undefined)
+            return base;
+        const extra = this.dynamicPairs();
+        if (extra === undefined)
+            return base;
+        return { comment: render([...pairs, ...extra].sort(byKey)), dynamic: true };
+    }
+    /**
+     * The name a statement with comment `c` is sent under, given its template's
+     * name. A template sent unnamed stays unnamed; a dynamic comment is unnamed;
+     * anything else gets a stable `c_` name from the process-wide budget, or
+     * goes unnamed once that is spent.
+     */
+    preparedName(templateName, c) {
+        if (!templateName)
+            return templateName;
+        if (c.dynamic)
+            return '';
+        const key = `${templateName}\u0000${c.comment}`;
+        const known = this.names.get(key);
+        if (known !== undefined)
+            return known;
+        const name = claimPreparedName(`c_${fnv1a64Hex(key)}`);
+        if (name !== '')
+            this.names.set(key, name);
+        return name;
+    }
+    /** The usable dynamic pairs, encoded, or `undefined` when there are none. */
+    dynamicPairs() {
+        let values;
+        try {
+            values = this.dynamic?.();
+        }
+        catch (err) {
+            this.dropped('threw', '', `sqlComment.dynamic threw (${err instanceof Error ? err.message : String(err)}), so ` +
+                'this statement carries no dynamic values. The statement itself ran as usual.');
+            return undefined;
+        }
+        if (values === undefined || values === null)
+            return undefined;
+        if (typeof values !== 'object' || Array.isArray(values)) {
+            this.dropped('shape', '', 'sqlComment.dynamic returned something other than an object of string values, so this statement carries ' +
+                'no dynamic values. Return an object such as { traceparent: "00-..." }, or undefined for none.');
+            return undefined;
+        }
+        let out;
+        for (const key of Object.keys(values)) {
+            const value = values[key];
+            if (value === undefined)
+                continue;
+            const reason = this.refusal(key, value);
+            if (reason !== undefined) {
+                this.dropped(reason[0], key, `sqlComment.dynamic key ${describeKey(key)} was left out of the comment: ${reason[1]}`);
+                continue;
+            }
+            const encoded = encodeValue(value);
+            if (encoded === undefined) {
+                this.dropped('encoding', key, `sqlComment.dynamic key ${describeKey(key)} was left out of the comment: its value is not well-formed ` +
+                    'Unicode (a lone surrogate), so it cannot be URL-encoded.');
+                continue;
+            }
+            if (out === undefined)
+                out = [];
+            out.push([key, encoded]);
+        }
+        return out;
+    }
+    /** Why a dynamic key or value cannot be used, as [warning key, sentence], or `undefined`. */
+    refusal(key, value) {
+        if (!SQL_COMMENT_KEY_PATTERN.test(key)) {
+            return ['key', 'a key must be lower-case letters, digits and underscores, starting with a letter.'];
+        }
+        if (this.reservedKeys.has(key)) {
+            return ['reserved', 'that key is already set by sqlComment.static, model or tag, which take precedence.'];
+        }
+        if (typeof value !== 'string')
+            return ['type', `its value is ${typeof value}, not a string.`];
+        if (value.length > MAX_SQL_COMMENT_VALUE_LENGTH) {
+            return ['length', `its value is ${value.length} characters, over the ${MAX_SQL_COMMENT_VALUE_LENGTH} allowed.`];
+        }
+        return undefined;
+    }
+    /** One warning per reason and key, so a hook that misbehaves on every statement says it once. */
+    dropped(reason, key, message) {
+        if (!shouldWarnOnce(DROPPED_WARN_NS, `${reason}|${key.slice(0, 64)}`))
+            return;
+        logTo(this.logger, 'warn', message, { code: 'sql-comment-dropped', reason });
+    }
+}
+/**
+ * Validate `TurbineConfig.sqlComment` and build its commenter, or `undefined`
+ * when there is nothing to add. Throws `ValidationError` (E003) for a malformed
+ * option, and `UnsupportedFeatureError` (E017) where it cannot be honoured:
+ *
+ *   - a backend that builds no SQL (PowDB, which injects its own query
+ *     interface) has nothing to comment;
+ *   - `dynamic` on an engine that prepares every statement text
+ *     (`preparesEveryStatement`), which is MySQL: the MySQL engine sends each
+ *     parameterized statement through mysql2's `execute()`, which keeps one
+ *     SERVER-side prepared
+ *     statement per distinct text per connection (up to 16,000 each), and the
+ *     server caps the total across every client at `max_prepared_stmt_count`
+ *     (16,382 by default). A value unique per request makes every text
+ *     distinct, so a busy pool reaches that cap (error 1461) and every client
+ *     of the server then fails to prepare.
+ */
+export function resolveSqlComment(value, logger, engine) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value)) {
+        throw new ValidationError('Invalid sqlComment: expected an object with any of `static`, `model`, `tag` and `dynamic`, for example ' +
+            "{ static: { application: 'billing' }, model: true }.");
+    }
+    for (const key of Object.keys(value)) {
+        if (!OPTION_KEYS.has(key)) {
+            throw new ValidationError(`Invalid sqlComment: unknown key ${describeKey(key)}. The keys are \`static\`, \`model\`, \`tag\` and \`dynamic\`.`);
+        }
+    }
+    const { static: staticValues, model, tag, dynamic } = value;
+    for (const [name, flag] of [
+        ['model', model],
+        ['tag', tag],
+    ]) {
+        if (flag !== undefined && typeof flag !== 'boolean') {
+            throw new ValidationError(`Invalid sqlComment.${name}: expected true or false, got ${typeof flag}.`);
+        }
+    }
+    if (dynamic !== undefined && typeof dynamic !== 'function') {
+        throw new ValidationError(`Invalid sqlComment.dynamic: expected a function returning an object of string values, got ${typeof dynamic}.`);
+    }
+    const pairs = [];
+    if (staticValues !== undefined) {
+        if (!isPlainObject(staticValues)) {
+            throw new ValidationError("Invalid sqlComment.static: expected an object of string values, for example { application: 'billing' }.");
+        }
+        for (const key of Object.keys(staticValues)) {
+            const v = staticValues[key];
+            const where = `sqlComment.static key ${describeKey(key)}`;
+            if (!SQL_COMMENT_KEY_PATTERN.test(key)) {
+                throw new ValidationError(`Invalid ${where}: a key must be lower-case letters, digits and underscores, starting with a letter ` +
+                    '(the comment must never open a MySQL executable or hint comment, `/*!` or `/*+`).');
+            }
+            if ((model === true && MODEL_KEYS.includes(key)) || (tag === true && key === TAG_KEY)) {
+                throw new ValidationError(`Invalid ${where}: \`${key}\` is filled in by sqlComment.${key === TAG_KEY ? 'tag' : 'model'}. ` +
+                    'Rename the static key or turn that option off.');
+            }
+            if (typeof v !== 'string') {
+                throw new ValidationError(`Invalid ${where}: expected a string value, got ${typeof v}.`);
+            }
+            if (v.length > MAX_SQL_COMMENT_VALUE_LENGTH) {
+                throw new ValidationError(`Invalid ${where}: the value is ${v.length} characters, over the ${MAX_SQL_COMMENT_VALUE_LENGTH} allowed.`);
+            }
+            const encoded = encodeValue(v);
+            if (encoded === undefined) {
+                throw new ValidationError(`Invalid ${where}: the value is not well-formed Unicode (a lone surrogate), so it cannot be URL-encoded.`);
+            }
+            pairs.push([key, encoded]);
+        }
+    }
+    if (pairs.length === 0 && model !== true && tag !== true && dynamic === undefined)
+        return undefined;
+    if (!engine.buildsSql) {
+        throw new UnsupportedFeatureError('sqlComment', engine.dialect, 'This engine does not run SQL, so there is no statement to carry a comment. Remove the option for this client.');
+    }
+    if (dynamic !== undefined && engine.preparesEveryStatement) {
+        throw new UnsupportedFeatureError('sqlComment.dynamic', engine.dialect, 'The MySQL engine prepares each distinct statement text on the server (mysql2 execute(), up to 16,000 per ' +
+            'connection), and the server caps prepared statements across all clients at max_prepared_stmt_count ' +
+            '(16,382 by default). A per-statement value makes every text distinct, so a busy pool reaches that cap ' +
+            '(error 1461) and prepares start failing server-wide. Use `static`, `model` and `tag`, which are bounded.');
+    }
+    return new SqlCommenter(pairs, model === true, tag === true, dynamic, logger);
+}
+/**
+ * `sql` with a comment Turbine appended removed, for code that reads statement
+ * text to decide how to run it (an engine shim telling a row-returning
+ * statement from a change count). A value can never contain `/*` (it is
+ * URL-encoded), so the last ` /*` of a statement ending in `*\/` is the
+ * comment's own opener; text Turbine did not comment is returned unchanged
+ * unless it, too, ends in a block comment, which is equally not code.
+ */
+export function withoutTrailingComment(sql) {
+    if (!sql.endsWith('*/'))
+        return sql;
+    const at = sql.lastIndexOf(' /*');
+    return at < 0 ? sql : sql.slice(0, at);
+}
+/**
+ * `q` as sent with `comment`: its statement, and every statement of its
+ * reselect plan (MySQL), carry the comment. Everything else on the query is
+ * kept. Used by the batch paths (`pipeline`, `$transaction([...])`), which run
+ * deferred queries without going through a query interface.
+ */
+export function commentDeferred(q, comment) {
+    if (comment === undefined)
+        return q;
+    const reselect = q.reselect;
+    return {
+        ...q,
+        sql: `${q.sql} ${comment}`,
+        ...(reselect
+            ? { reselect: (exec) => reselect((sql, params, name) => exec(`${sql} ${comment}`, params, name)) }
+            : {}),
+    };
+}