@wavehouse/chtypes 0.1.0

package/dist/discover.js

@@ -0,0 +1,291 @@
+/**
+ * The discovery kit.
+ *
+ * This library NEVER talks to ClickHouse; it ships the queries. At connect
+ * time a caller (a gateway, WaveHouse) runs these three queries against the
+ * deployment's own server with whatever client it already has, feeds the
+ * results to the typed parsers below, and then declares what it learned:
+ *
+ *   profile.version  -> Registry#for / the artifact to load
+ *   profile.settings -> compileDdl({ settings }) (compile-time) and per-call settings
+ *   columns          -> reconstructDdl -> compileDdl
+ *
+ * The pattern, in full (spec/bindings.md §Discovery):
+ *
+ *   1. run QUERY_SERVER_VERSION, QUERY_CHANGED_SETTINGS once per connection
+ *   2. cache the ServerProfile per deployment/tenant
+ *   3. const lib = registry.for(profile.version)
+ *   4. const schema = lib.compileDdl(ddl, { settings: profile.settings, mode: 0 })
+ *   5. per call: pass profile.settings (plus any per-INSERT overrides) to rows()
+ *
+ * Never ask the customer for their settings — ask their server. The queries
+ * return exactly what the server believes, spelled the way the server spells
+ * it, which is what the settings gate (spec/c-abi.md, Settings rule 2)
+ * validates against.
+ *
+ * The parsers read JSONEachRow bytes through this package's own byte-exact
+ * JSON reader, so a numeric field (`position`) is taken from its literal
+ * digits — quoted or bare, ClickHouse's stock HTTP output quotes 64-bit
+ * integers — and never routed through a float.
+ */
+import { ChtypesError } from './errors.js';
+import { asString, parseJsonValue, rawText } from './json.js';
+// The canonical discovery queries. Each carries its FORMAT clause so the
+// bytes an HTTP client gets back are exactly what the matching parse*
+// function consumes. A native-protocol client that returns typed rows
+// instead can ignore the parsers and fill the structs directly.
+/**
+ * Names the deployment's exact release — the string `Registry#for` resolves
+ * (minor line or exact patch both work). One row: `{"version":"25.8.28.1"}`.
+ */
+export const QUERY_SERVER_VERSION = 'SELECT version() AS version FORMAT JSONEachRow';
+/**
+ * Lists every query setting the deployment runs at a NON-default value — the
+ * whole declared profile, from the server itself. One row per setting:
+ * `{"name":"flatten_nested","value":"0"}`. `system.settings.value` is already
+ * a String; the map feeds `compileDdl({ settings })` and per-call settings
+ * verbatim.
+ */
+export const QUERY_CHANGED_SETTINGS = 'SELECT name, value FROM system.settings WHERE changed FORMAT JSONEachRow';
+/**
+ * Describes one existing table, in declaration order, with everything a
+ * column-declaration list needs — INCLUDING `default_kind` and
+ * `default_expression`, without which a reconstructed schema silently loses
+ * its DEFAULT/MATERIALIZED semantics. Uses ClickHouse's own query parameters:
+ * send `param_db` / `param_table` (HTTP) or bind `{db}`/`{table}` (native).
+ */
+export const QUERY_TABLE_COLUMNS = 'SELECT name, type, default_kind, default_expression, position ' +
+    'FROM system.columns WHERE database = {db:String} AND table = {table:String} ' +
+    'ORDER BY position FORMAT JSONEachRow';
+const asBuffer = (body) => typeof body === 'string'
+    ? Buffer.from(body, 'utf8')
+    : Buffer.isBuffer(body)
+        ? body
+        : Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+/** Split a JSONEachRow body into one parsed object per line. */
+function jsonEachRowDocs(body) {
+    const out = [];
+    for (const line of splitLines(asBuffer(body))) {
+        if (line[0] !== 0x7b /* { */) {
+            throw new ChtypesError(`chtypes: not a JSONEachRow line: ${line.toString('utf8').slice(0, 60)}`);
+        }
+        const doc = parseJsonValue(line);
+        if (doc === null || doc.kind !== 'object') {
+            throw new ChtypesError(`chtypes: not a JSONEachRow line: ${line.toString('utf8').slice(0, 60)}`);
+        }
+        out.push(doc);
+    }
+    return out;
+}
+function splitLines(body) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i <= body.length; i++) {
+        if (i === body.length || body[i] === 0x0a) {
+            const line = trimSpace(body.subarray(start, i));
+            if (line.length > 0)
+                out.push(line);
+            start = i + 1;
+        }
+    }
+    return out;
+}
+/** ASCII whitespace trim over bytes, so no decode happens before the parse. */
+function trimSpace(line) {
+    let a = 0;
+    let b = line.length;
+    const ws = (c) => c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d;
+    while (a < b && ws(line[a]))
+        a++;
+    while (b > a && ws(line[b - 1]))
+        b--;
+    return line.subarray(a, b);
+}
+/** A field of a discovery row, by key — the reference's `row[k]`, last wins. */
+function member(doc, key) {
+    let found;
+    for (let i = 0; i < doc.keys.length; i++) {
+        if (doc.keys[i].toString('utf8') === key)
+            found = doc.items[i];
+    }
+    return found;
+}
+/**
+ * A field's value that may arrive quoted or bare (ClickHouse quotes 64-bit
+ * integers in JSON output by default), digits preserved exactly — never
+ * through a float. Mirrors the reference's `jsonString`.
+ */
+function jsonString(value) {
+    if (value === undefined)
+        return '';
+    // A parsed value's raw slice carries no surrounding whitespace, so the
+    // reference's TrimSpace has nothing to do here — and JS's own `trim()` is
+    // deliberately avoided in this package (its WhiteSpace set includes U+FEFF).
+    return value.kind === 'string' ? asString(value) : rawText(value);
+}
+/**
+ * Read `QUERY_SERVER_VERSION`'s JSONEachRow body.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns the version string, e.g. `"25.8.28.1"` — feed `Registry#for`.
+ * @throws {ChtypesError} when the body is not exactly one JSONEachRow row with
+ *   a non-empty `version` field.
+ */
+export function parseVersionResult(body) {
+    const docs = jsonEachRowDocs(body);
+    if (docs.length !== 1) {
+        throw new ChtypesError(`chtypes: version query returned ${docs.length} rows, want 1`);
+    }
+    const v = member(docs[0], 'version');
+    if (v === undefined) {
+        throw new ChtypesError('chtypes: version query row has no `version` field');
+    }
+    const out = jsonString(v);
+    if (out === '') {
+        throw new ChtypesError('chtypes: version query returned an empty version');
+    }
+    return out;
+}
+/**
+ * Read `QUERY_CHANGED_SETTINGS`' JSONEachRow body. An empty body is a stock
+ * server: an empty map, not an error.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns setting name → value, ready for `ServerProfile#settings`,
+ *   `compileDdl({ settings })` and per-call settings.
+ * @throws {ChtypesError} when a row is not JSONEachRow or lacks `name`/`value`.
+ */
+export function parseChangedSettingsResult(body) {
+    const out = {};
+    for (const doc of jsonEachRowDocs(body)) {
+        const name = member(doc, 'name');
+        if (name === undefined) {
+            throw new ChtypesError(`chtypes: settings row has no \`name\` field: ${rawText(doc).slice(0, 60)}`);
+        }
+        const value = member(doc, 'value');
+        if (value === undefined) {
+            throw new ChtypesError(`chtypes: settings row has no \`value\` field: ${rawText(doc).slice(0, 60)}`);
+        }
+        out[jsonString(name)] = jsonString(value);
+    }
+    return out;
+}
+/**
+ * Read `QUERY_TABLE_COLUMNS`' JSONEachRow body, in the query's ORDER BY
+ * position order. `position` survives both spellings — quoted on stock HTTP
+ * output (`output_format_json_quote_64bit_integers=1`) and bare when a client
+ * unsets that — parsed from its literal digits, never through `JSON.parse`'s
+ * double. A position is small, so it fits a JS number once those digits are
+ * in hand; a malformed one is left 0, as the reference leaves it.
+ *
+ * @param body - the query result bytes (or text) as the server sent them.
+ * @returns one `DiscoveredColumn` per row, in the query's position order —
+ *   feed `reconstructDdl`.
+ * @throws {ChtypesError} when a row is malformed, lacks `name`/`type`, or the
+ *   body holds no rows at all (wrong database/table, or no access).
+ */
+export function parseColumnsResult(body) {
+    const out = [];
+    for (const doc of jsonEachRowDocs(body)) {
+        const name = jsonString(member(doc, 'name'));
+        const type = jsonString(member(doc, 'type'));
+        if (name === '' || type === '') {
+            throw new ChtypesError(`chtypes: columns row missing name/type: ${rawText(doc).slice(0, 80)}`);
+        }
+        let position = 0;
+        const raw = member(doc, 'position');
+        if (raw !== undefined) {
+            const digits = jsonString(raw);
+            const n = Number(digits);
+            if (/^\d+$/.test(digits) && Number.isSafeInteger(n))
+                position = n;
+        }
+        out.push({
+            name,
+            type,
+            defaultKind: jsonString(member(doc, 'default_kind')),
+            defaultExpression: jsonString(member(doc, 'default_expression')),
+            position,
+        });
+    }
+    if (out.length === 0) {
+        throw new ChtypesError('chtypes: columns query returned no rows — wrong database/table, or no access');
+    }
+    return out;
+}
+/**
+ * Quote an identifier the way ClickHouse DDL requires: plain
+ * `[A-Za-z_][A-Za-z0-9_]*` stays bare, anything else is backticked with
+ * backticks doubled. `system.columns` can return anything — the flattened
+ * Nested idiom (`n.a`), spaces, keywords.
+ */
+function backquoteIfNeeded(name) {
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        return name;
+    return '`' + name.replaceAll('`', '``') + '`';
+}
+/**
+ * Turn `QUERY_TABLE_COLUMNS`' rows back into the column-declaration list
+ * `compileDdl` takes. It is a spelling exercise, not a semantic one: types
+ * and expressions are the server's own text, passed through verbatim, and the
+ * library's own compile is the judge of the result.
+ *
+ * Two facts a caller must know, both properties of the server rather than of
+ * this function:
+ *
+ *  - `system.columns` reports the table AS STORED. Under the default
+ *    `flatten_nested=1` a `Nested(a,b)` column appears as its flattened
+ *    `n.a`/`n.b` Array columns and reconstructs to exactly those — which is
+ *    the same table. Under `flatten_nested=0` it appears as one column of
+ *    type `Nested(...)`, which also reconstructs directly. Reconstruction is
+ *    therefore shape-faithful either way, PROVIDED the same `flatten_nested`
+ *    value is declared to `compileDdl({ settings })` that the table was
+ *    created under — which is what the discovered `ServerProfile.settings`
+ *    carries.
+ *  - a MATERIALIZED/ALIAS column reconstructs with its expression; an
+ *    EPHEMERAL column may legitimately have an empty `default_expression`.
+ *
+ * @param cols - the discovered columns, e.g. from `parseColumnsResult`.
+ * @returns the column-declaration list for `Library#compileDdl`.
+ * @throws {ChtypesError} when a column is inconsistent: no name/type, a
+ *   `default_expression` with no kind, a DEFAULT/MATERIALIZED/ALIAS kind with
+ *   no expression, an unknown kind, or no columns at all.
+ */
+export function reconstructDdl(cols) {
+    if (cols.length === 0) {
+        throw new ChtypesError('chtypes: no columns to reconstruct');
+    }
+    const parts = [];
+    for (let i = 0; i < cols.length; i++) {
+        const c = cols[i];
+        if (c.name === '' || c.type === '') {
+            throw new ChtypesError(`chtypes: column ${i} has no name/type`);
+        }
+        let decl = `${backquoteIfNeeded(c.name)} ${c.type}`;
+        switch (c.defaultKind) {
+            case '':
+                if (c.defaultExpression !== '') {
+                    throw new ChtypesError(`chtypes: column ${c.name} has a default_expression but no default_kind`);
+                }
+                break;
+            case 'DEFAULT':
+            case 'MATERIALIZED':
+            case 'ALIAS':
+                if (c.defaultExpression === '') {
+                    throw new ChtypesError(`chtypes: column ${c.name} is ${c.defaultKind} but has no default_expression`);
+                }
+                decl += ` ${c.defaultKind} ${c.defaultExpression}`;
+                break;
+            case 'EPHEMERAL':
+                decl += ' EPHEMERAL';
+                if (c.defaultExpression !== '')
+                    decl += ` ${c.defaultExpression}`;
+                break;
+            default:
+                throw new ChtypesError(`chtypes: column ${c.name} has unknown default_kind ${JSON.stringify(c.defaultKind)}`);
+        }
+        parts.push(decl);
+    }
+    return parts.join(', ');
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The error model, which is three outcomes that must never be conflated
+ * (spec/c-abi.md §Error model):
+ *
+ *   - ClickHouse rejects        -> a real ClickHouse error code
+ *   - this build refuses        -> CODE_UNSUPPORTED (-2), never a ClickHouse code
+ *   - ClickHouse accepts but the value cannot be read back -> code 691, and it
+ *     is an ACCEPTED insert, surfaced through the row outcome rather than here.
+ *
+ * Mapping `unsupported` onto a rejection manufactures an over-reject the product
+ * never made; mapping it onto an acceptance manufactures an over-accept, which
+ * is the cardinal sin. So it gets its own sentinel on the wire and, since
+ * 2026-08-26, its own ERROR CLASS here — `UnsupportedError`, a peer of
+ * `SchemaError` rather than a subclass, so that a `catch` which handles only
+ * `SchemaError` cannot silently swallow a decline as a rejection.
+ */
+/** "This build refuses to answer." Never a real ClickHouse error code. */
+export declare const CODE_UNSUPPORTED = -2;
+/**
+ * The chs_* ABI revision this binding was written against — `CHS_ABI_REVISION`
+ * in `include/chtypes.h`.
+ *
+ * This package dlopens artifacts rather than compiling against the header, so
+ * this is a hand-kept mirror and MUST be bumped in the same cycle the header
+ * is. A `Registry` refuses an artifact reporting a different nonzero revision;
+ * 0 means the artifact predates the probe, which is ignorance rather than
+ * incompatibility (spec/artifact.md §Loading).
+ *
+ * Revision 3 (2026-08-31): `chs_rows` gained `export_format` / `doc_flags` /
+ * `out_bytes`, and the `chs_filter_compile` / `chs_filter_free` /
+ * `chs_filter_rows` trio joined the surface.
+ *
+ * Revision 4 (2026-08-31, the filter phase-2 cycle): `chs_filter_compile`
+ * gained `params_json` (`{name:Type}` query parameters), and the block twin
+ * joined — `chs_block_parse` / `chs_block_free` / `chs_filter_eval`. This
+ * binding therefore speaks 4 and refuses revision-3 artifacts — calling the
+ * 5-argument `chs_filter_compile` through the 4-argument revision-3 artifact
+ * is undefined behaviour, which is exactly what the gate exists to prevent.
+ */
+export declare const ABI_REVISION = 4;
+/** Base class for everything this package throws. */
+export declare class ChtypesError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A registry could not be loaded, or a version could not be resolved. */
+export declare class RegistryError extends ChtypesError {
+}
+/**
+ * A REFUSAL: ClickHouse itself refused a type, a column list, an engine or a
+ * TTL.
+ *
+ * `code` is ALWAYS a real ClickHouse error code. "This build declines to
+ * answer" is a DIFFERENT CLASS — `UnsupportedError` — never this one carrying
+ * a sentinel, so no `SchemaError` ever holds `CODE_UNSUPPORTED`
+ * (spec/bindings.md rule 12).
+ */
+export declare class SchemaError extends ChtypesError {
+    readonly code: number;
+    readonly detail: string;
+    readonly column: string | undefined;
+    constructor(code: number, detail: string, column?: string);
+}
+/**
+ * A DECLINE: "a real server might well have accepted this; I will not guess."
+ * Never ClickHouse rejecting anything, so it carries no `code` property at all
+ * — there is no code to carry.
+ *
+ * It is a PEER of `SchemaError`, deliberately NOT a subclass and deliberately
+ * NOT matched by `err instanceof SchemaError`. A decline that still satisfied
+ * "is a SchemaError" would be the sentinel problem wearing a class hierarchy:
+ * every `catch` that forgot the predicate would keep silently turning declines
+ * into rejections, which is a manufactured over-reject — data loss the product
+ * never made, budgeted at zero. As a peer, forgetting throws on past the
+ * handler, which is loud.
+ *
+ * ```ts
+ * try {
+ *   schema.setEngine(engine, orderBy);
+ * } catch (err) {
+ *   // validate cautiously; do NOT blame the tenant
+ *   if (err instanceof UnsupportedError) return degradeToCarefulPath(err);
+ *   // ClickHouse refused: err.code is its own code
+ *   if (err instanceof SchemaError) return rejectWith(err.code, err.detail);
+ *   throw err;
+ * }
+ * ```
+ *
+ * The MESSAGE still renders the ABI's `CODE_UNSUPPORTED` sentinel in the shape
+ * `SchemaError` renders its code. The sentinel is not a property of this class
+ * — it is the wire value the C ABI returned — but the rendering is frozen: the
+ * conformance driver puts this exact string on the protocol wire as an
+ * `unsupported` scope, and Python's `UnsupportedError` already spells it this
+ * way. Changing the text would move rig records without changing a verdict.
+ */
+export declare class UnsupportedError extends ChtypesError {
+    readonly detail: string;
+    readonly column: string | undefined;
+    constructor(detail: string, column?: string);
+}
+/**
+ * The ONE place an ABI error code becomes an error object, so the
+ * refusal/decline split cannot be decided differently in two files.
+ *
+ * The SIGN decides (spec/bindings.md rule 12, spec/c-abi.md §Error model): a
+ * positive code is the server's own refusal and rides through verbatim; any
+ * negative code is this library declining (`-2` "I will not guess", `-1` a
+ * guarded exception, and a binding's own missing-symbol sentinel) and becomes
+ * an `UnsupportedError`. Keying on the sign rather than on `=== CODE_UNSUPPORTED`
+ * means a negative sentinel a later era adds can never become "a SchemaError
+ * with a negative code", which the class's own contract forbids.
+ *
+ * Internal: not re-exported from the package index.
+ */
+export declare function schemaErrorFor(code: number, detail: string, column?: string): SchemaError | UnsupportedError;
+/** The codes docs/fetch.md §7 shares across every SDK. */
+export type ArtifactErrorCode = 'CHTYPES_ARTIFACT_MISSING' | 'CHTYPES_ARTIFACT_UNTRUSTED' | 'CHTYPES_ARTIFACT_CORRUPT' | 'CHTYPES_ARTIFACT_PINNED' | 'CHTYPES_ARTIFACT_UNPUBLISHED' | 'CHTYPES_SOURCE_UNREACHABLE';
+/** The command this SDK's §7 message tells a user to run. */
+export declare const FETCH_COMMAND = "npx @wavehouse/chtypes fetch";
+/**
+ * The §7 message, verbatim apart from the bracketed parts:
+ *
+ *     chtypes: no artifact for ClickHouse <line> (<os>-<arch>). Looked in: <dir1>, <dir2>, ….
+ *     Install it:  npx @wavehouse/chtypes fetch <line>
+ *     or set CHTYPES_AUTOFETCH=1 to fetch on first use.
+ */
+export declare function artifactMissingMessage(line: string, platform: string, lookedIn: readonly string[]): string;
+/**
+ * The one identifiable error for a missing artifact (docs/fetch.md §7):
+ * a `Registry` was asked for a line that no directory on its search path
+ * holds. `code` is `'CHTYPES_ARTIFACT_MISSING'`; the message is the
+ * contract's, and names every directory that was looked in and the command
+ * that installs the line.
+ *
+ * A subclass of `RegistryError`, so a `catch` written against `for()`'s
+ * documented error keeps working; the `code` is what a caller matches on.
+ */
+export declare class ArtifactMissingError extends RegistryError {
+    readonly code: 'CHTYPES_ARTIFACT_MISSING';
+    /** The minor line that was asked for, e.g. `25.8`. */
+    readonly line: string;
+    /** The platform key the registry serves, e.g. `darwin-arm64`. */
+    readonly platform: string;
+    /** Every directory of the search path, in order. */
+    readonly lookedIn: readonly string[];
+    constructor(line: string, platform: string, lookedIn: readonly string[]);
+}
+/**
+ * Base of the fetch-time verdicts (docs/fetch.md §3–§7). `code` is one of the
+ * shared codes; the subclasses exist so `instanceof` reads as well as `code`.
+ */
+export declare class FetchError extends ChtypesError {
+    readonly code: Exclude<ArtifactErrorCode, 'CHTYPES_ARTIFACT_MISSING'>;
+    constructor(code: Exclude<ArtifactErrorCode, 'CHTYPES_ARTIFACT_MISSING'>, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `CHTYPES_ARTIFACT_UNTRUSTED`: the release's `SHA256SUMS.sig` is absent,
+ * malformed, or does not verify with any trusted key. Nothing is downloaded
+ * around it (§3 step 0).
+ */
+export declare class ArtifactUntrustedError extends FetchError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `CHTYPES_ARTIFACT_CORRUPT`: any hash mismatch along the chain, a release
+ * that disagrees with itself (`index.json` vs `SHA256SUMS`, manifest vs
+ * index), or an archive that cannot be read safely.
+ */
+export declare class ArtifactCorruptError extends FetchError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `CHTYPES_ARTIFACT_PINNED`: a `--frozen` lock file names a different asset
+ * or sha256 for this line — or none at all — and the fetch refused it (§5).
+ */
+export declare class ArtifactPinnedError extends FetchError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** `CHTYPES_ARTIFACT_UNPUBLISHED`: the release has nothing for this platform, line or exact patch. */
+export declare class ArtifactUnpublishedError extends FetchError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `CHTYPES_SOURCE_UNREACHABLE`: the source could not be reached or does not
+ * serve the release files — or `offline` forbade reaching it and the line is
+ * not installed and verified.
+ */
+export declare class SourceUnreachableError extends FetchError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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