@stigmer/react 0.3.3 → 0.4.0

package/src/internal/__tests__/fetch-cache.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { FetchCache } from "../fetch-cache";
+
+describe("FetchCache", () => {
+  // -------------------------------------------------------------------
+  // get / set / has
+  // -------------------------------------------------------------------
+
+  it("returns undefined for a missing key", () => {
+    const cache = new FetchCache();
+    expect(cache.get("nope")).toBeUndefined();
+    expect(cache.has("nope")).toBe(false);
+  });
+
+  it("stores and retrieves a value", () => {
+    const cache = new FetchCache();
+    const obj = { id: "ses_1", name: "Test" };
+    cache.set("session:ses_1", obj);
+
+    expect(cache.get("session:ses_1")).toBe(obj);
+    expect(cache.has("session:ses_1")).toBe(true);
+  });
+
+  it("overwrites an existing entry", () => {
+    const cache = new FetchCache();
+    cache.set("k", "first");
+    cache.set("k", "second");
+    expect(cache.get("k")).toBe("second");
+  });
+
+  it("preserves reference identity (no cloning)", () => {
+    const cache = new FetchCache();
+    const arr = [1, 2, 3];
+    cache.set("k", arr);
+    expect(cache.get("k")).toBe(arr);
+  });
+
+  // -------------------------------------------------------------------
+  // TTL
+  // -------------------------------------------------------------------
+
+  describe("TTL expiration", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("returns the value before TTL expires", () => {
+      const cache = new FetchCache({ ttl: 1000 });
+      cache.set("k", "v");
+
+      vi.advanceTimersByTime(999);
+      expect(cache.get("k")).toBe("v");
+    });
+
+    it("returns undefined after TTL expires", () => {
+      const cache = new FetchCache({ ttl: 1000 });
+      cache.set("k", "v");
+
+      vi.advanceTimersByTime(1001);
+      expect(cache.get("k")).toBeUndefined();
+      expect(cache.has("k")).toBe(false);
+    });
+
+    it("expired entries are excluded from size", () => {
+      const cache = new FetchCache({ ttl: 500 });
+      cache.set("a", 1);
+      cache.set("b", 2);
+
+      vi.advanceTimersByTime(501);
+      expect(cache.size).toBe(0);
+    });
+
+    it("writing refreshes the timestamp", () => {
+      const cache = new FetchCache({ ttl: 1000 });
+      cache.set("k", "first");
+
+      vi.advanceTimersByTime(800);
+      cache.set("k", "second");
+
+      vi.advanceTimersByTime(800);
+      expect(cache.get("k")).toBe("second");
+    });
+  });
+
+  // -------------------------------------------------------------------
+  // LRU eviction
+  // -------------------------------------------------------------------
+
+  it("evicts the oldest entries when maxEntries is exceeded", () => {
+    const cache = new FetchCache({ maxEntries: 3 });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+    cache.set("d", 4);
+
+    expect(cache.has("a")).toBe(false);
+    expect(cache.get("b")).toBe(2);
+    expect(cache.get("c")).toBe(3);
+    expect(cache.get("d")).toBe(4);
+    expect(cache.size).toBe(3);
+  });
+
+  it("re-setting a key moves it to the tail (LRU refresh)", () => {
+    const cache = new FetchCache({ maxEntries: 3 });
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+
+    // Touch "a" — moves it to the tail.
+    cache.set("a", 10);
+
+    // Adding "d" should evict "b" (the oldest untouched), not "a".
+    cache.set("d", 4);
+
+    expect(cache.has("b")).toBe(false);
+    expect(cache.get("a")).toBe(10);
+    expect(cache.get("c")).toBe(3);
+    expect(cache.get("d")).toBe(4);
+  });
+
+  // -------------------------------------------------------------------
+  // invalidate / invalidatePrefix / clear
+  // -------------------------------------------------------------------
+
+  it("invalidate removes a single entry", () => {
+    const cache = new FetchCache();
+    cache.set("a", 1);
+    cache.set("b", 2);
+
+    cache.invalidate("a");
+
+    expect(cache.has("a")).toBe(false);
+    expect(cache.has("b")).toBe(true);
+  });
+
+  it("invalidate is a no-op for missing keys", () => {
+    const cache = new FetchCache();
+    expect(() => cache.invalidate("nope")).not.toThrow();
+  });
+
+  it("invalidatePrefix removes all matching entries", () => {
+    const cache = new FetchCache();
+    cache.set("session:1", "s1");
+    cache.set("session:2", "s2");
+    cache.set("session-executions:1", "e1");
+    cache.set("agent:a", "ag");
+
+    cache.invalidatePrefix("session:");
+
+    expect(cache.has("session:1")).toBe(false);
+    expect(cache.has("session:2")).toBe(false);
+    expect(cache.has("session-executions:1")).toBe(true);
+    expect(cache.has("agent:a")).toBe(true);
+  });
+
+  it("clear drops all entries", () => {
+    const cache = new FetchCache();
+    cache.set("a", 1);
+    cache.set("b", 2);
+    cache.set("c", 3);
+
+    cache.clear();
+
+    expect(cache.size).toBe(0);
+    expect(cache.has("a")).toBe(false);
+  });
+
+  // -------------------------------------------------------------------
+  // prefetch
+  // -------------------------------------------------------------------
+
+  it("prefetch writes successful result to cache", async () => {
+    const cache = new FetchCache();
+    const fetchFn = vi.fn(async () => ({ id: "ses_1" }));
+
+    cache.prefetch("session:ses_1", fetchFn);
+    await vi.waitFor(() => expect(cache.has("session:ses_1")).toBe(true));
+
+    expect(cache.get("session:ses_1")).toEqual({ id: "ses_1" });
+    expect(fetchFn).toHaveBeenCalledOnce();
+  });
+
+  it("prefetch silently swallows errors", async () => {
+    const cache = new FetchCache();
+    const fetchFn = vi.fn(async () => {
+      throw new Error("network down");
+    });
+
+    cache.prefetch("k", fetchFn);
+
+    // Give the microtask queue time to process the rejection.
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(cache.has("k")).toBe(false);
+  });
+
+  // -------------------------------------------------------------------
+  // size
+  // -------------------------------------------------------------------
+
+  it("reports correct size", () => {
+    const cache = new FetchCache();
+    expect(cache.size).toBe(0);
+
+    cache.set("a", 1);
+    cache.set("b", 2);
+    expect(cache.size).toBe(2);
+
+    cache.invalidate("a");
+    expect(cache.size).toBe(1);
+  });
+
+  // -------------------------------------------------------------------
+  // defaults
+  // -------------------------------------------------------------------
+
+  it("uses default maxEntries of 100", () => {
+    const cache = new FetchCache();
+    for (let i = 0; i < 110; i++) {
+      cache.set(`k${i}`, i);
+    }
+    expect(cache.size).toBe(100);
+    // First 10 should have been evicted.
+    expect(cache.has("k0")).toBe(false);
+    expect(cache.has("k10")).toBe(true);
+  });
+});

package/src/internal/__tests__/stream-controller.test.ts

@@ -0,0 +1,395 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  StreamController,
+  type StreamControllerSink,
+} from "../stream-controller";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSnapshot(
+  phase: ExecutionPhase,
+  messageCount = 0,
+): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = phase;
+  for (let i = 0; i < messageCount; i++) {
+    status.messages.push({} as never);
+  }
+  exec.status = status;
+  return exec;
+}
+
+function createTestSink(): StreamControllerSink & {
+  snapshots: AgentExecution[];
+  states: Array<{ stage: string; executionId?: string; error?: Error }>;
+} {
+  const snapshots: AgentExecution[] = [];
+  const states: Array<{ stage: string; executionId?: string; error?: Error }> =
+    [];
+  return {
+    snapshots,
+    states,
+    ingestSnapshot(snapshot) {
+      snapshots.push(snapshot);
+    },
+    setStreamState(state) {
+      states.push(state as never);
+    },
+  };
+}
+
+type FlushCallback = () => void;
+
+function createSynchronousScheduler() {
+  const pending: Array<{ id: number; cb: FlushCallback }> = [];
+  let nextId = 1;
+
+  return {
+    pending,
+    schedule(cb: FlushCallback): number {
+      const id = nextId++;
+      pending.push({ id, cb });
+      return id;
+    },
+    cancel(id: number): void {
+      const idx = pending.findIndex((p) => p.id === id);
+      if (idx !== -1) pending.splice(idx, 1);
+    },
+    flush(): void {
+      const toRun = [...pending];
+      pending.length = 0;
+      for (const { cb } of toRun) cb();
+    },
+    get size() {
+      return pending.length;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("StreamController", () => {
+  let sink: ReturnType<typeof createTestSink>;
+  let scheduler: ReturnType<typeof createSynchronousScheduler>;
+  let controller: StreamController;
+
+  beforeEach(() => {
+    sink = createTestSink();
+    scheduler = createSynchronousScheduler();
+    controller = new StreamController(
+      sink,
+      scheduler.schedule,
+      scheduler.cancel,
+    );
+  });
+
+  describe("initial state", () => {
+    it("starts in idle", () => {
+      expect(controller.state).toEqual({ stage: "idle" });
+    });
+
+    it("has no pending flush", () => {
+      expect(controller.hasPendingFlush).toBe(false);
+    });
+  });
+
+  describe("start()", () => {
+    it("transitions to connecting", () => {
+      controller.start("exec-1");
+      expect(controller.state).toEqual({
+        stage: "connecting",
+        executionId: "exec-1",
+      });
+    });
+
+    it("notifies the sink of the state transition", () => {
+      controller.start("exec-1");
+      expect(sink.states).toEqual([
+        { stage: "connecting", executionId: "exec-1" },
+      ]);
+    });
+
+    it("resets when starting a different execution", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      controller.start("exec-2");
+      expect(controller.state).toEqual({
+        stage: "connecting",
+        executionId: "exec-2",
+      });
+      expect(scheduler.size).toBe(0);
+    });
+  });
+
+  describe("handleSnapshot() — non-terminal", () => {
+    beforeEach(() => {
+      controller.start("exec-1");
+      sink.states.length = 0;
+    });
+
+    it("transitions from connecting to streaming on first snapshot", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      expect(controller.state).toEqual({
+        stage: "streaming",
+        executionId: "exec-1",
+      });
+    });
+
+    it("buffers the snapshot (does not flush immediately)", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      expect(sink.snapshots).toHaveLength(0);
+      expect(controller.hasPendingFlush).toBe(true);
+    });
+
+    it("flushes on scheduler callback", () => {
+      const snap = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS);
+      controller.handleSnapshot(snap);
+      scheduler.flush();
+      expect(sink.snapshots).toEqual([snap]);
+      expect(controller.hasPendingFlush).toBe(false);
+    });
+
+    it("coalesces multiple snapshots into one flush", () => {
+      const snap1 = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 1);
+      const snap2 = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 2);
+      const snap3 = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 3);
+
+      controller.handleSnapshot(snap1);
+      controller.handleSnapshot(snap2);
+      controller.handleSnapshot(snap3);
+
+      expect(scheduler.size).toBe(1);
+      scheduler.flush();
+      expect(sink.snapshots).toEqual([snap3]);
+    });
+
+    it("schedules a new flush after the previous one fires", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 1),
+      );
+      scheduler.flush();
+      expect(scheduler.size).toBe(0);
+
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 2),
+      );
+      expect(scheduler.size).toBe(1);
+    });
+  });
+
+  describe("handleSnapshot() — terminal", () => {
+    beforeEach(() => {
+      controller.start("exec-1");
+      sink.states.length = 0;
+    });
+
+    it("flushes immediately without waiting for scheduler", () => {
+      const snap = makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED);
+      controller.handleSnapshot(snap);
+      expect(sink.snapshots).toEqual([snap]);
+      expect(scheduler.size).toBe(0);
+    });
+
+    it("transitions to complete", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      expect(controller.state).toEqual({
+        stage: "complete",
+        executionId: "exec-1",
+      });
+    });
+
+    it("cancels any pending non-terminal flush", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS, 1),
+      );
+      expect(scheduler.size).toBe(1);
+
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      expect(scheduler.size).toBe(0);
+    });
+
+    it("handles terminal as first snapshot (connecting -> complete)", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      expect(controller.state).toEqual({
+        stage: "complete",
+        executionId: "exec-1",
+      });
+      expect(sink.states).toEqual([
+        { stage: "complete", executionId: "exec-1" },
+      ]);
+    });
+
+    it("handles EXECUTION_FAILED as terminal", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_FAILED),
+      );
+      expect(controller.state.stage).toBe("complete");
+    });
+
+    it("handles EXECUTION_CANCELLED as terminal", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_CANCELLED),
+      );
+      expect(controller.state.stage).toBe("complete");
+    });
+
+    it("handles EXECUTION_TERMINATED as terminal", () => {
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_TERMINATED),
+      );
+      expect(controller.state.stage).toBe("complete");
+    });
+  });
+
+  describe("handleStreamEnd()", () => {
+    it("flushes buffered snapshot and transitions to complete", () => {
+      controller.start("exec-1");
+      const snap = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS);
+      controller.handleSnapshot(snap);
+      controller.handleStreamEnd();
+
+      expect(sink.snapshots).toEqual([snap]);
+      expect(controller.state).toEqual({
+        stage: "complete",
+        executionId: "exec-1",
+      });
+    });
+
+    it("no-ops if already complete (terminal snapshot already handled)", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      sink.states.length = 0;
+
+      controller.handleStreamEnd();
+      expect(sink.states).toHaveLength(0);
+    });
+
+    it("no-ops if idle", () => {
+      controller.handleStreamEnd();
+      expect(sink.states).toHaveLength(0);
+    });
+  });
+
+  describe("handleError()", () => {
+    it("transitions to error state", () => {
+      controller.start("exec-1");
+      const err = new Error("network timeout");
+      controller.handleError(err);
+
+      expect(controller.state).toEqual({
+        stage: "error",
+        executionId: "exec-1",
+        error: err,
+      });
+    });
+
+    it("flushes buffered snapshot before transitioning", () => {
+      controller.start("exec-1");
+      const snap = makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS);
+      controller.handleSnapshot(snap);
+      controller.handleError(new Error("fail"));
+
+      expect(sink.snapshots).toEqual([snap]);
+    });
+
+    it("cancels pending rAF", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      expect(scheduler.size).toBe(1);
+
+      controller.handleError(new Error("fail"));
+      expect(scheduler.size).toBe(0);
+    });
+
+    it("no-ops if idle", () => {
+      controller.handleError(new Error("orphan"));
+      expect(sink.states).toHaveLength(0);
+    });
+  });
+
+  describe("reset()", () => {
+    it("transitions to idle", () => {
+      controller.start("exec-1");
+      controller.reset();
+      expect(controller.state).toEqual({ stage: "idle" });
+    });
+
+    it("cancels pending flush", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      controller.reset();
+      expect(scheduler.size).toBe(0);
+      expect(controller.hasPendingFlush).toBe(false);
+    });
+
+    it("clears buffered snapshot", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      controller.reset();
+      scheduler.flush();
+      expect(sink.snapshots).toHaveLength(0);
+    });
+
+    it("no-ops if already idle", () => {
+      controller.reset();
+      expect(sink.states).toHaveLength(0);
+    });
+
+    it("notifies sink of idle transition", () => {
+      controller.start("exec-1");
+      sink.states.length = 0;
+      controller.reset();
+      expect(sink.states).toEqual([{ stage: "idle" }]);
+    });
+  });
+
+  describe("stale event guard", () => {
+    it("ignores snapshots after reset", () => {
+      controller.start("exec-1");
+      controller.reset();
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      expect(sink.snapshots).toHaveLength(0);
+    });
+
+    it("ignores errors after reset", () => {
+      controller.start("exec-1");
+      controller.reset();
+      controller.handleError(new Error("stale"));
+      expect(controller.state).toEqual({ stage: "idle" });
+    });
+  });
+});