@spfn/core 0.3.0-beta.27 → 0.3.0-beta.29

package/dist/state/client.d.ts

@@ -51,9 +51,10 @@ interface StateFrame<V = unknown, D = unknown> {
     data?: D;
 }
 /**
- * What the client holds for one `(id, key)`: the latest frame and whether the
- * server still serves it. A state the server stopped serving before any value
- * arrived is `{ status: 'revoked' }` alone.
+ * What the client holds for one `(id, key)`: the frame that last changed
+ * `status`, `value` or `data` — its `at` is that read's, not the newest `at`
+ * the client has seen — and whether the server still serves it. A state the
+ * server stopped serving before any value arrived is `{ status: 'revoked' }` alone.
  */
 type StateEntry<V = unknown, D = unknown> = Readonly<StateFrame<V, D> & {
     status: 'ready' | 'revoked';
@@ -65,7 +66,36 @@ type StateEntry<V = unknown, D = unknown> = Readonly<StateFrame<V, D> & {
 }>;
 /** Called after the entry of a subscribed `(id, key)` changed. */
 type StateListener = () => void;
-interface StateClientConfig {
+/**
+ * Whether the client's stream is live. `'reconnecting'` until a stream opens and while the SSE
+ * client retries a dropped one — `attempt` is its count, `0` before its first retry;
+ * `'failed'` when the retries are exhausted (the SSE client's `maxReconnectAttempts`, the
+ * client's `maxRetries` for the first snapshot), until `retry()`, a new `subscribe` or `online`.
+ */
+type ConnectionStatus = {
+    status: 'connected';
+} | {
+    status: 'reconnecting';
+    attempt: number;
+} | {
+    status: 'failed';
+};
+/** Called with the new status after the client's connection status changed. */
+type ConnectionListener = (status: ConnectionStatus) => void;
+/**
+ * The snapshot a server render read, for a client to start from (`StateClientConfig.initial`).
+ * Pass what `api.getStates` answered: a snapshot whose manifest names a state the server does not
+ * serve keeps the stream from opening, as the SSE handler refuses that event. The router type
+ * parameter (`StateClientInitial<typeof states>`, `createStateClient<typeof states>`) is what types
+ * `snapshot`; without it the client is untyped, as before.
+ */
+interface StateClientInitial<TStates extends AnyStateRouter = any> {
+    /** What `api.getStates` (or the snapshot route) answered for the render. */
+    snapshot: StatesSnapshot<TStates['states']>;
+    /** The query that snapshot was read with; keyed entries are stored under its key. @default {} */
+    query?: Record<string, string>;
+}
+interface StateClientConfig<TStates extends AnyStateRouter = any> {
     /**
      * The SSE client the stream is opened on — `createAuthSSEClient()` for an
      * authenticated app. Give the state client its own: an `SSEClient` holds
@@ -88,6 +118,21 @@ interface StateClientConfig {
      * @default 3000
      */
     retryDelay?: number;
+    /**
+     * How many times a failed first snapshot is read again before the client
+     * gives up: the status turns `'failed'` and no retry is set, until
+     * `retry()`, a new `subscribe` or `online`. The first read is not a retry.
+     * `0` retries until the snapshot succeeds.
+     * @default 0
+     */
+    maxRetries?: number;
+    /**
+     * The snapshot the server rendered with. The client installs its manifest
+     * and applies its states at construction, so `current()` answers at once
+     * and the first `subscribe` opens the stream without reading the snapshot
+     * first. The stream's open still re-reads it.
+     */
+    initial?: StateClientInitial<TStates>;
 }
 /**
  * The browser side of a state router: one store per `(id, key)`, one SSE
@@ -99,8 +144,8 @@ interface StateClient<TStates extends AnyStateRouter> {
     /** Read every state the query names a key for, and the manifest; each entry is applied and the snapshot returned. */
     snapshot(query?: Record<string, string>): Promise<StatesSnapshot<TStates['states']>>;
     /**
-     * Watch one `(id, key)`. The first subscriber reads the snapshot, then opens
-     * the stream. A key whose fields are not the state's goes to `onError` once
+     * Watch one `(id, key)`. The first subscriber reads the snapshot — unless
+     * the client was built with `initial` — then opens the stream. A key whose fields are not the state's goes to `onError` once
      * the manifest is known. Returns the unsubscribe.
      */
     subscribe<Id extends StateId<TStates>>(id: Id, ...args: [...key: StateKeyArgs<TStates, Id>, listener: StateListener]): () => void;
@@ -108,7 +153,22 @@ interface StateClient<TStates extends AnyStateRouter> {
     write<Id extends WritableStateId<TStates>>(id: Id, input: StateCatalog<TStates>[Id]['input'], ...key: StateKeyArgs<TStates, Id>): Promise<StateFrameOf<TStates, Id>>;
     /** The entry held for `(id, key)`, the same object until it changes. */
     current<Id extends StateId<TStates>>(id: Id, ...key: StateKeyArgs<TStates, Id>): StateEntry<StateCatalog<TStates>[Id]['value'], StateCatalog<TStates>[Id]['data']> | undefined;
-    /** Close the stream and drop every listener. */
+    /** The connection status, a frozen object: the same reference until it changes. */
+    connection(): ConnectionStatus;
+    /**
+     * Call `listener` with the new status on every change of `connection()`.
+     * Returns the unsubscribe (idempotent).
+     */
+    subscribeConnection(listener: ConnectionListener): () => void;
+    /**
+     * Restart now when `'failed'` or `'reconnecting'`: the first snapshot is
+     * read again, its retry count reset, or the stream reopened. A no-op when
+     * `'connected'`, while the first snapshot is in flight, or with nothing
+     * subscribed — so after `close()`, until a new `subscribe`, which `retry()`
+     * then restarts as before. `online` is not listened to again after `close()`.
+     */
+    retry(): void;
+    /** Close the stream, drop every listener and stop listening to `online`. */
     close(): void;
 }
 
@@ -135,10 +195,12 @@ interface StateClient<TStates extends AnyStateRouter> {
 
 /**
  * Build the client for `typeof states`. The first subscription (or call)
- * reads the snapshot, whose manifest names every state; the stream then
+ * reads the snapshot, whose manifest names every state — or takes it from
+ * `initial`, the snapshot the server rendered with; the stream then
  * requests every state event — the server's `grant` can only activate an
- * event the connection requested.
+ * event the connection requested. The router type parameter is what types
+ * `initial.snapshot`; without it the client is untyped, as before.
  */
-declare function createStateClient<TStates extends AnyStateRouter>(config: StateClientConfig): StateClient<TStates>;
+declare function createStateClient<TStates extends AnyStateRouter>(config: StateClientConfig<TStates>): StateClient<TStates>;
 
-export { type AnyStateRouter, type InferStateData, type StateCatalog, type StateClient, type StateClientConfig, type StateEntry, type StateFrame, type StateFrameOf, type StateId, type StateKeyArgs, type StateListener, type WritableStateId, createStateClient };
+export { type AnyStateRouter, type ConnectionListener, type ConnectionStatus, type InferStateData, type StateCatalog, type StateClient, type StateClientConfig, type StateClientInitial, type StateEntry, type StateFrame, type StateFrameOf, type StateId, type StateKeyArgs, type StateListener, type WritableStateId, createStateClient };

package/dist/state/client.js

@@ -20,14 +20,11 @@ function sameJson(a, b) {
   const bRecord = b;
   return aKeys.length === Object.keys(b).length && aKeys.every((field) => field in bRecord && sameJson(a[field], bRecord[field]));
 }
-function supersedes(current, arrival) {
-  if (current?.at === void 0 || arrival.at > current.at) {
-    return true;
-  }
-  if (arrival.at < current.at) {
-    return false;
-  }
-  return !sameJson(current.value, arrival.value) || !sameJson(current.data, arrival.data);
+function isOlder(stamp, arrival) {
+  return stamp !== void 0 && arrival.at < stamp;
+}
+function changes(current, arrival) {
+  return current?.at === void 0 || !sameJson(current.value, arrival.value) || !sameJson(current.data, arrival.data);
 }
 function entryOf(frame, status) {
   const { at, value, data } = frame;
@@ -35,6 +32,12 @@ function entryOf(frame, status) {
 }
 var StateStore = class {
   entries = /* @__PURE__ */ new Map();
+  /**
+   * The newest `at` seen per slot, kept apart from the entry: an arrival
+   * that changes nothing still orders the ones after it, while the entry's
+   * `at` stays the `at` of the read that last changed the value.
+   */
+  stamps = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Map();
   /**
    * The slots the server stopped serving, with the generation of the
@@ -52,12 +55,16 @@ var StateStore = class {
   }
   /**
    * Apply an arrival: the value under the ordering rule, the status from the
-   * revoked mark. Listeners hear only an applied change.
+   * revoked mark. Listeners hear only a changed status, value or data.
    */
   apply(slot, frame) {
     const current = this.entries.get(slot);
     const status = this.revoked.has(slot) ? "revoked" : "ready";
-    if (supersedes(current, frame)) {
+    const ordered = !isOlder(this.stamps.get(slot), frame);
+    if (ordered) {
+      this.stamps.set(slot, frame.at);
+    }
+    if (ordered && changes(current, frame)) {
       this.replace(slot, entryOf(frame, status));
     } else if (current.status !== status) {
       this.replace(slot, entryOf(current, status));
@@ -113,9 +120,21 @@ function notify(slot, listener) {
 }
 
 // src/state/client.ts
+var CONNECTED = Object.freeze({ status: "connected" });
+var FAILED = Object.freeze({ status: "failed" });
+var STARTING = Object.freeze({ status: "reconnecting", attempt: 0 });
+function reconnecting(attempt) {
+  return attempt === 0 ? STARTING : Object.freeze({ status: "reconnecting", attempt });
+}
+function sameStatus(a, b) {
+  return a.status === b.status && a.attempt === b.attempt;
+}
 function routeName(method, id) {
   return `${method}${id[0].toUpperCase()}${id.slice(1)}State`;
 }
+function stateEventName(id) {
+  return `state.${id}.changed`;
+}
 function carries(query, key) {
   return Object.entries(key).every(([field, value]) => query[field] === value);
 }
@@ -130,6 +149,12 @@ var BrowserStateClient = class {
     this.config = config;
     this.api = createApi(config.api);
     this.reportError = config.onError ?? ((error) => console.error("[state] A refresh failed:", error));
+    if (config.initial) {
+      this.hydrate(config.initial);
+    }
+    if (typeof globalThis.addEventListener === "function") {
+      globalThis.addEventListener("online", this.onOnline);
+    }
   }
   store = new StateStore();
   api;
@@ -139,6 +164,11 @@ var BrowserStateClient = class {
   manifestRead;
   stream;
   syncQueued = false;
+  status = STARTING;
+  connectionListeners = /* @__PURE__ */ new Set();
+  onOnline = () => this.retry();
+  /** The retries of the first snapshot since its last start, against `maxRetries`. */
+  retries = 0;
   /** The lifetime whose subscriptions wait on the first snapshot — its read in flight, or its retry timer set. */
   waitingLifetime;
   retryTimer;
@@ -191,13 +221,70 @@ var BrowserStateClient = class {
   current(id, key) {
     return this.store.current(this.slot(id, key));
   }
+  connection() {
+    return this.status;
+  }
+  subscribeConnection(listener) {
+    const notify2 = (status) => listener(status);
+    this.connectionListeners.add(notify2);
+    return () => {
+      this.connectionListeners.delete(notify2);
+    };
+  }
+  /**
+   * Restart what gave up or is still retrying, now: the first snapshot
+   * while the manifest is unknown, else the stream — a new `sse.subscribe`,
+   * whose attempt count starts at 0. Nothing to do when connected or with
+   * nothing watched — so after `close()`, until a new `subscribe`.
+   */
+  retry() {
+    if (this.status === CONNECTED || this.watched.size === 0) {
+      return;
+    }
+    if (this.manifest) {
+      this.openStream(this.streamQuery());
+    } else {
+      this.rereadManifest();
+    }
+  }
   close() {
     this.lifetime++;
     clearTimeout(this.retryTimer);
     this.retryTimer = void 0;
+    this.retries = 0;
     this.closeStream();
     this.watched.clear();
     this.store.clearListeners();
+    this.connectionListeners.clear();
+    this.status = STARTING;
+    if (typeof globalThis.removeEventListener === "function") {
+      globalThis.removeEventListener("online", this.onOnline);
+    }
+  }
+  /** The status is `next` from now; each connection listener hears it, a throwing one logged. */
+  setConnection(next) {
+    if (sameStatus(next, this.status)) {
+      return;
+    }
+    this.status = next;
+    for (const listener of [...this.connectionListeners]) {
+      try {
+        listener(next);
+      } catch (error) {
+        console.warn("[state] A connection listener threw:", error);
+      }
+    }
+  }
+  /**
+   * Start from the snapshot the server rendered with: its manifest, then
+   * each state present, as a read snapshot applies them, under generation 0
+   * — no connection yet. Nothing is marked `'revoked'`: nothing is watched,
+   * and an omission in the render's snapshot is not a denial by the stream.
+   */
+  hydrate(initial) {
+    const snapshot = initial.snapshot;
+    this.installManifest(snapshot.manifest);
+    this.applyPresent(snapshot, initial.query ?? {}, this.tag());
   }
   slot(id, key) {
     return StateStore.slot(id, stableKey(key));
@@ -282,16 +369,23 @@ var BrowserStateClient = class {
    * generation alone — a frame or a write answer of the new connection may
    * land first with a newer `at` — and the ordering rule decides only the value.
    */
-  serve(slot, frame, tag) {
-    if ((this.store.revokedBy(slot) ?? Infinity) < tag.generation) {
+  serve(slot, frame, generation) {
+    if ((this.store.revokedBy(slot) ?? Infinity) < generation) {
       this.store.allow(slot);
     }
     this.store.apply(slot, frame);
   }
-  /** A state present is served, under the generation rule of `serve`. */
+  /**
+   * A state present is served, under the generation rule of `serve`. A state
+   * the manifest does not describe, or a keyed one whose key fields the query
+   * lacks, is skipped: the server never serves either, but a hand-built
+   * `initial` might.
+   */
   applyPresent(snapshot, query, tag) {
     for (const [id, result] of Object.entries(snapshot.states)) {
-      this.serve(this.slot(id, this.keyIn(id, query)), { at: snapshot.at, ...result }, tag);
+      if (this.manifest[id]?.key.every((field) => field in query)) {
+        this.serve(this.slot(id, this.keyIn(id, query)), { at: snapshot.at, ...result }, tag.generation);
+      }
     }
   }
   /**
@@ -318,7 +412,9 @@ var BrowserStateClient = class {
     } else {
       this.watched.delete(slot);
     }
-    this.queueSync();
+    if (delta === 1 || this.watched.size === 0 || this.status !== FAILED) {
+      this.queueSync();
+    }
   }
   /**
    * One stream for the client, its query the union of the subscribed keys.
@@ -337,10 +433,15 @@ var BrowserStateClient = class {
   /**
    * Until the manifest is known, subscriptions wait for the first snapshot;
    * the stream opens after it, never before — its `events=` comes from it.
+   * A client built with `initial` knows it from the start. With nothing
+   * watched the stream closes, the retry count starts over for the next
+   * wait, and the status is the start value: no stream, nothing answered.
    */
   sync() {
     if (this.watched.size === 0) {
+      this.retries = 0;
       this.closeStream();
+      this.setConnection(STARTING);
       return;
     }
     if (!this.manifest) {
@@ -348,7 +449,7 @@ var BrowserStateClient = class {
       return;
     }
     const query = this.streamQuery();
-    if (this.stream?.text !== stableKey(query)) {
+    if (this.stream?.failed || this.stream?.text !== stableKey(query)) {
       this.openStream(query);
     }
   }
@@ -356,13 +457,18 @@ var BrowserStateClient = class {
    * One waiter per lifetime on the first snapshot. A failure goes to
    * `onError`, and the read is retried after `retryDelay` — the stream that
    * would reconnect on its own does not exist yet. A retry stops on
-   * `close()` or when nothing is watched (`sync` closes instead).
+   * `close()`, when nothing is watched (`sync` closes instead), or after
+   * `maxRetries`; a wait started after that last one restarts the count.
    */
   awaitManifest() {
     const lifetime = this.lifetime;
     if (this.waitingLifetime === lifetime) {
       return;
     }
+    if (this.status === FAILED) {
+      this.retries = 0;
+      this.setConnection(STARTING);
+    }
     this.waitingLifetime = lifetime;
     this.ensureManifest().then(
       () => lifetime === this.lifetime && this.resync(),
@@ -379,14 +485,40 @@ var BrowserStateClient = class {
     this.waitingLifetime = void 0;
     this.sync();
   }
-  /** Read the first snapshot again after `retryDelay`, as the SSE client reconnects a dropped stream. */
+  /**
+   * Read the first snapshot again after `retryDelay`, as the SSE client
+   * reconnects a dropped stream — or, with `maxRetries` spent, give up:
+   * `'failed'`, no timer, no wait.
+   */
   retryLater() {
+    const maxRetries = this.config.maxRetries ?? 0;
+    if (maxRetries > 0 && this.retries >= maxRetries) {
+      this.waitingLifetime = void 0;
+      this.setConnection(FAILED);
+      return;
+    }
+    this.retries++;
     this.retryTimer = setTimeout(() => {
       this.retryTimer = void 0;
       this.resync();
     }, this.config.retryDelay ?? 3e3);
     this.retryTimer.unref?.();
   }
+  /**
+   * `retry()` before the manifest: the count starts over and the first
+   * snapshot is read now, its pending timer cleared. A read in flight is
+   * already the retry; it is not doubled.
+   */
+  rereadManifest() {
+    this.retries = 0;
+    if (this.waitingLifetime === this.lifetime && this.retryTimer === void 0) {
+      return;
+    }
+    clearTimeout(this.retryTimer);
+    this.retryTimer = void 0;
+    this.setConnection(STARTING);
+    this.resync();
+  }
   /**
    * Every subscribed key's fields; one connection carries one value per
    * field, so on a conflict the latest subscribed key wins. The keys it
@@ -399,33 +531,96 @@ var BrowserStateClient = class {
    * Open (or reopen) the stream. `events` is every state of the manifest, in
    * its order, never only the subscribed ones: a state subscribed later would
    * otherwise be unrequested, and the server's `grant` cannot activate it.
+   * Unless connected, the status is `'reconnecting'` 0 until it opens: a
+   * new subscription counts its attempts from 0. A reopen on a key change
+   * while connected stays `'connected'`.
    */
   openStream(query) {
     this.closeStream();
+    if (this.status !== CONNECTED) {
+      this.setConnection(STARTING);
+    }
     const ids = Object.keys(this.manifest);
-    const stream = { query, text: stableKey(query), generation: 0, close: () => void 0 };
+    const stream = { query, text: stableKey(query), generation: 0, closedByClient: false, failed: false, close: () => void 0 };
     stream.close = this.config.sse.subscribe({
-      events: ids.map((id) => `state.${id}.changed`),
-      handlers: Object.fromEntries(ids.map((id) => [`state.${id}.changed`, (frame) => this.onFrame(id, frame)])),
+      events: ids.map(stateEventName),
+      handlers: Object.fromEntries(ids.map((id) => [stateEventName(id), (frame) => this.onFrame(id, frame, stream)])),
       query,
-      // Every open — the first, a reconnect, a reopen on a key change — re-reads the
-      // snapshot. A frame sent while no stream was open is lost, whether its key
-      // changed or not; the snapshot read after the open covers that gap.
       onOpen: () => {
         stream.generation = ++this.generation;
-        this.refresh(query);
+        this.streamStatus(stream, CONNECTED);
       },
+      onReconnect: (attempt) => this.streamStatus(stream, reconnecting(attempt)),
+      onClose: () => this.onStreamClose(stream),
+      onConnected: (connected) => this.onConnected(connected, stream),
       onSubscriptionChange: (change) => this.onSubscriptionChange(change, stream)
     });
     this.stream = stream;
   }
+  /** Flagged first: the SSE client fires `onClose` on this teardown too, and it is no failure. */
   closeStream() {
-    this.stream?.close();
-    this.stream = void 0;
+    if (this.stream) {
+      this.stream.closedByClient = true;
+      this.stream.close();
+      this.stream = void 0;
+    }
+  }
+  /** The status of a callback of `stream`, when no other stream replaced it. */
+  streamStatus(stream, status) {
+    if (stream === this.stream) {
+      this.setConnection(status);
+    }
+  }
+  /**
+   * The SSE client fires `onClose` on every teardown; one the client did
+   * not start is the reconnect attempts exhausted: `'failed'`, and the
+   * stream counts as absent for the next `sync`.
+   */
+  onStreamClose(stream) {
+    if (!stream.closedByClient && stream === this.stream) {
+      stream.failed = true;
+      this.setConnection(FAILED);
+    }
+  }
+  /**
+   * Every connection — the first, a reconnect, a reopen on a key change —
+   * must cover the frames sent while no stream was open. The server says in
+   * `connected` which states it served their current frame right after it;
+   * the snapshot is read only when one it did not serve is neither denied
+   * nor served — or when the server predates `initial`. A denied state the
+   * client watches is `'revoked'`, as an omission from that snapshot would
+   * be. A connection already replaced is ignored.
+   */
+  onConnected(connected, stream) {
+    if (stream !== this.stream || stream.generation !== this.generation) {
+      return;
+    }
+    const denied = new Set(connected.deniedEvents);
+    const served = new Set(connected.initial ?? []);
+    const unserved = Object.keys(this.manifest).map(stateEventName).filter((name) => !denied.has(name) && !served.has(name));
+    this.revokeDenied(denied, stream);
+    if (connected.initial && unserved.length === 0) {
+      this.readShadowedKeys(stream.query);
+    } else {
+      this.refresh(stream.query);
+    }
+  }
+  /** Each watched state the connection denies, on the key it carries, marked `'revoked'` by it. */
+  revokeDenied(denied, stream) {
+    for (const id of Object.keys(this.manifest)) {
+      const slot = this.slot(id, this.keyIn(id, stream.query));
+      if (denied.has(stateEventName(id)) && this.watched.has(slot)) {
+        this.store.revoke(slot, stream.generation);
+      }
+    }
   }
   /** The snapshot for the stream's query, and one read for each subscribed key the query shadows. */
   refresh(query) {
     this.readSnapshot(query, this.tag()).catch(this.reportError);
+    this.readShadowedKeys(query);
+  }
+  /** One read for each subscribed key the query shadows: the stream serves one key per field. */
+  readShadowedKeys(query) {
     for (const watch of this.watched.values()) {
       if (watch.key && !carries(query, watch.key)) {
         this.readShadowed(watch.id, watch.key, this.tag()).catch(this.reportError);
@@ -438,13 +633,18 @@ var BrowserStateClient = class {
    */
   async readShadowed(id, key, tag) {
     const frame = await this.api[routeName("get", id)].call({ query: key });
-    this.serve(this.slot(id, key), frame, tag);
+    this.serve(this.slot(id, key), frame, tag.generation);
   }
-  /** A frame for a key nobody here subscribed is dropped — the server's filter is the first guard, this the second. */
-  onFrame(id, frame) {
+  /**
+   * A frame for a key nobody here subscribed is dropped — the server's filter
+   * is the first guard, this the second. A frame is served under its
+   * connection's generation: the server sends one only on a connection that
+   * allows the state, so a newer connection's frame lifts an older revoke.
+   */
+  onFrame(id, frame, stream) {
     const slot = this.slot(id, frame.key);
     if (this.watched.has(slot)) {
-      this.store.apply(slot, frame);
+      this.serve(slot, frame, stream.generation);
     }
   }
   /**