@stratal/testing 0.0.21 → 0.0.23

package/README.md

@@ -37,7 +37,6 @@ Set up base modules once in your Vitest setup file, then create test modules in
 
 ```typescript
 // vitest.setup.ts
-import 'reflect-metadata'
 import { Test } from '@stratal/testing'
 import { CoreModule } from './src/core.module'
 
@@ -316,27 +315,11 @@ beforeEach(() => {
 })
 ```
 
-### Nodemailer mock
-
-A drop-in mock for nodemailer, useful in Vitest's module mocking:
-
-```typescript
-// vitest.config.ts (or inline vi.mock)
-export default defineConfig({
-  test: {
-    alias: {
-      nodemailer: '@stratal/testing/mocks/nodemailer',
-    },
-  },
-})
-```
-
 ## Sub-path Exports
 
 ```typescript
 import { Test, TestingModule, createFetchMock } from '@stratal/testing'
 import { createMock, type DeepMocked } from '@stratal/testing/mocks'
-import nodemailer from '@stratal/testing/mocks/nodemailer'
 ```
 
 ## License

package/dist/database/index.d.mts

@@ -0,0 +1,2 @@
+import { a as TestDatabaseGlobalSetupOptions, c as createTestDatabaseGlobalSetup, d as deriveDbName, f as deriveTemplateName, i as ISOLATION_ENV_VAR, l as databasePrefix, m as normalizeIsolation, n as DEFAULT_DB_BINDING, o as buildConnectionString, p as dropDatabase, r as DatabaseIsolation, s as createDatabaseFromTemplate, t as BINDING_ENV_VAR, u as deriveAdminConnectionString } from "../index-BIr5nLof.mjs";
+export { BINDING_ENV_VAR, DEFAULT_DB_BINDING, type DatabaseIsolation, ISOLATION_ENV_VAR, type TestDatabaseGlobalSetupOptions, buildConnectionString, createDatabaseFromTemplate, createTestDatabaseGlobalSetup, databasePrefix, deriveAdminConnectionString, deriveDbName, deriveTemplateName, dropDatabase, normalizeIsolation };

package/dist/database/index.mjs

@@ -0,0 +1,2 @@
+import { a as createDatabaseFromTemplate, c as deriveAdminConnectionString, d as dropDatabase, f as normalizeIsolation, i as buildConnectionString, l as deriveDbName, n as DEFAULT_DB_BINDING, o as createTestDatabaseGlobalSetup, r as ISOLATION_ENV_VAR, s as databasePrefix, t as BINDING_ENV_VAR, u as deriveTemplateName } from "../database-B02eYKhE.mjs";
+export { BINDING_ENV_VAR, DEFAULT_DB_BINDING, ISOLATION_ENV_VAR, buildConnectionString, createDatabaseFromTemplate, createTestDatabaseGlobalSetup, databasePrefix, deriveAdminConnectionString, deriveDbName, deriveTemplateName, dropDatabase, normalizeIsolation };

package/dist/database-B02eYKhE.mjs

@@ -0,0 +1,334 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+//#region src/database/test-database.ts
+/**
+* Test database isolation helpers.
+*
+* Implements database-per-test-file isolation for parallel e2e runs against
+* Postgres. A migrated **template** database is built once in global setup;
+* each test file clones it instantly via `CREATE DATABASE ... TEMPLATE` and
+* drops it on teardown. See `@stratal/testing/database`.
+*
+* `pg` is imported dynamically so this module loads without it — consumers
+* that don't use a database never pay the dependency.
+*/
+/** Env var that selects the isolation mode (single source of truth). */
+const ISOLATION_ENV_VAR = "STRATAL_TEST_DB_ISOLATION";
+/** Env var carrying the name of the Hyperdrive binding to isolate. */
+const BINDING_ENV_VAR = "STRATAL_TEST_DB_BINDING";
+/** Default Hyperdrive binding name when none is configured. */
+const DEFAULT_DB_BINDING = "DB";
+/**
+* Normalize an isolation value (from an option or env var) to a mode.
+* Anything other than the literal `'database'` resolves to `'shared'` — the
+* default — so parallel isolation is strictly opt-in.
+*/
+function normalizeIsolation(value) {
+	return value === "database" ? "database" : "shared";
+}
+/**
+* Postgres' identifier length limit. Names longer than this are silently
+* truncated by the server, which would cause distinct logical names to collide
+* on the same physical database. We assert against it everywhere a name is
+* derived.
+*/
+const MAX_IDENTIFIER_LENGTH = 63;
+/** Quote a Postgres identifier for safe interpolation into DDL. */
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+/** Quote a Postgres string literal for safe interpolation into SQL. */
+function quoteLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+* Dynamically import `pg` (an optional peer), surfacing an actionable error
+* instead of a raw module-not-found when database isolation is requested
+* without the dependency installed.
+*/
+async function importPg() {
+	try {
+		const { default: pg } = await import("pg");
+		return pg;
+	} catch (error) {
+		throw new Error("[stratal-testing] `pg` is required for database isolation but is not installed. Install it: `npm install --save-dev pg` (or `yarn add -D pg`).", { cause: error });
+	}
+}
+/**
+* Assert a derived identifier fits within Postgres' {@link MAX_IDENTIFIER_LENGTH}
+* limit. Throws a clear, actionable error instead of letting the server
+* silently truncate and collide names.
+*/
+function assertIdentifierLength(name, kind) {
+	if (name.length > MAX_IDENTIFIER_LENGTH) throw new Error(`[stratal-testing] Derived ${kind} "${name}" is ${name.length} characters, exceeding Postgres' ${MAX_IDENTIFIER_LENGTH}-character identifier limit. Use a shorter base database name so the test-isolation suffix fits.`);
+}
+/** Parse the database name out of a Postgres connection URL. */
+function databaseNameOf(connectionString) {
+	return new URL(connectionString).pathname.replace(/^\//, "") || "postgres";
+}
+/**
+* Derive an admin connection string pointing at the `postgres` maintenance
+* database. `CREATE`/`DROP DATABASE` cannot run on a connection bound to the
+* target database, so administration always goes through `postgres`.
+*/
+function deriveAdminConnectionString(connectionString) {
+	const url = new URL(connectionString);
+	url.pathname = "/postgres";
+	return url.toString();
+}
+/** Build a connection string identical to `base` but pointing at `dbName`. */
+function buildConnectionString(base, dbName) {
+	const url = new URL(base);
+	url.pathname = `/${dbName}`;
+	return url.toString();
+}
+/** Length of the random token appended by {@link deriveDbName}. */
+const DB_NAME_TOKEN_LENGTH = 12;
+/** The shared prefix for per-file databases, used as the leak-sweep key. */
+function databasePrefix(base) {
+	const prefix = `${databaseNameOf(base).replace(/[^a-z0-9_]/gi, "_")}_t_`;
+	assertIdentifierLength(`${prefix}${"x".repeat(DB_NAME_TOKEN_LENGTH)}`, "per-file database name");
+	return prefix;
+}
+/** Name of the migrated template database cloned per file. */
+function deriveTemplateName(base) {
+	const name = `${databaseNameOf(base).replace(/[^a-z0-9_]/gi, "_")}_template`;
+	assertIdentifierLength(name, "template database name");
+	return name;
+}
+/**
+* Generate a unique per-`compile()` database name. Random (not path-based) so
+* it is collision-free across concurrent isolates and multiple modules in the
+* same file, and stays well within Postgres' 63-char identifier limit.
+*/
+function deriveDbName(base) {
+	const token = randomUUID().replace(/-/g, "").slice(0, DB_NAME_TOKEN_LENGTH);
+	return `${databasePrefix(base)}${token}`;
+}
+async function withAdminClient(adminConn, fn) {
+	const client = new (await (importPg())).Client({ connectionString: adminConn });
+	await client.connect();
+	try {
+		return await fn((sql) => client.query(sql));
+	} finally {
+		await client.end();
+	}
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** True for transient errors worth retrying a `CREATE DATABASE ... TEMPLATE`. */
+function isTemplateBusy(error) {
+	const e = error;
+	return e?.code === "55006" || /is being accessed by other users/i.test(e?.message ?? "");
+}
+/**
+* Terminate every backend connected to `dbName` except the caller's own. Used
+* to evict lingering sessions on the template database so `CREATE DATABASE ...
+* TEMPLATE` (which requires the source to have no other connections) succeeds.
+*/
+async function terminateConnections(query, dbName) {
+	await query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = ${quoteLiteral(dbName)} AND pid <> pg_backend_pid()`);
+}
+/**
+* Clone the template database into `dbName`. `CREATE DATABASE ... TEMPLATE`
+* fails (SQLSTATE 55006) if any session is connected to the template, so we
+* proactively terminate lingering template backends before each attempt and
+* retry with exponential backoff while a concurrent clone briefly locks it.
+*/
+async function createDatabaseFromTemplate(adminConn, dbName, template, attempts = 10) {
+	const sql = `CREATE DATABASE ${quoteIdent(dbName)} TEMPLATE ${quoteIdent(template)}`;
+	for (let attempt = 0; attempt < attempts; attempt++) try {
+		await withAdminClient(adminConn, async (query) => {
+			await terminateConnections(query, template);
+			await query(sql);
+		});
+		return;
+	} catch (error) {
+		if (!isTemplateBusy(error) || attempt === attempts - 1) throw error;
+		const jitter = parseInt(randomUUID().slice(0, 2), 16);
+		await sleep(Math.min(50 * 2 ** attempt, 2e3) + jitter);
+	}
+}
+/** Drop a database, terminating any lingering connections. */
+async function dropDatabase(adminConn, dbName) {
+	await withAdminClient(adminConn, (query) => query(`DROP DATABASE IF EXISTS ${quoteIdent(dbName)} WITH (FORCE)`));
+}
+/**
+* Drop leaked per-file databases matching the prefix while leaving a concurrent
+* process's **live** databases intact.
+*
+* Multiple setups can run at once (CI sharding, several e2e projects). A blanket
+* "drop everything matching the prefix" sweep would delete a sibling process's
+* in-flight per-file databases. So we only drop databases that currently have
+* **no active backend connections** — i.e. true leaks from a crashed prior run.
+* A live per-file database always has the test worker's pool connected, so it is
+* skipped. The `WITH (FORCE)` covers the narrow race where a connection appears
+* between the check and the drop.
+*/
+async function sweepStaleDatabases(adminConn, prefix) {
+	const likePrefix = prefix.replace(/'/g, "''").replace(/[\\%_]/g, (c) => `\\${c}`);
+	await withAdminClient(adminConn, async (query) => {
+		const { rows } = await query(`SELECT d.datname FROM pg_database d WHERE d.datname LIKE '${likePrefix}%' ESCAPE '\\' AND NOT EXISTS (SELECT 1 FROM pg_stat_activity a WHERE a.datname = d.datname)`);
+		for (const { datname } of rows) await query(`DROP DATABASE IF EXISTS ${quoteIdent(datname)} WITH (FORCE)`);
+	});
+}
+/**
+* Run `fn` while holding a session-level Postgres advisory lock keyed to
+* `lockKey`, serializing template setup across concurrent processes (CI
+* sharding, multiple e2e projects) so they don't drop/recreate the template out
+* from under each other. The lock is released in `finally`.
+*/
+async function withAdvisoryLock(adminConn, lockKey, fn) {
+	return withAdminClient(adminConn, async (query) => {
+		await query(`SELECT pg_advisory_lock(hashtext(${quoteLiteral(lockKey)}))`);
+		try {
+			return await fn();
+		} finally {
+			await query(`SELECT pg_advisory_unlock(hashtext(${quoteLiteral(lockKey)}))`);
+		}
+	});
+}
+/** Schema source file extensions hashed into the template fingerprint. */
+const SCHEMA_FILE_RE = /\.(zmodel|prisma|sql)$/;
+/** Matches ZModel `import "..."` / `import '...'` statements. */
+const ZMODEL_IMPORT_RE = /^\s*import\s+['"]([^'"]+)['"]/gm;
+/**
+* Follow a ZModel file's `import` graph, collecting the root plus every
+* transitively imported `.zmodel` file — ZenStack supports multi-file schemas,
+* so editing an imported file must invalidate the fingerprint. Import paths
+* resolve relative to the importing file; the `.zmodel` extension is optional.
+* A missing import target is skipped (migration surfaces the real error).
+*/
+function collectZmodelImports(file, seen) {
+	if (seen.has(file)) return;
+	let content;
+	try {
+		content = readFileSync(file, "utf8");
+	} catch {
+		return;
+	}
+	seen.add(file);
+	for (const [, importPath] of content.matchAll(ZMODEL_IMPORT_RE)) {
+		const target = resolve(dirname(file), importPath);
+		collectZmodelImports(target.endsWith(".zmodel") ? target : `${target}.zmodel`, seen);
+	}
+}
+/**
+* Expand a schema path into the concrete files to hash. A directory contributes
+* every schema file in its tree; a single `.zmodel` file contributes its whole
+* `import` graph; any other file contributes itself.
+*/
+function collectSchemaFiles(path) {
+	if (statSync(path).isDirectory()) {
+		const out = [];
+		for (const entry of readdirSync(path, { withFileTypes: true })) {
+			const full = join(path, entry.name);
+			if (entry.isDirectory()) out.push(...collectSchemaFiles(full));
+			else if (SCHEMA_FILE_RE.test(entry.name)) out.push(full);
+		}
+		return out;
+	}
+	if (path.endsWith(".zmodel")) {
+		const seen = /* @__PURE__ */ new Set();
+		collectZmodelImports(path, seen);
+		return [...seen];
+	}
+	return [path];
+}
+/**
+* A content-derived fingerprint of the schema source(s) plus the migrate
+* routine. The template is reused across runs while this is unchanged; any edit
+* to a schema file — or to how migration runs — changes it and forces a rebuild.
+* Uses file basenames (not absolute paths) so it is stable across checkouts.
+*/
+function computeSchemaFingerprint(schema, migrate) {
+	const roots = Array.isArray(schema) ? schema : [schema];
+	const files = roots.flatMap(collectSchemaFiles).sort();
+	if (files.length === 0) throw new Error(`[stratal-testing] No schema files found for fingerprinting under: ${roots.join(", ")}`);
+	const hash = createHash("sha256");
+	for (const file of files) {
+		hash.update(basename(file));
+		hash.update("\0");
+		hash.update(readFileSync(file));
+		hash.update("\0");
+	}
+	hash.update(migrate.toString());
+	return hash.digest("hex");
+}
+/**
+* Read the template database's stored schema fingerprint (kept as the database
+* COMMENT). Returns `null` when the template does not exist or carries no
+* fingerprint. Database comments are NOT copied by `CREATE DATABASE ...
+* TEMPLATE`, so per-file clones never inherit it.
+*/
+async function readTemplateFingerprint(query, template) {
+	const { rows } = await query(`SELECT shobj_description(oid, 'pg_database') AS fingerprint FROM pg_database WHERE datname = ${quoteLiteral(template)}`);
+	return rows.length === 0 ? null : rows[0].fingerprint;
+}
+/**
+* Build a Vitest `globalSetup` default export that prepares the test database.
+*
+* - `'shared'` (default): migrates the base database in place (no isolation).
+* - `'database'`: under a Postgres advisory lock (so concurrent setups across
+*   CI shards / multiple e2e projects don't clobber each other), sweeps leaked
+*   per-file databases, then ensures a migrated template exists — ready to be
+*   cloned per test file.
+*
+* **Template reuse.** The template is fingerprinted from the `schema` source(s)
+* + the `migrate` routine and the fingerprint is stored as the template's
+* database COMMENT. On each run, a matching fingerprint means the schema is
+* unchanged and the existing template is reused as-is — `migrate` runs **only**
+* on the first run after a schema edit (or on a fresh database). The fingerprint
+* is stamped only after a successful migrate, so a match always implies a
+* complete template; there is no force/skip flag — reuse is purely fingerprint-
+* driven.
+*
+* **Concurrency model.** The reuse check + rebuild runs under
+* `pg_advisory_lock(hashtext(<template>))`, so only one process rebuilds the
+* template at a time. The stale-database sweep only drops per-file databases
+* with **no active connections**, leaving a sibling process's live databases
+* intact. Teardown deliberately does **not** sweep or drop the template: a
+* concurrent process may still be using both, and the next run's setup sweep is
+* the backstop for any leak.
+*
+* @example
+* ```ts
+* // test/global-setup.ts
+* import { createTestDatabaseGlobalSetup } from '@stratal/testing/database'
+*
+* export default createTestDatabaseGlobalSetup({
+*   schema: schemaPath, // file or directory — reused-when-unchanged fingerprint
+*   migrate: (conn) => execFileSync(zenstackBin, ['db', 'push', '--force-reset', `--schema=${schemaPath}`, '--accept-data-loss'],
+*     { env: { ...process.env, DATABASE_URL: conn }, stdio: 'inherit' }),
+* })
+* ```
+*/
+function createTestDatabaseGlobalSetup(opts) {
+	return async () => {
+		const base = opts.connectionString ?? process.env.DATABASE_URL;
+		if (!base) throw new Error("[stratal-testing] No connection string for test database setup. Set process.env.DATABASE_URL or pass `connectionString`.");
+		if (normalizeIsolation(opts.isolation ?? process.env["STRATAL_TEST_DB_ISOLATION"]) === "shared") {
+			await opts.migrate(base);
+			return;
+		}
+		if (!opts.schema) throw new Error("[stratal-testing] `schema` is required for database isolation. Pass the schema file(s) or directory so the migrated template can be reused across runs when unchanged (and rebuilt when it changes).");
+		const adminConn = deriveAdminConnectionString(base);
+		const template = opts.templateName ?? deriveTemplateName(base);
+		const prefix = databasePrefix(base);
+		const fingerprint = computeSchemaFingerprint(opts.schema, opts.migrate);
+		await withAdvisoryLock(adminConn, template, async () => {
+			await sweepStaleDatabases(adminConn, prefix);
+			if (await withAdminClient(adminConn, (query) => readTemplateFingerprint(query, template)) === fingerprint) return;
+			await withAdminClient(adminConn, async (query) => {
+				await query(`DROP DATABASE IF EXISTS ${quoteIdent(template)} WITH (FORCE)`);
+				await query(`CREATE DATABASE ${quoteIdent(template)}`);
+			});
+			await opts.migrate(buildConnectionString(base, template));
+			await withAdminClient(adminConn, (query) => query(`COMMENT ON DATABASE ${quoteIdent(template)} IS ${quoteLiteral(fingerprint)}`));
+		});
+	};
+}
+//#endregion
+export { createDatabaseFromTemplate as a, deriveAdminConnectionString as c, dropDatabase as d, normalizeIsolation as f, buildConnectionString as i, deriveDbName as l, DEFAULT_DB_BINDING as n, createTestDatabaseGlobalSetup as o, ISOLATION_ENV_VAR as r, databasePrefix as s, BINDING_ENV_VAR as t, deriveTemplateName as u };
+
+//# sourceMappingURL=database-B02eYKhE.mjs.map

package/dist/database-B02eYKhE.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-B02eYKhE.mjs","names":[],"sources":["../src/database/test-database.ts"],"sourcesContent":["/**\n * Test database isolation helpers.\n *\n * Implements database-per-test-file isolation for parallel e2e runs against\n * Postgres. A migrated **template** database is built once in global setup;\n * each test file clones it instantly via `CREATE DATABASE ... TEMPLATE` and\n * drops it on teardown. See `@stratal/testing/database`.\n *\n * `pg` is imported dynamically so this module loads without it — consumers\n * that don't use a database never pay the dependency.\n */\n\nimport { createHash, randomUUID } from 'node:crypto'\nimport { readFileSync, readdirSync, statSync } from 'node:fs'\nimport { basename, dirname, join, resolve } from 'node:path'\n\nimport type pg from 'pg'\n\n/** Postgres isolation mode for tests. */\nexport type DatabaseIsolation = 'shared' | 'database'\n\n/** Env var that selects the isolation mode (single source of truth). */\nexport const ISOLATION_ENV_VAR = 'STRATAL_TEST_DB_ISOLATION'\n\n/** Env var carrying the name of the Hyperdrive binding to isolate. */\nexport const BINDING_ENV_VAR = 'STRATAL_TEST_DB_BINDING'\n\n/** Default Hyperdrive binding name when none is configured. */\nexport const DEFAULT_DB_BINDING = 'DB'\n\n/**\n * Normalize an isolation value (from an option or env var) to a mode.\n * Anything other than the literal `'database'` resolves to `'shared'` — the\n * default — so parallel isolation is strictly opt-in.\n */\nexport function normalizeIsolation(value: string | undefined): DatabaseIsolation {\n  return value === 'database' ? 'database' : 'shared'\n}\n\n/**\n * Postgres' identifier length limit. Names longer than this are silently\n * truncated by the server, which would cause distinct logical names to collide\n * on the same physical database. We assert against it everywhere a name is\n * derived.\n */\nconst MAX_IDENTIFIER_LENGTH = 63\n\n/** Quote a Postgres identifier for safe interpolation into DDL. */\nfunction quoteIdent(name: string): string {\n  return `\"${name.replace(/\"/g, '\"\"')}\"`\n}\n\n/** Quote a Postgres string literal for safe interpolation into SQL. */\nfunction quoteLiteral(value: string): string {\n  return `'${value.replace(/'/g, \"''\")}'`\n}\n\n/**\n * Dynamically import `pg` (an optional peer), surfacing an actionable error\n * instead of a raw module-not-found when database isolation is requested\n * without the dependency installed.\n */\nasync function importPg(): Promise<typeof pg> {\n  try {\n    const { default: pg } = await import('pg')\n    return pg\n  } catch (error) {\n    throw new Error(\n      \"[stratal-testing] `pg` is required for database isolation but is not installed. \" +\n        'Install it: `npm install --save-dev pg` (or `yarn add -D pg`).',\n      { cause: error },\n    )\n  }\n}\n\n/**\n * Assert a derived identifier fits within Postgres' {@link MAX_IDENTIFIER_LENGTH}\n * limit. Throws a clear, actionable error instead of letting the server\n * silently truncate and collide names.\n */\nfunction assertIdentifierLength(name: string, kind: string): void {\n  if (name.length > MAX_IDENTIFIER_LENGTH) {\n    throw new Error(\n      `[stratal-testing] Derived ${kind} \"${name}\" is ${name.length} characters, ` +\n        `exceeding Postgres' ${MAX_IDENTIFIER_LENGTH}-character identifier limit. ` +\n        'Use a shorter base database name so the test-isolation suffix fits.',\n    )\n  }\n}\n\n/** Parse the database name out of a Postgres connection URL. */\nfunction databaseNameOf(connectionString: string): string {\n  const name = new URL(connectionString).pathname.replace(/^\\//, '')\n  return name || 'postgres'\n}\n\n/**\n * Derive an admin connection string pointing at the `postgres` maintenance\n * database. `CREATE`/`DROP DATABASE` cannot run on a connection bound to the\n * target database, so administration always goes through `postgres`.\n */\nexport function deriveAdminConnectionString(connectionString: string): string {\n  const url = new URL(connectionString)\n  url.pathname = '/postgres'\n  return url.toString()\n}\n\n/** Build a connection string identical to `base` but pointing at `dbName`. */\nexport function buildConnectionString(base: string, dbName: string): string {\n  const url = new URL(base)\n  url.pathname = `/${dbName}`\n  return url.toString()\n}\n\n/** Length of the random token appended by {@link deriveDbName}. */\nconst DB_NAME_TOKEN_LENGTH = 12\n\n/** The shared prefix for per-file databases, used as the leak-sweep key. */\nexport function databasePrefix(base: string): string {\n  const baseName = databaseNameOf(base).replace(/[^a-z0-9_]/gi, '_')\n  const prefix = `${baseName}_t_`\n  // The per-file name is `${prefix}${12-char token}`; assert the full budget so\n  // long base names fail loudly here instead of silently truncating + colliding.\n  assertIdentifierLength(`${prefix}${'x'.repeat(DB_NAME_TOKEN_LENGTH)}`, 'per-file database name')\n  return prefix\n}\n\n/** Name of the migrated template database cloned per file. */\nexport function deriveTemplateName(base: string): string {\n  const name = `${databaseNameOf(base).replace(/[^a-z0-9_]/gi, '_')}_template`\n  assertIdentifierLength(name, 'template database name')\n  return name\n}\n\n/**\n * Generate a unique per-`compile()` database name. Random (not path-based) so\n * it is collision-free across concurrent isolates and multiple modules in the\n * same file, and stays well within Postgres' 63-char identifier limit.\n */\nexport function deriveDbName(base: string): string {\n  const token = randomUUID().replace(/-/g, '').slice(0, DB_NAME_TOKEN_LENGTH)\n  return `${databasePrefix(base)}${token}`\n}\n\nasync function withAdminClient<T>(adminConn: string, fn: (query: (sql: string) => Promise<unknown>) => Promise<T>): Promise<T> {\n  const pg = await importPg()\n  const client = new pg.Client({ connectionString: adminConn })\n  await client.connect()\n  try {\n    return await fn((sql) => client.query(sql))\n  } finally {\n    await client.end()\n  }\n}\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))\n\n/** True for transient errors worth retrying a `CREATE DATABASE ... TEMPLATE`. */\nfunction isTemplateBusy(error: unknown): boolean {\n  const e = error as { code?: string; message?: string }\n  return e?.code === '55006' || /is being accessed by other users/i.test(e?.message ?? '')\n}\n\n/**\n * Terminate every backend connected to `dbName` except the caller's own. Used\n * to evict lingering sessions on the template database so `CREATE DATABASE ...\n * TEMPLATE` (which requires the source to have no other connections) succeeds.\n */\nasync function terminateConnections(query: (sql: string) => Promise<unknown>, dbName: string): Promise<void> {\n  await query(\n    `SELECT pg_terminate_backend(pid) FROM pg_stat_activity ` +\n      `WHERE datname = ${quoteLiteral(dbName)} AND pid <> pg_backend_pid()`,\n  )\n}\n\n/**\n * Clone the template database into `dbName`. `CREATE DATABASE ... TEMPLATE`\n * fails (SQLSTATE 55006) if any session is connected to the template, so we\n * proactively terminate lingering template backends before each attempt and\n * retry with exponential backoff while a concurrent clone briefly locks it.\n */\nexport async function createDatabaseFromTemplate(\n  adminConn: string,\n  dbName: string,\n  template: string,\n  attempts = 10,\n): Promise<void> {\n  const sql = `CREATE DATABASE ${quoteIdent(dbName)} TEMPLATE ${quoteIdent(template)}`\n  for (let attempt = 0; attempt < attempts; attempt++) {\n    try {\n      await withAdminClient(adminConn, async (query) => {\n        // Evict any lingering sessions on the template; otherwise the clone\n        // below fails with 55006 (\"source database is being accessed by other\n        // users\"). Our own admin connection is excluded by pid.\n        await terminateConnections(query, template)\n        await query(sql)\n      })\n      return\n    } catch (error) {\n      if (!isTemplateBusy(error) || attempt === attempts - 1) throw error\n      const jitter = parseInt(randomUUID().slice(0, 2), 16)\n      await sleep(Math.min(50 * 2 ** attempt, 2000) + jitter)\n    }\n  }\n}\n\n/** Drop a database, terminating any lingering connections. */\nexport async function dropDatabase(adminConn: string, dbName: string): Promise<void> {\n  await withAdminClient(adminConn, (query) => query(`DROP DATABASE IF EXISTS ${quoteIdent(dbName)} WITH (FORCE)`))\n}\n\n/**\n * Drop leaked per-file databases matching the prefix while leaving a concurrent\n * process's **live** databases intact.\n *\n * Multiple setups can run at once (CI sharding, several e2e projects). A blanket\n * \"drop everything matching the prefix\" sweep would delete a sibling process's\n * in-flight per-file databases. So we only drop databases that currently have\n * **no active backend connections** — i.e. true leaks from a crashed prior run.\n * A live per-file database always has the test worker's pool connected, so it is\n * skipped. The `WITH (FORCE)` covers the narrow race where a connection appears\n * between the check and the drop.\n */\nasync function sweepStaleDatabases(adminConn: string, prefix: string): Promise<void> {\n  // Escape both the SQL-string quote and the LIKE metacharacters (`\\`, `%`, `_`)\n  // so a prefix containing `_` (a single-char wildcard) can't over-match and drop\n  // an unrelated database. `\\` is the explicit ESCAPE character below.\n  const likePrefix = prefix\n    .replace(/'/g, \"''\")\n    .replace(/[\\\\%_]/g, (c) => `\\\\${c}`)\n  await withAdminClient(adminConn, async (query) => {\n    const { rows } = (await query(\n      `SELECT d.datname FROM pg_database d ` +\n        `WHERE d.datname LIKE '${likePrefix}%' ESCAPE '\\\\' ` +\n        `AND NOT EXISTS (SELECT 1 FROM pg_stat_activity a WHERE a.datname = d.datname)`,\n    )) as { rows: { datname: string }[] }\n    for (const { datname } of rows) {\n      await query(`DROP DATABASE IF EXISTS ${quoteIdent(datname)} WITH (FORCE)`)\n    }\n  })\n}\n\n/**\n * Run `fn` while holding a session-level Postgres advisory lock keyed to\n * `lockKey`, serializing template setup across concurrent processes (CI\n * sharding, multiple e2e projects) so they don't drop/recreate the template out\n * from under each other. The lock is released in `finally`.\n */\nasync function withAdvisoryLock<T>(adminConn: string, lockKey: string, fn: () => Promise<T>): Promise<T> {\n  return withAdminClient(adminConn, async (query) => {\n    await query(`SELECT pg_advisory_lock(hashtext(${quoteLiteral(lockKey)}))`)\n    try {\n      return await fn()\n    } finally {\n      await query(`SELECT pg_advisory_unlock(hashtext(${quoteLiteral(lockKey)}))`)\n    }\n  })\n}\n\n/** Schema source file extensions hashed into the template fingerprint. */\nconst SCHEMA_FILE_RE = /\\.(zmodel|prisma|sql)$/\n\n/** Matches ZModel `import \"...\"` / `import '...'` statements. */\nconst ZMODEL_IMPORT_RE = /^\\s*import\\s+['\"]([^'\"]+)['\"]/gm\n\n/**\n * Follow a ZModel file's `import` graph, collecting the root plus every\n * transitively imported `.zmodel` file — ZenStack supports multi-file schemas,\n * so editing an imported file must invalidate the fingerprint. Import paths\n * resolve relative to the importing file; the `.zmodel` extension is optional.\n * A missing import target is skipped (migration surfaces the real error).\n */\nfunction collectZmodelImports(file: string, seen: Set<string>): void {\n  if (seen.has(file)) return\n  let content: string\n  try {\n    content = readFileSync(file, 'utf8')\n  } catch {\n    return // missing import target — not part of the fingerprint\n  }\n  seen.add(file)\n  for (const [, importPath] of content.matchAll(ZMODEL_IMPORT_RE)) {\n    const target = resolve(dirname(file), importPath)\n    collectZmodelImports(target.endsWith('.zmodel') ? target : `${target}.zmodel`, seen)\n  }\n}\n\n/**\n * Expand a schema path into the concrete files to hash. A directory contributes\n * every schema file in its tree; a single `.zmodel` file contributes its whole\n * `import` graph; any other file contributes itself.\n */\nfunction collectSchemaFiles(path: string): string[] {\n  if (statSync(path).isDirectory()) {\n    const out: string[] = []\n    for (const entry of readdirSync(path, { withFileTypes: true })) {\n      const full = join(path, entry.name)\n      if (entry.isDirectory()) out.push(...collectSchemaFiles(full))\n      else if (SCHEMA_FILE_RE.test(entry.name)) out.push(full)\n    }\n    return out\n  }\n  if (path.endsWith('.zmodel')) {\n    const seen = new Set<string>()\n    collectZmodelImports(path, seen)\n    return [...seen]\n  }\n  return [path]\n}\n\n/**\n * A content-derived fingerprint of the schema source(s) plus the migrate\n * routine. The template is reused across runs while this is unchanged; any edit\n * to a schema file — or to how migration runs — changes it and forces a rebuild.\n * Uses file basenames (not absolute paths) so it is stable across checkouts.\n */\nfunction computeSchemaFingerprint(\n  schema: string | string[],\n  migrate: TestDatabaseGlobalSetupOptions['migrate'],\n): string {\n  const roots = Array.isArray(schema) ? schema : [schema]\n  const files = roots.flatMap(collectSchemaFiles).sort()\n  if (files.length === 0) {\n    throw new Error(\n      `[stratal-testing] No schema files found for fingerprinting under: ${roots.join(', ')}`,\n    )\n  }\n  const hash = createHash('sha256')\n  for (const file of files) {\n    hash.update(basename(file))\n    hash.update('\\0')\n    hash.update(readFileSync(file))\n    hash.update('\\0')\n  }\n  hash.update(migrate.toString())\n  return hash.digest('hex')\n}\n\n/**\n * Read the template database's stored schema fingerprint (kept as the database\n * COMMENT). Returns `null` when the template does not exist or carries no\n * fingerprint. Database comments are NOT copied by `CREATE DATABASE ...\n * TEMPLATE`, so per-file clones never inherit it.\n */\nasync function readTemplateFingerprint(\n  query: (sql: string) => Promise<unknown>,\n  template: string,\n): Promise<string | null> {\n  const { rows } = (await query(\n    `SELECT shobj_description(oid, 'pg_database') AS fingerprint ` +\n      `FROM pg_database WHERE datname = ${quoteLiteral(template)}`,\n  )) as { rows: { fingerprint: string | null }[] }\n  return rows.length === 0 ? null : rows[0].fingerprint\n}\n\n/** Options for {@link createTestDatabaseGlobalSetup}. */\nexport interface TestDatabaseGlobalSetupOptions {\n  /**\n   * Run migrations against the given connection string. In `'database'` mode\n   * the string points at the template database; in `'shared'` mode at the base\n   * database. Framework consumers typically run `zenstack db push` here.\n   */\n  migrate: (connectionString: string) => void | Promise<void>\n  /**\n   * Schema source(s) — a file or directory path, or a list of them. Their\n   * contents (plus the `migrate` routine) are hashed into a fingerprint; the\n   * template is reused across runs while the fingerprint is unchanged and\n   * rebuilt + re-migrated when it changes, so only the first run after a schema\n   * edit pays the migration cost. **Required** for `'database'` isolation.\n   *\n   * For a ZenStack multi-file schema, pass the **root `.zmodel`** — its `import`\n   * graph is followed, so editing any imported file invalidates the fingerprint.\n   * A directory path hashes every `.zmodel`/`.prisma`/`.sql` file in its tree.\n   */\n  schema?: string | string[]\n  /** Isolation mode. Defaults to {@link ISOLATION_ENV_VAR} or `'shared'`. */\n  isolation?: DatabaseIsolation\n  /** Base/admin connection string. Defaults to `process.env.DATABASE_URL`. */\n  connectionString?: string\n  /** Template database name. Defaults to `<baseDbName>_template`. */\n  templateName?: string\n}\n\n/**\n * Build a Vitest `globalSetup` default export that prepares the test database.\n *\n * - `'shared'` (default): migrates the base database in place (no isolation).\n * - `'database'`: under a Postgres advisory lock (so concurrent setups across\n *   CI shards / multiple e2e projects don't clobber each other), sweeps leaked\n *   per-file databases, then ensures a migrated template exists — ready to be\n *   cloned per test file.\n *\n * **Template reuse.** The template is fingerprinted from the `schema` source(s)\n * + the `migrate` routine and the fingerprint is stored as the template's\n * database COMMENT. On each run, a matching fingerprint means the schema is\n * unchanged and the existing template is reused as-is — `migrate` runs **only**\n * on the first run after a schema edit (or on a fresh database). The fingerprint\n * is stamped only after a successful migrate, so a match always implies a\n * complete template; there is no force/skip flag — reuse is purely fingerprint-\n * driven.\n *\n * **Concurrency model.** The reuse check + rebuild runs under\n * `pg_advisory_lock(hashtext(<template>))`, so only one process rebuilds the\n * template at a time. The stale-database sweep only drops per-file databases\n * with **no active connections**, leaving a sibling process's live databases\n * intact. Teardown deliberately does **not** sweep or drop the template: a\n * concurrent process may still be using both, and the next run's setup sweep is\n * the backstop for any leak.\n *\n * @example\n * ```ts\n * // test/global-setup.ts\n * import { createTestDatabaseGlobalSetup } from '@stratal/testing/database'\n *\n * export default createTestDatabaseGlobalSetup({\n *   schema: schemaPath, // file or directory — reused-when-unchanged fingerprint\n *   migrate: (conn) => execFileSync(zenstackBin, ['db', 'push', '--force-reset', `--schema=${schemaPath}`, '--accept-data-loss'],\n *     { env: { ...process.env, DATABASE_URL: conn }, stdio: 'inherit' }),\n * })\n * ```\n */\nexport function createTestDatabaseGlobalSetup(\n  opts: TestDatabaseGlobalSetupOptions,\n): () => Promise<void | (() => Promise<void>)> {\n  return async () => {\n    const base = opts.connectionString ?? process.env.DATABASE_URL\n    if (!base) {\n      throw new Error(\n        '[stratal-testing] No connection string for test database setup. Set process.env.DATABASE_URL or pass `connectionString`.',\n      )\n    }\n\n    const isolation = normalizeIsolation(opts.isolation ?? process.env[ISOLATION_ENV_VAR])\n    if (isolation === 'shared') {\n      await opts.migrate(base)\n      return\n    }\n\n    if (!opts.schema) {\n      throw new Error(\n        '[stratal-testing] `schema` is required for database isolation. Pass the schema ' +\n          'file(s) or directory so the migrated template can be reused across runs when ' +\n          'unchanged (and rebuilt when it changes).',\n      )\n    }\n\n    const adminConn = deriveAdminConnectionString(base)\n    const template = opts.templateName ?? deriveTemplateName(base)\n    const prefix = databasePrefix(base)\n    const fingerprint = computeSchemaFingerprint(opts.schema, opts.migrate)\n\n    // Serialize template rebuild across concurrent setups so they don't drop or\n    // migrate the template out from under each other.\n    await withAdvisoryLock(adminConn, template, async () => {\n      await sweepStaleDatabases(adminConn, prefix)\n\n      // Reuse the existing template when its stored fingerprint matches — the\n      // schema is unchanged, so the migrated template is ready to clone. Only a\n      // fingerprint mismatch (or a missing template) pays the migration cost.\n      const current = await withAdminClient(adminConn, (query) =>\n        readTemplateFingerprint(query, template),\n      )\n      if (current === fingerprint) return\n\n      await withAdminClient(adminConn, async (query) => {\n        await query(`DROP DATABASE IF EXISTS ${quoteIdent(template)} WITH (FORCE)`)\n        await query(`CREATE DATABASE ${quoteIdent(template)}`)\n      })\n      await opts.migrate(buildConnectionString(base, template))\n      // Stamp the fingerprint only after a successful migrate, so a matching\n      // fingerprint always implies a complete, ready template. Database COMMENTs\n      // are not copied by CREATE DATABASE ... TEMPLATE, so clones stay clean.\n      await withAdminClient(adminConn, (query) =>\n        query(`COMMENT ON DATABASE ${quoteIdent(template)} IS ${quoteLiteral(fingerprint)}`),\n      )\n    })\n\n    // No teardown hook: anything destructive here (sweeping per-file databases\n    // or dropping the template) could clobber a concurrent process that is still\n    // running. The next run's setup sweep (connection-guarded) reclaims leaks.\n  }\n}\n"],"mappings":"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"}

package/dist/decorate-B7nr7eBl.mjs

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.133.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as t };

package/dist/feature-flags/index.d.mts

@@ -0,0 +1,2 @@
+import { n as FakeFeatureFlagService, r as FlagValue, t as FEATURE_FLAG_SERVICE_TOKEN } from "../index-qgWNJRdC.mjs";
+export { FEATURE_FLAG_SERVICE_TOKEN, FakeFeatureFlagService, type FlagValue };

package/dist/feature-flags/index.mjs

@@ -0,0 +1,2 @@
+import { n as FakeFeatureFlagService, t as FEATURE_FLAG_SERVICE_TOKEN } from "../feature-flags-BiLhfSGh.mjs";
+export { FEATURE_FLAG_SERVICE_TOKEN, FakeFeatureFlagService };

package/dist/feature-flags-BiLhfSGh.mjs

@@ -0,0 +1,86 @@
+import { t as __decorate } from "./decorate-B7nr7eBl.mjs";
+import { Singleton } from "stratal/di";
+//#region src/feature-flags/fake-feature-flag.service.ts
+/**
+* Global DI token for the feature-flags service.
+*
+* Mirrors `FEATURE_FLAG_TOKENS.FeatureFlagService` from `@stratal/feature-flags`
+* — `Symbol.for(...)` resolves to the same symbol across packages via the global
+* registry. Declared here so `@stratal/testing` needs no dependency on the
+* optional feature-flags package. Keep this string in sync with
+* `packages/feature-flags/src/feature-flags.tokens.ts`.
+*/
+const FEATURE_FLAG_SERVICE_TOKEN = Symbol.for("stratal:feature-flags:service");
+let FakeFeatureFlagService = class FakeFeatureFlagService {
+	flags = /* @__PURE__ */ new Map();
+	/** Set a single flag value. */
+	set(flagKey, value) {
+		this.flags.set(flagKey, value);
+		return this;
+	}
+	/** Replace all configured flags with the given map. */
+	setAll(flags) {
+		this.reset();
+		for (const [key, value] of Object.entries(flags)) this.flags.set(key, value);
+		return this;
+	}
+	/** Clear every configured flag. */
+	reset() {
+		this.flags.clear();
+		return this;
+	}
+	async get(flagKey, defaultValue) {
+		return Promise.resolve(this.flags.has(flagKey) ? this.flags.get(flagKey) : defaultValue);
+	}
+	async getBooleanValue(flagKey, defaultValue = false) {
+		return this.resolve(flagKey, defaultValue);
+	}
+	async getStringValue(flagKey, defaultValue = "") {
+		return this.resolve(flagKey, defaultValue);
+	}
+	async getNumberValue(flagKey, defaultValue = 0) {
+		return this.resolve(flagKey, defaultValue);
+	}
+	async getObjectValue(flagKey, defaultValue = {}) {
+		return this.resolve(flagKey, defaultValue);
+	}
+	async getBooleanDetails(flagKey, defaultValue = false) {
+		return this.details(flagKey, await this.getBooleanValue(flagKey, defaultValue));
+	}
+	async getStringDetails(flagKey, defaultValue = "") {
+		return this.details(flagKey, await this.getStringValue(flagKey, defaultValue));
+	}
+	async getNumberDetails(flagKey, defaultValue = 0) {
+		return this.details(flagKey, await this.getNumberValue(flagKey, defaultValue));
+	}
+	async getObjectDetails(flagKey, defaultValue = {}) {
+		return this.details(flagKey, await this.getObjectValue(flagKey, defaultValue));
+	}
+	/** Returns every configured flag as a `{ key: value }` map. */
+	async all() {
+		return Promise.resolve(Object.fromEntries(this.flags));
+	}
+	/** Switching Flagship apps is a no-op in the fake. */
+	use() {
+		return this;
+	}
+	/** The binding name this instance targets. */
+	get app() {
+		return "fake";
+	}
+	resolve(flagKey, defaultValue) {
+		return Promise.resolve(this.flags.has(flagKey) ? this.flags.get(flagKey) : defaultValue);
+	}
+	details(flagKey, value) {
+		return {
+			flagKey,
+			value,
+			reason: "fake"
+		};
+	}
+};
+FakeFeatureFlagService = __decorate([Singleton(FEATURE_FLAG_SERVICE_TOKEN)], FakeFeatureFlagService);
+//#endregion
+export { FakeFeatureFlagService as n, FEATURE_FLAG_SERVICE_TOKEN as t };
+
+//# sourceMappingURL=feature-flags-BiLhfSGh.mjs.map

package/dist/feature-flags-BiLhfSGh.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags-BiLhfSGh.mjs","names":[],"sources":["../src/feature-flags/fake-feature-flag.service.ts"],"sourcesContent":["import { Singleton } from 'stratal/di';\n\n/**\n * Global DI token for the feature-flags service.\n *\n * Mirrors `FEATURE_FLAG_TOKENS.FeatureFlagService` from `@stratal/feature-flags`\n * — `Symbol.for(...)` resolves to the same symbol across packages via the global\n * registry. Declared here so `@stratal/testing` needs no dependency on the\n * optional feature-flags package. Keep this string in sync with\n * `packages/feature-flags/src/feature-flags.tokens.ts`.\n */\nexport const FEATURE_FLAG_SERVICE_TOKEN = Symbol.for('stratal:feature-flags:service')\n\n/** A value a feature flag can resolve to. */\nexport type FlagValue = boolean | string | number | object\n\ninterface FakeFlagDetails<T> {\n  flagKey: string\n  value: T\n  reason: string\n}\n\n/**\n * FakeFeatureFlagService\n *\n * In-memory stand-in for `@stratal/feature-flags`'s request-scoped\n * `FeatureFlagService`, auto-registered by the testing module so feature-gated\n * code resolves without a real Cloudflare Flagship binding (which only exists at\n * runtime). Mirrors the real service's public evaluation surface.\n *\n * Unset flags return the per-call default (or the type's zero value). Configure\n * values with {@link set} / {@link setAll}; access it in tests via\n * `module.featureFlags`.\n *\n * @example\n * ```typescript\n * module.featureFlags.set('new-checkout', true)\n * const enabled = await flags.getBooleanValue('new-checkout') // true\n * ```\n */\n@Singleton(FEATURE_FLAG_SERVICE_TOKEN)\nexport class FakeFeatureFlagService {\n  private readonly flags = new Map<string, FlagValue>()\n\n  // ==================== CONFIGURATION ====================\n\n  /** Set a single flag value. */\n  set(flagKey: string, value: FlagValue): this {\n    this.flags.set(flagKey, value)\n    return this\n  }\n\n  /** Replace all configured flags with the given map. */\n  setAll(flags: Record<string, FlagValue>): this {\n    this.reset()\n    for (const [key, value] of Object.entries(flags)) this.flags.set(key, value)\n    return this\n  }\n\n  /** Clear every configured flag. */\n  reset(): this {\n    this.flags.clear()\n    return this\n  }\n\n  // ==================== EVALUATION ====================\n\n  async get(flagKey: string, defaultValue?: unknown): Promise<unknown> {\n    return Promise.resolve(this.flags.has(flagKey) ? this.flags.get(flagKey) : defaultValue)\n  }\n\n  async getBooleanValue(flagKey: string, defaultValue = false): Promise<boolean> {\n    return this.resolve(flagKey, defaultValue)\n  }\n\n  async getStringValue(flagKey: string, defaultValue = ''): Promise<string> {\n    return this.resolve(flagKey, defaultValue)\n  }\n\n  async getNumberValue(flagKey: string, defaultValue = 0): Promise<number> {\n    return this.resolve(flagKey, defaultValue)\n  }\n\n  async getObjectValue<T extends object>(flagKey: string, defaultValue: T = {} as T): Promise<T> {\n    return this.resolve(flagKey, defaultValue)\n  }\n\n  async getBooleanDetails(flagKey: string, defaultValue = false): Promise<FakeFlagDetails<boolean>> {\n    return this.details(flagKey, await this.getBooleanValue(flagKey, defaultValue))\n  }\n\n  async getStringDetails(flagKey: string, defaultValue = ''): Promise<FakeFlagDetails<string>> {\n    return this.details(flagKey, await this.getStringValue(flagKey, defaultValue))\n  }\n\n  async getNumberDetails(flagKey: string, defaultValue = 0): Promise<FakeFlagDetails<number>> {\n    return this.details(flagKey, await this.getNumberValue(flagKey, defaultValue))\n  }\n\n  async getObjectDetails<T extends object>(flagKey: string, defaultValue: T = {} as T): Promise<FakeFlagDetails<T>> {\n    return this.details(flagKey, await this.getObjectValue(flagKey, defaultValue))\n  }\n\n  /** Returns every configured flag as a `{ key: value }` map. */\n  async all(): Promise<Record<string, FlagValue>> {\n    return Promise.resolve(Object.fromEntries(this.flags))\n  }\n\n  /** Switching Flagship apps is a no-op in the fake. */\n  use(): this {\n    return this\n  }\n\n  /** The binding name this instance targets. */\n  // oxlint-disable-next-line typescript/class-literal-property-style\n  get app(): string {\n    return 'fake'\n  }\n\n  // ==================== INTERNAL ====================\n\n  private resolve<T extends FlagValue>(flagKey: string, defaultValue: T): Promise<T> {\n    return Promise.resolve(this.flags.has(flagKey) ? (this.flags.get(flagKey) as T) : defaultValue)\n  }\n\n  private details<T>(flagKey: string, value: T): FakeFlagDetails<T> {\n    return { flagKey, value, reason: 'fake' }\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,6BAA6B,OAAO,IAAI,+BAA+B;AA8B7E,IAAA,yBAAA,MAAM,uBAAuB;CAClC,wBAAyB,IAAI,IAAuB;;CAKpD,IAAI,SAAiB,OAAwB;EAC3C,KAAK,MAAM,IAAI,SAAS,KAAK;EAC7B,OAAO;CACT;;CAGA,OAAO,OAAwC;EAC7C,KAAK,MAAM;EACX,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAAG,KAAK,MAAM,IAAI,KAAK,KAAK;EAC3E,OAAO;CACT;;CAGA,QAAc;EACZ,KAAK,MAAM,MAAM;EACjB,OAAO;CACT;CAIA,MAAM,IAAI,SAAiB,cAA0C;EACnE,OAAO,QAAQ,QAAQ,KAAK,MAAM,IAAI,OAAO,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,YAAY;CACzF;CAEA,MAAM,gBAAgB,SAAiB,eAAe,OAAyB;EAC7E,OAAO,KAAK,QAAQ,SAAS,YAAY;CAC3C;CAEA,MAAM,eAAe,SAAiB,eAAe,IAAqB;EACxE,OAAO,KAAK,QAAQ,SAAS,YAAY;CAC3C;CAEA,MAAM,eAAe,SAAiB,eAAe,GAAoB;EACvE,OAAO,KAAK,QAAQ,SAAS,YAAY;CAC3C;CAEA,MAAM,eAAiC,SAAiB,eAAkB,CAAC,GAAoB;EAC7F,OAAO,KAAK,QAAQ,SAAS,YAAY;CAC3C;CAEA,MAAM,kBAAkB,SAAiB,eAAe,OAA0C;EAChG,OAAO,KAAK,QAAQ,SAAS,MAAM,KAAK,gBAAgB,SAAS,YAAY,CAAC;CAChF;CAEA,MAAM,iBAAiB,SAAiB,eAAe,IAAsC;EAC3F,OAAO,KAAK,QAAQ,SAAS,MAAM,KAAK,eAAe,SAAS,YAAY,CAAC;CAC/E;CAEA,MAAM,iBAAiB,SAAiB,eAAe,GAAqC;EAC1F,OAAO,KAAK,QAAQ,SAAS,MAAM,KAAK,eAAe,SAAS,YAAY,CAAC;CAC/E;CAEA,MAAM,iBAAmC,SAAiB,eAAkB,CAAC,GAAqC;EAChH,OAAO,KAAK,QAAQ,SAAS,MAAM,KAAK,eAAe,SAAS,YAAY,CAAC;CAC/E;;CAGA,MAAM,MAA0C;EAC9C,OAAO,QAAQ,QAAQ,OAAO,YAAY,KAAK,KAAK,CAAC;CACvD;;CAGA,MAAY;EACV,OAAO;CACT;;CAIA,IAAI,MAAc;EAChB,OAAO;CACT;CAIA,QAAqC,SAAiB,cAA6B;EACjF,OAAO,QAAQ,QAAQ,KAAK,MAAM,IAAI,OAAO,IAAK,KAAK,MAAM,IAAI,OAAO,IAAU,YAAY;CAChG;CAEA,QAAmB,SAAiB,OAA8B;EAChE,OAAO;GAAE;GAAS;GAAO,QAAQ;EAAO;CAC1C;AACF;qCAxFC,UAAU,0BAA0B,CAAA,GAAA,sBAAA"}