@wavehouse/chtypes 0.1.0

package/dist/paths.js

@@ -0,0 +1,78 @@
+/**
+ * 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).
+ */
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * This host's platform key, `<os>-<arch>` in the artifact spellings
+ * (`linux`/`darwin`, `arm64`/`amd64`), e.g. `darwin-arm64`.
+ */
+export function hostPlatform() {
+    const arch = { x64: 'amd64', arm64: 'arm64' }[os.arch()] ?? os.arch();
+    return `${os.platform()}-${arch}`;
+}
+/** True for the four platform keys a release can carry. */
+export function isPlatformKey(key) {
+    return /^(linux|darwin)-(arm64|amd64)$/.test(key);
+}
+/** `${XDG_CACHE_HOME:-~/.cache}/chtypes` — the root every chtypes cache lives under. */
+export function cacheRoot() {
+    const xdg = process.env['XDG_CACHE_HOME'];
+    const base = xdg !== undefined && xdg !== '' ? xdg : path.join(os.homedir(), '.cache');
+    return path.join(base, 'chtypes');
+}
+/** The per-user artifact cache for one platform — search-path slot (3). */
+export function cacheRegistryDir(platform = hostPlatform()) {
+    return path.join(cacheRoot(), 'artifacts', platform);
+}
+/** The reserved system locations — search-path slot (4), never written by fetch. */
+export function systemRegistryDirs(platform = hostPlatform()) {
+    return [`/usr/local/share/chtypes/artifacts/${platform}`, `/opt/chtypes/artifacts/${platform}`];
+}
+/**
+ * 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 function registrySearchPath(explicit, platform = hostPlatform()) {
+    const out = [];
+    if (explicit !== undefined && explicit !== '')
+        out.push(path.resolve(explicit));
+    const env = process.env['CHTYPES_REGISTRY'];
+    if (env !== undefined && env !== '')
+        out.push(path.resolve(env));
+    out.push(cacheRegistryDir(platform), ...systemRegistryDirs(platform));
+    return [...new Set(out)];
+}
+/**
+ * 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 function fetchDestination(explicit, platform = hostPlatform()) {
+    if (explicit !== undefined && explicit !== '')
+        return path.resolve(explicit);
+    const env = process.env['CHTYPES_REGISTRY'];
+    if (env !== undefined && env !== '' && platform === hostPlatform())
+        return path.resolve(env);
+    return cacheRegistryDir(platform);
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,IAAI,GAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAA6B,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;IAClG,OAAO,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,QAAQ,GAAW,YAAY,EAAE;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,QAAQ,GAAW,YAAY,EAAE;IAClE,OAAO,CAAC,sCAAsC,QAAQ,EAAE,EAAE,0BAA0B,QAAQ,EAAE,CAAC,CAAC;AAClG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAiB,EAAE,QAAQ,GAAW,YAAY,EAAE;IACrF,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB,EAAE,QAAQ,GAAW,YAAY,EAAE;IACnF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,IAAI,QAAQ,KAAK,YAAY,EAAE;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7F,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The artifact-directory loader: one subdirectory per ClickHouse minor line,
+ * each self-contained (spec/artifact.md).
+ *
+ *   <registry>/25.8/{manifest.json, libchtypes.dylib, CH_VERSION, unsafe_families.txt}
+ *
+ * Two rules here were paid for and are not negotiable:
+ *
+ *  - **The shared library's file name comes from `manifest.json`'s `library`
+ *    field.** Not from a hard-coded `libchtypes.so`, not from a glob, not from
+ *    the platform. The current tree proves why: every darwin artifact says
+ *    `libchtypes.dylib` while the *shipping* linux artifacts still say
+ *    `libchtypes_s1.so`, so a loader that constructs the name finds nothing on
+ *    the platform that matters.
+ *  - **Each artifact is loaded into its own symbol scope (`RTLD_LOCAL`).** That
+ *    is the entire mechanism by which two builds that both define
+ *    `DB::DataTypeFactory` live in one process. ffi-rs loads through libloading,
+ *    which uses `RTLD_LAZY | RTLD_LOCAL`; `assertLocalSymbolScope()` in the test
+ *    suite proves it from outside rather than trusting the claim.
+ *
+ * Where a registry IS follows the search path of docs/fetch.md §1 (`paths.ts`):
+ * the explicit directory, `CHTYPES_REGISTRY`, the per-user cache, then the
+ * reserved system locations. The first directory holding artifacts is scanned
+ * and loaded at construction; a line it lacks is taken, on request, from the
+ * first later directory that has it. A line no directory has is the one §7
+ * error, `ArtifactMissingError` — or, with `autofetch`, a fetch on first
+ * `open()`.
+ */
+import { type EnsureOptions } from './fetch.js';
+import { Library } from './library.js';
+/** The nine fields `lib/build.sh` writes. Unknown fields are ignored. */
+export interface Manifest {
+    library: string;
+    library_bytes?: number;
+    library_sha256?: string;
+    clickhouse_version?: string;
+    clickhouse_minor?: string;
+    clickhouse_commit?: string;
+    os?: string;
+    arch?: string;
+    unsafe_families?: string;
+}
+/** Options for `new Registry(dir, options)`. */
+export interface RegistryOptions {
+    /**
+     * The server timezone assumed for bare DateTime / DateTime64 columns. Defaults
+     * to UTC — what a stock ClickHouse container uses — and is deliberately not
+     * read from the environment, so the host's TZ cannot leak into results.
+     */
+    timezone?: string;
+    /**
+     * Re-hash each library and compare against `manifest.library_sha256` before
+     * loading. SHOULD be on for an artifact that came from anywhere but a local
+     * build, and MUST be on for one that came over a network.
+     */
+    verifyChecksums?: boolean;
+    /**
+     * Lazy fetch on first open (docs/fetch.md §6): `open()` of a line no
+     * directory on the search path holds runs `ensure()` first, into the
+     * directory a fetch writes to (§1), once per process per line. Off by
+     * default — a production process must not begin a 250 MB download inside
+     * a request — and `CHTYPES_AUTOFETCH=1` turns it on from the environment.
+     * `for()` stays synchronous and never fetches.
+     */
+    autofetch?: boolean | undefined;
+    /** Options handed to `ensure()` by autofetch: source (`url`/`tag`), lock, keys, progress. */
+    fetch?: EnsureOptions | undefined;
+}
+/**
+ * The artifact-directory loader — the multi-version entry point of this
+ * package. Construction scans one subdirectory per ClickHouse version, dlopens
+ * each artifact into its own symbol scope (`RTLD_LOCAL`, ~120 MB resident per
+ * version), verifies its ABI revision against this binding's `ABI_REVISION`
+ * (a different nonzero revision is refused; 0 means the artifact predates the
+ * probe and degrades per symbol), and runs each library's one-time
+ * `chs_init` with the UTC default timezone and the artifact's own
+ * `unsafe_families.txt`.
+ *
+ * Libraries are never dlclosed; `close()` joins background threads only.
+ * Loading the same artifact path from two `Registry` instances shares one
+ * loaded image, so `chs_init` still runs exactly once per artifact.
+ */
+export declare class Registry {
+    /**
+     * The primary registry directory: the first on the search path that held
+     * artifacts, scanned and loaded at construction — or, with `autofetch` and
+     * nothing installed anywhere, the directory the first fetch will create.
+     */
+    readonly dir: string;
+    /** The §1 search path, in order, every candidate whether or not it exists. */
+    readonly searchPath: readonly string[];
+    /** This host's platform key, e.g. `darwin-arm64` — the only artifacts a process can dlopen. */
+    readonly platform: string;
+    private readonly byId;
+    private readonly byPath;
+    private readonly loaded;
+    private readonly timezone;
+    private readonly verifyChecksums;
+    private readonly autofetch;
+    private readonly fetchOptions;
+    private readonly explicit;
+    /**
+     * Scan and load a registry.
+     *
+     * @param dir - the registry root; the head of the search path. Absent, the
+     *   path is `CHTYPES_REGISTRY`, the per-user artifact cache, then the system
+     *   locations (see `registrySearchPath` / `defaultRegistryDir`).
+     * @param options - timezone, checksum verification, autofetch — see `RegistryOptions`.
+     * @throws {RegistryError} when a directory named explicitly (the argument or
+     *   `CHTYPES_REGISTRY`) does not exist and autofetch is off, when no
+     *   directory on the search path holds an artifact (and autofetch is off),
+     *   the primary directory cannot be read, an artifact fails its checksum,
+     *   fails to load, or reports a ClickHouse version different from its
+     *   manifest's.
+     * @throws {ChtypesError} when an artifact reports a different nonzero ABI
+     *   revision than this binding speaks, or `chs_init` fails (e.g. an unknown
+     *   timezone — the message names it).
+     */
+    constructor(dir?: string, options?: RegistryOptions);
+    /** dlopen one artifact directory, cross-check it, `chs_init` it, index it. */
+    private load;
+    /** Load `<dir>/<minor>/` if it is an artifact directory; null when it is not. */
+    private loadLine;
+    private lookup;
+    /** The ClickHouse minor lines this registry has loaded, oldest first. */
+    versions(): string[];
+    /** Every loaded library, in release order (oldest minor line first). */
+    libraries(): readonly Library[];
+    /**
+     * Resolve a version to its library. A minor line ("25.8") or an exact patch
+     * ("25.8.28.1-lts") both work, and an unknown patch inside a loaded minor line
+     * resolves to that line — asking for "25.8.30.16" finds the loaded 25.8.
+     *
+     * A line the primary directory lacks is loaded from the first later
+     * directory on the search path that holds it (docs/fetch.md §1), and joins
+     * `versions()` / `libraries()` from then on. Never a fetch: this call is
+     * synchronous; `open()` is the one that may fetch.
+     *
+     * Failure is the one §7 error, never a fallback to the nearest version:
+     * answering 26.7 semantics from a 25.8 artifact is a lie, and silent
+     * wrongness is what the rigs score hardest.
+     *
+     * @param version - a minor line (`"25.8"`) or an exact patch
+     *   (`"25.8.28.1-lts"`), e.g. what `parseVersionResult` discovered.
+     * @returns the loaded `Library` for that version.
+     * @throws {ArtifactMissingError} (`code` `CHTYPES_ARTIFACT_MISSING`, a
+     *   `RegistryError`) when no directory on the search path holds the line;
+     *   the message names every directory looked in and the fetch command.
+     * @throws {RegistryError} when a directory holds the line but it does not load.
+     */
+    for(version: string): Library;
+    /**
+     * `for()`, with the lazy fetch of docs/fetch.md §6 in front of it: a line no
+     * directory on the search path holds is fetched through `ensure()` — into
+     * the directory a fetch writes to (§1), verified, once per process per line
+     * even under concurrent opens — and then loaded. With `autofetch` off (the
+     * default) this is `for()` behind a promise, and a missing line rejects
+     * with the same `ArtifactMissingError`.
+     *
+     * @throws {ArtifactMissingError} when the line is missing and autofetch is off.
+     * @throws {FetchError} the §7 fetch verdicts (`CHTYPES_ARTIFACT_UNTRUSTED`,
+     *   `…_CORRUPT`, `…_PINNED`, `…_UNPUBLISHED`, `CHTYPES_SOURCE_UNREACHABLE`).
+     * @throws {RegistryError} when the fetched artifact does not load.
+     */
+    open(version: string): Promise<Library>;
+    /**
+     * True when this registry can answer for a version: loaded already, or held
+     * by a directory on the search path (which `for()` would load). Never a
+     * fetch, and never a load.
+     */
+    has(version: string): boolean;
+    /**
+     * Join every loaded library's background threads. `chs_init` registers
+     * `chs_shutdown` with `atexit`, so an ordinary process needs no call; a test
+     * that must not depend on `atexit` should make one.
+     */
+    close(): void;
+    /** `using registry = new Registry(...)` closes it at scope exit. */
+    [Symbol.dispose](): void;
+}
+/** Numeric ordering: 25.10 is a later minor than 25.8, whatever strings say. */
+export declare function compareMinor(a: string, b: string): number;
+/**
+ * Where the registry is: the explicit argument, else `CHTYPES_REGISTRY`, else
+ * the first of the per-user artifact cache and the system locations that
+ * holds artifacts (docs/fetch.md §1). An explicit path and the environment
+ * variable are returned as given — a wrong one must produce an error naming
+ * it, not a silent fallback — while the unnamed candidates only count if they
+ * actually hold artifacts.
+ */
+export declare function resolveRegistryDir(explicit?: string): string | null;
+/**
+ * The per-user artifact cache for this host —
+ * `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/<os>-<arch>`, `<arch>` spelled
+ * the artifact way (`amd64`, `arm64`). Where `chtypes fetch` and
+ * `scripts/fetch.sh` install, where a core-repository build lands, and what
+ * every SDK's tests and playgrounds fall back to when `CHTYPES_REGISTRY` is
+ * unset — one directory the four SDKs agree on. A path, not a promise:
+ * `Registry` still throws if nothing is there.
+ */
+export declare function defaultRegistryDir(): string;
+/** Does this directory hold at least one artifact with a usable manifest? */
+export declare function looksLikeRegistry(dir: string): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

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