@zintrust/core 3.5.1 → 3.6.0

package/src/tools/queue/QueueReliabilityOrchestrator.js

@@ -0,0 +1,82 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ShutdownTrace } from '../../helper/index.js';
+import { JobReconciliationRunner } from './JobReconciliationRunner.js';
+import { JobRecoveryDaemon } from './JobRecoveryDaemon.js';
+import { StalledJobMonitor } from './StalledJobMonitor.js';
+const isUnrefableTimer = (timer) => {
+    return (typeof timer === 'object' &&
+        timer !== null &&
+        'unref' in timer &&
+        typeof timer.unref === 'function');
+};
+const state = {
+    started: false,
+};
+const clearTimer = (timer) => {
+    if (timer === undefined)
+        return;
+    clearInterval(timer);
+};
+const startInterval = (handler, intervalMs) => {
+    const timer = setInterval(() => {
+        handler().catch((error) => {
+            Logger.warn('Queue reliability interval failed', {
+                error: error instanceof Error ? error : String(error),
+            });
+        });
+    }, intervalMs);
+    if (isUnrefableTimer(timer)) {
+        timer.unref();
+    }
+    return timer;
+};
+export const QueueReliabilityOrchestrator = Object.freeze({
+    isEnabled() {
+        return Env.getBool('JOB_RELIABILITY_ENABLED', true);
+    },
+    start() {
+        if (!this.isEnabled())
+            return;
+        if (state.started)
+            return;
+        const reconciliationMs = Math.max(5000, Env.getInt('JOB_RECONCILIATION_INTERVAL_MS', 60000));
+        const recoveryMs = Math.max(5000, Env.getInt('JOB_RECOVERY_INTERVAL_MS', 30000));
+        const stalledMs = Math.max(5000, Env.getInt('STALLED_JOB_CHECK_INTERVAL_MS', 30000));
+        state.reconciliationTimer = startInterval(async () => {
+            await JobReconciliationRunner.runOnce();
+        }, reconciliationMs);
+        state.recoveryTimer = startInterval(async () => {
+            await JobRecoveryDaemon.runOnce();
+        }, recoveryMs);
+        state.stalledTimer = startInterval(async () => {
+            await StalledJobMonitor.scanOnce();
+        }, stalledMs);
+        state.started = true;
+        Logger.info('Queue reliability orchestrator started', {
+            reconciliationMs,
+            recoveryMs,
+            stalledMs,
+        });
+        ShutdownTrace.logHandles('queue-reliability.start', {
+            reconciliationMs,
+            recoveryMs,
+            stalledMs,
+        });
+    },
+    stop() {
+        ShutdownTrace.log('queue-reliability.stop.start', {
+            started: state.started,
+        });
+        clearTimer(state.reconciliationTimer);
+        clearTimer(state.recoveryTimer);
+        clearTimer(state.stalledTimer);
+        state.reconciliationTimer = undefined;
+        state.recoveryTimer = undefined;
+        state.stalledTimer = undefined;
+        state.started = false;
+        Logger.info('Queue reliability orchestrator stopped');
+        ShutdownTrace.logHandles('queue-reliability.stop.complete');
+    },
+});
+export default QueueReliabilityOrchestrator;

package/src/tools/queue/QueueRuntimeRegistration.d.ts

@@ -0,0 +1,3 @@
+import type { QueueConfig } from '../../config/queue.js';
+export declare function registerQueuesFromRuntimeConfig(config: QueueConfig): Promise<void>;
+//# sourceMappingURL=QueueRuntimeRegistration.d.ts.map

package/src/tools/queue/QueueRuntimeRegistration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueRuntimeRegistration.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueRuntimeRegistration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AA8JjD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDxF"}

package/src/tools/queue/QueueRuntimeRegistration.js

@@ -0,0 +1,163 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { ZintrustLang } from '../../lang/lang.js';
+import { existsSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import { pathToFileURL } from '../../node-singletons/url.js';
+import { detectRuntime } from '../../runtime/detectRuntime.js';
+import { DatabaseQueue } from './drivers/Database.js';
+import { InMemoryQueue } from './drivers/InMemory.js';
+import { autoRegisterJobStateTrackerPersistenceFromEnv } from './JobStateTrackerDbPersistence.js';
+import { Queue } from './Queue.js';
+import { QueueReliabilityOrchestrator } from './QueueReliabilityOrchestrator.js';
+const QUEUE_REDIS_PACKAGE = '@zintrust/queue-redis';
+const ZEDGI_PACKAGE = '@zintrust/zedgi';
+/**
+ * Register queue drivers from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Built-in drivers are registered so `QUEUE_DRIVER=sync|inmemory|redis` works out of the box.
+ * - If the configured default is registered, it is ALSO registered as 'default'.
+ * - Unknown/unregistered driver names still throw when selected.
+ */
+const isDriverRegistered = (name) => {
+    try {
+        Queue.get(name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const getLocalPackageUrl = (pkgFolder) => {
+    try {
+        const cwd = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '';
+        if (cwd.trim() === '')
+            return null;
+        const localEntry = path.join(cwd, 'dist', 'packages', pkgFolder, 'src', 'index.js');
+        if (!existsSync(localEntry))
+            return null;
+        return pathToFileURL(localEntry).href;
+    }
+    catch {
+        return null;
+    }
+};
+const registerRedisDriverIfAvailable = async () => {
+    if (isDriverRegistered('redis')) {
+        return true;
+    }
+    const tryRegister = (mod) => {
+        if (mod.RedisQueue !== undefined) {
+            Queue.register('redis', mod.RedisQueue);
+            return true;
+        }
+        if (mod.BullMQRedisQueue !== undefined) {
+            Queue.register('redis', mod.BullMQRedisQueue);
+            return true;
+        }
+        return false;
+    };
+    // Fall back to dynamic import only if not already registered
+    try {
+        const mod = (await import(/* @vite-ignore */ QUEUE_REDIS_PACKAGE));
+        if (tryRegister(mod)) {
+            return true;
+        }
+    }
+    catch {
+        // Fall back to local dist build output when running inside the core repo Docker image.
+        // In that environment, `@zintrust/queue-redis` is not installed in node_modules,
+        // but the compiled package is available at `dist/packages/queue-redis`.
+        try {
+            const url = getLocalPackageUrl('queue-redis');
+            if (url !== null) {
+                const localMod = (await import(url));
+                if (tryRegister(localMod)) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+    return false;
+};
+const registerZedgiQueueDriverIfAvailable = async (config) => {
+    if (isDriverRegistered('queue-zedgi')) {
+        return true;
+    }
+    const tryRegister = (mod) => {
+        if (mod.ZedgiQueueDriver !== undefined) {
+            Queue.register('queue-zedgi', mod.ZedgiQueueDriver.create(config.drivers['queue-zedgi']));
+            return true;
+        }
+        return false;
+    };
+    // Fall back to dynamic import only if not already registered
+    try {
+        const mod = (await import(/* @vite-ignore */ ZEDGI_PACKAGE));
+        if (tryRegister(mod)) {
+            return true;
+        }
+    }
+    catch {
+        try {
+            const url = getLocalPackageUrl('zedgi');
+            if (url !== null) {
+                const localMod = (await import(url));
+                if (tryRegister(localMod)) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+    return false;
+};
+export async function registerQueuesFromRuntimeConfig(config) {
+    autoRegisterJobStateTrackerPersistenceFromEnv();
+    // Built-in drivers (core)
+    Queue.register('inmemory', InMemoryQueue);
+    Queue.register(ZintrustLang.DATABASE, DatabaseQueue);
+    // Project templates use QUEUE_DRIVER=sync; treat this as an alias of in-memory.
+    Queue.register('sync', InMemoryQueue);
+    const defaultName = (config.default ?? '').toString().trim().toLowerCase();
+    if (defaultName.length === 0) {
+        throw ErrorFactory.createConfigError('Queue default driver is not configured');
+    }
+    if (defaultName === 'redis') {
+        const registered = await registerRedisDriverIfAvailable();
+        if (!registered) {
+            throw ErrorFactory.createConfigError('Redis queue driver is not registered. Install queue:redis via zin plugin install.');
+        }
+    }
+    if (defaultName === 'queue-zedgi') {
+        const registered = await registerZedgiQueueDriverIfAvailable(config);
+        if (!registered) {
+            throw ErrorFactory.createConfigError('Zedgi queue driver is not registered. Install @zintrust/zedgi.');
+        }
+    }
+    try {
+        const drv = Queue.get(defaultName);
+        Queue.register('default', drv);
+        if (Env.getBool('JOB_RELIABILITY_AUTOSTART', false)) {
+            QueueReliabilityOrchestrator.start();
+        }
+    }
+    catch (error) {
+        const { isCloudflare } = detectRuntime();
+        if (isCloudflare) {
+            Logger.warn(`[queue] Default driver '${defaultName}' is unavailable in Cloudflare runtime; falling back to 'sync'.`);
+            Queue.register('default', Queue.get('sync'));
+            return;
+        }
+        throw ErrorFactory.createConfigError('Queue default driver is not available', error);
+    }
+}

package/src/tools/queue/QueueTracing.d.ts

@@ -0,0 +1,32 @@
+export type QueueTraceOperation = 'enqueue' | 'dequeue' | 'ack' | 'length' | 'drain';
+export type QueueTraceStatus = 'ok' | 'error';
+export type QueueTraceEvent = {
+    traceId: string;
+    spanId: string;
+    queueName: string;
+    operation: QueueTraceOperation;
+    status: QueueTraceStatus;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    error?: string;
+    attributes?: Record<string, unknown>;
+};
+export type QueueTraceExporter = (events: ReadonlyArray<QueueTraceEvent>) => void | Promise<void>;
+export declare const QueueTracing: Readonly<{
+    isEnabled: () => boolean;
+    registerExporter(exporter: QueueTraceExporter): void;
+    unregisterExporter(exporter: QueueTraceExporter): void;
+    flush(): Promise<number>;
+    snapshot(limit?: number): QueueTraceEvent[];
+    prune(): void;
+    reset(): void;
+    traceOperation<T>(input: {
+        queueName: string;
+        operation: QueueTraceOperation;
+        attributes?: Record<string, unknown>;
+        execute: () => Promise<T>;
+    }): Promise<T>;
+}>;
+export default QueueTracing;
+//# sourceMappingURL=QueueTracing.d.ts.map

package/src/tools/queue/QueueTracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueTracing.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueTracing.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErF,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAiFlG,eAAO,MAAM,YAAY;qBArEH,OAAO;+BAwEA,kBAAkB,GAAG,IAAI;iCAIvB,kBAAkB,GAAG,IAAI;aAIvC,OAAO,CAAC,MAAM,CAAC;8BAuBP,eAAe,EAAE;aAO/B,IAAI;aAIJ,IAAI;mBAMQ,CAAC,SAAS;QAC7B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,mBAAmB,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;KAC3B,GAAG,OAAO,CAAC,CAAC,CAAC;EAiDd,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/tools/queue/QueueTracing.js

@@ -0,0 +1,151 @@
+import { OpenTelemetry } from '../../observability/OpenTelemetry.js';
+import { generateUuid } from '../../common/utility.js';
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+const storedEvents = [];
+const pendingEvents = [];
+const exporters = new Set();
+const normalizeSampleRate = () => {
+    const value = Env.getFloat('QUEUE_TRACING_SAMPLE_RATE', 1);
+    if (Number.isFinite(value) === false)
+        return 1;
+    return Math.max(0, Math.min(1, value));
+};
+const isEnabled = () => Env.getBool('QUEUE_TRACING_ENABLED', false);
+const shouldSample = () => {
+    const rate = normalizeSampleRate();
+    if (rate >= 1)
+        return true;
+    if (rate <= 0)
+        return false;
+    return Math.random() <= rate; // NOSONAR - Math.random() is sufficient for sampling decisions in this context.
+};
+const maxEvents = () => Math.max(1, Env.getInt('QUEUE_TRACING_MAX_EVENTS', 5000));
+const retentionMs = () => Math.max(1000, Env.getInt('QUEUE_TRACING_RETENTION_MS', 86400000));
+const exportBatchSize = () => Math.max(1, Env.getInt('QUEUE_TRACING_EXPORT_BATCH_SIZE', 20));
+const shouldExportToOtel = () => Env.getBool('QUEUE_TRACING_EXPORT_OTEL', true);
+const pruneStored = () => {
+    const cutoff = Date.now() - retentionMs();
+    const filtered = storedEvents.filter((event) => {
+        const ended = new Date(event.endedAt).getTime();
+        if (Number.isNaN(ended))
+            return false;
+        return ended >= cutoff;
+    });
+    storedEvents.splice(0, storedEvents.length, ...filtered);
+    const keep = maxEvents();
+    if (storedEvents.length > keep) {
+        storedEvents.splice(0, storedEvents.length - keep);
+    }
+};
+const finalize = (event) => {
+    storedEvents.push(event);
+    pendingEvents.push(event);
+    pruneStored();
+};
+const normalizeError = (error) => {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+};
+const tryExportToOpenTelemetry = (batch) => {
+    if (shouldExportToOtel() === false)
+        return;
+    const recordQueueSpan = OpenTelemetry.recordQueueOperationSpan;
+    if (recordQueueSpan === undefined)
+        return;
+    batch.forEach((event) => {
+        recordQueueSpan({
+            queueName: event.queueName,
+            operation: event.operation,
+            durationMs: event.durationMs,
+            status: event.status,
+        });
+    });
+};
+export const QueueTracing = Object.freeze({
+    isEnabled,
+    registerExporter(exporter) {
+        exporters.add(exporter);
+    },
+    unregisterExporter(exporter) {
+        exporters.delete(exporter);
+    },
+    async flush() {
+        if (pendingEvents.length === 0)
+            return 0;
+        const batch = pendingEvents.splice(0, pendingEvents.length);
+        tryExportToOpenTelemetry(batch);
+        if (exporters.size > 0) {
+            const settled = await Promise.allSettled(Array.from(exporters).map(async (exporter) => exporter(batch)));
+            settled.forEach((result) => {
+                if (result.status === 'rejected') {
+                    Logger.warn('Queue trace exporter failed', {
+                        error: String(result.reason),
+                    });
+                }
+            });
+        }
+        return batch.length;
+    },
+    snapshot(limit = 100) {
+        const safeLimit = Math.max(1, Math.floor(limit));
+        pruneStored();
+        if (storedEvents.length <= safeLimit)
+            return [...storedEvents];
+        return storedEvents.slice(storedEvents.length - safeLimit);
+    },
+    prune() {
+        pruneStored();
+    },
+    reset() {
+        storedEvents.splice(0, storedEvents.length);
+        pendingEvents.splice(0, pendingEvents.length);
+        exporters.clear();
+    },
+    async traceOperation(input) {
+        if (isEnabled() === false || shouldSample() === false) {
+            return input.execute();
+        }
+        const startedAtMs = Date.now();
+        const traceId = generateUuid();
+        const spanId = generateUuid();
+        try {
+            const result = await input.execute();
+            finalize({
+                traceId,
+                spanId,
+                queueName: input.queueName,
+                operation: input.operation,
+                status: 'ok',
+                startedAt: new Date(startedAtMs).toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - startedAtMs),
+                attributes: input.attributes,
+            });
+            if (pendingEvents.length >= exportBatchSize()) {
+                void this.flush();
+            }
+            return result;
+        }
+        catch (error) {
+            finalize({
+                traceId,
+                spanId,
+                queueName: input.queueName,
+                operation: input.operation,
+                status: 'error',
+                startedAt: new Date(startedAtMs).toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - startedAtMs),
+                error: normalizeError(error),
+                attributes: input.attributes,
+            });
+            if (pendingEvents.length >= exportBatchSize()) {
+                void this.flush();
+            }
+            throw error;
+        }
+    },
+});
+export default QueueTracing;

package/src/tools/queue/StalledJobMonitor.d.ts

@@ -0,0 +1,5 @@
+export declare const StalledJobMonitor: Readonly<{
+    scanOnce(): Promise<number>;
+}>;
+export default StalledJobMonitor;
+//# sourceMappingURL=StalledJobMonitor.d.ts.map

package/src/tools/queue/StalledJobMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StalledJobMonitor.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/StalledJobMonitor.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,iBAAiB;gBACV,OAAO,CAAC,MAAM,CAAC;EAoBjC,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/tools/queue/StalledJobMonitor.js

@@ -0,0 +1,21 @@
+import { Logger } from '../../config/logger.js';
+import { JobHeartbeatStore } from './JobHeartbeatStore.js';
+import { JobStateTracker } from './JobStateTracker.js';
+export const StalledJobMonitor = Object.freeze({
+    async scanOnce() {
+        const expired = await JobHeartbeatStore.listExpired();
+        await Promise.all(expired.map(async (row) => {
+            await JobStateTracker.stalled({
+                queueName: row.queueName,
+                jobId: row.jobId,
+                reason: 'Heartbeat expired',
+            });
+            await JobHeartbeatStore.remove(row.queueName, row.jobId);
+        }));
+        if (expired.length > 0) {
+            Logger.warn('Stalled jobs detected from heartbeat store', { count: expired.length });
+        }
+        return expired.length;
+    },
+});
+export default StalledJobMonitor;

package/src/tools/queue/TimeoutManager.d.ts

@@ -0,0 +1,14 @@
+export type TimeoutRetryConfig = {
+    timeoutMs: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    operationName?: string;
+};
+export declare const TimeoutManager: Readonly<{
+    getQueueJobTimeoutMs(): number;
+    withTimeout<T>(operation: () => Promise<T>, timeoutMs: number, operationName: string, timeoutHandler?: () => Promise<T>): Promise<T>;
+    withTimeoutRetry<T>(operation: () => Promise<T>, config: TimeoutRetryConfig): Promise<T>;
+    isTimeoutError: (error: unknown) => boolean;
+}>;
+export default TimeoutManager;
+//# sourceMappingURL=TimeoutManager.d.ts.map

package/src/tools/queue/TimeoutManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeoutManager.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/TimeoutManager.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA8BF,eAAO,MAAM,cAAc;4BACD,MAAM;gBAKZ,CAAC,aACN,MAAM,OAAO,CAAC,CAAC,CAAC,aAChB,MAAM,iBACF,MAAM,mBACJ,MAAM,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC;qBAuBU,CAAC,aAAa,MAAM,OAAO,CAAC,CAAC,CAAC,UAAU,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;4BA7CjE,OAAO,KAAG,OAAO;EAqE9C,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/tools/queue/TimeoutManager.js

@@ -0,0 +1,77 @@
+import { Env } from '../../config/env.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+const sleep = async (ms) => {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => {
+        const timeoutRef = globalThis.setTimeout(() => {
+            clearTimeout(timeoutRef);
+            resolve();
+        }, ms);
+    });
+};
+const createTimeoutError = (operationName, timeoutMs) => ErrorFactory.createTryCatchError(`Operation timed out: ${operationName}`, {
+    code: 'QUEUE_TIMEOUT',
+    operationName,
+    timeoutMs,
+});
+const isTimeoutError = (error) => {
+    if (error === null || error === undefined || typeof error !== 'object')
+        return false;
+    const code = error.code;
+    if (code === 'QUEUE_TIMEOUT')
+        return true;
+    const details = error.details;
+    if (details !== null && details !== undefined && typeof details === 'object') {
+        return details.code === 'QUEUE_TIMEOUT';
+    }
+    return false;
+};
+export const TimeoutManager = Object.freeze({
+    getQueueJobTimeoutMs() {
+        const timeoutSeconds = Env.getInt('QUEUE_JOB_TIMEOUT', 60);
+        return Math.max(1000, timeoutSeconds * 1000);
+    },
+    async withTimeout(operation, timeoutMs, operationName, timeoutHandler) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = globalThis.setTimeout(() => {
+                reject(createTimeoutError(operationName, timeoutMs));
+            }, Math.max(1, timeoutMs));
+        });
+        try {
+            return await Promise.race([operation(), timeoutPromise]);
+        }
+        catch (error) {
+            if (timeoutHandler !== undefined && isTimeoutError(error)) {
+                return await timeoutHandler();
+            }
+            throw error;
+        }
+        finally {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        }
+    },
+    async withTimeoutRetry(operation, config) {
+        const retries = Math.max(0, Math.floor(config.maxRetries));
+        const attemptRun = async (attempt) => {
+            try {
+                return await this.withTimeout(operation, config.timeoutMs, config.operationName ?? 'queue-operation');
+            }
+            catch (error) {
+                const shouldRetry = isTimeoutError(error) && attempt < retries;
+                if (!shouldRetry) {
+                    throw error;
+                }
+                const delay = Math.max(0, Math.floor(config.retryDelayMs * 2 ** attempt));
+                await sleep(delay);
+                return attemptRun(attempt + 1);
+            }
+        };
+        return attemptRun(0);
+    },
+    isTimeoutError,
+});
+export default TimeoutManager;

package/src/tools/queue/drivers/Database.d.ts

@@ -0,0 +1,23 @@
+import type { QueueMessage } from '../Queue.js';
+export interface DatabaseQueueConfig {
+    connection?: string;
+    table?: string;
+    retryAttempts?: number;
+    visibilityTimeout?: number;
+}
+export interface IDatabaseQueueDriver {
+    enqueue<T = unknown>(queue: string, payload: T, connectionName?: string): Promise<string>;
+    dequeue<T = unknown>(queue: string, connectionName?: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string, connectionName?: string): Promise<void>;
+    length(queue: string, connectionName?: string): Promise<number>;
+    drain(queue: string, connectionName?: string): Promise<void>;
+}
+export declare const DatabaseQueue: {
+    readonly enqueue: <T = unknown>(queue: string, payload: T, connectionName?: string) => Promise<string>;
+    readonly dequeue: <T = unknown>(queue: string, connectionName?: string) => Promise<QueueMessage<T> | undefined>;
+    readonly ack: (queue: string, id: string, connectionName?: string) => Promise<void>;
+    readonly length: (queue: string, connectionName?: string) => Promise<number>;
+    readonly drain: (queue: string, connectionName?: string) => Promise<void>;
+};
+export default DatabaseQueue;
+//# sourceMappingURL=Database.d.ts.map

package/src/tools/queue/drivers/Database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../../../../src/tools/queue/drivers/Database.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1F,OAAO,CAAC,CAAC,GAAG,OAAO,EACjB,KAAK,EAAE,MAAM,EACb,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACxC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,aAAa;uBAkBR,CAAC,mBACN,MAAM,WACJ,CAAC,mBACO,MAAM,KACtB,OAAO,CAAC,MAAM,CAAC;uBAkBJ,CAAC,mBACN,MAAM,mBACI,MAAM,KACtB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;0BAwEtB,MAAM,MAAM,MAAM,mBAAmB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAYxD,MAAM,mBAAmB,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;4BAoBlD,MAAM,mBAAmB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;CASlE,CAAC;AAEL,eAAe,aAAa,CAAC"}