@hypequery/clickhouse 2.4.0 → 2.5.1

package/dist/core/compiled/parameters.js

@@ -0,0 +1,282 @@
+import { ProtocolValueError, isProtocolIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+import { CompiledQueryError } from './errors.js';
+const LOGICAL_TYPES = new Set([
+    'array', 'boolean', 'bytes', 'date', 'datetime', 'decimal', 'enum', 'float',
+    'integer', 'map', 'null', 'string', 'tuple', 'uuid',
+]);
+function skipQuoted(sql, start, quote) {
+    let index = start + 1;
+    while (index < sql.length) {
+        if (sql[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (sql[index] === quote) {
+            if (sql[index + 1] === quote) {
+                index += 2;
+                continue;
+            }
+            return index + 1;
+        }
+        index += 1;
+    }
+    return sql.length;
+}
+function parsePlaceholder(sql, start) {
+    let index = start + 1;
+    while (/\s/.test(sql[index] ?? ''))
+        index += 1;
+    const nameStart = index;
+    if (!/[A-Za-z_]/.test(sql[index] ?? ''))
+        return undefined;
+    index += 1;
+    while (/[A-Za-z0-9_]/.test(sql[index] ?? ''))
+        index += 1;
+    const name = sql.slice(nameStart, index);
+    while (/\s/.test(sql[index] ?? ''))
+        index += 1;
+    if (sql[index] !== ':')
+        return undefined;
+    index += 1;
+    const typeStart = index;
+    let quote;
+    let parenthesisDepth = 0;
+    while (index < sql.length) {
+        const character = sql[index];
+        if (quote) {
+            if (character === '\\') {
+                index += 2;
+                continue;
+            }
+            if (character === quote) {
+                if (sql[index + 1] === quote) {
+                    index += 2;
+                    continue;
+                }
+                quote = undefined;
+            }
+            index += 1;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            index += 1;
+            continue;
+        }
+        if (character === '(')
+            parenthesisDepth += 1;
+        if (character === ')') {
+            parenthesisDepth -= 1;
+            if (parenthesisDepth < 0)
+                return undefined;
+        }
+        if (character === '{')
+            return undefined;
+        if (character === '}' && parenthesisDepth === 0) {
+            const type = sql.slice(typeStart, index).trim();
+            if (type.length === 0)
+                return undefined;
+            return { name, type, start, end: index + 1 };
+        }
+        index += 1;
+    }
+    return undefined;
+}
+function scanSqlParameters(sql) {
+    const references = [];
+    let hasPositionalPlaceholder = false;
+    let index = 0;
+    while (index < sql.length) {
+        const character = sql[index];
+        if (character === "'" || character === '"' || character === '`') {
+            index = skipQuoted(sql, index, character);
+            continue;
+        }
+        if (character === '-' && sql[index + 1] === '-') {
+            const newline = sql.indexOf('\n', index + 2);
+            index = newline === -1 ? sql.length : newline + 1;
+            continue;
+        }
+        if (character === '#') {
+            const newline = sql.indexOf('\n', index + 1);
+            index = newline === -1 ? sql.length : newline + 1;
+            continue;
+        }
+        if (character === '/' && sql[index + 1] === '*') {
+            const close = sql.indexOf('*/', index + 2);
+            index = close === -1 ? sql.length : close + 2;
+            continue;
+        }
+        if (character === '?')
+            hasPositionalPlaceholder = true;
+        if (character === '{') {
+            const reference = parsePlaceholder(sql, index);
+            if (reference) {
+                references.push(reference);
+                index = reference.end;
+                continue;
+            }
+        }
+        index += 1;
+    }
+    return { references, hasPositionalPlaceholder };
+}
+/** Extract the set of parameter names a SQL text references via `{name:Type}`. */
+export function extractReferencedParameters(sql) {
+    return new Set(scanSqlParameters(sql).references.map(({ name }) => name));
+}
+export function replaceParameterPlaceholders(sql, replace) {
+    const references = scanSqlParameters(sql).references;
+    let result = '';
+    let offset = 0;
+    for (const reference of references) {
+        result += sql.slice(offset, reference.start);
+        result += replace(reference.name, reference.type);
+        offset = reference.end;
+    }
+    return result + sql.slice(offset);
+}
+/**
+ * Validate that the SQL only references declared parameters. Fails closed when a
+ * placeholder names an undeclared parameter (RFC 0010 §Parameters).
+ */
+export function validateParameterReferences(sql, declarations) {
+    const declared = new Map(declarations.map((declaration) => [
+        declaration.name,
+        declaration,
+    ]));
+    for (const reference of scanSqlParameters(sql).references) {
+        const declaration = declared.get(reference.name);
+        if (!declaration) {
+            throw new CompiledQueryError('input-invalid', `SQL references undeclared parameter ${reference.name}.`);
+        }
+        if (reference.type !== declaration.type.clickHouseType) {
+            throw new CompiledQueryError('input-invalid', `SQL parameter ${reference.name} does not match its declared ClickHouse type.`);
+        }
+    }
+}
+/**
+ * Resolve supplied values against declarations into the native `{name: value}` bindings
+ * an adapter binds to server parameters. Fail-closed rules (RFC 0010 §Parameters):
+ *   - a supplied name that is not declared is rejected;
+ *   - a required declared name with no supplied value is rejected;
+ *   - an optional declared name may be absent;
+ *   - every supplied value is validated (RFC 0001 for tagged values).
+ *
+ * No value is ever concatenated into SQL text: values live only in the returned bindings.
+ */
+export function buildParameterBindings(declarations, values) {
+    const declaredByName = new Map();
+    for (const declaration of declarations) {
+        if (!isProtocolIdentifier(declaration.name)) {
+            throw new CompiledQueryError('input-invalid', 'Parameter declaration has an invalid name.');
+        }
+        if (declaredByName.has(declaration.name)) {
+            throw new CompiledQueryError('input-invalid', `Duplicate parameter declaration ${declaration.name}.`);
+        }
+        declaredByName.set(declaration.name, declaration);
+    }
+    for (const suppliedName of Object.keys(values)) {
+        if (!declaredByName.has(suppliedName)) {
+            throw new CompiledQueryError('input-invalid', `Value supplied for undeclared parameter ${suppliedName}.`);
+        }
+    }
+    const bindings = {};
+    for (const [name, declaration] of declaredByName) {
+        const present = Object.prototype.hasOwnProperty.call(values, name);
+        if (!present) {
+            if (declaration.optional)
+                continue;
+            throw new CompiledQueryError('input-invalid', `Required parameter ${name} is missing.`);
+        }
+        bindings[name] = validateParameterValue(name, declaration, values[name]);
+    }
+    return Object.freeze(bindings);
+}
+function validateParameterValue(name, declaration, value) {
+    try {
+        const validated = validateCanonicalValue(value, {
+            declaredClickHouseType: declaration.type.clickHouseType,
+        });
+        validateLogicalType(name, declaration, validated);
+        return validated;
+    }
+    catch (error) {
+        if (error instanceof ProtocolValueError) {
+            throw new CompiledQueryError('input-invalid', `Parameter ${name} failed value validation (${error.code}).`, { cause: error });
+        }
+        throw error;
+    }
+}
+function logicalTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'float';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    return value.$hypequery.type;
+}
+function unwrapNullable(type) {
+    const trimmed = type.trim();
+    if (trimmed.startsWith('Nullable(') && trimmed.endsWith(')')) {
+        return { nullable: true, inner: trimmed.slice(9, -1).trim() };
+    }
+    return { nullable: false, inner: trimmed };
+}
+function clickHouseTypeSupportsLogical(type, logical) {
+    const { nullable, inner } = unwrapNullable(type);
+    if (logical === 'null')
+        return nullable;
+    switch (logical) {
+        case 'string': return /^(?:String|FixedString\(\d+\)|LowCardinality\(String\))$/.test(inner);
+        case 'float': return /^Float(?:32|64)$/.test(inner);
+        case 'boolean': return /^(?:Bool|Boolean)$/.test(inner);
+        case 'integer': return /^(?:U?Int)(?:8|16|32|64|128|256)$/.test(inner);
+        case 'decimal': return /^Decimal(?:(?:32|64|128|256)\(\d+\)|\(\d+\s*,\s*\d+\))$/.test(inner);
+        case 'date': return /^(?:Date|Date32)$/.test(inner);
+        case 'datetime': return /^DateTime(?:64)?(?:\(.*\))?$/.test(inner);
+        case 'uuid': return inner === 'UUID';
+        case 'bytes': return /^(?:String|FixedString\(\d+\))$/.test(inner);
+        case 'enum': return /^Enum(?:8|16)\(.*\)$/.test(inner);
+        case 'array': return /^Array\(.+\)$/.test(inner);
+        case 'tuple': return /^Tuple\(.+\)$/.test(inner);
+        case 'map': return /^Map\(.+\)$/.test(inner);
+        default: return false;
+    }
+}
+function validateLogicalType(name, declaration, value) {
+    const actual = logicalTypeOf(value);
+    const declared = declaration.type.logical;
+    if (!LOGICAL_TYPES.has(declared) || (actual !== declared && actual !== 'null')) {
+        throw new CompiledQueryError('input-invalid', `Parameter ${name} does not match its declared logical type.`);
+    }
+    if (!clickHouseTypeSupportsLogical(declaration.type.clickHouseType, actual)) {
+        throw new CompiledQueryError('input-invalid', `Parameter ${name} does not match its declared ClickHouse type.`);
+    }
+}
+/**
+ * Assert the invariant that no bound value has leaked into the SQL text. The compile path
+ * never substitutes values, so this is a defense-in-depth check: the SQL must reference
+ * every non-optional bound name through a placeholder and must not be the legacy
+ * positional form (`?`).
+ */
+export function assertNoValuesInSql(sql, bindings) {
+    const scan = scanSqlParameters(sql);
+    if (scan.hasPositionalPlaceholder) {
+        throw new CompiledQueryError('input-invalid', 'Compiled SQL must not use positional placeholders.');
+    }
+    const referenced = new Set(scan.references.map(({ name }) => name));
+    for (const name of Object.keys(bindings)) {
+        if (!referenced.has(name)) {
+            throw new CompiledQueryError('input-invalid', `Bound parameter ${name} is not referenced by the SQL.`);
+        }
+    }
+    for (const name of referenced) {
+        if (!Object.prototype.hasOwnProperty.call(bindings, name)) {
+            throw new CompiledQueryError('input-invalid', `SQL parameter ${name} does not have a bound value.`);
+        }
+    }
+}

package/dist/core/compiled/settings.d.ts

@@ -0,0 +1,49 @@
+import type { CompiledDeadline, CompiledSettings } from './types.js';
+/**
+ * Closed, typed settings allow-list (RFC 0010 §Settings). Each entry defines an inclusive
+ * range; products may TIGHTEN a range but never loosen it. Settings originate only from
+ * trusted components — a request can never set, override, or relax them.
+ */
+export interface SettingBound {
+    readonly min: number;
+    readonly max: number;
+}
+export declare const COMPILED_SETTING_BOUNDS: Readonly<{
+    readonly maxExecutionMs: {
+        readonly min: 1;
+        readonly max: 3600000;
+    };
+    readonly maxResultRows: {
+        readonly min: 0;
+        readonly max: 1000000000000;
+    };
+    readonly maxResultBytes: {
+        readonly min: 0;
+        readonly max: 1099511627776;
+    };
+}>;
+export type CompiledSettingName = keyof typeof COMPILED_SETTING_BOUNDS;
+/**
+ * Clamp trusted settings into the allow-list. A value outside the closed range is
+ * rejected fail-closed rather than silently coerced, since settings are trusted input and
+ * an out-of-range value signals a policy bug, not caller data.
+ */
+export declare function resolveCompiledSettings(input: CompiledSettings): CompiledSettings;
+export interface DeadlineInputs {
+    /** Absolute caller-supplied deadline, epoch-millis. */
+    readonly callerAtEpochMs?: number;
+    /** Policy-derived maximum window from `now`, milliseconds. */
+    readonly policyMaxMs?: number;
+    /** Current time, epoch-millis. Injected so resolution stays deterministic/testable. */
+    readonly nowEpochMs: number;
+}
+/**
+ * Resolve the effective deadline (RFC 0010 §Deadline and cancellation precedence).
+ *
+ * The effective deadline is the EARLIER of the caller-supplied deadline and the
+ * policy-derived maximum — a caller can shorten but never extend the window. A supplied
+ * deadline at or before `now` fails immediately with `deadline-exceeded` rather than being
+ * extended or ignored.
+ */
+export declare function resolveCompiledDeadline(inputs: DeadlineInputs): CompiledDeadline | undefined;
+//# sourceMappingURL=settings.d.ts.map

package/dist/core/compiled/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;EAI8B,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,uBAAuB,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAejF;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,SAAS,CAyC5F"}

package/dist/core/compiled/settings.js

@@ -0,0 +1,65 @@
+import { CompiledQueryError } from './errors.js';
+export const COMPILED_SETTING_BOUNDS = Object.freeze({
+    maxExecutionMs: { min: 1, max: 3_600_000 },
+    maxResultRows: { min: 0, max: 1_000_000_000_000 },
+    maxResultBytes: { min: 0, max: 1_099_511_627_776 },
+});
+/**
+ * Clamp trusted settings into the allow-list. A value outside the closed range is
+ * rejected fail-closed rather than silently coerced, since settings are trusted input and
+ * an out-of-range value signals a policy bug, not caller data.
+ */
+export function resolveCompiledSettings(input) {
+    const resolved = {};
+    for (const key of Object.keys(COMPILED_SETTING_BOUNDS)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        const bound = COMPILED_SETTING_BOUNDS[key];
+        if (!Number.isInteger(value) || value < bound.min || value > bound.max) {
+            throw new CompiledQueryError('input-invalid', `Setting ${key} is outside its allowed range.`);
+        }
+        resolved[key] = value;
+    }
+    return Object.freeze(resolved);
+}
+/**
+ * Resolve the effective deadline (RFC 0010 §Deadline and cancellation precedence).
+ *
+ * The effective deadline is the EARLIER of the caller-supplied deadline and the
+ * policy-derived maximum — a caller can shorten but never extend the window. A supplied
+ * deadline at or before `now` fails immediately with `deadline-exceeded` rather than being
+ * extended or ignored.
+ */
+export function resolveCompiledDeadline(inputs) {
+    const { callerAtEpochMs, policyMaxMs, nowEpochMs } = inputs;
+    if (!Number.isSafeInteger(nowEpochMs) || nowEpochMs < 0) {
+        throw new CompiledQueryError('input-invalid', 'The current time is invalid.');
+    }
+    if (callerAtEpochMs !== undefined
+        && (!Number.isSafeInteger(callerAtEpochMs) || callerAtEpochMs < 0)) {
+        throw new CompiledQueryError('input-invalid', 'The supplied deadline is invalid.');
+    }
+    if (policyMaxMs !== undefined && (!Number.isSafeInteger(policyMaxMs) || policyMaxMs <= 0)) {
+        throw new CompiledQueryError('input-invalid', 'The policy deadline window is invalid.');
+    }
+    const policyAt = policyMaxMs === undefined ? undefined : nowEpochMs + policyMaxMs;
+    if (policyAt !== undefined && !Number.isSafeInteger(policyAt)) {
+        throw new CompiledQueryError('input-invalid', 'The policy deadline is outside the safe range.');
+    }
+    if (callerAtEpochMs !== undefined && callerAtEpochMs <= nowEpochMs) {
+        throw new CompiledQueryError('deadline-exceeded', 'The supplied deadline is at or before the current time.');
+    }
+    if (callerAtEpochMs === undefined && policyAt === undefined) {
+        return undefined;
+    }
+    if (callerAtEpochMs === undefined) {
+        return Object.freeze({ atEpochMs: policyAt, source: 'policy' });
+    }
+    if (policyAt === undefined) {
+        return Object.freeze({ atEpochMs: callerAtEpochMs, source: 'caller' });
+    }
+    return Object.freeze(callerAtEpochMs <= policyAt
+        ? { atEpochMs: callerAtEpochMs, source: 'caller' }
+        : { atEpochMs: policyAt, source: 'policy' });
+}

package/dist/core/compiled/types.d.ts

@@ -0,0 +1,115 @@
+import type { ProtocolIdentifier, TaggedValue } from '@hypequery/protocol';
+/**
+ * Execution-request contract from RFC 0010 (compiled query, error, cancellation),
+ * realized for the ClickHouse runtime.
+ *
+ * This is the versioned shape a runtime hands to an adapter. It sits *beside* the
+ * legacy positional path (`adapter.query(sql, params: unknown[])`, which renders
+ * values into SQL text via `substituteParameters`). Nothing here lets a request
+ * author SQL, tenant proof, or settings — those are trusted build/policy output.
+ *
+ * NOTE: distinct from the internal `CompiledQuery` in `../../types/base.ts`, which
+ * is the SQL-formatter fragment `{ query, parameters }`.
+ */
+export declare const COMPILED_QUERY_VERSION: 1;
+/** Closed operation set (RFC 0010 §Operations). The operation belongs to the compiled
+ * query, never to the request. */
+export type CompiledOperation = 'query' | 'command' | 'insert';
+/**
+ * A logical parameter type. The logical tag drives validation and the `{name:Type}`
+ * placeholder the adapter sends; `clickHouseType` is the concrete server type string
+ * (e.g. `UInt64`, `DateTime64(3, 'UTC')`, `Array(String)`).
+ */
+export interface CompiledParameterType {
+    /** RFC 0001 logical tag, or a scalar shorthand for native JSON scalars. */
+    readonly logical: TaggedValue['$hypequery']['type'] | 'boolean' | 'string' | 'float' | 'null';
+    /** Concrete ClickHouse server type used to build the native placeholder. */
+    readonly clickHouseType: string;
+}
+/**
+ * A named, typed parameter declaration carried beside the SQL text. A request supplies
+ * only values for declared names; it can neither add names nor change types.
+ */
+export interface CompiledParameterDeclaration {
+    readonly name: ProtocolIdentifier;
+    readonly type: CompiledParameterType;
+    /** Optional parameters may be absent from a request; required ones fail closed. */
+    readonly optional: boolean;
+}
+/** A supplied parameter value: an RFC 0001 tagged value or a native JSON scalar. */
+export type CompiledParameterValue = TaggedValue | string | number | boolean | null;
+/**
+ * The resolved `{name: value}` map the adapter binds to native server parameters.
+ * Every key is a declared parameter name; no value is ever rendered into SQL text.
+ */
+export type CompiledParameterBindings = Readonly<Record<string, CompiledParameterValue>>;
+/**
+ * Data sensitivity metadata. Marks whether the query touches tenant-scoped or otherwise
+ * sensitive data so diagnostics/redaction downstream can act without inspecting values.
+ */
+export interface CompiledSensitivity {
+    /** The compiled SQL already contains trusted tenant predicates (RFC 0010 §Operations). */
+    readonly tenantScoped: boolean;
+    /** Free-form trusted classification labels (e.g. 'pii'); never request-supplied. */
+    readonly labels: readonly string[];
+}
+/**
+ * Bounded settings the runtime applies per execution. These originate only from trusted
+ * components; a request can never set, override, or relax them. See `settings.ts` for the
+ * closed allow-list and ranges.
+ */
+export interface CompiledSettings {
+    /** Wall-clock ceiling for server-side execution, milliseconds. Always enforced. */
+    readonly maxExecutionMs?: number;
+    /** Maximum rows the result may contain. */
+    readonly maxResultRows?: number;
+    /** Maximum bytes the result may contain. */
+    readonly maxResultBytes?: number;
+}
+/** Effective deadline + cancellation inputs (RFC 0010 §Deadline and cancellation). */
+export interface CompiledDeadline {
+    /** Epoch-millis absolute deadline. Earlier of caller-supplied and policy-derived. */
+    readonly atEpochMs: number;
+    /** Which side set the effective deadline, for honest diagnostics. */
+    readonly source: 'caller' | 'policy';
+}
+/** Authoritative + optional correlation identifiers (RFC 0010 §Query identifier). */
+export interface CompiledIdentifiers {
+    /** Server-generated, unique per execution, unguessable, safe for logs/cache metadata. */
+    readonly queryId: string;
+    /** Caller-supplied, non-authoritative, ≤1024 UTF-8 bytes, no control chars; never
+     * influences routing, cache keys, or authorization. */
+    readonly correlationId?: string;
+}
+/**
+ * Redacted, non-executable debug form (RFC 0010 §Debug form). Shows SQL structure with
+ * placeholders and declared types; carries no values, tenant values, credentials, or
+ * settings beyond their names. `sql` here is deliberately not valid database SQL.
+ */
+export interface CompiledDebugForm {
+    readonly sql: string;
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly type: string;
+        readonly optional: boolean;
+    }[];
+    readonly settings: readonly string[];
+}
+/**
+ * The compiled query: the only way a runtime asks a ClickHouse adapter to execute.
+ */
+export interface CompiledQueryV1 {
+    readonly version: typeof COMPILED_QUERY_VERSION;
+    readonly operation: CompiledOperation;
+    /** Trusted build/server output. Callers influence execution only via `bindings`. */
+    readonly sql: string;
+    readonly parameters: readonly CompiledParameterDeclaration[];
+    /** Resolved values for declared names, bound to native server parameters. */
+    readonly bindings: CompiledParameterBindings;
+    readonly settings: CompiledSettings;
+    readonly identifiers: CompiledIdentifiers;
+    readonly deadline?: CompiledDeadline;
+    readonly sensitivity: CompiledSensitivity;
+    readonly debug: CompiledDebugForm;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/compiled/types.d.ts.map

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

package/dist/core/compiled/types.js

@@ -0,0 +1,13 @@
+/**
+ * Execution-request contract from RFC 0010 (compiled query, error, cancellation),
+ * realized for the ClickHouse runtime.
+ *
+ * This is the versioned shape a runtime hands to an adapter. It sits *beside* the
+ * legacy positional path (`adapter.query(sql, params: unknown[])`, which renders
+ * values into SQL text via `substituteParameters`). Nothing here lets a request
+ * author SQL, tenant proof, or settings — those are trusted build/policy output.
+ *
+ * NOTE: distinct from the internal `CompiledQuery` in `../../types/base.ts`, which
+ * is the SQL-formatter fragment `{ query, parameters }`.
+ */
+export const COMPILED_QUERY_VERSION = 1;

package/dist/core/features/analytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,qBAAa,gBAAgB,CAC3B,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC;IAExF,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAExD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,EAAE,eAAe,CAAC,GAAG,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAStH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IASnG,eAAe,CACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,EAC9J,OAAO,EAAE,UAAU,GAClB,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAa3C,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAUhF"}
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,qBAAa,gBAAgB,CAC3B,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC;IAExF,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAExD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,EAAE,eAAe,CAAC,GAAG,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAStH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAYnG,eAAe,CACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,EAC9J,OAAO,EAAE,UAAU,GAClB,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAa3C,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAUhF"}

package/dist/core/features/analytics.js

@@ -1,4 +1,5 @@
 import { substituteParameters } from '../utils.js';
+import { terminateTrailingLineComment } from '../utils/sql-parens.js';
 export class AnalyticsFeature {
     builder;
     constructor(builder) {
@@ -14,7 +15,7 @@ export class AnalyticsFeature {
     }
     addScalar(alias, expression) {
         const query = this.builder.getQueryNode();
-        const scalarExpression = substituteParameters(expression.sql, expression.parameters);
+        const scalarExpression = substituteParameters(terminateTrailingLineComment(expression.sql), expression.parameters);
         return {
             ...query,
             ctes: [...(query.ctes || []), { kind: 'cte', expression: `${scalarExpression} AS ${alias}` }]

package/dist/core/formatters/sql-formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-formatter.d.ts","sourceRoot":"","sources":["../../../src/core/formatters/sql-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAkB,MAAM,sBAAsB,CAAC;AAEhJ,qBAAa,YAAY;IACvB,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAMtD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAMvD,gBAAgB,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAO1D,cAAc,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIxD,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIrD,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM;IAUvC,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,UAAQ,GAAG,aAAa;IAoD3D,OAAO,CAAC,gBAAgB;IAuFxB,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,aAAa;IAY9D,OAAO,CAAC,cAAc;IActB,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,aAAa;IAkB7D,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIrD,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAKpD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAOvD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAKvD,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,4BAA4B;CAMrC"}
+{"version":3,"file":"sql-formatter.d.ts","sourceRoot":"","sources":["../../../src/core/formatters/sql-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAkB,MAAM,sBAAsB,CAAC;AAGhJ,qBAAa,YAAY;IACvB,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAMtD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAMvD,gBAAgB,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAO1D,cAAc,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIxD,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIrD,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM;IAUvC,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,UAAQ,GAAG,aAAa;IA0D3D,OAAO,CAAC,gBAAgB;IAuFxB,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,aAAa;IAkB9D,OAAO,CAAC,cAAc;IActB,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,aAAa;IAkB7D,WAAW,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAIrD,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAKpD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAOvD,aAAa,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAKvD,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,4BAA4B;CAMrC"}

package/dist/core/formatters/sql-formatter.js

@@ -1,3 +1,4 @@
+import { hasTopLevelLogicalOperator, terminateTrailingLineComment } from '../utils/sql-parens.js';
 export class SQLFormatter {
     formatSelect(query) {
         const distinctClause = query.distinct ? 'DISTINCT ' : '';
@@ -38,11 +39,17 @@ export class SQLFormatter {
         if (!expr)
             return { query: '', parameters: [] };
         switch (expr.kind) {
-            case 'raw':
+            case 'raw': {
+                // A raw fragment with a top-level AND/OR would rebind against sibling
+                // conditions when embedded in a sequence (issue #348), so wrap it.
+                const rawExpression = terminateTrailingLineComment(expr.expression);
                 return {
-                    query: expr.expression,
+                    query: nested && hasTopLevelLogicalOperator(rawExpression)
+                        ? `(${rawExpression})`
+                        : rawExpression,
                     parameters: expr.parameters.map(parameter => parameter.value),
                 };
+            }
             case 'group': {
                 if (!expr.expression) {
                     return { query: '', parameters: [] };
@@ -173,10 +180,16 @@ export class SQLFormatter {
     compileHaving(query) {
         if (!query.having?.length)
             return { query: '', parameters: [] };
-        return this.combineCompiledWithSeparator(query.having.map(item => ({
-            query: item.expression,
-            parameters: item.parameters?.map(parameter => parameter.value) || [],
-        })), ' AND ');
+        const wrapFragments = query.having.length > 1;
+        return this.combineCompiledWithSeparator(query.having.map(item => {
+            const expression = terminateTrailingLineComment(item.expression);
+            return {
+                query: wrapFragments && hasTopLevelLogicalOperator(expression)
+                    ? `(${expression})`
+                    : expression,
+                parameters: item.parameters?.map(parameter => parameter.value) || [],
+            };
+        }), ' AND ');
     }
     getSqlOperator(operator) {
         switch (operator) {