@wavehouse/chtypes 0.1.0

package/dist/schema.js

@@ -0,0 +1,448 @@
+/**
+ * A compiled schema — one tenant table's column list, compiled inside one
+ * version's library, plus the engine and TTL declarations that make `rows()`
+ * answer with the storage layer's verdict as well as the type layer's.
+ */
+import { ChtypesError } from './errors.js';
+import { DOC_ALL, EXPORT_NONE } from './format.js';
+import { parseDocument } from './json.js';
+import { batchResultOf, filterResultOf, rowResultOf, } from './results.js';
+import { encodeSettings } from './settings.js';
+/**
+ * A compiled schema — one tenant table's column list, compiled inside one
+ * version's library. Obtained from `Library#compileDdl`; never constructed
+ * directly. Release with `close()` (idempotent) or `using` / `Symbol.dispose`.
+ *
+ * Thread-safety: the C ABI forbids using one `chs_schema *` from two threads
+ * at once; on a single JS thread every call here is synchronous, so ordinary
+ * Node code satisfies that by construction. Do not share a `Schema` across
+ * `worker_threads`.
+ */
+export class Schema {
+    native;
+    ddl;
+    /**
+     * The declared columns as ClickHouse canonicalised them, in declaration
+     * order — flattened under `flatten_nested=1`, DEFAULT-rewritten types
+     * (`x Int64 DEFAULT NULL` compiles as `Nullable(Int64)`), ALIAS types
+     * inferred. A gateway detects EPHEMERAL columns here, at compile time
+     * (`defaultKind === 'EPHEMERAL'`), not per row.
+     */
+    columns;
+    handle;
+    /**
+     * Every open `Filter` compiled from this handle, so `close()` can free them
+     * FIRST — the C layer does not refcount, and freeing the schema under a
+     * live filter is use-after-free (spec/c-abi.md §Filters, handle lifetime).
+     */
+    filters = new Set();
+    /**
+     * Every open `Block` parsed from this handle — the same non-owning rule,
+     * the same free-before-schema order (spec/c-abi.md §Blocks).
+     */
+    blocks = new Set();
+    /** @internal — obtained from `Library#compileDdl`. */
+    constructor(native, handle, 
+    /** The column-declaration list this schema was compiled from, verbatim. */
+    ddl) {
+        this.native = native;
+        this.ddl = ddl;
+        this.handle = handle;
+        this.columns = native.columns(handle);
+    }
+    live() {
+        if (this.handle === null)
+            throw new ChtypesError('chtypes: schema is closed');
+        return this.handle;
+    }
+    /**
+     * Declare the table engine, so `rows()` applies the engine's own insert-time
+     * merge (`optimize_on_insert = 1`): a CollapsingMergeTree refusing an invalid
+     * Sign with code 117 before anything is stored, a SummingMergeTree summing
+     * equal keys and dropping all-zero rows, a ReplacingMergeTree deduplicating.
+     *
+     * `options.mergeTreeSettings` declares the table's MergeTree-namespace
+     * settings — see `EngineOptions` for the error contract (unknown name ⇒ the
+     * server's 115; non-default declared value ⇒ `unsupported`, never silently
+     * ignored). Absent/empty is structurally the plain engine declaration:
+     * `chs_schema_engine` takes "{}" either way.
+     *
+     * The two error classes here are the refusal/decline split and MUST be
+     * handled as peers — `UnsupportedError` is deliberately NOT
+     * `instanceof SchemaError` (spec/bindings.md rule 12):
+     *
+     * @param engine - the engine expression, e.g. `"SummingMergeTree"`,
+     *   `"CollapsingMergeTree(sign)"`.
+     * @param orderBy - the sorting key, e.g. `"(day, key)"`.
+     * @param options - the MergeTree-namespace `SETTINGS` clause, if any.
+     * @throws {SchemaError} when the SERVER refused (positive code): this DDL
+     *   can never exist and the tenant has to be told. Today that is 115, an
+     *   unknown MergeTree setting name, with the server's own message verbatim.
+     * @throws {UnsupportedError} when this LIBRARY declined: an engine or
+     *   sorting key this build does not model, a known MergeTree setting
+     *   declared at a non-default value, or a guarded exception. A real server
+     *   might well have accepted it — validate cautiously, fall back to the
+     *   server, and never present the decline as a rejection.
+     */
+    setEngine(engine, orderBy, options) {
+        this.native.schemaEngine(this.live(), engine, orderBy, encodeSettings(options?.mergeTreeSettings));
+    }
+    /**
+     * Declare the table's rows TTL (`ts + INTERVAL 30 DAY`). An expired row is
+     * reported NOT STORED through the batch's `transformed` list.
+     *
+     * Column-level TTLs need no call: they are part of the declaration list.
+     *
+     * @param ttl - the rows-TTL expression, e.g. `"ts + INTERVAL 30 DAY"`. It is
+     *   validated under the handle's declared compile profile when one exists.
+     * @throws {UnsupportedError} for a TTL form this build refuses rather than
+     *   guesses: WHERE / GROUP BY TTLs, TO DISK/VOLUME moves, RECOMPRESS, any
+     *   clock-reading TTL expression, and guarded exceptions. Fall back to the
+     *   server; do not report a tenant error.
+     */
+    setTtl(ttl) {
+        this.native.schemaTtl(this.live(), ttl);
+    }
+    /**
+     * Validate and coerce ONE row body, answering exactly as this ClickHouse
+     * version's insert path would.
+     *
+     * There is no exception for a bad row: rejection, poisoning and declines all
+     * arrive as the `RowResult`'s `outcome` (see `Outcome` for the taxonomy and
+     * the caller's obligations per arm).
+     *
+     * @param format - the wire format code (`Format`). Binary-format support
+     *   depends on the loaded artifact — probe, don't assume.
+     * @param raw - the row's bytes, exactly as they would arrive in an INSERT
+     *   body. Always bytes, never a JS string: binary formats contain NUL bytes
+     *   and text rows can carry invalid UTF-8 on purpose.
+     * @param settings - per-call settings; they win over the compile profile and
+     *   the library defaults (except a type gate the profile declared, which the
+     *   handle has already settled, as a real server's CREATE does).
+     * @returns the `RowResult` — verdict, stored values, and every silent change.
+     * @throws {ChtypesError} when the schema is closed, or a settings value is a
+     *   JS `number`.
+     * @throws {UnsupportedError} when the artifact predates `chs_row`.
+     */
+    row(format, raw, settings) {
+        const doc = this.native.row(this.live(), format, raw, encodeSettings(settings));
+        return rowResultOf(parseDocument(doc));
+    }
+    /**
+     * Validate and coerce a whole request body, which may hold many rows.
+     *
+     * This is not `row()` in a loop and must never be implemented as one: row
+     * separation is format-specific (a quoted CSV field can contain a newline),
+     * `input_format_allow_errors_num` / `_ratio` decide whether a bad row is
+     * skipped or aborts the batch, and one batch is one clock instant for the
+     * volatile-DEFAULT guarantee.
+     *
+     * @param format - the wire format code (`Format`).
+     * @param body - the whole request body as bytes (never a JS string).
+     * @param settings - per-call settings; same precedence as `row`.
+     * @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
+     *   is the stored truth, and batch-level storage transforms (`ttl_expired`,
+     *   `ttl_column_expired`) are folded into `transformed`.
+     * With `options.exportFormat` the same ONE call also serializes the batch's
+     * accepted rows through the vendored writer: `payload` carries the bytes
+     * (zero-length = emitted-empty, an accepted batch with zero accepted rows;
+     * `undefined` + `exportDeclined` = withheld, with the reason), and `spans`
+     * is index-aligned with `rows` — `payload.subarray(s.off, s.off + s.len)`
+     * IS row i's line. With `options.docFlags` the per-row documents are
+     * thinned to the selected groups; the verdict channel is never thinned.
+     * See `RowsOptions` for the defaults and `BatchResult` for the three
+     * payload states.
+     *
+     * @param format - the wire format code (`Format`).
+     * @param body - the whole request body as bytes (never a JS string).
+     * @param settings - per-call settings; same precedence as `row`.
+     * @param options - the revision-3 export/doc-flag channels; absent =
+     *   today's full document, byte-identical to revision 2.
+     * @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
+     *   is the stored truth, and batch-level storage transforms (`ttl_expired`,
+     *   `ttl_column_expired`) are folded into `transformed`.
+     * @throws {ChtypesError} when the schema is closed, a settings value is a JS
+     *   `number`, or the artifact predates `chs_rows` (a mandatory symbol).
+     */
+    rows(format, body, settings, options) {
+        const exportFormat = options?.exportFormat ?? EXPORT_NONE;
+        const docFlags = options?.docFlags ?? (options?.exportFormat === undefined ? DOC_ALL : 0);
+        const { doc, payload } = this.native.rows(this.live(), format, body, encodeSettings(settings), exportFormat, docFlags);
+        return batchResultOf(parseDocument(doc), payload);
+    }
+    /**
+     * Compile one boolean SQL expression over this schema's PHYSICAL columns
+     * (ordinary + MATERIALIZED; naming an ALIAS/EPHEMERAL column fails with
+     * ClickHouse's own UNKNOWN_IDENTIFIER, exactly where a real CREATE fails) —
+     * the same TreeRewriter + ExpressionAnalyzer pipeline the CONSTRAINT CHECK
+     * path runs, so comparison semantics are WHERE-side by construction:
+     * `x = 256` over UInt8 promotes (false for every row), it never wraps
+     * (spec/c-abi.md §Filters).
+     *
+     * The expression may contain `{name:Type}` query parameters, bound with
+     * `options.params` (revision 4) — substitution is the server's own
+     * `ReplaceQueryParameterVisitor`, run before analysis, exactly where a
+     * real server runs it; see `CompileFilterOptions` for the injection-safety
+     * and cache-discipline contract. Close the filter when done (`close()` /
+     * `Symbol.dispose`); `schema.close()` also closes every open filter FIRST,
+     * so no caller ordering can free the schema under a live filter.
+     *
+     * ENFORCEMENT GATE: nothing may enforce read-side security on this surface
+     * until the WHERE-truth rig gates green (zero over-admit, zero over-hide);
+     * until then it is a shadow/replay surface.
+     *
+     * @param expr - one boolean expression, e.g. `"x = 256"` or
+     *   `"tenant = {t:String}"`.
+     * @param options - the `{name:Type}` bindings, if any.
+     * @returns the compiled `Filter`.
+     * @throws {SchemaError} when ClickHouse itself refuses the expression —
+     *   unknown identifier (47), unknown function, an analyzer-raised
+     *   NO_COMMON_TYPE — and, since revision 4, the server's own parameter
+     *   refusals: an UNBOUND `{name:Type}` is **456** UNKNOWN_QUERY_PARAMETER
+     *   ("Substitution `name` is not set"), a value the declared type cannot
+     *   parse completely is **457** BAD_QUERY_PARAMETER — the server's own
+     *   code and message, verbatim. A bound name the expression never uses is
+     *   ignored, as a live server ignores an unused `param_*`.
+     * @throws {UnsupportedError} when this build declines: a non-deterministic
+     *   expression (clock reads — `now() > ts` —, `rand()`, server-constants;
+     *   the scan runs AFTER substitution, so a value can never smuggle one
+     *   in), or an artifact that predates the filter trio.
+     */
+    compileFilter(expr, options) {
+        const handle = this.native.filterCompile(this.live(), expr, encodeSettings(options?.params));
+        const filter = new Filter(this.native, this, handle, expr);
+        this.filters.add(filter);
+        return filter;
+    }
+    /** @internal — `Filter#close` deregisters itself here. */
+    forgetFilter(filter) {
+        this.filters.delete(filter);
+    }
+    /**
+     * Parse a body ONCE into a `Block` (`chs_block_parse`) — the parse half of
+     * `Filter#rows`, exported so K filters can evaluate one event with no
+     * re-parse (`Filter#eval`; spec/c-abi.md §Blocks). Same formats and
+     * settings contract as `rows` (`settings` is the PARSE-side map: format
+     * settings, clock keys; evaluation takes none). Volatile DEFAULTs resolve
+     * against THIS call's clock instant, so
+     * `filter.eval(schema.parseBlock(...))` ≡ `filter.rows(...)` exactly when
+     * the clock is pinned (`chtypes_now_epoch_nanos`) or the schema has no
+     * volatile DEFAULT.
+     *
+     * Per-row parse failures do NOT throw — they are recorded IN the block and
+     * answer `'decline'` from every filter, with the recorded error. Release
+     * with `close()` / `Symbol.dispose`; `schema.close()` closes open blocks
+     * FIRST, the C-required order.
+     *
+     * @param format - the wire format code (`Format`).
+     * @param body - the rows as bytes (never a JS string).
+     * @param settings - parse-side settings; same precedence as `Schema#rows`.
+     * @returns the parsed `Block`.
+     * @throws {SchemaError} on a call-level failure — an unknown setting's
+     *   115, an unsplittable body, a binary decode fault, the deferred
+     *   JSONEachRow framing verdict: a malformed body yields no block and no
+     *   partial answers.
+     * @throws {UnsupportedError} when this build declines the call, or the
+     *   artifact predates the block twin.
+     */
+    parseBlock(format, body, settings) {
+        const handle = this.native.blockParse(this.live(), format, body, encodeSettings(settings));
+        const block = new Block(this.native, this, handle);
+        this.blocks.add(block);
+        return block;
+    }
+    /** @internal — `Block#close` deregisters itself here. */
+    forgetBlock(block) {
+        this.blocks.delete(block);
+    }
+    /**
+     * Release the native schema. Idempotent. After it, `row` / `rows` /
+     * `setEngine` / `setTtl` throw `ChtypesError` ("schema is closed").
+     * Any `Filter` or `Block` still open on this schema is closed FIRST, in
+     * the same call — the handles-before-schema free order the C layer
+     * requires, enforced here so no dispose ordering can get it backwards.
+     */
+    close() {
+        for (const filter of this.filters)
+            filter.close();
+        this.filters.clear();
+        for (const block of this.blocks)
+            block.close();
+        this.blocks.clear();
+        if (this.handle === null)
+            return;
+        this.native.schemaFree(this.handle);
+        this.handle = null;
+    }
+    /** `using schema = lib.compileDdl(...)` releases it at scope exit. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+/**
+ * One boolean SQL expression compiled against a `Schema`'s columns
+ * (`chs_filter_compile`). Obtained from `Schema#compileFilter`; never
+ * constructed directly.
+ *
+ * LIFETIME: a filter REFERENCES its schema handle — the C layer does not copy
+ * and does not refcount (spec/c-abi.md §Filters). This binding enforces the
+ * free order structurally, both ways: the `Filter` holds its `Schema` (so the
+ * schema stays reachable), and `Schema#close` closes every open filter before
+ * freeing the schema. `close()` is idempotent, and `using` / `Symbol.dispose`
+ * work on both objects in any nesting — the schema's dispose runs the
+ * filter's first when the caller forgot. A filter compiled from a schema
+ * answers for THAT handle: recompile filters when the schema is recompiled.
+ *
+ * THREADS: the header's rule, verbatim — one `chs_filter` "must not be used
+ * from two threads at once, and a chs_filter call is ALSO a use of its schema
+ * handle" (two filters over ONE schema must not run concurrently either). On
+ * a single JS thread every call here is synchronous, so ordinary Node code
+ * satisfies both by construction (spec/bindings.md §Concurrency); do not
+ * share a `Filter` — or its `Schema` — across `worker_threads`.
+ *
+ * ENFORCEMENT GATE: `'error'` and `'decline'` verdicts are NOT answers — a
+ * caller enforcing visibility MUST fail closed on both — and NO caller may
+ * enforce read-side security on this surface until the WHERE-truth rig gates
+ * green; until then it is a shadow/replay surface (spec/c-abi.md §Filters).
+ */
+export class Filter {
+    native;
+    schema;
+    expr;
+    handle;
+    /** @internal — obtained from `Schema#compileFilter`. */
+    constructor(native, schema, handle, 
+    /** The expression text as compiled, for logging and cache keys. */
+    expr) {
+        this.native = native;
+        this.schema = schema;
+        this.expr = expr;
+        this.handle = handle;
+    }
+    /**
+     * Evaluate the filter over a body of rows (`chs_filter_rows`) — the same
+     * formats and settings contract as `Schema#rows`, ONE C call. Rows are
+     * evaluated INDEPENDENTLY (there is no INSERT to abort):
+     * `input_format_allow_errors_*` does not apply, a bad text row declines
+     * (`'decline'`) and the tail resyncs so verdict indexes keep matching input
+     * rows, and volatile DEFAULTs resolve against one clock instant per call.
+     *
+     * @param format - the wire format code (`Format`).
+     * @param body - the rows as bytes (never a JS string).
+     * @param settings - per-call settings; same precedence as `Schema#rows`.
+     * @returns the `FilterResult` — the call-level outcome, and one verdict per
+     *   row when it is `'ok'`.
+     * @throws {ChtypesError} when the filter is closed, or a settings value is
+     *   a JS `number`.
+     */
+    rows(format, body, settings) {
+        if (this.handle === null)
+            throw new ChtypesError('chtypes: filter is closed');
+        const doc = this.native.filterRows(this.handle, format, body, encodeSettings(settings));
+        return filterResultOf(parseDocument(doc));
+    }
+    /**
+     * Evaluate this filter over an already-parsed `Block` (`chs_filter_eval`)
+     * — the SAME result document `rows` returns: same `FilterResult` fields,
+     * same verdicts, same `errors` rule (a row the parse recorded as
+     * unparseable answers `'decline'` with the recorded error). Evaluation is
+     * a pure function of (filter, block): no settings, and the block is
+     * neither consumed nor mutated, so one block can be evaluated by K filters
+     * sequentially with no re-parse — the live-SSE call shape.
+     *
+     * Filter and block MUST come from the SAME schema: a mismatched pair
+     * answers a REJECTED result (code 1002) — the C layer's loud refusal,
+     * never undefined behaviour. A pair from two different libraries throws
+     * `ChtypesError`: no handle ever crosses a dlopen'd image boundary.
+     *
+     * @param block - a `Block` from `Schema#parseBlock`.
+     * @returns the `FilterResult`, exactly as `rows` would answer it.
+     * @throws {ChtypesError} when the filter or block is closed, or they come
+     *   from two different libraries.
+     */
+    eval(block) {
+        if (this.handle === null)
+            throw new ChtypesError('chtypes: filter is closed');
+        if (block.nativeLib !== this.native) {
+            throw new ChtypesError('chtypes: filter and block come from different libraries');
+        }
+        const doc = this.native.filterEval(this.handle, block.liveHandle());
+        return filterResultOf(parseDocument(doc));
+    }
+    /**
+     * Release the native filter (`chs_filter_free`). Idempotent, and also
+     * performed by the schema's own `close()` — filters first, then the schema,
+     * the C-required order.
+     */
+    close() {
+        if (this.handle === null)
+            return;
+        this.native.filterFree(this.handle);
+        this.handle = null;
+        this.schema.forgetFilter(this);
+    }
+    /** `using filter = schema.compileFilter(...)` releases it at scope exit. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+/**
+ * One body, parsed ONCE under one schema handle and one clock instant
+ * (`chs_block_parse`). Obtained from `Schema#parseBlock`; evaluated by
+ * `Filter#eval`. The parse-once/eval-many twin of `Filter#rows`
+ * (spec/c-abi.md §Blocks): the live-SSE hot path is K filters × 1 event, and
+ * the block sheds the re-parse.
+ *
+ * LIFETIME: a block REFERENCES its schema handle exactly as a filter does —
+ * the C layer does not copy and does not refcount. This binding enforces the
+ * free order structurally, both ways: the `Block` holds its `Schema` (so the
+ * schema stays reachable), and `Schema#close` closes every open block before
+ * freeing the schema — `using` / `Symbol.dispose` work on all three objects
+ * in any nesting, and the schema's dispose runs the block's first when the
+ * caller forgot. A block may be evaluated by MANY filters, sequentially;
+ * evaluation does not consume or mutate it. Recompile blocks when the schema
+ * is recompiled.
+ *
+ * THREADS: one block must not be used from two threads at once, and an eval
+ * is a use of BOTH handles. On a single JS thread every call here is
+ * synchronous, so ordinary Node code satisfies both by construction; do not
+ * share a `Block` — or its `Schema` — across `worker_threads`.
+ */
+export class Block {
+    native;
+    schema;
+    handle;
+    /** @internal — obtained from `Schema#parseBlock`. */
+    constructor(native, schema, handle) {
+        this.native = native;
+        this.schema = schema;
+        this.handle = handle;
+    }
+    /** @internal — the loaded library this block's handle belongs to. */
+    get nativeLib() {
+        return this.native;
+    }
+    /** @internal — the live handle, for `Filter#eval`. */
+    liveHandle() {
+        if (this.handle === null)
+            throw new ChtypesError('chtypes: block is closed');
+        return this.handle;
+    }
+    /**
+     * Release the native block (`chs_block_free`). Idempotent, and also
+     * performed by the schema's own `close()` — blocks first, then the schema,
+     * the C-required order.
+     */
+    close() {
+        if (this.handle === null)
+            return;
+        this.native.blockFree(this.handle);
+        this.handle = null;
+        this.schema.forgetBlock(this);
+    }
+    /** `using block = schema.parseBlock(...)` releases it at scope exit. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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

package/dist/settings.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A setting value crosses the boundary as a JSON **string**, always.
+ *
+ * This is not cosmetic (spec/c-abi.md §Settings): `chtypes_now_epoch_nanos` is a
+ * 19-digit nanosecond epoch, which does not survive an IEEE double. Serialised
+ * as a JSON *number* through a JS `number` it arrives as 1.7e+18 and the setting
+ * is **silently ignored** — the batch keeps stamping the real wall clock and
+ * nothing anywhere says so.
+ *
+ * The type therefore admits `string` and `bigint` and not `number`, and the
+ * runtime rejects a `number` as well, because TypeScript is not present at the
+ * call site of a JS consumer.
+ */
+export type SettingValue = string | bigint;
+/**
+ * A map of ClickHouse query/format settings plus the six `chtypes_*` keys
+ * (clock control and admission budgets — spec/c-abi.md §Settings), by name.
+ *
+ * Accepted everywhere settings travel: the compile profile
+ * (`Library#compileDdl`), the per-call map (`Schema#row` / `Schema#rows`), the
+ * process seed (`Library#setDefaultSettings`) and the engine's
+ * MergeTree-namespace settings (`Schema#setEngine`). Precedence on the row
+ * path: per-call > compile profile > library defaults > ClickHouse defaults —
+ * except a TYPE GATE declared in the compile profile, which binds at compile
+ * and then outranks the per-call map, as a real server's CREATE does.
+ *
+ * An unknown setting name is refused WHOLESALE with the server's own code 115
+ * on every channel — nothing is applied, nothing is silently dropped.
+ */
+export type Settings = Readonly<Record<string, SettingValue>>;
+/**
+ * Serialise settings to the `settings_json` object the C ABI expects — every
+ * value crossing as a JSON string.
+ *
+ * @param settings - the settings map; `undefined` encodes as `"{}"`, the
+ *   structurally settings-free path.
+ * @returns the JSON text to hand to a `chs_*` entry point.
+ * @throws {ChtypesError} when a value is neither `string` nor `bigint` — a JS
+ *   `number` is rejected at runtime because a 19-digit nanosecond epoch does
+ *   not survive an IEEE double and the setting would be silently ignored.
+ */
+export declare function encodeSettings(settings?: Settings): string;
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAkB1D"}

package/dist/settings.js

@@ -0,0 +1,33 @@
+import { ChtypesError } from './errors.js';
+/**
+ * Serialise settings to the `settings_json` object the C ABI expects — every
+ * value crossing as a JSON string.
+ *
+ * @param settings - the settings map; `undefined` encodes as `"{}"`, the
+ *   structurally settings-free path.
+ * @returns the JSON text to hand to a `chs_*` entry point.
+ * @throws {ChtypesError} when a value is neither `string` nor `bigint` — a JS
+ *   `number` is rejected at runtime because a 19-digit nanosecond epoch does
+ *   not survive an IEEE double and the setting would be silently ignored.
+ */
+export function encodeSettings(settings) {
+    if (settings === undefined)
+        return '{}';
+    const out = {};
+    for (const [key, value] of Object.entries(settings)) {
+        if (typeof value === 'string') {
+            out[key] = value;
+        }
+        else if (typeof value === 'bigint') {
+            out[key] = value.toString();
+        }
+        else {
+            throw new ChtypesError(`chtypes: setting ${JSON.stringify(key)} must be a string or a bigint, got ` +
+                `${typeof value}. A JS number cannot carry a 19-digit nanosecond epoch: ` +
+                `1700000000123456789 becomes 1.7e+18 and the setting is silently ignored ` +
+                `(spec/c-abi.md §Settings).`);
+        }
+    }
+    return JSON.stringify(out);
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAkC3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmB;IAChD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,YAAY,CACpB,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,qCAAqC;gBAC1E,GAAG,OAAO,KAAK,0DAA0D;gBACzE,0EAA0E;gBAC1E,4BAA4B,CAC/B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/tar.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A streaming reader for the artifact tarballs — ustar, pax extended
+ * headers, GNU long names — written here rather than taken from a
+ * dependency: this package's one runtime dependency is ffi-rs, and a reader
+ * that extracts regular files under one directory is a page of code.
+ *
+ * Files only. Directories are created; everything else — symlinks, hard
+ * links, devices, FIFOs — is skipped without being followed: an artifact is
+ * `manifest.json`, one library and two text files, and a link inside one is
+ * an attack, not a feature. Every entry name is confined to the destination
+ * (no absolute names, no `..` components, no escape once resolved), and a
+ * name that escapes is refused as corrupt rather than clamped.
+ *
+ * The archive is consumed as a stream: a 300 MB library is written to disk
+ * as it inflates and never sits in memory whole.
+ */
+/** One regular file the extractor wrote. */
+export interface ExtractedEntry {
+    /** The entry name as confined under the destination, `/`-separated. */
+    readonly name: string;
+    readonly size: number;
+}
+/**
+ * Inflate and unpack `archive` (a `.tar.gz`) into `dest`, which must already
+ * exist. Returns the regular files written, in archive order.
+ *
+ * @throws {ArtifactCorruptError} when the bytes are not a gzip stream, a
+ *   header fails its checksum, the archive is truncated, or an entry name
+ *   would land outside `dest`.
+ */
+export declare function extractTarGz(archive: string, dest: string): Promise<ExtractedEntry[]>;
+//# sourceMappingURL=tar.d.ts.map

package/dist/tar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../src/tar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAW3F"}