@btravstack/prisma 0.15.0 → 0.16.0

package/README.md

@@ -1,69 +1,70 @@
 # @btravstack/prisma
 
 > The Prisma starter for [`@btravstack/core`](https://github.com/btravstack/btravstack):
-> `DATABASE_URL` bound through `Config`, the Postgres driver adapter, and a
-> client whose pool is the application scope's.
+> `DATABASE_URL` bound through `Config`, per-query observation as middleware,
+> and a client whose pool is the application scope's. Prisma **8**.
 
 📖 **[Documentation](https://btravstack.github.io/btravstack/reference/prisma)** ·
 [API Reference](https://btravstack.github.io/btravstack/api/prisma/)
 
 ```sh
 pnpm add @btravstack/prisma @btravstack/core @btravstack/config @btravstack/di unthrown \
-  @prisma/adapter-pg
+  @prisma/orm-postgres@8.0.0-rc.11
 ```
 
 Five peer dependencies — install every one, so the application holds a single
-copy of each. Your own `@prisma/client`, `prisma` and (if you want the `try*`
-twins) `@unthrown/prisma` are yours, not this package's: the client is
-generated from your schema. `@prisma/client` is also an **optional** peer here,
-used only by the `@btravstack/prisma/rls` subpath below — a consumer that never
-imports it installs nothing extra. Node `>=22`.
+copy of each. The `prisma` CLI is yours, as a dev dependency: the client is
+built from _your_ emitted contract, so there is none for this package to ship.
+Node `>=22`.
+
+**This is Prisma 8**, which is a different package family rather than a version
+bump — `@prisma/orm-postgres` replaces `@prisma/client` and `@prisma/adapter-pg`
+both, and there is no `@prisma/instrumentation`. For Prisma 7 use
+`@btravstack/prisma@0.14`.
 
 ## A worked example
 
 <!-- doctest: group=order-api -->
 <!-- doctest: prelude
 import { Env } from "@btravstack/config";
-import { Logger } from "@btravstack/core";
 import { Module } from "@btravstack/di";
-import { PrismaPg } from "@prisma/adapter-pg";
-
-// The stand-in for the client YOUR schema generates, and the extension you
-// apply to it. Neither exists in this package — that is what the `client`
-// arrow is for.
-declare class PrismaClient {
-  constructor(options: { readonly adapter: PrismaPg });
-  $disconnect(): Promise<void>;
-  $queryRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<unknown>;
-  $extends(extension: unknown): this;
-}
-declare const unthrownPrisma: unknown;
+import type { PrismaBinding } from "@btravstack/prisma";
+
+// The stand-in for the client YOUR contract types. It does not exist in this
+// package — that is what the `client` arrow is for.
+declare const postgres: (options: PrismaBinding & { readonly contractJson: unknown }) => {
+  readonly raw: { readonly sql: unknown };
+  readonly runtime: unknown;
+};
+declare const contractJson: unknown;
 -->
 
 ```ts
 import { prismaDatabase } from "@btravstack/prisma";
 
 const database = prismaDatabase("OrderDatabase")({
-  client: (adapter) => new PrismaClient({ adapter }).$extends(unthrownPrisma),
+  client: ({ url, middleware }) => postgres({ contractJson, url, middleware }),
 });
 ```
 
 That is the whole surface. `database` is a **module** carrying the port a
 composition root reads; the provider binding `DATABASE_URL`, the resourceful
-client provider, the health check and the engine-tracing loader are inside it:
+client provider and the health check are inside it:
 
 ```ts
 export const PersistenceModule = Module("Persistence")({
   imports: [database],
   exports: [database.port],
-  needs: [Env, Logger],
+  needs: [Env],
 });
 ```
 
-**The client type is yours, and that is deliberate.** A Prisma client is
-generated from _your_ schema, so there is none for this package to ship — the
-`client` arrow is where your generated class and your extensions meet, and the
-port is typed by exactly what it returns.
+**The client type is yours, and that is deliberate.** A Prisma 8 client is
+typed by _your_ emitted `Contract` and built from _your_ `contract.json`, so
+there is none for this package to ship — the `client` arrow is where your
+contract and this starter meet, and the port is typed by exactly what it
+returns. Spread the `middleware` it hands you into the client: that is where
+the per-query observation below comes from.
 
 ## What it owns
 
@@ -71,87 +72,98 @@ port is typed by exactly what it returns.
   `ConfigInvalid` naming the variable, not a throw — so a misconfigured
   deployment exits `78` with the reason on stderr instead of crashing on the
   first query.
-- **The Postgres driver adapter**, constructed from that URL. Another driver is
-  reachable — build it in your own `client` arrow and ignore the one passed in.
 - **The pool's lifetime.** The provider is _resourceful_, so `release` closes it
   on every exit path, including a boot that fails after it ran.
-- **A health check**, named after the starter — `SELECT 1` through `$queryRaw`,
-  folded into the kernel's `GET /healthz` with nothing wired. `/readyz` does not
-  read it: failing readiness on a dependency every replica shares removes them
-  all at once.
-- **Engine tracing, offered rather than registered.** The starter contributes a
-  loader for the optional `@prisma/instrumentation` peer to `Instrumentations`;
-  composing `@btravstack/observability/otel` is what turns it on, and a graph
-  with no SDK never imports it. A missing peer is a `debug` line, never silence.
-- **Every query handed to `Observers`**, so composing `observability()` writes
-  the failures as lines and `otel()` mints the instruments — with no flag here
-  and no port list to satisfy when you compose neither.
+- **A health check**, named after the starter — `SELECT 1` through the raw
+  lane, folded into the kernel's `GET /healthz` with nothing wired. `/readyz`
+  does not read it: failing readiness on a dependency every replica shares
+  removes them all at once.
+- **Every query handed to `Observers`**, as one `afterQuery` middleware, so
+  composing `observability()` writes the failures as lines and `otel()` opens
+  the spans and mints the instruments — with no flag here and no port list to
+  satisfy when you compose neither. A middleware sees the ORM lane, the SQL
+  builder and the raw lane alike, and carries the runtime's own `latencyMs`.
+
+## `Result`s, on the `@btravstack/prisma/result` subpath
+
+Prisma 8 throws a **structured** error carrying PostgreSQL's own SQLSTATE.
+`tryQuery` turns that into a `Result` with three modeled arms —
+`UniqueConstraintViolation` (`23505`, with the `constraint` the database
+named), `ForeignKeyViolation` (`23503`) and `NotAuthorized` (`42501`,
+including a write a row-security policy refused). Anything else is a defect.
+
+<!-- doctest: isolate
+import { tryQuery } from "@btravstack/prisma/result";
+import { P } from "unthrown";
+
+declare const db: { readonly orm: { readonly orders: { readonly Order: { readonly create: (row: { readonly orderId: string }) => Promise<unknown> } } } };
+declare const orderId: string;
+declare const duplicate: (id: string) => Error;
+-->
+
+```ts
+const saved = tryQuery(() => db.orm.orders.Order.create({ orderId })).mapErrCases(
+  (matcher, defect) =>
+    matcher
+      .with(P.tag("UniqueConstraintViolation"), () => duplicate(orderId))
+      .with(P.tag("ForeignKeyViolation"), P.tag("NotAuthorized"), (cause) => defect(cause)),
+);
+```
+
+It takes a **thunk** rather than a promise: an `AsyncResult` is eager, so a
+promise built at the call site has already started before the Result exists.
 
 ## Row-level security, on the `@btravstack/prisma/rls` subpath
 
-`tenantScoped(tenant)` is a Prisma client extension that pins **every** statement
-— raw SQL included — to `tenant` through a transaction-local
-`set_config('app.tenant_id', tenant, true)`, so a PostgreSQL row-level-security
-policy reading `current_setting('app.tenant_id', true)` sees it. Apply it
-**last**:
+**The policy is declared in your contract** — `@@rls` on the model and a
+`policy_all` block beside it — and the planner emits `ENABLE ROW LEVEL
+SECURITY` and `CREATE POLICY` like any other migration operation. **The pin is
+a transaction:**
 
 <!-- doctest: isolate
-// `PrismaClient` and `unthrownPrisma` are the reader's own, exactly as in the
-// worked example above — so what this fence holds is `tenantScoped`'s call
-// shape and its place in the chain, not the generated client's `$extends`.
-// That half is compiled on the reference page, over the real client.
-import { PrismaPg } from "@prisma/adapter-pg";
-
-declare class PrismaClient {
-  constructor(options: { readonly adapter: PrismaPg });
-  $extends(extension: unknown): this;
-}
-declare const adapter: PrismaPg;
-declare const unthrownPrisma: unknown;
+import { tenantPinned } from "@btravstack/prisma/rls";
+
+declare const db: {
+  readonly raw: { readonly sql: unknown };
+  readonly transaction: <R>(fn: (tx: { readonly query: (plan: never) => Promise<unknown>; readonly orm: { readonly orders: { readonly Order: { readonly all: () => Promise<readonly unknown[]> } } } }) => PromiseLike<R>) => Promise<R>;
+};
 declare const tenant: string;
 -->
 
 ```ts
-import { tenantScoped } from "@btravstack/prisma/rls";
-
-const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+const orders = await tenantPinned(db, tenant, (tx) => tx.orm.orders.Order.all());
 ```
 
-That fence compiles `tenantScoped`'s call shape and its place in the chain over
-a client declared for the sample; the fence on the
-[reference page](https://btravstack.github.io/btravstack/reference/prisma) is
-the one compiled over a real generated client, which is what proves the
-extension is assignable to its `$extends`.
-
-It goes last because a transaction callback's `tx` comes from the client as it
-stood when this extension was applied, so anything added after it is invisible
-inside a transaction. `$transaction([...])` is refused rather than silently pinned: the
-batch form stops being atomic under this design, and a rejected promise beats a
-transaction that quietly no longer rolls back. Use the callback form.
-
-The database half stays the deployment's, and every part of it fails quietly
-when forgotten: a **superuser** role bypasses row security whatever the table
-says, and a policy without `FORCE ROW LEVEL SECURITY` is not applied to the
-table's **owner** — the role that ran the migrations. Either way the
-application works and no tenant is isolated. The policy must also read the
-**same** setting `tenantScoped` was given — `app.tenant_id` is only the default
-— because a `tenantScoped(tenant, { setting })` and a policy naming a different
-one deny every row and every write, which looks exactly like row security
-working. The
+`set_config(…, true)` is **transaction-local**, which is why this opens one
+rather than handing back a pinned client: a session-scoped pin works only while
+the pool happens to return the same connection, and fails silently the first
+time it does not. The policy must read the **same** setting — `app.tenant_id`
+is only the default — because a `tenantPinned(db, tenant, work, { setting })`
+and a policy naming a different one deny every row and every write, which looks
+exactly like row security working.
+
+Two halves stay the deployment's, and both fail quietly when forgotten: Prisma 8
+authors policies but no `GRANT`s, and it emits `ENABLE ROW LEVEL SECURITY` with
+no way to say `FORCE` — so the table's **owner**, which is the role that ran the
+migrations, bypasses every policy. Connect as a role that is neither the owner
+nor a superuser. The
 [reference page](https://btravstack.github.io/btravstack/reference/prisma)
-carries the DDL and the two smaller lines that fail the same way.
+carries the DDL and the smaller lines that fail the same way.
 
 ## What it does not
 
-**Migrations.** A deployment runs `prisma migrate deploy` against the same
-database _before the process starts_ — and, where row security is on, as its
-**owner** rather than the role `DATABASE_URL` carries. An application that
-migrates itself at boot races every other replica.
+**Migrations.** A deployment runs `prisma db migrate` against the same database
+_before the process starts_ — and, where row security is on, as its **owner**
+rather than the role `DATABASE_URL` carries. An application that migrates itself
+at boot races every other replica.
+
+**Engine-level tracing.** There is no engine: Prisma 8 is a TypeScript runtime
+and ships no instrumentation package, so the `afterQuery` middleware is the
+whole seam and it already carries the runtime's own latency.
 
 **Transactions.** Commit boundaries belong to the adapter, spelled at the call —
-`@unthrown/prisma`'s `$tryTransaction` is the primitive. The `rls` subpath
-overrides `$transaction` to pin the tenant on the connection and nothing more;
-it opens no boundary of its own. There is no unit-scoped
+`db.transaction(fn)` is the primitive. The `rls` subpath opens one transaction
+to pin a setting on and the work inside it is yours. There is no unit-scoped
 transaction and there will not be one; see
 [the kernel maps nothing](https://btravstack.github.io/btravstack/explanation/the-kernel-maps-nothing).
 
@@ -160,12 +172,12 @@ package's.
 
 ## Options
 
-| Option         | Where                                       | What it is                                                                               |
-| -------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `name`         | `prismaDatabase(name)`                      | the port's id and the health check's name — required                                     |
-| `client`       | `prismaDatabase(name)({ client })`          | builds your client from the driver adapter this package built from the URL — required    |
-| `DATABASE_URL` | environment, read by `prismaDatabase(name)` | the connection string — required, validated at graph build; blank is an error, exit `78` |
-| `setting`      | `tenantScoped(tenant, { setting })`         | the PostgreSQL run-time setting the policy reads — default `app.tenant_id`               |
+| Option         | Where                                         | What it is                                                                               |
+| -------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `name`         | `prismaDatabase(name)`                        | the port's id and the health check's name — required                                     |
+| `client`       | `prismaDatabase(name)({ client })`            | builds your client from the URL and middleware this package bound — required             |
+| `DATABASE_URL` | environment, read by `prismaDatabase(name)`   | the connection string — required, validated at graph build; blank is an error, exit `78` |
+| `setting`      | `tenantPinned(db, tenant, work, { setting })` | the PostgreSQL run-time setting the policy reads — default `app.tenant_id`               |
 
 There is **no `instrumented` flag**: observation is a set port every call is
 handed to, so a graph composing no observability pays one inert call and no

package/dist/index.cjs

@@ -2,150 +2,111 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _btravstack_config = require("@btravstack/config");
 let _btravstack_core = require("@btravstack/core");
 let _btravstack_di = require("@btravstack/di");
-let _prisma_adapter_pg = require("@prisma/adapter-pg");
 let unthrown = require("unthrown");
 //#region src/instrument.ts
 /**
-* Every query, handed to the graph's observers: a count of how it came out, and
-* a log line if it failed.
+* Every query, handed to the graph's observers: a span that spans the query, a
+* count of how it came out, and a log line if it failed.
 *
-* **This is why a generated client can be instrumented at all.** Prisma's
-* `$extends` takes a `query` component, and `$allModels.$allOperations`
-* intercepts every operation on every model — so the wrapper never needs to
-* know the schema, which is the thing this package cannot see. An earlier
-* revision of this package claimed instrumentation was impossible for that
-* reason; it was wrong, and this is the mechanism it missed.
+* **This is why a client the starter cannot name can be instrumented at all.**
+* `middleware` is a construction option rather than a wrapper, and a hook sees
+* every statement on every lane — the ORM's, the SQL builder's and the raw
+* one — so it never needs to know the contract, which is the thing this package
+* cannot see.
 *
-* **It deliberately opens no span.** Prisma's own `@prisma/instrumentation`,
-* which this package offers to `Instrumentations` and
-* `@btravstack/observability/otel` enables, traces at the ENGINE level — the
-* real SQL, the connection acquisition, the serialisation — all of it below
-* what a client-level wrapper can see. Emitting a span here as well would put two
-* spans on every query for strictly less information. What this wrapper keeps
-* is the pair Prisma's instrumentation does not do at all: a metric, and an
-* error line correlated with the ambient unit.
+* **It starts the operation in `beforeQuery` and settles it in `afterQuery`**,
+* paired by `ctx.planExecutionId`, because that is what `Observers` is for: the
+* port is called at the START and answers a finisher, so an observer can open a
+* span the query runs *inside*. Settling a span reconstructed afterwards from a
+* duration would make it the parent of nothing. It is also why the runtime's
+* own `latencyMs` is not reported — the observer started the operation, so the
+* duration is its own measurement rather than something to pass along.
 *
-* The wrapper is transparent to the answer: whatever the query resolves or
-* rejects with is what the caller receives, which is the kernel's own `RunUnit`
-* rule one layer down. `Promise.reject` re-raises rather than `throw`, so the
-* rejection propagates to `@unthrown/prisma`'s `try*` twin without this file
-* needing a `no-throw` exemption.
+* **Both lanes, because there are two.** A read settles through
+* `afterQuery`; a write with no `RETURNING` — a SQL-builder `delete()` run
+* through `runtime().execute(plan)` — settles through `afterExecute` and would
+* otherwise go unobserved entirely.
+*
+* `completed` is what settles the outcome, and a failed statement does reach
+* the hook: measured against a real database, a duplicate insert arrives as
+* `afterQuery … completed=false` before the rejection surfaces. That is what
+* keeps the errors half of RED honest.
 */
-const instrument = (client, observers) => {
-	return client.$extends({ query: { $allModels: { $allOperations: ({ model, operation, args, query }) => {
-		const settle = (0, _btravstack_core.observe)(observers, {
+const queryObserver = (observers) => {
+	const open = /* @__PURE__ */ new Map();
+	const start = (plan, ctx) => {
+		open.set(ctx.planExecutionId, (0, _btravstack_core.observe)(observers, {
 			component: "database",
-			name: operation,
-			attributes: {
-				model: model ?? "raw",
-				operation
-			},
-			traced: false
-		});
-		return query(args).then((value) => {
-			settle({ outcome: "ok" });
-			return value;
-		}, (cause) => {
-			settle({
-				outcome: "error",
-				cause
-			});
-			return Promise.reject(cause);
+			name: "query",
+			attributes: { scope: ctx.scope ?? "runtime" },
+			...plan.sql === void 0 ? {} : { details: { sql: plan.sql } }
+		}));
+		return Promise.resolve();
+	};
+	const finish = (_plan, result, ctx) => {
+		const settle = open.get(ctx.planExecutionId);
+		open.delete(ctx.planExecutionId);
+		settle?.({
+			outcome: result.completed ? "ok" : "error",
+			...result.source === void 0 ? {} : { attributes: { source: result.source } }
 		});
-	} } } });
-};
-//#endregion
-//#region src/tracing.ts
-/** Injected so a spec can drive the arm where the optional peer is absent. */
-const defaultLoader = async () => (await import("@prisma/instrumentation")).PrismaInstrumentation;
-/**
-* Prisma's own OpenTelemetry instrumentation, loaded if it is installed.
-*
-* Handed to `@btravstack/observability/otel` through the `Instrumentations`
-* set port rather than registered here: a graph with no SDK collects nothing
-* and this is never called, so engine tracing follows from composing `otel()`
-* instead of from importing this package.
-*
-* **A dynamic import, and it has to be**: `@prisma/instrumentation` is an
-* OPTIONAL peer, so a static import would make every consumer install it. The
-* import is attempted once, when the instrumented client is built, and a
-* failure to resolve is an ordinary answer rather than a fault — an application
-* that never wanted engine tracing simply does not have the package.
-*
-* **This can be a provider at all** because `@prisma/instrumentation` patches no
-* modules: `enable()` sets a helper on `globalThis` under a versioned key, and
-* a Prisma client reads it PER QUERY. Registration order is therefore free, and
-* this works after `@prisma/client` is imported and after clients are built.
-* The `--import` preload rule in `@btravstack/observability` governs
-* instrumentations that patch, and does not reach this one.
-*
-* **The skip is logged, not silent.** Telemetry you believe you have and do not
-* is worse than none, so the one path that quietly produces no spans says so at
-* `debug` — the level for something that is a choice rather than a fault.
-*
-* This is the one place in this package that still holds a `Logger`, and it is
-* why the module needs one: it is a STARTUP fact rather than an operation, so
-* the `Observers` seam has nothing to settle. An observer writes lines about
-* operations that fail; a missing optional peer is neither.
-*/
-const loadPrismaInstrumentation = async (logger, load = defaultLoader) => {
-	try {
-		const instrumentation = new (await (load()))();
-		instrumentation.enable();
-		return instrumentation;
-	} catch {
-		logger.debug("engine-level tracing is off: @prisma/instrumentation is not installed. Queries are still counted and failures still logged.");
-		return;
-	}
+		return Promise.resolve();
+	};
+	return {
+		name: "btravstack-observers",
+		familyId: "sql",
+		beforeQuery: start,
+		afterQuery: finish,
+		beforeExecute: start,
+		afterExecute: finish
+	};
 };
 //#endregion
 //#region src/prisma.ts
+/** The one place the cast above is spelled. */
+const probeable = (db) => db;
 /**
 * A Prisma client whose pool is the application scope's.
 *
-* Returns the three pieces a composition root needs and nothing more: the
-* `config` provider binding the connection string, the `port` the client is
-* reached through, and the resourceful `provider` that opens it and closes it
-* again. Put both providers in a module's `provides` and export the port.
+* Returns a module carrying the three pieces a composition root needs and
+* nothing more: the `config` provider binding the connection string, the `port`
+* the client is reached through, and the resourceful provider that opens it and
+* closes it again.
 *
 * **The pool closes on every exit path**, including a boot that fails after
 * this provider ran — that is what makes it resourceful rather than a plain
-* value. `$disconnect` ends the driver adapter's pool without killing the
-* client; Prisma dials again lazily on the next statement, which is why no
-* spec asserts that a released client refuses to query.
+* value. `runtime().close()` ends the pool; Prisma dials again lazily on the
+* next statement, which is why no spec asserts that a released client refuses
+* to query.
 *
-* **Migrations are not run here.** A deployment runs `prisma migrate deploy`
+* **Migrations are not run here.** A deployment runs `prisma db migrate`
 * against this same URL *before the process starts*; an application that
 * migrates itself at boot races every other replica.
 */
 const prismaDatabase = (name) => ({ client }) => {
 	const config = _btravstack_config.Config.provider(`${name}Config`)(_btravstack_config.Config.object({ url: _btravstack_config.Config.string("DATABASE_URL") }));
 	const DatabasePort = (0, _btravstack_di.Port)(name);
-	const open = (url) => client(new _prisma_adapter_pg.PrismaPg({ connectionString: url }));
 	const port = DatabasePort;
 	const clientProvider = (0, _btravstack_di.Provider)(port)({
 		inject: {
 			settings: config.port,
 			observers: _btravstack_core.Observers
 		},
-		acquire: ({ settings, observers }) => {
-			return (0, unthrown.fromSafePromise)(Promise.resolve(instrument(open(settings.url), observers)));
-		},
-		release: (db) => db.$disconnect()
+		acquire: ({ settings, observers }) => (0, unthrown.fromSafePromise)(Promise.resolve().then(() => client({
+			url: settings.url,
+			middleware: [queryObserver(observers)]
+		}))),
+		release: (db) => probeable(db).runtime().close()
 	});
 	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
 		inject: { db: port },
 		sync: ({ db }) => ({
 			name,
-			check: () => (0, unthrown.fromPromise)(db.$queryRaw`SELECT 1`, (cause) => new _btravstack_core.HealthCheckFailed({ reason: cause instanceof Error ? cause.message : "database unreachable" })).map(() => void 0)
+			check: () => (0, unthrown.fromPromise)(probeable(db).runtime().query(probeable(db).raw.sql`SELECT 1`.affectedCount().build()), (cause) => new _btravstack_core.HealthCheckFailed({ reason: cause instanceof Error ? cause.message : "database unreachable" })).map(() => void 0)
 		})
 	});
-	const instrumentation = _btravstack_di.Provider.member(_btravstack_core.Instrumentations)({
-		inject: { logger: _btravstack_core.Logger },
-		sync: ({ logger }) => () => loadPrismaInstrumentation(logger)
-	});
 	const database = (0, _btravstack_di.Module)(name)({
-		needs: [_btravstack_config.Env, _btravstack_core.Logger],
+		needs: [_btravstack_config.Env],
 		provides: [
 			config,
 			_btravstack_di.Provider.member(_btravstack_core.Observers)({
@@ -153,14 +114,9 @@ const prismaDatabase = (name) => ({ client }) => {
 				value: _btravstack_core.noObserver
 			}),
 			clientProvider,
-			healthCheck,
-			instrumentation
+			healthCheck
 		],
-		exports: [
-			DatabasePort,
-			_btravstack_core.HealthChecks,
-			_btravstack_core.Instrumentations
-		]
+		exports: [DatabasePort, _btravstack_core.HealthChecks]
 	});
 	return Object.assign(database, { port: DatabasePort });
 };