@btravstack/prisma 0.9.0 → 0.11.0

package/README.md

@@ -22,7 +22,7 @@ generated from your schema. Node `>=22`.
 <!-- doctest: group=order-api -->
 <!-- doctest: prelude
 import { Env } from "@btravstack/config";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { Logger } from "@btravstack/core";
 import { Module } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
 
@@ -46,14 +46,15 @@ const database = prismaDatabase("OrderDatabase")({
 });
 ```
 
-That is the whole surface. `database` carries three pieces, and a composition
-root wants all three:
+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:
 
 ```ts
 export const PersistenceModule = Module("Persistence")({
   imports: [database],
   exports: [database.port],
-  needs: [Env, Logger, Meter, Tracer],
+  needs: [Env, Logger],
 });
 ```
 
@@ -72,6 +73,17 @@ port is typed by exactly what it returns.
   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.
 
 ## What it does not
 
@@ -89,9 +101,17 @@ package's.
 
 ## Options
 
-| Option   | Default | What it does                                       |
-| -------- | ------- | -------------------------------------------------- |
-| `client` | —       | Builds the client from the driver adapter and URL. |
+| 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` |
+
+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
+port list. The full table — defaults, semantics and the reasoning — lives on
+[the reference page](https://btravstack.github.io/btravstack/reference/prisma),
+which is this list's one detailed home.
 
 ## License
 

package/dist/index.cjs

@@ -30,27 +30,25 @@ let unthrown = require("unthrown");
 * rejection propagates to `@unthrown/prisma`'s `try*` twin without this file
 * needing a `no-throw` exemption.
 */
-const instrument = (client, logger, meter) => {
-	const operations = meter.createCounter("btravstack.database.operations", { description: "Database queries, by model, operation and outcome" });
+const instrument = (client, observers) => {
 	return client.$extends({ query: { $allModels: { $allOperations: ({ model, operation, args, query }) => {
-		const label = model ?? "raw";
+		const settle = (0, _btravstack_core.observe)(observers, {
+			component: "database",
+			name: operation,
+			attributes: {
+				model: model ?? "raw",
+				operation
+			},
+			traced: false
+		});
 		return query(args).then((value) => {
-			operations.add(1, {
-				model: label,
-				operation,
-				outcome: "ok"
-			});
+			settle({ outcome: "ok" });
 			return value;
 		}, (cause) => {
-			operations.add(1, {
-				model: label,
-				operation,
-				outcome: "error"
+			settle({
+				outcome: "error",
+				cause
 			});
-			logger.error("a database query failed", {
-				model: label,
-				operation
-			}, cause);
 			return Promise.reject(cause);
 		});
 	} } } });
@@ -83,6 +81,11 @@ const defaultLoader = async () => (await import("@prisma/instrumentation")).Pris
 * **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 {
@@ -114,27 +117,21 @@ const loadPrismaInstrumentation = async (logger, load = defaultLoader) => {
 * against this same URL *before the process starts*; an application that
 * migrates itself at boot races every other replica.
 */
-const prismaDatabase = (name) => ({ client, instrumented }) => {
+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 instrumentedProvider = (0, _btravstack_di.Provider)(port)({
+	const clientProvider = (0, _btravstack_di.Provider)(port)({
 		inject: {
 			settings: config.port,
-			logger: _btravstack_core.Logger,
-			meter: _btravstack_core.Meter
+			observers: _btravstack_core.Observers
 		},
-		acquire: ({ settings, logger, meter }) => {
-			return (0, unthrown.fromSafePromise)(Promise.resolve(instrument(open(settings.url), logger, meter)));
+		acquire: ({ settings, observers }) => {
+			return (0, unthrown.fromSafePromise)(Promise.resolve(instrument(open(settings.url), observers)));
 		},
 		release: (db) => db.$disconnect()
 	});
-	const plainProvider = (0, _btravstack_di.Provider)(port)({
-		inject: { settings: config.port },
-		acquire: ({ settings }) => (0, unthrown.OkAsync)(open(settings.url)),
-		release: (db) => db.$disconnect()
-	});
 	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
 		inject: { db: port },
 		sync: ({ db }) => ({
@@ -146,15 +143,15 @@ const prismaDatabase = (name) => ({ client, instrumented }) => {
 		inject: { logger: _btravstack_core.Logger },
 		sync: ({ logger }) => () => loadPrismaInstrumentation(logger)
 	});
-	const instrumentedModule = (0, _btravstack_di.Module)(name)({
-		needs: [
-			_btravstack_config.Env,
-			_btravstack_core.Logger,
-			_btravstack_core.Meter
-		],
+	const chosen = (0, _btravstack_di.Module)(name)({
+		needs: [_btravstack_config.Env, _btravstack_core.Logger],
 		provides: [
 			config,
-			instrumentedProvider,
+			_btravstack_di.Provider.member(_btravstack_core.Observers)({
+				inject: {},
+				value: _btravstack_core.noObserver
+			}),
+			clientProvider,
 			healthCheck,
 			instrumentation
 		],
@@ -164,16 +161,7 @@ const prismaDatabase = (name) => ({ client, instrumented }) => {
 			_btravstack_core.Instrumentations
 		]
 	});
-	const plainModule = (0, _btravstack_di.Module)(name)({
-		needs: [_btravstack_config.Env],
-		provides: [
-			config,
-			plainProvider,
-			healthCheck
-		],
-		exports: [DatabasePort, _btravstack_core.HealthChecks]
-	});
-	return Object.assign(instrumented !== false ? instrumentedModule : plainModule, { port: DatabasePort });
+	return Object.assign(chosen, { port: DatabasePort });
 };
 //#endregion
 exports.prismaDatabase = prismaDatabase;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Env } from "@btravstack/config";
-import { HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
+import { HealthChecks, Instrumentations, Logger, Observers } from "@btravstack/core";
 import { Module, PortClassOf } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
 //#region src/prisma.d.ts
@@ -20,7 +20,7 @@ type PrismaLike = {
   readonly $queryRaw: (query: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>;
 };
 /** What {@link prismaDatabase} is handed. */
-type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
+type PrismaOptions<C extends PrismaLike> = {
   /**
    * Builds the client from the driver adapter, which is already constructed
    * from the environment's URL.
@@ -31,19 +31,6 @@ type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
    * the returned type is exactly the one the application will hold.
    */
   readonly client: (adapter: PrismaPg) => C;
-  /**
-   * Span, count and log every query. **Default `true`**, `false` opts out — the
-   * same shape as `cache`, `mailer` and `storage`, and as `StartOptions`'
-   * `signals` and `probes`.
-   *
-   * On by default because telemetry that is missing is discovered during an
-   * incident. The cost is stated rather than hidden: instrumenting puts
-   * `Logger`, `Meter` and `Tracer` in the provider's dependencies, so a root
-   * without `observability()` and `otel()` gets a compile error naming all
-   * three. It also turns on Prisma's own engine-level tracing when
-   * `@prisma/instrumentation` is installed — no wiring at the root.
-   */
-  readonly instrumented?: Instrumented;
 };
 /**
  * A Prisma client whose pool is the application scope's.
@@ -63,15 +50,11 @@ type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
  * against this same URL *before the process starts*; an application that
  * migrates itself at boot races every other replica.
  */
-declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike, Instrumented extends boolean = true>({ client, instrumented }: PrismaOptions<C, Instrumented>) => (Instrumented extends true ? Module<HealthChecks | Instrumentations | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Logger, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Meter, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | Instrumentations | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | Instrumentations | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>> : Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Logger, HealthChecks | Instrumentations | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>>) & {
+}>>> & {
   readonly port: PortClassOf<N, C>;
 };
 //#endregion

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Env } from "@btravstack/config";
-import { HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
+import { HealthChecks, Instrumentations, Logger, Observers } from "@btravstack/core";
 import { Module, PortClassOf } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
 //#region src/prisma.d.ts
@@ -20,7 +20,7 @@ type PrismaLike = {
   readonly $queryRaw: (query: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>;
 };
 /** What {@link prismaDatabase} is handed. */
-type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
+type PrismaOptions<C extends PrismaLike> = {
   /**
    * Builds the client from the driver adapter, which is already constructed
    * from the environment's URL.
@@ -31,19 +31,6 @@ type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
    * the returned type is exactly the one the application will hold.
    */
   readonly client: (adapter: PrismaPg) => C;
-  /**
-   * Span, count and log every query. **Default `true`**, `false` opts out — the
-   * same shape as `cache`, `mailer` and `storage`, and as `StartOptions`'
-   * `signals` and `probes`.
-   *
-   * On by default because telemetry that is missing is discovered during an
-   * incident. The cost is stated rather than hidden: instrumenting puts
-   * `Logger`, `Meter` and `Tracer` in the provider's dependencies, so a root
-   * without `observability()` and `otel()` gets a compile error naming all
-   * three. It also turns on Prisma's own engine-level tracing when
-   * `@prisma/instrumentation` is installed — no wiring at the root.
-   */
-  readonly instrumented?: Instrumented;
 };
 /**
  * A Prisma client whose pool is the application scope's.
@@ -63,15 +50,11 @@ type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
  * against this same URL *before the process starts*; an application that
  * migrates itself at boot races every other replica.
  */
-declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike, Instrumented extends boolean = true>({ client, instrumented }: PrismaOptions<C, Instrumented>) => (Instrumented extends true ? Module<HealthChecks | Instrumentations | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Logger, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Meter, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | Instrumentations | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | Instrumentations | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>> : Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid, Exclude<Env, HealthChecks | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Logger, HealthChecks | Instrumentations | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>>) & {
+}>>> & {
   readonly port: PortClassOf<N, C>;
 };
 //#endregion

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { Config, Env } from "@btravstack/config";
-import { HealthCheckFailed, HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
+import { HealthCheckFailed, HealthChecks, Instrumentations, Logger, Observers, noObserver, observe } from "@btravstack/core";
 import { Module, Port, Provider } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
-import { OkAsync, fromPromise, fromSafePromise } from "unthrown";
+import { fromPromise, fromSafePromise } from "unthrown";
 //#region src/instrument.ts
 /**
 * Every query, wrapped: a span around it, a count of how it came out, and a log
@@ -29,27 +29,25 @@ import { OkAsync, fromPromise, fromSafePromise } from "unthrown";
 * rejection propagates to `@unthrown/prisma`'s `try*` twin without this file
 * needing a `no-throw` exemption.
 */
-const instrument = (client, logger, meter) => {
-	const operations = meter.createCounter("btravstack.database.operations", { description: "Database queries, by model, operation and outcome" });
+const instrument = (client, observers) => {
 	return client.$extends({ query: { $allModels: { $allOperations: ({ model, operation, args, query }) => {
-		const label = model ?? "raw";
+		const settle = observe(observers, {
+			component: "database",
+			name: operation,
+			attributes: {
+				model: model ?? "raw",
+				operation
+			},
+			traced: false
+		});
 		return query(args).then((value) => {
-			operations.add(1, {
-				model: label,
-				operation,
-				outcome: "ok"
-			});
+			settle({ outcome: "ok" });
 			return value;
 		}, (cause) => {
-			operations.add(1, {
-				model: label,
-				operation,
-				outcome: "error"
+			settle({
+				outcome: "error",
+				cause
 			});
-			logger.error("a database query failed", {
-				model: label,
-				operation
-			}, cause);
 			return Promise.reject(cause);
 		});
 	} } } });
@@ -82,6 +80,11 @@ const defaultLoader = async () => (await import("@prisma/instrumentation")).Pris
 * **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 {
@@ -113,27 +116,21 @@ const loadPrismaInstrumentation = async (logger, load = defaultLoader) => {
 * against this same URL *before the process starts*; an application that
 * migrates itself at boot races every other replica.
 */
-const prismaDatabase = (name) => ({ client, instrumented }) => {
+const prismaDatabase = (name) => ({ client }) => {
 	const config = Config.provider(`${name}Config`)(Config.object({ url: Config.string("DATABASE_URL") }));
 	const DatabasePort = Port(name);
 	const open = (url) => client(new PrismaPg({ connectionString: url }));
 	const port = DatabasePort;
-	const instrumentedProvider = Provider(port)({
+	const clientProvider = Provider(port)({
 		inject: {
 			settings: config.port,
-			logger: Logger,
-			meter: Meter
+			observers: Observers
 		},
-		acquire: ({ settings, logger, meter }) => {
-			return fromSafePromise(Promise.resolve(instrument(open(settings.url), logger, meter)));
+		acquire: ({ settings, observers }) => {
+			return fromSafePromise(Promise.resolve(instrument(open(settings.url), observers)));
 		},
 		release: (db) => db.$disconnect()
 	});
-	const plainProvider = Provider(port)({
-		inject: { settings: config.port },
-		acquire: ({ settings }) => OkAsync(open(settings.url)),
-		release: (db) => db.$disconnect()
-	});
 	const healthCheck = Provider.member(HealthChecks)({
 		inject: { db: port },
 		sync: ({ db }) => ({
@@ -145,15 +142,15 @@ const prismaDatabase = (name) => ({ client, instrumented }) => {
 		inject: { logger: Logger },
 		sync: ({ logger }) => () => loadPrismaInstrumentation(logger)
 	});
-	const instrumentedModule = Module(name)({
-		needs: [
-			Env,
-			Logger,
-			Meter
-		],
+	const chosen = Module(name)({
+		needs: [Env, Logger],
 		provides: [
 			config,
-			instrumentedProvider,
+			Provider.member(Observers)({
+				inject: {},
+				value: noObserver
+			}),
+			clientProvider,
 			healthCheck,
 			instrumentation
 		],
@@ -163,16 +160,7 @@ const prismaDatabase = (name) => ({ client, instrumented }) => {
 			Instrumentations
 		]
 	});
-	const plainModule = Module(name)({
-		needs: [Env],
-		provides: [
-			config,
-			plainProvider,
-			healthCheck
-		],
-		exports: [DatabasePort, HealthChecks]
-	});
-	return Object.assign(instrumented !== false ? instrumentedModule : plainModule, { port: DatabasePort });
+	return Object.assign(chosen, { port: DatabasePort });
 };
 //#endregion
 export { prismaDatabase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/prisma",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "The Prisma starter for @btravstack/core: DATABASE_URL through Config, the Postgres driver adapter, and a client whose pool is the application scope's",
   "keywords": [
     "database",
@@ -53,17 +53,17 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.9.0",
-    "@btravstack/core": "0.9.0",
-    "@btravstack/di": "0.9.0"
+    "@btravstack/config": "0.11.0",
+    "@btravstack/core": "0.11.0",
+    "@btravstack/di": "0.11.0"
   },
   "peerDependencies": {
     "@prisma/adapter-pg": "^7.0.0",
     "@prisma/instrumentation": "^7.0.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.9.0",
-    "@btravstack/core": "^0.9.0",
-    "@btravstack/di": "^0.9.0"
+    "@btravstack/config": "^0.11.0",
+    "@btravstack/core": "^0.11.0",
+    "@btravstack/di": "^0.11.0"
   },
   "peerDependenciesMeta": {
     "@prisma/instrumentation": {