@cosmicdrift/kumiko-testing 0.379.0 → 0.381.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.379.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.379.0",
-    "@cosmicdrift/kumiko-guards": "0.379.0",
-    "@cosmicdrift/kumiko-types": "0.379.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.379.0",
-    "@cosmicdrift/kumiko-dev-server": "0.379.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/db-cleanup.ts

@@ -1,5 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
-import { deleteMany } from "@cosmicdrift/kumiko-framework/db";
+import { deleteMany, requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import type { AnyDb } from "@cosmicdrift/kumiko-framework/internal/stack-support";
 import { withExecutorManagedWritesForTests } from "@cosmicdrift/kumiko-framework/internal/testing";
 
@@ -13,30 +13,16 @@ function tableFromName(name: string): EntityTableMeta {
   return { tableName: name, columns: [], indexes: [], source: "unmanaged" };
 }
 
-function resolveClearableTable(table: ClearableTable): unknown {
+function resolveClearableTable(table: ClearableTable): EntityTableMeta {
   if (typeof table === "string") return tableFromName(table);
-  if (
-    typeof table === "object" &&
-    table !== null &&
-    "tableName" in table &&
-    typeof table.tableName === "string"
-  ) {
-    return table;
-  }
-  return table;
+  return requireEntityTableMeta(table, "clearTables");
 }
 
 /** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
 export async function clearTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
   for (const table of tables) {
-    // Test-teardown truncate: resolveClearableTable returns `unknown` (string
-    // name or table object). The brand-strip cast is the sanctioned bypass —
-    // clearing a managed projection between tests is not a production write.
-    await deleteMany(
-      withExecutorManagedWritesForTests(db),
-      resolveClearableTable(table) as EntityTableMeta,
-      {},
-    );
+    // Test teardown: clearing a managed projection between tests is not a production write.
+    await deleteMany(withExecutorManagedWritesForTests(db), resolveClearableTable(table), {});
   }
 }
 

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/helpers/seed.ts

@@ -1,11 +1,10 @@
 // Test-only ES-bypass: seed / mutate a managed projection directly, skipping
-// the event log. Production code CANNOT do this — the write helpers reject a
-// branded EntityTable at compile time (#742). Tests seed read-model state to
-// arrange a scenario without driving the full event path; a projection rebuild
-// is not part of the test lifecycle, so eventless writes are safe here. The
-// `as EntityTableMeta` strips the executor-only brand at this single sanctioned
-// seam — the signatures mirror the query helpers so a call-site migration is a
-// plain identifier rename.
+// the event log. Production code cannot do this: the write helpers only accept
+// a runner carrying the executor capability or a Writable table. Tests seed
+// read-model state to arrange a scenario without driving the full event path;
+// a projection rebuild is not part of the test lifecycle, so eventless writes
+// are safe here. The signatures mirror the query helpers so a call-site
+// migration is a plain identifier rename.
 
 import type { EntityTable, EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -25,7 +24,7 @@ export function seedRow<TRow = unknown>(
   table: SeedTable,
   values: Record<string, unknown>,
 ): Promise<TRow | undefined> {
-  return insertOne<TRow>(withExecutorManagedWritesForTests(db), table as EntityTableMeta, values);
+  return insertOne<TRow>(withExecutorManagedWritesForTests(db), table, values);
 }
 
 export function seedRows<TRow = unknown>(
@@ -33,7 +32,7 @@ export function seedRows<TRow = unknown>(
   table: SeedTable,
   rows: ReadonlyArray<Record<string, unknown>>,
 ): Promise<readonly TRow[]> {
-  return insertMany<TRow>(withExecutorManagedWritesForTests(db), table as EntityTableMeta, rows);
+  return insertMany<TRow>(withExecutorManagedWritesForTests(db), table, rows);
 }
 
 export function updateRows<TRow = unknown>(
@@ -42,14 +41,9 @@ export function updateRows<TRow = unknown>(
   set: Record<string, unknown>,
   where: WhereObject,
 ): Promise<readonly TRow[]> {
-  return updateMany<TRow>(
-    withExecutorManagedWritesForTests(db),
-    table as EntityTableMeta,
-    set,
-    where,
-  );
+  return updateMany<TRow>(withExecutorManagedWritesForTests(db), table, set, where);
 }
 
 export function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<number> {
-  return deleteMany(withExecutorManagedWritesForTests(db), table as EntityTableMeta, where);
+  return deleteMany(withExecutorManagedWritesForTests(db), table, where);
 }

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,