@econ-v1/rpc 7.2.10 → 7.3.1

package/src/subscription-state.js

@@ -0,0 +1,74 @@
+// @ts-check
+
+/** @typedef {import("./client.js").SubscriptionState} SubscriptionState */
+/** @typedef {{ readonly onState: (state: SubscriptionState) => void, told: boolean }} SubscriptionStateHolder */
+
+/**
+ * One subscription's state and the holders watching it (ADR-039). Every layer that
+ * carries a subscription (a carrier, the managed client, the kernel lease, the RPC
+ * group) keeps one, so they all fold states the same way.
+ *
+ * Each `live` is the next generation, and a `live` reported as "subscribed" after an
+ * earlier one reads "resubscribed": whatever restarted below (a carrier, a kernel)
+ * counts from 1 again, but a holder never sees a generation twice. A repeated state
+ * that is not `live` is not re-sent. A holder that joins when there is a state gets
+ * it on a microtask, unless a transition reached it first.
+ */
+export class SubscriptionStateCell {
+    #generation = 0;
+    /** @type {Set<SubscriptionStateHolder>} */
+    #holders = new Set();
+    /** @type {SubscriptionState | undefined} */
+    #state;
+    get state() {
+        return this.#state;
+    }
+    /**
+     * @param {(state: SubscriptionState) => void} onState
+     * @returns {() => void}
+     */
+    watch(onState) {
+        /** @type {SubscriptionStateHolder} */
+        const holder = { onState, told: false };
+        this.#holders.add(holder);
+        void Promise.resolve().then(() => {
+            if (this.#holders.has(holder) && !holder.told && this.#state !== undefined)
+                tell(holder, this.#state);
+        });
+        return () => {
+            this.#holders.delete(holder);
+        };
+    }
+    /**
+     * @param {SubscriptionState["status"]} status
+     * @param {boolean} [confirmed] ignored unless `live`
+     * @param {SubscriptionState["reason"]} [reason] ignored unless `live`
+     * @returns {void}
+     */
+    report(status, confirmed = false, reason = "subscribed") {
+        if (status === "live") {
+            if (this.#generation++ > 0 && reason === "subscribed")
+                reason = "resubscribed";
+        }
+        else if (this.#state?.status === status)
+            return;
+        /** @type {SubscriptionState} */
+        const state = status === "live"
+            ? { confirmed, generation: this.#generation, reason, status }
+            : { confirmed: false, generation: this.#generation, status };
+        this.#state = state;
+        for (const holder of [...this.#holders])
+            tell(holder, state);
+    }
+}
+
+/** @param {SubscriptionStateHolder} holder @param {SubscriptionState} state */
+function tell(holder, state) {
+    holder.told = true;
+    try {
+        holder.onState(state);
+    }
+    catch {
+        // One holder's failure must not starve the others.
+    }
+}