@hypequery/clickhouse 2.10.1 → 2.11.1

package/dist/core/utils/named-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-parameters.d.ts","sourceRoot":"","sources":["../../../src/core/utils/named-parameters.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,UAAU,EAAE,OAAO,EAAE,CAAC;CACvB;AAoDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,SAAQ,GACd,qBAAqB,CAgDvB"}

package/dist/core/utils/named-parameters.js

@@ -0,0 +1,108 @@
+import { escapeValue } from '../utils.js';
+import { skipNonCode } from './sql-parens.js';
+import { serializeCompoundParameter } from './compound-parameter.js';
+const IDENTIFIER_START = /[A-Za-z_]/;
+const IDENTIFIER_CHAR = /[A-Za-z0-9_]/;
+function readIdentifier(sql, start) {
+    if (!IDENTIFIER_START.test(sql[start] ?? ''))
+        return undefined;
+    let i = start + 1;
+    while (i < sql.length && IDENTIFIER_CHAR.test(sql[i]))
+        i += 1;
+    return sql.slice(start, i);
+}
+/**
+ * Reads a `{name:Type}` placeholder starting at the `{`. The type is consumed
+ * with paren nesting so `{ids:Array(UInt64)}` matches, and anything that is not
+ * shaped like a placeholder — a `{shard}` macro, a brace in an expression —
+ * returns undefined so it is left untouched.
+ */
+function matchPlaceholder(sql, start) {
+    const name = readIdentifier(sql, start + 1);
+    if (name === undefined)
+        return undefined;
+    let i = start + 1 + name.length;
+    if (sql[i] !== ':')
+        return undefined;
+    i += 1;
+    const typeStart = i;
+    let depth = 0;
+    while (i < sql.length) {
+        const skippedTo = skipNonCode(sql, i);
+        if (skippedTo !== undefined) {
+            i = skippedTo;
+            continue;
+        }
+        const ch = sql[i];
+        if (ch === '{')
+            return undefined;
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')')
+            depth -= 1;
+        else if (ch === '}' && depth === 0) {
+            const type = sql.slice(typeStart, i).trim();
+            return type ? { name, type, end: i + 1 } : undefined;
+        }
+        i += 1;
+    }
+    return undefined;
+}
+/**
+ * Rewrites ClickHouse-style `{name:Type}` placeholders to the positional `?`
+ * markers the builder binds against, pairing each with its value.
+ *
+ * TODO: Remove this client-side rewrite and its CAST/compound serialization
+ * once native server-side query_params binding replaces positional parameters.
+ * The public {name:Type} placeholder API can stay unchanged.
+ *
+ * Each marker is wrapped in a `CAST` to the declared type, which is what the
+ * server's own `{name:Type}` substitution does. Without it the value arrives as
+ * a String and any expression that depends on the real type fails to compile.
+ *
+ * Placeholders inside string literals, quoted identifiers, heredocs, and
+ * comments are data and are left alone, so a body can talk about braces without
+ * having them bound.
+ *
+ * Values that no placeholder references are ignored: a caller may pass one
+ * context object to several fragments.
+ */
+export function bindNamedParameters(sql, values = {}, context = 'SQL') {
+    const parameters = [];
+    let bound = '';
+    let copiedTo = 0;
+    let i = 0;
+    while (i < sql.length) {
+        const skippedTo = skipNonCode(sql, i);
+        if (skippedTo !== undefined) {
+            i = skippedTo;
+            continue;
+        }
+        if (sql[i] !== '{') {
+            i += 1;
+            continue;
+        }
+        const placeholder = matchPlaceholder(sql, i);
+        if (!placeholder) {
+            const name = readIdentifier(sql, i + 1);
+            const afterName = name === undefined ? undefined : sql[i + 1 + name.length];
+            if (name !== undefined && (afterName === '}' || afterName === ':') && name in values) {
+                throw new Error(`${context} placeholder "{${name}}" is missing a type. Write it as {${name}:Type}, for example {${name}:UUID}.`);
+            }
+            i += 1;
+            continue;
+        }
+        if (!(placeholder.name in values)) {
+            throw new Error(`${context} references parameter "${placeholder.name}", but no value was provided for it.`);
+        }
+        // The declared type has to survive substitution: a bare escaped literal
+        // reaches the server as a String, which breaks any expression that needs
+        // the real type — a UUID join key, for instance.
+        bound += `${sql.slice(copiedTo, i)}CAST(?, ${escapeValue(placeholder.type)})`;
+        const value = values[placeholder.name];
+        parameters.push(serializeCompoundParameter(value, placeholder.type));
+        copiedTo = placeholder.end;
+        i = placeholder.end;
+    }
+    return { sql: bound + sql.slice(copiedTo), parameters };
+}

package/dist/core/utils/parameter-type.d.ts

@@ -0,0 +1,10 @@
+export declare function parseParameterType(type: string): {
+    name: string;
+    args: string[];
+};
+/** Named tuple fields can still be supplied positionally as JavaScript arrays. */
+export declare function parseTupleField(field: string): {
+    name?: string;
+    type: string;
+};
+//# sourceMappingURL=parameter-type.d.ts.map

package/dist/core/utils/parameter-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-type.d.ts","sourceRoot":"","sources":["../../../src/core/utils/parameter-type.ts"],"names":[],"mappings":"AA0BA,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAIjF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAW9E"}

package/dist/core/utils/parameter-type.js

@@ -0,0 +1,46 @@
+import { skipNonCode } from './sql-parens.js';
+/** Split type arguments without treating quoted or nested commas as separators. */
+function splitTypeArguments(input) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    let i = 0;
+    while (i < input.length) {
+        const end = skipNonCode(input, i);
+        if (end !== undefined) {
+            i = end;
+            continue;
+        }
+        if (input[i] === '(')
+            depth += 1;
+        if (input[i] === ')')
+            depth -= 1;
+        if (input[i] === ',' && depth === 0) {
+            parts.push(input.slice(start, i).trim());
+            start = i + 1;
+        }
+        i += 1;
+    }
+    if (input.slice(start).trim())
+        parts.push(input.slice(start).trim());
+    return parts;
+}
+export function parseParameterType(type) {
+    const match = /^([A-Za-z][A-Za-z0-9]*)\s*(?:\(([\s\S]*)\))?$/.exec(type.trim());
+    if (!match)
+        throw new Error(`Cannot serialize parameter with type ${type}`);
+    return { name: match[1], args: match[2] === undefined ? [] : splitTypeArguments(match[2]) };
+}
+/** Named tuple fields can still be supplied positionally as JavaScript arrays. */
+export function parseTupleField(field) {
+    if (field[0] === '`' || field[0] === '"') {
+        const end = skipNonCode(field, 0);
+        const quote = field[0];
+        const name = field.slice(1, end - 1)
+            .replace(new RegExp(`${quote}${quote}`, 'g'), quote)
+            .replace(/\\(.)/gs, (_, char) => ({ n: '\n', r: '\r', t: '\t', '0': '\0', b: '\b', f: '\f' }[char] ?? char));
+        return { name, type: field.slice(end).trim() };
+    }
+    const named = /^([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z][\s\S]*)$/.exec(field);
+    return named ? { name: named[1], type: named[2] } : { type: field };
+}

package/dist/core/utils/record-guards.d.ts

@@ -0,0 +1,3 @@
+/** Accept plain objects and null-prototype records, excluding class instances. */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=record-guards.d.ts.map

package/dist/core/utils/record-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-guards.d.ts","sourceRoot":"","sources":["../../../src/core/utils/record-guards.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI9E"}

package/dist/core/utils/record-guards.js

@@ -0,0 +1,7 @@
+/** Accept plain objects and null-prototype records, excluding class instances. */
+export function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/core/utils/sql-parens.d.ts

@@ -1,3 +1,9 @@
+/**
+ * When `start` opens a region that is not SQL code — a literal, a quoted
+ * identifier, a heredoc, or a comment — returns the index just past it.
+ * Scanners use it so markers inside such a region stay data.
+ */
+export declare function skipNonCode(sql: string, start: number): number | undefined;
 /**
  * Split on positional parameter markers that occur in SQL code. Question marks
  * inside literals, quoted identifiers, heredocs, or comments are data, not

package/dist/core/utils/sql-parens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-parens.d.ts","sourceRoot":"","sources":["../../../src/core/utils/sql-parens.ts"],"names":[],"mappings":"AAqGA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB1D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA8B/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAuBzD"}
+{"version":3,"file":"sql-parens.d.ts","sourceRoot":"","sources":["../../../src/core/utils/sql-parens.ts"],"names":[],"mappings":"AAuEA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqB1E;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB1D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA8B/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAuBzD"}

package/dist/core/utils/sql-parens.js

@@ -65,7 +65,12 @@ function isLineCommentStart(sql, start) {
         return true;
     return sql[start] === '#' && (sql[start + 1] === ' ' || sql[start + 1] === '!');
 }
-function skipNonCode(sql, start) {
+/**
+ * When `start` opens a region that is not SQL code — a literal, a quoted
+ * identifier, a heredoc, or a comment — returns the index just past it.
+ * Scanners use it so markers inside such a region stay data.
+ */
+export function skipNonCode(sql, start) {
     const ch = sql[start];
     if (ch === "'" || ch === '"' || ch === '`') {
         return skipQuoted(sql, start, ch);

package/dist/index.d.ts

@@ -12,7 +12,6 @@ export type { SqlDialect } from './core/dialects/sql-dialect.js';
 export type { ClickHouseConfig, ClickHouseAdapterConfig, ClickHouseAdapterOptions, ClickHouseClientConfig, CreateQueryBuilderConfig, ExecuteOptions, IntegerJsonEncoding, StreamOptions } from './core/query-builder.js';
 export { isClientConfig } from './core/query-builder.js';
 export { substituteParameters, escapeValue } from './core/utils.js';
-export * from './core/compiled/index.js';
 export type { CacheOptions, CacheConfig, CacheProvider, CacheEntry, CacheStatus } from './core/cache/types.js';
 export { CacheController } from './core/cache/controller.js';
 export { MemoryCacheProvider } from './core/cache/providers/memory-lru.js';
@@ -20,7 +19,10 @@ export { MemoryCacheProvider as MemoryLRUCacheProvider } from './core/cache/prov
 export { NoopCacheProvider } from './core/cache/providers/noop.js';
 export type { ColumnType, TableColumn, TableSchema, TableRecord, DatabaseSchema, InferColumnType, } from './types/schema.js';
 export type { InsertRow, InsertRowForColumns, InsertValue, InsertJsonValue, } from './types/insert.js';
-export type { OrderDirection, QueryConfig, AggregationType } from './types/base.js';
+export type { OrderDirection, QueryConfig, AggregationType, RawCteBody } from './types/base.js';
+export { CteScope } from './core/cte-scope.js';
+export type { CteScopeDeps } from './core/cte-scope.js';
+export type { CteBody } from './core/features/analytics.js';
 export type { FilterOperator, OperatorValueMap, FilterConditionInput } from './types/filters.js';
 export type { JoinPath, JoinPathOptions } from './core/join-relationships.js';
 export { CrossFilter } from './core/cross-filter.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -9,15 +9,11 @@ export { isClientConfig } from './core/query-builder.js';
 // SQL rendering used by the built-in adapter; exported so third-party DatabaseAdapter
 // implementations (e.g. embedded engines) reproduce identical ?-param rendering.
 export { substituteParameters, escapeValue } from './core/utils.js';
-// CompiledQuery v1 (RFC 0010) — versioned execution-request contract with named typed
-// parameters, closed operations/settings, authoritative ids, deadlines, a redacted debug
-// form, and the public error envelope. Introduced beside the legacy ?-param path (CH-01);
-// the built-in adapter transport is wired in a later change.
-export * from './core/compiled/index.js';
 export { CacheController } from './core/cache/controller.js';
 export { MemoryCacheProvider } from './core/cache/providers/memory-lru.js';
 export { MemoryCacheProvider as MemoryLRUCacheProvider } from './core/cache/providers/memory-lru.js';
 export { NoopCacheProvider } from './core/cache/providers/noop.js';
+export { CteScope } from './core/cte-scope.js';
 export { CrossFilter } from './core/cross-filter.js';
 export { logger } from './core/utils/logger.js';
 // Re-export SQL expression utilities

package/dist/types/base.d.ts

@@ -16,6 +16,12 @@ export interface QueryConfig<_T, _Schema> {
     orderBy?: OrderByItemNode[];
     joins?: JoinNode[];
     ctes?: CteNode[];
+    /**
+     * Renders the `WITH` clause as `WITH RECURSIVE`. `RECURSIVE` is a property of
+     * the clause rather than of a single entry, so one recursive CTE marks the
+     * whole list — the same rule SQL itself uses.
+     */
+    recursiveCtes?: boolean;
     unionQueries?: string[];
     settings?: ClickHouseSettings;
 }
@@ -69,6 +75,12 @@ export interface TableSourceNode {
     kind: 'table';
     name: string;
     final?: boolean;
+    /**
+     * The name resolves to a CTE declared on this query rather than to a table.
+     * It renders identically, but table-only modifiers (`FINAL`, `PREWHERE`) do
+     * not apply to it.
+     */
+    cte?: boolean;
 }
 export interface SubquerySourceNode {
     kind: 'subquery';
@@ -117,7 +129,34 @@ export interface LimitByNode {
 }
 export interface CteNode {
     kind: 'cte';
+    /**
+     * The entry as a single rendered fragment, with any parameter values already
+     * substituted. Kept as the canonical field so consumers reading it keep
+     * working; compilation prefers `name`/`body` when they are present.
+     */
     expression: string;
+    /** CTE alias. Present for named CTEs, absent for `withScalar` entries. */
+    name?: string;
+    /**
+     * The CTE body with `?` placeholders left in place, so its values can stay
+     * bound instead of being escaped into `expression`.
+     */
+    body?: string;
+    /** Values for the placeholders in `body`, in order. */
+    parameters?: unknown[];
+}
+/**
+ * A raw CTE body with its values kept out of the SQL text. Placeholders use
+ * ClickHouse's `{name:Type}` form and are matched by name against `parameters`.
+ *
+ * Required for a recursive CTE, whose recursive term references an alias that
+ * no builder can express; ordinary CTEs are better written as a builder.
+ */
+export interface RawCteBody {
+    /** The CTE body, with `{name:Type}` placeholders for its values. */
+    sql: string;
+    /** Values for those placeholders, keyed by placeholder name. */
+    parameters?: Record<string, unknown>;
 }
 export interface SelectQueryNode<T, Schema> extends QueryConfig<T, Schema> {
     kind: 'select-query';

package/dist/types/base.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/clickhouse",
-  "version": "2.10.1",
+  "version": "2.11.1",
   "description": "Type-safe ClickHouse query builder and schema generator for TypeScript analytics",
   "keywords": [
     "clickhouse",
@@ -47,8 +47,7 @@
   ],
   "dependencies": {
     "@clickhouse/client": "^1.18.3",
-    "dotenv": "^16.0.0",
-    "@hypequery/protocol": "0.13.0"
+    "dotenv": "^16.0.0"
   },
   "peerDependencies": {
     "@clickhouse/client-web": "^0.2.0 || ^1.0.0",
@@ -74,7 +73,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/datasets": "0.15.0"
+    "@hypequery/datasets": "0.17.0"
   },
   "ts-node": {
     "esm": true,

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

@@ -1,25 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,134 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,25 +0,0 @@
-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

@@ -1,38 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}