@laboverwire/stitch-wasm 0.5.0 → 0.6.0

package/README.md

@@ -83,9 +83,7 @@ wasm-pack build crates/stitch-wasm                       # produces pkg/
 wasm-pack test --headless --chrome crates/stitch-wasm    # in-browser smoke test
 ```
 
-The headless suite cannot host a broker, so it asserts the wasm client builds
-and fails gracefully when the broker is unreachable; the native broker-backed
-`stitch-sync` tests cover the sync engine itself.
+The headless suite asserts the wasm client builds and fails gracefully when the broker is unreachable. When `STITCH_WASM_BROKER_URL` is set at build time (for example `ws://127.0.0.1:8083/mqtt` against mqdb started with `--ws-bind` and a `testuser`/`testpass` password file), it also syncs a child create to that live broker. The native broker-backed `stitch-sync` tests cover the rest of the sync engine.
 
 ## License
 

package/package.json

@@ -5,7 +5,7 @@
     "LabOverWire"
   ],
   "description": "Browser (wasm-bindgen) bindings for the stitch reactive state-sync store.",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/stitch_wasm.d.ts

@@ -25,6 +25,22 @@ export class ConnectOptions {
     set requestProblemInformation(value: boolean | null | undefined);
     get requestResponseInformation(): boolean | undefined;
     set requestResponseInformation(value: boolean | null | undefined);
+    /**
+     * Accept `Session Present = 1` on a client that holds no local session state.
+     *
+     * By default a client that has not yet established a session in this instance
+     * rejects a CONNACK with Session Present set to 1, sends DISCONNECT 0x82 and closes
+     * the connection (MQTT-3.2.2-4). Set this to `true` (together with
+     * `cleanStart = false`) to deliberately resume a session the broker still holds,
+     * for example after a page reload or crash. The client has nothing to resend in
+     * that case; the broker resumes delivery of the messages it holds. A CONNACK with
+     * Session Present set to 1 in reply to `cleanStart = true` is always rejected.
+     *
+     * The broker only keeps a session to resume if the previous connection set a non-zero
+     * `sessionExpiryInterval`: under MQTT v5 an absent value means 0, so the session ends
+     * when the connection closes.
+     */
+    resumeExistingSession: boolean;
     get sessionExpiryInterval(): number | undefined;
     set sessionExpiryInterval(value: number | null | undefined);
     set authenticationData(value: Uint8Array);
@@ -62,6 +78,13 @@ export class Cursor {
 export class Database {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Adds a foreign key constraint and persists to storage.
+     *
+     * # Errors
+     * Returns an error if storage fails.
+     */
+    addForeignKeyAsync(source_entity: string, source_field: string, target_entity: string, target_field: string, on_delete: string): Promise<void>;
     /**
      * Adds a foreign key constraint.
      *
@@ -70,12 +93,12 @@ export class Database {
      */
     addForeignKey(source_entity: string, source_field: string, target_entity: string, target_field: string, on_delete: string): void;
     /**
-     * Adds a foreign key constraint and persists to storage.
+     * Adds an index on the specified fields and backfills from existing records (async).
      *
      * # Errors
-     * Returns an error if storage fails.
+     * Returns an error if the storage operation fails during backfill.
      */
-    addForeignKeyAsync(source_entity: string, source_field: string, target_entity: string, target_field: string, on_delete: string): Promise<void>;
+    addIndexAsync(entity: string, fields: string[]): Promise<void>;
     /**
      * Adds an index on the specified fields and backfills from existing records (sync, memory only).
      *
@@ -84,12 +107,12 @@ export class Database {
      */
     addIndex(entity: string, fields: string[]): void;
     /**
-     * Adds an index on the specified fields and backfills from existing records (async).
+     * Adds a NOT NULL constraint and persists to storage.
      *
      * # Errors
-     * Returns an error if the storage operation fails during backfill.
+     * Returns an error if storage fails.
      */
-    addIndexAsync(entity: string, fields: string[]): Promise<void>;
+    addNotNullAsync(entity: string, field: string): Promise<void>;
     /**
      * Adds a NOT NULL constraint on the specified field.
      *
@@ -98,12 +121,12 @@ export class Database {
      */
     addNotNull(entity: string, field: string): void;
     /**
-     * Adds a NOT NULL constraint and persists to storage.
+     * Adds a relationship definition and persists to storage.
      *
      * # Errors
      * Returns an error if storage fails.
      */
-    addNotNullAsync(entity: string, field: string): Promise<void>;
+    addRelationshipAsync(source_entity: string, field: string, target_entity: string): Promise<void>;
     /**
      * Adds a relationship definition for eager loading.
      *
@@ -112,12 +135,12 @@ export class Database {
      */
     addRelationship(source_entity: string, field: string, target_entity: string): void;
     /**
-     * Adds a relationship definition and persists to storage.
+     * Adds a schema definition for an entity and persists to storage.
      *
      * # Errors
-     * Returns an error if storage fails.
+     * Returns an error if the schema definition is invalid or storage fails.
      */
-    addRelationshipAsync(source_entity: string, field: string, target_entity: string): Promise<void>;
+    addSchemaAsync(entity: string, schema_js: any): Promise<void>;
     /**
      * Adds a schema definition for an entity (sync, memory backend only).
      *
@@ -126,12 +149,12 @@ export class Database {
      */
     addSchema(entity: string, schema_js: any): void;
     /**
-     * Adds a schema definition for an entity and persists to storage.
+     * Adds a unique constraint and persists to storage.
      *
      * # Errors
-     * Returns an error if the schema definition is invalid or storage fails.
+     * Returns an error if storage fails.
      */
-    addSchemaAsync(entity: string, schema_js: any): Promise<void>;
+    addUniqueConstraintAsync(entity: string, fields: string[]): Promise<void>;
     /**
      * Adds a unique constraint on the specified fields.
      *
@@ -140,12 +163,10 @@ export class Database {
      */
     addUniqueConstraint(entity: string, fields: string[]): void;
     /**
-     * Adds a unique constraint and persists to storage.
-     *
      * # Errors
-     * Returns an error if storage fails.
+     * Returns an error if options are invalid or the backend is not memory-based.
      */
-    addUniqueConstraintAsync(entity: string, fields: string[]): Promise<void>;
+    countSync(entity: string, options: any): number;
     /**
      * Counts records matching optional filters, using indexes when available.
      *
@@ -155,9 +176,9 @@ export class Database {
     count(entity: string, options: any): Promise<number>;
     /**
      * # Errors
-     * Returns an error if options are invalid or the backend is not memory-based.
+     * Returns an error if validation fails or the backend is not memory-based.
      */
-    countSync(entity: string, options: any): number;
+    createSync(entity: string, data: any): any;
     /**
      * Creates a new record in the specified entity.
      *
@@ -165,11 +186,6 @@ export class Database {
      * Returns an error if validation fails or the storage operation fails.
      */
     create(entity: string, data: any): Promise<any>;
-    /**
-     * # Errors
-     * Returns an error if validation fails or the backend is not memory-based.
-     */
-    createSync(entity: string, data: any): any;
     /**
      * Creates a cursor for streaming iteration over records.
      *
@@ -177,6 +193,11 @@ export class Database {
      * Returns an error if options are invalid or the storage operation fails.
      */
     cursor(entity: string, options: any): Promise<Cursor>;
+    /**
+     * # Errors
+     * Returns an error if the record is not found, foreign key constraints prevent deletion, or the backend is not memory-based.
+     */
+    deleteSync(entity: string, id: string): void;
     /**
      * Deletes a record by entity and ID.
      *
@@ -184,11 +205,6 @@ export class Database {
      * Returns an error if the record is not found or foreign key constraints prevent deletion.
      */
     delete(entity: string, id: string): Promise<void>;
-    /**
-     * # Errors
-     * Returns an error if the record is not found, foreign key constraints prevent deletion, or the backend is not memory-based.
-     */
-    deleteSync(entity: string, id: string): void;
     /**
      * Executes a database operation based on an MQTT-style topic.
      *
@@ -219,13 +235,6 @@ export class Database {
      */
     heartbeat(sub_id: string): boolean;
     isMemoryBackend(): boolean;
-    /**
-     * Lists records from an entity with optional filtering, sorting, and pagination.
-     *
-     * # Errors
-     * Returns an error if options are invalid or the storage operation fails.
-     */
-    list(entity: string, options: any): Promise<any>;
     listConstraints(entity: string): any;
     /**
      * # Errors
@@ -238,16 +247,16 @@ export class Database {
      * Returns an error if options are invalid or the backend is not memory-based.
      */
     listSync(entity: string, options: any): any;
-    constructor();
-    static openEncrypted(db_name: string, passphrase: string): Promise<Database>;
-    static openPersistent(db_name: string): Promise<Database>;
     /**
-     * Reads a record by entity and ID.
+     * Lists records from an entity with optional filtering, sorting, and pagination.
      *
      * # Errors
-     * Returns an error if the record is not found or deserialization fails.
+     * Returns an error if options are invalid or the storage operation fails.
      */
-    read(entity: string, id: string): Promise<any>;
+    list(entity: string, options: any): Promise<any>;
+    constructor();
+    static openEncrypted(db_name: string, passphrase: string): Promise<Database>;
+    static openPersistent(db_name: string): Promise<Database>;
     /**
      * # Errors
      * Returns an error if the record is not found or the backend is not memory-based.
@@ -261,10 +270,12 @@ export class Database {
      */
     readWithIncludes(entity: string, id: string, includes: any): Promise<any>;
     /**
+     * Reads a record by entity and ID.
+     *
      * # Errors
-     * Returns `JsValue` if the database is currently borrowed.
+     * Returns an error if the record is not found or deserialization fails.
      */
-    subscribe(pattern: string, entity: string | null | undefined, callback: Function): string;
+    read(entity: string, id: string): Promise<any>;
     /**
      * # Errors
      * Returns `JsValue` if the database is currently borrowed.
@@ -274,19 +285,24 @@ export class Database {
      * # Errors
      * Returns `JsValue` if the database is currently borrowed.
      */
-    unsubscribe(sub_id: string): boolean;
+    subscribe(pattern: string, entity: string | null | undefined, callback: Function): string;
     /**
-     * Updates an existing record with new field values.
-     *
      * # Errors
-     * Returns an error if the record is not found or validation fails.
+     * Returns `JsValue` if the database is currently borrowed.
      */
-    update(entity: string, id: string, fields: any): Promise<any>;
+    unsubscribe(sub_id: string): boolean;
     /**
      * # Errors
      * Returns an error if the record is not found, validation fails, or the backend is not memory-based.
      */
     updateSync(entity: string, id: string, fields: any): any;
+    /**
+     * Updates an existing record with new field values.
+     *
+     * # Errors
+     * Returns an error if the record is not found or validation fails.
+     */
+    update(entity: string, id: string, fields: any): Promise<any>;
 }
 
 export class MessageProperties {
@@ -309,12 +325,12 @@ export class MqttClient {
      * # Errors
      * Returns an error if connection fails.
      */
-    connect(url: string): Promise<void>;
+    connectBroadcastChannel(channelName: string): Promise<void>;
     /**
      * # Errors
      * Returns an error if connection fails.
      */
-    connectBroadcastChannel(channelName: string): Promise<void>;
+    connectMessagePortWithOptions(port: MessagePort, config: ConnectOptions): Promise<void>;
     /**
      * # Errors
      * Returns an error if connection fails.
@@ -324,12 +340,12 @@ export class MqttClient {
      * # Errors
      * Returns an error if connection fails.
      */
-    connectMessagePortWithOptions(port: MessagePort, config: ConnectOptions): Promise<void>;
+    connectWithOptions(url: string, config: ConnectOptions): Promise<void>;
     /**
      * # Errors
      * Returns an error if connection fails.
      */
-    connectWithOptions(url: string, config: ConnectOptions): Promise<void>;
+    connect(url: string): Promise<void>;
     destroy(): void;
     /**
      * # Errors
@@ -352,22 +368,22 @@ export class MqttClient {
      * # Errors
      * Returns an error if not connected or publish fails.
      */
-    publish(topic: string, payload: Uint8Array): Promise<void>;
+    publishQos1(topic: string, payload: Uint8Array, callback: Function): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or publish fails.
      */
-    publishQos1(topic: string, payload: Uint8Array, callback: Function): Promise<number>;
+    publishQos2(topic: string, payload: Uint8Array, callback: Function): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or publish fails.
      */
-    publishQos2(topic: string, payload: Uint8Array, callback: Function): Promise<number>;
+    publishWithOptions(topic: string, payload: Uint8Array, options: PublishOptions): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or publish fails.
      */
-    publishWithOptions(topic: string, payload: Uint8Array, options: PublishOptions): Promise<void>;
+    publish(topic: string, payload: Uint8Array): Promise<void>;
     /**
      * # Errors
      * Returns an error if no auth method is set or send fails.
@@ -378,17 +394,17 @@ export class MqttClient {
      * # Errors
      * Returns an error if not connected or subscribe fails.
      */
-    subscribe(topic: string): Promise<number>;
+    subscribeWithCallback(topic: string, callback: Function): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or subscribe fails.
      */
-    subscribeWithCallback(topic: string, callback: Function): Promise<number>;
+    subscribeWithOptions(topic: string, callback: Function, options: SubscribeOptions): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or subscribe fails.
      */
-    subscribeWithOptions(topic: string, callback: Function, options: SubscribeOptions): Promise<number>;
+    subscribe(topic: string): Promise<number>;
     /**
      * # Errors
      * Returns an error if not connected or unsubscribe fails.
@@ -477,6 +493,15 @@ export class Store {
      * Returns an error if the write fails.
      */
     create(entity: string, scope_id: string, data: any, tag?: string | null): Promise<string>;
+    /**
+     * Compare-and-set delete: remove the row only if its server version still
+     * equals `expectedVersion`. Same semantics as `updateIf`.
+     *
+     * # Errors
+     * Returns an error if the argument is malformed, there is no connected
+     * remote, or the broker rejects the write (including version mismatch).
+     */
+    deleteIf(entity: string, id: string, expected_version: number): Promise<void>;
     /**
      * Delete a row. No-op if absent.
      *
@@ -513,20 +538,20 @@ export class Store {
      */
     getChildCount(entity: string, scope_id: string): number;
     /**
-     * Snapshot of all rows for `entity` within `scopeId`. Equivalent to TS
-     * `getSnapshot`.
+     * Snapshot of `entity` within `scopeId` as an object keyed by row id.
      *
      * # Errors
      * Returns an error if the read fails.
      */
-    getSnapshot(entity: string, scope_id: string): any;
+    getSnapshotAsMap(entity: string, scope_id: string): any;
     /**
-     * Snapshot of `entity` within `scopeId` as an object keyed by row id.
+     * Snapshot of all rows for `entity` within `scopeId`. Equivalent to TS
+     * `getSnapshot`.
      *
      * # Errors
      * Returns an error if the read fails.
      */
-    getSnapshotAsMap(entity: string, scope_id: string): any;
+    getSnapshot(entity: string, scope_id: string): any;
     /**
      * Change token for `(scopeId, entity)`: increments on every mutation and on
      * scope load, and resets to `0` when the scope is cleared or replaced by
@@ -570,14 +595,6 @@ export class Store {
      * Returns an error if the store is not initialized.
      */
     isReconnecting(): boolean;
-    /**
-     * List rows of `entity`, optionally filtered/sorted. `filter` is
-     * `{ scopeId?, sort?: [{ field, direction }], projection?: [string] }`.
-     *
-     * # Errors
-     * Returns an error if the read fails or `filter` is malformed.
-     */
-    list(entity: string, filter: any): Promise<any>;
     /**
      * List all root entities across scopes, optionally sorted (`[{ field,
      * direction }]`).
@@ -586,6 +603,14 @@ export class Store {
      * Returns an error if the read fails or `sort` is malformed.
      */
     listRootEntities(sort: any): Promise<any>;
+    /**
+     * List rows of `entity`, optionally filtered/sorted. `filter` is
+     * `{ scopeId?, sort?: [{ field, direction }], projection?: [string] }`.
+     *
+     * # Errors
+     * Returns an error if the read fails or `filter` is malformed.
+     */
+    list(entity: string, filter: any): Promise<any>;
     /**
      * Load a scope's rows into the in-memory cache from caller-supplied data,
      * `{ entity: [records] }`, replacing any currently-loaded scope. Equivalent
@@ -605,21 +630,21 @@ export class Store {
      */
     pendingMutationCount(scope_id: string): Promise<number>;
     /**
-     * Read a single row from the in-memory cache, or `null` if absent.
+     * Read a row straight from durable persistence, bypassing the in-memory
+     * cache. Returns `null` if absent. Falls back to memory when the store has
+     * no persistence configured.
      *
      * # Errors
      * Returns an error if the read fails.
      */
-    read(entity: string, id: string): any;
+    readLocalState(entity: string, id: string): Promise<any>;
     /**
-     * Read a row straight from durable persistence, bypassing the in-memory
-     * cache. Returns `null` if absent. Falls back to memory when the store has
-     * no persistence configured.
+     * Read a single row from the in-memory cache, or `null` if absent.
      *
      * # Errors
      * Returns an error if the read fails.
      */
-    readLocalState(entity: string, id: string): Promise<any>;
+    read(entity: string, id: string): any;
     /**
      * `true` once [`Store::initialize`] has completed.
      */
@@ -701,12 +726,16 @@ export class Store {
      */
     subscribeToScope(scope_id: string, entity: string, callback: Function): any;
     /**
-     * Partial-update a row.
+     * Compare-and-set update: apply `fields` only if the row's server version
+     * still equals `expectedVersion` (from a prior row's `_version`). Returns
+     * the new version. Requires a live remote; rejects with a
+     * `preconditionFailed` error on a stale version.
      *
      * # Errors
-     * Returns an error if the write fails.
+     * Returns an error if the argument is malformed, there is no connected
+     * remote, or the broker rejects the write (including version mismatch).
      */
-    update(entity: string, id: string, fields: any, tag?: string | null): Promise<void>;
+    updateIf(entity: string, id: string, fields: any, expected_version: number): Promise<number>;
     /**
      * Upsert into persistence directly, bypassing memory and remote.
      *
@@ -714,6 +743,13 @@ export class Store {
      * Returns an error if the write fails.
      */
     updateLocalState(entity: string, id: string, fields: any): Promise<void>;
+    /**
+     * Partial-update a row.
+     *
+     * # Errors
+     * Returns an error if the write fails.
+     */
+    update(entity: string, id: string, fields: any, tag?: string | null): Promise<void>;
 }
 
 export class SubscribeOptions {