@rindle/wasm 0.1.0-rc.5

package/pkg/rindle.d.ts

@@ -0,0 +1,261 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * The in-memory live-query engine, callable from JavaScript. See the module docs.
+ */
+export class Db {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Tear down a registered query: drop its sink + reclaim its pipeline (disconnect from
+     * the shared sources, free its slots — [`Graph::destroy_pipeline`]). Other queries
+     * and the shared sources are untouched. A no-op for an unknown id.
+     */
+    destroyQuery(query_id: number): void;
+    constructor();
+    /**
+     * Register a live query from a Zero-wire AST under the caller's opaque `query_id`.
+     * Lowers it into the shared graph, sinks it in a change-sink, and hydrates. Returns
+     * `{ queryId, comparatorVersion, schema, snapshot }` — the `hello` + hydrate
+     * snapshot for the JS `ArrayView` (snapshot cells **bare**). A malformed AST /
+     * unknown table / unknown column throws a JS `Error` carrying a `.kind`.
+     */
+    query(query_id: number, ast_json: any): any;
+    /**
+     * Register a base table from a `SchemaSpec` (`{ columns, primaryKey, sort? }` —
+     * [`marshal::schema_from_js`]; any `relationships` in the spec are ignored — nesting
+     * is query-local via `sub`). Seeds an empty shared source. Idempotent per name.
+     */
+    registerTable(table: string, schema: any): void;
+    /**
+     * Open a §1.3 reconcile cycle against the coherent server delta `deltas` —
+     * an array of base-table row ops `{ table, type: "add"|"remove"|"edit", row,
+     * old? }` (the cv-released normalized batch, bare cells). Runs the rewind
+     * (steps 1–4): the engine's input becomes the authoritative state `S'`, with
+     * every optimistic write un-applied and the server delta folded in; `sync`
+     * re-forks. Nothing is delivered yet — the JS side now **re-invokes each
+     * still-pending client mutator** (ordinary `write()`/`commit()` calls, whose
+     * events buffer into the cycle), then calls
+     * [`server_batch_end`](Db::server_batch_end) for the one coalesced delivery.
+     *
+     * Errors if a cycle is already open, on an unknown table, or on a push failure
+     * — after which the optimistic state is poisoned (a partial rewind may have
+     * applied): the only safe recovery is to discard this `Db` and re-hydrate.
+     */
+    serverBatchBegin(deltas: any): void;
+    /**
+     * Close the open cycle: deliver the whole buffered event stream (rewind +
+     * re-invocations) per query, **in order**, as `[{ queryId, events: FlatChange[] }]`
+     * — one batch per affected query. The stream is forwarded RAW: the IVM sink emits
+     * changes in a valid incremental order (`FLAT-CHANGES-DESIGN.md` §5.4), so the
+     * receiver folds them in order to reach `view(head_new)`. The §3 "notify once"
+     * boundary is the view's own — one `applyChanges` per batch, settling before it
+     * notifies. Queries the cycle never touched are omitted.
+     *
+     * Note: a still-pending write whose re-invocation reproduced its prediction emits a
+     * balanced `remove`+`add` here. That nets to no observable change once the view
+     * settles, but it is no longer suppressed *at this boundary* (the netting/reordering
+     * that did so was the source of the coalescer correctness bugs). Restoring
+     * no-op-cycle ⇒ no-notify is a view-level optimization (Step 2 of the removal).
+     */
+    serverBatchEnd(): any;
+    /**
+     * Remove a base table previously added by [`register_table`](Self::register_table): free
+     * its source node, drop its optimistic baseline, and forget it from the source map — the
+     * inverse of `register_table`. For a SYNTHETIC aggregate table (`__agg_*`) whose last
+     * reading query has been destroyed (`AGGREGATE-SYNC-DESIGN.md` §4): aggregate state is
+     * reclaimed, not permanent. Idempotent for an unknown/already-removed table. Throws a JS
+     * `Error` if the table still has a live query connected to it — the caller must
+     * `destroy_query` every reader first (the optimistic/normalized backend refcounts so this
+     * holds).
+     */
+    unregisterTable(table: string): void;
+    /**
+     * Open a write transaction. Stage row ops with [`WriteTxn::add`]/`remove`/`edit`,
+     * then [`WriteTxn::commit`] to apply them as one batch and get the per-query flat
+     * changes back. Dropping (or `rollback`) without committing applies nothing.
+     */
+    write(): WriteTxn;
+}
+
+/**
+ * A built, hydrated query view, callable from JavaScript.
+ */
+export class RindleView {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build + hydrate a view from an AST (JS JSON) and a table→schema map.
+     *
+     * - `ast_json`: the query AST — Zero's wire shape (see `src/ast.rs`).
+     * - `schemas`: `{ tableName: <SchemaSpec> }` (see [`marshal::schema_from_js`]).
+     * - `data`: optional `{ tableName: row[][] }` initial rows (each row a cell
+     *   array, positional with the schema's `columns`); a table absent here seeds
+     *   empty.
+     *
+     * A `BuildError`/`RindleError` is thrown as a JS `Error` with a `.kind` tag.
+     */
+    static build(ast_json: any, schemas: any, data: any): RindleView;
+    /**
+     * The current materialized view tree as a JS value (array / object / `null`).
+     */
+    data(): any;
+    /**
+     * Close the current transaction: fire listeners with the new snapshot.
+     */
+    flush(): void;
+    /**
+     * Push one source change `{ type: 'add'|'remove'|'edit', row, old? }` to `table`.
+     * Does **not** flush — call [`RindleView::flush`] to close the transaction (so a JS
+     * client can batch several pushes into one notification).
+     */
+    push(table: string, change: any): void;
+    /**
+     * The view's current result type (`"unknown" | "complete" | "error"`).
+     */
+    resultType(): any;
+    /**
+     * Resolve the async result type (the `queryComplete` transition); fires
+     * listeners out of band. Accepts `"complete" | "error" | "unknown"`.
+     */
+    setResultType(rt: string): void;
+    /**
+     * Subscribe a JS callback `(data, resultType) => void`, fired **once
+     * immediately** and on every subsequent [`RindleView::flush`]. Returns the
+     * listener index.
+     */
+    subscribe(cb: Function): number;
+}
+
+/**
+ * An open write transaction: a staging buffer of row ops applied atomically at
+ * [`commit`](WriteTxn::commit). Nothing touches the engine until commit, so a dropped or
+ * rolled-back txn is a clean no-op (no `Drop` undo needed).
+ */
+export class WriteTxn {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Stage an add of `row` (a positional cell array, width-checked against the table's
+     * schema) to `table`.
+     */
+    add(table: string, row: any): void;
+    /**
+     * Apply the staged ops (push through the shared sources, fanning to every dependent
+     * query), drain each affected query's sink, and return `[{ queryId, events:
+     * FlatChange[] }]` for the queries that changed (empties omitted, like
+     * `Publisher::commit`). Consumes the transaction.
+     *
+     * **Inside a server-batch cycle** (a pending mutator re-invocation between
+     * [`Db::server_batch_begin`] and [`Db::server_batch_end`]) the drained events
+     * buffer into the cycle instead and an **empty** array returns — the §3
+     * notify-once boundary: the whole cycle delivers exactly once, coalesced, at
+     * `serverBatchEnd`.
+     */
+    commit(): any;
+    /**
+     * Stage an edit of `old` → `new_row` in `table` (both width-checked).
+     *
+     * **Partial (optimistic) edit (`PROJECTION-SUPPORT-DESIGN.md` §8 / OQ-3).** An
+     * [`OwnedValue::Absent`] cell in `new_row` means *"not touching this column — leave it
+     * unchanged"*: it falls through to the current **effective** row (the live engine under
+     * this txn's staged overlay, i.e. what [`WriteTxn::get`] would return). The merge is
+     * resolved **here, at the staging boundary**, into a concrete full-width
+     * [`SourceChange::Edit`] whose `old` is that effective row — so operators, indexes, and
+     * the overlay never learn about merge semantics (they keep seeing whole rows), and a
+     * re-invocation after a server rebase re-reads the *new* effective row and re-merges.
+     * Presence is **monotonic**: a partial edit only *sets* columns (or leaves them), never
+     * narrows — narrowing is sync-only (§4.2). A full `new_row` (no `Absent`) stages verbatim,
+     * byte-identical to before (§7).
+     */
+    edit(table: string, old: any, new_row: any): void;
+    /**
+     * The current row of `table` whose primary key equals `pk` (an array of the PK
+     * column cells, in `primaryKey` order), or `undefined`. Reads the live engine
+     * state **plus this transaction's own staged ops** (later staged ops win), so a
+     * read-dependent client mutator sees its prior writes — the §4.1 contract. During
+     * a server-batch cycle the live state is the rebased base (`S'` + the pending
+     * mutations re-invoked so far), which is exactly what re-invocation must read.
+     */
+    get(table: string, pk: any): any;
+    /**
+     * Stage a remove of `row` from `table`.
+     */
+    remove(table: string, row: any): void;
+    /**
+     * Discard the staged ops without applying anything. (Nothing was applied, so this
+     * just consumes the handle; it exists for a symmetric, explicit API.)
+     */
+    rollback(): void;
+}
+
+/**
+ * Install the panic hook so a residual wasm panic surfaces a legible JS `Error`
+ * (with a Rust message) instead of an opaque `RuntimeError: unreachable` (WS09.6).
+ * Runs once on module load.
+ */
+export function __rindle_wasm_start(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __rindle_wasm_start: () => void;
+    readonly __wbg_db_free: (a: number, b: number) => void;
+    readonly __wbg_rindleview_free: (a: number, b: number) => void;
+    readonly __wbg_writetxn_free: (a: number, b: number) => void;
+    readonly db_destroyQuery: (a: number, b: number) => void;
+    readonly db_new: () => number;
+    readonly db_query: (a: number, b: number, c: any) => [number, number, number];
+    readonly db_registerTable: (a: number, b: number, c: number, d: any) => [number, number];
+    readonly db_serverBatchBegin: (a: number, b: any) => [number, number];
+    readonly db_serverBatchEnd: (a: number) => [number, number, number];
+    readonly db_unregisterTable: (a: number, b: number, c: number) => [number, number];
+    readonly db_write: (a: number) => number;
+    readonly rindleview_build: (a: any, b: any, c: any) => [number, number, number];
+    readonly rindleview_data: (a: number) => any;
+    readonly rindleview_flush: (a: number) => void;
+    readonly rindleview_push: (a: number, b: number, c: number, d: any) => [number, number];
+    readonly rindleview_resultType: (a: number) => any;
+    readonly rindleview_setResultType: (a: number, b: number, c: number) => void;
+    readonly rindleview_subscribe: (a: number, b: any) => number;
+    readonly writetxn_add: (a: number, b: number, c: number, d: any) => [number, number];
+    readonly writetxn_commit: (a: number) => [number, number, number];
+    readonly writetxn_edit: (a: number, b: number, c: number, d: any, e: any) => [number, number];
+    readonly writetxn_get: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly writetxn_remove: (a: number, b: number, c: number, d: any) => [number, number];
+    readonly writetxn_rollback: (a: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;