@gobing-ai/ts-db 0.1.0

package/src/entity-dao.ts

@@ -0,0 +1,290 @@
+import { and, count as countFn, eq, type SQL } from 'drizzle-orm';
+import type { SQLiteColumn, SQLiteTable } from 'drizzle-orm/sqlite-core';
+import type { DbClient } from './adapter';
+import { BaseDao } from './base-dao';
+
+/**
+ * Type for tables compatible with EntityDao.
+ * Must have standard columns: createdAt, updatedAt.
+ */
+export type EntityTable = SQLiteTable & {
+    createdAt: SQLiteColumn;
+    updatedAt: SQLiteColumn;
+};
+
+/**
+ * Type for tables with soft delete support.
+ */
+export type SoftDeletableTable = EntityTable & {
+    inUsed: SQLiteColumn;
+};
+
+/**
+ * Type for primary key columns.
+ */
+export type PKColumn = SQLiteColumn;
+
+/**
+ * Generic CRUD base class for entity DAOs.
+ *
+ * Provides standard create, read, update, delete operations with:
+ * - Type-safe public API using Drizzle's inference types
+ * - Automatic soft delete filtering (if table has `inUsed` column)
+ *
+ * @typeParam TTable - The table type (must extend EntityTable)
+ * @typeParam TPK - The primary key column type
+ *
+ * @example
+ * ```ts
+ * export class UsersDao extends EntityDao<typeof users, typeof users.id> {
+ *     constructor(db: DbClient) {
+ *         super(db, users, users.id, 'users');
+ *     }
+ *
+ *     // Add entity-specific methods here
+ *     async findByEmail(email: string) {
+ *         return this.findBy(users.email, email);
+ *     }
+ * }
+ * ```
+ */
+export class EntityDao<TTable extends EntityTable, TPK extends SQLiteColumn> extends BaseDao {
+    constructor(
+        db: DbClient,
+        public readonly table: TTable,
+        protected readonly primaryKey: TPK,
+        protected readonly collectionName: string,
+    ) {
+        super(db);
+    }
+
+    /**
+     * Check if the table has soft delete support (inUsed column).
+     */
+    protected get hasSoftDelete(): boolean {
+        return 'inUsed' in this.table;
+    }
+
+    /**
+     * Build a where condition that filters out soft-deleted records.
+     * Returns undefined if the table doesn't support soft delete.
+     */
+    protected get activeCondition(): SQL | undefined {
+        if (this.hasSoftDelete) {
+            return eq((this.table as unknown as SoftDeletableTable).inUsed, 1);
+        }
+        return undefined;
+    }
+
+    /**
+     * Create a new record.
+     *
+     * `createdAt` and `updatedAt` are auto-filled if not provided.
+     *
+     * @param data - The data to insert (createdAt/updatedAt optional).
+     * @returns The created record.
+     */
+    async create(
+        data: Omit<TTable['$inferInsert'], 'createdAt' | 'updatedAt'> & { createdAt?: number; updatedAt?: number },
+    ): Promise<TTable['$inferSelect']> {
+        const now = this.now();
+        const record = {
+            ...data,
+            createdAt: (data as Record<string, unknown>).createdAt ?? now,
+            updatedAt: (data as Record<string, unknown>).updatedAt ?? now,
+        };
+
+        await this.db.insert(this.table).values(record);
+
+        return record as TTable['$inferSelect'];
+    }
+
+    /**
+     * Find a record by its primary key.
+     *
+     * @param id - The primary key value.
+     * @param includeDeleted - Whether to include soft-deleted records.
+     * @returns The record if found, otherwise undefined.
+     */
+    async findById(id: string | number, includeDeleted = false): Promise<TTable['$inferSelect'] | undefined> {
+        const conditions = [eq(this.primaryKey, id)];
+        if (!includeDeleted && this.activeCondition) {
+            conditions.push(this.activeCondition);
+        }
+
+        const result = await this.db
+            .select()
+            .from(this.table)
+            .where(and(...conditions));
+
+        return (result as TTable['$inferSelect'][])[0];
+    }
+
+    /**
+     * Find all records.
+     *
+     * @param includeDeleted - Whether to include soft-deleted records.
+     * @returns Array of records.
+     */
+    async findAll(includeDeleted = false): Promise<TTable['$inferSelect'][]> {
+        const query = this.db.select().from(this.table);
+
+        if (!includeDeleted && this.activeCondition) {
+            return query.where(this.activeCondition);
+        }
+
+        return query;
+    }
+
+    /**
+     * Update a record by its primary key.
+     *
+     * @param id - The primary key value.
+     * @param data - The data to update.
+     * @returns The updated record if found, otherwise undefined.
+     */
+    async update(
+        id: string | number,
+        data: Partial<TTable['$inferInsert']>,
+    ): Promise<TTable['$inferSelect'] | undefined> {
+        const now = this.now();
+        const updateData = {
+            ...data,
+            updatedAt: now,
+        };
+
+        await this.db.update(this.table).set(updateData).where(eq(this.primaryKey, id));
+
+        return this.findById(id);
+    }
+
+    /**
+     * Delete a record by its primary key.
+     *
+     * @param id - The primary key value.
+     * @param soft - Whether to perform a soft delete (default: true if table supports it).
+     * @returns The deleted record (for soft delete), otherwise undefined.
+     */
+    async delete(id: string | number, soft?: boolean): Promise<TTable['$inferSelect'] | undefined> {
+        const useSoftDelete = soft ?? this.hasSoftDelete;
+
+        if (useSoftDelete && this.hasSoftDelete) {
+            const now = this.now();
+            await this.db
+                .update(this.table)
+                .set({ inUsed: 0, updatedAt: now } as Partial<TTable['$inferInsert']>)
+                .where(eq(this.primaryKey, id));
+
+            return this.findById(id, true);
+        }
+
+        await this.db.delete(this.table).where(eq(this.primaryKey, id));
+
+        return undefined;
+    }
+
+    /**
+     * Find a record by a specific column value.
+     *
+     * @param column - The column to search.
+     * @param value - The value to match.
+     * @param includeDeleted - Whether to include soft-deleted records.
+     * @returns The record if found, otherwise undefined.
+     */
+    async findBy<TCol extends SQLiteColumn>(
+        column: TCol,
+        value: TCol['_']['data'],
+        includeDeleted = false,
+    ): Promise<TTable['$inferSelect'] | undefined> {
+        const conditions = [eq(column, value)];
+        if (!includeDeleted && this.activeCondition) {
+            conditions.push(this.activeCondition);
+        }
+
+        const result = await this.db
+            .select()
+            .from(this.table)
+            .where(and(...conditions));
+
+        return (result as TTable['$inferSelect'][])[0];
+    }
+
+    /**
+     * Find all records matching a specific column value.
+     *
+     * @param column - The column to search.
+     * @param value - The value to match.
+     * @param includeDeleted - Whether to include soft-deleted records.
+     * @returns Array of matching records.
+     */
+    async findAllBy<TCol extends SQLiteColumn>(
+        column: TCol,
+        value: TCol['_']['data'],
+        includeDeleted = false,
+    ): Promise<TTable['$inferSelect'][]> {
+        const conditions = [eq(column, value)];
+        if (!includeDeleted && this.activeCondition) {
+            conditions.push(this.activeCondition);
+        }
+
+        return this.db
+            .select()
+            .from(this.table)
+            .where(and(...conditions));
+    }
+
+    /**
+     * List records with pagination and optional filtering.
+     *
+     * @param options - List options (limit, offset, where).
+     * @returns Array of records.
+     */
+    async list(
+        options: { limit?: number; offset?: number; where?: SQL; includeDeleted?: boolean } = {},
+    ): Promise<TTable['$inferSelect'][]> {
+        const { limit = 100, offset = 0, where, includeDeleted = false } = options;
+        const conditions: SQL[] = [];
+
+        if (!includeDeleted && this.activeCondition) {
+            conditions.push(this.activeCondition);
+        }
+
+        if (where) {
+            conditions.push(where);
+        }
+
+        const query = this.db.select().from(this.table);
+
+        if (conditions.length > 0) {
+            return query
+                .where(and(...conditions))
+                .limit(limit)
+                .offset(offset);
+        }
+
+        return query.limit(limit).offset(offset);
+    }
+
+    /**
+     * Count records in the table.
+     *
+     * @param where - Optional filter condition.
+     * @param includeDeleted - Whether to include soft-deleted records.
+     * @returns The count of matching records.
+     */
+    async count(where?: SQL, includeDeleted = false): Promise<number> {
+        const conditions: SQL[] = [];
+        if (!includeDeleted && this.activeCondition) {
+            conditions.push(this.activeCondition);
+        }
+        if (where) {
+            conditions.push(where);
+        }
+
+        const query = this.db.select<{ value: number }>({ value: countFn() }).from(this.table);
+
+        const result = conditions.length > 0 ? await query.where(and(...conditions)) : await query;
+
+        return result[0]?.value ?? 0;
+    }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type DbClient, type DbTable } from './adapter';
+export { BunSqliteAdapter, type BunSqliteOptions } from './adapters/bun-sqlite';
+export { D1Adapter } from './adapters/d1';
+export { BaseDao } from './base-dao';
+export { type EmbeddedMigration, embeddedMigrations } from './embedded-migrations';
+export { EntityDao, type EntityTable, type PKColumn, type SoftDeletableTable } from './entity-dao';
+export { applyMigrations, type MigrationOptions } from './migrate';
+export { QueueJobDao, type QueueJobRecord, type QueueStats } from './queue-job-dao';
+export {
+    appendOnlyColumns,
+    buildAppendOnlyColumns,
+    buildStandardColumns,
+    buildStandardColumnsWithSoftDelete,
+    nowTimestamp,
+    standardColumns,
+    standardColumnsWithSoftDelete,
+} from './schema/common';
+export { queueJobs } from './schema/queue-jobs';
+export type { SpanContext } from './span-context';

package/src/migrate.ts

@@ -0,0 +1,163 @@
+import { resolve } from 'node:path';
+import type { FileSystem } from '@gobing-ai/ts-runtime';
+
+import type { DbAdapter } from './adapter';
+import { embeddedMigrations } from './embedded-migrations';
+
+/**
+ * Find project root by walking up looking for bun.lock.
+ * @deprecated Use `FileSystem.getProjectRoot()` instead.
+ * @internal — only used for backward compatibility.
+ */
+/** @internal */
+export function findProjectRoot(_startDir: string): string {
+    return process.cwd();
+}
+
+/**
+ * Options for configuring migration behaviour (folder path, table name).
+ */
+export interface MigrationOptions {
+    /** Path to migration SQL files. Default: `fs.resolve('drizzle')` */
+    migrationsFolder?: string;
+    /** Name of the migrations tracking table. Default: '__drizzle_migrations' */
+    migrationsTable?: string;
+    /** File system abstraction for path resolution. */
+    fs?: FileSystem;
+}
+
+/**
+ * Ensure the migration tracking table exists with proper SQLite types.
+ *
+ * drizzle-orm 0.45 generates `id SERIAL PRIMARY KEY` for the journal table,
+ * but SQLite doesn't recognize SERIAL as auto-increment. Pre-create with
+ * proper syntax so drizzle-orm's `CREATE TABLE IF NOT EXISTS` skips it.
+ */
+async function ensureJournalTable(adapter: DbAdapter, table: string): Promise<void> {
+    await adapter.exec(
+        `CREATE TABLE IF NOT EXISTS "${table}" (` +
+            'id INTEGER PRIMARY KEY AUTOINCREMENT, ' +
+            'hash text NOT NULL, ' +
+            'created_at numeric' +
+            ')',
+    );
+}
+
+function validateMigrationTableName(table: string): string {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+        throw new Error(`Invalid migration journal table name: ${table}`);
+    }
+    return table;
+}
+
+/**
+ * Apply migrations from embedded SQL strings (for compiled binaries).
+ *
+ * Checks the journal table and applies only migrations that haven't run yet.
+ * Each migration is executed with adapter.exec() for file-based or adapter.run() for journal tracking.
+ */
+async function applyEmbeddedMigrations(adapter: DbAdapter, journalTable: string): Promise<void> {
+    // Validate journal table name — this is an internal constant, never user input.
+    if (!/^__[a-z_]+$/.test(journalTable)) {
+        throw new Error(`Invalid migration journal table name: ${journalTable}`);
+    }
+    // Get already-applied hashes
+    const appliedHashes = new Set<string>();
+    try {
+        const rows = await adapter.queryAll<{ hash: string }>(`SELECT hash FROM "${journalTable}"`);
+        for (const row of rows) {
+            appliedHashes.add(row.hash);
+        }
+    } catch {
+        // Journal table may not exist yet — will be created by ensureJournalTable
+    }
+
+    let applied = 0;
+    for (const migration of embeddedMigrations) {
+        if (appliedHashes.has(migration.hash)) continue;
+
+        console.info(`Applying embedded migration: ${migration.tag}`);
+
+        // Split on semicolons and execute each non-empty statement
+        const statements = migration.sql
+            .split(';')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+
+        for (const stmt of statements) {
+            await adapter.exec(stmt);
+        }
+
+        // Record in journal
+        await adapter.run(`INSERT INTO "${journalTable}" (hash, created_at) VALUES (?, ?)`, migration.hash, Date.now());
+        applied++;
+    }
+
+    if (applied > 0) {
+        console.info(`Applied ${applied} embedded migration(s)`);
+    }
+}
+
+/**
+ * Apply pending migrations using drizzle-orm's built-in migrator.
+ *
+ * Tracks applied migrations in the `__drizzle_migrations` table.
+ * Safe to call on every startup — already-applied migrations are skipped.
+ *
+ * Two migration strategies:
+ * 1. **File-based** (preferred): reads SQL from a `drizzle/` folder on disk.
+ * 2. **Embedded** (fallback): uses SQL bundled in the binary when no folder exists.
+ *
+ * Only works with BunSqliteAdapter. D1 migrations should use
+ * `wrangler d1 migrations apply` instead.
+ *
+ * @param adapter - A DbAdapter instance (must be BunSqliteAdapter).
+ * @param options - Optional migration folder and table name overrides.
+ */
+export async function applyMigrations(adapter: DbAdapter, options?: MigrationOptions): Promise<void> {
+    const { BunSqliteAdapter } = await import('./adapters/bun-sqlite');
+    if (!(adapter instanceof BunSqliteAdapter)) {
+        console.warn('Skipping in-app migrations: only supported for bun-sqlite adapter');
+        return;
+    }
+
+    const table = validateMigrationTableName(options?.migrationsTable ?? '__drizzle_migrations');
+
+    await ensureJournalTable(adapter, table);
+
+    const folder = options?.migrationsFolder ?? resolve(findProjectRoot(process.cwd()), 'drizzle');
+
+    // File-based migrations: attempt if drizzle/ folder is accessible.
+    // Use FileSystem.exists when available, otherwise try and fall back to embedded.
+    const fs = options?.fs;
+    const tryFileBased = fs?.exists(folder) ?? true; // optimistic when no fs
+
+    if (tryFileBased) {
+        try {
+            const { migrate: drizzleMigrate } = await import('drizzle-orm/bun-sqlite/migrator');
+
+            console.info(`Applying database migrations from ${folder}`);
+
+            await drizzleMigrate(adapter.getDrizzleDb(), {
+                migrationsFolder: folder,
+                ...(options?.migrationsTable !== undefined ? { migrationsTable: options.migrationsTable } : {}),
+            });
+            console.info('Database migrations complete');
+            return;
+        } catch (error) {
+            // If folder doesn't exist, fall through to embedded migrations.
+            // Any other error should be thrown.
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('journal') || message.includes('ENOENT') || message.includes('meta')) {
+                console.info(`File-based migrations unavailable, using embedded: ${message}`);
+            } else {
+                console.error(`[MIGRATE] drizzleMigrate failed: ${message}`);
+                throw error;
+            }
+        }
+    }
+
+    // Fallback: embedded migrations (for compiled binaries)
+    console.info('No drizzle/ folder found — applying embedded migrations');
+    await applyEmbeddedMigrations(adapter, table);
+}