@beignet/provider-drizzle-turso 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-drizzle-turso
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,415 @@
+# @beignet/provider-drizzle-turso
+
+Drizzle ORM + Turso/libSQL provider for Beignet applications.
+
+The provider installs a typed database port backed by Drizzle ORM and Turso's
+libSQL client. Your application still owns the schema, repository interfaces,
+and migration workflow.
+
+## Features
+
+- Factory-based provider creation with your schema at the call site.
+- Full TypeScript inference from your Drizzle schema.
+- Works with Turso Cloud or local libSQL.
+- Keeps runtime provider wiring separate from Drizzle CLI configuration.
+
+## Install
+
+```bash
+bun add @beignet/provider-drizzle-turso drizzle-orm @libsql/client
+```
+
+## Setup
+
+### 1. Define your schema
+
+Create your Drizzle schema files wherever makes sense for your app. Framework
+usage keeps them under `infra/db/schema/` so larger apps can split schema by
+feature:
+
+```ts
+// infra/db/schema/todos.ts
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const todos = sqliteTable("todos", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at").notNull(),
+});
+```
+
+```ts
+// infra/db/schema/index.ts
+export { todos } from "./todos";
+```
+
+### 2. Configure Drizzle CLI (build-time)
+
+Create `drizzle.config.ts` in your app root for the Drizzle CLI:
+
+```ts
+// drizzle.config.ts
+export default {
+  schema: "./infra/db/schema/index.ts",
+  out: "./drizzle",
+  dialect: "sqlite",
+  dbCredentials: {
+    url: process.env.TURSO_DB_URL!,
+  },
+};
+```
+
+### 3. Create the provider (runtime)
+
+Import your schema and create the provider:
+
+```ts
+// server/providers.ts
+import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+import * as schema from "@/infra/db/schema";
+
+const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+
+export const providers = [drizzleTursoProvider];
+```
+
+### 4. Type your ports
+
+Define your app's ports type:
+
+```ts
+// ports/index.ts
+import type { DbPort } from "@beignet/provider-drizzle-turso";
+import * as schema from "@/infra/db/schema";
+
+export type AppPorts = {
+  db: DbPort<typeof schema>;
+  // other ports...
+};
+```
+
+### 5. Wire it up in your server
+
+```ts
+// server/index.ts
+import { createNextServer } 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,
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+### 6. Expose repository ports to use cases
+
+Use cases should depend on app-owned repository ports. Keep raw Drizzle access in
+infrastructure, then wire the repository into `ctx.ports`.
+
+```ts
+// infra/todos/drizzle-todo-repository.ts
+import { desc } from "drizzle-orm";
+import type { DrizzleTursoDatabase } from "@beignet/provider-drizzle-turso";
+import type { TodoRepository } from "@/features/todos/ports";
+import * as schema from "@/infra/db/schema";
+
+export function createTodoRepository(
+  db: DrizzleTursoDatabase<typeof schema>,
+): TodoRepository {
+  return {
+    async list(input) {
+      return db
+        .select()
+        .from(schema.todos)
+        .orderBy(desc(schema.todos.createdAt))
+        .limit(input.limit)
+        .offset(input.offset);
+    },
+  };
+}
+```
+
+Collect repositories in one infra factory:
+
+```ts
+// infra/db/repositories.ts
+import type { DrizzleTursoDatabase } from "@beignet/provider-drizzle-turso";
+import { createTodoRepository } from "@/infra/todos/drizzle-todo-repository";
+import * as schema from "./schema";
+
+export function createRepositories(db: DrizzleTursoDatabase<typeof schema>) {
+  return {
+    todos: createTodoRepository(db),
+  };
+}
+```
+
+```ts
+// features/todos/use-cases/list-todos.ts
+export const listTodos = useCase.query("todos.list").run(async ({ ctx }) => {
+  return ctx.ports.todos.list({ limit: 20, offset: 0 });
+});
+```
+
+`ctx.ports.db.db` remains available as a provider-specific escape hatch for
+infrastructure code and one-off advanced Drizzle features. Do not make it the
+normal dependency for application use cases.
+
+## Devtools
+
+When `@beignet/devtools` is registered before this provider, Drizzle query
+logging is recorded automatically under the `db` watcher. Events include the SQL
+query text, parameter count, port name, and provider name. Parameter values are
+redacted by default.
+
+```ts
+import { createDevtoolsProvider } from "@beignet/devtools";
+import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+
+export const providers = [
+  createDevtoolsProvider(),
+  createDrizzleTursoProvider({ schema }),
+];
+```
+
+## Unit of work
+
+Use `createDrizzleTursoUnitOfWork(...)` when a use case needs a real database
+transaction. Your app still owns the repository interfaces; the helper only
+starts a Drizzle transaction, gives you the transaction client, and optionally
+flushes recorded domain events after commit.
+
+```ts
+// ports/index.ts
+import type {
+  DomainEventRecorderPort,
+  UnitOfWorkPort,
+} from "@beignet/core/ports";
+import type { DbPort } from "@beignet/provider-drizzle-turso";
+import * as schema from "@/infra/db/schema";
+import type { TodoRepository } from "./todo-repository";
+
+export type AppTransactionPorts = {
+  todos: TodoRepository;
+  events: DomainEventRecorderPort;
+};
+
+export type AppPorts = {
+  db: DbPort<typeof schema>;
+  todos: TodoRepository;
+  uow: UnitOfWorkPort<AppTransactionPorts>;
+};
+```
+
+```ts
+// infra/todos/drizzle-todo-repository.ts
+import type { DrizzleTursoDatabase } from "@beignet/provider-drizzle-turso";
+import type { TodoRepository } from "@/features/todos/ports";
+import * as schema from "@/infra/db/schema";
+
+export function createDrizzleTodoRepository(
+  db: DrizzleTursoDatabase<typeof schema>,
+): TodoRepository {
+  return {
+    async create(input) {
+      const [row] = await db.insert(schema.todos).values(input).returning();
+      return row;
+    },
+  };
+}
+```
+
+```ts
+// server/index.ts
+import { createDrizzleTursoUnitOfWork } from "@beignet/provider-drizzle-turso";
+import { createRepositories } from "@/infra/db/repositories";
+
+createContext: async ({ ports }) => {
+  const repositories = createRepositories(ports.db.db);
+
+  return {
+    ports: {
+      ...ports,
+      ...repositories,
+      uow: createDrizzleTursoUnitOfWork({
+        db: ports.db.db,
+        eventBus: ports.eventBus,
+        createTransactionPorts: (tx, events) => ({
+          ...createRepositories(tx),
+          events,
+        }),
+      }),
+    },
+  };
+};
+```
+
+Inside a use case, call transaction-scoped repositories through `tx` and record
+declared events through the use-case `events` helper:
+
+```ts
+const todo = await ctx.ports.uow.transaction(async (tx) => {
+  const created = await tx.todos.create(input);
+  await events.record(tx.events, todoCreated, { todoId: created.id });
+  return created;
+});
+```
+
+Recorded events are published only after Drizzle commits. If the transaction
+throws, events are not flushed. If event publishing fails after commit,
+`transaction(...)` rejects but the database transaction is already committed;
+use an outbox when events or jobs need durable delivery guarantees.
+
+## Configuration
+
+The provider reads configuration from environment variables with the `TURSO_` prefix:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TURSO_DB_URL` | Yes | Turso/libSQL database URL (e.g., `libsql://your-db.turso.io` or `file:local.db`) |
+| `TURSO_DB_AUTH_TOKEN` | No | Turso auth token (required for cloud databases, optional for local) |
+
+### Example `.env`
+
+```env
+# For Turso cloud
+TURSO_DB_URL=libsql://my-app-db.turso.io
+TURSO_DB_AUTH_TOKEN=eyJhbGciOiJFZERTQSIsInR5cCI...
+
+# For local development
+TURSO_DB_URL=file:local.db
+```
+
+## Advanced usage
+
+### Multiple databases
+
+You can create multiple database providers with different port names:
+
+```ts
+import * as mainSchema from "@/infra/db/schema";
+import * as analyticsSchema from "@/infra/db/analytics-schema";
+import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+
+export const mainDbProvider = createDrizzleTursoProvider({
+  schema: mainSchema,
+  portName: "db", // default
+});
+
+export const analyticsDbProvider = createDrizzleTursoProvider({
+  schema: analyticsSchema,
+  portName: "analyticsDb",
+});
+
+// Then in your ports type:
+export type AppPorts = {
+  db: DbPort<typeof mainSchema>;
+  analyticsDb: DbPort<typeof analyticsSchema>;
+};
+```
+
+### Accessing the Drizzle instance
+
+The `DbPort` exposes the typed Drizzle database instance:
+
+```ts
+import { eq } from "drizzle-orm";
+
+const db = ctx.ports.db.db; // LibSQLDatabase<TSchema>
+
+// All Drizzle operations are available:
+await db.select().from(schema.todos);
+await db.insert(schema.todos).values({ id: "1", title: "Hello" });
+await db.update(schema.todos).set({ title: "Updated" }).where(eq(schema.todos.id, "1"));
+await db.delete(schema.todos).where(eq(schema.todos.id, "1"));
+
+// Prefer repository ports and createDrizzleTursoUnitOfWork(...) for application
+// workflows. Use raw db access in infra, scripts, and vendor-specific escape
+// hatches.
+
+// Access the underlying libSQL client for advanced operations:
+const client = ctx.ports.db.client;
+const result = await client.execute("SELECT * FROM todos WHERE id = ?", ["1"]);
+```
+
+## Key design principles
+
+### Runtime vs. build-time separation
+
+This provider follows a clean separation of concerns:
+
+- **Build-time (Drizzle CLI)**: Configured via `drizzle.config.ts`
+  - Used for generating migrations
+  - Used for introspecting the database
+  - Lives in your app repository
+
+- **Runtime (Provider)**: Configured via factory function
+  - Used for connecting to the database at runtime
+  - Used for executing queries in your use cases
+  - Gets the schema from your imports
+
+### Schema location independence
+
+The provider **does not care** where your schema file lives. You:
+
+1. Define your schema files wherever makes sense (`infra/db/schema/`, `db/schema.ts`, etc.)
+2. Import them in your app: `import * as schema from "@/infra/db/schema"`
+3. Pass it to the factory: `createDrizzleTursoProvider({ schema })`
+
+This keeps the provider flexible and your app in control of its structure.
+
+## API reference
+
+### `DbPort<TSchema>`
+
+The port interface exposed on `ctx.ports.db`:
+
+```ts
+interface DbPort<TSchema extends Record<string, any> = any> {
+  db: LibSQLDatabase<TSchema>;
+  client: Client;
+}
+```
+
+- `db`: The typed Drizzle database instance for ORM operations
+- `client`: The underlying libSQL client for advanced operations not covered by Drizzle
+
+### `createDrizzleTursoProvider<TSchema>(options)`
+
+Factory function to create a Drizzle Turso provider.
+
+**Parameters:**
+- `options.schema` (required): Your Drizzle schema object
+- `options.portName` (optional): Port name, defaults to `"db"`
+
+**Returns:** A provider that can be registered with `createServer`, `createNextServer`, or another Beignet server adapter.
+
+**Example:**
+```ts
+const provider = createDrizzleTursoProvider({
+  schema: mySchema,
+  portName: "db", // optional
+});
+```
+
+### `createDrizzleTursoUnitOfWork<TSchema, TxPorts>(options)`
+
+Factory function to create a transaction-backed `UnitOfWorkPort`.
+
+**Parameters:**
+- `options.db` (required): The root `LibSQLDatabase<TSchema>` instance
+- `options.createTransactionPorts` (required): Factory that receives the Drizzle transaction client and event recorder
+- `options.eventBus` (optional): Event bus used to flush recorded events after commit
+- `options.transactionConfig` (optional): Drizzle transaction configuration
+
+**Returns:** A `UnitOfWorkPort<TxPorts>` that runs work inside
+`db.transaction(...)`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @beignet/provider-drizzle-turso
+ *
+ * Drizzle ORM + Turso/libSQL provider that creates a typed database port.
+ *
+ * Configuration:
+ * - TURSO_DB_URL: Turso/libSQL database URL (required)
+ * - TURSO_DB_AUTH_TOKEN: Turso auth token (optional for local dev)
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ *
+ * // In createNextServer:
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [drizzleTursoProvider],
+ *   // ...
+ * });
+ *
+ * // In infra:
+ * const todos = createDrizzleTodoRepository(ctx.ports.db.db);
+ * ```
+ */
+import { type BufferedDomainEventRecorder, type EventBusPort, type UnitOfWorkPort } from "@beignet/core/ports";
+import { type Client } from "@libsql/client";
+import type { ExtractTablesWithRelations } from "drizzle-orm";
+import { type LibSQLDatabase } from "drizzle-orm/libsql";
+import type { LibSQLTransaction } from "drizzle-orm/libsql/session";
+import type { SQLiteTransactionConfig } from "drizzle-orm/sqlite-core";
+import { z } from "zod";
+/**
+ * Typed database port interface.
+ * Exposes a typed Drizzle database instance for your schema.
+ *
+ * @template TSchema - The Drizzle schema type (e.g., `typeof schema`)
+ */
+export interface DbPort<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * The typed Drizzle database instance.
+     * Use this to query your database with full type safety.
+     */
+    db: LibSQLDatabase<TSchema>;
+    /**
+     * The underlying libSQL client instance.
+     * Use this for advanced operations not covered by Drizzle ORM.
+     */
+    client: Client;
+}
+/**
+ * Drizzle database or transaction client accepted by repository factories.
+ */
+export type DrizzleTursoDatabase<TSchema extends Record<string, unknown> = Record<string, unknown>> = LibSQLDatabase<TSchema> | LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
+/**
+ * Drizzle transaction client passed to Unit of Work repository factories.
+ */
+export type DrizzleTursoTransaction<TSchema extends Record<string, unknown> = Record<string, unknown>> = LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
+export interface DrizzleTursoUnitOfWorkOptions<TSchema extends Record<string, unknown>, TxPorts> {
+    /**
+     * The root Drizzle database instance from `ctx.ports.db.db`.
+     */
+    db: LibSQLDatabase<TSchema>;
+    /**
+     * Create transaction-scoped ports from the Drizzle transaction client.
+     *
+     * The event recorder is transaction-local. Record domain events inside the
+     * callback and pass `eventBus` to publish them after the database commit.
+     */
+    createTransactionPorts: (db: DrizzleTursoTransaction<TSchema>, events: BufferedDomainEventRecorder) => TxPorts;
+    /**
+     * Optional event bus used to flush recorded domain events after commit.
+     */
+    eventBus?: EventBusPort;
+    /**
+     * Optional Drizzle transaction configuration.
+     */
+    transactionConfig?: SQLiteTransactionConfig;
+}
+/**
+ * Create a Unit of Work port backed by Drizzle's libSQL transaction API.
+ *
+ * Beignet does not own your repository interfaces. This helper only
+ * provides the transaction boundary and post-commit event flushing; your app
+ * decides which transaction-scoped ports to create.
+ */
+export declare function createDrizzleTursoUnitOfWork<TSchema extends Record<string, unknown>, TxPorts>(options: DrizzleTursoUnitOfWorkOptions<TSchema, TxPorts>): UnitOfWorkPort<TxPorts>;
+/**
+ * Configuration schema for the Drizzle Turso provider.
+ * Validates environment variables with TURSO_ prefix.
+ */
+declare const TursoConfigSchema: z.ZodObject<{
+    DB_URL: z.ZodString;
+    DB_AUTH_TOKEN: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Inferred configuration type for Turso provider.
+ */
+export type TursoConfig = z.infer<typeof TursoConfigSchema>;
+/**
+ * Options for creating a Drizzle Turso provider.
+ *
+ * @template TSchema - The Drizzle schema type
+ */
+export interface DrizzleTursoProviderOptions<TSchema extends Record<string, unknown>, PortName extends string = "db"> {
+    /**
+     * The Drizzle schema object (e.g. `import * as schema from '@/db/schema'`).
+     * This schema is used to create a typed Drizzle database instance.
+     */
+    schema: TSchema;
+    /**
+     * Optional port name. Defaults to "db".
+     * If you want multiple databases, you can override this.
+     */
+    portName?: PortName;
+}
+/**
+ * Create a Drizzle Turso provider factory.
+ *
+ * This factory creates a service provider that:
+ * - Uses Turso / libSQL via @libsql/client
+ * - Uses Drizzle ORM via drizzle-orm/libsql
+ * - Exposes a typed DbPort<TSchema> on ports
+ * - Uses TURSO_-prefixed env vars for connection config
+ *
+ * @template TSchema - The Drizzle schema type (inferred from the schema parameter)
+ * @param options - Configuration options including the schema
+ * @returns A service provider that can be used with createNextServer
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ * ```
+ */
+export declare function createDrizzleTursoProvider<TSchema extends Record<string, unknown>, PortName extends string = "db">(options: DrizzleTursoProviderOptions<TSchema, PortName>): import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    DB_URL: z.ZodString;
+    DB_AUTH_TOKEN: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<PortName, DbPort<TSchema>>>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,163 @@
+/**
+ * @beignet/provider-drizzle-turso
+ *
+ * Drizzle ORM + Turso/libSQL provider that creates a typed database port.
+ *
+ * Configuration:
+ * - TURSO_DB_URL: Turso/libSQL database URL (required)
+ * - TURSO_DB_AUTH_TOKEN: Turso auth token (optional for local dev)
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ *
+ * // In createNextServer:
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [drizzleTursoProvider],
+ *   // ...
+ * });
+ *
+ * // In infra:
+ * const todos = createDrizzleTodoRepository(ctx.ports.db.db);
+ * ```
+ */
+import { createDomainEventRecorder, } from "@beignet/core/ports";
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { createClient } from "@libsql/client";
+import { drizzle } from "drizzle-orm/libsql";
+import { z } from "zod";
+/**
+ * Create a Unit of Work port backed by Drizzle's libSQL transaction API.
+ *
+ * Beignet does not own your repository interfaces. This helper only
+ * provides the transaction boundary and post-commit event flushing; your app
+ * decides which transaction-scoped ports to create.
+ */
+export function createDrizzleTursoUnitOfWork(options) {
+    return {
+        async transaction(work) {
+            const events = createDomainEventRecorder();
+            const result = await options.db.transaction(async (tx) => {
+                const txPorts = options.createTransactionPorts(tx, events);
+                return work(txPorts);
+            }, options.transactionConfig);
+            if (options.eventBus) {
+                await events.flush(options.eventBus);
+            }
+            return result;
+        },
+    };
+}
+/**
+ * Configuration schema for the Drizzle Turso provider.
+ * Validates environment variables with TURSO_ prefix.
+ */
+const TursoConfigSchema = z.object({
+    /**
+     * Turso / libSQL database URL.
+     * Example: "libsql://<org>-<db>.turso.io" or "file:local.db"
+     */
+    DB_URL: z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("libsql://") || val.startsWith("file:"), {
+        message: 'DB_URL must be a valid "libsql://" or "file:" URL (e.g., "libsql://<org>-<db>.turso.io" or "file:local.db")',
+    }),
+    /**
+     * Turso auth token (optional for local dev).
+     * Required when connecting to Turso cloud databases.
+     */
+    DB_AUTH_TOKEN: z.string().optional(),
+});
+function summarizeQuery(query) {
+    const normalized = query.replace(/\s+/g, " ").trim();
+    return normalized.length > 120
+        ? `${normalized.slice(0, 117)}...`
+        : normalized;
+}
+/**
+ * Create a Drizzle Turso provider factory.
+ *
+ * This factory creates a service provider that:
+ * - Uses Turso / libSQL via @libsql/client
+ * - Uses Drizzle ORM via drizzle-orm/libsql
+ * - Exposes a typed DbPort<TSchema> on ports
+ * - Uses TURSO_-prefixed env vars for connection config
+ *
+ * @template TSchema - The Drizzle schema type (inferred from the schema parameter)
+ * @param options - Configuration options including the schema
+ * @returns A service provider that can be used with createNextServer
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ * ```
+ */
+export function createDrizzleTursoProvider(options) {
+    const { schema, portName = "db" } = options;
+    return createProvider({
+        name: "drizzle-turso",
+        config: {
+            schema: TursoConfigSchema,
+            envPrefix: "TURSO_",
+        },
+        async setup({ ports, config }) {
+            if (!config) {
+                throw new Error("[drizzleTursoProvider] Missing config. Set TURSO_DB_URL (and optional TURSO_DB_AUTH_TOKEN).");
+            }
+            // 1. Create Turso client
+            const client = createClient({
+                url: config.DB_URL,
+                authToken: config.DB_AUTH_TOKEN,
+            });
+            const instrumentation = createProviderInstrumentation(ports, {
+                providerName: "drizzle-turso",
+                watcher: "db",
+            });
+            const logger = instrumentation.isEnabled()
+                ? {
+                    logQuery(query, params) {
+                        instrumentation.custom({
+                            name: "db.query",
+                            label: "Database query",
+                            summary: summarizeQuery(query),
+                            details: {
+                                query,
+                                params: params.length > 0 ? "[redacted]" : [],
+                                paramsCount: params.length,
+                                portName,
+                            },
+                        });
+                    },
+                }
+                : undefined;
+            // 2. Create typed Drizzle instance
+            const db = logger
+                ? drizzle(client, { schema, logger })
+                : drizzle(client, { schema });
+            // 3. Build a typed DbPort
+            const dbPort = { db, client };
+            return {
+                ports: { [portName]: dbPort },
+                async stop() {
+                    // Gracefully close the database connection
+                    try {
+                        await dbPort.client.close();
+                    }
+                    catch (error) {
+                        // Log error but don't throw - we're shutting down anyway
+                        console.error("[drizzleTursoProvider] Error closing database connection:", error);
+                    }
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@beignet/provider-drizzle-turso",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Drizzle ORM + Turso/libSQL provider for Beignet - adds typed DbPort using drizzle-orm",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "drizzle",
+    "turso",
+    "libsql",
+    "provider",
+    "database",
+    "ports",
+    "hex",
+    "hexagonal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-drizzle-turso"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@libsql/client": "^0.6.0 || ^0.14.0 || ^0.15.0",
+    "drizzle-orm": "^0.36.0 || ^0.37.0 || ^0.38.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@libsql/client": "^0.14.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "drizzle-orm": "^0.38.3",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,306 @@
+/**
+ * @beignet/provider-drizzle-turso
+ *
+ * Drizzle ORM + Turso/libSQL provider that creates a typed database port.
+ *
+ * Configuration:
+ * - TURSO_DB_URL: Turso/libSQL database URL (required)
+ * - TURSO_DB_AUTH_TOKEN: Turso auth token (optional for local dev)
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ *
+ * // In createNextServer:
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [drizzleTursoProvider],
+ *   // ...
+ * });
+ *
+ * // In infra:
+ * const todos = createDrizzleTodoRepository(ctx.ports.db.db);
+ * ```
+ */
+
+import {
+  type BufferedDomainEventRecorder,
+  createDomainEventRecorder,
+  type EventBusPort,
+  type UnitOfWorkCallback,
+  type UnitOfWorkPort,
+} from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+} from "@beignet/core/providers";
+import { type Client, createClient } from "@libsql/client";
+import type { ExtractTablesWithRelations } from "drizzle-orm";
+import { drizzle, type LibSQLDatabase } from "drizzle-orm/libsql";
+import type { LibSQLTransaction } from "drizzle-orm/libsql/session";
+import type { SQLiteTransactionConfig } from "drizzle-orm/sqlite-core";
+import { z } from "zod";
+
+/**
+ * Typed database port interface.
+ * Exposes a typed Drizzle database instance for your schema.
+ *
+ * @template TSchema - The Drizzle schema type (e.g., `typeof schema`)
+ */
+export interface DbPort<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /**
+   * The typed Drizzle database instance.
+   * Use this to query your database with full type safety.
+   */
+  db: LibSQLDatabase<TSchema>;
+
+  /**
+   * The underlying libSQL client instance.
+   * Use this for advanced operations not covered by Drizzle ORM.
+   */
+  client: Client;
+}
+
+/**
+ * Drizzle database or transaction client accepted by repository factories.
+ */
+export type DrizzleTursoDatabase<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> =
+  | LibSQLDatabase<TSchema>
+  | LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
+
+/**
+ * Drizzle transaction client passed to Unit of Work repository factories.
+ */
+export type DrizzleTursoTransaction<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> = LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
+
+export interface DrizzleTursoUnitOfWorkOptions<
+  TSchema extends Record<string, unknown>,
+  TxPorts,
+> {
+  /**
+   * The root Drizzle database instance from `ctx.ports.db.db`.
+   */
+  db: LibSQLDatabase<TSchema>;
+
+  /**
+   * Create transaction-scoped ports from the Drizzle transaction client.
+   *
+   * The event recorder is transaction-local. Record domain events inside the
+   * callback and pass `eventBus` to publish them after the database commit.
+   */
+  createTransactionPorts: (
+    db: DrizzleTursoTransaction<TSchema>,
+    events: BufferedDomainEventRecorder,
+  ) => TxPorts;
+
+  /**
+   * Optional event bus used to flush recorded domain events after commit.
+   */
+  eventBus?: EventBusPort;
+
+  /**
+   * Optional Drizzle transaction configuration.
+   */
+  transactionConfig?: SQLiteTransactionConfig;
+}
+
+/**
+ * Create a Unit of Work port backed by Drizzle's libSQL transaction API.
+ *
+ * Beignet does not own your repository interfaces. This helper only
+ * provides the transaction boundary and post-commit event flushing; your app
+ * decides which transaction-scoped ports to create.
+ */
+export function createDrizzleTursoUnitOfWork<
+  TSchema extends Record<string, unknown>,
+  TxPorts,
+>(
+  options: DrizzleTursoUnitOfWorkOptions<TSchema, TxPorts>,
+): UnitOfWorkPort<TxPorts> {
+  return {
+    async transaction<Result>(
+      work: UnitOfWorkCallback<TxPorts, Result>,
+    ): Promise<Result> {
+      const events = createDomainEventRecorder();
+
+      const result = await options.db.transaction(async (tx) => {
+        const txPorts = options.createTransactionPorts(
+          tx as DrizzleTursoTransaction<TSchema>,
+          events,
+        );
+        return work(txPorts);
+      }, options.transactionConfig);
+
+      if (options.eventBus) {
+        await events.flush(options.eventBus);
+      }
+
+      return result;
+    },
+  };
+}
+
+/**
+ * Configuration schema for the Drizzle Turso provider.
+ * Validates environment variables with TURSO_ prefix.
+ */
+const TursoConfigSchema = z.object({
+  /**
+   * Turso / libSQL database URL.
+   * Example: "libsql://<org>-<db>.turso.io" or "file:local.db"
+   */
+  DB_URL: z
+    .string()
+    .min(1)
+    .refine((val) => val.startsWith("libsql://") || val.startsWith("file:"), {
+      message:
+        'DB_URL must be a valid "libsql://" or "file:" URL (e.g., "libsql://<org>-<db>.turso.io" or "file:local.db")',
+    }),
+
+  /**
+   * Turso auth token (optional for local dev).
+   * Required when connecting to Turso cloud databases.
+   */
+  DB_AUTH_TOKEN: z.string().optional(),
+});
+
+/**
+ * Inferred configuration type for Turso provider.
+ */
+export type TursoConfig = z.infer<typeof TursoConfigSchema>;
+
+function summarizeQuery(query: string): string {
+  const normalized = query.replace(/\s+/g, " ").trim();
+  return normalized.length > 120
+    ? `${normalized.slice(0, 117)}...`
+    : normalized;
+}
+
+/**
+ * Options for creating a Drizzle Turso provider.
+ *
+ * @template TSchema - The Drizzle schema type
+ */
+export interface DrizzleTursoProviderOptions<
+  TSchema extends Record<string, unknown>,
+  PortName extends string = "db",
+> {
+  /**
+   * The Drizzle schema object (e.g. `import * as schema from '@/db/schema'`).
+   * This schema is used to create a typed Drizzle database instance.
+   */
+  schema: TSchema;
+
+  /**
+   * Optional port name. Defaults to "db".
+   * If you want multiple databases, you can override this.
+   */
+  portName?: PortName;
+}
+
+/**
+ * Create a Drizzle Turso provider factory.
+ *
+ * This factory creates a service provider that:
+ * - Uses Turso / libSQL via @libsql/client
+ * - Uses Drizzle ORM via drizzle-orm/libsql
+ * - Exposes a typed DbPort<TSchema> on ports
+ * - Uses TURSO_-prefixed env vars for connection config
+ *
+ * @template TSchema - The Drizzle schema type (inferred from the schema parameter)
+ * @param options - Configuration options including the schema
+ * @returns A service provider that can be used with createNextServer
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";
+ *
+ * export const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+ * ```
+ */
+export function createDrizzleTursoProvider<
+  TSchema extends Record<string, unknown>,
+  PortName extends string = "db",
+>(options: DrizzleTursoProviderOptions<TSchema, PortName>) {
+  const { schema, portName = "db" } = options;
+
+  return createProvider({
+    name: "drizzle-turso",
+
+    config: {
+      schema: TursoConfigSchema,
+      envPrefix: "TURSO_",
+    },
+
+    async setup({ ports, config }) {
+      if (!config) {
+        throw new Error(
+          "[drizzleTursoProvider] Missing config. Set TURSO_DB_URL (and optional TURSO_DB_AUTH_TOKEN).",
+        );
+      }
+
+      // 1. Create Turso client
+      const client: Client = createClient({
+        url: config.DB_URL,
+        authToken: config.DB_AUTH_TOKEN,
+      });
+
+      const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "drizzle-turso",
+        watcher: "db",
+      });
+
+      const logger = instrumentation.isEnabled()
+        ? {
+            logQuery(query: string, params: unknown[]) {
+              instrumentation.custom({
+                name: "db.query",
+                label: "Database query",
+                summary: summarizeQuery(query),
+                details: {
+                  query,
+                  params: params.length > 0 ? "[redacted]" : [],
+                  paramsCount: params.length,
+                  portName,
+                },
+              });
+            },
+          }
+        : undefined;
+
+      // 2. Create typed Drizzle instance
+      const db: LibSQLDatabase<TSchema> = logger
+        ? drizzle(client, { schema, logger })
+        : drizzle(client, { schema });
+
+      // 3. Build a typed DbPort
+      const dbPort: DbPort<TSchema> = { db, client };
+
+      return {
+        ports: { [portName]: dbPort } as Record<PortName, DbPort<TSchema>>,
+        async stop() {
+          // Gracefully close the database connection
+          try {
+            await dbPort.client.close();
+          } catch (error) {
+            // Log error but don't throw - we're shutting down anyway
+            console.error(
+              "[drizzleTursoProvider] Error closing database connection:",
+              error,
+            );
+          }
+        },
+      };
+    },
+  });
+}