@wavehouse/chtypes 0.5.2 → 1.0.0

package/dist/errors.js

@@ -1,321 +0,0 @@
-/**
- * The error model, which is three outcomes that must never be conflated
- * (the C ABI contract §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 -> usually code 691; 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 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 (docs/reference/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`.
- *
- * Revision 5 (2026-09-15, the explicit INSERT column list): `chs_row`,
- * `chs_rows` and `chs_block_parse` each gained a trailing `columns_json` —
- * `RowsOptions#columns`. This binding therefore speaks 5 and refuses
- * revision-4 artifacts — calling the 6-argument `chs_row` (or the
- * 9-argument `chs_rows`, or the 8-argument `chs_block_parse`) through a
- * revision-4 artifact's shorter declaration is undefined behavior, which is
- * exactly what the gate exists to prevent.
- *
- * Revision 6 (the error-code table and the partition key): `chs_error_codes`
- * and `chs_schema_partition_by` joined the surface. Purely additive, and still
- * a new number: this binding speaks 6 and refuses revision-5 artifacts.
- */
-export const ABI_REVISION = 6;
-/** Base class for everything this package throws. */
-export class ChtypesError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = new.target.name;
-    }
-}
-/** A registry could not be loaded, or a version could not be resolved. */
-export class RegistryError extends ChtypesError {
-}
-/**
- * This artifact IMAGE is already initialized under a different timezone.
- *
- * `dlopen` maps one image per file, and `chs_init` runs at most once per
- * image, so a second load asking for another zone can be neither honored nor
- * silently ignored: re-running `chs_init` would move the zone under the first
- * load's live libraries. A hardlink or symlink to a loaded artifact is that
- * same image and is refused the same way.
- *
- * A `RegistryError`, because it is a reason the loader cannot serve this
- * request — so a `catch` written against `for()`'s documented `RegistryError`
- * keeps working — and matched with `instanceof InitConflictError`, like every
- * other class here. Not an `ArtifactError`: the artifact is fine, and none of
- * the shared fetch codes describes it.
- */
-export class InitConflictError extends RegistryError {
-    /** The artifact path this load asked for, as given. */
-    path;
-    /** The timezone the image is live under. */
-    have;
-    /** The timezone this load asked for, refused. */
-    want;
-    constructor(path, have, want) {
-        super(`chtypes: ${path} is already initialized with timezone ${JSON.stringify(have)}; ` +
-            `cannot re-initialize with ${JSON.stringify(want)} (one image per file — a hardlink ` +
-            'or symlink to a loaded artifact is the same image, and chs_init runs at most once)');
-        this.path = path;
-        this.have = have;
-        this.want = want;
-    }
-}
-/**
- * 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`
- * (docs/reference/bindings.md rule 12).
- */
-export class SchemaError extends ChtypesError {
-    code;
-    detail;
-    column;
-    constructor(code, detail, column) {
-        super(column
-            ? `chtypes: column ${JSON.stringify(column)}: [${code}] ${detail}`
-            : `chtypes: [${code}] ${detail}`);
-        this.code = code;
-        this.detail = detail;
-        this.column = column;
-    }
-}
-/**
- * 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 class UnsupportedError extends ChtypesError {
-    detail;
-    column;
-    constructor(detail, column) {
-        super(column
-            ? `chtypes: column ${JSON.stringify(column)}: [${CODE_UNSUPPORTED}] ${detail}`
-            : `chtypes: [${CODE_UNSUPPORTED}] ${detail}`);
-        this.detail = detail;
-        this.column = column;
-    }
-}
-/**
- * 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 (docs/reference/bindings.md rule 12, the C ABI contract §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 function schemaErrorFor(code, detail, column) {
-    return code < 0 ? new UnsupportedError(detail, column) : new SchemaError(code, detail, column);
-}
-// ---------------------------------------------------------------- artifacts
-//
-// The fetch/verify contract (docs/guides/fetch.md §7) shares six codes across the
-// four SDKs. Five of them are verdicts of the verification chain or of the
-// source and are raised by `ensure` / the CLI; the sixth,
-// `CHTYPES_ARTIFACT_MISSING`, is the loader's — raised when a registry is
-// asked for a line no directory on the search path holds.
-/**
- * The codes docs/guides/fetch.md §6 shares across every SDK, as named constants.
- *
- * Each error below carries its own `code`, and a caller matches on it. Naming
- * them here is what lets that caller write `err.code === CODE_ARTIFACT_PINNED`
- * instead of retyping the string — which is exactly why the Go, Python and Rust
- * bindings all export them, and why this one already exported
- * `CODE_UNSUPPORTED`. A typo in a hand-written literal is a comparison that is
- * silently always false.
- */
-export const CODE_ARTIFACT_MISSING = 'CHTYPES_ARTIFACT_MISSING';
-/** docs/guides/fetch.md §6: the signature did not verify against the trust list. */
-export const CODE_ARTIFACT_UNTRUSTED = 'CHTYPES_ARTIFACT_UNTRUSTED';
-/** docs/guides/fetch.md §6: a hash mismatch, or a release that disagrees with itself. */
-export const CODE_ARTIFACT_CORRUPT = 'CHTYPES_ARTIFACT_CORRUPT';
-/** docs/guides/fetch.md §6: `--frozen` refused an asset the lock file does not pin. */
-export const CODE_ARTIFACT_PINNED = 'CHTYPES_ARTIFACT_PINNED';
-/** docs/guides/fetch.md §6: the release offers nothing for this platform or line. */
-export const CODE_ARTIFACT_UNPUBLISHED = 'CHTYPES_ARTIFACT_UNPUBLISHED';
-/** docs/guides/fetch.md §6: the source could not be reached or does not serve the release. */
-export const CODE_SOURCE_UNREACHABLE = 'CHTYPES_SOURCE_UNREACHABLE';
-/**
- * The single catchable type for every artifact-loading condition: a missing
- * artifact (`ArtifactMissingError`) or one of the five fetch/verify verdicts
- * (`FetchError`'s subclasses) — the six conditions docs/guides/fetch.md §3, §5
- * and §7 name. A caller that wants "the loader could not produce a usable
- * artifact" now catches exactly this one class, matching Python's
- * `ArtifactError`, Go's `*ArtifactError` (`.Code`), and Rust's
- * `Error::artifact_code()` (chtypes-sdk#13 A3, aligned 2026-09-15) — before
- * this, `ArtifactMissingError` was a `RegistryError` while the other five
- * were unrelated `FetchError`s, and a caller had to catch both types to
- * cover all six conditions.
- *
- * A `RegistryError`, because every one of these is a reason the loader could
- * not serve a version — `catch`es written against the pre-existing
- * `RegistryError` contract keep working unchanged.
- */
-export class ArtifactError extends RegistryError {
-}
-/** The command this SDK's §7 message tells a user to run. */
-export 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 function artifactMissingMessage(line, platform, lookedIn) {
-    return (`chtypes: no artifact for ClickHouse ${line} (${platform}). Looked in: ${lookedIn.join(', ')}.\n` +
-        `Install it:  ${FETCH_COMMAND} ${line}\n` +
-        'or set CHTYPES_AUTOFETCH=1 to fetch on first use.');
-}
-/**
- * The one identifiable error for a missing artifact (docs/guides/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 `ArtifactError` (itself a `RegistryError`), so a `catch`
- * written against `for()`'s documented `RegistryError`, or against the
- * single catchable `ArtifactError`, both keep working; the `code` is what a
- * caller matches on.
- */
-export class ArtifactMissingError extends ArtifactError {
-    code = 'CHTYPES_ARTIFACT_MISSING';
-    /** The minor line that was asked for, e.g. `25.8`. */
-    line;
-    /** The platform key the registry serves, e.g. `darwin-arm64`. */
-    platform;
-    /** Every directory of the search path, in order. */
-    lookedIn;
-    constructor(line, platform, lookedIn) {
-        super(artifactMissingMessage(line, platform, lookedIn));
-        this.line = line;
-        this.platform = platform;
-        this.lookedIn = [...lookedIn];
-    }
-}
-/**
- * Base of the fetch-time verdicts (docs/guides/fetch.md §3–§7). `code` is one of the
- * shared codes; the subclasses exist so `instanceof` reads as well as `code`.
- *
- * An `ArtifactError`, alongside `ArtifactMissingError` — so `catch (err) { if
- * (err instanceof ArtifactError) … }` handles all six artifact conditions in
- * one arm, while `instanceof FetchError` still isolates these five verdicts
- * from a missing artifact when that distinction matters.
- */
-export class FetchError extends ArtifactError {
-    code;
-    constructor(code, message, options) {
-        super(message, options);
-        this.code = code;
-    }
-}
-/**
- * `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 class ArtifactUntrustedError extends FetchError {
-    constructor(message, options) {
-        super('CHTYPES_ARTIFACT_UNTRUSTED', message, options);
-    }
-}
-/**
- * `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 class ArtifactCorruptError extends FetchError {
-    constructor(message, options) {
-        super('CHTYPES_ARTIFACT_CORRUPT', message, options);
-    }
-}
-/**
- * `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 class ArtifactPinnedError extends FetchError {
-    constructor(message, options) {
-        super('CHTYPES_ARTIFACT_PINNED', message, options);
-    }
-}
-/** `CHTYPES_ARTIFACT_UNPUBLISHED`: the release has nothing for this platform, line or exact patch. */
-export class ArtifactUnpublishedError extends FetchError {
-    constructor(message, options) {
-        super('CHTYPES_ARTIFACT_UNPUBLISHED', message, options);
-    }
-}
-/**
- * `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 class SourceUnreachableError extends FetchError {
-    constructor(message, options) {
-        super('CHTYPES_SOURCE_UNREACHABLE', message, options);
-    }
-}
-//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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