@usearete/sdk 0.25.0 → 0.25.1

package/README.md

@@ -382,8 +382,11 @@ for await (const update of session.stacks.myStack.views.settlementGame.list.watc
 }
 
 const game = await session.stacks.myStack.views.settlementGame.state.get('game-123');
+const latest = await session.stacks.ore.views.OreRound.latest.getOne();
 ```
 
+`get` and `getOne` open (or reuse) an equivalent subscription, wait for its initial snapshot, and release it. They reject with `InitialDataTimeoutError` after `timeoutMs` (5000 by default; `null` waits forever). `getSync` only reads a subscription that is already active and returns `undefined` when there is none.
+
 Every options object is a protocol v2 query with independent ordered membership. Different windows and filters on the same view can run concurrently, while equivalent normalized queries share one reference-counted wire subscription:
 
 ```ts

package/dist/index.cjs

@@ -444,6 +444,7 @@ class SubscriptionRegistry {
         this.queryStore = queryStore;
         this.subscriptions = new Map();
         this.subscriptionsById = new Map();
+        this.failureListeners = new Set();
     }
     subscribe(query, snapshotEnabled = true) {
         const request = normalizeSubscriptionRequest({
@@ -506,12 +507,30 @@ class SubscriptionRegistry {
             ? this.queryStore.getSnapshot(tracker.subscription.subscriptionId)
             : undefined;
     }
-    handleConnectionState(state) {
+    handleConnectionState(state, message) {
         if (state === 'reconnecting')
             this.queryStore.beginReconnect();
-        if (state === 'error') {
-            this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        if (state !== 'error') {
+            this.connectionError = undefined;
+            return;
         }
+        this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        // Queries still waiting for their first snapshot are not failed above;
+        // one-shot reads learn about the failure here instead of timing out.
+        this.connectionError = new AreteError(message ?? 'Connection failed', 'CONNECTION_ERROR');
+        this.notifyFailure(this.connectionError);
+    }
+    /** The terminal connection failure while the connection is in the `error` state. */
+    getConnectionError() {
+        return this.connectionError;
+    }
+    /**
+     * Called when pending queries can no longer resolve: the connection failed
+     * terminally, or a disconnect cleared every subscription.
+     */
+    onFailure(callback) {
+        this.failureListeners.add(callback);
+        return () => this.failureListeners.delete(callback);
     }
     clear() {
         for (const { subscription } of this.subscriptions.values()) {
@@ -527,6 +546,11 @@ class SubscriptionRegistry {
         }
         this.subscriptions.clear();
         this.subscriptionsById.clear();
+        this.notifyFailure(new AreteError('Subscriptions were cleared by a disconnect', 'CONNECTION_CANCELLED'));
+    }
+    notifyFailure(error) {
+        for (const listener of [...this.failureListeners])
+            listener(error);
     }
     createLease(tracker) {
         let released = false;
@@ -3565,10 +3589,90 @@ function createRichUpdateStream(_storage, subscriptionRegistry, query, keyFilter
     };
 }
 
+/** How long `get` and `getOne` wait for an initial snapshot, as in the Rust and Python SDKs. */
+const DEFAULT_INITIAL_DATA_TIMEOUT_MS = 5000;
+/**
+ * `get` or `getOne` gave up waiting for the initial snapshot: the socket never
+ * delivered it (no connection, a reconnect storm, a server that never
+ * answers). The read's subscription is released before this is thrown.
+ */
+class InitialDataTimeoutError extends AreteError {
+    constructor(view, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for the initial snapshot of view '${view}'`, 'INITIAL_DATA_TIMEOUT', { view, timeoutMs });
+        this.view = view;
+        this.timeoutMs = timeoutMs;
+        this.name = 'InitialDataTimeoutError';
+    }
+}
 function queryOptions(options) {
-    const { schema: _schema, withSnapshot, ...query } = options ?? {};
+    const { schema: _schema, withSnapshot, timeoutMs: _timeoutMs, ...query } = options ?? {};
     return { query, snapshotEnabled: withSnapshot ?? true };
 }
+function resolveTimeout(options) {
+    const timeoutMs = options?.timeoutMs === undefined
+        ? DEFAULT_INITIAL_DATA_TIMEOUT_MS
+        : options.timeoutMs;
+    if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new RangeError('timeoutMs must be a positive finite number or null');
+    }
+    return timeoutMs;
+}
+/**
+ * Open (or reuse) the equivalent subscription, wait until its snapshot has
+ * resolved or its query has failed, and release it. A terminal connection
+ * failure or a disconnect rejects with that reason. Bounded by `timeoutMs`
+ * (`null` waits forever) so a socket that never delivers cannot hang the caller.
+ */
+async function readResolved(registry, query, snapshotEnabled, timeoutMs) {
+    const lease = registry.subscribe(query, snapshotEnabled);
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            let stop = () => { };
+            let timer;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                stop();
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const check = () => {
+                const error = lease.getError();
+                if (error)
+                    finish(error);
+                else if (!lease.getSnapshot().isLoading)
+                    finish();
+                else {
+                    const connectionError = registry.getConnectionError();
+                    if (connectionError)
+                        finish(connectionError);
+                }
+            };
+            check();
+            if (settled)
+                return;
+            const stopChanges = lease.onChange(check);
+            const stopFailures = registry.onFailure(finish);
+            stop = () => {
+                stopChanges();
+                stopFailures();
+            };
+            if (timeoutMs !== null) {
+                timer = setTimeout(() => finish(new InitialDataTimeoutError(query.view, timeoutMs)), timeoutMs);
+            }
+        });
+        return lease.getSnapshot();
+    }
+    finally {
+        lease.release();
+    }
+}
 function serializeViewKeyValue(value, view, field) {
     const location = field === undefined ? `view '${view}'` : `key field '${field}' for view '${view}'`;
     if (typeof value === 'string')
@@ -3619,7 +3723,10 @@ function createTypedStateView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, serializedKey, snapshotEnabled);
         },
         async get(key, options) {
-            return this.getSync(key, options) ?? null;
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, key: wireKey(key), ...query }, snapshotEnabled, timeoutMs);
+            return snapshot.data[0] ?? null;
         },
         getSync(key, options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -3647,7 +3754,14 @@ function createTypedListView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, undefined, snapshotEnabled);
         },
         async get(options) {
-            return this.getSync(options) ?? [];
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, ...query }, snapshotEnabled, timeoutMs);
+            return [...snapshot.data];
+        },
+        async getOne(options) {
+            const items = await this.get({ ...options, take: 1 });
+            return items[0] ?? null;
         },
         getSync(options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -7565,8 +7679,8 @@ let Arete$1 = class Arete {
         this.connection.onFrame((frame) => {
             this.processor.handleFrame(frame);
         });
-        this.connection.onStateChange((state) => {
-            this.subscriptionRegistry.handleConnectionState(state);
+        this.connection.onStateChange((state, error) => {
+            this.subscriptionRegistry.handleConnectionState(state, error);
         });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
         this._queries = this.buildQueries();
@@ -8554,9 +8668,11 @@ exports.Arete = Arete;
 exports.AreteError = AreteError;
 exports.ConnectionManager = ConnectionManager;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+exports.DEFAULT_INITIAL_DATA_TIMEOUT_MS = DEFAULT_INITIAL_DATA_TIMEOUT_MS;
 exports.DEFAULT_MAX_ENTRIES_PER_VIEW = DEFAULT_MAX_ENTRIES_PER_VIEW;
 exports.EXTENSION_API_VERSION = EXTENSION_API_VERSION;
 exports.FrameProcessor = FrameProcessor;
+exports.InitialDataTimeoutError = InitialDataTimeoutError;
 exports.InstructionError = InstructionError;
 exports.MemoryAdapter = MemoryAdapter;
 exports.OPERATION_KIND = OPERATION_KIND;