@gobing-ai/ts-infra 0.2.7 → 0.2.8

package/README.md

@@ -1,6 +1,6 @@
 # @gobing-ai/ts-infra
 
-Infrastructure backbone — typed event bus, job queue (types), cron scheduler, OpenTelemetry telemetry, HTTP API client, and structured logging. Designed to be wired together at bootstrap via `RuntimeContext`.
+Infrastructure backbone — typed event bus, DB-backed job queue, cron scheduler, OpenTelemetry telemetry, HTTP API client, and structured logging.
 
 ## Overview
 
@@ -10,10 +10,10 @@ Infrastructure backbone — typed event bus, job queue (types), cron scheduler,
 |-----------|--------|---------|
 | **Event Bus** | `event-bus/` | Typed pub/sub with sync + async dispatch, lifecycle self-observability |
 | **Events** | `events/` | Typed event map pattern + system bus factory |
-| **Job Queue** | `job-queue/` | Types for DB-backed job processing (`JobQueue`, `QueueConsumer`, `Job`) |
+| **Job Queue** | `job-queue/` | DB-backed enqueue and consume flow (`DBJobQueue`, `DBQueueConsumer`) plus queue interfaces |
 | **Scheduler** | `scheduler/` | Cron-like scheduled actions — Node (interval), Cloudflare (Cron Triggers), Noop (test) |
 | **Telemetry** | `telemetry/` | OpenTelemetry SDK wrapper — tracing (`traceAsync`), metrics (17 instruments), SQL sanitizer |
-| **API Client** | `api-client.ts` | Typed HTTP client with OTel tracing, retry, timeout, error handling |
+| **API Client** | `api-client.ts` | Typed HTTP client with OTel tracing, timeout, and error handling |
 | **Logger** | `logger.ts` | Structured JSON logger with levels, child loggers, and mute toggle |
 
 ## Architecture
@@ -51,6 +51,18 @@ classDiagram
             +stop() Promise~void~
             +stats() Promise~QueueStats~
         }
+        class DBJobQueue~T~ {
+            +enqueue(type, payload, opts?) Promise~string~
+            +enqueueBatch(jobs) Promise~string[]~
+            +stats() Promise~QueueStats~
+        }
+        class DBQueueConsumer~T~ {
+            +register(type, handler) void
+            +start() Promise~void~
+            +stop() Promise~void~
+            +processOnce() Promise~number~
+            +stats() Promise~QueueStats~
+        }
         class Job~T~ {
             <<interface>>
         }
@@ -141,6 +153,8 @@ classDiagram
     SchedulerFactory --> CloudflareSchedulerAdapter
     SchedulerFactory --> NoopSchedulerAdapter
     EventBus --> JobQueue : "async dispatch"
+    DBJobQueue --> JobQueue : "implements"
+    DBQueueConsumer --> QueueConsumer : "implements"
     EventBus --> Logger : "self-observability"
     APIClient --> Tracing : "traceAsync"
     APIClient --> Metrics : "counters + histograms"
@@ -182,7 +196,11 @@ bus.once('user.signed_up', () => console.log('one-time'));
 **Lifecycle events** — inject a second `EventBus` to observe bus internals:
 
 ```ts
-const lifecycleBus = new EventBus<BusLifecycleEvents>();
+type LifecycleEvents = {
+    'bus.emit.done': (detail: { event: string; syncCount: number; asyncCount: number; emitDurationMs: number }) => void;
+};
+
+const lifecycleBus = new EventBus<LifecycleEvents>();
 lifecycleBus.on('bus.emit.done', (detail) => {
     // { event, syncCount, asyncCount, emitDurationMs, errors }
     metrics.recordEmit(detail);
@@ -191,6 +209,45 @@ lifecycleBus.on('bus.emit.done', (detail) => {
 const bus = new EventBus<AppEvents>({ lifecycleBus });
 ```
 
+### Job Queue — DB-backed async work
+
+`DBJobQueue` and `DBQueueConsumer` run over `@gobing-ai/ts-db`'s `QueueJobDao`. Use this when event handlers, schedulers, or API handlers need durable background work with retries.
+
+```ts
+import { createDbAdapter, QueueJobDao } from '@gobing-ai/ts-db';
+import { DBJobQueue, DBQueueConsumer } from '@gobing-ai/ts-infra';
+
+const db = await createDbAdapter({ driver: 'bun-sqlite', url: './jobs.db' });
+const dao = new QueueJobDao(db);
+
+const queue = new DBJobQueue<{ to: string; subject: string }>(dao);
+await queue.enqueue(
+    'send-email',
+    { to: 'alice@example.com', subject: 'Welcome' },
+    { maxRetries: 5, delay: 1_000, ttlMs: 86_400_000 },
+);
+
+const consumer = new DBQueueConsumer<{ to: string; subject: string }>(dao, {
+    batchSize: 10,
+    maxConcurrency: 4,
+    visibilityTimeout: 30_000,
+});
+
+consumer.register('send-email', async (job) => {
+    await sendEmail(job.payload.to, job.payload.subject);
+});
+
+await consumer.start();
+```
+
+For scheduled drains and tests, call `processOnce()` instead of starting the polling loop:
+
+```ts
+const processed = await consumer.processOnce();
+```
+
+The consumer claims ready jobs, resets stuck processing jobs after the visibility timeout, retries failed jobs with exponential backoff, and marks expired jobs failed through `QueueJobDao`.
+
 ### Scheduler — cron-like actions
 
 ```ts
@@ -269,9 +326,7 @@ const reqLog = log.child({ requestId: 'req-123' });
 reqLog.error('Validation failed', { field: 'email' });
 // → {...,"category":"auth","requestId":"req-123","field":"email"}
 
-// Mute during tests
-import { setLoggerMuted } from './logger.js'; // internal import
-setLoggerMuted(true);
+// In tests, prefer injecting a logger boundary or initializing at a quiet level.
 ```
 
 ### Telemetry — OpenTelemetry

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { EventBus, type EventMap, type SubscribeOptions } from './event-bus/inde
 export type { AppEvents, AppInternalEvents } from './events/index';
 export { createSystemBus } from './events/index';
 export type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig, QueueStats, } from './job-queue/index';
+export { DBJobQueue, DBQueueConsumer } from './job-queue/index';
 export { getLogger, initializeLogger, type Logger, type LogLevel } from './logger';
 export { CloudflareSchedulerAdapter, getSchedulerAdapter, initScheduler, NodeSchedulerAdapter, NoopSchedulerAdapter, type ScheduledAction, type SchedulerAdapter, setSchedulerAdapter, } from './scheduler/index';
 export { addSpanAttributes, addSpanEvent, extractSqlOperation, getActiveSpan, getDbOperationDuration, getDbOperationErrors, getDbOperationTotal, getEventbusEmitsTotal, getEventbusErrorsTotal, getHttpClientRequestDuration, getHttpClientRequestErrors, getHttpClientRequestTotal, getHttpServerRequestDuration, getHttpServerRequestErrors, getHttpServerRequestTotal, getQueueJobCompletedTotal, getQueueJobEnqueuedTotal, getQueueJobFailedTotal, getQueueJobProcessingDuration, getSchedulerJobDuration, getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal, getTelemetryConfig, getTracer, initMetrics, initTelemetry, isTelemetryEnabled, sanitizeSql, shutdownMetrics, shutdownTelemetry, type TelemetryConfig, type TelemetryConfigPartial, traceAsync, traceSync, withSpan, } from './telemetry/index';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9F,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGnF,OAAO,EACH,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,mBAAmB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9F,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGhE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGnF,OAAO,EACH,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,mBAAmB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -3,6 +3,8 @@ export { APIClient, APIError } from './api-client.js';
 // Event Bus
 export { EventBus } from './event-bus/index.js';
 export { createSystemBus } from './events/index.js';
+// Job Queue
+export { DBJobQueue, DBQueueConsumer } from './job-queue/index.js';
 // Logger
 export { getLogger, initializeLogger } from './logger.js';
 // Scheduler

package/dist/job-queue/db-job-queue.d.ts

@@ -0,0 +1,40 @@
+import type { QueueJobDao, QueueStats } from '@gobing-ai/ts-db';
+import type { EnqueueOptions, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig } from './types';
+/** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
+export declare class DBJobQueue<T = unknown> implements JobQueue<T> {
+    readonly dao: QueueJobDao;
+    constructor(dao: QueueJobDao);
+    enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string>;
+    enqueueBatch(jobs: Array<{
+        type: string;
+        payload: T;
+    } & EnqueueOptions>): Promise<string[]>;
+    stats(): Promise<QueueStats>;
+}
+/** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
+export declare class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
+    private readonly dao;
+    private readonly handlers;
+    private readonly pollInterval;
+    private readonly batchSize;
+    private readonly maxConcurrency;
+    private readonly visibilityTimeout;
+    private readonly baseDelay;
+    private readonly maxDelay;
+    private readonly drainTimeoutMs;
+    private timer;
+    private running;
+    private inFlight;
+    constructor(dao: QueueJobDao, config?: QueueConsumerConfig);
+    register(type: string, handler: JobHandler<T>): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    stats(): Promise<QueueStats>;
+    /** Process one batch immediately. Useful for tests, schedulers, and manual drains. */
+    processOnce(): Promise<number>;
+    private schedule;
+    private poll;
+    private processJob;
+    private failOrRetry;
+}
+//# sourceMappingURL=db-job-queue.d.ts.map

package/dist/job-queue/db-job-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-job-queue.d.ts","sourceRoot":"","sources":["../../src/job-queue/db-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAO,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE7G,kFAAkF;AAClF,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,WAAW;gBAAhB,GAAG,EAAE,WAAW;IAE/B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI3F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAGrC;AAED,qFAAqF;AACrF,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAc7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAbxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;gBAGA,GAAG,EAAE,WAAW,EACjC,MAAM,GAAE,mBAAwB;IAWpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAarB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIlC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAyBpC,OAAO,CAAC,QAAQ;YAMF,IAAI;YASJ,UAAU;YAgBV,WAAW;CAW5B"}

package/dist/job-queue/db-job-queue.js

@@ -0,0 +1,144 @@
+/** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
+export class DBJobQueue {
+    dao;
+    constructor(dao) {
+        this.dao = dao;
+    }
+    async enqueue(type, payload, options) {
+        return this.dao.enqueue(type, payload, options);
+    }
+    async enqueueBatch(jobs) {
+        return this.dao.enqueueBatch(jobs);
+    }
+    async stats() {
+        return this.dao.getStats();
+    }
+}
+/** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
+export class DBQueueConsumer {
+    dao;
+    handlers = new Map();
+    pollInterval;
+    batchSize;
+    maxConcurrency;
+    visibilityTimeout;
+    baseDelay;
+    maxDelay;
+    drainTimeoutMs;
+    timer = null;
+    running = false;
+    inFlight = 0;
+    constructor(dao, config = {}) {
+        this.dao = dao;
+        this.pollInterval = config.pollInterval ?? 1_000;
+        this.batchSize = config.batchSize ?? 10;
+        this.maxConcurrency = config.maxConcurrency ?? this.batchSize;
+        this.visibilityTimeout = config.visibilityTimeout ?? 30_000;
+        this.baseDelay = config.baseDelay ?? 1_000;
+        this.maxDelay = config.maxDelay ?? 60_000;
+        this.drainTimeoutMs = config.drainTimeoutMs ?? 30_000;
+    }
+    register(type, handler) {
+        this.handlers.set(type, handler);
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule(0);
+    }
+    async stop() {
+        this.running = false;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const deadline = Date.now() + this.drainTimeoutMs;
+        while (this.inFlight > 0 && Date.now() < deadline) {
+            await sleep(10);
+        }
+    }
+    async stats() {
+        return this.dao.getStats();
+    }
+    /** Process one batch immediately. Useful for tests, schedulers, and manual drains. */
+    async processOnce() {
+        await this.dao.resetStuckJobs(this.visibilityTimeout);
+        await this.dao.failExpiredJobs();
+        const jobs = await this.dao.claimReady(this.batchSize);
+        let processed = 0;
+        for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
+            const batch = jobs.slice(index, index + this.maxConcurrency);
+            await Promise.all(batch.map(async (job) => {
+                this.inFlight += 1;
+                try {
+                    await this.processJob(job);
+                    processed += 1;
+                }
+                finally {
+                    this.inFlight -= 1;
+                }
+            }));
+        }
+        return processed;
+    }
+    schedule(delay) {
+        this.timer = setTimeout(() => {
+            void this.poll();
+        }, delay);
+    }
+    async poll() {
+        if (!this.running)
+            return;
+        try {
+            await this.processOnce();
+        }
+        finally {
+            if (this.running)
+                this.schedule(this.pollInterval);
+        }
+    }
+    async processJob(record) {
+        const job = toJob(record);
+        const handler = this.handlers.get(job.type);
+        if (handler === undefined) {
+            await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
+            return;
+        }
+        try {
+            await handler(job);
+            await this.dao.markCompleted(job.id);
+        }
+        catch (error) {
+            await this.failOrRetry(job, error);
+        }
+    }
+    async failOrRetry(job, error) {
+        const attempts = job.attempts + 1;
+        const message = error instanceof Error ? error.message : String(error);
+        if (attempts >= job.maxRetries) {
+            await this.dao.markFailed(job.id, attempts, message);
+            return;
+        }
+        const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
+        await this.dao.markForRetry(job.id, attempts, message, Date.now() + delay);
+    }
+}
+function toJob(record) {
+    return {
+        id: record.id,
+        type: record.type,
+        payload: JSON.parse(record.payload),
+        status: record.status,
+        attempts: record.attempts,
+        maxRetries: record.maxRetries,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        nextRetryAt: record.nextRetryAt,
+        lastError: record.lastError,
+        processingAt: record.processingAt,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/job-queue/index.d.ts

@@ -1,2 +1,3 @@
+export { DBJobQueue, DBQueueConsumer } from './db-job-queue';
 export type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig, QueueStats, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/job-queue/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/job-queue/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/job-queue/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,SAAS,CAAC"}

package/dist/job-queue/index.js

@@ -0,0 +1 @@
+export { DBJobQueue, DBQueueConsumer } from './db-job-queue.js';

package/dist/job-queue/types.d.ts

@@ -1,10 +1,8 @@
 /**
  * Job queue types for async work processing with retry.
  *
- * **Types only** — the DB-backed `DbQueue` and `DbConsumer` implementations
- * that drive the job-queue subsystem live in `@spur/core`. These interfaces
- * are provided here so `EventBus` and other infra components can reference
- * the queue contract without a circular dependency on the DB layer.
+ * The concrete DB-backed implementations live beside these interfaces in
+ * `DBJobQueue` and `DBQueueConsumer`.
  */
 export interface Job<T = unknown> {
     id: string;

package/dist/job-queue/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/F;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/F;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}

package/dist/job-queue/types.js

@@ -1,8 +1,6 @@
 /**
  * Job queue types for async work processing with retry.
  *
- * **Types only** — the DB-backed `DbQueue` and `DbConsumer` implementations
- * that drive the job-queue subsystem live in `@spur/core`. These interfaces
- * are provided here so `EventBus` and other infra components can reference
- * the queue contract without a circular dependency on the DB layer.
+ * The concrete DB-backed implementations live beside these interfaces in
+ * `DBJobQueue` and `DBQueueConsumer`.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.2.7",
+    "version": "0.2.8",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -50,8 +50,8 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.2.7",
-        "@gobing-ai/ts-runtime": "^0.2.7"
+        "@gobing-ai/ts-db": "^0.2.8",
+        "@gobing-ai/ts-runtime": "^0.2.8"
     },
     "peerDependencies": {
         "@opentelemetry/api": "^1.9.0"

package/src/index.ts

@@ -7,8 +7,6 @@ export { EventBus, type EventMap, type SubscribeOptions } from './event-bus/inde
 // Events
 export type { AppEvents, AppInternalEvents } from './events/index';
 export { createSystemBus } from './events/index';
-
-// Job Queue
 export type {
     EnqueueOptions,
     Job,
@@ -18,6 +16,8 @@ export type {
     QueueConsumerConfig,
     QueueStats,
 } from './job-queue/index';
+// Job Queue
+export { DBJobQueue, DBQueueConsumer } from './job-queue/index';
 
 // Logger
 export { getLogger, initializeLogger, type Logger, type LogLevel } from './logger';

package/src/job-queue/db-job-queue.ts

@@ -0,0 +1,163 @@
+import type { QueueJobDao, QueueJobRecord, QueueStats } from '@gobing-ai/ts-db';
+import type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig } from './types';
+
+/** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
+export class DBJobQueue<T = unknown> implements JobQueue<T> {
+    constructor(readonly dao: QueueJobDao) {}
+
+    async enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string> {
+        return this.dao.enqueue(type, payload, options);
+    }
+
+    async enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]> {
+        return this.dao.enqueueBatch(jobs);
+    }
+
+    async stats(): Promise<QueueStats> {
+        return this.dao.getStats();
+    }
+}
+
+/** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
+export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
+    private readonly handlers = new Map<string, JobHandler<T>>();
+    private readonly pollInterval: number;
+    private readonly batchSize: number;
+    private readonly maxConcurrency: number;
+    private readonly visibilityTimeout: number;
+    private readonly baseDelay: number;
+    private readonly maxDelay: number;
+    private readonly drainTimeoutMs: number;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private running = false;
+    private inFlight = 0;
+
+    constructor(
+        private readonly dao: QueueJobDao,
+        config: QueueConsumerConfig = {},
+    ) {
+        this.pollInterval = config.pollInterval ?? 1_000;
+        this.batchSize = config.batchSize ?? 10;
+        this.maxConcurrency = config.maxConcurrency ?? this.batchSize;
+        this.visibilityTimeout = config.visibilityTimeout ?? 30_000;
+        this.baseDelay = config.baseDelay ?? 1_000;
+        this.maxDelay = config.maxDelay ?? 60_000;
+        this.drainTimeoutMs = config.drainTimeoutMs ?? 30_000;
+    }
+
+    register(type: string, handler: JobHandler<T>): void {
+        this.handlers.set(type, handler);
+    }
+
+    async start(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+        this.schedule(0);
+    }
+
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        const deadline = Date.now() + this.drainTimeoutMs;
+        while (this.inFlight > 0 && Date.now() < deadline) {
+            await sleep(10);
+        }
+    }
+
+    async stats(): Promise<QueueStats> {
+        return this.dao.getStats();
+    }
+
+    /** Process one batch immediately. Useful for tests, schedulers, and manual drains. */
+    async processOnce(): Promise<number> {
+        await this.dao.resetStuckJobs(this.visibilityTimeout);
+        await this.dao.failExpiredJobs();
+
+        const jobs = await this.dao.claimReady(this.batchSize);
+        let processed = 0;
+
+        for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
+            const batch = jobs.slice(index, index + this.maxConcurrency);
+            await Promise.all(
+                batch.map(async (job) => {
+                    this.inFlight += 1;
+                    try {
+                        await this.processJob(job);
+                        processed += 1;
+                    } finally {
+                        this.inFlight -= 1;
+                    }
+                }),
+            );
+        }
+
+        return processed;
+    }
+
+    private schedule(delay: number): void {
+        this.timer = setTimeout(() => {
+            void this.poll();
+        }, delay);
+    }
+
+    private async poll(): Promise<void> {
+        if (!this.running) return;
+        try {
+            await this.processOnce();
+        } finally {
+            if (this.running) this.schedule(this.pollInterval);
+        }
+    }
+
+    private async processJob(record: QueueJobRecord): Promise<void> {
+        const job = toJob<T>(record);
+        const handler = this.handlers.get(job.type);
+        if (handler === undefined) {
+            await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
+            return;
+        }
+
+        try {
+            await handler(job);
+            await this.dao.markCompleted(job.id);
+        } catch (error) {
+            await this.failOrRetry(job, error);
+        }
+    }
+
+    private async failOrRetry(job: Job<T>, error: unknown): Promise<void> {
+        const attempts = job.attempts + 1;
+        const message = error instanceof Error ? error.message : String(error);
+        if (attempts >= job.maxRetries) {
+            await this.dao.markFailed(job.id, attempts, message);
+            return;
+        }
+
+        const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
+        await this.dao.markForRetry(job.id, attempts, message, Date.now() + delay);
+    }
+}
+
+function toJob<T>(record: QueueJobRecord): Job<T> {
+    return {
+        id: record.id,
+        type: record.type,
+        payload: JSON.parse(record.payload) as T,
+        status: record.status as Job<T>['status'],
+        attempts: record.attempts,
+        maxRetries: record.maxRetries,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        nextRetryAt: record.nextRetryAt,
+        lastError: record.lastError,
+        processingAt: record.processingAt,
+    };
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/job-queue/index.ts

@@ -1,3 +1,4 @@
+export { DBJobQueue, DBQueueConsumer } from './db-job-queue';
 export type {
     EnqueueOptions,
     Job,

package/src/job-queue/types.ts

@@ -1,10 +1,8 @@
 /**
  * Job queue types for async work processing with retry.
  *
- * **Types only** — the DB-backed `DbQueue` and `DbConsumer` implementations
- * that drive the job-queue subsystem live in `@spur/core`. These interfaces
- * are provided here so `EventBus` and other infra components can reference
- * the queue contract without a circular dependency on the DB layer.
+ * The concrete DB-backed implementations live beside these interfaces in
+ * `DBJobQueue` and `DBQueueConsumer`.
  */
 
 export interface Job<T = unknown> {