@gobing-ai/ts-db 0.1.0

package/README.md

@@ -0,0 +1,326 @@
+# @gobing-ai/ts-db
+
+Database abstraction layer — adapter pattern with Drizzle ORM, generic CRUD DAOs, job queue persistence, and migration tooling. Supports Bun SQLite (in-memory and file-based) and Cloudflare D1.
+
+## Overview
+
+`ts-db` provides a typed database layer decoupled from any specific storage engine. The `DbAdapter` interface abstracts Bun SQLite and Cloudflare D1 behind a common API, while `BaseDao`, `EntityDao`, and `QueueJobDao` provide progressively richer data access patterns.
+
+| Component | Purpose |
+|-----------|---------|
+| `DbAdapter` | Unified interface across Bun SQLite and D1 |
+| `BunSqliteAdapter` | Bun SQLite implementation with statement caching and WAL pragmas |
+| `D1Adapter` | Cloudflare D1 implementation (no `@cloudflare/workers-types` dependency) |
+| `BaseDao` | Transaction + timestamp utilities for all DAOs |
+| `EntityDao` | Generic CRUD with soft delete, pagination, and `count()` |
+| `QueueJobDao` | Job queue persistence — `enqueue`, `claimReady`, `markCompleted`, `failExpiredJobs` |
+| `applyMigrations` | Drizzle migration runner (file-based + embedded fallback) |
+| `schema` | Reusable Drizzle column helpers + `queue_jobs` table definition |
+| `SpanContext` | Re-exported from `@gobing-ai/ts-runtime` for telemetry |
+
+## Architecture
+
+```mermaid
+classDiagram
+    class DbAdapter {
+        <<interface>>
+        +getDb() DbClient
+        +exec(sql) void
+        +run(sql, ...params) void
+        +queryFirst(sql, ...params) T?
+        +queryAll(sql, ...params) T[]
+        +close() void
+    }
+
+    class BunSqliteAdapter {
+        -Database sqlite
+        -drizzleDb
+        -stmtCache
+        +getDrizzleDb()
+    }
+
+    class D1Adapter {
+        -binding
+        -drizzleDb
+        +getBinding()
+    }
+
+    class BaseDao {
+        <<abstract>>
+        #db
+        +now() number
+        +withTransaction(fn) T
+    }
+
+    class EntityDao {
+        +create(data) TSelect
+        +findById(id) TSelect?
+        +findAll() TSelect[]
+        +update(id, data) TSelect?
+        +delete(id, soft?) TSelect?
+        +findBy(column, value) TSelect?
+        +findAllBy(column, value) TSelect[]
+        +list(opts) TSelect[]
+        +count(where?) number
+        #hasSoftDelete boolean
+        #activeCondition SQL?
+    }
+
+    class QueueJobDao {
+        +enqueue(type, payload, opts?) string
+        +enqueueBatch(jobs) string[]
+        +claimReady(batchSize) QueueJobRecord[]
+        +markProcessing(ids) void
+        +markCompleted(id) void
+        +markFailed(id, attempts, error) void
+        +markForRetry(id, attempts, error, nextRetryAt) void
+        +resetStuckJobs(timeout) number
+        +failExpiredJobs() number
+        +getStats() QueueStats
+    }
+
+    class ColumnHelpers {
+        +standardColumns
+        +standardColumnsWithSoftDelete
+        +appendOnlyColumns
+    }
+
+    class QueueJobsTable {
+        +queueJobs
+    }
+
+    class MigrationRunner {
+        +applyMigrations(adapter, opts?) void
+    }
+
+    class EmbeddedMigrations {
+        +embeddedMigrations EmbeddedMigration[]
+    }
+
+    DbAdapter <|.. BunSqliteAdapter : implements
+    DbAdapter <|.. D1Adapter : implements
+    BaseDao <|-- EntityDao : extends
+    EntityDao <|-- QueueJobDao : extends
+    QueueJobDao --> QueueJobsTable : "uses"
+    MigrationRunner --> EmbeddedMigrations : "uses"
+    MigrationRunner --> BunSqliteAdapter : "requires"
+```
+
+## How It Works
+
+### Adapter pattern
+
+`createDbAdapter()` selects the correct implementation based on driver config:
+
+```ts
+import { createDbAdapter } from '@gobing-ai/ts-db';
+
+// Bun SQLite (in-memory)
+const adapter = await createDbAdapter({ driver: 'bun-sqlite', url: ':memory:' });
+
+// Bun SQLite (file-based with pragmas)
+const adapter = await createDbAdapter({
+    driver: 'bun-sqlite',
+    url: './data/app.db',
+    pragmas: { journalMode: 'PRAGMA journal_mode = WAL' },
+});
+
+// Cloudflare D1
+const adapter = await createDbAdapter({ driver: 'd1', binding: env.DB });
+```
+
+All adapters implement the same `DbAdapter` interface:
+
+```ts
+await adapter.exec('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)');
+await adapter.run('INSERT INTO users VALUES (?, ?)', 'u1', 'Alice');
+const user = await adapter.queryFirst<{ name: string }>('SELECT name FROM users WHERE id = ?', 'u1');
+const all = await adapter.queryAll<{ name: string }>('SELECT name FROM users');
+```
+
+### EntityDao — CRUD with soft delete
+
+Define a Drizzle table, extend `EntityDao`, get full CRUD for free:
+
+```ts
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+import { EntityDao, standardColumns } from '@gobing-ai/ts-db';
+
+const users = sqliteTable('users', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
+    ...standardColumns,
+});
+
+class UsersDao extends EntityDao<typeof users, typeof users.id> {
+    constructor(db: DbClient) {
+        super(db, users, users.id, 'users');
+    }
+
+    async findByEmail(email: string) {
+        return this.findBy(users.email, email);
+    }
+}
+
+// Usage
+const dao = new UsersDao(adapter.getDb());
+const user = await dao.create({ id: 'u1', name: 'Alice', email: 'a@test.com' });
+const found = await dao.findById('u1');
+const updated = await dao.update('u1', { name: 'Alice Updated' });
+const page = await dao.list({ limit: 20, offset: 0 });
+const total = await dao.count();
+await dao.delete('u1'); // soft delete if table has `inUsed` column
+```
+
+**Soft delete** is automatic for tables with an `inUsed` column (from `standardColumnsWithSoftDelete`). Call `findById(id, true)` to include soft-deleted records.
+
+### QueueJobDao — job queue persistence
+
+```ts
+import { QueueJobDao } from '@gobing-ai/ts-db';
+
+const queue = new QueueJobDao(adapter.getDb());
+
+// Enqueue
+const jobId = await queue.enqueue('send-email', { to: 'user@test.com' }, { maxRetries: 5 });
+
+// Consumer: claim ready jobs atomically
+const jobs = await queue.claimReady(10);
+
+for (const job of jobs) {
+    try {
+        await processJob(job);
+        await queue.markCompleted(job.id);
+    } catch (error) {
+        if (job.attempts >= job.maxRetries) {
+            await queue.markFailed(job.id, job.attempts + 1, String(error));
+        } else {
+            const retryAt = Date.now() + Math.pow(2, job.attempts) * 1000;
+            await queue.markForRetry(job.id, job.attempts + 1, String(error), retryAt);
+        }
+    }
+}
+
+// Maintenance
+await queue.resetStuckJobs(30_000); // reset stuck after 30s
+await queue.failExpiredJobs(); // fail expired TTL jobs
+
+const stats = await queue.getStats();
+// → { pending: 5, processing: 2, completed: 100, failed: 3 }
+```
+
+### Migrations
+
+```ts
+import { BunSqliteAdapter, applyMigrations } from '@gobing-ai/ts-db';
+
+const adapter = new BunSqliteAdapter({ databaseUrl: './data/app.db' });
+
+// Applies pending migrations from drizzle/ folder (file-based)
+// Falls back to embedded SQL if no folder exists (compiled binaries, CF Workers)
+await applyMigrations(adapter);
+
+// Safe to call on every startup — already-applied migrations are skipped
+```
+
+### Schema helpers
+
+```ts
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { standardColumns, standardColumnsWithSoftDelete, queueJobs } from '@gobing-ai/ts-db';
+
+// Standard columns (createdAt, updatedAt)
+const docs = sqliteTable('docs', {
+    id: text('id').primaryKey(),
+    title: text('title').notNull(),
+    ...standardColumns,
+});
+
+// With soft delete (adds inUsed column)
+const projects = sqliteTable('projects', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    ...standardColumnsWithSoftDelete,
+});
+
+// queue_jobs table is pre-built for use with QueueJobDao
+```
+
+## Usage
+
+### Install
+
+```bash
+bun add @gobing-ai/ts-db drizzle-orm
+bun add -D drizzle-kit
+```
+
+### Define your schema
+
+```ts
+// src/schema.ts
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { standardColumns } from '@gobing-ai/ts-db';
+
+export const todos = sqliteTable('todos', {
+    id: text('id').primaryKey(),
+    title: text('title').notNull(),
+    done: text('done').notNull().default('0'),
+    ...standardColumns,
+});
+```
+
+### Create a DAO
+
+```ts
+// src/todos-dao.ts
+import type { DbClient } from '@gobing-ai/ts-db';
+import { EntityDao } from '@gobing-ai/ts-db';
+import { todos } from './schema';
+
+export class TodosDao extends EntityDao<typeof todos, typeof todos.id> {
+    constructor(db: DbClient) {
+        super(db, todos, todos.id, 'todos');
+    }
+
+    async findPending() {
+        return this.findAllBy(todos.done, '0');
+    }
+
+    async markDone(id: string) {
+        return this.update(id, { done: '1' });
+    }
+}
+```
+
+### Wire it up
+
+```ts
+// src/index.ts
+import { createDbAdapter, applyMigrations } from '@gobing-ai/ts-db';
+import { TodosDao } from './todos-dao';
+
+const adapter = await createDbAdapter({ driver: 'bun-sqlite', url: ':memory:' });
+await applyMigrations(adapter);
+
+const todos = new TodosDao(adapter.getDb());
+
+await todos.create({ id: '1', title: 'Learn ts-db' });
+await todos.create({ id: '2', title: 'Build something' });
+
+const pending = await todos.findPending();
+// → [{ id: '1', ... }, { id: '2', ... }]
+
+await todos.markDone('1');
+```
+
+### Running with Bun
+
+```bash
+# Generate migrations
+bun drizzle-kit generate
+
+# Apply at startup
+bun run src/index.ts
+```

package/dist/adapter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Minimal D1 binding interface — avoids depending on @cloudflare/workers-types.
+ */
+interface D1Binding {
+    prepare(sql: string): unknown;
+    exec(sql: string): Promise<void>;
+}
+/**
+ * Generic database table descriptor carrying select and insert type info.
+ */
+export interface DbTable<TSelect, TInsert = TSelect> {
+    readonly $inferSelect: TSelect;
+    readonly $inferInsert: TInsert;
+}
+type DbInsertBuilder<TTable extends DbTable<unknown, unknown>> = {
+    values(values: TTable['$inferInsert'] | TTable['$inferInsert'][]): PromiseLike<unknown>;
+};
+interface DbSelectWhereResult<TTable extends DbTable<unknown, unknown>> extends PromiseLike<TTable['$inferSelect'][]> {
+    limit(value: number): DbSelectWhereResult<TTable>;
+    offset(value: number): DbSelectWhereResult<TTable>;
+    orderBy(column: unknown): DbSelectWhereResult<TTable>;
+}
+type DbSelectFromResult<TTable extends DbTable<unknown, unknown>> = DbSelectWhereResult<TTable> & {
+    where(condition: unknown): DbSelectWhereResult<TTable>;
+};
+type DbSelectBuilder = {
+    from<TTable extends DbTable<unknown, unknown>>(table: TTable): DbSelectFromResult<TTable>;
+};
+type DbProjectionSelectBuilder<TProjection> = {
+    from(table: DbTable<unknown, unknown>): PromiseLike<TProjection[]> & {
+        where(condition: unknown): PromiseLike<TProjection[]>;
+    };
+};
+interface DbUpdateResult {
+    changes: number;
+}
+interface DbUpdateBuilder<TTable extends DbTable<unknown, unknown>> {
+    set(values: Partial<TTable['$inferInsert']>): {
+        where(condition: unknown): PromiseLike<DbUpdateResult>;
+    };
+}
+/**
+ * Abstract database client with insert/select/update/delete query builders.
+ */
+export interface DbClient {
+    insert<TTable extends DbTable<unknown, unknown>>(table: TTable): DbInsertBuilder<TTable>;
+    select(): DbSelectBuilder;
+    select<TProjection>(projection: Record<string, unknown>): DbProjectionSelectBuilder<TProjection>;
+    update<TTable extends DbTable<unknown, unknown>>(table: TTable): DbUpdateBuilder<TTable>;
+    delete<TTable extends DbTable<unknown, unknown>>(table: TTable): {
+        where(condition: unknown): PromiseLike<DbUpdateResult>;
+    };
+}
+/**
+ * Database adapter providing a unified client, raw SQL exec, and lifecycle management.
+ */
+export interface DbAdapter {
+    getDb(): DbClient;
+    exec(sql: string): Promise<void>;
+    /** Parameterized write (INSERT/UPDATE/DELETE) that returns no rows. */
+    run(sql: string, ...params: unknown[]): Promise<void>;
+    queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    close(): void;
+}
+/**
+ * Discriminated-union config for creating a database adapter (bun-sqlite or D1).
+ */
+export type DbAdapterConfig = {
+    driver: 'bun-sqlite';
+    url?: string;
+    pragmas?: {
+        journalMode?: string;
+        synchronous?: string;
+        foreignKeys?: string;
+    };
+} | {
+    driver: 'd1';
+    binding: D1Binding;
+};
+/**
+ * Factory: creates the correct {@link DbAdapter} implementation based on driver config.
+ */
+export declare function createDbAdapter(config: DbAdapterConfig): Promise<DbAdapter>;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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

package/dist/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * Factory: creates the correct {@link DbAdapter} implementation based on driver config.
+ */
+export async function createDbAdapter(config) {
+    switch (config.driver) {
+        case 'bun-sqlite': {
+            const { BunSqliteAdapter } = await import('./adapters/bun-sqlite.js');
+            return new BunSqliteAdapter({
+                ...(config.url ? { databaseUrl: config.url } : {}),
+                ...(config.pragmas ? { pragmas: config.pragmas } : {}),
+            });
+        }
+        case 'd1': {
+            const { D1Adapter } = await import('./adapters/d1.js');
+            return new D1Adapter(config.binding);
+        }
+    }
+}

package/dist/adapters/bun-sqlite.d.ts

@@ -0,0 +1,40 @@
+import { type BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import type { DbAdapter, DbClient } from '../adapter';
+import * as schema from '../schema/index';
+/**
+ * Configuration options for the bun:sqlite adapter (path, pragmas).
+ */
+export interface BunSqliteOptions {
+    /** Database path or ":memory:". Default: ".spur/spur.db" */
+    databaseUrl?: string;
+    /** SQLite pragmas. All have sensible defaults. */
+    pragmas?: {
+        journalMode?: string;
+        synchronous?: string;
+        foreignKeys?: string;
+    };
+}
+/**
+ * Bun SQLite database adapter backed by `bun:sqlite`.
+ */
+export declare class BunSqliteAdapter implements DbAdapter {
+    private sqlite;
+    private drizzleDb;
+    /**
+     * Compiled-statement cache keyed by SQL text. `bun:sqlite` statements are
+     * reusable across calls with different params, so caching collapses the
+     * per-call `prepare()` recompile that dominated bulk write loops.
+     */
+    private readonly stmtCache;
+    private getStatement;
+    constructor(options?: BunSqliteOptions);
+    getDb(): DbClient;
+    /** Returns the underlying drizzle instance for migration operations. */
+    getDrizzleDb(): BunSQLiteDatabase<typeof schema>;
+    exec(sql: string): Promise<void>;
+    run(sql: string, ...params: unknown[]): Promise<void>;
+    queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    close(): void;
+}
+//# sourceMappingURL=bun-sqlite.d.ts.map

package/dist/adapters/bun-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun-sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/bun-sqlite.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAW,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAS1C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACL;AAUD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC9C,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAmC;IACpD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IAEpE,OAAO,CAAC,YAAY;gBAUR,OAAO,CAAC,EAAE,gBAAgB;IAkBtC,KAAK,IAAI,QAAQ;IAIjB,wEAAwE;IACxE,YAAY,IAAI,iBAAiB,CAAC,OAAO,MAAM,CAAC;IAI1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKlE,KAAK,IAAI,IAAI;CAGhB"}

package/dist/adapters/bun-sqlite.js

@@ -0,0 +1,70 @@
+import { Database } from 'bun:sqlite';
+import { isAbsolute, resolve } from 'node:path';
+import { drizzle } from 'drizzle-orm/bun-sqlite';
+import * as schema from '../schema/index.js';
+const DEFAULT_PRAGMAS = {
+    journalMode: 'PRAGMA journal_mode = WAL',
+    synchronous: 'PRAGMA synchronous = NORMAL',
+    foreignKeys: 'PRAGMA foreign_keys = ON',
+};
+const DEFAULT_DB_PATH = '.spur/spur.db';
+/**
+ * Bun SQLite database adapter backed by `bun:sqlite`.
+ */
+export class BunSqliteAdapter {
+    sqlite;
+    drizzleDb;
+    /**
+     * Compiled-statement cache keyed by SQL text. `bun:sqlite` statements are
+     * reusable across calls with different params, so caching collapses the
+     * per-call `prepare()` recompile that dominated bulk write loops.
+     */
+    stmtCache = new Map();
+    getStatement(sql) {
+        const cached = this.stmtCache.get(sql);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const stmt = this.sqlite.prepare(sql);
+        this.stmtCache.set(sql, stmt);
+        return stmt;
+    }
+    constructor(options) {
+        let dbPath = options?.databaseUrl ?? DEFAULT_DB_PATH;
+        const pragmas = { ...DEFAULT_PRAGMAS, ...options?.pragmas };
+        // Resolve relative paths
+        if (dbPath !== ':memory:' && !isAbsolute(dbPath)) {
+            dbPath = resolve(dbPath);
+        }
+        this.sqlite = new Database(dbPath, { create: true });
+        this.sqlite.run(pragmas.journalMode);
+        this.sqlite.run(pragmas.synchronous);
+        this.sqlite.run(pragmas.foreignKeys);
+        this.drizzleDb = drizzle({ client: this.sqlite, schema });
+    }
+    getDb() {
+        return this.drizzleDb;
+    }
+    /** Returns the underlying drizzle instance for migration operations. */
+    getDrizzleDb() {
+        return this.drizzleDb;
+    }
+    async exec(sql) {
+        this.sqlite.prepare(sql).run();
+    }
+    async run(sql, ...params) {
+        const stmt = this.getStatement(sql);
+        stmt.run(...params);
+    }
+    async queryFirst(sql, ...params) {
+        const stmt = this.getStatement(sql);
+        return stmt.get(...params);
+    }
+    async queryAll(sql, ...params) {
+        const stmt = this.getStatement(sql);
+        return stmt.all(...params) ?? [];
+    }
+    close() {
+        this.sqlite.close();
+    }
+}

package/dist/adapters/d1.d.ts

@@ -0,0 +1,48 @@
+import type { DbAdapter, DbClient } from '../adapter';
+/**
+ * Minimal D1 binding interface — avoids depending on @cloudflare/workers-types.
+ */
+export interface D1Binding {
+    prepare(sql: string): {
+        bind(...params: unknown[]): D1BoundStatement;
+        first?<T>(): Promise<T | null>;
+        run?(): Promise<{
+            results: unknown[];
+            success: boolean;
+        }>;
+    };
+    exec(sql: string): Promise<void>;
+}
+interface D1BoundStatement {
+    all<T>(): Promise<{
+        results: T[];
+        success: boolean;
+    }>;
+    run(): Promise<{
+        results: unknown[];
+        success: boolean;
+    }>;
+    raw<T>(): Promise<T[]>;
+    first?<T>(): Promise<T | null>;
+}
+/**
+ * Cloudflare D1 database adapter.
+ *
+ * Accepts a D1 binding object matching the Cloudflare Workers D1Database
+ * interface shape. No ambient @cloudflare/workers-types dependency required.
+ */
+export declare class D1Adapter implements DbAdapter {
+    private binding;
+    private drizzleDb;
+    constructor(binding: D1Binding);
+    getDb(): DbClient;
+    /** Returns the non-mutating binding for advanced direct D1 calls. */
+    getBinding(): D1Binding;
+    exec(sql: string): Promise<void>;
+    run(sql: string, ...params: unknown[]): Promise<void>;
+    queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=d1.d.ts.map

package/dist/adapters/d1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1.d.ts","sourceRoot":"","sources":["../../src/adapters/d1.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtD;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAClB,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;QAC7C,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/B,GAAG,CAAC,IAAI,OAAO,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KAC7D,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,UAAU,gBAAgB;IACtB,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtD,GAAG,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzD,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvB,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,SAAS;IACvC,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,SAAS,CAAmC;gBAExC,OAAO,EAAE,SAAS;IAK9B,KAAK,IAAI,QAAQ;IAIjB,qEAAqE;IACrE,UAAU,IAAI,SAAS;IAIjB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAOlE,KAAK,IAAI,IAAI;CAGhB"}

package/dist/adapters/d1.js

@@ -0,0 +1,45 @@
+import { drizzle } from 'drizzle-orm/d1';
+import * as schema from '../schema/index.js';
+/**
+ * Cloudflare D1 database adapter.
+ *
+ * Accepts a D1 binding object matching the Cloudflare Workers D1Database
+ * interface shape. No ambient @cloudflare/workers-types dependency required.
+ */
+export class D1Adapter {
+    binding;
+    drizzleDb;
+    constructor(binding) {
+        this.binding = binding;
+        this.drizzleDb = drizzle(this.binding, { schema });
+    }
+    getDb() {
+        return this.drizzleDb;
+    }
+    /** Returns the non-mutating binding for advanced direct D1 calls. */
+    getBinding() {
+        return this.binding;
+    }
+    async exec(sql) {
+        await this.binding.exec(sql);
+    }
+    async run(sql, ...params) {
+        const stmt = this.binding.prepare(sql);
+        const bound = params.length > 0 ? stmt.bind(...params) : stmt;
+        await bound.run();
+    }
+    async queryFirst(sql, ...params) {
+        const stmt = this.binding.prepare(sql);
+        const bound = params.length > 0 ? stmt.bind(...params) : stmt;
+        return ((await bound.first()) ?? undefined);
+    }
+    async queryAll(sql, ...params) {
+        const stmt = this.binding.prepare(sql);
+        const bound = stmt.bind(...params);
+        const result = await bound.all();
+        return result.results ?? [];
+    }
+    close() {
+        // D1 bindings are managed by the Workers runtime -- no-op
+    }
+}

package/dist/base-dao.d.ts

@@ -0,0 +1,27 @@
+import type { DbClient } from './adapter';
+/**
+ * Abstract base DAO providing transaction and timestamp utilities to all entity DAOs.
+ */
+export declare abstract class BaseDao {
+    protected readonly db: DbClient;
+    /**
+     * DB transaction utility for subclasses.
+     *
+     * Constructor is `protected` — instantiate through concrete DAO subclasses,
+     * not BaseDao directly. Tests must declare an explicit public constructor
+     * that calls `super(db)` to expose the protected constructor publicly.
+     */
+    protected constructor(db: DbClient);
+    protected now(): number;
+    /**
+     * Execute a function within a database transaction.
+     *
+     * Works uniformly on both D1 (async) and bun:sqlite (sync wrapped in promise).
+     * The callback receives a transaction-scoped DbClient.
+     *
+     * @param fn - Function to execute within the transaction.
+     * @returns The return value of `fn`.
+     */
+    protected withTransaction<T>(fn: (tx: DbClient) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=base-dao.d.ts.map

package/dist/base-dao.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-dao.d.ts","sourceRoot":"","sources":["../src/base-dao.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C;;GAEG;AACH,8BAAsB,OAAO;IAQH,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ;IAPrD;;;;;;OAMG;IACH,SAAS,aAAgC,EAAE,EAAE,QAAQ;IAErD,SAAS,CAAC,GAAG,IAAI,MAAM;IAIvB;;;;;;;;OAQG;cACa,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAQnF"}