@spfn/core 0.3.0-beta.3 → 0.3.0-beta.31

package/dist/state/client.js

@@ -0,0 +1,678 @@
+import { createApi } from '@spfn/core/nextjs';
+
+// src/state/client.ts
+
+// src/state/client-store.ts
+function stableKey(key) {
+  if (!key) {
+    return "";
+  }
+  return JSON.stringify(Object.keys(key).sort().map((field) => [field, key[field]]));
+}
+function sameJson(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) {
+    return false;
+  }
+  const aKeys = Object.keys(a);
+  const bRecord = b;
+  return aKeys.length === Object.keys(b).length && aKeys.every((field) => field in bRecord && sameJson(a[field], bRecord[field]));
+}
+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;
+  return Object.freeze(data === void 0 ? { at, value, status } : { at, value, data, 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
+   * connection that said so. Kept apart from the entries: a revoke can
+   * arrive before the slot has a value, and an arrival afterwards supplies
+   * the value without clearing the mark.
+   */
+  revoked = /* @__PURE__ */ new Map();
+  /** The store slot of `(id, key)`. */
+  static slot(id, keyText) {
+    return `${id}\0${keyText}`;
+  }
+  current(slot) {
+    return this.entries.get(slot);
+  }
+  /**
+   * Apply an arrival: the value under the ordering rule, the status from the
+   * 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";
+    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));
+    }
+  }
+  /** Mark `slot` revoked by the connection of `generation`; its value, if any, is kept. */
+  revoke(slot, generation) {
+    this.revoked.set(slot, generation);
+    const entry = this.entries.get(slot);
+    if (entry?.status !== "revoked") {
+      this.replace(slot, Object.freeze(entry ? { ...entry, status: "revoked" } : { status: "revoked" }));
+    }
+  }
+  /** The generation of the connection that revoked `slot`, or `undefined` while it is served. */
+  revokedBy(slot) {
+    return this.revoked.get(slot);
+  }
+  /** Clear the revoked mark; the next arrival for `slot` is `'ready'`. */
+  allow(slot) {
+    this.revoked.delete(slot);
+  }
+  listen(slot, listener) {
+    const set = this.listeners.get(slot) ?? /* @__PURE__ */ new Set();
+    set.add(listener);
+    this.listeners.set(slot, set);
+  }
+  unlisten(slot, listener) {
+    const set = this.listeners.get(slot);
+    if (listener) {
+      set?.delete(listener);
+    }
+    if (!listener || set?.size === 0) {
+      this.listeners.delete(slot);
+    }
+  }
+  clearListeners() {
+    this.listeners.clear();
+  }
+  /** Replace the entry and notify; a throwing listener is logged and does not stop the others. */
+  replace(slot, entry) {
+    this.entries.set(slot, entry);
+    for (const listener of [...this.listeners.get(slot) ?? []]) {
+      notify(slot, listener);
+    }
+  }
+};
+function notify(slot, listener) {
+  try {
+    listener();
+  } catch (error) {
+    console.warn(`[state] A listener of state "${slot.split("\0")[0]}" threw:`, error);
+  }
+}
+
+// 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);
+}
+function sortedFields(fields) {
+  return [...fields].sort().join(", ");
+}
+function createStateClient(config) {
+  return new BrowserStateClient(config);
+}
+var BrowserStateClient = class {
+  constructor(config) {
+    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;
+  watched = /* @__PURE__ */ new Map();
+  reportError;
+  manifest;
+  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;
+  /** Bumped by `close()`: a snapshot started before it is discarded. */
+  lifetime = 0;
+  /** Bumped on every connection open; tags the snapshot read for it. */
+  generation = 0;
+  /** Bumped on every automatic read and every grant, to tell which came first. */
+  clock = 0;
+  /** The clock at the latest grant of each slot. */
+  grants = /* @__PURE__ */ new Map();
+  async get(id, key) {
+    await this.requireManifest();
+    const frame = await this.api[routeName("get", id)].call(key ? { query: key } : {});
+    this.store.apply(this.slot(id, key), frame);
+    return frame;
+  }
+  async write(id, input, key) {
+    if (!(await this.requireManifest())[id]?.write) {
+      throw new Error(`State client: state "${id}" declares no .write(), so it has no write route.`);
+    }
+    const frame = await this.api[routeName("put", id)].call({ body: input, ...key ? { query: key } : {} });
+    this.store.apply(this.slot(id, key), frame);
+    return frame;
+  }
+  snapshot(query = this.streamQuery()) {
+    return this.readSnapshot(query, this.tag());
+  }
+  subscribe(id, ...args) {
+    const listener = args[args.length - 1];
+    const key = args.length === 2 ? args[0] : void 0;
+    const refusal = this.manifest && this.refusal(id, key);
+    if (refusal) {
+      this.reportError(refusal);
+      return () => void 0;
+    }
+    const notify2 = () => listener();
+    const slot = this.slot(id, key);
+    this.store.listen(slot, notify2);
+    this.watch(slot, id, key, 1);
+    let live = true;
+    return () => {
+      if (live) {
+        live = false;
+        this.store.unlisten(slot, notify2);
+        this.watch(slot, id, key, -1);
+      }
+    };
+  }
+  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));
+  }
+  tag() {
+    return { generation: this.generation, tick: ++this.clock };
+  }
+  /** The key of state `id` the query names; `undefined` for a keyless state. */
+  keyIn(id, query) {
+    const fields = this.manifest[id].key;
+    return fields.length ? Object.fromEntries(fields.map((field) => [field, query[field]])) : void 0;
+  }
+  /** Why the manifest refuses `subscribe(id, key)` — an unknown id, or key fields not the state's. */
+  refusal(id, key) {
+    const state = this.manifest[id];
+    if (!state) {
+      return new Error(`State client: the server's manifest has no state "${id}".`);
+    }
+    const expected = sortedFields(state.key);
+    const given = sortedFields(Object.keys(key ?? {}));
+    return expected === given ? void 0 : new Error(`State client: state "${id}" takes the key fields [${expected}], given [${given}].`);
+  }
+  /** The first snapshot, read once however many callers wait for it. */
+  ensureManifest() {
+    if (this.manifest) {
+      return Promise.resolve();
+    }
+    this.manifestRead ??= this.snapshot().then(() => void 0).finally(() => {
+      this.manifestRead = void 0;
+    });
+    return this.manifestRead;
+  }
+  /** The manifest for a call the app made; one whose wait outlived `close()` is refused. */
+  async requireManifest() {
+    await this.ensureManifest();
+    if (!this.manifest) {
+      throw new Error("State client: the client was closed while the first snapshot was in flight.");
+    }
+    return this.manifest;
+  }
+  /**
+   * Read the snapshot and apply it: the manifest first — `keyIn` and the
+   * key checks need it — then each state present, then each watched state
+   * it omits. A snapshot that resolves after `close()` is discarded.
+   */
+  async readSnapshot(query, tag) {
+    const lifetime = this.lifetime;
+    const snapshot = await this.api.getStates.call({ query });
+    if (lifetime === this.lifetime) {
+      this.installManifest(snapshot.manifest);
+      this.applyPresent(snapshot, query, tag);
+      this.applyOmitted(snapshot, query, tag);
+    }
+    return snapshot;
+  }
+  /**
+   * The manifest is static; the first one stays. Subscriptions made before
+   * it are checked now, and the stream opens for those it accepts —
+   * whichever call (`subscribe`, `get`, `write`, `snapshot`) brought it.
+   */
+  installManifest(manifest) {
+    if (this.manifest) {
+      return;
+    }
+    this.manifest = manifest;
+    for (const [slot, watch] of this.watched) {
+      const refusal = this.refusal(watch.id, watch.key);
+      if (refusal) {
+        this.watched.delete(slot);
+        this.store.unlisten(slot);
+        this.reportError(refusal);
+      }
+    }
+    if (this.watched.size > 0) {
+      this.queueSync();
+    }
+  }
+  /**
+   * An arrival from a read started for the connection of `tag`: a
+   * connection newer than the one that revoked the slot lifts the mark, an
+   * older or the same connection leaves `'revoked'`. The lift is by
+   * 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, 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
+   * 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)) {
+      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);
+      }
+    }
+  }
+  /**
+   * A watched state whose key the query carried (or a keyless one) and that
+   * the snapshot omits is not served to this subject: `'revoked'`. Not when
+   * a newer connection exists, nor when a grant came after the read started.
+   */
+  applyOmitted(snapshot, query, tag) {
+    if (tag.generation !== this.generation) {
+      return;
+    }
+    for (const [slot, watch] of this.watched) {
+      const asked = !watch.key || carries(query, watch.key);
+      const grantedSince = (this.grants.get(slot) ?? 0) > tag.tick;
+      if (asked && !(watch.id in snapshot.states) && !grantedSince) {
+        this.store.revoke(slot, tag.generation);
+      }
+    }
+  }
+  watch(slot, id, key, delta) {
+    const count = (this.watched.get(slot)?.count ?? 0) + delta;
+    if (count > 0) {
+      this.watched.set(slot, { id, key, count });
+    } else {
+      this.watched.delete(slot);
+    }
+    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.
+   * Batched to the end of the task, so components mounting together (or a
+   * StrictMode unmount-remount) open the stream once.
+   */
+  queueSync() {
+    if (!this.syncQueued) {
+      this.syncQueued = true;
+      queueMicrotask(() => {
+        this.syncQueued = false;
+        this.sync();
+      });
+    }
+  }
+  /**
+   * 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) {
+      this.awaitManifest();
+      return;
+    }
+    const query = this.streamQuery();
+    if (this.stream?.failed || this.stream?.text !== stableKey(query)) {
+      this.openStream(query);
+    }
+  }
+  /**
+   * 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()`, 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(),
+      (error) => {
+        this.reportError(error);
+        if (lifetime === this.lifetime) {
+          this.retryLater();
+        }
+      }
+    );
+  }
+  /** The wait is over; `sync` opens the stream, or waits again when a closed lifetime's read was discarded. */
+  resync() {
+    this.waitingLifetime = void 0;
+    this.sync();
+  }
+  /**
+   * 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
+   * shadows are read once when the stream opens and get no frames.
+   */
+  streamQuery() {
+    return Object.assign({}, ...[...this.watched.values()].map((watch) => watch.key ?? {}));
+  }
+  /**
+   * 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, closedByClient: false, failed: false, close: () => void 0 };
+    stream.close = this.config.sse.subscribe({
+      events: ids.map(stateEventName),
+      handlers: Object.fromEntries(ids.map((id) => [stateEventName(id), (frame) => this.onFrame(id, frame, stream)])),
+      query,
+      onOpen: () => {
+        stream.generation = ++this.generation;
+        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() {
+    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);
+      }
+    }
+  }
+  /**
+   * A shadowed key gets no frames, no grant and no snapshot entry; the
+   * server answering its own read is the evidence of access instead.
+   */
+  async readShadowed(id, key, tag) {
+    const frame = await this.api[routeName("get", id)].call({ query: key });
+    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. 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.serve(slot, frame, stream.generation);
+    }
+  }
+  /**
+   * A revoke or a grant concerns the key the connection carries — the
+   * server scopes both by the connect query — and so does the read after a
+   * grant. Revoked: the entry keeps its value, marked `'revoked'`, until a
+   * grant. Granted: the mark is cleared and the key read once; the server
+   * sends a frame too, in either order, and both arrive `'ready'`.
+   */
+  onSubscriptionChange(change, stream) {
+    const id = /^state\.(.+)\.changed$/.exec(change.event)?.[1];
+    if (id === void 0 || !this.manifest[id]) {
+      return;
+    }
+    const key = this.keyIn(id, stream.query);
+    const slot = this.slot(id, key);
+    if (change.status === "revoked") {
+      this.store.revoke(slot, stream.generation);
+      return;
+    }
+    this.grants.set(slot, ++this.clock);
+    this.store.allow(slot);
+    if (this.watched.has(slot)) {
+      this.get(id, key).catch(this.reportError);
+    }
+  }
+};
+
+export { createStateClient };
+//# sourceMappingURL=client.js.map
+//# sourceMappingURL=client.js.map