@gobing-ai/ts-db 0.2.8 → 0.3.0

package/src/migrate.ts

@@ -5,13 +5,16 @@ 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.
+ * Minimal structural logger for migration progress.
+ *
+ * Structurally compatible with `@gobing-ai/ts-infra`'s `Logger` so consumers can
+ * pass theirs directly — ts-db never imports ts-infra (keeps the package
+ * boundary). Defaults to `console` when absent.
  */
-/** @internal */
-export function findProjectRoot(_startDir: string): string {
-    return process.cwd();
+export interface MigrationLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
 }
 
 /**
@@ -24,6 +27,8 @@ export interface MigrationOptions {
     migrationsTable?: string;
     /** File system abstraction for path resolution. */
     fs?: FileSystem;
+    /** Logger for migration progress. Default: `console`. */
+    logger?: MigrationLogger;
 }
 
 /**
@@ -56,7 +61,11 @@ function validateMigrationTableName(table: string): string {
  * 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> {
+async function applyEmbeddedMigrations(
+    adapter: DbAdapter,
+    journalTable: string,
+    logger: MigrationLogger,
+): 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}`);
@@ -76,7 +85,7 @@ async function applyEmbeddedMigrations(adapter: DbAdapter, journalTable: string)
     for (const migration of embeddedMigrations) {
         if (appliedHashes.has(migration.hash)) continue;
 
-        console.info(`Applying embedded migration: ${migration.tag}`);
+        logger.info(`Applying embedded migration: ${migration.tag}`);
 
         // Split on semicolons and execute each non-empty statement
         const statements = migration.sql
@@ -94,7 +103,7 @@ async function applyEmbeddedMigrations(adapter: DbAdapter, journalTable: string)
     }
 
     if (applied > 0) {
-        console.info(`Applied ${applied} embedded migration(s)`);
+        logger.info(`Applied ${applied} embedded migration(s)`);
     }
 }
 
@@ -115,9 +124,10 @@ async function applyEmbeddedMigrations(adapter: DbAdapter, journalTable: string)
  * @param options - Optional migration folder and table name overrides.
  */
 export async function applyMigrations(adapter: DbAdapter, options?: MigrationOptions): Promise<void> {
+    const logger = options?.logger ?? console;
     const { BunSqliteAdapter } = await import('./adapters/bun-sqlite');
     if (!(adapter instanceof BunSqliteAdapter)) {
-        console.warn('Skipping in-app migrations: only supported for bun-sqlite adapter');
+        logger.warn('Skipping in-app migrations: only supported for bun-sqlite adapter');
         return;
     }
 
@@ -125,39 +135,41 @@ export async function applyMigrations(adapter: DbAdapter, options?: MigrationOpt
 
     await ensureJournalTable(adapter, table);
 
-    const folder = options?.migrationsFolder ?? resolve(findProjectRoot(process.cwd()), 'drizzle');
+    const folder = options?.migrationsFolder ?? resolve(process.cwd(), 'drizzle');
 
-    // File-based migrations: attempt if drizzle/ folder is accessible.
-    // Use FileSystem.exists when available, otherwise try and fall back to embedded.
+    // File-based migrations: attempt only if the drizzle/ folder is present.
+    // With an injected fs we get a definitive answer (await the Promise — a bare
+    // `fs.exists(...)` is always truthy and silently disables the check); without
+    // one we attempt optimistically and fall back on the migrator's own error.
     const fs = options?.fs;
-    const tryFileBased = fs?.exists(folder) ?? true; // optimistic when no fs
+    const tryFileBased = fs ? await fs.exists(folder) : true;
 
     if (tryFileBased) {
         try {
             const { migrate: drizzleMigrate } = await import('drizzle-orm/bun-sqlite/migrator');
 
-            console.info(`Applying database migrations from ${folder}`);
+            logger.info(`Applying database migrations from ${folder}`);
 
             await drizzleMigrate(adapter.getDrizzleDb(), {
                 migrationsFolder: folder,
                 ...(options?.migrationsTable !== undefined ? { migrationsTable: options.migrationsTable } : {}),
             });
-            console.info('Database migrations complete');
+            logger.info('Database migrations complete');
             return;
         } catch (error) {
-            // If folder doesn't exist, fall through to embedded migrations.
-            // Any other error should be thrown.
+            // A missing/empty migrations folder is expected in compiled binaries —
+            // fall through to embedded. Any other failure is real; rethrow it.
             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}`);
+                logger.info(`File-based migrations unavailable, using embedded: ${message}`);
             } else {
-                console.error(`[MIGRATE] drizzleMigrate failed: ${message}`);
+                logger.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);
+    logger.info('No drizzle/ folder found — applying embedded migrations');
+    await applyEmbeddedMigrations(adapter, table, logger);
 }

package/src/queue-job-dao.ts

@@ -1,60 +1,15 @@
 import { and, eq, inArray, sql } from 'drizzle-orm';
 import type { DbAdapter } from './adapter';
+import type {
+    SelectOrderedLimitDb,
+    SelectProjectionDb,
+    UpdateChangesDb,
+    UpdateReturningDb,
+    UpdateVoidDb,
+} from './drizzle-builders';
 import { EntityDao } from './entity-dao';
 import { queueJobs } from './schema/queue-jobs';
 
-type SelectGroupByQuery = {
-    groupBy: (group: unknown) => Promise<unknown[]>;
-};
-
-type SelectWhereQuery = {
-    where: (where: unknown) => Promise<unknown[]>;
-};
-
-type SelectReadyQuery = {
-    where: (where: unknown) => {
-        orderBy: (order: unknown) => { limit: (limit: number) => Promise<unknown[]> };
-    };
-};
-
-type QueueSelectDb = {
-    select: (projection: unknown) => {
-        from: (table: unknown) => SelectGroupByQuery & SelectWhereQuery;
-    };
-};
-
-type QueueReadyDb = {
-    select: () => {
-        from: (table: unknown) => SelectReadyQuery;
-    };
-};
-
-type QueueUpdateReturningDb = {
-    update: (table: unknown) => {
-        set: (value: unknown) => {
-            where: (where: unknown) => {
-                returning: () => Promise<unknown[]>;
-            };
-        };
-    };
-};
-
-type QueueUpdateVoidDb = {
-    update: (table: unknown) => {
-        set: (value: unknown) => {
-            where: (where: unknown) => Promise<unknown>;
-        };
-    };
-};
-
-type QueueUpdateChangesDb = {
-    update: (table: unknown) => {
-        set: (value: unknown) => {
-            where: (where: unknown) => Promise<{ changes: number }>;
-        };
-    };
-};
-
 /**
  * Aggregate queue statistics by job status.
  */
@@ -153,7 +108,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
      * Get aggregate job counts by status.
      */
     async getStats(): Promise<QueueStats> {
-        const result = await (this.db as QueueSelectDb)
+        const result = await (this.db as SelectProjectionDb)
             .select({
                 status: queueJobs.status,
                 count: sql`count(*)`,
@@ -176,7 +131,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
      * Count jobs by status.
      */
     async countByStatus(status: string): Promise<number> {
-        const result = await (this.db as QueueSelectDb)
+        const result = await (this.db as SelectProjectionDb)
             .select({ value: sql`count(*)` })
             .from(queueJobs)
             .where(sql`${queueJobs.status} = ${status}`);
@@ -190,7 +145,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     async findPending(batchSize: number): Promise<QueueJobRecord[]> {
         const now = this.now();
 
-        const result = await (this.db as QueueReadyDb)
+        const result = await (this.db as SelectOrderedLimitDb)
             .select()
             .from(queueJobs)
             .where(
@@ -214,7 +169,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
 
         const now = this.now();
 
-        const result = await (this.db as QueueUpdateReturningDb)
+        const result = await (this.db as UpdateReturningDb)
             .update(queueJobs)
             .set({ status: 'processing', processingAt: now, updatedAt: now })
             .where(
@@ -241,7 +196,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
 
         const now = this.now();
 
-        await (this.db as QueueUpdateVoidDb)
+        await (this.db as UpdateVoidDb)
             .update(queueJobs)
             .set({ status: 'processing', processingAt: now, updatedAt: now })
             .where(and(inArray(queueJobs.id, ids), eq(queueJobs.status, 'pending')));
@@ -288,7 +243,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     async resetStuckJobs(visibilityTimeout: number): Promise<number> {
         const cutoff = this.now() - visibilityTimeout;
 
-        const result = await (this.db as QueueUpdateChangesDb)
+        const result = await (this.db as UpdateChangesDb)
             .update(queueJobs)
             .set({ status: 'pending', processingAt: null, updatedAt: this.now() })
             .where(
@@ -307,7 +262,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     async failExpiredJobs(): Promise<number> {
         const now = this.now();
 
-        const result = await (this.db as QueueUpdateChangesDb)
+        const result = await (this.db as UpdateChangesDb)
             .update(queueJobs)
             .set({
                 status: 'failed',

package/src/schema/ddl.ts

@@ -1,4 +1,5 @@
 import { getTableConfig, type SQLiteTable } from 'drizzle-orm/sqlite-core';
+import { getDrizzleTableName, sqlExpressionToText } from './drizzle-internals';
 
 /**
  * Quote an identifier for use in SQL (double-quoted for SQLite compatibility).
@@ -7,26 +8,6 @@ function quoteIdent(name: string): string {
     return `"${name.replace(/"/g, '""')}"`;
 }
 
-/**
- * Extract the SQL string from a drizzle-orm SQL expression by walking its
- * internal `queryChunks` — StringChunk values plus Param placeholders.
- */
-function sqlToString(chunks: Array<{ value?: unknown; input?: unknown }>): string {
-    return chunks
-        .map((chunk) => {
-            // StringChunk — the literal SQL fragment
-            if ('value' in chunk && typeof chunk.value === 'string') {
-                return chunk.value;
-            }
-            // Param — use the input value if available
-            if ('input' in chunk && chunk.input !== undefined) {
-                return String(chunk.input);
-            }
-            return String(chunk.value ?? '?');
-        })
-        .join('');
-}
-
 /**
  * Map a column default value to its SQL literal representation.
  *
@@ -48,25 +29,8 @@ function defaultToSql(value: unknown): string | undefined {
     if (typeof value === 'boolean') {
         return value ? '1' : '0';
     }
-    // drizzle-orm SQL expression (has queryChunks)
-    if (typeof value === 'object' && value !== null && 'queryChunks' in value) {
-        const chunks = (value as Record<string, unknown>).queryChunks as
-            | Array<{ value?: unknown; input?: unknown }>
-            | undefined;
-        if (chunks) {
-            return sqlToString(chunks);
-        }
-    }
-    return String(value);
-}
-
-/**
- * Resolve a drizzle table object to its string name.
- */
-function getTableName(table: Record<string, unknown>): string {
-    // Drizzle tables store name at Symbol.for('drizzle:Name')
-    const nameSym = Symbol.for('drizzle:Name');
-    return String((table as unknown as Record<symbol, unknown>)[nameSym]);
+    // drizzle-orm SQL expression (sql`...`) — rendered via the internals quarantine.
+    return sqlExpressionToText(value) ?? String(value);
 }
 
 /**
@@ -157,7 +121,7 @@ export function generateCreateTableSql(table: SQLiteTable): string {
         const ref = fk.reference();
         const localCols = ref.columns.map((c) => quoteIdent(c.name)).join(', ');
         const foreignCols = ref.foreignColumns.map((c) => quoteIdent(c.name)).join(', ');
-        const foreignTableName = getTableName(ref.foreignTable as unknown as Record<string, symbol | unknown>);
+        const foreignTableName = getDrizzleTableName(ref.foreignTable);
 
         let constraint = `FOREIGN KEY (${localCols}) REFERENCES ${quoteIdent(foreignTableName)} (${foreignCols})`;
         if (fk.onDelete) {

package/src/schema/drizzle-internals.ts

@@ -0,0 +1,55 @@
+/**
+ * Quarantine for the *unversioned* drizzle-orm internal shapes ts-db reaches into
+ * for DDL generation.
+ *
+ * Everything else in ts-db consumes drizzle's public API (`getTableConfig`,
+ * column accessors). These two helpers are the only places that touch private
+ * structure — the SQL-expression `queryChunks` array and the
+ * `Symbol.for('drizzle:Name')` table-name slot — neither of which is covered by
+ * drizzle's semver contract. Keeping both here means a drizzle bump that changes
+ * an internal shape breaks in ONE file with ONE focused test, instead of silently
+ * mis-generating DDL across `ddl.ts`. If this module starts failing after an
+ * upgrade, the fix lives here.
+ */
+
+/** A drizzle SQL expression's internal chunk: a literal fragment or a bound param. */
+interface SqlChunk {
+    value?: unknown;
+    input?: unknown;
+}
+
+/**
+ * Render a drizzle `sql\`...\`` expression to its literal SQL text by walking its
+ * internal `queryChunks`. Used to emit SQL-level column defaults
+ * (e.g. `DEFAULT (unixepoch())`) into generated DDL.
+ *
+ * Returns `undefined` when `value` is not a drizzle SQL expression with chunks,
+ * so callers can fall through to their primitive/`String()` handling.
+ */
+export function sqlExpressionToText(value: unknown): string | undefined {
+    if (typeof value !== 'object' || value === null || !('queryChunks' in value)) {
+        return undefined;
+    }
+    const chunks = (value as Record<string, unknown>).queryChunks as SqlChunk[] | undefined;
+    if (!chunks) return undefined;
+
+    return chunks
+        .map((chunk) => {
+            // StringChunk — the literal SQL fragment
+            if ('value' in chunk && typeof chunk.value === 'string') {
+                return chunk.value;
+            }
+            // Param — use the input value if available
+            if ('input' in chunk && chunk.input !== undefined) {
+                return String(chunk.input);
+            }
+            return String(chunk.value ?? '?');
+        })
+        .join('');
+}
+
+/** Resolve a drizzle table object to its declared name (stored at a private symbol). */
+export function getDrizzleTableName(table: object): string {
+    const nameSym = Symbol.for('drizzle:Name');
+    return String((table as Record<symbol, unknown>)[nameSym]);
+}

package/src/schema/inbox-messages.ts

@@ -0,0 +1,22 @@
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Drizzle schema definition for durable inter-agent inbox messages.
+ */
+export const inboxMessages = sqliteTable(
+    'inbox_messages',
+    {
+        id: text('id').primaryKey(),
+        fromId: text('from_id'),
+        toId: text('to_id').notNull(),
+        body: text('body').notNull(),
+        status: text('status').notNull().default('queued'),
+        inReplyTo: text('in_reply_to'),
+        createdAt: integer('created_at').notNull(),
+        updatedAt: integer('updated_at').notNull(),
+        deliveredAt: integer('delivered_at'),
+        injectAttempts: integer('inject_attempts').notNull().default(0),
+        injectError: text('inject_error'),
+    },
+    (table) => [index('idx_inbox_messages_to_status').on(table.toId, table.status)],
+);

package/src/schema/index.ts

@@ -2,4 +2,5 @@ export { index, integer, text } from 'drizzle-orm/sqlite-core';
 export * from './common';
 export { generateCreateTableSql } from './ddl';
 export { type DefinedTable, defineTable } from './define-table';
+export { inboxMessages } from './inbox-messages';
 export { queueJobs } from './queue-jobs';

package/src/schema/runtime.ts

@@ -1 +1,2 @@
+export { inboxMessages } from './inbox-messages';
 export { queueJobs } from './queue-jobs';