@wavehouse/chtypes 0.1.0
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.
- package/CHANGELOG.md +24 -0
- package/LICENSE +202 -0
- package/README.md +442 -0
- package/dist/cli.d.ts +43 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +303 -0
- package/dist/cli.js.map +1 -0
- package/dist/discover.d.ts +134 -0
- package/dist/discover.d.ts.map +1 -0
- package/dist/discover.js +291 -0
- package/dist/discover.js.map +1 -0
- package/dist/errors.d.ts +204 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +228 -0
- package/dist/errors.js.map +1 -0
- package/dist/fetch.d.ts +235 -0
- package/dist/fetch.d.ts.map +1 -0
- package/dist/fetch.js +842 -0
- package/dist/fetch.js.map +1 -0
- package/dist/ffi.d.ts +346 -0
- package/dist/ffi.d.ts.map +1 -0
- package/dist/ffi.js +913 -0
- package/dist/ffi.js.map +1 -0
- package/dist/format.d.ts +104 -0
- package/dist/format.d.ts.map +1 -0
- package/dist/format.js +108 -0
- package/dist/format.js.map +1 -0
- package/dist/index.d.ts +28 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +28 -0
- package/dist/index.js.map +1 -0
- package/dist/json.d.ts +127 -0
- package/dist/json.d.ts.map +1 -0
- package/dist/json.js +577 -0
- package/dist/json.js.map +1 -0
- package/dist/library.d.ts +225 -0
- package/dist/library.d.ts.map +1 -0
- package/dist/library.js +234 -0
- package/dist/library.js.map +1 -0
- package/dist/numeric.d.ts +20 -0
- package/dist/numeric.d.ts.map +1 -0
- package/dist/numeric.js +107 -0
- package/dist/numeric.js.map +1 -0
- package/dist/paths.d.ts +47 -0
- package/dist/paths.d.ts.map +1 -0
- package/dist/paths.js +78 -0
- package/dist/paths.js.map +1 -0
- package/dist/registry.d.ts +204 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +409 -0
- package/dist/registry.js.map +1 -0
- package/dist/results.d.ts +326 -0
- package/dist/results.d.ts.map +1 -0
- package/dist/results.js +235 -0
- package/dist/results.js.map +1 -0
- package/dist/schema.d.ts +444 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +448 -0
- package/dist/schema.js.map +1 -0
- package/dist/settings.d.ts +43 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/settings.js +33 -0
- package/dist/settings.js.map +1 -0
- package/dist/tar.d.ts +32 -0
- package/dist/tar.d.ts.map +1 -0
- package/dist/tar.js +310 -0
- package/dist/tar.js.map +1 -0
- package/dist/transform.d.ts +73 -0
- package/dist/transform.d.ts.map +1 -0
- package/dist/transform.js +527 -0
- package/dist/transform.js.map +1 -0
- package/package.json +62 -0
package/dist/schema.d.ts
ADDED
|
@@ -0,0 +1,444 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A compiled schema — one tenant table's column list, compiled inside one
|
|
3
|
+
* version's library, plus the engine and TTL declarations that make `rows()`
|
|
4
|
+
* answer with the storage layer's verdict as well as the type layer's.
|
|
5
|
+
*/
|
|
6
|
+
import type { BlockHandle, FilterHandle, NativeLibrary, SchemaHandle } from './ffi.js';
|
|
7
|
+
import { type Format } from './format.js';
|
|
8
|
+
import { type BatchResult, type FilterResult, type RowResult } from './results.js';
|
|
9
|
+
import { type Settings } from './settings.js';
|
|
10
|
+
/** One declared column, as ClickHouse canonicalised it. */
|
|
11
|
+
export interface ColumnInfo {
|
|
12
|
+
readonly name: string;
|
|
13
|
+
/** Canonical type — pass it through verbatim, never re-normalise whitespace. */
|
|
14
|
+
readonly type: string;
|
|
15
|
+
/** "" | "DEFAULT" | "MATERIALIZED" | "ALIAS" | "EPHEMERAL" */
|
|
16
|
+
readonly defaultKind: string;
|
|
17
|
+
readonly defaultExpr: string;
|
|
18
|
+
/** True when the DEFAULT is a literal applicable without the interpreter. */
|
|
19
|
+
readonly defaultIsLiteral: boolean;
|
|
20
|
+
}
|
|
21
|
+
/** Options for `Schema#setEngine` — the table's MergeTree-namespace settings. */
|
|
22
|
+
export interface EngineOptions {
|
|
23
|
+
/**
|
|
24
|
+
* The `SETTINGS` clause after the engine — `allow_nullable_key` and friends,
|
|
25
|
+
* a namespace `DB::Settings` cannot carry (spec/c-abi.md §`chs_schema_engine`).
|
|
26
|
+
* Absent or empty is structurally identical to the plain engine declaration:
|
|
27
|
+
* `chs_schema_engine` takes "{}" either way. Names are validated by the
|
|
28
|
+
* server's own `MergeTreeSettings` object: an unknown name throws the
|
|
29
|
+
* server's own 115; a known name declared at a NON-default value is refused
|
|
30
|
+
* (`unsupported`, naming it) — no MergeTree setting's behaviour is modelled
|
|
31
|
+
* yet, and silently ignoring a declared value would mean the declared
|
|
32
|
+
* profile is not in force; a name declared AT its default is inert and
|
|
33
|
+
* accepted.
|
|
34
|
+
*/
|
|
35
|
+
readonly mergeTreeSettings?: Settings | undefined;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Options for `Schema#rows` — the revision-3 export and document-flag
|
|
39
|
+
* channels (spec/c-abi.md §Rows; docs/proposals/rows-export.md). Whatever the
|
|
40
|
+
* options, `rows()` is always ONE `chs_rows` call — never a second call,
|
|
41
|
+
* never re-parsing.
|
|
42
|
+
*/
|
|
43
|
+
export interface RowsOptions {
|
|
44
|
+
/**
|
|
45
|
+
* A `Format` the artifact can SERIALIZE — this revision exactly
|
|
46
|
+
* `Format.JSONCompactEachRow`. Any other value answers the whole call
|
|
47
|
+
* `outcome: 'unsupported'` and processes nothing — loud, never silent.
|
|
48
|
+
* Absent = no export: today's path, byte-identical to revision 2.
|
|
49
|
+
*/
|
|
50
|
+
readonly exportFormat?: Format | undefined;
|
|
51
|
+
/**
|
|
52
|
+
* A bitmask of `DOC_VALUES | DOC_TRANSFORMS | DOC_DEFAULTS` selecting the
|
|
53
|
+
* document groups; the verdict channel is always present and not a flag.
|
|
54
|
+
* Defaults: `DOC_ALL` when no `exportFormat` is given (the full document —
|
|
55
|
+
* plain `rows()` behaviour), `0` (LEAN — verdicts only: `values`,
|
|
56
|
+
* `transformed`, `substituted`, `computed` and `unknownFields` all come
|
|
57
|
+
* back empty) when one is. An explicit value always wins; a bit outside
|
|
58
|
+
* `DOC_ALL` is refused loudly by the library, never pre-validated here.
|
|
59
|
+
*/
|
|
60
|
+
readonly docFlags?: number | undefined;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Options for `Schema#compileFilter` — the revision-4 query-parameter
|
|
64
|
+
* bindings.
|
|
65
|
+
*/
|
|
66
|
+
export interface CompileFilterOptions {
|
|
67
|
+
/**
|
|
68
|
+
* `{name:Type}` query-parameter bindings: name → value STRING, exactly as
|
|
69
|
+
* the server's own parameter channels carry them. Each value is
|
|
70
|
+
* deserialized by the DECLARED type's own reader and injected as a typed
|
|
71
|
+
* literal AFTER SQL parsing, so a value is never SQL text and NEVER needs
|
|
72
|
+
* hand-escaping — injection safety is by construction, not by escaping
|
|
73
|
+
* (spec/c-abi.md §Filters, Query parameters). Do not render values into
|
|
74
|
+
* the expression yourself.
|
|
75
|
+
*
|
|
76
|
+
* CHOOSE THE BRACE TYPE FOR THE VALUE'S DOMAIN: the declared type's own
|
|
77
|
+
* reader WRAPS an out-of-domain integer — `{p:UInt8}` given `"256"` binds
|
|
78
|
+
* `0` and matches every genuine zero (measured, uniform 24.8–26.7) —
|
|
79
|
+
* while the same constant as a literal PROMOTES (`x = 256` is never
|
|
80
|
+
* true). Size the brace type for the tenant-supplied domain or validate
|
|
81
|
+
* the value first; malformed spellings refuse loudly (457 for
|
|
82
|
+
* `"-1"`/`"+7"`/`"007"` as UInt8, 32 for `""`). A name bound twice at the
|
|
83
|
+
* C boundary takes the LAST binding — the server's own `insert_or_assign`
|
|
84
|
+
* rule (unreachable through this unique-keyed object, stated for
|
|
85
|
+
* completeness).
|
|
86
|
+
*
|
|
87
|
+
* The compiled handle bakes the values in: identity is per
|
|
88
|
+
* (schema, expr, params), so changing a value means compiling a new
|
|
89
|
+
* `Filter`. A caller compiling filters from tenant-influenced values MUST
|
|
90
|
+
* bound its cache (an LRU keyed on schema generation + expr + params-hash)
|
|
91
|
+
* and its compile rate per principal — the key is attacker-influencable,
|
|
92
|
+
* so an unbounded cache is a memory DoS and an unmetered compile path is a
|
|
93
|
+
* CPU DoS.
|
|
94
|
+
*/
|
|
95
|
+
readonly params?: Settings | undefined;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* A compiled schema — one tenant table's column list, compiled inside one
|
|
99
|
+
* version's library. Obtained from `Library#compileDdl`; never constructed
|
|
100
|
+
* directly. Release with `close()` (idempotent) or `using` / `Symbol.dispose`.
|
|
101
|
+
*
|
|
102
|
+
* Thread-safety: the C ABI forbids using one `chs_schema *` from two threads
|
|
103
|
+
* at once; on a single JS thread every call here is synchronous, so ordinary
|
|
104
|
+
* Node code satisfies that by construction. Do not share a `Schema` across
|
|
105
|
+
* `worker_threads`.
|
|
106
|
+
*/
|
|
107
|
+
export declare class Schema {
|
|
108
|
+
private readonly native;
|
|
109
|
+
/** The column-declaration list this schema was compiled from, verbatim. */
|
|
110
|
+
readonly ddl: string;
|
|
111
|
+
/**
|
|
112
|
+
* The declared columns as ClickHouse canonicalised them, in declaration
|
|
113
|
+
* order — flattened under `flatten_nested=1`, DEFAULT-rewritten types
|
|
114
|
+
* (`x Int64 DEFAULT NULL` compiles as `Nullable(Int64)`), ALIAS types
|
|
115
|
+
* inferred. A gateway detects EPHEMERAL columns here, at compile time
|
|
116
|
+
* (`defaultKind === 'EPHEMERAL'`), not per row.
|
|
117
|
+
*/
|
|
118
|
+
readonly columns: readonly ColumnInfo[];
|
|
119
|
+
private handle;
|
|
120
|
+
/**
|
|
121
|
+
* Every open `Filter` compiled from this handle, so `close()` can free them
|
|
122
|
+
* FIRST — the C layer does not refcount, and freeing the schema under a
|
|
123
|
+
* live filter is use-after-free (spec/c-abi.md §Filters, handle lifetime).
|
|
124
|
+
*/
|
|
125
|
+
private readonly filters;
|
|
126
|
+
/**
|
|
127
|
+
* Every open `Block` parsed from this handle — the same non-owning rule,
|
|
128
|
+
* the same free-before-schema order (spec/c-abi.md §Blocks).
|
|
129
|
+
*/
|
|
130
|
+
private readonly blocks;
|
|
131
|
+
/** @internal — obtained from `Library#compileDdl`. */
|
|
132
|
+
constructor(native: NativeLibrary, handle: SchemaHandle,
|
|
133
|
+
/** The column-declaration list this schema was compiled from, verbatim. */
|
|
134
|
+
ddl: string);
|
|
135
|
+
private live;
|
|
136
|
+
/**
|
|
137
|
+
* Declare the table engine, so `rows()` applies the engine's own insert-time
|
|
138
|
+
* merge (`optimize_on_insert = 1`): a CollapsingMergeTree refusing an invalid
|
|
139
|
+
* Sign with code 117 before anything is stored, a SummingMergeTree summing
|
|
140
|
+
* equal keys and dropping all-zero rows, a ReplacingMergeTree deduplicating.
|
|
141
|
+
*
|
|
142
|
+
* `options.mergeTreeSettings` declares the table's MergeTree-namespace
|
|
143
|
+
* settings — see `EngineOptions` for the error contract (unknown name ⇒ the
|
|
144
|
+
* server's 115; non-default declared value ⇒ `unsupported`, never silently
|
|
145
|
+
* ignored). Absent/empty is structurally the plain engine declaration:
|
|
146
|
+
* `chs_schema_engine` takes "{}" either way.
|
|
147
|
+
*
|
|
148
|
+
* The two error classes here are the refusal/decline split and MUST be
|
|
149
|
+
* handled as peers — `UnsupportedError` is deliberately NOT
|
|
150
|
+
* `instanceof SchemaError` (spec/bindings.md rule 12):
|
|
151
|
+
*
|
|
152
|
+
* @param engine - the engine expression, e.g. `"SummingMergeTree"`,
|
|
153
|
+
* `"CollapsingMergeTree(sign)"`.
|
|
154
|
+
* @param orderBy - the sorting key, e.g. `"(day, key)"`.
|
|
155
|
+
* @param options - the MergeTree-namespace `SETTINGS` clause, if any.
|
|
156
|
+
* @throws {SchemaError} when the SERVER refused (positive code): this DDL
|
|
157
|
+
* can never exist and the tenant has to be told. Today that is 115, an
|
|
158
|
+
* unknown MergeTree setting name, with the server's own message verbatim.
|
|
159
|
+
* @throws {UnsupportedError} when this LIBRARY declined: an engine or
|
|
160
|
+
* sorting key this build does not model, a known MergeTree setting
|
|
161
|
+
* declared at a non-default value, or a guarded exception. A real server
|
|
162
|
+
* might well have accepted it — validate cautiously, fall back to the
|
|
163
|
+
* server, and never present the decline as a rejection.
|
|
164
|
+
*/
|
|
165
|
+
setEngine(engine: string, orderBy: string, options?: EngineOptions): void;
|
|
166
|
+
/**
|
|
167
|
+
* Declare the table's rows TTL (`ts + INTERVAL 30 DAY`). An expired row is
|
|
168
|
+
* reported NOT STORED through the batch's `transformed` list.
|
|
169
|
+
*
|
|
170
|
+
* Column-level TTLs need no call: they are part of the declaration list.
|
|
171
|
+
*
|
|
172
|
+
* @param ttl - the rows-TTL expression, e.g. `"ts + INTERVAL 30 DAY"`. It is
|
|
173
|
+
* validated under the handle's declared compile profile when one exists.
|
|
174
|
+
* @throws {UnsupportedError} for a TTL form this build refuses rather than
|
|
175
|
+
* guesses: WHERE / GROUP BY TTLs, TO DISK/VOLUME moves, RECOMPRESS, any
|
|
176
|
+
* clock-reading TTL expression, and guarded exceptions. Fall back to the
|
|
177
|
+
* server; do not report a tenant error.
|
|
178
|
+
*/
|
|
179
|
+
setTtl(ttl: string): void;
|
|
180
|
+
/**
|
|
181
|
+
* Validate and coerce ONE row body, answering exactly as this ClickHouse
|
|
182
|
+
* version's insert path would.
|
|
183
|
+
*
|
|
184
|
+
* There is no exception for a bad row: rejection, poisoning and declines all
|
|
185
|
+
* arrive as the `RowResult`'s `outcome` (see `Outcome` for the taxonomy and
|
|
186
|
+
* the caller's obligations per arm).
|
|
187
|
+
*
|
|
188
|
+
* @param format - the wire format code (`Format`). Binary-format support
|
|
189
|
+
* depends on the loaded artifact — probe, don't assume.
|
|
190
|
+
* @param raw - the row's bytes, exactly as they would arrive in an INSERT
|
|
191
|
+
* body. Always bytes, never a JS string: binary formats contain NUL bytes
|
|
192
|
+
* and text rows can carry invalid UTF-8 on purpose.
|
|
193
|
+
* @param settings - per-call settings; they win over the compile profile and
|
|
194
|
+
* the library defaults (except a type gate the profile declared, which the
|
|
195
|
+
* handle has already settled, as a real server's CREATE does).
|
|
196
|
+
* @returns the `RowResult` — verdict, stored values, and every silent change.
|
|
197
|
+
* @throws {ChtypesError} when the schema is closed, or a settings value is a
|
|
198
|
+
* JS `number`.
|
|
199
|
+
* @throws {UnsupportedError} when the artifact predates `chs_row`.
|
|
200
|
+
*/
|
|
201
|
+
row(format: Format, raw: Uint8Array, settings?: Settings): RowResult;
|
|
202
|
+
/**
|
|
203
|
+
* Validate and coerce a whole request body, which may hold many rows.
|
|
204
|
+
*
|
|
205
|
+
* This is not `row()` in a loop and must never be implemented as one: row
|
|
206
|
+
* separation is format-specific (a quoted CSV field can contain a newline),
|
|
207
|
+
* `input_format_allow_errors_num` / `_ratio` decide whether a bad row is
|
|
208
|
+
* skipped or aborts the batch, and one batch is one clock instant for the
|
|
209
|
+
* volatile-DEFAULT guarantee.
|
|
210
|
+
*
|
|
211
|
+
* @param format - the wire format code (`Format`).
|
|
212
|
+
* @param body - the whole request body as bytes (never a JS string).
|
|
213
|
+
* @param settings - per-call settings; same precedence as `row`.
|
|
214
|
+
* @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
|
|
215
|
+
* is the stored truth, and batch-level storage transforms (`ttl_expired`,
|
|
216
|
+
* `ttl_column_expired`) are folded into `transformed`.
|
|
217
|
+
* With `options.exportFormat` the same ONE call also serializes the batch's
|
|
218
|
+
* accepted rows through the vendored writer: `payload` carries the bytes
|
|
219
|
+
* (zero-length = emitted-empty, an accepted batch with zero accepted rows;
|
|
220
|
+
* `undefined` + `exportDeclined` = withheld, with the reason), and `spans`
|
|
221
|
+
* is index-aligned with `rows` — `payload.subarray(s.off, s.off + s.len)`
|
|
222
|
+
* IS row i's line. With `options.docFlags` the per-row documents are
|
|
223
|
+
* thinned to the selected groups; the verdict channel is never thinned.
|
|
224
|
+
* See `RowsOptions` for the defaults and `BatchResult` for the three
|
|
225
|
+
* payload states.
|
|
226
|
+
*
|
|
227
|
+
* @param format - the wire format code (`Format`).
|
|
228
|
+
* @param body - the whole request body as bytes (never a JS string).
|
|
229
|
+
* @param settings - per-call settings; same precedence as `row`.
|
|
230
|
+
* @param options - the revision-3 export/doc-flag channels; absent =
|
|
231
|
+
* today's full document, byte-identical to revision 2.
|
|
232
|
+
* @returns the `BatchResult`. When `engineRows` is present it — not `rows` —
|
|
233
|
+
* is the stored truth, and batch-level storage transforms (`ttl_expired`,
|
|
234
|
+
* `ttl_column_expired`) are folded into `transformed`.
|
|
235
|
+
* @throws {ChtypesError} when the schema is closed, a settings value is a JS
|
|
236
|
+
* `number`, or the artifact predates `chs_rows` (a mandatory symbol).
|
|
237
|
+
*/
|
|
238
|
+
rows(format: Format, body: Uint8Array, settings?: Settings, options?: RowsOptions): BatchResult;
|
|
239
|
+
/**
|
|
240
|
+
* Compile one boolean SQL expression over this schema's PHYSICAL columns
|
|
241
|
+
* (ordinary + MATERIALIZED; naming an ALIAS/EPHEMERAL column fails with
|
|
242
|
+
* ClickHouse's own UNKNOWN_IDENTIFIER, exactly where a real CREATE fails) —
|
|
243
|
+
* the same TreeRewriter + ExpressionAnalyzer pipeline the CONSTRAINT CHECK
|
|
244
|
+
* path runs, so comparison semantics are WHERE-side by construction:
|
|
245
|
+
* `x = 256` over UInt8 promotes (false for every row), it never wraps
|
|
246
|
+
* (spec/c-abi.md §Filters).
|
|
247
|
+
*
|
|
248
|
+
* The expression may contain `{name:Type}` query parameters, bound with
|
|
249
|
+
* `options.params` (revision 4) — substitution is the server's own
|
|
250
|
+
* `ReplaceQueryParameterVisitor`, run before analysis, exactly where a
|
|
251
|
+
* real server runs it; see `CompileFilterOptions` for the injection-safety
|
|
252
|
+
* and cache-discipline contract. Close the filter when done (`close()` /
|
|
253
|
+
* `Symbol.dispose`); `schema.close()` also closes every open filter FIRST,
|
|
254
|
+
* so no caller ordering can free the schema under a live filter.
|
|
255
|
+
*
|
|
256
|
+
* ENFORCEMENT GATE: nothing may enforce read-side security on this surface
|
|
257
|
+
* until the WHERE-truth rig gates green (zero over-admit, zero over-hide);
|
|
258
|
+
* until then it is a shadow/replay surface.
|
|
259
|
+
*
|
|
260
|
+
* @param expr - one boolean expression, e.g. `"x = 256"` or
|
|
261
|
+
* `"tenant = {t:String}"`.
|
|
262
|
+
* @param options - the `{name:Type}` bindings, if any.
|
|
263
|
+
* @returns the compiled `Filter`.
|
|
264
|
+
* @throws {SchemaError} when ClickHouse itself refuses the expression —
|
|
265
|
+
* unknown identifier (47), unknown function, an analyzer-raised
|
|
266
|
+
* NO_COMMON_TYPE — and, since revision 4, the server's own parameter
|
|
267
|
+
* refusals: an UNBOUND `{name:Type}` is **456** UNKNOWN_QUERY_PARAMETER
|
|
268
|
+
* ("Substitution `name` is not set"), a value the declared type cannot
|
|
269
|
+
* parse completely is **457** BAD_QUERY_PARAMETER — the server's own
|
|
270
|
+
* code and message, verbatim. A bound name the expression never uses is
|
|
271
|
+
* ignored, as a live server ignores an unused `param_*`.
|
|
272
|
+
* @throws {UnsupportedError} when this build declines: a non-deterministic
|
|
273
|
+
* expression (clock reads — `now() > ts` —, `rand()`, server-constants;
|
|
274
|
+
* the scan runs AFTER substitution, so a value can never smuggle one
|
|
275
|
+
* in), or an artifact that predates the filter trio.
|
|
276
|
+
*/
|
|
277
|
+
compileFilter(expr: string, options?: CompileFilterOptions): Filter;
|
|
278
|
+
/** @internal — `Filter#close` deregisters itself here. */
|
|
279
|
+
forgetFilter(filter: Filter): void;
|
|
280
|
+
/**
|
|
281
|
+
* Parse a body ONCE into a `Block` (`chs_block_parse`) — the parse half of
|
|
282
|
+
* `Filter#rows`, exported so K filters can evaluate one event with no
|
|
283
|
+
* re-parse (`Filter#eval`; spec/c-abi.md §Blocks). Same formats and
|
|
284
|
+
* settings contract as `rows` (`settings` is the PARSE-side map: format
|
|
285
|
+
* settings, clock keys; evaluation takes none). Volatile DEFAULTs resolve
|
|
286
|
+
* against THIS call's clock instant, so
|
|
287
|
+
* `filter.eval(schema.parseBlock(...))` ≡ `filter.rows(...)` exactly when
|
|
288
|
+
* the clock is pinned (`chtypes_now_epoch_nanos`) or the schema has no
|
|
289
|
+
* volatile DEFAULT.
|
|
290
|
+
*
|
|
291
|
+
* Per-row parse failures do NOT throw — they are recorded IN the block and
|
|
292
|
+
* answer `'decline'` from every filter, with the recorded error. Release
|
|
293
|
+
* with `close()` / `Symbol.dispose`; `schema.close()` closes open blocks
|
|
294
|
+
* FIRST, the C-required order.
|
|
295
|
+
*
|
|
296
|
+
* @param format - the wire format code (`Format`).
|
|
297
|
+
* @param body - the rows as bytes (never a JS string).
|
|
298
|
+
* @param settings - parse-side settings; same precedence as `Schema#rows`.
|
|
299
|
+
* @returns the parsed `Block`.
|
|
300
|
+
* @throws {SchemaError} on a call-level failure — an unknown setting's
|
|
301
|
+
* 115, an unsplittable body, a binary decode fault, the deferred
|
|
302
|
+
* JSONEachRow framing verdict: a malformed body yields no block and no
|
|
303
|
+
* partial answers.
|
|
304
|
+
* @throws {UnsupportedError} when this build declines the call, or the
|
|
305
|
+
* artifact predates the block twin.
|
|
306
|
+
*/
|
|
307
|
+
parseBlock(format: Format, body: Uint8Array, settings?: Settings): Block;
|
|
308
|
+
/** @internal — `Block#close` deregisters itself here. */
|
|
309
|
+
forgetBlock(block: Block): void;
|
|
310
|
+
/**
|
|
311
|
+
* Release the native schema. Idempotent. After it, `row` / `rows` /
|
|
312
|
+
* `setEngine` / `setTtl` throw `ChtypesError` ("schema is closed").
|
|
313
|
+
* Any `Filter` or `Block` still open on this schema is closed FIRST, in
|
|
314
|
+
* the same call — the handles-before-schema free order the C layer
|
|
315
|
+
* requires, enforced here so no dispose ordering can get it backwards.
|
|
316
|
+
*/
|
|
317
|
+
close(): void;
|
|
318
|
+
/** `using schema = lib.compileDdl(...)` releases it at scope exit. */
|
|
319
|
+
[Symbol.dispose](): void;
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* One boolean SQL expression compiled against a `Schema`'s columns
|
|
323
|
+
* (`chs_filter_compile`). Obtained from `Schema#compileFilter`; never
|
|
324
|
+
* constructed directly.
|
|
325
|
+
*
|
|
326
|
+
* LIFETIME: a filter REFERENCES its schema handle — the C layer does not copy
|
|
327
|
+
* and does not refcount (spec/c-abi.md §Filters). This binding enforces the
|
|
328
|
+
* free order structurally, both ways: the `Filter` holds its `Schema` (so the
|
|
329
|
+
* schema stays reachable), and `Schema#close` closes every open filter before
|
|
330
|
+
* freeing the schema. `close()` is idempotent, and `using` / `Symbol.dispose`
|
|
331
|
+
* work on both objects in any nesting — the schema's dispose runs the
|
|
332
|
+
* filter's first when the caller forgot. A filter compiled from a schema
|
|
333
|
+
* answers for THAT handle: recompile filters when the schema is recompiled.
|
|
334
|
+
*
|
|
335
|
+
* THREADS: the header's rule, verbatim — one `chs_filter` "must not be used
|
|
336
|
+
* from two threads at once, and a chs_filter call is ALSO a use of its schema
|
|
337
|
+
* handle" (two filters over ONE schema must not run concurrently either). On
|
|
338
|
+
* a single JS thread every call here is synchronous, so ordinary Node code
|
|
339
|
+
* satisfies both by construction (spec/bindings.md §Concurrency); do not
|
|
340
|
+
* share a `Filter` — or its `Schema` — across `worker_threads`.
|
|
341
|
+
*
|
|
342
|
+
* ENFORCEMENT GATE: `'error'` and `'decline'` verdicts are NOT answers — a
|
|
343
|
+
* caller enforcing visibility MUST fail closed on both — and NO caller may
|
|
344
|
+
* enforce read-side security on this surface until the WHERE-truth rig gates
|
|
345
|
+
* green; until then it is a shadow/replay surface (spec/c-abi.md §Filters).
|
|
346
|
+
*/
|
|
347
|
+
export declare class Filter {
|
|
348
|
+
private readonly native;
|
|
349
|
+
private readonly schema;
|
|
350
|
+
/** The expression text as compiled, for logging and cache keys. */
|
|
351
|
+
readonly expr: string;
|
|
352
|
+
private handle;
|
|
353
|
+
/** @internal — obtained from `Schema#compileFilter`. */
|
|
354
|
+
constructor(native: NativeLibrary, schema: Schema, handle: FilterHandle,
|
|
355
|
+
/** The expression text as compiled, for logging and cache keys. */
|
|
356
|
+
expr: string);
|
|
357
|
+
/**
|
|
358
|
+
* Evaluate the filter over a body of rows (`chs_filter_rows`) — the same
|
|
359
|
+
* formats and settings contract as `Schema#rows`, ONE C call. Rows are
|
|
360
|
+
* evaluated INDEPENDENTLY (there is no INSERT to abort):
|
|
361
|
+
* `input_format_allow_errors_*` does not apply, a bad text row declines
|
|
362
|
+
* (`'decline'`) and the tail resyncs so verdict indexes keep matching input
|
|
363
|
+
* rows, and volatile DEFAULTs resolve against one clock instant per call.
|
|
364
|
+
*
|
|
365
|
+
* @param format - the wire format code (`Format`).
|
|
366
|
+
* @param body - the rows as bytes (never a JS string).
|
|
367
|
+
* @param settings - per-call settings; same precedence as `Schema#rows`.
|
|
368
|
+
* @returns the `FilterResult` — the call-level outcome, and one verdict per
|
|
369
|
+
* row when it is `'ok'`.
|
|
370
|
+
* @throws {ChtypesError} when the filter is closed, or a settings value is
|
|
371
|
+
* a JS `number`.
|
|
372
|
+
*/
|
|
373
|
+
rows(format: Format, body: Uint8Array, settings?: Settings): FilterResult;
|
|
374
|
+
/**
|
|
375
|
+
* Evaluate this filter over an already-parsed `Block` (`chs_filter_eval`)
|
|
376
|
+
* — the SAME result document `rows` returns: same `FilterResult` fields,
|
|
377
|
+
* same verdicts, same `errors` rule (a row the parse recorded as
|
|
378
|
+
* unparseable answers `'decline'` with the recorded error). Evaluation is
|
|
379
|
+
* a pure function of (filter, block): no settings, and the block is
|
|
380
|
+
* neither consumed nor mutated, so one block can be evaluated by K filters
|
|
381
|
+
* sequentially with no re-parse — the live-SSE call shape.
|
|
382
|
+
*
|
|
383
|
+
* Filter and block MUST come from the SAME schema: a mismatched pair
|
|
384
|
+
* answers a REJECTED result (code 1002) — the C layer's loud refusal,
|
|
385
|
+
* never undefined behaviour. A pair from two different libraries throws
|
|
386
|
+
* `ChtypesError`: no handle ever crosses a dlopen'd image boundary.
|
|
387
|
+
*
|
|
388
|
+
* @param block - a `Block` from `Schema#parseBlock`.
|
|
389
|
+
* @returns the `FilterResult`, exactly as `rows` would answer it.
|
|
390
|
+
* @throws {ChtypesError} when the filter or block is closed, or they come
|
|
391
|
+
* from two different libraries.
|
|
392
|
+
*/
|
|
393
|
+
eval(block: Block): FilterResult;
|
|
394
|
+
/**
|
|
395
|
+
* Release the native filter (`chs_filter_free`). Idempotent, and also
|
|
396
|
+
* performed by the schema's own `close()` — filters first, then the schema,
|
|
397
|
+
* the C-required order.
|
|
398
|
+
*/
|
|
399
|
+
close(): void;
|
|
400
|
+
/** `using filter = schema.compileFilter(...)` releases it at scope exit. */
|
|
401
|
+
[Symbol.dispose](): void;
|
|
402
|
+
}
|
|
403
|
+
/**
|
|
404
|
+
* One body, parsed ONCE under one schema handle and one clock instant
|
|
405
|
+
* (`chs_block_parse`). Obtained from `Schema#parseBlock`; evaluated by
|
|
406
|
+
* `Filter#eval`. The parse-once/eval-many twin of `Filter#rows`
|
|
407
|
+
* (spec/c-abi.md §Blocks): the live-SSE hot path is K filters × 1 event, and
|
|
408
|
+
* the block sheds the re-parse.
|
|
409
|
+
*
|
|
410
|
+
* LIFETIME: a block REFERENCES its schema handle exactly as a filter does —
|
|
411
|
+
* the C layer does not copy and does not refcount. This binding enforces the
|
|
412
|
+
* free order structurally, both ways: the `Block` holds its `Schema` (so the
|
|
413
|
+
* schema stays reachable), and `Schema#close` closes every open block before
|
|
414
|
+
* freeing the schema — `using` / `Symbol.dispose` work on all three objects
|
|
415
|
+
* in any nesting, and the schema's dispose runs the block's first when the
|
|
416
|
+
* caller forgot. A block may be evaluated by MANY filters, sequentially;
|
|
417
|
+
* evaluation does not consume or mutate it. Recompile blocks when the schema
|
|
418
|
+
* is recompiled.
|
|
419
|
+
*
|
|
420
|
+
* THREADS: one block must not be used from two threads at once, and an eval
|
|
421
|
+
* is a use of BOTH handles. On a single JS thread every call here is
|
|
422
|
+
* synchronous, so ordinary Node code satisfies both by construction; do not
|
|
423
|
+
* share a `Block` — or its `Schema` — across `worker_threads`.
|
|
424
|
+
*/
|
|
425
|
+
export declare class Block {
|
|
426
|
+
private readonly native;
|
|
427
|
+
private readonly schema;
|
|
428
|
+
private handle;
|
|
429
|
+
/** @internal — obtained from `Schema#parseBlock`. */
|
|
430
|
+
constructor(native: NativeLibrary, schema: Schema, handle: BlockHandle);
|
|
431
|
+
/** @internal — the loaded library this block's handle belongs to. */
|
|
432
|
+
get nativeLib(): NativeLibrary;
|
|
433
|
+
/** @internal — the live handle, for `Filter#eval`. */
|
|
434
|
+
liveHandle(): BlockHandle;
|
|
435
|
+
/**
|
|
436
|
+
* Release the native block (`chs_block_free`). Idempotent, and also
|
|
437
|
+
* performed by the schema's own `close()` — blocks first, then the schema,
|
|
438
|
+
* the C-required order.
|
|
439
|
+
*/
|
|
440
|
+
close(): void;
|
|
441
|
+
/** `using block = schema.parseBlock(...)` releases it at scope exit. */
|
|
442
|
+
[Symbol.dispose](): void;
|
|
443
|
+
}
|
|
444
|
+
//# sourceMappingURL=schema.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
|