@shivaedev/test-sql 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.11.0 - 2026-10-30
+
+### Added
+
+- `raceWithLock` holds a native PostgreSQL row, table or advisory lock until every competing call is queued, then releases the holder and returns each call's result or typed failure in input order.
+
+### Changed
+
+- Require Effect 4.0.6 and align the Effect companion package peers and generated starter catalog to the same exact release. Install the 4.0.6 Effect stack together.
+
+### Fixed
+
+- Register hosted RPC cache-control handling through Effect 4.0.6's request-scoped pre-response API so responses keep `private, no-store`.
+- Accept native RPC's `application/x-ndjson` media type while preserving `application/ndjson` callers at the transport guard.
+- Keep subscriptions open after their HTTP request body completes; closing the socket still cancels them.
+
 ## 0.10.2 - 2026-10-28
 
 ### Changed

package/README.md

@@ -8,11 +8,9 @@ Table cleanup couples tests to the order they run. A rollback test keeps its wri
 
 ```ts
 effectApp("renames an item", function* () {
-  const sql = yield* SqlClient.SqlClient;
-  yield* sql`update items set name = 'Renamed' where id = 1`;
-  expect(yield* sql`select name from items where id = 1`).toEqual([
-    { name: "Renamed" },
-  ]);
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`update items set name = 'Renamed' where id = 1`;
+	expect(yield* sql`select name from items where id = 1`).toEqual([{ name: "Renamed" }]);
 });
 ```
 
@@ -37,27 +35,27 @@ import { makePostgresTestLayer } from "@shivaedev/test-sql/server/postgres.ts";
 import { withTestTransaction } from "@shivaedev/test-sql/server/withTestTransaction.ts";
 
 const layer = makePostgresTestLayer({
-  url: Redacted.make(Effect.runSync(Config.String("TEST_DATABASE_URL"))),
-  migrations: {
-    lockTimeout: "5 seconds",
-    loader: Migrator.fromRecord({
-      "1_create_items": Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient;
-        yield* sql`create table items (id integer primary key, name text not null)`;
-      }),
-    }),
-  },
-  fixtures: Effect.gen(function* () {
-    const sql = yield* SqlClient.SqlClient;
-    yield* sql`insert into items values (1, 'Original')`;
-  }),
+	url: Redacted.make(Effect.runSync(Config.String("TEST_DATABASE_URL"))),
+	migrations: {
+		lockTimeout: "5 seconds",
+		loader: Migrator.fromRecord({
+			"1_create_items": Effect.gen(function* () {
+				const sql = yield* SqlClient.SqlClient;
+				yield* sql`create table items (id integer primary key, name text not null)`;
+			}),
+		}),
+	},
+	fixtures: Effect.gen(function* () {
+		const sql = yield* SqlClient.SqlClient;
+		yield* sql`insert into items values (1, 'Original')`;
+	}),
 });
 
 export const { effectApp } = makeEffectIt({
-  layer,
-  clock: "live",
-  around: withTestTransaction,
-  makeHarness: () => Effect.void,
+	layer,
+	clock: "live",
+	around: withTestTransaction,
+	makeHarness: () => Effect.void,
 });
 ```
 
@@ -69,13 +67,14 @@ Fixtures can also be a `PostgresTestLoader`: a callback from the migrated templa
 import * as PgClient from "@effect/sql-pg/PgClient";
 
 const layer = makePostgresTestLayer({
-  url,
-  migrations: appMigrations,
-  fixtures: (templateUrl) => Effect.gen(function* () {
-    const client = yield* PgClient.makeClient({ url: templateUrl });
-    yield* client`create table app_fixture (name text not null)`;
-    yield* client`insert into app_fixture values ('Original')`;
-  }),
+	url,
+	migrations: appMigrations,
+	fixtures: (templateUrl) =>
+		Effect.gen(function* () {
+			const client = yield* PgClient.makeClient({ url: templateUrl });
+			yield* client`create table app_fixture (name text not null)`;
+			yield* client`insert into app_fixture values ('Original')`;
+		}),
 });
 ```
 
@@ -85,8 +84,8 @@ Supply `initialize` instead of `migrations` when the application already owns it
 
 ```ts
 const layer = makePostgresTestLayer({
-  url: testDatabaseUrl,
-  initialize: (templateUrl) => migrateDatabase(templateUrl),
+	url: testDatabaseUrl,
+	initialize: (templateUrl) => migrateDatabase(templateUrl),
 });
 ```
 
@@ -98,9 +97,9 @@ Choose exactly one of `migrations` and `initialize`. The initializer is an Effec
 
 ```ts
 const layer = makePostgresTestLayer({
-  ...appClientOptions,
-  url: testDatabaseUrl,
-  migrations: appMigrations,
+	...appClientOptions,
+	url: testDatabaseUrl,
+	migrations: appMigrations,
 });
 ```
 
@@ -108,13 +107,13 @@ Declare the mapping once in `appClientOptions`, for example with `clientOptions(
 
 ### Budget PostgreSQL connections
 
-Each database pool opens connections on demand, with a default maximum of **two**: the shared database can use two, and each active per-test or per-story clone can use another two. Preparation uses the same limit and closes before tests start. An administrative connection exists only during a create or drop operation and closes as soon as that operation finishes; idle workers keep no administrative connection. Set `maxConnections` on `makePostgresTestLayer` to override the limit for the suite's preparation, shared and isolated pools:
+Each database pool opens connections on demand, with a default maximum of two: the shared database can use two, and each active per-test or per-story clone can use another two. Preparation uses the same limit and closes before tests start. An administrative connection exists only during a create or drop operation and closes as soon as that operation finishes; idle workers keep no administrative connection. Set `maxConnections` on `makePostgresTestLayer` to override the limit for the suite's preparation, shared and isolated pools:
 
 ```ts
 const layer = makePostgresTestLayer({
-  url,
-  migrations,
-  maxConnections: 3,
+	url,
+	migrations,
+	maxConnections: 3,
 });
 ```
 
@@ -142,10 +141,12 @@ An isolated block can live inside the rollback tester above:
 import { withIsolatedDatabase } from "@shivaedev/test-sql/server/withIsolatedDatabase.ts";
 
 effectApp("commits in its own database", function* () {
-  yield* withIsolatedDatabase(Effect.gen(function* () {
-    const sql = yield* SqlClient.SqlClient;
-    yield* sql`update items set name = 'Committed' where id = 1`;
-  }));
+	yield* withIsolatedDatabase(
+		Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			yield* sql`update items set name = 'Committed' where id = 1`;
+		}),
+	);
 });
 ```
 
@@ -153,6 +154,23 @@ The clone starts from the template, including the original fixtures, even if the
 
 Inside an isolated block, `PostgresTestDatabase.url` names that clone. Use it to acquire additional native PostgreSQL connections in the block's scope. Native SQL services are replaced in the block's Context; application services acquired earlier retain the client they captured. Build application service Layers inside the isolated block when they acquire SQL clients; use `Layer.fresh` when reusing a Layer definition already acquired by the worker. Keep servers and background fibers in that scope so they finish before the database is dropped. Separate databases isolate database contents; external services and server capacity need separate planning.
 
+### Race stories
+
+Use `raceWithLock` with a live story clock inside an isolated database, outside a wrapping transaction. Supply the native SQL Effect that takes a row, table or transaction advisory lock, and one Effect per competing call. The helper holds the lock in a separate transaction, starts the calls, and waits for PostgreSQL's blocker graph to contain every contender before releasing the holder. Keep other lock-taking work out of that database during the race, and allow at least `effects.length + 1` pool connections. Contenders keep their own transaction and service conventions.
+
+```ts
+import { raceWithLock } from "@shivaedev/test-sql/server/raceWithLock.ts";
+
+const results = yield* raceWithLock({
+	lock: sql`lock table items in share mode`,
+	effects: [claimLastPlace(), claimLastPlace(), claimLastPlace()],
+});
+expect(results.filter(Result.isSuccess)).toHaveLength(1);
+expect(results.filter(Result.isFailure).map((result) => result.failure)).toEqual(["full", "full"]);
+```
+
+`claimLastPlace` is the application's guarded write, failing with the typed `"full"` value when no place remains; `Result` is Effect's native `Result` module. Results stay in input order, including each call's typed failure. The holder rolls back by default, discarding any writes in `lock`; set `release: "commit"` when a contender must observe the holder's committed write. The default timeout is five seconds; `timeout` accepts an Effect duration. Defects and interruption retain their native failure kind, and the helper's scope owns the holder and competing fibers.
+
 ### Choose an empty database per story or trait
 
 The default clone is migrated. A first-deploy or upgrade block can select the empty template from the same Layer:
@@ -180,26 +198,24 @@ import { withIsolatedDatabase } from "@shivaedev/test-sql/server/withIsolatedDat
 import { appMigrations } from "./migrations.ts";
 
 const migrationLayer = makePostgresTestLayer({
-  url,
-  migrations: appMigrations,
-  prepare: false,
+	url,
+	migrations: appMigrations,
+	prepare: false,
 });
 
 const { effectApp: migrationTest } = makeEffectIt({
-  layer: migrationLayer,
-  clock: "live",
-  around: withIsolatedDatabase,
-  makeHarness: () => migrationSteps(appMigrations),
+	layer: migrationLayer,
+	clock: "live",
+	around: withIsolatedDatabase,
+	makeHarness: () => migrationSteps(appMigrations),
 });
 
 migrationTest("preserves contact emails in the new table", function* (steps) {
-  yield* steps.migrateTo("001_create_contacts");
-  const sql = yield* SqlClient.SqlClient;
-  yield* sql`insert into contacts (id, email) values (1, 'alice@example.test')`;
-  yield* steps.migrateToLatest;
-  expect(yield* sql`select contact_id, address from emails`).toEqual([
-    { contact_id: 1, address: "alice@example.test" },
-  ]);
+	yield* steps.migrateTo("001_create_contacts");
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`insert into contacts (id, email) values (1, 'alice@example.test')`;
+	yield* steps.migrateToLatest;
+	expect(yield* sql`select contact_id, address from emails`).toEqual([{ contact_id: 1, address: "alice@example.test" }]);
 });
 ```
 
@@ -237,15 +253,15 @@ The assertion uses the SQL `Model`'s selected database fields, including generat
 
 Import each name from the module that defines it. The package has no root entry.
 
-| Module | Exports |
-| --- | --- |
-| `@shivaedev/test-sql/server/postgres.ts` | `makePostgresTestLayer({ url, migrations?, initialize?, fixtures?, maxConnections?, prepare?, transformQueryNames?, transformResultNames? })`, `PostgresTestOptions`, `PostgresTestLoader` |
-| `@shivaedev/test-sql/server/withTestTransaction.ts` | `withTestTransaction(effect)` |
-| `@shivaedev/test-sql/server/withIsolatedDatabase.ts` | `withIsolatedDatabase(effect, { template? }?)` |
-| `@shivaedev/test-sql/server/database.ts` | `PostgresTestDatabase`, `PostgresTestDatabaseService`, `PostgresTestServices`, `PostgresTestTemplate` |
-| `@shivaedev/test-sql/server/migrationSteps.ts` | `migrationSteps(appMigrations)` returning `{ migrateTo(name), migrateToLatest }` |
-| `@shivaedev/test-sql/server/migrationUpgrade.ts` | `migrationUpgrade({ migrations, upTo, table })`, `MigrationUpgradeOptions`, `PostgresColumn` |
-| `@shivaedev/test-sql/server/assertModelColumns.ts` | `assertModelColumns(columns, model, types)`, `ModelColumnMismatch` |
+| Module                                               | Exports                                                                                                                                                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@shivaedev/test-sql/server/postgres.ts`             | `makePostgresTestLayer({ url, migrations?, initialize?, fixtures?, maxConnections?, prepare?, transformQueryNames?, transformResultNames? })`, `PostgresTestOptions`, `PostgresTestLoader` |
+| `@shivaedev/test-sql/server/withTestTransaction.ts`  | `withTestTransaction(effect)`                                                                                                                                                              |
+| `@shivaedev/test-sql/server/withIsolatedDatabase.ts` | `withIsolatedDatabase(effect, { template? }?)`                                                                                                                                             |
+| `@shivaedev/test-sql/server/database.ts`             | `PostgresTestDatabase`, `PostgresTestDatabaseService`, `PostgresTestServices`, `PostgresTestTemplate`                                                                                      |
+| `@shivaedev/test-sql/server/migrationSteps.ts`       | `migrationSteps(appMigrations)` returning `{ migrateTo(name), migrateToLatest }`                                                                                                           |
+| `@shivaedev/test-sql/server/migrationUpgrade.ts`     | `migrationUpgrade({ migrations, upTo, table })`, `MigrationUpgradeOptions`, `PostgresColumn`                                                                                               |
+| `@shivaedev/test-sql/server/assertModelColumns.ts`   | `assertModelColumns(columns, model, types)`, `ModelColumnMismatch`                                                                                                                         |
 
 `url` is a redacted PostgreSQL URL for an existing administrative database. `PostgresTestDatabase` supplies the current database's redacted `url`, an `awaitCleanup: Effect<void>` drain, a scoped `isolated` Effect that acquires a migrated clone's service Context, and `clone(template)` for an explicit `"empty"` or `"migrated"` choice. With `prepare: false`, both choices are empty. Prefer `withIsolatedDatabase` to acquire and release that Context around a test. Wrappers retain the body's result, failures and unmet service requirements, with native `SqlError` added for acquisition or transaction failures. Cleanup failures surface as SQL defects when the Layer closes. Drops that fail with connection exhaustion (SQLSTATE `53300`) retry every 100 ms of live time for up to 300 retries, even while a test clock is paused; if capacity does not return, the SQL defect remains visible. Startup sweeps databases left by dead processes on the same host and databases from the older unowned naming format. Databases owned by live processes or another host are retained, so local parallel workers keep their databases. Use the same host to reclaim its abandoned databases.
 
@@ -255,4 +271,4 @@ Import each name from the module that defines it. The package has no root entry.
 pnpm add --save-dev @shivaedev/test-sql @shivaedev/test @effect/sql-pg @effect/vitest effect vitest
 ```
 
-Use versions compatible with the package's peer dependencies. The package requires Node.js 24 or later. The PostgreSQL role must be able to create and drop databases; use a dedicated test server. PostgreSQL 13 or later supports the forced database drops used for cleanup. The migrations and fixtures must complete their work during preparation; their scoped resources are closed before cloning.
+`@effect/sql-pg` and `effect` are peer dependencies; `@shivaedev/test` supplies the `makeEffectIt` runner the examples use. The package requires Node.js 24 or later. The PostgreSQL role must be able to create and drop databases; use a dedicated test server. PostgreSQL 13 or later supports the forced database drops used for cleanup. The migrations and fixtures must complete their work during preparation; their scoped resources are closed before cloning.

package/dist/server/raceWithLock.d.ts

@@ -0,0 +1,9 @@
+import { type Duration, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+export declare function raceWithLock<A, E, R, TLockError, TLockServices>(options: {
+    readonly lock: Effect.Effect<unknown, TLockError, TLockServices>;
+    readonly effects: readonly Effect.Effect<A, E, R>[];
+    readonly timeout?: Duration.Input;
+    readonly release?: "commit" | "rollback";
+}): Effect.Effect<import("effect/Result").Result<A, E>[], TLockError | import("effect/sql/SqlError").SqlError | import("effect/Cause").TimeoutError, import("effect/reactivity/Reactivity").Reactivity | SqlClient.SqlClient | Exclude<R, import("effect/Scope").Scope> | Exclude<Exclude<TLockServices, import("effect/Scope").Scope>, import("effect/Scope").Scope>>;
+//# sourceMappingURL=raceWithLock.d.ts.map

package/dist/server/raceWithLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raceWithLock.d.ts","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,EAAmB,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;CACzC,sWA6BA"}

package/dist/server/raceWithLock.js

@@ -0,0 +1,28 @@
+import { Deferred, Effect, Fiber, Schedule } from "effect";
+import { SqlClient } from "effect/sql";
+import { transact } from "@shivaedev/sql/transact.ts";
+import { withTestTransaction } from "#withTestTransaction.ts";
+export function raceWithLock(options) {
+    return Effect.scoped(Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const ready = yield* Deferred.make();
+        const started = yield* Deferred.make();
+        const hold = Effect.gen(function* () {
+            yield* options.lock;
+            yield* Deferred.succeed(ready, undefined);
+            yield* Deferred.await(started);
+            yield* sql `select pg_stat_clear_snapshot()`.pipe(Effect.andThen(sql `with recursive blocked(pid) as (
+						select pid from pg_stat_activity where pg_backend_pid() = any(pg_blocking_pids(pid))
+						union
+						select activity.pid from pg_stat_activity activity join blocked on blocked.pid = any(pg_blocking_pids(activity.pid))
+					) select count(*)::integer as waiting from blocked`), Effect.repeat({ schedule: Schedule.spaced("10 millis"), while: ([row]) => row?.waiting !== options.effects.length }));
+        });
+        const holder = yield* (options.release === "commit" ? transact(Effect.scoped(hold), { onSqlError: (error) => error }) : withTestTransaction(hold)).pipe(Effect.forkScoped);
+        yield* Effect.raceFirst(Deferred.await(ready), Fiber.join(holder).pipe(Effect.andThen(Effect.never)));
+        const contenders = yield* Effect.forEach(options.effects, Effect.result, { concurrency: "unbounded" }).pipe(Effect.forkScoped);
+        yield* Deferred.succeed(started, undefined);
+        yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(contenders).pipe(Effect.andThen(Effect.never)));
+        return yield* Fiber.join(contenders);
+    })).pipe(Effect.timeout(options.timeout ?? "5 seconds"));
+}
+//# sourceMappingURL=raceWithLock.js.map

package/dist/server/raceWithLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raceWithLock.js","sourceRoot":"","sources":["../../src/server/raceWithLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,UAAU,YAAY,CAAqC,OAKhE;IACA,OAAO,MAAM,CAAC,MAAM,CACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAQ,CAAC;QAC3C,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAQ,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAChC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;YACpB,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC1C,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC/B,KAAK,CAAC,CAAC,GAAG,CAAA,iCAAiC,CAAC,IAAI,CAC/C,MAAM,CAAC,OAAO,CAAC,GAAG,CAAqB;;;;wDAIY,CAAC,EACpD,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CACpH,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CACrB,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAC1H,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1B,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACtG,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC/H,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC5C,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACvG,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC,CAAC,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-sql",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "PostgreSQL rollback and real-commit test isolation for Effect",
   "keywords": [
     "effect"
@@ -44,23 +44,23 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/sql": "0.24.0"
+    "@shivaedev/sql": "0.25.0"
   },
   "devDependencies": {
-    "@effect/sql-pg": "4.0.5",
-    "@effect/vitest": "4.0.5",
-    "@shivaedev/quality": "0.43.0",
-    "@shivaedev/test": "0.10.0",
-    "@shivaedev/test-story": "0.22.0",
+    "@effect/sql-pg": "4.0.6",
+    "@effect/vitest": "4.0.6",
+    "@shivaedev/quality": "0.45.0",
+    "@shivaedev/test": "0.10.1",
+    "@shivaedev/test-story": "0.24.0",
     "@types/node": "24.19.2",
-    "effect": "4.0.5",
+    "effect": "4.0.6",
     "pg-boss": "12.38.0",
     "typescript": "7.0.2",
     "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "@effect/sql-pg": "4.0.5",
-    "effect": "4.0.5"
+    "@effect/sql-pg": "4.0.6",
+    "effect": "4.0.6"
   },
   "engines": {
     "node": ">=24"

package/src/server/raceWithLock.ts

@@ -0,0 +1,40 @@
+import { Deferred, type Duration, Effect, Fiber, Schedule } from "effect";
+import { SqlClient } from "effect/sql";
+import { transact } from "@shivaedev/sql/transact.ts";
+import { withTestTransaction } from "#withTestTransaction.ts";
+
+export function raceWithLock<A, E, R, TLockError, TLockServices>(options: {
+	readonly lock: Effect.Effect<unknown, TLockError, TLockServices>;
+	readonly effects: readonly Effect.Effect<A, E, R>[];
+	readonly timeout?: Duration.Input;
+	readonly release?: "commit" | "rollback";
+}) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const sql = yield* SqlClient.SqlClient;
+			const ready = yield* Deferred.make<void>();
+			const started = yield* Deferred.make<void>();
+			const hold = Effect.gen(function* () {
+				yield* options.lock;
+				yield* Deferred.succeed(ready, undefined);
+				yield* Deferred.await(started);
+				yield* sql`select pg_stat_clear_snapshot()`.pipe(
+					Effect.andThen(sql<{ waiting: number }>`with recursive blocked(pid) as (
+						select pid from pg_stat_activity where pg_backend_pid() = any(pg_blocking_pids(pid))
+						union
+						select activity.pid from pg_stat_activity activity join blocked on blocked.pid = any(pg_blocking_pids(activity.pid))
+					) select count(*)::integer as waiting from blocked`),
+					Effect.repeat({ schedule: Schedule.spaced("10 millis"), while: ([row]) => row?.waiting !== options.effects.length }),
+				);
+			});
+			const holder = yield* (
+				options.release === "commit" ? transact(Effect.scoped(hold), { onSqlError: (error) => error }) : withTestTransaction(hold)
+			).pipe(Effect.forkScoped);
+			yield* Effect.raceFirst(Deferred.await(ready), Fiber.join(holder).pipe(Effect.andThen(Effect.never)));
+			const contenders = yield* Effect.forEach(options.effects, Effect.result, { concurrency: "unbounded" }).pipe(Effect.forkScoped);
+			yield* Deferred.succeed(started, undefined);
+			yield* Effect.raceFirst(Fiber.join(holder), Fiber.join(contenders).pipe(Effect.andThen(Effect.never)));
+			return yield* Fiber.join(contenders);
+		}),
+	).pipe(Effect.timeout(options.timeout ?? "5 seconds"));
+}