@wavehouse/chtypes 0.1.0

package/dist/library.d.ts

@@ -0,0 +1,225 @@
+/**
+ * One loaded ClickHouse build. It names itself — `chs_clickhouse_version()` —
+ * and nothing is ever inferred from the directory or the file name.
+ */
+import type { NativeLibrary } from './ffi.js';
+import { Schema } from './schema.js';
+import { type Settings } from './settings.js';
+/**
+ * The minor line: the first two dot-separated components of the reported
+ * version. `25.10` is a *later* minor than `25.8`, so string comparison of minor
+ * lines is meaningless and must not be used for ordering.
+ *
+ * @param version - an exact patch (`"25.8.28.1-lts"`) or already a minor line.
+ * @returns the minor line (`"25.8"`); a string with fewer than two components
+ *   is returned unchanged. Never throws.
+ */
+export declare function minorOf(version: string): string;
+/**
+ * The compile MODE — how the profile handed to `compileDdl` relates to the
+ * settings this build compiles under. Numeric values are part of the C ABI
+ * (bindings pass an int), exactly like `Format`.
+ */
+export declare const CompileMode: {
+    /**
+     * The only defined mode: every setting the profile names takes the
+     * caller's value, every setting it does not name keeps the library's own
+     * permissive compile base. A partial profile can admit a schema the server
+     * might refuse, but can never fabricate a rejection. Any other value is
+     * refused loudly (an `UnsupportedError`), reserved for a future
+     * COMPLETE-profile mode.
+     */
+    readonly Declared: 0;
+};
+export type CompileMode = (typeof CompileMode)[keyof typeof CompileMode];
+/**
+ * Options for `Library#compileDdl` — the DECLARED settings profile a schema is
+ * compiled under (spec/c-abi.md §Compile-time vs per-call settings;
+ * spec/bindings.md "Compile under a declared settings profile").
+ */
+export interface CompileOptions {
+    /**
+     * The settings the deployment's server runs, fixed into the compiled schema
+     * exactly as a real CREATE TABLE fixes them into the table. Values are
+     * strings (or bigints), as everywhere on this ABI. Absent or empty is
+     * structurally identical to the plain compile — `chs_schema_compile` takes
+     * "{}" plus mode 0 either way. An unknown setting name fails the compile
+     * with the server's own code 115 (`chtypes_*` per-call keys included), and
+     * nothing is compiled.
+     */
+    readonly settings?: Settings | undefined;
+    /**
+     * `CompileMode.Declared` (0), the default and the only defined mode — see
+     * `CompileMode`.
+     */
+    readonly mode?: CompileMode | undefined;
+}
+/**
+ * One loaded ClickHouse build — the entry point for compiling schemas and
+ * canonicalising types under that release's exact semantics. Obtained from
+ * `Registry#for`; never constructed directly.
+ *
+ * Thread-safety: every call here is synchronous on the JS thread, so ordinary
+ * single-threaded Node code needs no locking. `setDefaultSettings` and
+ * `shutdown` mutate per-library process state and refuse loudly if called from
+ * inside another chtypes call (a reentrancy guard, not a lock). Two
+ * `worker_threads` share one dlopen'd image and one set of C globals, which no
+ * per-isolate guard can see — seed settings before starting workers, or
+ * serialise the seed yourself (spec/bindings.md §Concurrency).
+ */
+export declare class Library {
+    private readonly native;
+    /** The exact patch this build is, e.g. "25.8.28.1-lts". */
+    readonly version: string;
+    /** The line callers and the rigs ask in, e.g. "25.8". */
+    readonly minor: string;
+    /** The shared library that was loaded. */
+    readonly path: string;
+    /**
+     * The chs_* ABI revision this ARTIFACT was built from, or 0 when it predates
+     * `chs_abi_revision`. A `Library` that exists reports either `ABI_REVISION`
+     * or 0 — a different nonzero revision is refused at load (spec/c-abi.md
+     * §ABI identity).
+     */
+    readonly abiRevision: number;
+    /** @internal — obtained from a `Registry`. */
+    constructor(native: NativeLibrary);
+    /**
+     * Parse and canonicalise one type expression, e.g. `DECIMAL(18,4)` ->
+     * `Decimal(18, 4)`. The library's spelling is authoritative: pass it through
+     * verbatim and never normalise its whitespace.
+     *
+     * Note that this alone is insufficient for a schema — `x Int64 DEFAULT NULL`
+     * canonicalises the *column* to `Nullable(Int64)`, which only `compileDdl` sees.
+     *
+     * @param typeExpr - a ClickHouse type expression, e.g. `"Nullable(Decimal(18,4))"`.
+     * @returns the canonical spelling, e.g. `"Nullable(Decimal(18, 4))"`.
+     * @throws {SchemaError} when ClickHouse itself refuses the expression —
+     *   `code` is its own code (`50` `Unknown data type family` for a typo) and
+     *   the message its own text.
+     * @throws {UnsupportedError} when this build declines to construct the type
+     *   (an unsafe family), or the artifact predates `chs_validate_type`.
+     */
+    validateType(typeExpr: string): string;
+    /**
+     * Compile a ClickHouse column-declaration list — not a CREATE TABLE:
+     * `"a UInt8, b Nullable(String) DEFAULT 'x', c DateTime MATERIALIZED now()"`.
+     * It is parsed by ClickHouse's own `ParserColumnDeclarationList`, so DEFAULT
+     * expressions are validated as real SQL. Column-level TTL clauses belong here.
+     *
+     * With `options.settings` the schema is compiled under that DECLARED profile,
+     * exactly as a real CREATE TABLE under those settings: `{ flatten_nested: '0' }`
+     * keeps `n Nested(a,b)` ONE column `n` of type `Nested(…)` where the default
+     * flattens it to the `n.a`/`n.b` Array columns, and every downstream shape —
+     * `columns`, JSONEachRow name lookup, positional arity, the RowBinary wire —
+     * follows the compiled shape. The profile is compile-time only and immutable
+     * for the schema's life; per-call settings still govern row parsing, and only
+     * row parsing.
+     *
+     * Absent/empty settings are structurally the plain compile: `chs_schema_compile`
+     * takes settings "{}" and `mode` `CompileMode.Declared` (0) either way. An
+     * unknown setting name fails the compile with the server's own code 115.
+     *
+     * @param ddl - a column-declaration list, e.g. `"x UInt8, s String DEFAULT 'x'"`.
+     * @param options - the declared settings profile and compile mode.
+     * @returns the compiled `Schema`. Release it with `close()` (or `using`).
+     * @throws {SchemaError} when the compile is REFUSED with a positive code: a
+     *   bad type or DEFAULT carries ClickHouse's own code and message; an
+     *   unknown setting name in `options.settings` carries the server's own 115
+     *   (with its did-you-mean hint), and nothing is compiled; a type gate
+     *   declared at a refusing value fails with the server's own 455/44, exactly
+     *   as that server's CREATE; an Enum DEFAULT outside the declared domain is
+     *   691 (schema-level poisoning, refused on every version by design).
+     * @throws {UnsupportedError} when this build DECLINES rather than guesses —
+     *   a `mode` other than `CompileMode.Declared`, or a DEFAULT it refuses to
+     *   evaluate (server-property functions like `hostName()`, `sleep`, an
+     *   admission-budget overrun). Validate cautiously; do not blame the tenant.
+     */
+    compileDdl(ddl: string, options?: CompileOptions): Schema;
+    /**
+     * Does this artifact export the consolidated, settings-aware
+     * `chs_schema_compile`? True on every artifact this repo builds — the
+     * symbol is one of the mandatory four. Kept for a `Registry` that may
+     * someday load a third-party-built artifact that lacks it, in which case
+     * `compileDdl` with a non-empty `settings` and `setEngine` with non-empty
+     * `mergeTreeSettings` throw an `UnsupportedError` instead of
+     * crashing.
+     */
+    hasCompileSettings(): boolean;
+    /**
+     * Seed the settings every later call starts from. ClickHouse gates several type
+     * families at column-creation time (`allow_suspicious_low_cardinality_types`,
+     * `allow_experimental_json_type`, …); those are properties of the server the
+     * table lives on, not of the row, so a gateway sets them once here. Anything a
+     * per-call settings map sets still wins.
+     *
+     * Prefer `compileDdl(ddl, { settings })` for a gate that belongs to a
+     * particular tenant's table: a gate declared in the compile profile binds
+     * where a real server binds it — once, at CREATE — and then outranks the
+     * per-call map for that handle (measured on live 25.10.7.6 and 26.7.3.19;
+     * spec/c-abi.md, "Server-level type gates"). This process-wide seed stays the
+     * right channel only for gateway-uniform policy.
+     *
+     * @param settings - the seed. An unknown name refuses the WHOLE payload with
+     *   the server's own 115 and nothing is committed — a gateway can never
+     *   believe a default profile is in force when part of it never applied.
+     * @throws {ChtypesError} when the payload is refused (the message carries
+     *   the server's own text, did-you-mean hint included), when a value is a JS
+     *   `number`, or when called from inside another chtypes call — it replaces
+     *   process-global state the row path reads by reference, so it must never
+     *   overlap another call on this library. In a `worker_threads` setup, seed
+     *   BEFORE starting workers; the guard cannot see across isolates.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_set_default_settings`.
+     */
+    setDefaultSettings(settings: Settings): void;
+    /**
+     * Diagnostic: the widened reference type this build compares against —
+     * `UInt8` → `Int256`, `DateTime` → `DateTime64(0, 'UTC')`. Not needed to
+     * function (the reference parse is already applied inside `row`/`rows` and
+     * reported per column); it makes transformation findings explainable.
+     *
+     * @param typeExpr - a ClickHouse type expression.
+     * @returns the reference type, or `''` for a type with no wider type to
+     *   compare against (`String`, `Float64`).
+     * @throws {UnsupportedError} when the artifact predates `chs_reference_type`.
+     */
+    referenceType(typeExpr: string): string;
+    /**
+     * Every type family in this build's own runtime registry (139 entries on
+     * 25.8) — the answer to "does this build track upstream type families?"
+     * without a hand-maintained table. Part of the three-question introspection
+     * surface every SDK exposes (spec/bindings.md §Introspection).
+     *
+     * @returns the family names, one per registry entry.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_registered_families`.
+     */
+    registeredFamilies(): string[];
+    /**
+     * The TSV audit of every registered function's volatility
+     * (`chs_function_flags`), VERBATIM: one function per line, six
+     * tab-separated fields — `name`, `deterministic`, `deterministic_in_query`,
+     * `server_constant`, `stateful`, `resolver_error_code`. ClickHouse's own
+     * answers off this build's own registry, and the input to the statelessness
+     * gate (`lib/tools/gen_function_flags.py`). Part of the three-question
+     * introspection surface every SDK exposes (spec/bindings.md
+     * §Introspection).
+     *
+     * @returns the audit text, verbatim.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_function_flags`.
+     */
+    functionFlags(): string;
+    /**
+     * Join the DEFAULT evaluator's background threads. `chs_init` registers this
+     * with `atexit`, so an ordinary process needs no call; it is REQUIRED before
+     * an explicit unload, and useful in tests that must not depend on `atexit`.
+     * Idempotent.
+     *
+     * @throws {ChtypesError} when called from inside another chtypes call on
+     *   this library (the same reentrancy guard as `setDefaultSettings`).
+     */
+    shutdown(): void;
+}
+//# sourceMappingURL=library.d.ts.map

package/dist/library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../src/library.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;aACH,QAAQ,EAAE,CAAC;CACH,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAgBN,OAAO,CAAC,QAAQ,CAAC,MAAM;IAfnC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,8CAA8C;IAC9C,YAA6B,MAAM,EAAE,aAAa,EAKjD;IAED;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAIxD;IAED;;;;;;;;OAQG;IACH,kBAAkB,IAAI,OAAO,CAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE3C;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtC;IAED;;;;;;;;;OASG;IACH,kBAAkB,IAAI,MAAM,EAAE,CAE7B;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,MAAM,CAEtB;IAED;;;;;;;;OAQG;IACH,QAAQ,IAAI,IAAI,CAEf;CACF"}

package/dist/library.js

@@ -0,0 +1,234 @@
+/**
+ * One loaded ClickHouse build. It names itself — `chs_clickhouse_version()` —
+ * and nothing is ever inferred from the directory or the file name.
+ */
+import { schemaErrorFor } from './errors.js';
+import { Schema } from './schema.js';
+import { encodeSettings } from './settings.js';
+/**
+ * The minor line: the first two dot-separated components of the reported
+ * version. `25.10` is a *later* minor than `25.8`, so string comparison of minor
+ * lines is meaningless and must not be used for ordering.
+ *
+ * @param version - an exact patch (`"25.8.28.1-lts"`) or already a minor line.
+ * @returns the minor line (`"25.8"`); a string with fewer than two components
+ *   is returned unchanged. Never throws.
+ */
+export function minorOf(version) {
+    const parts = version.split('.');
+    if (parts.length < 2)
+        return version;
+    return `${parts[0]}.${parts[1]}`;
+}
+/**
+ * The compile MODE — how the profile handed to `compileDdl` relates to the
+ * settings this build compiles under. Numeric values are part of the C ABI
+ * (bindings pass an int), exactly like `Format`.
+ */
+export const CompileMode = {
+    /**
+     * The only defined mode: every setting the profile names takes the
+     * caller's value, every setting it does not name keeps the library's own
+     * permissive compile base. A partial profile can admit a schema the server
+     * might refuse, but can never fabricate a rejection. Any other value is
+     * refused loudly (an `UnsupportedError`), reserved for a future
+     * COMPLETE-profile mode.
+     */
+    Declared: 0,
+};
+/**
+ * One loaded ClickHouse build — the entry point for compiling schemas and
+ * canonicalising types under that release's exact semantics. Obtained from
+ * `Registry#for`; never constructed directly.
+ *
+ * Thread-safety: every call here is synchronous on the JS thread, so ordinary
+ * single-threaded Node code needs no locking. `setDefaultSettings` and
+ * `shutdown` mutate per-library process state and refuse loudly if called from
+ * inside another chtypes call (a reentrancy guard, not a lock). Two
+ * `worker_threads` share one dlopen'd image and one set of C globals, which no
+ * per-isolate guard can see — seed settings before starting workers, or
+ * serialise the seed yourself (spec/bindings.md §Concurrency).
+ */
+export class Library {
+    native;
+    /** The exact patch this build is, e.g. "25.8.28.1-lts". */
+    version;
+    /** The line callers and the rigs ask in, e.g. "25.8". */
+    minor;
+    /** The shared library that was loaded. */
+    path;
+    /**
+     * The chs_* ABI revision this ARTIFACT was built from, or 0 when it predates
+     * `chs_abi_revision`. A `Library` that exists reports either `ABI_REVISION`
+     * or 0 — a different nonzero revision is refused at load (spec/c-abi.md
+     * §ABI identity).
+     */
+    abiRevision;
+    /** @internal — obtained from a `Registry`. */
+    constructor(native) {
+        this.native = native;
+        this.version = native.version;
+        this.minor = minorOf(native.version);
+        this.path = native.path;
+        this.abiRevision = native.abiRevision;
+    }
+    /**
+     * Parse and canonicalise one type expression, e.g. `DECIMAL(18,4)` ->
+     * `Decimal(18, 4)`. The library's spelling is authoritative: pass it through
+     * verbatim and never normalise its whitespace.
+     *
+     * Note that this alone is insufficient for a schema — `x Int64 DEFAULT NULL`
+     * canonicalises the *column* to `Nullable(Int64)`, which only `compileDdl` sees.
+     *
+     * @param typeExpr - a ClickHouse type expression, e.g. `"Nullable(Decimal(18,4))"`.
+     * @returns the canonical spelling, e.g. `"Nullable(Decimal(18, 4))"`.
+     * @throws {SchemaError} when ClickHouse itself refuses the expression —
+     *   `code` is its own code (`50` `Unknown data type family` for a typo) and
+     *   the message its own text.
+     * @throws {UnsupportedError} when this build declines to construct the type
+     *   (an unsafe family), or the artifact predates `chs_validate_type`.
+     */
+    validateType(typeExpr) {
+        const r = this.native.validateType(typeExpr);
+        if (!r.ok)
+            throw schemaErrorFor(r.code, r.message);
+        return r.canonical;
+    }
+    /**
+     * Compile a ClickHouse column-declaration list — not a CREATE TABLE:
+     * `"a UInt8, b Nullable(String) DEFAULT 'x', c DateTime MATERIALIZED now()"`.
+     * It is parsed by ClickHouse's own `ParserColumnDeclarationList`, so DEFAULT
+     * expressions are validated as real SQL. Column-level TTL clauses belong here.
+     *
+     * With `options.settings` the schema is compiled under that DECLARED profile,
+     * exactly as a real CREATE TABLE under those settings: `{ flatten_nested: '0' }`
+     * keeps `n Nested(a,b)` ONE column `n` of type `Nested(…)` where the default
+     * flattens it to the `n.a`/`n.b` Array columns, and every downstream shape —
+     * `columns`, JSONEachRow name lookup, positional arity, the RowBinary wire —
+     * follows the compiled shape. The profile is compile-time only and immutable
+     * for the schema's life; per-call settings still govern row parsing, and only
+     * row parsing.
+     *
+     * Absent/empty settings are structurally the plain compile: `chs_schema_compile`
+     * takes settings "{}" and `mode` `CompileMode.Declared` (0) either way. An
+     * unknown setting name fails the compile with the server's own code 115.
+     *
+     * @param ddl - a column-declaration list, e.g. `"x UInt8, s String DEFAULT 'x'"`.
+     * @param options - the declared settings profile and compile mode.
+     * @returns the compiled `Schema`. Release it with `close()` (or `using`).
+     * @throws {SchemaError} when the compile is REFUSED with a positive code: a
+     *   bad type or DEFAULT carries ClickHouse's own code and message; an
+     *   unknown setting name in `options.settings` carries the server's own 115
+     *   (with its did-you-mean hint), and nothing is compiled; a type gate
+     *   declared at a refusing value fails with the server's own 455/44, exactly
+     *   as that server's CREATE; an Enum DEFAULT outside the declared domain is
+     *   691 (schema-level poisoning, refused on every version by design).
+     * @throws {UnsupportedError} when this build DECLINES rather than guesses —
+     *   a `mode` other than `CompileMode.Declared`, or a DEFAULT it refuses to
+     *   evaluate (server-property functions like `hostName()`, `sleep`, an
+     *   admission-budget overrun). Validate cautiously; do not blame the tenant.
+     */
+    compileDdl(ddl, options) {
+        const settingsJson = encodeSettings(options?.settings);
+        const mode = options?.mode ?? CompileMode.Declared;
+        return new Schema(this.native, this.native.schemaCompile(ddl, settingsJson, mode), ddl);
+    }
+    /**
+     * Does this artifact export the consolidated, settings-aware
+     * `chs_schema_compile`? True on every artifact this repo builds — the
+     * symbol is one of the mandatory four. Kept for a `Registry` that may
+     * someday load a third-party-built artifact that lacks it, in which case
+     * `compileDdl` with a non-empty `settings` and `setEngine` with non-empty
+     * `mergeTreeSettings` throw an `UnsupportedError` instead of
+     * crashing.
+     */
+    hasCompileSettings() {
+        return this.native.hasCompileSettings();
+    }
+    /**
+     * Seed the settings every later call starts from. ClickHouse gates several type
+     * families at column-creation time (`allow_suspicious_low_cardinality_types`,
+     * `allow_experimental_json_type`, …); those are properties of the server the
+     * table lives on, not of the row, so a gateway sets them once here. Anything a
+     * per-call settings map sets still wins.
+     *
+     * Prefer `compileDdl(ddl, { settings })` for a gate that belongs to a
+     * particular tenant's table: a gate declared in the compile profile binds
+     * where a real server binds it — once, at CREATE — and then outranks the
+     * per-call map for that handle (measured on live 25.10.7.6 and 26.7.3.19;
+     * spec/c-abi.md, "Server-level type gates"). This process-wide seed stays the
+     * right channel only for gateway-uniform policy.
+     *
+     * @param settings - the seed. An unknown name refuses the WHOLE payload with
+     *   the server's own 115 and nothing is committed — a gateway can never
+     *   believe a default profile is in force when part of it never applied.
+     * @throws {ChtypesError} when the payload is refused (the message carries
+     *   the server's own text, did-you-mean hint included), when a value is a JS
+     *   `number`, or when called from inside another chtypes call — it replaces
+     *   process-global state the row path reads by reference, so it must never
+     *   overlap another call on this library. In a `worker_threads` setup, seed
+     *   BEFORE starting workers; the guard cannot see across isolates.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_set_default_settings`.
+     */
+    setDefaultSettings(settings) {
+        this.native.setDefaultSettings(encodeSettings(settings));
+    }
+    /**
+     * Diagnostic: the widened reference type this build compares against —
+     * `UInt8` → `Int256`, `DateTime` → `DateTime64(0, 'UTC')`. Not needed to
+     * function (the reference parse is already applied inside `row`/`rows` and
+     * reported per column); it makes transformation findings explainable.
+     *
+     * @param typeExpr - a ClickHouse type expression.
+     * @returns the reference type, or `''` for a type with no wider type to
+     *   compare against (`String`, `Float64`).
+     * @throws {UnsupportedError} when the artifact predates `chs_reference_type`.
+     */
+    referenceType(typeExpr) {
+        return this.native.referenceType(typeExpr);
+    }
+    /**
+     * Every type family in this build's own runtime registry (139 entries on
+     * 25.8) — the answer to "does this build track upstream type families?"
+     * without a hand-maintained table. Part of the three-question introspection
+     * surface every SDK exposes (spec/bindings.md §Introspection).
+     *
+     * @returns the family names, one per registry entry.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_registered_families`.
+     */
+    registeredFamilies() {
+        return this.native.registeredFamilies();
+    }
+    /**
+     * The TSV audit of every registered function's volatility
+     * (`chs_function_flags`), VERBATIM: one function per line, six
+     * tab-separated fields — `name`, `deterministic`, `deterministic_in_query`,
+     * `server_constant`, `stateful`, `resolver_error_code`. ClickHouse's own
+     * answers off this build's own registry, and the input to the statelessness
+     * gate (`lib/tools/gen_function_flags.py`). Part of the three-question
+     * introspection surface every SDK exposes (spec/bindings.md
+     * §Introspection).
+     *
+     * @returns the audit text, verbatim.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_function_flags`.
+     */
+    functionFlags() {
+        return this.native.functionFlags();
+    }
+    /**
+     * Join the DEFAULT evaluator's background threads. `chs_init` registers this
+     * with `atexit`, so an ordinary process needs no call; it is REQUIRED before
+     * an explicit unload, and useful in tests that must not depend on `atexit`.
+     * Idempotent.
+     *
+     * @throws {ChtypesError} when called from inside another chtypes call on
+     *   this library (the same reentrancy guard as `setDefaultSettings`).
+     */
+    shutdown() {
+        this.native.shutdown();
+    }
+}
+//# sourceMappingURL=library.js.map

package/dist/library.js.map

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

package/dist/numeric.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Exact numeric comparison. `Decimal(76, 24)`'s extra digits, a quoted 64-bit
+ * integer and an `Int256` all have to compare by value and never through a
+ * double: `18446744073709551615` must not become `18446744073709552000`, and an
+ * `Int256` must not become `-5.78960446186581e+76`. The reference implementation
+ * uses `math/big.Rat`; this is the same comparison over `BigInt`.
+ */
+/** Fold ClickHouse's denormal spellings onto one of "nan" / "inf" / "-inf". */
+export declare function denormal(s: string): string;
+export declare function parseRational(text: string): {
+    num: bigint;
+    den: bigint;
+} | null;
+/** Is this text a number (or a denormal token)? */
+export declare function isNumericText(text: string): boolean;
+/** Strip the JSON quoting ClickHouse uses for 64-bit integers and datetimes. */
+export declare function trimQuotes(s: string): string;
+/** Exact numeric equality of two renderings, denormals included. */
+export declare function numEqual(a: string, b: string): boolean;
+//# sourceMappingURL=numeric.d.ts.map

package/dist/numeric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric.d.ts","sourceRoot":"","sources":["../src/numeric.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB1C;AAUD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoB/E;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAInD;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAWtD"}

package/dist/numeric.js

@@ -0,0 +1,107 @@
+/**
+ * Exact numeric comparison. `Decimal(76, 24)`'s extra digits, a quoted 64-bit
+ * integer and an `Int256` all have to compare by value and never through a
+ * double: `18446744073709551615` must not become `18446744073709552000`, and an
+ * `Int256` must not become `-5.78960446186581e+76`. The reference implementation
+ * uses `math/big.Rat`; this is the same comparison over `BigInt`.
+ */
+/**
+ * Whitespace is exactly JSON's four bytes (spec/bindings.md §detectors) — never
+ * `String.prototype.trim()`, whose `WhiteSpace` set includes `<ZWNBSP>`.
+ * `trim()` here made `<BOM>42` numeric text, and the detector then reported 12
+ * `reformat` transforms on CSV/TSV fields that were stored exactly as supplied.
+ * The reference implementation's `big.Rat.SetString` tolerates no surrounding
+ * whitespace at all, so this is the narrower of the two readings.
+ */
+function trimJsonSpace(s) {
+    let from = 0;
+    let to = s.length;
+    const space = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
+    while (from < to && space(s[from]))
+        from++;
+    while (to > from && space(s[to - 1]))
+        to--;
+    return s.slice(from, to);
+}
+/** Fold ClickHouse's denormal spellings onto one of "nan" / "inf" / "-inf". */
+export function denormal(s) {
+    switch (trimJsonSpace(s).toLowerCase()) {
+        case 'nan':
+        case '__nan__':
+        case '-nan':
+            return 'nan';
+        case 'inf':
+        case 'infinity':
+        case '__inf__':
+        case '+inf':
+            return 'inf';
+        case '-inf':
+        case '-infinity':
+        case '__-inf__':
+            return '-inf';
+        default:
+            return '';
+    }
+}
+/**
+ * A decimal (optionally exponential) literal as an exact rational, or null when
+ * the text is not a number. The exponent is bounded: a gateway parses
+ * tenant-supplied text, and 1e1000000000 must not become a 10^9-digit integer.
+ */
+const MAX_ABS_EXPONENT = 100_000;
+const DECIMAL = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
+export function parseRational(text) {
+    const s = trimJsonSpace(text);
+    if (s === '')
+        return null;
+    const m = DECIMAL.exec(s);
+    if (m === null)
+        return null;
+    const sign = m[1] ?? '';
+    const int = m[2] ?? '';
+    const frac = m[3] ?? '';
+    const expText = m[4];
+    if (int === '' && frac === '')
+        return null;
+    const exp = expText === undefined ? 0 : Number(expText);
+    if (!Number.isSafeInteger(exp) || Math.abs(exp) > MAX_ABS_EXPONENT)
+        return null;
+    let num = BigInt((int === '' ? '0' : int) + frac);
+    let den = 10n ** BigInt(frac.length);
+    if (exp > 0)
+        num *= 10n ** BigInt(exp);
+    else if (exp < 0)
+        den *= 10n ** BigInt(-exp);
+    if (sign === '-')
+        num = -num;
+    return { num, den };
+}
+/** Is this text a number (or a denormal token)? */
+export function isNumericText(text) {
+    if (text === '')
+        return false;
+    if (denormal(text) !== '')
+        return true;
+    return parseRational(text) !== null;
+}
+/** Strip the JSON quoting ClickHouse uses for 64-bit integers and datetimes. */
+export function trimQuotes(s) {
+    return s.replace(/^"+|"+$/g, '');
+}
+/** Exact numeric equality of two renderings, denormals included. */
+export function numEqual(a, b) {
+    const x = trimQuotes(a);
+    const y = trimQuotes(b);
+    if (x === y)
+        return true;
+    const dx = denormal(x);
+    const dy = denormal(y);
+    if (dx !== '' || dy !== '')
+        return dx === dy;
+    const ra = parseRational(x);
+    const rb = parseRational(y);
+    if (ra === null || rb === null)
+        return false;
+    return ra.num * rb.den === rb.num * ra.den;
+}
+//# sourceMappingURL=numeric.js.map

package/dist/numeric.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Where artifacts are looked for and where a fetch writes — the §1 search
+ * path of docs/fetch.md, spelled once so the loader (`Registry`), the fetch
+ * (`ensure`) and the CLI (`chtypes where`) cannot disagree about it.
+ *
+ * The search path, in order, first directory that holds the requested line
+ * wins:
+ *
+ *   1. a path given explicitly to the registry constructor
+ *   2. `CHTYPES_REGISTRY`
+ *   3. `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/<os>-<arch>` — the
+ *      per-user cache, where fetch installs
+ *   4. `/usr/local/share/chtypes/artifacts/<os>-<arch>`, then
+ *      `/opt/chtypes/artifacts/<os>-<arch>` — system locations, reserved
+ *
+ * A fetch WRITES to the first of (1), (2), (3) that is set; never to (4).
+ */
+/**
+ * This host's platform key, `<os>-<arch>` in the artifact spellings
+ * (`linux`/`darwin`, `arm64`/`amd64`), e.g. `darwin-arm64`.
+ */
+export declare function hostPlatform(): string;
+/** True for the four platform keys a release can carry. */
+export declare function isPlatformKey(key: string): boolean;
+/** `${XDG_CACHE_HOME:-~/.cache}/chtypes` — the root every chtypes cache lives under. */
+export declare function cacheRoot(): string;
+/** The per-user artifact cache for one platform — search-path slot (3). */
+export declare function cacheRegistryDir(platform?: string): string;
+/** The reserved system locations — search-path slot (4), never written by fetch. */
+export declare function systemRegistryDirs(platform?: string): string[];
+/**
+ * The §1 search path for one platform: every candidate directory, in order,
+ * whether or not it exists. `explicit` is slot (1); `CHTYPES_REGISTRY` is
+ * slot (2) when set. Duplicates collapse to their first position.
+ */
+export declare function registrySearchPath(explicit?: string, platform?: string): string[];
+/**
+ * Where a fetch writes: the first of (1) `explicit`, (2) `CHTYPES_REGISTRY`,
+ * (3) the per-user cache that is set — never a system location.
+ *
+ * `CHTYPES_REGISTRY` names THIS host's registry, so it is only a destination
+ * for this host's own platform; artifacts fetched for another platform (a
+ * container's `linux-arm64` from a Mac) land in the cache keyed by that
+ * platform unless `explicit` says otherwise.
+ */
+export declare function fetchDestination(explicit?: string, platform?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wFAAwF;AACxF,wBAAgB,SAAS,IAAI,MAAM,CAIlC;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAAuB,GAAG,MAAM,CAE1E;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,MAAuB,GAAG,MAAM,EAAE,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuB,GAAG,MAAM,EAAE,CAOjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuB,GAAG,MAAM,CAK7F"}