@cosmicdrift/kumiko-testing 0.380.0 → 0.382.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.380.0",
+  "version": "0.382.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -99,9 +99,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.380.0",
-    "@cosmicdrift/kumiko-guards": "0.380.0",
-    "@cosmicdrift/kumiko-types": "0.380.0",
+    "@cosmicdrift/kumiko-framework": "0.382.0",
+    "@cosmicdrift/kumiko-guards": "0.382.0",
+    "@cosmicdrift/kumiko-types": "0.382.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -125,8 +125,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.380.0",
-    "@cosmicdrift/kumiko-dev-server": "0.380.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.382.0",
+    "@cosmicdrift/kumiko-dev-server": "0.382.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.382.0",
+    "type": "improvement",
+    "title": "withEnv and readSseFrames test helpers",
+    "detail": "withEnv restores process.env after a callback so parallel no-isolate runs do not leak variables; readSseFrames replaces hand-written SSE stream parsers in tests."
+  },
+  {
+    "version": "0.381.0",
+    "type": "improvement",
+    "title": "Deterministic concurrency test helpers",
+    "detail": "createBarrier proves handler calls overlapped, burst fires N requests and tallies statuses with a guard against the pool size, TestStack exposes dbPoolMax."
+  },
   {
     "version": "0.376.0",
     "type": "fix",

package/src/helpers/barrier.ts

@@ -0,0 +1,59 @@
+export type Barrier = {
+  readonly arrive: () => Promise<void>;
+  readonly skip: () => void;
+  readonly arrived: number;
+  readonly skipped: number;
+};
+
+const DEFAULT_BARRIER_TIMEOUT_MS = 5000;
+
+export function createBarrier(options: {
+  readonly expected: number;
+  readonly timeoutMs?: number;
+}): Barrier {
+  const { expected, timeoutMs = DEFAULT_BARRIER_TIMEOUT_MS } = options;
+  if (expected < 1) {
+    throw new Error(`barrier expected must be at least 1, got ${expected}`);
+  }
+
+  let arrived = 0;
+  let skipped = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const waiting: { resolve: () => void; reject: (error: Error) => void }[] = [];
+
+  function openIfComplete(): void {
+    if (arrived + skipped >= expected) {
+      clearTimeout(timer);
+      for (const waiter of waiting.splice(0)) waiter.resolve();
+    }
+  }
+
+  return {
+    arrive() {
+      arrived++;
+      const pending = new Promise<void>((resolve, reject) => {
+        waiting.push({ resolve, reject });
+      });
+      if (arrived === 1 && arrived + skipped < expected) {
+        timer = setTimeout(() => {
+          const error = new Error(
+            `barrier timed out: ${arrived} of ${expected} arrived, ${skipped} skipped`,
+          );
+          for (const waiter of waiting.splice(0)) waiter.reject(error);
+        }, timeoutMs);
+      }
+      openIfComplete();
+      return pending;
+    },
+    skip() {
+      skipped++;
+      openIfComplete();
+    },
+    get arrived() {
+      return arrived;
+    },
+    get skipped() {
+      return skipped;
+    },
+  };
+}

package/src/helpers/burst.ts

@@ -0,0 +1,22 @@
+export type BurstResult = {
+  readonly responses: readonly Response[];
+  readonly statuses: Readonly<Record<number, number>>;
+};
+
+export async function burst(
+  stack: { readonly dbPoolMax: number },
+  count: number,
+  request: (index: number) => Promise<Response>,
+): Promise<BurstResult> {
+  if (count > stack.dbPoolMax) {
+    throw new Error(
+      `burst of ${count} exceeds dbPoolMax ${stack.dbPoolMax}: extra requests queue on the pool and a barrier inside the handler deadlocks; raise TestStackOptions.dbPoolMax or lower the count`,
+    );
+  }
+  const responses = await Promise.all(Array.from({ length: count }, (_, index) => request(index)));
+  const statuses: Record<number, number> = {};
+  for (const response of responses) {
+    statuses[response.status] = (statuses[response.status] ?? 0) + 1;
+  }
+  return { responses, statuses };
+}

package/src/helpers/index.ts

@@ -13,10 +13,11 @@ export {
   resetEventPiiCatalogForTests,
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/internal/testing";
-
 export { rolesOf } from "./access-assertions.ts";
 export { expectError, expectSuccess } from "./assertions.ts";
+export { type Barrier, createBarrier } from "./barrier.ts";
 export { withBootValidatorFixture } from "./boot-validator-fixture.ts";
+export { type BurstResult, burst } from "./burst.ts";
 export {
   captureClosedConnectionError,
   terminateBackendsByApplicationName,
@@ -61,8 +62,10 @@ export {
   sharedWidgetEntity,
   sharedWidgetTable,
 } from "./shared-entities.ts";
+export { readSseFrames, type SseFrame } from "./sse-frames.ts";
 export { createTestStoredEvent } from "./stored-event-fixture.ts";
 export { sleep } from "./utils.ts";
 export { waitFor } from "./wait-for.ts";
+export { withEnv } from "./with-env.ts";
 export { withoutAmbientTemporal } from "./without-ambient-temporal.ts";
 export { zipWithEntries } from "./zip-fixture.ts";

package/src/helpers/sse-frames.ts

@@ -0,0 +1,82 @@
+export type SseFrame = {
+  readonly event: string | undefined;
+  readonly data: string;
+  readonly id: string | undefined;
+};
+
+export type ReadSseFramesOptions = {
+  readonly until: (frame: SseFrame, all: readonly SseFrame[]) => boolean;
+  readonly skipPings?: boolean;
+  readonly timeoutMs?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export async function readSseFrames(
+  response: Response,
+  options: ReadSseFramesOptions,
+): Promise<SseFrame[]> {
+  if (response.body === null) {
+    throw new Error("sse response has no body");
+  }
+  const skipPings = options.skipPings ?? true;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const frames: SseFrame[] = [];
+  let buffer = "";
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(new Error(`sse read timed out after ${timeoutMs}ms: ${frames.length} frames read`)),
+      timeoutMs,
+    );
+  });
+
+  try {
+    for (;;) {
+      const chunk = await Promise.race([reader.read(), timedOut]);
+      if (chunk.done) {
+        throw new Error(`sse stream ended before condition: ${frames.length} frames read`);
+      }
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let separator = buffer.indexOf("\n\n");
+      while (separator !== -1) {
+        const rawFrame = buffer.slice(0, separator);
+        buffer = buffer.slice(separator + 2);
+        const frame = parseFrame(rawFrame);
+        if (frame !== undefined && !(skipPings && frame.event === "ping")) {
+          frames.push(frame);
+          if (options.until(frame, frames)) {
+            return frames;
+          }
+        }
+        separator = buffer.indexOf("\n\n");
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+function parseFrame(rawFrame: string): SseFrame | undefined {
+  let event: string | undefined;
+  let id: string | undefined;
+  const dataLines: string[] = [];
+  for (const line of rawFrame.split("\n")) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const rawValue = colon === -1 ? "" : line.slice(colon + 1);
+    const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+    if (field === "event") event = value;
+    else if (field === "id") id = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (event === undefined && id === undefined && dataLines.length === 0) {
+    return undefined;
+  }
+  return { event, data: dataLines.join("\n"), id };
+}

package/src/helpers/with-env.ts

@@ -0,0 +1,28 @@
+export async function withEnv<T>(
+  overrides: Readonly<Record<string, string | undefined>>,
+  run: () => T | Promise<T>,
+): Promise<T> {
+  const previous = new Map<string, string | undefined>();
+  for (const key of Object.keys(overrides)) {
+    previous.set(key, process.env[key]);
+  }
+  try {
+    for (const [key, value] of Object.entries(overrides)) {
+      applyEnvValue(key, value);
+    }
+    return await run();
+  } finally {
+    for (const [key, value] of previous) {
+      applyEnvValue(key, value);
+    }
+  }
+}
+
+// Assigning undefined would store the string "undefined", so absence must go through delete.
+function applyEnvValue(key: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}

package/src/stack/db.ts

@@ -22,8 +22,11 @@ function requireEnv(name: string): string {
   return value;
 }
 
+export const DEFAULT_TEST_DB_POOL_MAX = 10;
+
 export type TestDb = {
   db: DbConnection;
+  poolMax: number;
   outsideTransactionDb: DbConnection;
   client: PgListenClient;
   dbName: string;
@@ -59,10 +62,8 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
   }
 
   const testUrl = url.replace(/\/[^/]+$/, `/${dbName}`);
-  const conn = createDbConnection({
-    url: testUrl,
-    ...(opts.poolMax !== undefined ? { maxConnections: opts.poolMax } : {}),
-  });
+  const poolMax = opts.poolMax ?? DEFAULT_TEST_DB_POOL_MAX;
+  const conn = createDbConnection({ url: testUrl, maxConnections: poolMax });
   const outsideConn = createDbConnection({
     url: testUrl,
     maxConnections: opts.outsideTransactionPoolMax ?? DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX,
@@ -73,6 +74,7 @@ export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<
 
   return {
     db: conn.db,
+    poolMax,
     outsideTransactionDb: outsideConn.db,
     client: conn.client,
     dbName,

package/src/stack/index.ts

@@ -17,6 +17,7 @@ export {
 export {
   type CreateTestDbOptions,
   createTestDb,
+  DEFAULT_TEST_DB_POOL_MAX,
   type TestDb,
 } from "./db.ts";
 export { drainEventConsumers } from "./drain-event-consumers.ts";

package/src/stack/test-stack.ts

@@ -61,6 +61,8 @@ export type TestStack = {
   jwt: JwtHelper;
   registry: Registry;
   db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
+  /** Resolved connection pool size of `db`. */
+  readonly dbPoolMax: number;
   redis: TestRedis;
   // The bus this stack publishes/subscribes on; pass to TierResolverPlugin.build
   // so a tier-engine resolver built outside buildServer joins the same sync.
@@ -686,6 +688,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       jwt: server.jwt,
       registry,
       db: testDb.db,
+      dbPoolMax: testDb.poolMax,
       redis: testRedis,
       cacheSync,
       search: searchAdapter,