@cosmicdrift/kumiko-testing 0.380.0 → 0.381.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.380.0",
+  "version": "0.381.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.381.0",
+    "@cosmicdrift/kumiko-guards": "0.381.0",
+    "@cosmicdrift/kumiko-types": "0.381.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.381.0",
+    "@cosmicdrift/kumiko-dev-server": "0.381.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,10 @@
 [
+  {
+    "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,

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,