@wavehouse/chtypes 0.2.1 → 0.3.0

package/dist/library.js

@@ -2,6 +2,7 @@
  * One loaded ClickHouse build. It names itself — `chs_clickhouse_version()` —
  * and nothing is ever inferred from the directory or the file name.
  */
+import { reconstructDdlWith } from './discover.js';
 import { schemaErrorFor } from './errors.js';
 import { Schema } from './schema.js';
 import { encodeSettings } from './settings.js';
@@ -188,6 +189,79 @@ export class Library {
     referenceType(typeExpr) {
         return this.native.referenceType(typeExpr);
     }
+    /**
+     * Spell `name` as a back-quoted identifier — ALWAYS quoted, which is the
+     * safe default and the one to reach for without thinking
+     * (`chs_quote_identifier`, the vendored `backQuote`).
+     *
+     * The bytes are this library's own: an embedded back-quote comes back in the
+     * spelling the server's formatter prints, not in a spelling of ours. Reach
+     * for `quoteIdentifierIfNeeded` only when the bare spelling matters to
+     * something downstream.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the quoted identifier.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    quoteIdentifier(name) {
+        return this.quote('chs_quote_identifier', name);
+    }
+    /**
+     * Spell `name` bare where THIS library's ClickHouse says a bare spelling is
+     * legal, and back-quote it otherwise (`chs_quote_identifier_if_needed`, the
+     * vendored `backQuoteIfNeed`).
+     *
+     * Which names it leaves bare is a property of the vendored build, not of
+     * this package, and it CHANGES between builds — ask the library you will
+     * compile against rather than caching an answer across versions.
+     *
+     * @param name - a table, column or alias name.
+     * @returns the identifier, bare or quoted.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier_if_needed`.
+     */
+    quoteIdentifierIfNeeded(name) {
+        return this.quote('chs_quote_identifier_if_needed', name);
+    }
+    /**
+     * Spell `text` as a ClickHouse string literal, quotes and escapes included
+     * (`chs_quote_literal`, the vendored `quoteString`) — the call to reach for
+     * when a value is spliced into DDL, e.g. a DEFAULT expression.
+     *
+     * The input is counted, so a value carrying a NUL byte is quoted correctly;
+     * the answer is escaped and therefore NUL-free.
+     *
+     * @param text - the string value.
+     * @returns the ClickHouse string literal.
+     * @throws {UnsupportedError} when the artifact predates `chs_quote_literal`.
+     */
+    quoteLiteral(text) {
+        return this.quote('chs_quote_literal', text);
+    }
+    quote(symbol, text) {
+        const r = this.native.quote(symbol, text);
+        if (!r.ok)
+            throw schemaErrorFor(r.code, r.message || `${symbol} refused the input`);
+        return r.quoted;
+    }
+    /**
+     * Turn `QUERY_TABLE_COLUMNS`' rows back into the column-declaration list
+     * `compileDdl` takes.
+     *
+     * It hangs off a Library because the one thing it spells — the column NAME —
+     * is spelled by this library's own `quoteIdentifier`; see `discover.ts` for
+     * what reconstruction does and does not promise.
+     *
+     * @param cols - the discovered columns, e.g. from `parseColumnsResult`.
+     * @returns the column-declaration list for `compileDdl`.
+     * @throws {ChtypesError} when a column is inconsistent, or there are none.
+     * @throws {UnsupportedError} when the artifact predates
+     *   `chs_quote_identifier`.
+     */
+    reconstructDdl(cols) {
+        return reconstructDdlWith(cols, (name) => this.quoteIdentifier(name));
+    }
     /**
      * 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?"

package/dist/library.js.map

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

package/dist/registry.d.ts

@@ -20,11 +20,10 @@
  *
  * Where a registry IS follows the search path of docs/guides/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()`.
+ * reserved system locations. Construction READS THE MANIFESTS on that path and
+ * `dlopen`s nothing; a line is taken, on request, from the first 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';
@@ -52,8 +51,40 @@ export interface RegistryOptions {
      * 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.
+     *
+     * A policy on the REGISTRY, not a property of `preload`: a library's
+     * checksum is computed immediately before that library is `dlopen`ed and at
+     * no other time — at construction for the preloaded lines, at first use for
+     * the rest, never for a line nobody asks for.
+     *
+     * What this option ADDS is the sha256 comparison. The cheaper
+     * `manifest.library_bytes` size check that runs just before it is NOT
+     * conditional on this option — `load()` below always makes it, on every
+     * open, regardless (issue #82). Its timing is the same as the checksum's:
+     * at construction for the preloaded lines, at first use for the rest.
      */
     verifyChecksums?: boolean;
+    /**
+     * Open these lines AT CONSTRUCTION — the one eager path, and the same option
+     * Go spells `WithPreload(...)`, Python `preload=[...]` and Rust
+     * `RegistryOptions::preload`.
+     *
+     * Each entry is a version spelling resolved exactly as `for()` resolves one:
+     * a minor line (`'25.8'`) or an exact patch (`'25.8.28.1-lts'`), never a
+     * path. They are opened in the order given, before the constructor returns,
+     * and an entry no directory on the §1 search path holds is
+     * `ArtifactMissingError` — the same §7 error the first `for()` would have
+     * thrown, thrown earlier.
+     *
+     * It NEVER fetches, even with `autofetch` on: this constructor is
+     * synchronous and `ensure()` is not, and autofetch is a first-use behavior
+     * in all four bindings. An empty list is exactly the default.
+     *
+     * Deliberately a list of lines rather than "everything in the directory": a
+     * registry directory is whatever a fetch left behind, and each open costs
+     * about 120 MB resident.
+     */
+    preload?: readonly string[] | undefined;
     /**
      * Lazy fetch on first open (docs/guides/fetch.md §6): `open()` of a line no
      * directory on the search path holds runs `ensure()` first, into the
@@ -68,13 +99,20 @@ export interface RegistryOptions {
 }
 /**
  * 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`.
+ * package.
+ *
+ * **Construction reads `manifest.json` files and `dlopen`s nothing**, with or
+ * without a directory. Nothing in this package opens an artifact except a
+ * request for a specific version (`for()` / `open()`) or an explicit
+ * `preload` — not `versions()`, not `libraries()`, not `has()`. An open costs
+ * about 120 MB resident per version, which a listing call must not spend on a
+ * caller's behalf.
+ *
+ * An open dlopens the artifact into its own symbol scope (`RTLD_LOCAL`),
+ * 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 that library's one-time `chs_init` with the
+ * registry's 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
@@ -82,9 +120,9 @@ export interface RegistryOptions {
  */
 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.
+     * The primary registry directory: the first on the search path that holds
+     * artifacts — 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. */
@@ -94,47 +132,88 @@ export declare class Registry {
     private readonly byId;
     private readonly byPath;
     private readonly loaded;
+    /**
+     * Minor line -> the FIRST directory on the search path that holds it, as the
+     * construction-time manifest scan found it. What `versions()` answers from,
+     * and what makes "no artifact anywhere" and a bad `preload` entry decidable
+     * at construction without a single `dlopen`.
+     */
+    private readonly known;
     private readonly timezone;
     private readonly verifyChecksums;
     private readonly autofetch;
     private readonly fetchOptions;
     private readonly explicit;
     /**
-     * Scan and load a registry.
+     * Scan a registry. Reads manifests; opens nothing unless `preload` names a
+     * line.
      *
      * @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.
+     * @param options - timezone, checksum verification, autofetch, preload — see
+     *   `RegistryOptions`.
+     * @throws {RegistryError} for what manifests can decide, and only that: a
+     *   directory named explicitly (the argument or `CHTYPES_REGISTRY`) that does
+     *   not exist, and no directory on the search path holding a readable
+     *   `<minor>/manifest.json` — both suppressed when autofetch is on. A
+     *   `preload` entry no directory holds is `ArtifactMissingError`. Everything
+     *   a bad artifact can be wrong about — a failed checksum, a load failure, a
+     *   library whose ClickHouse version disagrees with its manifest — is
+     *   reported by the call that opens it, which is `preload`'s open at
+     *   construction or the first `for()` otherwise.
      * @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).
+     *   timezone — the message names it); again, from the call that opens it.
      */
     constructor(dir?: string, options?: RegistryOptions);
+    /**
+     * Open one `preload` entry, before the constructor returns, without
+     * fetching. Resolution is `for()`'s, and so is the failure: a line no
+     * directory holds is the same `ArtifactMissingError`, raised earlier.
+     */
+    private preloadLine;
     /** 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. */
+    /**
+     * Resolve without fetching: what is already open, then the line's directory
+     * as the construction-time scan recorded it, then a fresh walk of the search
+     * path for a line installed since. `undefined` means no directory holds it,
+     * which is a fetch's cue on `open()` and the §7 error everywhere else —
+     * `preload` never fetches, and this is the one function that makes the
+     * preload path and the first-use path identical in everything else.
+     */
+    private resolve;
+    /**
+     * Every ClickHouse minor line this registry CAN ANSWER FOR, oldest first —
+     * the ones it has opened plus the ones its construction-time manifest scan
+     * discovered on the search path.
+     *
+     * That is one meaning in all four bindings, and it is the meaning that
+     * survives lazy loading: "the lines that happen to be open" would read as an
+     * empty registry until the first `for()`. It opens nothing.
+     */
     versions(): string[];
-    /** Every loaded library, in release order (oldest minor line first). */
+    /**
+     * The libraries this registry has OPENED, in release order (oldest minor
+     * line first) — what is open right now, never what could be. A discovered
+     * line that no `for()` and no `preload` has opened appears in `versions()`
+     * and not here. It opens nothing.
+     */
     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/guides/fetch.md §1), and joins
-     * `versions()` / `libraries()` from then on. Never a fetch: this call is
-     * synchronous; `open()` is the one that may fetch.
+     * **This is what opens an artifact.** Construction does not: the line is
+     * taken from the first directory on the search path that holds it
+     * (docs/guides/fetch.md §1), `dlopen`ed once, and joins `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

package/dist/registry.d.ts.map

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