@spfn/core 0.3.0-beta.24 → 0.3.0-beta.26

package/dist/state/client.d.ts

@@ -0,0 +1,144 @@
+import { TSchema, Static } from '@sinclair/typebox';
+import { SSEClient } from '@spfn/core/event/sse/client';
+import { ApiConfig } from '@spfn/core/nextjs';
+import { StateRouter, StatesSnapshot } from '@spfn/core/state';
+export { InferStateInput, InferStateKey, InferStateValue } from '@spfn/core/state';
+
+/**
+ * State Client Types
+ *
+ * Everything the browser side knows about a state router is its type,
+ * `typeof states`, imported type-only. These types turn it into the ids, keys,
+ * values and write inputs the client and the hook accept. Nothing here is
+ * runtime: the client bundle never contains server code.
+ */
+
+/** Any state router, as `typeof states`. */
+type AnyStateRouter = StateRouter<any>;
+type StateOf<TStates extends AnyStateRouter> = TStates['states'][keyof TStates['states']];
+type Schema<T> = T extends TSchema ? Static<T> : undefined;
+/**
+ * What the client needs of each state, computed once per router: key, value,
+ * data and write input by id. Every signature below indexes it, rather than
+ * re-deriving a state's shape per argument.
+ */
+type StateCatalog<TStates extends AnyStateRouter> = {
+    [S in StateOf<TStates> as S['id']]: {
+        key: Schema<S['_types']['key']>;
+        value: Schema<S['_types']['value']>;
+        data: Schema<S['_types']['data']>;
+        input: S['_types']['input'] extends TSchema ? Static<S['_types']['input']> : never;
+    };
+};
+/** The ids of a router's states. */
+type StateId<TStates extends AnyStateRouter> = keyof StateCatalog<TStates> & string;
+/** The data type of state `Id`, `undefined` when it declares no `.data()`. */
+type InferStateData<TStates extends AnyStateRouter, Id extends StateId<TStates>> = StateCatalog<TStates>[Id]['data'];
+/** The ids of the states that declare a `.write()`. */
+type WritableStateId<TStates extends AnyStateRouter> = {
+    [Id in StateId<TStates>]: [StateCatalog<TStates>[Id]['input']] extends [never] ? never : Id;
+}[StateId<TStates>];
+/** The key argument of state `Id`: one key object when keyed, none when keyless. */
+type StateKeyArgs<TStates extends AnyStateRouter, Id extends StateId<TStates>> = [
+    StateCatalog<TStates>[Id]['key']
+] extends [undefined] ? [] : [key: StateCatalog<TStates>[Id]['key']];
+/** The frame type of state `Id`. */
+type StateFrameOf<TStates extends AnyStateRouter, Id extends StateId<TStates>> = StateFrame<StateCatalog<TStates>[Id]['value'], StateCatalog<TStates>[Id]['data']>;
+/** A value as a read, a write or the SSE event answers it, stamped with the `at` of its read. */
+interface StateFrame<V = unknown, D = unknown> {
+    at: string;
+    value: V;
+    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.
+ */
+type StateEntry<V = unknown, D = unknown> = Readonly<StateFrame<V, D> & {
+    status: 'ready' | 'revoked';
+}> | Readonly<{
+    at?: undefined;
+    value?: undefined;
+    data?: undefined;
+    status: 'revoked';
+}>;
+/** Called after the entry of a subscribed `(id, key)` changed. */
+type StateListener = () => void;
+interface StateClientConfig {
+    /**
+     * The SSE client the stream is opened on — `createAuthSSEClient()` for an
+     * authenticated app. Give the state client its own: an `SSEClient` holds
+     * one subscription, and the state client's supersedes any other on it.
+     */
+    sse: SSEClient<any>;
+    /** Passed to `createApi` for the read, write and snapshot routes. */
+    api?: ApiConfig;
+    /**
+     * Something the client ran on its own failed: a snapshot (the first, or the
+     * one after a stream opened), the read after a grant, or a `subscribe` the
+     * manifest refuses. Calls the app makes reject instead.
+     * @default console.error
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Milliseconds before a failed first snapshot is read again, while
+     * subscriptions wait on it — the SSE client's `reconnectDelay` for a
+     * stream that does not exist yet.
+     * @default 3000
+     */
+    retryDelay?: number;
+}
+/**
+ * The browser side of a state router: one store per `(id, key)`, one SSE
+ * stream for the whole client.
+ */
+interface StateClient<TStates extends AnyStateRouter> {
+    /** Read one state; the answer is applied to the store and returned. */
+    get<Id extends StateId<TStates>>(id: Id, ...key: StateKeyArgs<TStates, Id>): Promise<StateFrameOf<TStates, Id>>;
+    /** 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
+     * the manifest is known. Returns the unsubscribe.
+     */
+    subscribe<Id extends StateId<TStates>>(id: Id, ...args: [...key: StateKeyArgs<TStates, Id>, listener: StateListener]): () => void;
+    /** Write a state through its write route; the answer is applied at once and returned. */
+    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. */
+    close(): void;
+}
+
+/**
+ * State Client
+ *
+ * The browser side of a state router (`@spfn/core/state`): it calls the derived
+ * read, write and snapshot routes, keeps one SSE stream open for every state of
+ * the router, and orders snapshots against frames per `(id, key)`. It knows the
+ * router by type — `typeof states` — and at runtime by the manifest every
+ * snapshot carries; it imports no server code.
+ *
+ * @example
+ * ```typescript
+ * import { createStateClient } from '@spfn/core/state/client';
+ * import { createAuthSSEClient } from '@spfn/core/event/sse/client';
+ * import type { states } from '@/server/states';
+ *
+ * export const state = createStateClient<typeof states>({ sse: createAuthSSEClient() });
+ *
+ * const stop = state.subscribe('runtime', { workspaceId }, () => render(state.current('runtime', { workspaceId })));
+ * ```
+ */
+
+/**
+ * Build the client for `typeof states`. The first subscription (or call)
+ * reads the snapshot, whose manifest names every state; the stream then
+ * requests every state event — the server's `grant` can only activate an
+ * event the connection requested.
+ */
+declare function createStateClient<TStates extends AnyStateRouter>(config: StateClientConfig): 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 };

package/dist/state/client.js

@@ -0,0 +1,478 @@
+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 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 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();
+  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 an applied change.
+   */
+  apply(slot, frame) {
+    const current = this.entries.get(slot);
+    const status = this.revoked.has(slot) ? "revoked" : "ready";
+    if (supersedes(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
+function routeName(method, id) {
+  return `${method}${id[0].toUpperCase()}${id.slice(1)}State`;
+}
+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));
+  }
+  store = new StateStore();
+  api;
+  watched = /* @__PURE__ */ new Map();
+  reportError;
+  manifest;
+  manifestRead;
+  stream;
+  syncQueued = false;
+  /** 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));
+  }
+  close() {
+    this.lifetime++;
+    clearTimeout(this.retryTimer);
+    this.retryTimer = void 0;
+    this.closeStream();
+    this.watched.clear();
+    this.store.clearListeners();
+  }
+  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, tag) {
+    if ((this.store.revokedBy(slot) ?? Infinity) < tag.generation) {
+      this.store.allow(slot);
+    }
+    this.store.apply(slot, frame);
+  }
+  /** A state present is served, under the generation rule of `serve`. */
+  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);
+    }
+  }
+  /**
+   * 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);
+    }
+    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.
+   */
+  sync() {
+    if (this.watched.size === 0) {
+      this.closeStream();
+      return;
+    }
+    if (!this.manifest) {
+      this.awaitManifest();
+      return;
+    }
+    const query = this.streamQuery();
+    if (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()` or when nothing is watched (`sync` closes instead).
+   */
+  awaitManifest() {
+    const lifetime = this.lifetime;
+    if (this.waitingLifetime === lifetime) {
+      return;
+    }
+    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. */
+  retryLater() {
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = void 0;
+      this.resync();
+    }, this.config.retryDelay ?? 3e3);
+    this.retryTimer.unref?.();
+  }
+  /**
+   * 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.
+   */
+  openStream(query) {
+    this.closeStream();
+    const ids = Object.keys(this.manifest);
+    const stream = { query, text: stableKey(query), generation: 0, 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)])),
+      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);
+      },
+      onSubscriptionChange: (change) => this.onSubscriptionChange(change, stream)
+    });
+    this.stream = stream;
+  }
+  closeStream() {
+    this.stream?.close();
+    this.stream = void 0;
+  }
+  /** 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);
+    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);
+  }
+  /** A frame for a key nobody here subscribed is dropped — the server's filter is the first guard, this the second. */
+  onFrame(id, frame) {
+    const slot = this.slot(id, frame.key);
+    if (this.watched.has(slot)) {
+      this.store.apply(slot, frame);
+    }
+  }
+  /**
+   * 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