@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.
Files changed (72) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/LICENSE +202 -0
  3. package/README.md +442 -0
  4. package/dist/cli.d.ts +43 -0
  5. package/dist/cli.d.ts.map +1 -0
  6. package/dist/cli.js +303 -0
  7. package/dist/cli.js.map +1 -0
  8. package/dist/discover.d.ts +134 -0
  9. package/dist/discover.d.ts.map +1 -0
  10. package/dist/discover.js +291 -0
  11. package/dist/discover.js.map +1 -0
  12. package/dist/errors.d.ts +204 -0
  13. package/dist/errors.d.ts.map +1 -0
  14. package/dist/errors.js +228 -0
  15. package/dist/errors.js.map +1 -0
  16. package/dist/fetch.d.ts +235 -0
  17. package/dist/fetch.d.ts.map +1 -0
  18. package/dist/fetch.js +842 -0
  19. package/dist/fetch.js.map +1 -0
  20. package/dist/ffi.d.ts +346 -0
  21. package/dist/ffi.d.ts.map +1 -0
  22. package/dist/ffi.js +913 -0
  23. package/dist/ffi.js.map +1 -0
  24. package/dist/format.d.ts +104 -0
  25. package/dist/format.d.ts.map +1 -0
  26. package/dist/format.js +108 -0
  27. package/dist/format.js.map +1 -0
  28. package/dist/index.d.ts +28 -0
  29. package/dist/index.d.ts.map +1 -0
  30. package/dist/index.js +28 -0
  31. package/dist/index.js.map +1 -0
  32. package/dist/json.d.ts +127 -0
  33. package/dist/json.d.ts.map +1 -0
  34. package/dist/json.js +577 -0
  35. package/dist/json.js.map +1 -0
  36. package/dist/library.d.ts +225 -0
  37. package/dist/library.d.ts.map +1 -0
  38. package/dist/library.js +234 -0
  39. package/dist/library.js.map +1 -0
  40. package/dist/numeric.d.ts +20 -0
  41. package/dist/numeric.d.ts.map +1 -0
  42. package/dist/numeric.js +107 -0
  43. package/dist/numeric.js.map +1 -0
  44. package/dist/paths.d.ts +47 -0
  45. package/dist/paths.d.ts.map +1 -0
  46. package/dist/paths.js +78 -0
  47. package/dist/paths.js.map +1 -0
  48. package/dist/registry.d.ts +204 -0
  49. package/dist/registry.d.ts.map +1 -0
  50. package/dist/registry.js +409 -0
  51. package/dist/registry.js.map +1 -0
  52. package/dist/results.d.ts +326 -0
  53. package/dist/results.d.ts.map +1 -0
  54. package/dist/results.js +235 -0
  55. package/dist/results.js.map +1 -0
  56. package/dist/schema.d.ts +444 -0
  57. package/dist/schema.d.ts.map +1 -0
  58. package/dist/schema.js +448 -0
  59. package/dist/schema.js.map +1 -0
  60. package/dist/settings.d.ts +43 -0
  61. package/dist/settings.d.ts.map +1 -0
  62. package/dist/settings.js +33 -0
  63. package/dist/settings.js.map +1 -0
  64. package/dist/tar.d.ts +32 -0
  65. package/dist/tar.d.ts.map +1 -0
  66. package/dist/tar.js +310 -0
  67. package/dist/tar.js.map +1 -0
  68. package/dist/transform.d.ts +73 -0
  69. package/dist/transform.d.ts.map +1 -0
  70. package/dist/transform.js +527 -0
  71. package/dist/transform.js.map +1 -0
  72. package/package.json +62 -0
@@ -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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"}