@hypequery/clickhouse 2.4.0 → 2.5.1

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

@@ -0,0 +1,25 @@
+import { type CompiledIdentifiers, type CompiledOperation, type CompiledParameterDeclaration, type CompiledParameterValue, type CompiledQueryV1, type CompiledSensitivity, type CompiledSettings } from './types.js';
+export interface CompileQueryInput {
+    readonly operation: CompiledOperation;
+    /** Trusted build/server output. Callers never author this. */
+    readonly sql: string;
+    readonly parameters?: readonly CompiledParameterDeclaration[];
+    /** Values supplied for declared parameter names. */
+    readonly values?: Readonly<Record<string, CompiledParameterValue>>;
+    readonly settings?: CompiledSettings;
+    readonly sensitivity?: CompiledSensitivity;
+    /** Server-generated authoritative identifier; the caller may add a correlation id. */
+    readonly identifiers: CompiledIdentifiers;
+    readonly deadline?: {
+        readonly callerAtEpochMs?: number;
+        readonly policyMaxMs?: number;
+        readonly nowEpochMs: number;
+    };
+}
+/**
+ * Assemble and validate a `CompiledQueryV1` (RFC 0010). This constructs the execution
+ * request beside the legacy positional path; it performs every fail-closed check before an
+ * adapter is ever handed the query, but performs no I/O.
+ */
+export declare function compileQueryV1(input: CompileQueryInput): CompiledQueryV1;
+//# sourceMappingURL=compile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/compile.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAmBpB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAC9D,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,eAAe,CAqCxE"}

package/dist/core/compiled/compile.js

@@ -0,0 +1,134 @@
+import { buildDebugForm } from './debug.js';
+import { CompiledQueryError } from './errors.js';
+import { assertNoValuesInSql, buildParameterBindings, validateParameterReferences, } from './parameters.js';
+import { resolveCompiledDeadline, resolveCompiledSettings } from './settings.js';
+import { COMPILED_QUERY_VERSION, } from './types.js';
+const MAX_CORRELATION_ID_BYTES = 1024;
+const MAX_QUERY_ID_BYTES = 200;
+const MAX_SQL_BYTES = 1_048_576;
+const MAX_PARAMETERS = 256;
+const MAX_CLICKHOUSE_TYPE_BYTES = 256;
+const MAX_SENSITIVITY_LABELS = 32;
+const MAX_SENSITIVITY_LABEL_BYTES = 64;
+// eslint-disable-next-line no-control-regex -- control chars are exactly what we reject
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F-\u009F]/;
+const QUERY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const SENSITIVITY_LABEL_PATTERN = /^[a-z][a-z0-9._-]*$/;
+const LOGICAL_TYPES = new Set([
+    'array', 'boolean', 'bytes', 'date', 'datetime', 'decimal', 'enum', 'float',
+    'integer', 'map', 'null', 'string', 'tuple', 'uuid',
+]);
+const utf8 = new TextEncoder();
+/**
+ * Assemble and validate a `CompiledQueryV1` (RFC 0010). This constructs the execution
+ * request beside the legacy positional path; it performs every fail-closed check before an
+ * adapter is ever handed the query, but performs no I/O.
+ */
+export function compileQueryV1(input) {
+    validateOperation(input.operation);
+    validateSql(input.sql);
+    const parameters = snapshotParameters(input.parameters ?? []);
+    const values = input.values ?? {};
+    validateParameterReferences(input.sql, parameters);
+    const bindings = buildParameterBindings(parameters, values);
+    assertNoValuesInSql(input.sql, bindings);
+    const settings = resolveCompiledSettings(input.settings ?? {});
+    const identifiers = validateIdentifiers(input.identifiers);
+    const deadlineInputs = input.deadline
+        ? {
+            ...input.deadline,
+            policyMaxMs: minimumDefined(input.deadline.policyMaxMs, settings.maxExecutionMs),
+        }
+        : undefined;
+    const deadline = deadlineInputs
+        ? resolveCompiledDeadline(deadlineInputs)
+        : undefined;
+    const sensitivity = snapshotSensitivity(input.sensitivity);
+    const debug = buildDebugForm(input.sql, parameters, settings);
+    return Object.freeze({
+        version: COMPILED_QUERY_VERSION,
+        operation: input.operation,
+        sql: input.sql,
+        parameters,
+        bindings,
+        settings,
+        identifiers,
+        deadline,
+        sensitivity,
+        debug,
+    });
+}
+function minimumDefined(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    return Math.min(left, right);
+}
+function validateOperation(operation) {
+    if (operation !== 'query' && operation !== 'command' && operation !== 'insert') {
+        throw new CompiledQueryError('input-invalid', 'The compiled operation is invalid.');
+    }
+}
+function validateSql(sql) {
+    if (typeof sql !== 'string' || sql.length === 0 || utf8.encode(sql).length > MAX_SQL_BYTES) {
+        throw new CompiledQueryError('input-invalid', 'The compiled SQL is empty or too large.');
+    }
+}
+function snapshotParameters(input) {
+    if (!Array.isArray(input) || input.length > MAX_PARAMETERS) {
+        throw new CompiledQueryError('too-large', 'The compiled query has too many parameters.');
+    }
+    return Object.freeze(input.map((declaration) => {
+        const logical = declaration?.type?.logical;
+        const clickHouseType = declaration?.type?.clickHouseType;
+        if (!LOGICAL_TYPES.has(logical)
+            || typeof clickHouseType !== 'string'
+            || clickHouseType.length === 0
+            || CONTROL_CHAR_PATTERN.test(clickHouseType)
+            || utf8.encode(clickHouseType).length > MAX_CLICKHOUSE_TYPE_BYTES
+            || typeof declaration.optional !== 'boolean') {
+            throw new CompiledQueryError('input-invalid', 'A parameter declaration is invalid.');
+        }
+        return Object.freeze({
+            name: declaration.name,
+            type: Object.freeze({ logical, clickHouseType }),
+            optional: declaration.optional,
+        });
+    }));
+}
+function snapshotSensitivity(input) {
+    const tenantScoped = input?.tenantScoped ?? false;
+    const labels = input?.labels ?? [];
+    if (typeof tenantScoped !== 'boolean' || !Array.isArray(labels) || labels.length > MAX_SENSITIVITY_LABELS) {
+        throw new CompiledQueryError('input-invalid', 'Sensitivity metadata is invalid.');
+    }
+    const snapshot = labels.map((label) => {
+        if (typeof label !== 'string'
+            || !SENSITIVITY_LABEL_PATTERN.test(label)
+            || utf8.encode(label).length > MAX_SENSITIVITY_LABEL_BYTES) {
+            throw new CompiledQueryError('input-invalid', 'A sensitivity label is invalid.');
+        }
+        return label;
+    });
+    return Object.freeze({ tenantScoped, labels: Object.freeze(snapshot) });
+}
+function validateIdentifiers(identifiers) {
+    if (typeof identifiers.queryId !== 'string'
+        || !QUERY_ID_PATTERN.test(identifiers.queryId)
+        || utf8.encode(identifiers.queryId).length > MAX_QUERY_ID_BYTES) {
+        throw new CompiledQueryError('internal', 'A server-generated query id is required.');
+    }
+    const { correlationId } = identifiers;
+    if (correlationId !== undefined) {
+        if (CONTROL_CHAR_PATTERN.test(correlationId)) {
+            throw new CompiledQueryError('input-invalid', 'The correlation id contains control characters.');
+        }
+        if (utf8.encode(correlationId).length > MAX_CORRELATION_ID_BYTES) {
+            throw new CompiledQueryError('too-large', 'The correlation id exceeds the allowed size.');
+        }
+    }
+    return Object.freeze(correlationId === undefined
+        ? { queryId: identifiers.queryId }
+        : { queryId: identifiers.queryId, correlationId });
+}

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

@@ -0,0 +1,7 @@
+import type { CompiledDebugForm, CompiledParameterDeclaration, CompiledSettings } from './types.js';
+/**
+ * Build the redacted, non-executable debug form. It carries no parameter values, tenant
+ * values, credentials, or setting values — only names, declared types, and structure.
+ */
+export declare function buildDebugForm(sql: string, parameters: readonly CompiledParameterDeclaration[], settings: CompiledSettings): CompiledDebugForm;
+//# sourceMappingURL=debug.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,4BAA4B,EAAE,EACnD,QAAQ,EAAE,gBAAgB,GACzB,iBAAiB,CAkBnB"}

package/dist/core/compiled/debug.js

@@ -0,0 +1,25 @@
+import { replaceParameterPlaceholders } from './parameters.js';
+/**
+ * Marker wrapping placeholders in the debug form. The guillemets make the rendered SQL
+ * deliberately invalid as database SQL — it cannot be pasted into a client and run — while
+ * still showing structure and declared types (RFC 0010 §Debug form).
+ */
+const DEBUG_OPEN = '«param ';
+const DEBUG_CLOSE = '»';
+/**
+ * Build the redacted, non-executable debug form. It carries no parameter values, tenant
+ * values, credentials, or setting values — only names, declared types, and structure.
+ */
+export function buildDebugForm(sql, parameters, settings) {
+    const redactedSql = replaceParameterPlaceholders(sql, (name, type) => `${DEBUG_OPEN}${name}: ${type}${DEBUG_CLOSE}`);
+    return Object.freeze({
+        sql: redactedSql,
+        parameters: Object.freeze(parameters.map((p) => Object.freeze({
+            name: p.name,
+            type: p.type.clickHouseType,
+            optional: p.optional,
+        }))),
+        // Setting names only; values are policy and never appear in diagnostics.
+        settings: Object.freeze(Object.keys(settings).filter((key) => settings[key] !== undefined)),
+    });
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Public execution-failure envelope from RFC 0010 §Error envelope.
+ *
+ * The category set is closed and stable within version 1. It matches the frozen set in
+ * `@hypequery/protocol` (`events` module) so runtime failures and emitted diagnostics
+ * speak the same vocabulary. New categories require a new contract version.
+ */
+export declare const COMPILED_ERROR_CATEGORIES: readonly ["input-invalid", "unauthenticated", "forbidden", "tenant-required", "not-found", "too-large", "aborted", "deadline-exceeded", "unavailable", "internal"];
+export type CompiledErrorCategory = (typeof COMPILED_ERROR_CATEGORIES)[number];
+export declare function isCompiledErrorCategory(value: unknown): value is CompiledErrorCategory;
+export declare function isClientFaultCategory(category: CompiledErrorCategory): boolean;
+/** The stable, serializable error object surfaced to callers. */
+export interface CompiledErrorEnvelope {
+    readonly category: CompiledErrorCategory;
+    readonly message: string;
+    /** Authoritative query identifier; safe for logs. Absent only before one is assigned. */
+    readonly queryId?: string;
+}
+export interface CompiledQueryErrorOptions {
+    readonly queryId?: string;
+    /** Non-public cause retained for local logging; never serialized into the envelope. */
+    readonly cause?: unknown;
+}
+/**
+ * The only execution-failure shape a runtime may surface for a compiled query. For
+ * server-fault categories the caller-facing message is fixed to a generic string so no
+ * adapter text, SQL, value, or tenant identifier can leak.
+ */
+export declare class CompiledQueryError extends Error {
+    readonly category: CompiledErrorCategory;
+    readonly queryId?: string;
+    readonly cause?: unknown;
+    constructor(category: CompiledErrorCategory, message: string, options?: CompiledQueryErrorOptions);
+    private static resolveMessage;
+    /** The redacted, serializable envelope. Only closed fields; no `cause`, no stack. */
+    toEnvelope(): CompiledErrorEnvelope;
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,oKAW5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoB/E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAKtF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAE9E;AAED,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAGhC,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B;IAUzC,OAAO,CAAC,MAAM,CAAC,cAAc;IAY7B,qFAAqF;IACrF,UAAU,IAAI,qBAAqB;CAKpC"}

package/dist/core/compiled/errors.js

@@ -0,0 +1,91 @@
+/**
+ * Public execution-failure envelope from RFC 0010 §Error envelope.
+ *
+ * The category set is closed and stable within version 1. It matches the frozen set in
+ * `@hypequery/protocol` (`events` module) so runtime failures and emitted diagnostics
+ * speak the same vocabulary. New categories require a new contract version.
+ */
+export const COMPILED_ERROR_CATEGORIES = [
+    'input-invalid',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'not-found',
+    'too-large',
+    'aborted',
+    'deadline-exceeded',
+    'unavailable',
+    'internal',
+];
+/**
+ * Categories that describe a client-supplied fault. Their messages MAY carry a safe,
+ * caller-facing explanation. Every other category is a server/dependency fault whose
+ * message MUST NOT expose adapter error text, SQL, values, or tenant identifiers.
+ */
+const CLIENT_FAULT_CATEGORIES = new Set([
+    'input-invalid',
+    'unauthenticated',
+    'forbidden',
+    'tenant-required',
+    'not-found',
+    'too-large',
+    'aborted',
+    'deadline-exceeded',
+]);
+const SAFE_MESSAGE_PATTERN = /[\r\n\t]/;
+export function isCompiledErrorCategory(value) {
+    return (typeof value === 'string' &&
+        COMPILED_ERROR_CATEGORIES.includes(value));
+}
+export function isClientFaultCategory(category) {
+    return CLIENT_FAULT_CATEGORIES.has(category);
+}
+/**
+ * The only execution-failure shape a runtime may surface for a compiled query. For
+ * server-fault categories the caller-facing message is fixed to a generic string so no
+ * adapter text, SQL, value, or tenant identifier can leak.
+ */
+export class CompiledQueryError extends Error {
+    category;
+    queryId;
+    cause;
+    constructor(category, message, options = {}) {
+        const safeMessage = CompiledQueryError.resolveMessage(category, message);
+        super(safeMessage);
+        this.name = 'CompiledQueryError';
+        this.category = category;
+        this.queryId = options.queryId;
+        this.cause = options.cause;
+    }
+    static resolveMessage(category, message) {
+        if (!isClientFaultCategory(category)) {
+            // Server-fault categories never carry a caller-authored message.
+            return DEFAULT_SERVER_FAULT_MESSAGE[category] ?? 'The request could not be completed.';
+        }
+        const trimmed = typeof message === 'string' ? message.trim() : '';
+        if (trimmed.length === 0 || SAFE_MESSAGE_PATTERN.test(trimmed)) {
+            return DEFAULT_CLIENT_FAULT_MESSAGE[category] ?? 'The request was rejected.';
+        }
+        return trimmed;
+    }
+    /** The redacted, serializable envelope. Only closed fields; no `cause`, no stack. */
+    toEnvelope() {
+        return this.queryId === undefined
+            ? { category: this.category, message: this.message }
+            : { category: this.category, message: this.message, queryId: this.queryId };
+    }
+}
+const DEFAULT_CLIENT_FAULT_MESSAGE = {
+    'input-invalid': 'The request parameters were invalid.',
+    unauthenticated: 'Authentication is required.',
+    forbidden: 'Access is denied.',
+    'tenant-required': 'A tenant context is required.',
+    'not-found': 'The requested resource was not found.',
+    'too-large': 'The request or result exceeded an allowed bound.',
+    aborted: 'The request was cancelled.',
+    'deadline-exceeded': 'The request deadline was exceeded.',
+};
+const DEFAULT_SERVER_FAULT_MESSAGE = {
+    unavailable: 'The executor is temporarily unavailable.',
+    internal: 'The request could not be completed.',
+};

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

@@ -0,0 +1,15 @@
+/**
+ * CompiledQuery v1 (RFC 0010) — the versioned execution-request contract for the
+ * ClickHouse runtime, introduced beside the legacy positional path. See `./types.ts`.
+ *
+ * CH-01 provides the shape, validation, and redacted debug/error surfaces. Wiring the real
+ * `@clickhouse/client` `{name:Type}` + `query_params` transport, capability negotiation,
+ * and end-to-end cancellation is CH-02+ and does not touch the legacy adapter signature.
+ */
+export { COMPILED_QUERY_VERSION, type CompiledDeadline, type CompiledDebugForm, type CompiledIdentifiers, type CompiledOperation, type CompiledParameterBindings, type CompiledParameterDeclaration, type CompiledParameterType, type CompiledParameterValue, type CompiledQueryV1, type CompiledSensitivity, type CompiledSettings, } from './types.js';
+export { compileQueryV1, type CompileQueryInput } from './compile.js';
+export { assertNoValuesInSql, buildParameterBindings, extractReferencedParameters, validateParameterReferences, } from './parameters.js';
+export { COMPILED_SETTING_BOUNDS, type CompiledSettingName, type DeadlineInputs, type SettingBound, resolveCompiledDeadline, resolveCompiledSettings, } from './settings.js';
+export { COMPILED_ERROR_CATEGORIES, CompiledQueryError, type CompiledErrorCategory, type CompiledErrorEnvelope, type CompiledQueryErrorOptions, isClientFaultCategory, isCompiledErrorCategory, } from './errors.js';
+export { buildDebugForm } from './debug.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,yBAAyB,EACzB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/compiled/index.js

@@ -0,0 +1,14 @@
+/**
+ * CompiledQuery v1 (RFC 0010) — the versioned execution-request contract for the
+ * ClickHouse runtime, introduced beside the legacy positional path. See `./types.ts`.
+ *
+ * CH-01 provides the shape, validation, and redacted debug/error surfaces. Wiring the real
+ * `@clickhouse/client` `{name:Type}` + `query_params` transport, capability negotiation,
+ * and end-to-end cancellation is CH-02+ and does not touch the legacy adapter signature.
+ */
+export { COMPILED_QUERY_VERSION, } from './types.js';
+export { compileQueryV1 } from './compile.js';
+export { assertNoValuesInSql, buildParameterBindings, extractReferencedParameters, validateParameterReferences, } from './parameters.js';
+export { COMPILED_SETTING_BOUNDS, resolveCompiledDeadline, resolveCompiledSettings, } from './settings.js';
+export { COMPILED_ERROR_CATEGORIES, CompiledQueryError, isClientFaultCategory, isCompiledErrorCategory, } from './errors.js';
+export { buildDebugForm } from './debug.js';

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

@@ -0,0 +1,28 @@
+import type { CompiledParameterBindings, CompiledParameterDeclaration, CompiledParameterValue } from './types.js';
+/** Extract the set of parameter names a SQL text references via `{name:Type}`. */
+export declare function extractReferencedParameters(sql: string): Set<string>;
+export declare function replaceParameterPlaceholders(sql: string, replace: (name: string, type: string) => string): string;
+/**
+ * Validate that the SQL only references declared parameters. Fails closed when a
+ * placeholder names an undeclared parameter (RFC 0010 §Parameters).
+ */
+export declare function validateParameterReferences(sql: string, declarations: readonly CompiledParameterDeclaration[]): void;
+/**
+ * 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 declare function buildParameterBindings(declarations: readonly CompiledParameterDeclaration[], values: Readonly<Record<string, CompiledParameterValue>>): CompiledParameterBindings;
+/**
+ * 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 declare function assertNoValuesInSql(sql: string, bindings: CompiledParameterBindings): void;
+//# sourceMappingURL=parameters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../src/core/compiled/parameters.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAsIpB,kFAAkF;AAClF,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEpE;AAED,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAC9C,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,SAAS,4BAA4B,EAAE,GACpD,IAAI,CAoBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,SAAS,4BAA4B,EAAE,EACrD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,GACvD,yBAAyB,CAyC3B;AAmFD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,yBAAyB,GAClC,IAAI,CAyBN"}