@abloatai/ablo 0.26.0 → 0.28.0

package/dist/testing/mocks/MockWebSocket.d.ts

@@ -1,12 +1,11 @@
 /**
- * MockWebSocket — Controllable WebSocket for sync engine tests.
- *
- * Simulates the SyncWebSocket event interface without a real connection.
- * Provides methods to inject deltas, simulate disconnection/reconnection,
- * and trigger bootstrap hints.
+ * A controllable WebSocket stand-in for sync engine tests. It reproduces the
+ * event interface of the real connection without opening a socket, so tests
+ * can drive connection changes, deltas, and bootstrap hints by hand.
  */
 import type { SyncActionType } from '../../types/index.js';
-/** Delta shape matching the SyncAction interface */
+import type { BootstrapReason } from '../../wire/bootstrapReason.js';
+/** The shape of a single delta — one change the server pushes to the client. */
 export interface MockDelta {
     id: number;
     modelName: string;
@@ -14,22 +13,28 @@ export interface MockDelta {
     action: SyncActionType;
     data: Record<string, unknown>;
 }
-/** Bootstrap hint from server */
+/**
+ * A hint from the server that the client has fallen too far behind and should
+ * rebuild its data from scratch rather than catch up one delta at a time.
+ */
 export interface MockBootstrapHint {
-    reason: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
+    reason: BootstrapReason;
     tables?: string[];
     staleTables?: string[];
 }
 type EventHandler = (...args: unknown[]) => void;
 /**
- * MockWebSocket provides a controllable event-based interface
- * for testing sync engine components that consume WebSocket events.
+ * A controllable, event-based stand-in for the sync engine's WebSocket
+ * connection. Subscribe with {@link MockWebSocket.on} exactly as production
+ * code does, then use the `simulate*` and `receive*` methods to push
+ * connection changes, deltas, and bootstrap hints. Every event the mock emits
+ * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
  */
 export declare class MockWebSocket {
     private _connected;
     private _sessionError;
     private _listeners;
-    /** Track all emitted events for assertions */
+    /** Every event the mock has emitted, in order, for assertions. */
     readonly emittedEvents: {
         type: string;
         data: unknown;
@@ -38,29 +43,29 @@ export declare class MockWebSocket {
     get sessionError(): boolean;
     on(event: string, handler: EventHandler): () => void;
     private emit;
-    /** Simulate successful connection */
+    /** Fires a successful connection, emitting the `connected` event. */
     simulateConnect(): void;
-    /** Simulate disconnection */
+    /** Drops the connection, emitting the `disconnected` event. */
     simulateDisconnect(): void;
-    /** Simulate reconnection attempt */
+    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
     simulateReconnecting(attempt: number, delay: number): void;
-    /** Simulate session error (401/403) */
+    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
     simulateSessionError(code?: number): void;
-    /** Simulate reconnection failure (max attempts reached) */
+    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
     simulateReconnectFailed(): void;
-    /** Inject a single delta (as if received from server) */
+    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
     receiveDelta(delta: MockDelta): void;
-    /** Inject a batch of deltas */
+    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
     receiveDeltas(deltas: MockDelta[]): void;
-    /** Inject a bootstrap_required hint from server */
+    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
     simulateBootstrapHint(hint: MockBootstrapHint): void;
-    /** Inject a presence update */
+    /** Emits a `presence_update` event carrying the given payload. */
     simulatePresenceUpdate(data: Record<string, unknown>): void;
-    /** Get all events of a specific type */
+    /** Returns the payloads of every emitted event of the given type, in order. */
     getEvents(type: string): unknown[];
-    /** Check if a specific event was emitted */
+    /** Reports whether an event of the given type has been emitted. */
     hasEmitted(type: string): boolean;
-    /** Reset all state */
+    /** Clears connection state, listeners, and the record of emitted events. */
     reset(): void;
 }
 export {};

package/dist/testing/mocks/MockWebSocket.js

@@ -1,19 +1,20 @@
 /**
- * MockWebSocket — Controllable WebSocket for sync engine tests.
- *
- * Simulates the SyncWebSocket event interface without a real connection.
- * Provides methods to inject deltas, simulate disconnection/reconnection,
- * and trigger bootstrap hints.
+ * A controllable WebSocket stand-in for sync engine tests. It reproduces the
+ * event interface of the real connection without opening a socket, so tests
+ * can drive connection changes, deltas, and bootstrap hints by hand.
  */
 /**
- * MockWebSocket provides a controllable event-based interface
- * for testing sync engine components that consume WebSocket events.
+ * A controllable, event-based stand-in for the sync engine's WebSocket
+ * connection. Subscribe with {@link MockWebSocket.on} exactly as production
+ * code does, then use the `simulate*` and `receive*` methods to push
+ * connection changes, deltas, and bootstrap hints. Every event the mock emits
+ * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
  */
 export class MockWebSocket {
     _connected = false;
     _sessionError = false;
     _listeners = new Map();
-    /** Track all emitted events for assertions */
+    /** Every event the mock has emitted, in order, for assertions. */
     emittedEvents = [];
     get connected() {
         return this._connected;
@@ -22,7 +23,7 @@ export class MockWebSocket {
         return this._sessionError;
     }
     // ─────────────────────────────────────────────
-    // Event subscription (matches SyncWebSocket API)
+    // Event subscription (matches the real connection's API)
     // ─────────────────────────────────────────────
     on(event, handler) {
         if (!this._listeners.has(event)) {
@@ -45,28 +46,28 @@ export class MockWebSocket {
     // ─────────────────────────────────────────────
     // Test control: connection lifecycle
     // ─────────────────────────────────────────────
-    /** Simulate successful connection */
+    /** Fires a successful connection, emitting the `connected` event. */
     simulateConnect() {
         this._connected = true;
         this._sessionError = false;
         this.emit('connected');
     }
-    /** Simulate disconnection */
+    /** Drops the connection, emitting the `disconnected` event. */
     simulateDisconnect() {
         this._connected = false;
         this.emit('disconnected');
     }
-    /** Simulate reconnection attempt */
+    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
     simulateReconnecting(attempt, delay) {
         this.emit('reconnecting', { attempt, delay });
     }
-    /** Simulate session error (401/403) */
+    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
     simulateSessionError(code = 401) {
         this._sessionError = true;
         this._connected = false;
         this.emit('session_error', { code });
     }
-    /** Simulate reconnection failure (max attempts reached) */
+    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
     simulateReconnectFailed() {
         this._connected = false;
         this.emit('reconnect_failed');
@@ -74,40 +75,40 @@ export class MockWebSocket {
     // ─────────────────────────────────────────────
     // Test control: delta injection
     // ─────────────────────────────────────────────
-    /** Inject a single delta (as if received from server) */
+    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
     receiveDelta(delta) {
         this.emit('delta', delta);
     }
-    /** Inject a batch of deltas */
+    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
     receiveDeltas(deltas) {
         this.emit('delta_batch', deltas);
     }
     // ─────────────────────────────────────────────
     // Test control: bootstrap hints
     // ─────────────────────────────────────────────
-    /** Inject a bootstrap_required hint from server */
+    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
     simulateBootstrapHint(hint) {
         this.emit('bootstrap_required', hint);
     }
     // ─────────────────────────────────────────────
     // Test control: presence
     // ─────────────────────────────────────────────
-    /** Inject a presence update */
+    /** Emits a `presence_update` event carrying the given payload. */
     simulatePresenceUpdate(data) {
         this.emit('presence_update', data);
     }
     // ─────────────────────────────────────────────
     // Assertions
     // ─────────────────────────────────────────────
-    /** Get all events of a specific type */
+    /** Returns the payloads of every emitted event of the given type, in order. */
     getEvents(type) {
         return this.emittedEvents.filter((e) => e.type === type).map((e) => e.data);
     }
-    /** Check if a specific event was emitted */
+    /** Reports whether an event of the given type has been emitted. */
     hasEmitted(type) {
         return this.emittedEvents.some((e) => e.type === type);
     }
-    /** Reset all state */
+    /** Clears connection state, listeners, and the record of emitted events. */
     reset() {
         this._connected = false;
         this._sessionError = false;