@nwire/drizzle 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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

@@ -0,0 +1,69 @@
+# @nwire/drizzle
+
+> Drizzle ORM provider — lifecycle-managed `db` client handlers import directly.
+
+> See: [write paths (actor xor direct-DB)](https://nwire.dev/concepts/write-paths) — direct-DB is one of two write paths; do not mix it with `ctx.use(Actor, id)` in the same handler.
+
+## What it does
+
+Boots a Drizzle ORM client as a Nwire provider so handlers can use the _real_ Drizzle API (full end-to-end TypeScript inference) without DI ceremony. Pluggable health check + telemetry emit on every query. Pairs with [pglite](https://github.com/electric-sql/pglite) for zero-Docker tests.
+
+## Install
+
+```bash
+pnpm add @nwire/drizzle drizzle-orm
+```
+
+## Quick start
+
+```ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { drizzleProvider } from "@nwire/drizzle";
+import { defineApp, defineAction } from "@nwire/forge";
+import * as schema from "./schema.js";
+import { db } from "./db.js";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export const drizzleDb = drizzle(pool, { schema });
+
+defineApp("my-app", {
+ modules: [...],
+ providers: [drizzleProvider({ db: drizzleDb, close: () => pool.end() })],
+});
+
+// In a handler — import db directly:
+defineAction({
+ name: "users.create",
+ handler: async ({ input }) => {
+ const [user] = await db.insert(users).values(input).returning();
+ return user;
+ },
+});
+```
+
+## API surface
+
+- `drizzleProvider({ db, close?, check? })` — provider definition; lifecycle-managed.
+
+## See also
+
+- [Plain CRUD with Drizzle](https://nwire.dev/recipes/data-drizzle) — wiring this provider into an app.
+- [Drizzle migrations + seeds](https://nwire.dev/recipes/drizzle-migrations-seeds) — authoring migrations, boot-vs-deploy, seeds, tests, production checklist.
+
+## When to use
+
+When you want a typed SQL layer with end-to-end inference.Compose with `@nwire/auth-better-auth`
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```

package/dist/data-drizzle.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `@nwire/drizzle` — plugin that lifecycle-manages a Drizzle ORM
+ * client so application handlers can use the *real* Drizzle API directly.
+ *
+ *   import { drizzlePlugin } from "@nwire/drizzle";
+ *   import { drizzle }       from "drizzle-orm/node-postgres";
+ *   import { Pool }          from "pg";
+ *   import * as schema       from "./schema";
+ *
+ *   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ *   const db   = drizzle(pool, { schema });
+ *
+ *   defineApp("my-app", {
+ *     modules: [...],
+ *     plugins: [drizzlePlugin({ db, close: () => pool.end() })],
+ *   });
+ *
+ *   // In a handler — import db directly, no DI ceremony:
+ *   import { db } from "../db";
+ *
+ *   defineAction({
+ *     name: "users.create",
+ *     handler: async (input) => {
+ *       const [user] = await db.insert(users).values(input).returning();
+ *       return UserWasRegistered({ userId: user.id });
+ *     },
+ *   });
+ *
+ * Why "import db directly" instead of `ctx.resolve('db')`:
+ *   - Drizzle's strength is end-to-end TypeScript inference. The schema
+ *     types flow into the query builder. Going through DI erases that.
+ *   - For tests / multi-tenancy where you need a different client, the
+ *     same instance is also registered on the container under the
+ *     plugin's name (default: `"db"`) — `ctx.resolve("db")` works.
+ *   - This is the same recommendation Drizzle's own docs make.
+ *
+ * What the plugin gives you:
+ *   1. Lifecycle — graceful pool close during shutdown.
+ *   2. DI registration — same instance accessible via `ctx.resolve(name)`.
+ *
+ * Health checks belong on the endpoint, not the plugin. Use
+ * `endpoint({ probes: { checks: [{ name: "db", check: () => db.execute(...) }] } })`
+ * to wire a readiness probe — see the `station-mgmt-drizzle` recipe.
+ */
+import { type PluginDefinition } from "@nwire/app";
+/**
+ * Minimum shape we need from a Drizzle client. Kept structural so we don't
+ * have to take a hard dep on a specific drizzle driver (node-postgres,
+ * mysql2, libsql, neon, planetscale, …). The user's `db` is whatever
+ * `drizzle(...)` returned.
+ */
+export type DrizzleClient = Record<string, any>;
+export interface DrizzlePluginOptions<TDb extends DrizzleClient> {
+    /**
+     * The Drizzle client instance — what `drizzle(pool, { schema })` returns.
+     * Pass it in pre-configured; we don't construct it for you so the user
+     * keeps full control of driver choice + schema typing.
+     */
+    readonly db: TDb;
+    /**
+     * Name the client is registered under on the container. Default: `"db"`.
+     * Use a different name when running multiple databases (e.g. `"primary"`,
+     * `"analytics"`).
+     */
+    readonly name?: string;
+    /**
+     * Called during shutdown to close the underlying connection pool.
+     * Examples:
+     *   - node-postgres: `() => pool.end()`
+     *   - mysql2:        `() => pool.end()`
+     *   - better-sqlite3:`() => sqlite.close()`
+     *   - libsql / neon / planetscale: usually a no-op (HTTP-backed)
+     * Optional — omit for drivers that don't need cleanup.
+     */
+    readonly close?: () => Promise<void> | void;
+}
+/**
+ * Build a Nwire plugin that registers a Drizzle client on the container
+ * and tears down its connection pool on shutdown.
+ */
+export declare function drizzlePlugin<TDb extends DrizzleClient>(options: DrizzlePluginOptions<TDb>): PluginDefinition;

package/dist/data-drizzle.js

@@ -0,0 +1,60 @@
+/**
+ * `@nwire/drizzle` — plugin that lifecycle-manages a Drizzle ORM
+ * client so application handlers can use the *real* Drizzle API directly.
+ *
+ *   import { drizzlePlugin } from "@nwire/drizzle";
+ *   import { drizzle }       from "drizzle-orm/node-postgres";
+ *   import { Pool }          from "pg";
+ *   import * as schema       from "./schema";
+ *
+ *   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ *   const db   = drizzle(pool, { schema });
+ *
+ *   defineApp("my-app", {
+ *     modules: [...],
+ *     plugins: [drizzlePlugin({ db, close: () => pool.end() })],
+ *   });
+ *
+ *   // In a handler — import db directly, no DI ceremony:
+ *   import { db } from "../db";
+ *
+ *   defineAction({
+ *     name: "users.create",
+ *     handler: async (input) => {
+ *       const [user] = await db.insert(users).values(input).returning();
+ *       return UserWasRegistered({ userId: user.id });
+ *     },
+ *   });
+ *
+ * Why "import db directly" instead of `ctx.resolve('db')`:
+ *   - Drizzle's strength is end-to-end TypeScript inference. The schema
+ *     types flow into the query builder. Going through DI erases that.
+ *   - For tests / multi-tenancy where you need a different client, the
+ *     same instance is also registered on the container under the
+ *     plugin's name (default: `"db"`) — `ctx.resolve("db")` works.
+ *   - This is the same recommendation Drizzle's own docs make.
+ *
+ * What the plugin gives you:
+ *   1. Lifecycle — graceful pool close during shutdown.
+ *   2. DI registration — same instance accessible via `ctx.resolve(name)`.
+ *
+ * Health checks belong on the endpoint, not the plugin. Use
+ * `endpoint({ probes: { checks: [{ name: "db", check: () => db.execute(...) }] } })`
+ * to wire a readiness probe — see the `station-mgmt-drizzle` recipe.
+ */
+import { definePlugin } from "@nwire/app";
+/**
+ * Build a Nwire plugin that registers a Drizzle client on the container
+ * and tears down its connection pool on shutdown.
+ */
+export function drizzlePlugin(options) {
+    const name = options.name ?? "db";
+    return definePlugin(`drizzle:${name}`, ({ bind, dispose }) => {
+        bind(name, options.db);
+        if (options.close) {
+            dispose(async () => {
+                await options.close();
+            });
+        }
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nwire/drizzle",
+  "version": "0.10.0",
+  "description": "Nwire — Drizzle ORM adapter. Provider that registers a Drizzle client on the container, manages the connection pool lifecycle, and exposes optional readiness checks + telemetry. No Repository wrapper — handlers get the real Drizzle API.",
+  "keywords": [
+    "drizzle",
+    "mysql",
+    "nwire",
+    "orm",
+    "postgres",
+    "provider",
+    "sqlite"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/data-drizzle.js",
+  "types": "./dist/data-drizzle.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/data-drizzle.js",
+      "types": "./dist/data-drizzle.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/app": "0.10.0",
+    "@nwire/forge": "0.10.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.4.5",
+    "@types/node": "^22.19.9",
+    "drizzle-orm": "^0.45.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.40.0"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}