@gobing-ai/ts-db 0.1.0

package/src/queue-job-dao.ts

@@ -0,0 +1,317 @@
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import type { DbClient } from './adapter';
+import { EntityDao } from './entity-dao';
+import { queueJobs } from './schema/queue-jobs';
+
+/**
+ * Aggregate queue statistics by job status.
+ */
+export interface QueueStats {
+    pending: number;
+    processing: number;
+    completed: number;
+    failed: number;
+}
+
+/**
+ * Row type inferred from the queue_jobs Drizzle schema.
+ */
+export type QueueJobRecord = typeof queueJobs.$inferSelect;
+
+/**
+ * DAO for the queue_jobs table.
+ *
+ * Extends EntityDao for generic CRUD operations. Adds queue-specific
+ * methods for job lifecycle management (enqueue, process, retry, fail).
+ */
+export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id> {
+    constructor(db: DbClient) {
+        super(db, queueJobs, queueJobs.id, 'queue_jobs');
+    }
+
+    /**
+     * Enqueue a new job.
+     */
+    async enqueue(
+        type: string,
+        payload: unknown,
+        options?: { maxRetries?: number; delay?: number; ttlMs?: number },
+    ): Promise<string> {
+        const now = this.now();
+        const id = crypto.randomUUID();
+
+        await this.create({
+            id,
+            type,
+            payload: JSON.stringify(payload),
+            status: 'pending',
+            attempts: 0,
+            maxRetries: options?.maxRetries ?? 3,
+            nextRetryAt: options?.delay !== undefined ? now + options.delay : now,
+            ...(options?.ttlMs !== undefined ? { expiresAt: now + options.ttlMs } : {}),
+        });
+
+        return id;
+    }
+
+    /**
+     * Enqueue multiple jobs in a single batch.
+     */
+    async enqueueBatch(
+        jobs: Array<{ type: string; payload: unknown } & { maxRetries?: number; delay?: number; ttlMs?: number }>,
+    ): Promise<string[]> {
+        const now = this.now();
+        const ids: string[] = [];
+
+        const rows = jobs.map((job) => {
+            const id = crypto.randomUUID();
+            ids.push(id);
+
+            return {
+                id,
+                type: job.type,
+                payload: JSON.stringify(job.payload),
+                status: 'pending' as const,
+                attempts: 0,
+                maxRetries: job.maxRetries ?? 3,
+                nextRetryAt: job.delay !== undefined ? now + job.delay : now,
+                ...(job.ttlMs !== undefined ? { expiresAt: now + job.ttlMs } : {}),
+            };
+        });
+
+        if (rows.length > 0) {
+            await this.withTransaction(async (tx) => {
+                for (const row of rows) {
+                    await tx.insert(queueJobs).values(row);
+                }
+            });
+        }
+
+        return ids;
+    }
+
+    /**
+     * Get a job by ID.
+     */
+    async getById(id: string): Promise<QueueJobRecord | undefined> {
+        return this.findBy(queueJobs.id, id);
+    }
+
+    /**
+     * Get aggregate job counts by status.
+     */
+    async getStats(): Promise<QueueStats> {
+        const result = await (
+            this.db as unknown as {
+                select: (fn: unknown) => { from: (t: unknown) => { groupBy: (g: unknown) => Promise<unknown[]> } };
+            }
+        )
+            .select({
+                status: queueJobs.status,
+                count: sql`count(*)`,
+            })
+            .from(queueJobs)
+            .groupBy(queueJobs.status);
+
+        const rows = result as { status: string; count: unknown }[];
+        const map = Object.fromEntries(rows.map((r) => [r.status, Number(r.count ?? 0)]));
+
+        return {
+            pending: map.pending ?? 0,
+            processing: map.processing ?? 0,
+            completed: map.completed ?? 0,
+            failed: map.failed ?? 0,
+        };
+    }
+
+    /**
+     * Count jobs by status.
+     */
+    async countByStatus(status: string): Promise<number> {
+        const result = await (
+            this.db as unknown as {
+                select: (fn: unknown) => { from: (t: unknown) => { where: (w: unknown) => Promise<unknown[]> } };
+            }
+        )
+            .select({ value: sql`count(*)` })
+            .from(queueJobs)
+            .where(sql`${queueJobs.status} = ${status}`);
+
+        return (result as { value: number }[])[0]?.value ?? 0;
+    }
+
+    /**
+     * Find pending jobs that are ready for processing (nextRetryAt <= now).
+     */
+    async findPending(batchSize: number): Promise<QueueJobRecord[]> {
+        const now = this.now();
+
+        const result = await (
+            this.db as unknown as {
+                select: () => {
+                    from: (t: unknown) => {
+                        where: (w: unknown) => {
+                            orderBy: (o: unknown) => { limit: (l: number) => Promise<unknown[]> };
+                        };
+                    };
+                };
+            }
+        )
+            .select()
+            .from(queueJobs)
+            .where(
+                sql`${queueJobs.status} = 'pending' AND (${queueJobs.nextRetryAt} IS NULL OR ${queueJobs.nextRetryAt} <= ${now})`,
+            )
+            .orderBy(queueJobs.createdAt)
+            .limit(batchSize);
+
+        return result as QueueJobRecord[];
+    }
+
+    /**
+     * Atomically claim ready pending jobs for processing.
+     *
+     * The update and selection happen in one SQLite statement so competing
+     * consumers only receive rows they actually transitioned to processing.
+     */
+    async claimReady(batchSize: number): Promise<QueueJobRecord[]> {
+        const limit = Math.floor(batchSize);
+        if (limit <= 0) return [];
+
+        const now = this.now();
+
+        const result = await (
+            this.db as unknown as {
+                update: (t: unknown) => {
+                    set: (v: unknown) => {
+                        where: (w: unknown) => {
+                            returning: () => Promise<unknown[]>;
+                        };
+                    };
+                };
+            }
+        )
+            .update(queueJobs)
+            .set({ status: 'processing', processingAt: now, updatedAt: now })
+            .where(
+                sql`${queueJobs.id} IN (
+                    SELECT id
+                    FROM ${queueJobs}
+                    WHERE status = 'pending'
+                      AND (next_retry_at IS NULL OR next_retry_at <= ${now})
+                    ORDER BY created_at
+                    LIMIT ${limit}
+                )
+                AND ${queueJobs.status} = 'pending'`,
+            )
+            .returning();
+
+        return result as QueueJobRecord[];
+    }
+
+    /**
+     * Mark jobs as processing.
+     */
+    async markProcessing(ids: string[]): Promise<void> {
+        if (ids.length === 0) return;
+
+        const now = this.now();
+
+        await (
+            this.db as unknown as {
+                update: (t: unknown) => { set: (v: unknown) => { where: (w: unknown) => Promise<unknown> } };
+            }
+        )
+            .update(queueJobs)
+            .set({ status: 'processing', processingAt: now, updatedAt: now })
+            .where(and(inArray(queueJobs.id, ids), eq(queueJobs.status, 'pending')));
+    }
+
+    /**
+     * Mark a job as completed.
+     */
+    async markCompleted(id: string): Promise<void> {
+        await this.update(id, {
+            status: 'completed',
+            processingAt: null,
+        });
+    }
+
+    /**
+     * Mark a job as failed.
+     */
+    async markFailed(id: string, attempts: number, error: string): Promise<void> {
+        await this.update(id, {
+            status: 'failed',
+            attempts,
+            lastError: error,
+            processingAt: null,
+        });
+    }
+
+    /**
+     * Reset a job to pending for retry with backoff.
+     */
+    async markForRetry(id: string, attempts: number, errorMessage: string, nextRetryAt: number): Promise<void> {
+        await this.update(id, {
+            status: 'pending',
+            attempts,
+            lastError: errorMessage,
+            nextRetryAt,
+            processingAt: null,
+        });
+    }
+
+    /**
+     * Reset stuck processing jobs (processing beyond visibility timeout).
+     */
+    async resetStuckJobs(visibilityTimeout: number): Promise<number> {
+        const cutoff = this.now() - visibilityTimeout;
+
+        const result = await (
+            this.db as unknown as {
+                update: (t: unknown) => {
+                    set: (v: unknown) => { where: (w: unknown) => Promise<{ changes: number }> };
+                };
+            }
+        )
+            .update(queueJobs)
+            .set({ status: 'pending', processingAt: null, updatedAt: this.now() })
+            .where(
+                sql`${queueJobs.status} = 'processing' AND ${queueJobs.processingAt} IS NOT NULL AND ${queueJobs.processingAt} <= ${cutoff}`,
+            );
+
+        return (result as { changes: number }).changes;
+    }
+
+    /**
+     * Mark expired pending jobs as failed.
+     *
+     * Jobs where `expires_at IS NOT NULL AND expires_at <= now` are
+     * transitioned to `failed` with an expiry error message.
+     */
+    async failExpiredJobs(): Promise<number> {
+        const now = this.now();
+
+        const result = await (
+            this.db as unknown as {
+                update: (t: unknown) => {
+                    set: (v: unknown) => { where: (w: unknown) => Promise<{ changes: number }> };
+                };
+            }
+        )
+            .update(queueJobs)
+            .set({
+                status: 'failed',
+                lastError: 'Job expired — not processed before TTL deadline',
+                updatedAt: now,
+                attempts: sql`${queueJobs.attempts} + 1`,
+                processingAt: null,
+            })
+            .where(
+                sql`${queueJobs.status} = 'pending' AND ${queueJobs.expiresAt} IS NOT NULL AND ${queueJobs.expiresAt} <= ${now}`,
+            );
+
+        return (result as { changes: number }).changes;
+    }
+}

package/src/schema/common.ts

@@ -0,0 +1,94 @@
+import { integer } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Returns the current timestamp in milliseconds.
+ * Extracted for testability and V8 coverage tracking.
+ */
+export function nowTimestamp(): number {
+    return Date.now();
+}
+
+/**
+ * Standard columns shared across all entity tables.
+ *
+ * Uses plain `integer` (returns `number`) to match the existing codebase
+ * convention where `nowMs()` returns `number` and all timestamp comparisons
+ * use numeric operators.
+ *
+ * Usage in schema definitions:
+ * ```ts
+ * import { standardColumns } from './common';
+ *
+ * export const myTable = sqliteTable('my_table', {
+ *     id: text('id').primaryKey(),
+ *     name: text('name').notNull(),
+ *     ...standardColumns,
+ * });
+ * ```
+ */
+export function buildStandardColumns() {
+    return {
+        createdAt: integer('created_at').notNull().$defaultFn(nowTimestamp).default(0),
+        updatedAt: integer('updated_at').notNull().$defaultFn(nowTimestamp).default(0),
+    };
+}
+
+/**
+ * Standard columns (createdAt, updatedAt) for use in Drizzle table definitions via spread.
+ */
+export const standardColumns = buildStandardColumns();
+
+/**
+ * Standard columns with soft-delete support.
+ *
+ * Adds an `inUsed` column (1 = active, 0 = soft-deleted).
+ * EntityDao automatically filters by `inUsed = 1` when the table has this column.
+ */
+export function buildStandardColumnsWithSoftDelete() {
+    return {
+        ...buildStandardColumns(),
+        inUsed: integer('in_used').notNull().default(1),
+    };
+}
+
+/**
+ * Standard columns with soft-delete `inUsed` flag for use in Drizzle table definitions via spread.
+ */
+export const standardColumnsWithSoftDelete = buildStandardColumnsWithSoftDelete();
+
+/**
+ * Type helper for tables that use standard columns.
+ * Provides the `inUsed`, `updatedAt`, `createdAt` column types.
+ */
+export type StandardColumns = typeof standardColumns;
+
+/**
+ * Type helper for tables that use standard columns with soft delete.
+ */
+export type StandardColumnsWithSoftDelete = typeof standardColumnsWithSoftDelete;
+
+/**
+ * Build append-only columns (createdAt only, no updatedAt).
+ *
+ * Enforces D-013 at the schema level: tables using this helper
+ * cannot support update operations because there is no `updatedAt`
+ * column to track mutations.
+ */
+export function buildAppendOnlyColumns() {
+    return {
+        createdAt: integer('created_at').notNull().$defaultFn(nowTimestamp).default(0),
+    };
+}
+
+/**
+ * Append-only columns for Drizzle table definitions via spread.
+ *
+ * Usage:
+ * ```ts
+ * export const runEvents = sqliteTable('run_event', {
+ *     id: text('id').primaryKey(),
+ *     ...appendOnlyColumns,
+ * });
+ * ```
+ */
+export const appendOnlyColumns = buildAppendOnlyColumns();

package/src/schema/index.ts

@@ -0,0 +1,2 @@
+export * from './common';
+export { queueJobs } from './queue-jobs';

package/src/schema/queue-jobs.ts

@@ -0,0 +1,23 @@
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { standardColumns } from './common';
+
+/**
+ * Drizzle schema definition for the queue_jobs table.
+ */
+export const queueJobs = sqliteTable(
+    'queue_jobs',
+    {
+        id: text('id').primaryKey(),
+        type: text('type').notNull(),
+        payload: text('payload').notNull(),
+        status: text('status').notNull().default('pending'),
+        attempts: integer('attempts').notNull().default(0),
+        maxRetries: integer('max_retries').notNull().default(3),
+        ...standardColumns,
+        nextRetryAt: integer('next_retry_at'),
+        lastError: text('last_error'),
+        processingAt: integer('processing_at'),
+        expiresAt: integer('expires_at'),
+    },
+    (table) => [index('queue_jobs_ready_idx').on(table.status, table.nextRetryAt, table.createdAt)],
+);

package/src/span-context.ts

@@ -0,0 +1 @@
+export type { SpanContext } from '@gobing-ai/ts-runtime';