turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/query/row-lock.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRowLock = resolveRowLock;
+exports.lockOutsideTransactionMessage = lockOutsideTransactionMessage;
+exports.lockOnStreamMessage = lockOnStreamMessage;
+exports.lockWithDistinctMessage = lockWithDistinctMessage;
+exports.assertNoLockInAutocommitPipeline = assertNoLockInAutocommitPipeline;
+const errors_js_1 = require("../errors.js");
+const global_filters_config_js_1 = require("../global-filters-config.js");
+const utils_js_1 = require("./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).
+ */
+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 = (0, utils_js_1.suggestKey)(key, LOCK_KEYS);
+                throw new errors_js_1.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 errors_js_1.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 errors_js_1.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' ? (0, utils_js_1.suggestKey)(mode, MODES) : null;
+        throw new errors_js_1.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 errors_js_1.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.
+ */
+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.${(0, global_filters_config_js_1.tableAccessorName)(table)}.${operation}({ ..., lock })).`);
+}
+/** The refusal for `lock` on a streaming read. */
+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`. */
+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.
+ */
+function assertNoLockInAutocommitPipeline(queries) {
+    const at = queries.findIndex((q) => q.rowLock === true);
+    if (at === -1)
+        return;
+    throw new errors_js_1.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 errors_js_1.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/cjs/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>;