@shivaedev/effect-test-sql 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-10-11
+
+### Added
+
+- `makePostgresTestLayer` prepares migrations and optional fixtures once in a PostgreSQL template and provides native services on a shared test database. `withTestTransaction` wraps harness setup, the body and scope finalizers in rollback, preserves nested `transact` savepoints, and discards commit-bound invalidations. `withIsolatedDatabase` clones the prepared template for real commits and drops the clone after the test. The Layer scope drops its shared database and template. Real PostgreSQL tests cover concurrency, row-lock release, failure and interruption, template reuse, second-connection commit visibility and resource cleanup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @shivaedev/effect-test-sql
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PostgreSQL tests should start from known data and leave it there. This package prepares migrations and fixtures once, wraps ordinary Effect tests in transactions that roll back, and clones the prepared database when a test needs real commits.
+
+## Why you want this
+
+Table cleanup couples tests to the order they run. A rollback test keeps its writes private and restores the prepared data when it ends:
+
+```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" },
+  ]);
+});
+```
+
+The next test still sees the original name. Tests that must observe a committed write use a disposable database copied from the same starting data.
+
+## Using it
+
+### Prepare one fixture
+
+`makePostgresTestLayer` creates a template database through an administrative connection, runs `migratePostgres` and optional fixtures there, then closes its preparation connections. It creates a shared test database from that template and provides `SqlClient`, `PgClient`, `Reactivity` and `PostgresTestDatabase`. The template remains closed and unchanged while tests run. Each isolated database is another copy of that template; its migrations and fixtures do not run again.
+
+The Layer's scope owns the template, shared database and their connections. `makeEffectIt` builds the Layer once for its worker fixture. Each test's wrapper owns the transaction or isolated database. Closing those scopes releases the connections and drops the disposable databases; the administrative database named by `url` remains in place.
+
+Define the tester in test support:
+
+```ts
+import { expect } from "vitest";
+import { Config, Effect, Redacted } from "effect";
+import { Migrator, SqlClient } from "effect/unstable/sql";
+import { makeEffectIt } from "@shivaedev/effect-test/vitest.ts";
+import { makePostgresTestLayer } from "@shivaedev/effect-test-sql/postgres.ts";
+import { withTestTransaction } from "@shivaedev/effect-test-sql/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')`;
+  }),
+});
+
+export const { effectApp } = makeEffectIt({
+  layer,
+  clock: "live",
+  around: withTestTransaction,
+  makeHarness: () => Effect.void,
+});
+```
+
+Use the application's migration loader in place of the example. `migrations` takes the existing `PostgresMigrationOptions`: `loader`, `lockTimeout`, and an optional ledger `table`. Fixtures are an Effect with access to the native PostgreSQL services. Additional migration or fixture dependencies remain requirements of the Layer and must be supplied before passing it to the runner. Setup failures remain failures; acquired databases are dropped when the acquisition scope closes.
+
+### Ordinary tests: rollback
+
+`around: withTestTransaction` wraps harness acquisition, the body and their scope finalizers. Success returns the body's value after rollback. Typed failures, defects and interruption also roll back and retain their failure kind. A nested `transact` uses the native savepoint path: a rejected nested write can roll back without losing earlier writes in the test. Commit-bound invalidations stay buffered and are discarded when the wrapping transaction rolls back.
+
+Tests may run concurrently on the shared database, with separate transaction connections. Other tests do not see uncommitted writes. PostgreSQL still enforces row locks and unique constraints: updates to the same keyed row, or inserts with the same unique key, can wait until the first test rolls back. Do not make tests wait for each other after acquiring conflicting locks. Use different keys or isolated databases when a scenario needs overlapping writes without that contention.
+
+PostgreSQL sequence advances survive rollback. Avoid asserting exact generated sequence numbers on the shared database; use an isolated database when its sequence state must start from the template.
+
+### Real commits: an isolated database
+
+Use `withIsolatedDatabase` for after-commit effects, LISTEN/NOTIFY, advisory-lock scenarios that need independent connections, migration tests, or work through several connections. It runs without a wrapping transaction on its clone. Ordinary autocommit and `transact` commit for real, and the clone is dropped when the wrapper finishes.
+
+An isolated block can live inside the rollback tester above:
+
+```ts
+import { withIsolatedDatabase } from "@shivaedev/effect-test-sql/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`;
+  }));
+});
+```
+
+The clone starts from the template, including the original fixtures, even if the shared database has changed. The outer rollback transaction belongs to a different native client and does not wrap the clone's work. To isolate harness acquisition and the entire body instead, define a tester with `around: withIsolatedDatabase`.
+
+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.
+
+### API
+
+Import each name from the module that defines it. The package has no root entry.
+
+| Module | Exports |
+| --- | --- |
+| `@shivaedev/effect-test-sql/postgres.ts` | `makePostgresTestLayer({ url, migrations, fixtures? })`, `PostgresTestOptions` |
+| `@shivaedev/effect-test-sql/withTestTransaction.ts` | `withTestTransaction(effect)` |
+| `@shivaedev/effect-test-sql/withIsolatedDatabase.ts` | `withIsolatedDatabase(effect)` |
+| `@shivaedev/effect-test-sql/database.ts` | `PostgresTestDatabase`, `PostgresTestDatabaseService`, `PostgresTestServices` |
+
+`url` is a redacted PostgreSQL URL for an existing administrative database. `PostgresTestDatabase` supplies the current database's redacted `url` and a scoped `isolated` Effect that acquires another clone's service Context. 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 are defects rather than successful cleanup.
+
+### Install, setup and evidence
+
+```sh
+pnpm add --save-dev @shivaedev/effect-test-sql @shivaedev/effect-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.
+
+The package tests use `PLATFORM_EFFECT_TEST_SQL_TEST_DATABASE_URL`. Repository setup and CI prepare that database on real PostgreSQL. Local tests skip when that variable is absent; CI rejects its absence. The PostgreSQL tests prove overlapping same-row visibility, shared-key lock contention and release, rollback, nested savepoints, runner/harness scope composition, one-time template preparation, commits visible through another connection, and database cleanup. Compiler and packed-consumer tests prove the exercised public type and export contracts. These are library checks, not evidence for an application's servers or notification delivery.

package/dist/database.d.ts

@@ -0,0 +1,15 @@
+import type * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, type Effect, type Redacted, type Scope } from "effect";
+import type * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import type { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+export type PostgresTestServices = PgClient.PgClient | SqlClient.SqlClient | Reactivity.Reactivity;
+export interface PostgresTestDatabaseService {
+    readonly isolated: Effect.Effect<Context.Context<PostgresTestServices | PostgresTestDatabase>, SqlError, Scope.Scope>;
+    readonly url: Redacted.Redacted<string>;
+}
+declare const PostgresTestDatabase_base: Context.ServiceClass<PostgresTestDatabase, "@shivaedev/effect-test-sql/PostgresTestDatabase", PostgresTestDatabaseService>;
+export declare class PostgresTestDatabase extends PostgresTestDatabase_base {
+}
+export {};
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,KAAK,KAAK,UAAU,MAAM,uCAAuC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAE7D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC;AAEnG,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,oBAAoB,GAAG,oBAAoB,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACtH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CACxC;;AAED,qBAAa,oBAAqB,SAAQ,yBAEzC;CAAG"}

package/dist/database.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export class PostgresTestDatabase extends Context.Service()("@shivaedev/effect-test-sql/PostgresTestDatabase") {
+}
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAA0C,MAAM,QAAQ,CAAC;AAYzE,MAAM,OAAO,oBAAqB,SAAQ,OAAO,CAAC,OAAO,EAAqD,CAC7G,iDAAiD,CACjD;CAAG"}

package/dist/internal/databases.d.ts

@@ -0,0 +1,10 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Effect, Layer, Redacted } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { SqlClient } from "effect/unstable/sql";
+export declare function connection(url: Redacted.Redacted<string>): Layer.Layer<PgClient.PgClient | Reactivity.Reactivity | SqlClient.SqlClient, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const database: (admin: PgClient.PgClient, url: Redacted.Redacted<string>, template?: any) => Effect.Effect<{
+    name: string;
+    url: Redacted.Redacted<string>;
+}, import("effect/unstable/sql/SqlError").SqlError, import("effect/Scope").Scope>;
+//# sourceMappingURL=databases.d.ts.map

package/dist/internal/databases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.d.ts","sourceRoot":"","sources":["../../src/internal/databases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAW,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,KAAK,UAAU,MAAM,uCAAuC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,wIAIxD;AAED,eAAO,MAAM,QAAQ;;;iFAanB,CAAC"}

package/dist/internal/databases.js

@@ -0,0 +1,16 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, Effect, Layer, Redacted } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { SqlClient } from "effect/unstable/sql";
+export function connection(url) {
+    return Layer.effectContext(Effect.map(PgClient.make({ url }), (client) => Context.make(SqlClient.SqlClient, client).pipe(Context.add(PgClient.PgClient, client)))).pipe(Layer.provideMerge(Layer.fresh(Reactivity.layer)));
+}
+export const database = Effect.fn("PostgresTest.database")(function* (admin, url, template = "template0") {
+    const name = `effect_test_${crypto.randomUUID().replaceAll("-", "")}`;
+    const target = new URL(Redacted.value(url));
+    target.pathname = `/${name}`;
+    target.searchParams.delete("database");
+    yield* Effect.acquireRelease(admin `create database ${admin(name)} template ${admin(template)}`, () => Effect.orDie(admin `drop database ${admin(name)} with (force)`));
+    return { name, url: Redacted.make(target.toString()) };
+});
+//# sourceMappingURL=databases.js.map

package/dist/internal/databases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.js","sourceRoot":"","sources":["../../src/internal/databases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,KAAK,UAAU,MAAM,uCAAuC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,UAAU,UAAU,CAAC,GAA8B;IACxD,OAAO,KAAK,CAAC,aAAa,CACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CACtI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC,QAAQ,CAAC,EACnE,KAAwB,EACxB,GAA8B,EAC9B,QAAQ,GAAG,WAAW;IAEtB,MAAM,IAAI,GAAG,eAAe,MAAM,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACvC,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAA,mBAAmB,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CACpG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAA,iBAAiB,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAC9D,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC,CAAC,CAAC"}

package/dist/postgres.d.ts

@@ -0,0 +1,12 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Effect, Layer, type Redacted } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { type PostgresMigrationOptions } from "@shivaedev/effect-sql/migrations.ts";
+import { PostgresTestDatabase, type PostgresTestServices } from "./database.ts";
+export interface PostgresTestOptions<E = never, R = never, TFixtures = never> {
+    readonly fixtures?: Effect.Effect<unknown, E, TFixtures | PostgresTestServices>;
+    readonly migrations: PostgresMigrationOptions<R>;
+    readonly url: Redacted.Redacted<string>;
+}
+export declare function makePostgresTestLayer<E = never, R = never, TFixtures = never>(options: PostgresTestOptions<E, R, TFixtures>): Layer.Layer<PgClient.PgClient | PostgresTestDatabase | Reactivity.Reactivity | import("effect/unstable/sql/SqlClient").SqlClient, E | import("effect/unstable/sql/Migrator").MigrationError | import("effect/unstable/sql/SqlError").SqlError, Exclude<Exclude<Exclude<Exclude<R, PgClient.PgClient | Reactivity.Reactivity | import("effect/unstable/sql/SqlClient").SqlClient>, import("effect/Scope").Scope>, import("effect/Scope").Scope>, Reactivity.Reactivity> | Exclude<Exclude<Exclude<Exclude<TFixtures, PgClient.PgClient | Reactivity.Reactivity | import("effect/unstable/sql/SqlClient").SqlClient>, import("effect/Scope").Scope>, import("effect/Scope").Scope>, Reactivity.Reactivity>>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAW,MAAM,EAAE,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC/D,OAAO,KAAK,UAAU,MAAM,uCAAuC,CAAC;AACpE,OAAO,EAAmB,KAAK,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAErG,OAAO,EAAE,oBAAoB,EAAoC,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAElH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,SAAS,GAAG,KAAK;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,SAAS,GAAG,oBAAoB,CAAC,CAAC;IAChF,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,6qBAwB3H"}

package/dist/postgres.js

@@ -0,0 +1,28 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, Effect, Layer } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { migratePostgres } from "@shivaedev/effect-sql/migrations.ts";
+import { connection, database } from "#internal/databases.ts";
+import { PostgresTestDatabase } from "./database.js";
+export function makePostgresTestLayer(options) {
+    return Layer.effectContext(Effect.gen(function* () {
+        const admin = yield* PgClient.make({ url: options.url });
+        const template = yield* database(admin, options.url);
+        yield* Effect.scoped(Effect.gen(function* () {
+            const services = yield* Layer.build(connection(template.url));
+            yield* migratePostgres(options.migrations).pipe(Effect.provideContext(services));
+            if (options.fixtures !== undefined) {
+                yield* options.fixtures.pipe(Effect.provideContext(services));
+            }
+        }));
+        const shared = yield* database(admin, options.url, template.name);
+        const services = yield* Layer.build(connection(shared.url));
+        const isolated = Effect.gen(function* () {
+            const clone = yield* database(admin, options.url, template.name);
+            const context = yield* Layer.build(connection(clone.url));
+            return Context.add(context, PostgresTestDatabase, { isolated, url: clone.url });
+        });
+        return Context.add(services, PostgresTestDatabase, { isolated, url: shared.url });
+    })).pipe(Layer.provide(Reactivity.layer));
+}
+//# sourceMappingURL=postgres.js.map

package/dist/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAiB,MAAM,QAAQ,CAAC;AAC/D,OAAO,KAAK,UAAU,MAAM,uCAAuC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAiC,MAAM,qCAAqC,CAAC;AACrG,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAA+D,MAAM,eAAe,CAAC;AAQlH,MAAM,UAAU,qBAAqB,CAA0C,OAA6C;IAC3H,OAAO,KAAK,CAAC,aAAa,CACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QACrD,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9D,KAAK,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;YACjF,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACpC,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC/D,CAAC;QACF,CAAC,CAAC,CACF,CAAC;QACF,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClE,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAA4C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjE,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1D,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,oBAAoB,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACnF,CAAC,CAAC,CACF,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC"}

package/dist/withIsolatedDatabase.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+import { PostgresTestDatabase } from "./database.ts";
+export declare function withIsolatedDatabase<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | import("effect/unstable/sql/SqlError").SqlError, PostgresTestDatabase | Exclude<Exclude<R, PostgresTestDatabase | import("./database.ts").PostgresTestServices>, import("effect/Scope").Scope>>;
+//# sourceMappingURL=withIsolatedDatabase.d.ts.map

package/dist/withIsolatedDatabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withIsolatedDatabase.d.ts","sourceRoot":"","sources":["../src/withIsolatedDatabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,wNAQ3E"}

package/dist/withIsolatedDatabase.js

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { PostgresTestDatabase } from "./database.js";
+export function withIsolatedDatabase(effect) {
+    return Effect.scoped(Effect.gen(function* () {
+        const database = yield* PostgresTestDatabase;
+        const services = yield* database.isolated;
+        return yield* effect.pipe(Effect.provideContext(services));
+    }));
+}
+//# sourceMappingURL=withIsolatedDatabase.js.map

package/dist/withIsolatedDatabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withIsolatedDatabase.js","sourceRoot":"","sources":["../src/withIsolatedDatabase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,UAAU,oBAAoB,CAAU,MAA8B;IAC3E,OAAO,MAAM,CAAC,MAAM,CACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,oBAAoB,CAAC;QAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC1C,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,CACF,CAAC;AACH,CAAC"}

package/dist/withTestTransaction.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+export declare function withTestTransaction<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | SqlError, import("effect/unstable/reactivity/Reactivity").Reactivity | import("effect/unstable/sql/SqlClient").SqlClient | Exclude<R, import("effect/Scope").Scope>>;
+//# sourceMappingURL=withTestTransaction.d.ts.map

package/dist/withTestTransaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTestTransaction.d.ts","sourceRoot":"","sources":["../src/withTestTransaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAO7D,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,6LAM1E"}

package/dist/withTestTransaction.js

@@ -0,0 +1,9 @@
+import { Effect, Exit } from "effect";
+import { transact } from "@shivaedev/effect-sql/transact.ts";
+function isTestExit(value) {
+    return Exit.isExit(value);
+}
+export function withTestTransaction(effect) {
+    return Effect.uninterruptibleMask((restore) => transact(Effect.flatMap(Effect.exit(Effect.scoped(restore(effect))), Effect.fail), { onSqlError: (error) => error }).pipe(Effect.catchIf(isTestExit, (exit) => exit)));
+}
+//# sourceMappingURL=withTestTransaction.js.map

package/dist/withTestTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTestTransaction.js","sourceRoot":"","sources":["../src/withTestTransaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAE7D,SAAS,UAAU,CAAO,KAAiC;IAC1D,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAU,MAA8B;IAC1E,OAAO,MAAM,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE,EAAE,CAC7C,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CACxH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAC1C,CACD,CAAC;AACH,CAAC"}

package/docs/north-star.md

@@ -0,0 +1,9 @@
+# PostgreSQL tests with deliberate lifetimes
+
+Database tests repeat expensive setup and fragile cleanup when each application invents its own fixture lifecycle. The ideal is one migration and fixture preparation for a worker fixture, ordinary tests whose data disappears through rollback, and a deliberate escape for tests that need PostgreSQL to commit.
+
+Native Effect owns Context, Scope, failure, interruption and SQL transaction connections. `effect-test` owns the runner; `effect-sql` owns migrations and commit-bound transactions. This package joins those paths with PostgreSQL database resources. It does not implement another migration engine, pool driver or test runner.
+
+Prepare an immutable template, close its connections, and clone it for the shared database and isolated scenarios. Connection finalizers precede database drops. A rejected or interrupted test must not become a successful test during cleanup. A rolled-back nested transaction uses a savepoint, and a rolled-back test must not publish commit-bound invalidations.
+
+Isolation does not erase PostgreSQL's concurrency rules. Conflicting keyed writes share locks in the ordinary path. Separate databases permit independent data and real commits, while cluster-wide resources still need scenario-specific choices. Preserve these boundaries over a promise of universal concurrency.

package/docs/roadmap.md

@@ -0,0 +1,8 @@
+# Roadmap
+
+- [x] Prepare migrations and optional fixtures once in a closed template database.
+- [x] Supply native PostgreSQL services on a shared database with per-test rollback.
+- [x] Compose the wrapping transaction with `makeEffectIt`, harness scopes and nested `transact` savepoints.
+- [x] Clone isolated databases for real commits and drop them after use.
+- [x] Prove the database lifecycle against PostgreSQL and the public contracts with compiler and packed-consumer checks.
+- [x] Prepare the approved initial 0.1.0 release metadata.

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@shivaedev/effect-test-sql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "PostgreSQL rollback and real-commit test isolation for Effect",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/effect-test-sql#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/effect-test-sql"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "source": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "docs",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/effect-sql": "0.2.0"
+  },
+  "devDependencies": {
+    "@effect/sql-pg": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@shivaedev/effect-test": "0.3.1",
+    "@shivaedev/quality": "0.18.0",
+    "@types/node": "24.10.1",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "effect": "4.0.0-rc.112",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@effect/sql-pg": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/database.ts

@@ -0,0 +1,16 @@
+import type * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, type Effect, type Redacted, type Scope } from "effect";
+import type * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import type { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+
+export type PostgresTestServices = PgClient.PgClient | SqlClient.SqlClient | Reactivity.Reactivity;
+
+export interface PostgresTestDatabaseService {
+	readonly isolated: Effect.Effect<Context.Context<PostgresTestServices | PostgresTestDatabase>, SqlError, Scope.Scope>;
+	readonly url: Redacted.Redacted<string>;
+}
+
+export class PostgresTestDatabase extends Context.Service<PostgresTestDatabase, PostgresTestDatabaseService>()(
+	"@shivaedev/effect-test-sql/PostgresTestDatabase",
+) {}

package/src/internal/databases.ts

@@ -0,0 +1,25 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, Effect, Layer, Redacted } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { SqlClient } from "effect/unstable/sql";
+
+export function connection(url: Redacted.Redacted<string>) {
+	return Layer.effectContext(
+		Effect.map(PgClient.make({ url }), (client) => Context.make(SqlClient.SqlClient, client).pipe(Context.add(PgClient.PgClient, client))),
+	).pipe(Layer.provideMerge(Layer.fresh(Reactivity.layer)));
+}
+
+export const database = Effect.fn("PostgresTest.database")(function* (
+	admin: PgClient.PgClient,
+	url: Redacted.Redacted<string>,
+	template = "template0",
+) {
+	const name = `effect_test_${crypto.randomUUID().replaceAll("-", "")}`;
+	const target = new URL(Redacted.value(url));
+	target.pathname = `/${name}`;
+	target.searchParams.delete("database");
+	yield* Effect.acquireRelease(admin`create database ${admin(name)} template ${admin(template)}`, () =>
+		Effect.orDie(admin`drop database ${admin(name)} with (force)`),
+	);
+	return { name, url: Redacted.make(target.toString()) };
+});

package/src/postgres.ts

@@ -0,0 +1,38 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Context, Effect, Layer, type Redacted } from "effect";
+import * as Reactivity from "effect/unstable/reactivity/Reactivity";
+import { migratePostgres, type PostgresMigrationOptions } from "@shivaedev/effect-sql/migrations.ts";
+import { connection, database } from "#internal/databases.ts";
+import { PostgresTestDatabase, type PostgresTestDatabaseService, type PostgresTestServices } from "./database.ts";
+
+export interface PostgresTestOptions<E = never, R = never, TFixtures = never> {
+	readonly fixtures?: Effect.Effect<unknown, E, TFixtures | PostgresTestServices>;
+	readonly migrations: PostgresMigrationOptions<R>;
+	readonly url: Redacted.Redacted<string>;
+}
+
+export function makePostgresTestLayer<E = never, R = never, TFixtures = never>(options: PostgresTestOptions<E, R, TFixtures>) {
+	return Layer.effectContext(
+		Effect.gen(function* () {
+			const admin = yield* PgClient.make({ url: options.url });
+			const template = yield* database(admin, options.url);
+			yield* Effect.scoped(
+				Effect.gen(function* () {
+					const services = yield* Layer.build(connection(template.url));
+					yield* migratePostgres(options.migrations).pipe(Effect.provideContext(services));
+					if (options.fixtures !== undefined) {
+						yield* options.fixtures.pipe(Effect.provideContext(services));
+					}
+				}),
+			);
+			const shared = yield* database(admin, options.url, template.name);
+			const services = yield* Layer.build(connection(shared.url));
+			const isolated: PostgresTestDatabaseService["isolated"] = Effect.gen(function* () {
+				const clone = yield* database(admin, options.url, template.name);
+				const context = yield* Layer.build(connection(clone.url));
+				return Context.add(context, PostgresTestDatabase, { isolated, url: clone.url });
+			});
+			return Context.add(services, PostgresTestDatabase, { isolated, url: shared.url });
+		}),
+	).pipe(Layer.provide(Reactivity.layer));
+}

package/src/withIsolatedDatabase.ts

@@ -0,0 +1,12 @@
+import { Effect } from "effect";
+import { PostgresTestDatabase } from "./database.ts";
+
+export function withIsolatedDatabase<A, E, R>(effect: Effect.Effect<A, E, R>) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const database = yield* PostgresTestDatabase;
+			const services = yield* database.isolated;
+			return yield* effect.pipe(Effect.provideContext(services));
+		}),
+	);
+}

package/src/withTestTransaction.ts

@@ -0,0 +1,15 @@
+import { Effect, Exit } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { transact } from "@shivaedev/effect-sql/transact.ts";
+
+function isTestExit<A, E>(value: Exit.Exit<A, E> | SqlError): value is Exit.Exit<A, E> {
+	return Exit.isExit(value);
+}
+
+export function withTestTransaction<A, E, R>(effect: Effect.Effect<A, E, R>) {
+	return Effect.uninterruptibleMask((restore) =>
+		transact(Effect.flatMap(Effect.exit(Effect.scoped(restore(effect))), Effect.fail), { onSqlError: (error) => error }).pipe(
+			Effect.catchIf(isTestExit, (exit) => exit),
+		),
+	);
+}