@wavehouse/chtypes 0.5.2 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +34 -38
  3. package/dist/abi1/buildinfo.d.ts +40 -0
  4. package/dist/abi1/buildinfo.d.ts.map +1 -0
  5. package/dist/abi1/buildinfo.js +83 -0
  6. package/dist/abi1/buildinfo.js.map +1 -0
  7. package/dist/abi1/calls.gen.d.ts +55 -0
  8. package/dist/abi1/calls.gen.d.ts.map +1 -0
  9. package/dist/abi1/calls.gen.js +110 -0
  10. package/dist/abi1/calls.gen.js.map +1 -0
  11. package/dist/abi1/decls.gen.d.ts +115 -0
  12. package/dist/abi1/decls.gen.d.ts.map +1 -0
  13. package/dist/abi1/decls.gen.js +1613 -0
  14. package/dist/abi1/decls.gen.js.map +1 -0
  15. package/dist/abi1/errmap.gen.d.ts +18 -0
  16. package/dist/abi1/errmap.gen.d.ts.map +1 -0
  17. package/dist/abi1/errmap.gen.js +66 -0
  18. package/dist/abi1/errmap.gen.js.map +1 -0
  19. package/dist/abi1/errors.d.ts +107 -0
  20. package/dist/abi1/errors.d.ts.map +1 -0
  21. package/dist/abi1/errors.js +134 -0
  22. package/dist/abi1/errors.js.map +1 -0
  23. package/dist/abi1/handles.d.ts +31 -0
  24. package/dist/abi1/handles.d.ts.map +1 -0
  25. package/dist/abi1/handles.js +76 -0
  26. package/dist/abi1/handles.js.map +1 -0
  27. package/dist/abi1/index.d.ts +17 -0
  28. package/dist/abi1/index.d.ts.map +1 -0
  29. package/dist/abi1/index.js +17 -0
  30. package/dist/abi1/index.js.map +1 -0
  31. package/dist/abi1/libc.d.ts +54 -0
  32. package/dist/abi1/libc.d.ts.map +1 -0
  33. package/dist/abi1/libc.gen.d.ts +12 -0
  34. package/dist/abi1/libc.gen.d.ts.map +1 -0
  35. package/dist/abi1/libc.gen.js +75 -0
  36. package/dist/abi1/libc.gen.js.map +1 -0
  37. package/dist/abi1/libc.js +109 -0
  38. package/dist/abi1/libc.js.map +1 -0
  39. package/dist/abi1/loader.d.ts +101 -0
  40. package/dist/abi1/loader.d.ts.map +1 -0
  41. package/dist/abi1/loader.js +274 -0
  42. package/dist/abi1/loader.js.map +1 -0
  43. package/dist/abi1/raw.d.ts +104 -0
  44. package/dist/abi1/raw.d.ts.map +1 -0
  45. package/dist/abi1/raw.js +296 -0
  46. package/dist/abi1/raw.js.map +1 -0
  47. package/dist/abi1/strictjson.d.ts +19 -0
  48. package/dist/abi1/strictjson.d.ts.map +1 -0
  49. package/dist/abi1/strictjson.js +78 -0
  50. package/dist/abi1/strictjson.js.map +1 -0
  51. package/dist/abi1/vocab.gen.d.ts +169 -0
  52. package/dist/abi1/vocab.gen.d.ts.map +1 -0
  53. package/dist/abi1/vocab.gen.js +306 -0
  54. package/dist/abi1/vocab.gen.js.map +1 -0
  55. package/dist/cli.d.ts +25 -26
  56. package/dist/cli.d.ts.map +1 -1
  57. package/dist/cli.js +206 -218
  58. package/dist/cli.js.map +1 -1
  59. package/dist/documents.d.ts +195 -0
  60. package/dist/documents.d.ts.map +1 -0
  61. package/dist/documents.js +389 -0
  62. package/dist/documents.js.map +1 -0
  63. package/dist/env.d.ts +16 -0
  64. package/dist/env.d.ts.map +1 -0
  65. package/dist/env.js +57 -0
  66. package/dist/env.js.map +1 -0
  67. package/dist/index.d.ts +19 -24
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +17 -23
  70. package/dist/index.js.map +1 -1
  71. package/dist/json.d.ts +11 -89
  72. package/dist/json.d.ts.map +1 -1
  73. package/dist/json.js +16 -180
  74. package/dist/json.js.map +1 -1
  75. package/dist/library.d.ts +53 -309
  76. package/dist/library.d.ts.map +1 -1
  77. package/dist/library.js +77 -315
  78. package/dist/library.js.map +1 -1
  79. package/dist/ocifetch/constants.gen.d.ts +84 -0
  80. package/dist/ocifetch/constants.gen.d.ts.map +1 -0
  81. package/dist/ocifetch/constants.gen.js +92 -0
  82. package/dist/ocifetch/constants.gen.js.map +1 -0
  83. package/dist/ocifetch/dsse.d.ts +114 -0
  84. package/dist/ocifetch/dsse.d.ts.map +1 -0
  85. package/dist/ocifetch/dsse.js +331 -0
  86. package/dist/ocifetch/dsse.js.map +1 -0
  87. package/dist/ocifetch/ensure.d.ts +65 -0
  88. package/dist/ocifetch/ensure.d.ts.map +1 -0
  89. package/dist/ocifetch/ensure.js +775 -0
  90. package/dist/ocifetch/ensure.js.map +1 -0
  91. package/dist/ocifetch/errors.d.ts +92 -0
  92. package/dist/ocifetch/errors.d.ts.map +1 -0
  93. package/dist/ocifetch/errors.js +101 -0
  94. package/dist/ocifetch/errors.js.map +1 -0
  95. package/dist/ocifetch/goldens.d.ts +44 -0
  96. package/dist/ocifetch/goldens.d.ts.map +1 -0
  97. package/dist/ocifetch/goldens.js +62 -0
  98. package/dist/ocifetch/goldens.js.map +1 -0
  99. package/dist/ocifetch/http.d.ts +124 -0
  100. package/dist/ocifetch/http.d.ts.map +1 -0
  101. package/dist/ocifetch/http.js +549 -0
  102. package/dist/ocifetch/http.js.map +1 -0
  103. package/dist/ocifetch/index.d.ts +17 -0
  104. package/dist/ocifetch/index.d.ts.map +1 -0
  105. package/dist/ocifetch/index.js +14 -0
  106. package/dist/ocifetch/index.js.map +1 -0
  107. package/dist/ocifetch/layout.d.ts +126 -0
  108. package/dist/ocifetch/layout.d.ts.map +1 -0
  109. package/dist/ocifetch/layout.js +375 -0
  110. package/dist/ocifetch/layout.js.map +1 -0
  111. package/dist/ocifetch/localverify.d.ts +43 -0
  112. package/dist/ocifetch/localverify.d.ts.map +1 -0
  113. package/dist/ocifetch/localverify.js +164 -0
  114. package/dist/ocifetch/localverify.js.map +1 -0
  115. package/dist/ocifetch/lock.d.ts +39 -0
  116. package/dist/ocifetch/lock.d.ts.map +1 -0
  117. package/dist/ocifetch/lock.js +140 -0
  118. package/dist/ocifetch/lock.js.map +1 -0
  119. package/dist/ocifetch/oci.d.ts +100 -0
  120. package/dist/ocifetch/oci.d.ts.map +1 -0
  121. package/dist/ocifetch/oci.js +323 -0
  122. package/dist/ocifetch/oci.js.map +1 -0
  123. package/dist/ocifetch/referrers.d.ts +55 -0
  124. package/dist/ocifetch/referrers.d.ts.map +1 -0
  125. package/dist/ocifetch/referrers.js +132 -0
  126. package/dist/ocifetch/referrers.js.map +1 -0
  127. package/dist/ocifetch/types.d.ts +167 -0
  128. package/dist/ocifetch/types.d.ts.map +1 -0
  129. package/dist/ocifetch/types.js +88 -0
  130. package/dist/ocifetch/types.js.map +1 -0
  131. package/dist/ocifetch/unpack.d.ts +55 -0
  132. package/dist/ocifetch/unpack.d.ts.map +1 -0
  133. package/dist/ocifetch/unpack.js +205 -0
  134. package/dist/ocifetch/unpack.js.map +1 -0
  135. package/dist/registry.d.ts +38 -387
  136. package/dist/registry.d.ts.map +1 -1
  137. package/dist/registry.js +95 -819
  138. package/dist/registry.js.map +1 -1
  139. package/dist/schema.d.ts +77 -588
  140. package/dist/schema.d.ts.map +1 -1
  141. package/dist/schema.js +87 -549
  142. package/dist/schema.js.map +1 -1
  143. package/dist/settings.d.ts +27 -36
  144. package/dist/settings.d.ts.map +1 -1
  145. package/dist/settings.js +75 -25
  146. package/dist/settings.js.map +1 -1
  147. package/dist/setup.d.ts +46 -0
  148. package/dist/setup.d.ts.map +1 -0
  149. package/dist/setup.js +79 -0
  150. package/dist/setup.js.map +1 -0
  151. package/dist/tar.d.ts +27 -11
  152. package/dist/tar.d.ts.map +1 -1
  153. package/dist/tar.js +54 -32
  154. package/dist/tar.js.map +1 -1
  155. package/package.json +2 -2
  156. package/dist/discover.d.ts +0 -142
  157. package/dist/discover.d.ts.map +0 -1
  158. package/dist/discover.js +0 -288
  159. package/dist/discover.js.map +0 -1
  160. package/dist/error-codes.d.ts +0 -80
  161. package/dist/error-codes.d.ts.map +0 -1
  162. package/dist/error-codes.js +0 -139
  163. package/dist/error-codes.js.map +0 -1
  164. package/dist/errors.d.ts +0 -284
  165. package/dist/errors.d.ts.map +0 -1
  166. package/dist/errors.js +0 -321
  167. package/dist/errors.js.map +0 -1
  168. package/dist/fetch.d.ts +0 -382
  169. package/dist/fetch.d.ts.map +0 -1
  170. package/dist/fetch.js +0 -1498
  171. package/dist/fetch.js.map +0 -1
  172. package/dist/ffi.d.ts +0 -410
  173. package/dist/ffi.d.ts.map +0 -1
  174. package/dist/ffi.js +0 -1154
  175. package/dist/ffi.js.map +0 -1
  176. package/dist/format.d.ts +0 -128
  177. package/dist/format.d.ts.map +0 -1
  178. package/dist/format.js +0 -132
  179. package/dist/format.js.map +0 -1
  180. package/dist/numeric.d.ts +0 -20
  181. package/dist/numeric.d.ts.map +0 -1
  182. package/dist/numeric.js +0 -107
  183. package/dist/numeric.js.map +0 -1
  184. package/dist/paths.d.ts +0 -55
  185. package/dist/paths.d.ts.map +0 -1
  186. package/dist/paths.js +0 -87
  187. package/dist/paths.js.map +0 -1
  188. package/dist/results.d.ts +0 -495
  189. package/dist/results.d.ts.map +0 -1
  190. package/dist/results.js +0 -406
  191. package/dist/results.js.map +0 -1
  192. package/dist/transform.d.ts +0 -73
  193. package/dist/transform.d.ts.map +0 -1
  194. package/dist/transform.js +0 -533
  195. package/dist/transform.js.map +0 -1
@@ -1,395 +1,46 @@
1
1
  /**
2
- * The artifact-directory loader: one subdirectory per ClickHouse minor line,
3
- * each self-contained (docs/reference/artifact.md), plus — since #284 — every
4
- * OTHER installed exact patch of a line, in a sibling `patches/` tree:
5
- *
6
- * <registry>/25.8/{manifest.json, libchtypes.dylib, CH_VERSION, unsafe_families.txt}
7
- * <registry>/patches/25.8/25.8.28.1-lts/{manifest.json, libchtypes.dylib, ...}
8
- *
9
- * The flat `<registry>/<minor>/` slot is what a LINE request resolves to —
10
- * exactly the pre-#284 layout, so every SDK through 0.4.x keeps reading it
11
- * unchanged. Any OTHER exact patch of that line lives in
12
- * `<registry>/patches/<minor>/<clickhouse_version>/`, which no released SDK
13
- * (0.4.x and earlier) scans, fetches into or deletes (measured, issue #284
14
- * comment 5919199794): it is a new, additive tree, not a migration of the old
15
- * one. When a line fetch changes which patch occupies the flat slot, the
16
- * outgoing install is DEMOTED — an atomic, same-filesystem rename into
17
- * `patches/<minor>/<its version>/` — never deleted, so a server still on the
18
- * older patch keeps its exact match with no re-fetch.
19
- *
20
- * Two rules here were paid for and are not negotiable:
21
- *
22
- * - **The shared library's file name comes from `manifest.json`'s `library`
23
- * field.** Not from a hard-coded `libchtypes.so`, not from a glob, not from
24
- * the platform. The current tree proves why: every darwin artifact says
25
- * `libchtypes.dylib` while the *shipping* linux artifacts still say
26
- * `libchtypes_s1.so`, so a loader that constructs the name finds nothing on
27
- * the platform that matters.
28
- * - **Each artifact is loaded into its own symbol scope (`RTLD_LOCAL`).** That
29
- * is the entire mechanism by which two builds that both define
30
- * `DB::DataTypeFactory` live in one process — now routinely two builds of
31
- * the SAME minor line, one per patch. ffi-rs loads through libloading,
32
- * which uses `RTLD_LAZY | RTLD_LOCAL`; `assertLocalSymbolScope()` in the
33
- * test suite proves it from outside rather than trusting the claim.
34
- *
35
- * Where a registry IS follows the search path of docs/guides/fetch.md §1 (`paths.ts`):
36
- * the explicit directory, `CHTYPES_REGISTRY`, the per-user cache, then the
37
- * reserved system locations. Construction READS THE MANIFESTS on that path and
38
- * `dlopen`s nothing; a version is taken, on request, from the first directory
39
- * that has it. Resolution (docs/reference/bindings.md §Version selection):
40
- *
41
- * - **A line request** ("25.8") never falls back and never crosses lines: the
42
- * newest patch of the line, in the first search-path directory that holds
43
- * any patch of it (a nested install beating a flat one on a version tie),
44
- * pinned for this registry for as long as it runs.
45
- * - **A patch request** ("25.8.28.1-lts") loads that exact patch when it is
46
- * open or installed anywhere on the search path. Otherwise it falls back to
47
- * the newest installed patch of the same line, flags the result
48
- * `exact: false`, and warns once per (requested, actual) pair per process —
49
- * never another line, which stays the one §7 error, `ArtifactMissingError`.
50
- *
51
- * A patch spelled with no channel suffix matches that patch on any channel
52
- * (docs/guides/fetch.md Decision 7); ordering is numeric, channel ignored.
2
+ * `Registry`: from a version request to a loaded `Library`
3
+ * (`docs/reference/bindings-v1.md` §6, "The sequence").
4
+ *
5
+ * registry.for(request)
6
+ * 1. the registry's memo: a request opened before returns the same Library,
7
+ * for the registry's life (a line request never moves mid-process: a
8
+ * newer patch installed later is picked up by a new registry)
9
+ * 2. resolved = resolveInstalled(request, host platform, fetch options) never the network
10
+ * 3. on a miss: autofetch on -> resolved = ensure(request, fetch options) may use the network
11
+ * autofetch off -> ArtifactMissingError, naming request and platform
12
+ * 4. input = adapt(resolved): the library path, the predicate VERBATIM (never
13
+ * re-encoded: a re-encoding is a second derivation of the statement the
14
+ * signature covered) and the platform
15
+ * 5. loader steps 1-6, once per image; step 7 under the process setup
16
+ * 6. the image's Library, whose `resolved` is the record that first opened it
17
+ *
18
+ * Construction opens nothing: `Registry.open` is asynchronous only because the
19
+ * fetch layer is, and nothing opens an artifact except a request for a version
20
+ * or `preload`. The binding orders and matches no versions itself: which
21
+ * installed build a floating request means is the fetch layer's.
53
22
  */
54
- import { type EnsureOptions } from './fetch.js';
55
- import { Library } from './library.js';
56
- /** The nine fields `lib/build.sh` writes. Unknown fields are ignored. */
57
- export interface Manifest {
58
- library: string;
59
- library_bytes?: number;
60
- library_sha256?: string;
61
- clickhouse_version?: string;
62
- clickhouse_minor?: string;
63
- clickhouse_commit?: string;
64
- os?: string;
65
- arch?: string;
66
- unsafe_families?: string;
67
- }
68
- /** Options for `new Registry(dir, options)`. */
23
+ import { type Library } from './library.js';
24
+ import { type FetchV1Options, type Resolved } from './ocifetch/index.js';
25
+ /** The fetch layer's options (bases, cache directory, system directories, trusted keys, token, allow-unsigned, offline, frozen, lock path, ...) without its test-only hooks. */
26
+ export type FetchOptions = Omit<FetchV1Options, 'beforeIndexRename' | 'httpLog' | 'clock'>;
69
27
  export interface RegistryOptions {
70
- /**
71
- * The server timezone assumed for bare DateTime / DateTime64 columns. Defaults
72
- * to UTC — what a stock ClickHouse container uses — and is deliberately not
73
- * read from the environment, so the host's TZ cannot leak into results.
74
- */
75
- timezone?: string;
76
- /**
77
- * Re-hash each library and compare against `manifest.library_sha256` before
78
- * loading. SHOULD be on for an artifact that came from anywhere but a local
79
- * build, and MUST be on for one that came over a network.
80
- *
81
- * A policy on the REGISTRY, not a property of `preload`: a library's
82
- * checksum is computed immediately before that library is `dlopen`ed and at
83
- * no other time — at construction for the preloaded lines, at first use for
84
- * the rest, never for a line nobody asks for.
85
- *
86
- * What this option ADDS is the sha256 comparison. The cheaper
87
- * `manifest.library_bytes` size check that runs just before it is NOT
88
- * conditional on this option — `load()` below always makes it, on every
89
- * open, regardless (issue #82). Its timing is the same as the checksum's:
90
- * at construction for the preloaded lines, at first use for the rest.
91
- */
92
- verifyChecksums?: boolean;
93
- /**
94
- * Open these lines AT CONSTRUCTION — the one eager path, and the same option
95
- * Go spells `WithPreload(...)`, Python `preload=[...]` and Rust
96
- * `RegistryOptions::preload`.
97
- *
98
- * Each entry is a version spelling resolved exactly as `for()` resolves one:
99
- * a minor line (`'25.8'`) or an exact patch (`'25.8.28.1-lts'`), never a
100
- * path. They are opened in the order given, before the constructor returns,
101
- * and an entry no directory on the §1 search path holds is
102
- * `ArtifactMissingError` — the same §7 error the first `for()` would have
103
- * thrown, thrown earlier. A patch entry that falls back to its line warns at
104
- * construction, exactly as `for()` would.
105
- *
106
- * It NEVER fetches, even with `autofetch` on: this constructor is
107
- * synchronous and `ensure()` is not, and autofetch is a first-use behavior
108
- * in all four bindings. An empty list is exactly the default.
109
- *
110
- * Deliberately a list of lines rather than "everything in the directory": a
111
- * registry directory is whatever a fetch left behind, and each open costs
112
- * about 120 MB resident.
113
- */
114
- preload?: readonly string[] | undefined;
115
- /**
116
- * Lazy fetch on first open (docs/guides/fetch.md §6): `open()` of a version no
117
- * directory on the search path holds runs `ensure()` first, into the
118
- * directory a fetch writes to (§1), once per process per (destination,
119
- * spelling). Off by default — a production process must not begin a 250 MB
120
- * download inside a request — and `CHTYPES_AUTOFETCH=1` turns it on from the
121
- * environment. `for()` / `resolve()` stay synchronous and never fetch.
122
- */
123
- autofetch?: boolean | undefined;
124
- /** Options handed to `ensure()` by autofetch: source (`url`/`tag`), lock, keys, progress. */
125
- fetch?: EnsureOptions | undefined;
126
- }
127
- /**
128
- * What a `resolve()` / `openResolution()` call hands back: the loaded
129
- * `Library`, the caller's own spelling, what actually loaded, and whether the
130
- * two are the same patch (docs/reference/bindings.md §Version selection).
131
- * `for()` / `open()` run the same resolution and hand back only `.library`.
132
- */
133
- export interface Resolution {
134
- /** The `Library` this resolution loaded (or found already loaded). */
135
- readonly library: Library;
136
- /** The caller's own spelling, trimmed — never normalized further. */
137
- readonly requested: string;
138
- /**
139
- * What actually loaded, i.e. `library.version`. Equal to the requested
140
- * patch when `exact` is true; the newest installed/published patch of the
141
- * requested line otherwise.
142
- */
143
- readonly version: string;
144
- /**
145
- * `true` for a line request — it asked for "a patch of this line" and got
146
- * one. For a patch request, `true` only when the loaded version matches the
147
- * requested patch (a spelled channel matches only itself; an unspelled one
148
- * matches on any channel). `false` means the fallback within the line was
149
- * taken, and a warning was already issued for this (requested, actual) pair
150
- * — once per pair per process.
151
- */
152
- readonly exact: boolean;
28
+ readonly fetch?: FetchOptions | undefined;
29
+ /** Fetch on a miss. Defaults to the `CHTYPES_AUTOFETCH` environment variable, and is off when that is unset. */
30
+ readonly autofetch?: boolean | undefined;
31
+ /** Requests opened at construction, in list order. They never fetch, even with autofetch on. */
32
+ readonly preload?: readonly string[] | undefined;
153
33
  }
154
- /** TEST-ONLY: forget every warned pair, so a suite can assert a fresh warning fires. Not re-exported from index.ts. */
155
- export declare function resetPatchFallbackWarnings(): void;
156
- /**
157
- * The artifact-directory loader — the multi-version entry point of this
158
- * package.
159
- *
160
- * **Construction reads `manifest.json` files and `dlopen`s nothing**, with or
161
- * without a directory. Nothing in this package opens an artifact except a
162
- * request for a specific version (`for()` / `resolve()` / `open()` /
163
- * `openResolution()`) or an explicit `preload` — not `versions()`, not
164
- * `libraries()`, not `has()`. An open costs about 120 MB resident per patch,
165
- * which a listing call must not spend on a caller's behalf, and which grows
166
- * with every DISTINCT patch a process is asked for — libraries are never
167
- * dlclosed (docs/guides/multi-version.md).
168
- *
169
- * An open dlopens the artifact into its own symbol scope (`RTLD_LOCAL`),
170
- * verifies its ABI revision against this binding's `ABI_REVISION` (a different
171
- * nonzero revision is refused; 0 means the artifact predates the probe and
172
- * degrades per symbol), and runs that library's one-time `chs_init` with the
173
- * registry's timezone and the artifact's own `unsafe_families.txt`.
174
- *
175
- * Libraries are never dlclosed; `close()` joins background threads only.
176
- * Loading the same artifact FILE from two `Registry` instances — by one path,
177
- * another spelling, a symlink or a hardlink — shares one loaded image, so
178
- * `chs_init` still runs exactly once per artifact; a second timezone for an
179
- * image already initialized is refused as `InitConflictError`.
180
- */
181
34
  export declare class Registry {
182
- /**
183
- * The primary registry directory: the first on the search path that holds
184
- * artifacts — or, with `autofetch` and nothing installed anywhere, the
185
- * directory the first fetch will create.
186
- */
187
- readonly dir: string;
188
- /** The §1 search path, in order, every candidate whether or not it exists. */
189
- readonly searchPath: readonly string[];
190
- /** This host's platform key, e.g. `darwin-arm64` — the only artifacts a process can dlopen. */
191
- readonly platform: string;
192
- private readonly byPath;
193
- private readonly loaded;
194
- /** Line -> the library currently answering FOR THE LINE. Set once per line; never re-pointed while this registry runs (R3/R8). */
195
- private readonly linePins;
196
- /**
197
- * Line -> every patch the construction-time manifest scan found for it,
198
- * across the whole search path. What `versions()` answers from, and what
199
- * makes "no artifact anywhere" and a bad `preload` entry decidable at
200
- * construction without a single `dlopen`. Resolution itself re-scans the
201
- * live filesystem on every call (a patch installed after construction, by
202
- * this process or another, is used from the next call on).
203
- */
204
- private readonly known;
205
- private readonly timezone;
206
- private readonly verifyChecksums;
207
- private readonly autofetch;
208
- private readonly fetchOptions;
209
- private readonly explicit;
210
- /** (dest, line) already `Ensure()`d successfully by THIS registry's autofetch — never re-read over the network again. */
211
- private readonly ensuredLines;
212
- /** (dest, exact patch) autofetch has already confirmed CHTYPES_ARTIFACT_UNPUBLISHED for — never retried within this registry's lifetime. */
213
- private readonly unpublishedPatches;
214
- /**
215
- * Scan a registry. Reads manifests; opens nothing unless `preload` names a
216
- * version.
217
- *
218
- * @param dir - the registry root; the head of the search path. Absent, the
219
- * path is `CHTYPES_REGISTRY`, the per-user artifact cache, then the system
220
- * locations (see `registrySearchPath` / `defaultRegistryDir`).
221
- * @param options - timezone, checksum verification, autofetch, preload — see
222
- * `RegistryOptions`.
223
- * @throws {RegistryError} for what manifests can decide, and only that: a
224
- * directory named explicitly (the argument or `CHTYPES_REGISTRY`) that does
225
- * not exist, and no directory on the search path holding a readable
226
- * manifest at either slot — both suppressed when autofetch is on. A
227
- * `preload` entry no directory holds is `ArtifactMissingError`. Everything
228
- * a bad artifact can be wrong about — a failed checksum, a load failure, a
229
- * library whose ClickHouse version disagrees with its manifest — is
230
- * reported by the call that opens it, which is `preload`'s open at
231
- * construction or the first `for()` otherwise.
232
- * @throws {ChtypesError} when an artifact reports a different nonzero ABI
233
- * revision than this binding speaks, or `chs_init` fails (e.g. an unknown
234
- * timezone — the message names it); again, from the call that opens it.
235
- */
236
- constructor(dir?: string, options?: RegistryOptions);
237
- /**
238
- * Open one `preload` entry, before the constructor returns, without
239
- * fetching. Resolution is `for()`'s (minus any fetch), and so is the
240
- * failure: a version no directory holds anywhere is the same
241
- * `ArtifactMissingError`, raised earlier. A patch entry that falls back
242
- * warns here, at construction, exactly as `for()` would.
243
- */
244
- private preloadLine;
245
- /** dlopen one artifact directory, cross-check it, `chs_init` it, index it. */
246
- private load;
247
- /** Load an artifact directory whose manifest is already known-readable, or return null when it is not one. */
248
- private loadDir;
249
- /** Every patch (both slots, every search-path root) this registry can currently see for `minor` — a live scan. */
250
- private scanLine;
251
- /** R3: line request — the pin if this registry already has one, else the newest patch in the first root that holds any. */
252
- private resolveLineSync;
253
- /** R4 steps 1-2: an exact match, already open or anywhere on the search path — never a fallback. */
254
- private resolveExactPatchSync;
255
- /**
256
- * R4 in full, synchronous shape: exact, else the newest-installed fallback
257
- * within the line. R-c: the already-open check is free (no I/O) and always
258
- * current; everything past it needs a directory read per search-path entry,
259
- * so once a request has fallen back, the WHOLE re-check — retrying the exact
260
- * match and picking the fallback alike — is throttled together, at most
261
- * once per `FALLBACK_RECHECK_MS` per requested patch per process.
262
- *
263
- * §3: the warning fires as soon as the fallback patch is CHOSEN — its
264
- * version is already known from the manifest scan, before `loadDir` ever
265
- * runs — so a caller sees the warning even when the chosen directory then
266
- * fails to load (a broken artifact is still a fallback that was taken).
267
- */
268
- private resolvePatchSync;
269
- private resolveSync;
270
- /** Would `req` resolve without opening anything? Mirrors `resolveSync` with no `load()` call. */
271
- private wouldResolve;
272
- private warnFallback;
273
- /**
274
- * Every ClickHouse minor line this registry CAN ANSWER FOR, oldest first —
275
- * the ones it has opened plus the ones its construction-time manifest scan
276
- * discovered on the search path, at either slot.
277
- *
278
- * That is one meaning in all four bindings, and it is the meaning that
279
- * survives lazy loading: "the lines that happen to be open" would read as an
280
- * empty registry until the first `for()`. It opens nothing.
281
- */
282
- versions(): string[];
283
- /**
284
- * The libraries this registry has OPENED, in full numeric version order —
285
- * what is open right now, never what could be. Two patches of one line both
286
- * appear, each in its own slot in this order. A discovered patch that no
287
- * `for()` and no `preload` has opened appears in `versions()` and not here.
288
- * It opens nothing.
289
- */
35
+ #private;
36
+ private constructor();
37
+ /** Construct a registry. It opens nothing, except each `preload` request, in list order. */
38
+ static open(options?: RegistryOptions): Promise<Registry>;
39
+ /** Open a version: the installed build the request names, fetched first when autofetch is on and none is installed. */
40
+ for(request: string): Promise<Library>;
41
+ /** What is installed: the fetch layer's own listing. */
42
+ installed(): Promise<readonly Resolved[]>;
43
+ /** The libraries this registry has opened, in order of first open. */
290
44
  libraries(): readonly Library[];
291
- /**
292
- * Resolve a version to its library. A minor line ("25.8") never falls back:
293
- * the newest patch of the line, from the first search-path directory that
294
- * holds any patch of it. An exact patch ("25.8.28.1-lts") loads that patch
295
- * when it is open or installed anywhere on the search path; otherwise the
296
- * newest installed patch of the same line is loaded instead, and one
297
- * warning is written per (requested, actual) pair per process — `resolve()`
298
- * reports the same fallback as `exact: false` instead of only warning.
299
- *
300
- * **This is what opens an artifact.** Construction does not: a version is
301
- * loaded on first request, `dlopen`ed once, and joins `libraries()` from
302
- * then on. Never a fetch: this call is synchronous; `open()` /
303
- * `openResolution()` are the ones that may fetch.
304
- *
305
- * Failure is the one §7 error, never a fallback to another line: answering
306
- * 26.7 semantics from a 25.8 artifact is a lie, and silent wrongness is what
307
- * the rigs score hardest.
308
- *
309
- * @param version - a minor line (`"25.8"`) or an exact patch
310
- * (`"25.8.28.1-lts"`), e.g. what `parseVersionResult` discovered.
311
- * @returns the loaded `Library` for that version.
312
- * @throws {ArtifactMissingError} (`code` `CHTYPES_ARTIFACT_MISSING`, a
313
- * `RegistryError`) when no directory on the search path holds a matching
314
- * or fallback patch; the message names every directory looked in and the
315
- * fetch command.
316
- * @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
317
- * @throws {RegistryError} when a directory holds a version but it does not load.
318
- */
319
- for(version: string): Library;
320
- /**
321
- * `for()`, but returns the full `Resolution` — the requested spelling, what
322
- * actually loaded, and whether the two are the same patch. Never fetches;
323
- * `openResolution()` is the async twin that may.
324
- *
325
- * @throws {ArtifactMissingError} as `for()`.
326
- * @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
327
- */
328
- resolve(version: string): Resolution;
329
- /**
330
- * `for()`, with the lazy fetch of docs/guides/fetch.md §6 in front of it. A
331
- * LINE request no directory holds is fetched through `ensure()` and loaded.
332
- * A PATCH request tries `ensure()` of that exact patch first; on
333
- * `CHTYPES_ARTIFACT_UNPUBLISHED` (remembered for this registry, so it costs
334
- * one network round trip, not one per call) it falls back to `ensure()` of
335
- * the line and loads whatever that installs, with `exact: false` and one
336
- * warning. Any other fetch failure (untrusted, corrupt, pinned, source
337
- * unreachable) surfaces as itself and is never remembered, so a later call
338
- * retries. With `autofetch` off, this is `for()` behind a promise.
339
- *
340
- * @throws {ArtifactMissingError} when nothing is found and autofetch is off.
341
- * @throws {FetchError} the §7 fetch verdicts (`CHTYPES_ARTIFACT_UNTRUSTED`,
342
- * `…_CORRUPT`, `…_PINNED`, `…_UNPUBLISHED`, `CHTYPES_SOURCE_UNREACHABLE`).
343
- * @throws {RegistryError} when the fetched artifact does not load.
344
- */
345
- open(version: string): Promise<Library>;
346
- /** `open()`, but returns the full `Resolution` — see `resolve()` and `open()`. */
347
- openResolution(version: string): Promise<Resolution>;
348
- /** `ensure(line)`, at most once per (dest, line) over this registry's lifetime — never re-read over the network again. */
349
- private ensureLineOnce;
350
- /**
351
- * True when this registry can answer for a version without fetching or
352
- * loading: already open, or held by a directory on the search path (at
353
- * either slot) which `for()` would load. A patch resolves true when the
354
- * patch itself, or any patch of its line, is installed or open — the same
355
- * condition `for()` would resolve, fallback included. Never a fetch, and
356
- * never a load.
357
- */
358
- has(version: string): boolean;
359
- /**
360
- * Join every loaded library's background threads. `chs_init` registers
361
- * `chs_shutdown` with `atexit`, so an ordinary process needs no call; a test
362
- * that must not depend on `atexit` should make one.
363
- */
364
- close(): void;
365
- /** `using registry = new Registry(...)` closes it at scope exit. */
366
- [Symbol.dispose](): void;
367
45
  }
368
- /** Numeric ordering: 25.10 is a later minor than 25.8, whatever strings say. */
369
- export declare function compareMinor(a: string, b: string): number;
370
- /**
371
- * Where the registry is: the explicit argument, else `CHTYPES_REGISTRY`, else
372
- * the first of the per-user artifact cache and the system locations that
373
- * holds artifacts (docs/guides/fetch.md §1). An explicit path and the environment
374
- * variable are returned as given — a wrong one must produce an error naming
375
- * it, not a silent fallback — while the unnamed candidates only count if they
376
- * actually hold artifacts.
377
- */
378
- export declare function resolveRegistryDir(explicit?: string): string | null;
379
- /**
380
- * The per-user artifact cache for this host —
381
- * `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/abi<R>/<os>-<arch>`, R this
382
- * binding's `ABI_REVISION` and `<arch>` spelled the artifact way (`amd64`,
383
- * `arm64`). Where `chtypes fetch` and `scripts/fetch.sh` install, and what
384
- * every SDK's tests and playgrounds fall back to when `CHTYPES_REGISTRY` is
385
- * unset — one directory the four SDKs at the same revision agree on. A path,
386
- * not a promise: `Registry` still throws if nothing is there.
387
- */
388
- export declare function defaultRegistryDir(): string;
389
- /**
390
- * Does this directory hold at least one artifact with a usable manifest, at
391
- * either slot — the flat `<dir>/<minor>/` layout or the `<dir>/patches/<minor>/<version>/`
392
- * sibling tree? A registry that holds only nested installs is not empty.
393
- */
394
- export declare function looksLikeRegistry(dir: string): boolean;
395
46
  //# sourceMappingURL=registry.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAGL,KAAK,cAAc,EAInB,KAAK,QAAQ,EAEd,MAAM,qBAAqB,CAAC;AAK7B,gLAAgL;AAChL,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC1C,gHAAgH;IAChH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAClD;AAiBD,qBAAa,QAAQ;;IAMnB,OAAO,eAGN;IAED,4FAA4F;IAC5F,OAAa,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOlE;IAED,uHAAuH;IACjH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAED,wDAAwD;IAClD,SAAS,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAE9C;IAED,sEAAsE;IACtE,SAAS,IAAI,SAAS,OAAO,EAAE,CAE9B;CA6CF"}