@zmdb/sql 1.0.0-beta.1

package/README.md

@@ -0,0 +1,35 @@
+# @zmdb/sql
+
+`@zmdb/sql` turns typed query descriptions into SQL for each supported dialect. It covers reads and writes, joins, aggregates, full-text search, set operations, schema objects, and the vendor-neutral
+dialect protocols consumed by higher layers.
+
+Each database package owns a complete `SqlDialect` object with compiler traits, migration implementation, introspector and capabilities. Pass that object through the public SQL contract; built-in
+string dialect selection is removed. A third-party database can provide the same contract without editing this package. Schema snapshots, migration execution, catalog introspection and declaration
+emission are independently installable from `@zmdb/migrations`.
+
+`@zmdb/sql` has no runtime dependencies or peers. Its [foundation guide](https://github.com/ambasta/zmdb/blob/main/docs-site/content/runtime-foundation.md) explains the inward package graph and the
+separate database and tooling boundaries.
+
+It is part of [zmdb](https://github.com/ambasta/zmdb), where one TypeScript schema drives validation, serialization, SQL, OpenAPI, and CRUD.
+
+## Install
+
+```bash
+yarn add @zmdb/sql@1.0.0-beta.1
+```
+
+> **Prerelease** (`1.0.0-beta.1`). Requires **Node.js 26+** and is **ESM-only**. Ships built ESM `.js` + `.d.ts` under `./dist`.
+
+## Entry points
+
+- Query compilation: `@zmdb/sql`, `/joins`, `/aggregations`, `/fts`, `/set-ops`
+- SQL metadata and DDL: `/schema-objects`, `/comments`
+- Naming and outbox composition are owned by `@zmdb/schema/naming` and `@zmdb/orm/outbox`.
+
+## Documentation
+
+Full docs: **https://ambasta.github.io/zmdb/**
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later) — see [LICENSE](./LICENSE).

package/dist/aggregations/index.d.ts

@@ -0,0 +1,30 @@
+import { type ComparisonPredicate, type JoinCondition, type Predicate } from '../clauses.js';
+import type { DialectTarget } from '../dialects/index.js';
+import { type CompiledQuery, type QueryCompilerOptions } from '../index.js';
+export type { JoinCondition, JoinKind } from '../clauses.js';
+export interface AggregateSelect {
+    select(cols: readonly string[]): AggregateSelect;
+    count(expr: string, alias: string): AggregateSelect;
+    sum(expr: string, alias: string): AggregateSelect;
+    avg(expr: string, alias: string): AggregateSelect;
+    min(expr: string, alias: string): AggregateSelect;
+    max(expr: string, alias: string): AggregateSelect;
+    expr(rawExpr: string, alias: string): AggregateSelect;
+    innerJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): AggregateSelect;
+    innerJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): AggregateSelect;
+    leftJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): AggregateSelect;
+    leftJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): AggregateSelect;
+    rightJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): AggregateSelect;
+    rightJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): AggregateSelect;
+    where(col: string, op: string, value: unknown): AggregateSelect;
+    orWhere(col: string, op: string, value: unknown): AggregateSelect;
+    whereGroup(predicates: readonly ComparisonPredicate[]): AggregateSelect;
+    groupBy(...cols: string[]): AggregateSelect;
+    having(col: string, op: string, value: unknown): AggregateSelect;
+    orderBy(col: string, dir: 'asc' | 'desc'): AggregateSelect;
+    limit(n: number): AggregateSelect;
+    offset(n: number): AggregateSelect;
+    compile(): CompiledQuery;
+}
+export declare function aggregateSelectFrom(table: string, dialect: DialectTarget, options?: QueryCompilerOptions): AggregateSelect;
+//# sourceMappingURL=index.d.ts.map

package/dist/aggregations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/aggregations/index.ts"],"names":[],"mappings":"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"}

package/dist/aggregations/index.js

@@ -0,0 +1,52 @@
+import { frozenQuery, havingClause, joinClauses, joinMethods, queryTelemetry, tailClause, tailMethods, whereClause, } from '../clauses.js';
+import {} from '../index.js';
+import { quoteColumn, quoteIdentifier, quoteTable } from '../quoting.js';
+function make(d, s, telemetry) {
+    const next = (p) => make(d, { ...s, ...p }, telemetry);
+    const agg = (fn, col, alias) => next({ items: [...s.items, { kind: 'agg', fn, col, alias }] });
+    return {
+        ...joinMethods(s.joins, next),
+        ...tailMethods(s, next),
+        select: cols => next({ items: [...s.items, ...cols.map((c) => ({ kind: 'col', col: c }))] }),
+        count: (e, a) => agg('COUNT', e, a),
+        sum: (e, a) => agg('SUM', e, a),
+        avg: (e, a) => agg('AVG', e, a),
+        min: (e, a) => agg('MIN', e, a),
+        max: (e, a) => agg('MAX', e, a),
+        expr: (raw, alias) => next({ items: [...s.items, { kind: 'expr', raw, alias }] }),
+        where: (col, op, value) => next({ wheres: [...s.wheres, { col, op, value, connector: 'AND' }] }),
+        orWhere: (col, op, value) => next({ wheres: [...s.wheres, { col, op, value, connector: 'OR' }] }),
+        whereGroup: predicates => next({ wheres: [...s.wheres, { kind: 'group', predicates, connector: 'AND' }] }),
+        groupBy: (...cols) => next({ groups: [...s.groups, ...cols] }),
+        having: (col, op, value) => next({ havings: [...s.havings, { col, op, value }] }),
+        compile: () => {
+            const params = [];
+            const cols = s.items.map(it => {
+                if (it.kind === 'col') {
+                    const m = /^(\S+)\s+as\s+(\S+)$/i.exec(it.col.trim());
+                    if (m && m[1] && m[2])
+                        return `${quoteColumn(d, m[1])} AS ${quoteIdentifier(d, m[2])}`;
+                    if (it.col.includes('.') && !it.col.toLowerCase().startsWith(`${s.table.toLowerCase()}.`)) {
+                        return `${quoteColumn(d, it.col)} AS ${quoteIdentifier(d, it.col)}`;
+                    }
+                    return quoteColumn(d, it.col);
+                }
+                if (it.kind === 'agg')
+                    return `${it.fn}(${quoteColumn(d, it.col)}) AS ${quoteIdentifier(d, it.alias)}`;
+                return `${it.raw} AS ${quoteIdentifier(d, it.alias)}`;
+            });
+            const groupBy = s.groups.length > 0 ? ` GROUP BY ${s.groups.map(c => quoteColumn(d, c)).join(', ')}` : '';
+            const text = `SELECT ${cols.join(', ')} FROM ${quoteTable(d, s.table)}` +
+                joinClauses(d, s.joins, params) +
+                whereClause(d, s.wheres, params) +
+                groupBy +
+                havingClause(d, s.havings, params) +
+                tailClause(d, s);
+            return frozenQuery(text, params, queryTelemetry(d, 'SELECT', s.table, telemetry));
+        },
+    };
+}
+export function aggregateSelectFrom(table, dialect, options) {
+    return make(dialect, { table, items: [], joins: [], wheres: [], groups: [], havings: [], orderBys: [] }, options?.telemetry === true);
+}
+//# sourceMappingURL=index.js.map

package/dist/aggregations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/aggregations/index.ts"],"names":[],"mappings":"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"}

package/dist/clauses.d.ts

@@ -0,0 +1,112 @@
+import { type DialectTarget } from './dialects/index.js';
+import { type SpatialPredicateNode } from './extensions/index.js';
+import { type CompiledQuery, type QueryTelemetry } from './index.js';
+export type JoinKind = 'inner' | 'left' | 'right';
+export interface JoinCondition {
+    readonly leftCol: string;
+    readonly rightCol: string;
+}
+export interface JoinSpec {
+    readonly kind: JoinKind;
+    readonly target: string;
+    readonly conditions: readonly JoinCondition[];
+    /** Predicates that belong to this target and therefore stay in the ON clause. */
+    readonly on?: readonly Predicate[];
+}
+/**
+ * One comparison in a WHERE or HAVING list. `connector` says how it attaches to
+ * the predicate before it and is ignored on the first one; builders that only
+ * ever conjoin can leave it out.
+ */
+export interface ComparisonPredicate {
+    readonly kind?: 'comparison';
+    readonly col: string;
+    readonly op: string;
+    readonly value: unknown;
+    readonly connector?: 'AND' | 'OR' | undefined;
+}
+/** One parenthesized predicate list, attached to the surrounding list by `connector`. */
+export interface PredicateGroup {
+    readonly kind: 'group';
+    readonly predicates: readonly Predicate[];
+    readonly connector?: 'AND' | 'OR' | undefined;
+}
+export type Predicate = ComparisonPredicate | SpatialPredicateNode | PredicateGroup;
+export interface Tail<C = string> {
+    readonly orderBys?: readonly {
+        readonly col: C;
+        readonly dir: 'asc' | 'desc';
+    }[] | undefined;
+    readonly limitN?: number | undefined;
+    readonly offsetN?: number | undefined;
+    /** Used by builders that render a richer ORDER BY expression before delegating pagination. */
+    readonly ordered?: boolean | undefined;
+}
+export declare const OP_MAP: Readonly<Record<string, string>>;
+/**
+ * Anything with a `compile()` — a builder from this package, or a caller's own.
+ *
+ * boundary: the cast is inside the guard that the rest of the package relies on, and it
+ * reads the one property the `in` check on the line above has just proven is there. Its
+ * type is `unknown`, so the `typeof` is what establishes anything; a narrower cast would be
+ * the claim this function exists to test.
+ */
+export declare function isSubqueryTarget(value: unknown): value is {
+    compile(): CompiledQuery;
+};
+/**
+ * Normalizes known operators to canonical SQL keywords and admits an unmapped
+ * operator only when it is one bounded SQL token.
+ */
+export declare function sqlOperator(op: string, dialect: DialectTarget): string;
+/** `col op $n`, or `EXISTS (…)` / `col op (…)` when the value is a subquery. */
+export declare function renderPredicate(dialect: DialectTarget, p: Predicate, params: unknown[]): string;
+/** ` WHERE …`, appending each predicate's parameters to `params` in order. */
+export declare function whereClause(dialect: DialectTarget, preds: readonly Predicate[], params: unknown[]): string;
+/** ` HAVING …` — same rendering as WHERE, which is why they share a code path. */
+export declare function havingClause(dialect: DialectTarget, preds: readonly Predicate[], params: unknown[]): string;
+/** ` INNER JOIN … ON … = … [AND … = …] [AND …]` for each join, in order. */
+export declare function joinClauses(dialect: DialectTarget, joins: readonly JoinSpec[], params?: unknown[]): string;
+/**
+ * ` ORDER BY … LIMIT n OFFSET n`. LIMIT and OFFSET are interpolated rather than
+ * parameterized because they are numbers this package produced, never caller
+ * strings — the builders' `limit`/`offset` take `number`.
+ */
+export declare function tailClause(dialect: DialectTarget, tail: Tail): string;
+/** Every `compile()` in this package returns this shape, frozen at both levels. */
+export declare function frozenQuery(text: string, params: readonly unknown[], telemetry?: QueryTelemetry): CompiledQuery;
+/** Compile-known database attributes, absent when telemetry was not requested. */
+export declare function queryTelemetry(dialect: DialectTarget, operation: QueryTelemetry['operation'], collection: string, enabled: boolean): QueryTelemetry | undefined;
+/**
+ * What {@link tailMethods} passes to a builder's `next`. Deliberately not
+ * `Partial<Tail>`: under `exactOptionalPropertyTypes` an optional property that
+ * also admits `undefined` is not assignable to one that doesn't, and no
+ * builder's state wants an explicit `undefined` written over its array.
+ */
+export interface TailPatch<C = string> {
+    readonly orderBys?: readonly {
+        readonly col: C;
+        readonly dir: 'asc' | 'desc';
+    }[];
+    readonly limitN?: number;
+    readonly offsetN?: number;
+}
+/** `orderBy` / `limit` / `offset`, for any state carrying a {@link Tail}. */
+export declare function tailMethods<C, B>(tail: Tail<C>, next: (patch: TailPatch<C>) => B): {
+    orderBy: (col: C, dir: 'asc' | 'desc') => B;
+    limit: (n: number) => B;
+    offset: (n: number) => B;
+};
+export interface JoinMethod<B> {
+    (target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): B;
+    (target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): B;
+}
+/** `innerJoin` / `leftJoin` / `rightJoin`, for any state carrying a join list. */
+export declare function joinMethods<B>(joins: readonly JoinSpec[], next: (patch: {
+    joins: readonly JoinSpec[];
+}) => B): {
+    innerJoin: JoinMethod<B>;
+    leftJoin: JoinMethod<B>;
+    rightJoin: JoinMethod<B>;
+};
+//# sourceMappingURL=clauses.d.ts.map

package/dist/clauses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../src/clauses.ts"],"names":[],"mappings":"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"}

package/dist/clauses.js

@@ -0,0 +1,267 @@
+// Clause rendering shared by every builder in this package.
+//
+// SELECT, the join builder, the aggregate builder, FTS, UPDATE and DELETE all
+// have to turn the same three things into SQL: a predicate list, a join list,
+// and the ORDER BY / LIMIT / OFFSET tail. Each builder used to carry its own
+// copy, and the copies had drifted: the aggregate builder's `having` understood
+// a subquery but its `where` pushed the builder object into the parameter list
+// as if it were a value, and three of them reimplemented `renumberPlaceholders`
+// inline rather than importing the one in ./quoting.ts.
+//
+// Everything here appends its own leading space and returns '' when it has
+// nothing to render, so callers concatenate unconditionally.
+import { dialectName, dialectTraits } from './dialects/index.js';
+import { UnsupportedFeatureError } from './errors.js';
+import { DISTANCE_OPERATORS, encodePgVector, isDistanceOp, renderSpatialPredicate, } from './extensions/index.js';
+import {} from './index.js';
+import { formatPlaceholder, quoteColumn, quoteTable, renumberPlaceholders, unaliasedTable } from './quoting.js';
+const JOIN_KEYWORD = {
+    inner: 'INNER JOIN',
+    left: 'LEFT JOIN',
+    right: 'RIGHT JOIN',
+};
+// Object.create(null) prevents prototype inheritance so an operator named 'constructor' cannot resolve through Object.prototype.
+export const OP_MAP = Object.freeze(Object.assign(Object.create(null), {
+    '=': '=',
+    '!=': '!=',
+    '<': '<',
+    '<=': '<=',
+    '>': '>',
+    '>=': '>=',
+    like: 'LIKE',
+    ilike: 'ILIKE',
+    in: 'IN',
+    'not in': 'NOT IN',
+    nin: 'NOT IN',
+    exists: 'EXISTS',
+    'not exists': 'NOT EXISTS',
+    'is null': 'IS NULL',
+    'is not null': 'IS NOT NULL',
+    ...DISTANCE_OPERATORS,
+}));
+/**
+ * The lexical shape of an operator the compiler does not know by name.
+ *
+ * This is deliberately not a dialect/operator allowlist: PostgreSQL extensions,
+ * SQLite GLOB, MySQL's null-safe equality and SQL Server's !< all remain usable.
+ * It is only the boundary between one SQL token and caller-controlled SQL text.
+ *
+ * `--` is excluded even though `-` is needed by real operators such as `->>`.
+ * `#` is restricted to PostgreSQL's `#>` / `#>>`; a bare hash starts a MySQL
+ * line comment. Placeholder markers are excluded on the dialects where they
+ * would be parsed as parameters. Slash is absent, so block-comment openers
+ * cannot be formed.
+ */
+function isUnmappedOperatorToken(op, dialect) {
+    return dialectTraits(dialect).acceptsOperator(op);
+}
+/**
+ * Anything with a `compile()` — a builder from this package, or a caller's own.
+ *
+ * boundary: the cast is inside the guard that the rest of the package relies on, and it
+ * reads the one property the `in` check on the line above has just proven is there. Its
+ * type is `unknown`, so the `typeof` is what establishes anything; a narrower cast would be
+ * the claim this function exists to test.
+ */
+export function isSubqueryTarget(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'compile' in value &&
+        typeof value.compile === 'function');
+}
+/**
+ * Normalizes known operators to canonical SQL keywords and admits an unmapped
+ * operator only when it is one bounded SQL token.
+ */
+export function sqlOperator(op, dialect) {
+    const normalized = op.toLowerCase().trim();
+    if (isDistanceOp(normalized) && !dialectTraits(dialect).vectorDistance) {
+        throw new UnsupportedFeatureError(normalized, dialectName(dialect));
+    }
+    // A plain index read, and no own-property guard: `OP_MAP` has a null prototype, so
+    // `OP_MAP['constructor']` is already `undefined` rather than a function off
+    // `Object.prototype`. That is what makes `??` safe here, and it is why the map is built
+    // the way it is.
+    const mapped = OP_MAP[normalized];
+    if (mapped !== undefined)
+        return mapped;
+    if (!isUnmappedOperatorToken(op, dialect)) {
+        const name = dialectName(dialect);
+        throw new TypeError(`invalid unmapped SQL operator ${JSON.stringify(op)} for dialect ${JSON.stringify(name)}; expected ` +
+            'one non-comment operator token that does not conflict with the dialect placeholder syntax');
+    }
+    return op;
+}
+/** `col op $n`, or `EXISTS (…)` / `col op (…)` when the value is a subquery. */
+export function renderPredicate(dialect, p, params) {
+    if (p.kind === 'group') {
+        if (p.predicates.length === 0)
+            throw new TypeError('predicate groups must not be empty');
+        return `(${predicateList(dialect, p.predicates, params)})`;
+    }
+    if (p.kind === 'spatial')
+        return renderSpatialPredicate(dialect, p, params);
+    const normalized = p.op.toLowerCase().trim();
+    const sqlOp = sqlOperator(p.op, dialect);
+    if (sqlOp === 'IS NULL' || sqlOp === 'IS NOT NULL') {
+        return `${quoteColumn(dialect, p.col)} ${sqlOp}`;
+    }
+    if (isDistanceOp(normalized)) {
+        params.push(encodePgVector(p.value));
+        return `${quoteColumn(dialect, p.col)} ${sqlOp} ${formatPlaceholder(dialect, params.length)}`;
+    }
+    if (sqlOp === 'IS NULL' || sqlOp === 'IS NOT NULL') {
+        return `${quoteColumn(dialect, p.col)} ${sqlOp}`;
+    }
+    if (isSubqueryTarget(p.value)) {
+        const sub = p.value.compile();
+        // Continue the outer statement's numbering. Positional placeholders are a
+        // no-op here, so the order of the pushes below is what matters.
+        const text = renumberPlaceholders(sub.text, params.length, dialect);
+        params.push(...sub.parameters);
+        if (sqlOp === 'EXISTS')
+            return `EXISTS (${text})`;
+        if (sqlOp === 'NOT EXISTS')
+            return `NOT EXISTS (${text})`;
+        return `${quoteColumn(dialect, p.col)} ${sqlOp} (${text})`;
+    }
+    if (sqlOp === 'IN' || sqlOp === 'NOT IN') {
+        const isNotIn = sqlOp === 'NOT IN';
+        let arr = Array.isArray(p.value) ? p.value : [p.value];
+        if (isNotIn) {
+            arr = arr.filter(item => item !== null && item !== undefined);
+        }
+        if (arr.length === 0) {
+            return isNotIn ? '1 = 1' : '1 = 0';
+        }
+        const placeholders = arr
+            .map(item => {
+            params.push(item);
+            return formatPlaceholder(dialect, params.length);
+        })
+            .join(', ');
+        return `${quoteColumn(dialect, p.col)} ${sqlOp} (${placeholders})`;
+    }
+    params.push(p.value);
+    return `${quoteColumn(dialect, p.col)} ${sqlOp} ${formatPlaceholder(dialect, params.length)}`;
+}
+function predicateList(dialect, preds, params) {
+    return preds
+        .map((p, i) => {
+        const cond = renderPredicate(dialect, p, params);
+        return i === 0 ? cond : `${p.connector ?? 'AND'} ${cond}`;
+    })
+        .join(' ');
+}
+/** ` WHERE …`, appending each predicate's parameters to `params` in order. */
+export function whereClause(dialect, preds, params) {
+    if (preds.length === 0)
+        return '';
+    return ` WHERE ${predicateList(dialect, preds, params)}`;
+}
+/** ` HAVING …` — same rendering as WHERE, which is why they share a code path. */
+export function havingClause(dialect, preds, params) {
+    if (preds.length === 0)
+        return '';
+    return ` HAVING ${predicateList(dialect, preds, params)}`;
+}
+/** ` INNER JOIN … ON … = … [AND … = …] [AND …]` for each join, in order. */
+export function joinClauses(dialect, joins, params = []) {
+    return joins
+        .map(j => {
+        const conditions = j.conditions
+            .map(condition => `${quoteColumn(dialect, condition.leftCol)} = ${quoteColumn(dialect, condition.rightCol)}`)
+            .join(' AND ');
+        const targetPredicates = j.on === undefined || j.on.length === 0
+            ? ''
+            : j.on
+                .map((predicate, index) => {
+                const rendered = renderPredicate(dialect, predicate, params);
+                return `${index === 0 ? 'AND' : (predicate.connector ?? 'AND')} ${rendered}`;
+            })
+                .join(' ');
+        return (` ${JOIN_KEYWORD[j.kind]} ${quoteTable(dialect, j.target)} ` +
+            `ON ${conditions}` +
+            (targetPredicates.length === 0 ? '' : ` ${targetPredicates}`));
+    })
+        .join('');
+}
+/**
+ * ` ORDER BY … LIMIT n OFFSET n`. LIMIT and OFFSET are interpolated rather than
+ * parameterized because they are numbers this package produced, never caller
+ * strings — the builders' `limit`/`offset` take `number`.
+ */
+export function tailClause(dialect, tail) {
+    let text = '';
+    const rendersOrderBy = tail.orderBys !== undefined && tail.orderBys.length > 0;
+    const ordered = tail.ordered ?? rendersOrderBy;
+    if (rendersOrderBy) {
+        const ob = tail.orderBys.map(o => `${quoteColumn(dialect, o.col)} ${o.dir.toUpperCase()}`).join(', ');
+        text += ` ORDER BY ${ob}`;
+    }
+    text += dialectTraits(dialect).paginate({
+        ...(tail.limitN === undefined ? {} : { limit: tail.limitN }),
+        ...(tail.offsetN === undefined ? {} : { offset: tail.offsetN }),
+        ordered,
+    });
+    return text;
+}
+/** Every `compile()` in this package returns this shape, frozen at both levels. */
+export function frozenQuery(text, params, telemetry) {
+    const parameters = Object.freeze([...params]);
+    return telemetry === undefined ? Object.freeze({ text, parameters }) : Object.freeze({ text, parameters, telemetry });
+}
+/** Compile-known database attributes, absent when telemetry was not requested. */
+export function queryTelemetry(dialect, operation, collection, enabled) {
+    if (!enabled)
+        return undefined;
+    return Object.freeze({
+        system: dialect.telemetrySystem,
+        operation,
+        collection: unaliasedTable(collection),
+    });
+}
+/** `orderBy` / `limit` / `offset`, for any state carrying a {@link Tail}. */
+export function tailMethods(tail, next) {
+    return {
+        orderBy: (col, dir) => next({ orderBys: [...(tail.orderBys ?? []), { col, dir }] }),
+        limit: (n) => next({ limitN: n }),
+        offset: (n) => next({ offsetN: n }),
+    };
+}
+/** `innerJoin` / `leftJoin` / `rightJoin`, for any state carrying a join list. */
+export function joinMethods(joins, next) {
+    const add = (kind) => {
+        function join(target, leftColOrConditions, rightColOrOn, scalarOn) {
+            const conditions = typeof leftColOrConditions === 'string'
+                ? typeof rightColOrOn === 'string'
+                    ? [{ leftCol: leftColOrConditions, rightCol: rightColOrOn }]
+                    : []
+                : leftColOrConditions;
+            if (conditions.length === 0) {
+                throw new RangeError(`join "${target}" needs at least one ON condition`);
+            }
+            const on = typeof leftColOrConditions === 'string' ? scalarOn : rightColOrOn;
+            if (on !== undefined && typeof on === 'string') {
+                throw new TypeError(`join "${target}" received an invalid ON predicate list`);
+            }
+            return next({
+                joins: [
+                    ...joins,
+                    {
+                        kind,
+                        target,
+                        conditions: conditions.map(condition => ({
+                            leftCol: condition.leftCol,
+                            rightCol: condition.rightCol,
+                        })),
+                        ...(on === undefined ? {} : { on }),
+                    },
+                ],
+            });
+        }
+        return join;
+    };
+    return { innerJoin: add('inner'), leftJoin: add('left'), rightJoin: add('right') };
+}
+//# sourceMappingURL=clauses.js.map

package/dist/clauses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clauses.js","sourceRoot":"","sources":["../src/clauses.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,wDAAwD;AACxD,EAAE;AACF,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAsB,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAA2C,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA+ChH,MAAM,YAAY,GAA6B;IAC7C,KAAK,EAAE,YAAY;IACnB,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;CACpB,CAAC;AAEF,iIAAiI;AACjI,MAAM,CAAC,MAAM,MAAM,GAAqC,MAAM,CAAC,MAAM,CACnE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;IACjC,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,IAAI;IACV,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,IAAI;IACV,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,EAAE,EAAE,IAAI;IACR,QAAQ,EAAE,QAAQ;IAClB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,YAAY;IAC1B,SAAS,EAAE,SAAS;IACpB,aAAa,EAAE,aAAa;IAC5B,GAAG,kBAAkB;CACtB,CAAC,CACH,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAS,uBAAuB,CAAC,EAAU,EAAE,OAAsB;IACjE,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,SAAS,IAAI,KAAK;QAClB,OAAQ,KAA+B,CAAC,OAAO,KAAK,UAAU,CAC/D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,OAAsB;IAC5D,MAAM,UAAU,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC;QACvE,MAAM,IAAI,uBAAuB,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,mFAAmF;IACnF,4EAA4E;IAC5E,wFAAwF;IACxF,iBAAiB;IACjB,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,CAAC,uBAAuB,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,IAAI,SAAS,CACjB,iCAAiC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,gBAAgB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa;YAClG,2FAA2F,CAC9F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,OAAsB,EAAE,CAAY,EAAE,MAAiB;IACrF,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QACzF,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,sBAAsB,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5E,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAEzC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QACnD,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC;IACnD,CAAC;IAED,IAAI,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACrC,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IAChG,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QACnD,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC;IACnD,CAAC;IAED,IAAI,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC9B,0EAA0E;QAC1E,gEAAgE;QAChE,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;QAE/B,IAAI,KAAK,KAAK,QAAQ;YAAE,OAAO,WAAW,IAAI,GAAG,CAAC;QAClD,IAAI,KAAK,KAAK,YAAY;YAAE,OAAO,eAAe,IAAI,GAAG,CAAC;QAC1D,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,GAAG,CAAC;IAC7D,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,KAAK,KAAK,QAAQ,CAAC;QACnC,IAAI,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,OAAO,EAAE,CAAC;YACZ,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QACrC,CAAC;QACD,MAAM,YAAY,GAAG,GAAG;aACrB,GAAG,CAAC,IAAI,CAAC,EAAE;YACV,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACnD,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,YAAY,GAAG,CAAC;IACrE,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;AAChG,CAAC;AAED,SAAS,aAAa,CAAC,OAAsB,EAAE,KAA2B,EAAE,MAAiB;IAC3F,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACZ,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QACjD,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;IAC5D,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,OAAsB,EAAE,KAA2B,EAAE,MAAiB;IAChG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,UAAU,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,OAAsB,EAAE,KAA2B,EAAE,MAAiB;IACjG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,WAAW,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,OAAsB,EAAE,KAA0B,EAAE,MAAM,GAAc,EAAE;IACpG,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE;QACP,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU;aAC5B,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;aAC5G,IAAI,CAAC,OAAO,CAAC,CAAC;QACjB,MAAM,gBAAgB,GACpB,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;YACrC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,CAAC,CAAC,EAAE;iBACD,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE;gBACxB,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;gBAC7D,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC/E,CAAC,CAAC;iBACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CACL,IAAI,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG;YAC5D,MAAM,UAAU,EAAE;YAClB,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,gBAAgB,EAAE,CAAC,CAC9D,CAAC;IACJ,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAsB,EAAE,IAAU;IAC3D,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC;IAC/C,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtG,IAAI,IAAI,aAAa,EAAE,EAAE,CAAC;IAC5B,CAAC;IACD,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5D,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/D,OAAO;KACR,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAA0B,EAAE,SAA0B;IAC9F,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAC9C,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;AACxH,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAC5B,OAAsB,EACtB,SAAsC,EACtC,UAAkB,EAClB,OAAgB;IAEhB,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC,eAAe;QAC/B,SAAS;QACT,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC;KACvC,CAAC,CAAC;AACL,CAAC;AA+BD,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAO,IAAa,EAAE,IAAgC;IAC/E,OAAO;QACL,OAAO,EAAE,CAAC,GAAM,EAAE,GAAmB,EAAK,EAAE,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACzG,KAAK,EAAE,CAAC,CAAS,EAAK,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC5C,MAAM,EAAE,CAAC,CAAS,EAAK,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAOD,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAI,KAA0B,EAAE,IAAkD;IAC3G,MAAM,GAAG,GAAG,CAAC,IAAc,EAAiB,EAAE;QAG5C,SAAS,IAAI,CACX,MAAc,EACd,mBAAsD,EACtD,YAA4C,EAC5C,QAA+B;YAE/B,MAAM,UAAU,GACd,OAAO,mBAAmB,KAAK,QAAQ;gBACrC,CAAC,CAAC,OAAO,YAAY,KAAK,QAAQ;oBAChC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;oBAC5D,CAAC,CAAC,EAAE;gBACN,CAAC,CAAC,mBAAmB,CAAC;YAC1B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,UAAU,CAAC,SAAS,MAAM,mCAAmC,CAAC,CAAC;YAC3E,CAAC;YACD,MAAM,EAAE,GAAG,OAAO,mBAAmB,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC;YAC7E,IAAI,EAAE,KAAK,SAAS,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAC/C,MAAM,IAAI,SAAS,CAAC,SAAS,MAAM,yCAAyC,CAAC,CAAC;YAChF,CAAC;YACD,OAAO,IAAI,CAAC;gBACV,KAAK,EAAE;oBACL,GAAG,KAAK;oBACR;wBACE,IAAI;wBACJ,MAAM;wBACN,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;4BACvC,OAAO,EAAE,SAAS,CAAC,OAAO;4BAC1B,QAAQ,EAAE,SAAS,CAAC,QAAQ;yBAC7B,CAAC,CAAC;wBACH,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;qBACpC;iBACF;aACF,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;AACrF,CAAC"}

package/dist/comments/index.d.ts

@@ -0,0 +1,26 @@
+import { type CompiledQuery } from '../index.js';
+/** The closed sqlcommenter key set. */
+export type CommentKey = 'traceparent' | 'controller' | 'action' | 'route' | 'framework';
+/** Values available to one query execution. */
+export type CommentPairs = Readonly<Partial<Record<CommentKey, string>>>;
+/** A non-empty configured key list: absence, not an empty list, means off. */
+export type CommentKeys = readonly [CommentKey, ...CommentKey[]];
+interface ExecuteOptions {
+    readonly signal?: AbortSignal;
+    readonly batchSize?: number;
+}
+/** Serialize the inside of a sqlcommenter block in deterministic key order. */
+export declare function serializeComment(pairs: CommentPairs): string;
+/** Append one trailing sqlcommenter block, or return the original text unchanged. */
+export declare function appendComment(text: string, pairs: CommentPairs): string;
+/**
+ * Render request-scoped comments at execution time without mutating or widening
+ * the reusable compiled query.
+ */
+export declare function withComments<D extends {
+    execute(query: CompiledQuery, options?: ExecuteOptions): Promise<readonly Record<string, unknown>[]>;
+}>(driver: D, pairs: () => CommentPairs): D & {
+    execute(query: CompiledQuery, options?: ExecuteOptions): Promise<readonly Record<string, unknown>[]>;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/comments/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/comments/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAEzF,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAEzE,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;AAEjE,UAAU,cAAc;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAK5D;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAGvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS;IACR,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CACtG,EACD,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,YAAY;mBAGnB,aAAa,YAAY,cAAc,GAAG,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;EAKvG"}

package/dist/comments/index.js

@@ -0,0 +1,28 @@
+import {} from '../index.js';
+const encode = (value) => encodeURIComponent(value).replace(/'/g, "\\'");
+/** Serialize the inside of a sqlcommenter block in deterministic key order. */
+export function serializeComment(pairs) {
+    return Object.entries(pairs)
+        .toSorted(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, value]) => `${encode(key)}='${encode(value)}'`)
+        .join(',');
+}
+/** Append one trailing sqlcommenter block, or return the original text unchanged. */
+export function appendComment(text, pairs) {
+    const serialized = serializeComment(pairs);
+    return serialized.length === 0 ? text : `${text} /*${serialized}*/`;
+}
+/**
+ * Render request-scoped comments at execution time without mutating or widening
+ * the reusable compiled query.
+ */
+export function withComments(driver, pairs) {
+    return {
+        ...driver,
+        execute(query, options) {
+            const text = appendComment(query.text, pairs());
+            return driver.execute(text === query.text ? query : { ...query, text }, options);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/comments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/comments/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,MAAM,aAAa,CAAC;AAgBjD,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAEzF,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,KAAmB;IAClD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACzE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;SAC1D,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,KAAmB;IAC7D,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,UAAU,IAAI,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAI1B,MAAS,EAAE,KAAyB;IACpC,OAAO;QACL,GAAG,MAAM;QACT,OAAO,CAAC,KAAoB,EAAE,OAAwB;YACpD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAChD,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QACnF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/compiled-query.d.ts

@@ -0,0 +1,12 @@
+export interface CompiledQuery {
+    readonly text: string;
+    readonly parameters: readonly unknown[];
+    readonly telemetry?: QueryTelemetry;
+}
+/** Compile-time database attributes consumed by tracing and metrics. */
+export interface QueryTelemetry {
+    readonly system: string;
+    readonly operation: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+    readonly collection: string;
+}
+//# sourceMappingURL=compiled-query.d.ts.map

package/dist/compiled-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiled-query.d.ts","sourceRoot":"","sources":["../src/compiled-query.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/compiled-query.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compiled-query.js.map

package/dist/compiled-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiled-query.js","sourceRoot":"","sources":["../src/compiled-query.ts"],"names":[],"mappings":""}