@mandujs/core 0.13.1 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/filling/index.ts

@@ -10,6 +10,8 @@ export { ManduFilling, ManduFillingFactory, LoaderTimeoutError } from "./filling
 export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
 export { SSEConnection, createSSEConnection } from "./sse";
 export type { SSEOptions, SSESendOptions, SSECleanup } from "./sse";
+export { resolveResumeCursor, catchupFromCursor, mergeUniqueById } from "./sse-catchup";
+export type { SSECursor, CatchupResult, CatchupOptions } from "./sse-catchup";
 
 // Auth Guards
 export {

package/src/filling/sse-catchup.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+import { catchupFromCursor, mergeUniqueById, resolveResumeCursor } from "./sse-catchup";
+
+describe("sse catch-up primitives", () => {
+  const snapshot = [
+    { id: "m1", text: "first" },
+    { id: "m2", text: "second" },
+    { id: "m3", text: "third" },
+  ];
+
+  it("resolves Last-Event-ID cursor", () => {
+    const req = new Request("http://localhost/stream", {
+      headers: { "Last-Event-ID": "m2" },
+    });
+
+    expect(resolveResumeCursor(req)).toBe("m2");
+  });
+
+  it("returns delta list when cursor exists", () => {
+    const result = catchupFromCursor({ cursorId: "m1", snapshot });
+
+    expect(result.mode).toBe("delta");
+    expect(result.items.map((m) => m.id)).toEqual(["m2", "m3"]);
+  });
+
+  it("falls back to snapshot when cursor is missing", () => {
+    const result = catchupFromCursor({ snapshot });
+
+    expect(result.mode).toBe("snapshot");
+    expect(result.reason).toBe("missing-cursor");
+    expect(result.items.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("falls back to snapshot when cursor is unknown", () => {
+    const result = catchupFromCursor({ cursorId: "missing", snapshot });
+
+    expect(result.mode).toBe("snapshot");
+    expect(result.reason).toBe("unknown-cursor");
+    expect(result.items.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("merges incoming messages idempotently", () => {
+    const base = [
+      { id: "m1", text: "first" },
+      { id: "m2", text: "second" },
+    ];
+    const incoming = [
+      { id: "m2", text: "second-dup" },
+      { id: "m3", text: "third" },
+    ];
+
+    const merged = mergeUniqueById(base, incoming);
+
+    expect(merged.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+});

package/src/filling/sse-catchup.ts

@@ -0,0 +1,67 @@
+export interface SSECursor {
+  id: string;
+}
+
+export interface CatchupResult<T> {
+  mode: "delta" | "snapshot";
+  items: T[];
+  reason?: "missing-cursor" | "unknown-cursor";
+}
+
+export interface CatchupOptions<T extends SSECursor> {
+  cursorId?: string | null;
+  snapshot: readonly T[];
+}
+
+/**
+ * Resolve resume cursor from Last-Event-ID header.
+ */
+export function resolveResumeCursor(request: Request): string | undefined {
+  const raw = request.headers.get("last-event-id")?.trim();
+  return raw ? raw : undefined;
+}
+
+/**
+ * Return reconnect catch-up list if cursor exists, otherwise full snapshot fallback.
+ */
+export function catchupFromCursor<T extends SSECursor>(options: CatchupOptions<T>): CatchupResult<T> {
+  const { cursorId, snapshot } = options;
+
+  if (!cursorId) {
+    return {
+      mode: "snapshot",
+      reason: "missing-cursor",
+      items: [...snapshot],
+    };
+  }
+
+  const index = snapshot.findIndex((item) => item.id === cursorId);
+  if (index < 0) {
+    return {
+      mode: "snapshot",
+      reason: "unknown-cursor",
+      items: [...snapshot],
+    };
+  }
+
+  return {
+    mode: "delta",
+    items: snapshot.slice(index + 1),
+  };
+}
+
+/**
+ * Idempotent merge utility for reconnect + snapshot mix.
+ */
+export function mergeUniqueById<T extends SSECursor>(base: readonly T[], incoming: readonly T[]): T[] {
+  const seen = new Set(base.map((item) => item.id));
+  const merged = [...base];
+
+  for (const item of incoming) {
+    if (seen.has(item.id)) continue;
+    seen.add(item.id);
+    merged.push(item);
+  }
+
+  return merged;
+}