jazz-wasm 2.0.0-alpha.2

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "jazz-wasm",
+  "version": "2.0.0-alpha.2",
+  "description": "WebAssembly bindings for the Jazz database engine",
+  "keywords": [
+    "crdt",
+    "database",
+    "local-first",
+    "wasm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/garden-co/jazz"
+  },
+  "files": [
+    "pkg/jazz_wasm_bg.wasm",
+    "pkg/jazz_wasm.js",
+    "pkg/jazz_wasm.d.ts"
+  ],
+  "main": "pkg/jazz_wasm.js",
+  "types": "pkg/jazz_wasm.d.ts",
+  "devDependencies": {
+    "wasm-pack": "^0.14.0"
+  },
+  "scripts": {
+    "build": "wasm-pack build --target web --profiling"
+  }
+}

package/pkg/jazz_wasm.d.ts

@@ -0,0 +1,473 @@
+/* tslint:disable */
+/* eslint-disable */
+export interface WasmColumnDescriptor {
+    name: string;
+    column_type: WasmColumnType;
+    nullable: boolean;
+    references?: string;
+}
+
+export interface WasmOperationPolicy {
+    using?: WasmPolicyExpr;
+    with_check?: WasmPolicyExpr;
+}
+
+export interface WasmRow {
+    id: string;
+    values: WasmValue[];
+}
+
+export interface WasmRowDelta {
+    added: WasmRow[];
+    removed: WasmRow[];
+    updated: [WasmRow, WasmRow][];
+    pending: boolean;
+}
+
+export interface WasmSchema {
+    tables: Record<string, WasmTableSchema>;
+}
+
+export interface WasmTablePolicies {
+    select?: WasmOperationPolicy;
+    insert?: WasmOperationPolicy;
+    update?: WasmOperationPolicy;
+    delete?: WasmOperationPolicy;
+}
+
+export interface WasmTableSchema {
+    columns: WasmColumnDescriptor[];
+    policies?: WasmTablePolicies;
+}
+
+export type WasmCmpOp = "Eq" | "Ne" | "Lt" | "Le" | "Gt" | "Ge";
+
+export type WasmColumnType = { type: "Integer" } | { type: "BigInt" } | { type: "Boolean" } | { type: "Text" } | { type: "Enum"; variants: string[] } | { type: "Timestamp" } | { type: "Uuid" } | { type: "Array"; element: WasmColumnType } | { type: "Row"; columns: WasmColumnDescriptor[] };
+
+export type WasmPolicyExpr = { type: "Cmp"; column: string; op: WasmCmpOp; value: WasmPolicyValue } | { type: "IsNull"; column: string } | { type: "IsNotNull"; column: string } | { type: "In"; column: string; session_path: string[] } | { type: "Exists"; table: string; condition: WasmPolicyExpr } | { type: "ExistsRel"; rel: any } | { type: "Inherits"; operation: WasmPolicyOperation; via_column: string; max_depth?: number } | { type: "And"; exprs: WasmPolicyExpr[] } | { type: "Or"; exprs: WasmPolicyExpr[] } | { type: "Not"; expr: WasmPolicyExpr } | { type: "True" } | { type: "False" };
+
+export type WasmPolicyOperation = "Select" | "Insert" | "Update" | "Delete";
+
+export type WasmPolicyValue = { type: "Literal"; value: WasmValue } | { type: "SessionRef"; path: string[] };
+
+export type WasmValue = { type: "Integer"; value: number } | { type: "BigInt"; value: number } | { type: "Boolean"; value: boolean } | { type: "Text"; value: string } | { type: "Timestamp"; value: number } | { type: "Uuid"; value: string } | { type: "Array"; value: WasmValue[] } | { type: "Row"; value: WasmValue[] } | { type: "Null" };
+
+
+/**
+ * WASM-exposed QueryBuilder with camelCase methods.
+ */
+export class WasmQueryBuilder {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Set a table alias.
+     */
+    alias(alias: string): WasmQueryBuilder;
+    /**
+     * Set the branch to query.
+     */
+    branch(branch: string): WasmQueryBuilder;
+    /**
+     * Set multiple branches to query.
+     */
+    branches(branches: string[]): WasmQueryBuilder;
+    /**
+     * Build the query and return as JSON string.
+     */
+    build(): string;
+    /**
+     * Build and return as JsValue.
+     */
+    buildJs(): any;
+    /**
+     * Add an equals filter.
+     */
+    filterEq(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Add a greater-than-or-equal filter.
+     */
+    filterGe(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Add a greater-than filter.
+     */
+    filterGt(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Add a less-than-or-equal filter.
+     */
+    filterLe(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Add a less-than filter.
+     */
+    filterLt(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Add a not-equals filter.
+     */
+    filterNe(column: string, value: any): WasmQueryBuilder;
+    /**
+     * Include soft-deleted rows.
+     */
+    includeDeleted(): WasmQueryBuilder;
+    /**
+     * Join another table.
+     */
+    join(table: string): WasmQueryBuilder;
+    /**
+     * Set a limit.
+     */
+    limit(n: number): WasmQueryBuilder;
+    /**
+     * Create a new QueryBuilder for a table.
+     */
+    constructor(table: string);
+    /**
+     * Set an offset.
+     */
+    offset(n: number): WasmQueryBuilder;
+    /**
+     * Specify join condition.
+     */
+    on(left_col: string, right_col: string): WasmQueryBuilder;
+    /**
+     * Start a new OR branch.
+     */
+    or(): WasmQueryBuilder;
+    /**
+     * Add ascending order by.
+     */
+    orderBy(column: string): WasmQueryBuilder;
+    /**
+     * Add descending order by.
+     */
+    orderByDesc(column: string): WasmQueryBuilder;
+    /**
+     * Select specific columns.
+     */
+    select(columns: string[]): WasmQueryBuilder;
+}
+
+/**
+ * Main runtime for JavaScript applications.
+ *
+ * Wraps `Rc<RefCell<WasmCoreType>>`.
+ * All methods borrow the core, call RuntimeCore, and return.
+ * Async scheduling happens via WasmScheduler.schedule_batched_tick().
+ */
+export class WasmRuntime {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add a client connection (for server-side use in tests).
+     */
+    addClient(): string;
+    /**
+     * Add a server connection.
+     *
+     * After adding the server, immediately flushes the outbox so that
+     * catalogue sync messages (from queue_full_sync_to_server) are sent
+     * before the call returns, rather than being deferred to a microtask.
+     */
+    addServer(): void;
+    /**
+     * Delete a row by ObjectId.
+     */
+    delete(object_id: string): void;
+    /**
+     * Delete a row and return a Promise that resolves when the tier acks.
+     */
+    deleteWithAck(object_id: string, tier: string): Promise<any>;
+    /**
+     * Flush all data to persistent storage (snapshot).
+     */
+    flush(): void;
+    /**
+     * Flush only the WAL buffer to OPFS (not the snapshot).
+     */
+    flushWal(): void;
+    /**
+     * Get the current schema as JSON.
+     */
+    getSchema(): any;
+    /**
+     * Get the canonical schema hash (64-char hex).
+     */
+    getSchemaHash(): string;
+    /**
+     * Insert a row into a table.
+     *
+     * # Returns
+     * The new row's ObjectId as a UUID string.
+     */
+    insert(table: string, values: any): string;
+    /**
+     * Insert a row and return a Promise that resolves when the tier acks.
+     *
+     * `tier` must be one of: "worker", "edge", "core".
+     */
+    insertWithAck(table: string, values: any, tier: string): Promise<any>;
+    /**
+     * Create a new WasmRuntime.
+     *
+     * Storage is synchronous (in-memory via MemoryStorage).
+     *
+     * # Arguments
+     * * `schema_json` - JSON-encoded schema definition
+     * * `app_id` - Application identifier
+     * * `env` - Environment (e.g., "dev", "prod")
+     * * `user_branch` - User's branch name (e.g., "main")
+     * * `tier` - Optional persistence tier ("worker", "edge", "core").
+     *            Set for server nodes to enable ack emission.
+     */
+    constructor(schema_json: string, app_id: string, env: string, user_branch: string, tier?: string | null);
+    /**
+     * Called by JS when a sync message arrives from the server.
+     *
+     * # Arguments
+     * * `message_json` - JSON-encoded SyncPayload
+     */
+    onSyncMessageReceived(message_json: string): void;
+    /**
+     * Called by JS when a sync message arrives from a client (not a server).
+     *
+     * # Arguments
+     * * `client_id` - UUID string of the sending client
+     * * `message_json` - JSON-encoded SyncPayload
+     */
+    onSyncMessageReceivedFromClient(client_id: string, message_json: string): void;
+    /**
+     * Register a callback for outgoing sync messages.
+     */
+    onSyncMessageToSend(callback: Function): void;
+    /**
+     * Create a persistent WasmRuntime backed by OPFS.
+     *
+     * Opens a single OPFS file namespace and restores state from the latest
+     * durable checkpoint.
+     */
+    static openPersistent(schema_json: string, app_id: string, env: string, user_branch: string, db_name: string, tier?: string | null): Promise<WasmRuntime>;
+    /**
+     * Execute a query and return results as a Promise.
+     *
+     * Optional `settled_tier` holds delivery until the tier confirms.
+     */
+    query(query_json: string, session_json?: string | null, settled_tier?: string | null): Promise<any>;
+    /**
+     * Remove the current upstream server connection.
+     */
+    removeServer(): void;
+    /**
+     * Set a client's role.
+     *
+     * # Arguments
+     * * `client_id` - UUID string of the client
+     * * `role` - One of "user", "admin", "peer"
+     */
+    setClientRole(client_id: string, role: string): void;
+    /**
+     * Subscribe to a query with a callback.
+     *
+     * Default behavior matches RuntimeCore:
+     * - with upstream server: first callback waits for protocol QuerySettled convergence
+     * - without upstream server: first callback is local-immediate
+     *
+     * Pass `settled_tier` to override this default.
+     *
+     * # Returns
+     * Subscription handle (f64) for later unsubscription.
+     */
+    subscribe(query_json: string, on_update: Function, session_json?: string | null, settled_tier?: string | null): number;
+    /**
+     * Unsubscribe from a query.
+     */
+    unsubscribe(handle: number): void;
+    /**
+     * Update a row by ObjectId.
+     */
+    update(object_id: string, values: any): void;
+    /**
+     * Update a row and return a Promise that resolves when the tier acks.
+     */
+    updateWithAck(object_id: string, values: any, tier: string): Promise<any>;
+}
+
+export function bench_get_cache_bytes(): number;
+
+export function bench_get_overflow_threshold_bytes(): number;
+
+export function bench_get_pin_internal_pages(): boolean;
+
+export function bench_get_read_coalesce_pages(): number;
+
+export function bench_opfs_cold_random_read(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_cold_sequential_read(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_matrix(count: number): Promise<any>;
+
+export function bench_opfs_mixed_matrix(count: number): Promise<any>;
+
+export function bench_opfs_mixed_scenario(scenario_name: string, count: number, value_size: number, base_seed?: bigint | null): Promise<any>;
+
+export function bench_opfs_random_read(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_random_write(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_range_random_window(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_range_seq_window(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_sequential_read(count: number, value_size: number): Promise<any>;
+
+export function bench_opfs_sequential_write(count: number, value_size: number): Promise<any>;
+
+export function bench_reset_cache_bytes(): void;
+
+export function bench_reset_overflow_threshold_bytes(): void;
+
+export function bench_reset_pin_internal_pages(): void;
+
+export function bench_reset_read_coalesce_pages(): void;
+
+export function bench_set_cache_bytes(cache_bytes: number): void;
+
+export function bench_set_overflow_threshold_bytes(overflow_threshold_bytes: number): void;
+
+export function bench_set_pin_internal_pages(pin_internal_pages: boolean): void;
+
+export function bench_set_read_coalesce_pages(read_coalesce_pages: number): void;
+
+/**
+ * Get the current timestamp in microseconds since Unix epoch.
+ */
+export function currentTimestamp(): bigint;
+
+/**
+ * Generate a new UUID v7 (time-ordered).
+ *
+ * Useful for generating row IDs on the client side.
+ */
+export function generateId(): string;
+
+/**
+ * Initialize the WASM module.
+ *
+ * Sets up panic hook for better error messages in the browser console.
+ */
+export function init(): void;
+
+/**
+ * Parse a schema from JSON string.
+ *
+ * Returns the schema as a JsValue for inspection.
+ */
+export function parseSchema(json: string): any;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmquerybuilder_free: (a: number, b: number) => void;
+    readonly currentTimestamp: () => bigint;
+    readonly generateId: () => [number, number];
+    readonly parseSchema: (a: number, b: number) => [number, number, number];
+    readonly wasmquerybuilder_alias: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_branch: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_branches: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_build: (a: number) => [number, number, number, number];
+    readonly wasmquerybuilder_buildJs: (a: number) => [number, number, number];
+    readonly wasmquerybuilder_filterEq: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_filterGe: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_filterGt: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_filterLe: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_filterLt: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_filterNe: (a: number, b: number, c: number, d: any) => [number, number, number];
+    readonly wasmquerybuilder_includeDeleted: (a: number) => number;
+    readonly wasmquerybuilder_join: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_limit: (a: number, b: number) => number;
+    readonly wasmquerybuilder_new: (a: number, b: number) => number;
+    readonly wasmquerybuilder_offset: (a: number, b: number) => number;
+    readonly wasmquerybuilder_on: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmquerybuilder_or: (a: number) => number;
+    readonly wasmquerybuilder_orderBy: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_orderByDesc: (a: number, b: number, c: number) => number;
+    readonly wasmquerybuilder_select: (a: number, b: number, c: number) => number;
+    readonly init: () => void;
+    readonly __wbg_wasmruntime_free: (a: number, b: number) => void;
+    readonly wasmruntime_addClient: (a: number) => [number, number];
+    readonly wasmruntime_addServer: (a: number) => void;
+    readonly wasmruntime_delete: (a: number, b: number, c: number) => [number, number];
+    readonly wasmruntime_deleteWithAck: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly wasmruntime_flush: (a: number) => void;
+    readonly wasmruntime_flushWal: (a: number) => void;
+    readonly wasmruntime_getSchema: (a: number) => [number, number, number];
+    readonly wasmruntime_getSchemaHash: (a: number) => [number, number];
+    readonly wasmruntime_insert: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+    readonly wasmruntime_insertWithAck: (a: number, b: number, c: number, d: any, e: number, f: number) => [number, number, number];
+    readonly wasmruntime_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number];
+    readonly wasmruntime_onSyncMessageReceived: (a: number, b: number, c: number) => [number, number];
+    readonly wasmruntime_onSyncMessageReceivedFromClient: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly wasmruntime_onSyncMessageToSend: (a: number, b: any) => void;
+    readonly wasmruntime_openPersistent: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => any;
+    readonly wasmruntime_query: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+    readonly wasmruntime_removeServer: (a: number) => void;
+    readonly wasmruntime_setClientRole: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly wasmruntime_subscribe: (a: number, b: number, c: number, d: any, e: number, f: number, g: number, h: number) => [number, number, number];
+    readonly wasmruntime_unsubscribe: (a: number, b: number) => void;
+    readonly wasmruntime_update: (a: number, b: number, c: number, d: any) => [number, number];
+    readonly wasmruntime_updateWithAck: (a: number, b: number, c: number, d: any, e: number, f: number) => [number, number, number];
+    readonly bench_get_pin_internal_pages: () => number;
+    readonly bench_opfs_cold_random_read: (a: number, b: number) => any;
+    readonly bench_opfs_cold_sequential_read: (a: number, b: number) => any;
+    readonly bench_opfs_matrix: (a: number) => any;
+    readonly bench_opfs_mixed_matrix: (a: number) => any;
+    readonly bench_opfs_mixed_scenario: (a: number, b: number, c: number, d: number, e: number, f: bigint) => any;
+    readonly bench_opfs_random_read: (a: number, b: number) => any;
+    readonly bench_opfs_random_write: (a: number, b: number) => any;
+    readonly bench_opfs_range_random_window: (a: number, b: number) => any;
+    readonly bench_opfs_range_seq_window: (a: number, b: number) => any;
+    readonly bench_opfs_sequential_read: (a: number, b: number) => any;
+    readonly bench_opfs_sequential_write: (a: number, b: number) => any;
+    readonly bench_set_cache_bytes: (a: number) => [number, number];
+    readonly bench_set_overflow_threshold_bytes: (a: number) => [number, number];
+    readonly bench_set_pin_internal_pages: (a: number) => void;
+    readonly bench_set_read_coalesce_pages: (a: number) => [number, number];
+    readonly bench_get_cache_bytes: () => number;
+    readonly bench_get_overflow_threshold_bytes: () => number;
+    readonly bench_get_read_coalesce_pages: () => number;
+    readonly bench_reset_cache_bytes: () => void;
+    readonly bench_reset_overflow_threshold_bytes: () => void;
+    readonly bench_reset_pin_internal_pages: () => void;
+    readonly bench_reset_read_coalesce_pages: () => void;
+    readonly wasm_bindgen__closure__destroy__h36582af6159eae23: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h87add1091edf4849: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h2cc017d284ea0daf: (a: number, b: number, c: any) => 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>;