@beignet/provider-db-drizzle 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @beignet/provider-db-drizzle
 
+## 0.0.27
+
+### Patch Changes
+
+- f2461a9: Add lazy Next route server loaders and update generated route files and package docs to avoid booting providers during production build imports.
+
+## 0.0.26
+
+### Patch Changes
+
+- 104302c: Refresh package-shipped TanStack Intent skills and add package skills for Drizzle database providers, Better Auth, React Hook Form, and React uploads.
+
 ## 0.0.25
 
 ### Patch Changes

package/README.md

@@ -72,6 +72,14 @@ bun add @beignet/provider-db-drizzle @beignet/core drizzle-orm mysql2
 Doctor also checks standard Drizzle config, schema exports, database scripts,
 seed/reset entrypoints, and provider registration drift in generated apps.
 
+## Agent skills
+
+This package ships a TanStack Intent skill for coding agents:
+`@beignet/provider-db-drizzle#database-provider`. Load it when wiring Drizzle
+providers, schema placement, Drizzle config, `DbPort` typing, repository
+adapters, Unit of Work, audit, idempotency, outbox tables, migrations,
+seed/reset helpers, devtools query instrumentation, or database doctor drift.
+
 ## Setup
 
 ### 1. Define your schema
@@ -166,16 +174,19 @@ export type AppPorts = {
 
 ```ts
 // server/index.ts
-import { createNextServer } from "@beignet/next";
+import { createNextServer, createNextServerLoader } from "@beignet/next";
 import { appPorts } from "@/infra/app-ports";
 import { routes } from "@/server/routes";
-import { providers } from "./providers";
 
-export const server = await createNextServer({
-  ports: appPorts,
-  providers,
-  context: ({ ports }) => ({ ports }),
-  routes,
+export const getServer = createNextServerLoader(async () => {
+  const { providers } = await import("./providers");
+
+  return createNextServer({
+    ports: appPorts,
+    providers,
+    context: ({ ports }) => ({ ports }),
+    routes,
+  });
 });
 ```
 
@@ -954,15 +965,14 @@ These choices are deliberate and shared across the three backends:
   idempotency timestamps, plus audit `occurred_at`, as ISO-8601 UTC strings in
   text columns. This keeps retry timing, lease expiry, replay semantics, and
   audit ordering identical across backends, and lexicographic ordering matches
-  chronological ordering. A later release may move the Postgres ports to
-  `timestamptz`.
+  chronological ordering.
 - **MySQL key length limits.** SQLite and Postgres use unbounded text columns
   for idempotency keys; MySQL needs bounded `varchar` columns for its unique
   index, so over-length keys fail loudly rather than truncating silently.
 - **Shared conformance suite.** One conformance suite runs the same Unit of
   Work, outbox, and idempotency behavior tests against SQLite (libSQL),
-  Postgres (PGlite in-process plus a real server in CI), and MySQL (a real
-  server in CI), so durable workflow semantics do not drift between backends.
+  Postgres, and MySQL, so durable workflow semantics do not drift between
+  backends.
 
 ## Advanced usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/provider-db-drizzle",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "type": "module",
   "description": "Drizzle ORM database providers for Beignet — typed DbPort, unit of work, audit logs, outbox, and idempotency for SQLite (libSQL/Turso), Postgres, and MySQL.",
   "exports": {
@@ -35,6 +35,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.test-d.ts",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -60,7 +61,8 @@
     "database",
     "ports",
     "hex",
-    "hexagonal"
+    "hexagonal",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "repository": {

package/skills/database-provider/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: database-provider
+description: "Wire Beignet Drizzle database providers with @beignet/provider-db-drizzle: SQLite/libSQL, Postgres, MySQL, schema placement, Drizzle config, provider registration, DbPort typing, repository adapters, Unit of Work, audit, idempotency, outbox tables, migrations, seed/reset helpers, devtools query instrumentation, and doctor drift. Use when adding, fixing, or reviewing Beignet database provider setup."
+---
+
+# Beignet Drizzle Database Provider
+
+Use this skill when working in an app that depends on
+`@beignet/provider-db-drizzle`. Read local `AGENTS.md`, `beignet.config.*`,
+`drizzle.config.*`, `infra/db/`, `server/providers.ts`, and the nearest
+repository adapter before changing database code.
+
+## Backend Choice
+
+Use the provider subpath that matches the selected database:
+
+- SQLite/libSQL/Turso: `@beignet/provider-db-drizzle/sqlite`
+- Postgres/node-postgres: `@beignet/provider-db-drizzle/postgres`
+- MySQL/mysql2: `@beignet/provider-db-drizzle/mysql`
+
+Switching backends should change driver install, provider subpath, Drizzle
+schema dialect, connection env var, and infra adapters. Contracts, use cases,
+policies, routes, and UI should keep depending on app-owned ports.
+
+## App-Owned Schema
+
+Keep Drizzle schema and migrations in the app, normally:
+
+```txt
+infra/db/schema/
+drizzle/
+drizzle.config.ts
+```
+
+Feature use cases must not import Drizzle schema or provider packages. Put SQL
+mapping in `infra/<feature>/` or `infra/db/` adapters, then expose app-owned
+repository interfaces from `features/<feature>/ports.ts`.
+
+When audit, idempotency, or outbox need provider-owned SQL tables, generate the
+Beignet table exports into the app schema, then run the normal migration flow:
+
+```bash
+beignet db schema generate
+beignet db generate
+beignet db migrate
+```
+
+Use `--tables audit,idempotency,outbox` when adopting a subset.
+
+## Provider Registration
+
+Create the backend provider in `server/providers.ts` or a nearby infra module
+and register it before app-local providers that require `ctx.ports.db`.
+
+```ts
+import { createDrizzleSqliteProvider } from "@beignet/provider-db-drizzle/sqlite";
+import * as schema from "@/infra/db/schema";
+
+const drizzleSqliteProvider = createDrizzleSqliteProvider({ schema });
+
+export const providers = [drizzleSqliteProvider] as const;
+```
+
+Provider env vars:
+
+- SQLite: `SQLITE_DB_URL`, optional `SQLITE_DB_AUTH_TOKEN`
+- Postgres: `POSTGRES_DB_URL`
+- MySQL: `MYSQL_DB_URL`
+
+`beignet doctor --strict` checks required env, provider registration,
+Drizzle config, schema exports, scripts, seed/reset entrypoints, and
+registration drift in generated apps.
+
+## Port Typing
+
+Type the provider-contributed `db` port in app ports, then infer runtime ports
+from the registered providers.
+
+```ts
+import type { DbPort } from "@beignet/provider-db-drizzle/sqlite";
+import type { InferProviderPorts } from "@beignet/core/providers";
+import type * as schema from "@/infra/db/schema";
+import type { providers } from "@/server/providers";
+
+export type AppPorts = {
+  db: DbPort<typeof schema>;
+};
+
+export type AppRuntimePorts = AppPorts & InferProviderPorts<typeof providers>;
+```
+
+Use `ctx.ports.db.drizzle` inside infra and provider wiring. Keep ordinary app
+behavior behind repository, audit, outbox, idempotency, and Unit of Work ports.
+
+## Repositories
+
+Repository factories should accept a root database or transaction client from
+the matching provider subpath:
+
+```ts
+import { eq } from "drizzle-orm";
+import type { DrizzleSqliteDatabase } from "@beignet/provider-db-drizzle/sqlite";
+import type { TodoRepository } from "@/features/todos/ports";
+import * as schema from "@/infra/db/schema";
+
+export function createTodoRepository(
+  db: DrizzleSqliteDatabase<typeof schema>,
+): TodoRepository {
+  return {
+    async findById(id) {
+      const [row] = await db
+        .select()
+        .from(schema.todos)
+        .where(eq(schema.todos.id, id))
+        .limit(1);
+
+      return row ?? null;
+    },
+  };
+}
+```
+
+Collect repositories in an infra factory and contribute them through an
+app-local provider when they depend on `ctx.ports.db`.
+
+## Unit Of Work
+
+Use the backend `createDrizzleXUnitOfWork(...)` helper when a use case needs
+business writes, audit rows, idempotency records, outbox records, or domain
+events to commit together.
+
+Build every transaction-scoped port from the transaction client:
+
+```ts
+uow: createDrizzleSqliteUnitOfWork({
+  db: ports.db.drizzle,
+  eventBus: ports.eventBus,
+  createTransactionPorts: (tx, events) => ({
+    ...createRepositories(tx),
+    events,
+    audit: createDrizzleSqliteAuditLogPort(tx),
+    idempotency: createDrizzleSqliteIdempotencyPort(tx),
+    outbox: createDrizzleSqliteOutboxPort(tx),
+  }),
+});
+```
+
+Root ports are useful for reads and background work. They do not participate in
+the current transaction unless rebuilt from `tx`.
+
+## Gotchas
+
+- The provider installs `ctx.ports.db`; the app still owns schema,
+  migrations, repository interfaces, seed/reset scripts, and Drizzle config.
+- `ctx.ports.db.drizzle` is an infra escape hatch. Do not make it the normal
+  dependency for contracts, use cases, policies, routes, or UI.
+- Register Drizzle before app-local providers that call `ports.db.drizzle` in
+  `setup(...)`.
+- The legacy `ctx.ports.db.db` alias may exist, but new app code should use
+  `drizzle`.
+- Operational ports must be rebuilt from `tx` when they need to commit with
+  the business write.
+
+## Operational Ports
+
+- Audit: use `createDrizzleXAuditLogPort(...)`; wrap with
+  `createInstrumentedAuditLog(...)` or ambient audit helpers when the app needs
+  actor/request defaults and devtools events.
+- Idempotency: use `createDrizzleXIdempotencyPort(...)` with
+  `runIdempotently(...)` when replay safety must survive process restarts.
+- Outbox: use `createDrizzleXOutboxPort(...)`, record inside the transaction,
+  and drain from a worker, cron route, or explicit outbox drain route.
+
+Generate and migrate the backing tables before booting code that depends on
+these ports.
+
+## Testing
+
+Use repository fakes for pure use-case tests. Use isolated Drizzle databases
+for SQL mapping, transactions, migration assumptions, durable idempotency,
+audit rows, and outbox rows.
+
+After database provider changes, run from the app root:
+
+```bash
+beignet lint
+beignet doctor --strict
+bun run test
+bun run typecheck
+```