@btravstack/prisma 0.4.0 → 0.6.0

package/README.md

@@ -15,7 +15,7 @@ pnpm add @btravstack/prisma @btravstack/core @btravstack/config @btravstack/di u
 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. Node `>=20`.
+generated from your schema. Node `>=22`.
 
 ## A worked example
 
@@ -32,6 +32,7 @@ import { PrismaPg } from "@prisma/adapter-pg";
 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;
@@ -88,10 +89,9 @@ package's.
 
 ## Options
 
-| Option   | Default          | What it does                                       |
-| -------- | ---------------- | -------------------------------------------------- |
-| `client` | —                | Builds the client from the driver adapter and URL. |
-| `urlVar` | `"DATABASE_URL"` | The variable the connection string is read from.   |
+| Option   | Default | What it does                                       |
+| -------- | ------- | -------------------------------------------------- |
+| `client` | —       | Builds the client from the driver adapter and URL. |
 
 ## License
 

package/dist/index.cjs

@@ -60,7 +60,12 @@ const instrument = (client, logger, meter) => {
 /** 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, turned on if it is installed.
+* 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
@@ -79,7 +84,7 @@ const defaultLoader = async () => (await import("@prisma/instrumentation")).Pris
 * 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.
 */
-const enableTracing = async (logger, load = defaultLoader) => {
+const loadPrismaInstrumentation = async (logger, load = defaultLoader) => {
 	try {
 		const instrumentation = new (await (load()))();
 		instrumentation.enable();
@@ -109,19 +114,18 @@ const enableTracing = 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, urlVar = "DATABASE_URL", instrumented }) => {
-	const config = _btravstack_config.Config.provider(`${name}Config`)(_btravstack_config.Config.object({ url: _btravstack_config.Config.string(urlVar) }));
+const prismaDatabase = (name) => ({ client, instrumented }) => {
+	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 }), url);
+	const open = (url) => client(new _prisma_adapter_pg.PrismaPg({ connectionString: url }));
 	const port = DatabasePort;
 	const instrumentedProvider = (0, _btravstack_di.Provider)(port)({
 		settings: config.port,
 		logger: _btravstack_core.Logger,
-		tracer: _btravstack_core.Tracer,
 		meter: _btravstack_core.Meter
 	}, {
-		acquire: ({ settings, logger, tracer, meter }) => {
-			return (0, unthrown.fromSafePromise)(enableTracing(logger).then(() => instrument(open(settings.url), logger, meter)));
+		acquire: ({ settings, logger, meter }) => {
+			return (0, unthrown.fromSafePromise)(Promise.resolve(instrument(open(settings.url), logger, meter)));
 		},
 		release: (db) => db.$disconnect()
 	});
@@ -129,20 +133,37 @@ const prismaDatabase = (name) => ({ client, urlVar = "DATABASE_URL", instrumente
 		acquire: ({ settings }) => (0, unthrown.OkAsync)(open(settings.url)),
 		release: (db) => db.$disconnect()
 	});
+	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({ 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)
+	}) });
+	const instrumentation = _btravstack_di.Provider.member(_btravstack_core.Instrumentations)({ 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,
-			_btravstack_core.Tracer
+			_btravstack_core.Meter
+		],
+		provides: [
+			config,
+			instrumentedProvider,
+			healthCheck,
+			instrumentation
 		],
-		provides: [config, instrumentedProvider],
-		exports: [DatabasePort]
+		exports: [
+			DatabasePort,
+			_btravstack_core.HealthChecks,
+			_btravstack_core.Instrumentations
+		]
 	});
 	const plainModule = (0, _btravstack_di.Module)(name)({
 		needs: [_btravstack_config.Env],
-		provides: [config, plainProvider],
-		exports: [DatabasePort]
+		provides: [
+			config,
+			plainProvider,
+			healthCheck
+		],
+		exports: [DatabasePort, _btravstack_core.HealthChecks]
 	});
 	return Object.assign(instrumented !== false ? instrumentedModule : plainModule, { port: DatabasePort });
 };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Env } from "@btravstack/config";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
 import { Module, PortClassOf } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
 //#region src/prisma.d.ts
@@ -11,22 +11,26 @@ import { PrismaPg } from "@prisma/adapter-pg";
  */
 type PrismaLike = {
   readonly $disconnect: () => Promise<void>;
+  /**
+   * What the health check asks. Part of the contract rather than optional
+   * because every generated Prisma client has it, and a probe that has to
+   * feature-detect its own client cannot report the difference between "the
+   * database is down" and "this client cannot be asked".
+   */
+  readonly $queryRaw: (query: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>;
 };
 /** What {@link prismaDatabase} is handed. */
 type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
   /**
-   * Builds the client. The driver adapter is already constructed from the
-   * environment's URL; the second argument is that URL, for a client that wants
-   * it directly.
+   * Builds the client from the driver adapter, which is already constructed
+   * from the environment's URL.
    *
    * This is the one thing the starter cannot own: a Prisma client is
    * **generated per application** from its own schema, so there is no client
    * type to ship. Applying `@unthrown/prisma`'s extension belongs here too, so
    * the returned type is exactly the one the application will hold.
    */
-  readonly client: (adapter: PrismaPg, url: string) => C;
-  /** The variable the connection string is read from. `DATABASE_URL` by 12-factor convention. */
-  readonly urlVar?: string;
+  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`'
@@ -59,15 +63,13 @@ 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, urlVar, instrumented }: PrismaOptions<C, Instrumented>) => (Instrumented extends true ? Module<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, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Logger, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+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<Meter, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Logger, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>> | Exclude<Tracer, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Meter, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>> : Module<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, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>>> : 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`, {
   readonly url: string;
 }>>>) & {
   readonly port: PortClassOf<N, C>;

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Env } from "@btravstack/config";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
 import { Module, PortClassOf } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
 //#region src/prisma.d.ts
@@ -11,22 +11,26 @@ import { PrismaPg } from "@prisma/adapter-pg";
  */
 type PrismaLike = {
   readonly $disconnect: () => Promise<void>;
+  /**
+   * What the health check asks. Part of the contract rather than optional
+   * because every generated Prisma client has it, and a probe that has to
+   * feature-detect its own client cannot report the difference between "the
+   * database is down" and "this client cannot be asked".
+   */
+  readonly $queryRaw: (query: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>;
 };
 /** What {@link prismaDatabase} is handed. */
 type PrismaOptions<C extends PrismaLike, Instrumented extends boolean> = {
   /**
-   * Builds the client. The driver adapter is already constructed from the
-   * environment's URL; the second argument is that URL, for a client that wants
-   * it directly.
+   * Builds the client from the driver adapter, which is already constructed
+   * from the environment's URL.
    *
    * This is the one thing the starter cannot own: a Prisma client is
    * **generated per application** from its own schema, so there is no client
    * type to ship. Applying `@unthrown/prisma`'s extension belongs here too, so
    * the returned type is exactly the one the application will hold.
    */
-  readonly client: (adapter: PrismaPg, url: string) => C;
-  /** The variable the connection string is read from. `DATABASE_URL` by 12-factor convention. */
-  readonly urlVar?: string;
+  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`'
@@ -59,15 +63,13 @@ 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, urlVar, instrumented }: PrismaOptions<C, Instrumented>) => (Instrumented extends true ? Module<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, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
-  readonly url: string;
-}>> | Exclude<Logger, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+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<Meter, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Logger, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>> | Exclude<Tracer, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>> | Exclude<Meter, HealthChecks | Instrumentations | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
-}>>> : Module<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, import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+}>>> : 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`, {
   readonly url: string;
 }>>>) & {
   readonly port: PortClassOf<N, C>;

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { Config, Env } from "@btravstack/config";
-import { Logger, Meter, Tracer } from "@btravstack/core";
+import { HealthCheckFailed, HealthChecks, Instrumentations, Logger, Meter } from "@btravstack/core";
 import { Module, Port, Provider } from "@btravstack/di";
 import { PrismaPg } from "@prisma/adapter-pg";
-import { OkAsync, fromSafePromise } from "unthrown";
+import { OkAsync, 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
@@ -59,7 +59,12 @@ const instrument = (client, logger, meter) => {
 /** 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, turned on if it is installed.
+* 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
@@ -78,7 +83,7 @@ const defaultLoader = async () => (await import("@prisma/instrumentation")).Pris
 * 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.
 */
-const enableTracing = async (logger, load = defaultLoader) => {
+const loadPrismaInstrumentation = async (logger, load = defaultLoader) => {
 	try {
 		const instrumentation = new (await (load()))();
 		instrumentation.enable();
@@ -108,19 +113,18 @@ const enableTracing = 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, urlVar = "DATABASE_URL", instrumented }) => {
-	const config = Config.provider(`${name}Config`)(Config.object({ url: Config.string(urlVar) }));
+const prismaDatabase = (name) => ({ client, instrumented }) => {
+	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 }), url);
+	const open = (url) => client(new PrismaPg({ connectionString: url }));
 	const port = DatabasePort;
 	const instrumentedProvider = Provider(port)({
 		settings: config.port,
 		logger: Logger,
-		tracer: Tracer,
 		meter: Meter
 	}, {
-		acquire: ({ settings, logger, tracer, meter }) => {
-			return fromSafePromise(enableTracing(logger).then(() => instrument(open(settings.url), logger, meter)));
+		acquire: ({ settings, logger, meter }) => {
+			return fromSafePromise(Promise.resolve(instrument(open(settings.url), logger, meter)));
 		},
 		release: (db) => db.$disconnect()
 	});
@@ -128,20 +132,37 @@ const prismaDatabase = (name) => ({ client, urlVar = "DATABASE_URL", instrumente
 		acquire: ({ settings }) => OkAsync(open(settings.url)),
 		release: (db) => db.$disconnect()
 	});
+	const healthCheck = Provider.member(HealthChecks)({ db: port }, { sync: ({ db }) => ({
+		name,
+		check: () => fromPromise(db.$queryRaw`SELECT 1`, (cause) => new HealthCheckFailed({ reason: cause instanceof Error ? cause.message : "database unreachable" })).map(() => void 0)
+	}) });
+	const instrumentation = Provider.member(Instrumentations)({ logger: Logger }, { sync: ({ logger }) => () => loadPrismaInstrumentation(logger) });
 	const instrumentedModule = Module(name)({
 		needs: [
 			Env,
 			Logger,
-			Meter,
-			Tracer
+			Meter
+		],
+		provides: [
+			config,
+			instrumentedProvider,
+			healthCheck,
+			instrumentation
 		],
-		provides: [config, instrumentedProvider],
-		exports: [DatabasePort]
+		exports: [
+			DatabasePort,
+			HealthChecks,
+			Instrumentations
+		]
 	});
 	const plainModule = Module(name)({
 		needs: [Env],
-		provides: [config, plainProvider],
-		exports: [DatabasePort]
+		provides: [
+			config,
+			plainProvider,
+			healthCheck
+		],
+		exports: [DatabasePort, HealthChecks]
 	});
 	return Object.assign(instrumented !== false ? instrumentedModule : plainModule, { port: DatabasePort });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/prisma",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0",
-    "@btravstack/core": "0.4.0",
-    "@btravstack/di": "0.4.0"
+    "@btravstack/config": "0.6.0",
+    "@btravstack/core": "0.6.0",
+    "@btravstack/di": "0.6.0"
   },
   "peerDependencies": {
     "@prisma/adapter-pg": "^7.0.0",
     "@prisma/instrumentation": "^7.0.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.4.0",
-    "@btravstack/core": "^0.4.0",
-    "@btravstack/di": "^0.4.0"
+    "@btravstack/config": "^0.6.0",
+    "@btravstack/core": "^0.6.0",
+    "@btravstack/di": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@prisma/instrumentation": {
@@ -71,13 +71,13 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run --coverage",
     "test:types": "tsc -p tsconfig.test-d.json --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
   }
 }