@zintrust/core 0.1.28 → 0.1.30

package/src/tools/queue/LockProvider.js

@@ -0,0 +1,282 @@
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * Lock Provider Implementation
+ * Provides distributed lock management for job deduplication
+ */
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { Logger } from '../../config/logger.js';
+import { createBaseDrivers } from '../../config/queue.js';
+import { createRedisConnection } from '../../config/workers.js';
+import { ZintrustLang } from '../../lang/lang.js';
+// Singleton Redis client for locks to avoid connection spam
+let redisClient = null;
+function getRedisClient() {
+    if (!redisClient) {
+        const redisConfig = createBaseDrivers().redis;
+        // Adapt queue config to worker config format if needed
+        redisClient = createRedisConnection({
+            host: redisConfig.host,
+            port: redisConfig.port,
+            password: redisConfig.password,
+            db: redisConfig.database,
+        });
+    }
+    return redisClient;
+}
+const METRICS_SUFFIX = {
+    attempts: 'metrics:attempts',
+    acquired: 'metrics:acquired',
+    collisions: 'metrics:collisions',
+};
+const recordLockAttempt = async (prefix, acquired) => {
+    const client = getRedisClient();
+    try {
+        const attemptsKey = `${prefix}${METRICS_SUFFIX.attempts}`;
+        const acquiredKey = `${prefix}${METRICS_SUFFIX.acquired}`;
+        const collisionsKey = `${prefix}${METRICS_SUFFIX.collisions}`;
+        const operations = [client.incr(attemptsKey)];
+        operations.push(acquired ? client.incr(acquiredKey) : client.incr(collisionsKey));
+        await Promise.allSettled(operations);
+    }
+    catch (error) {
+        Logger.debug('Lock metrics update failed', { error });
+    }
+};
+function createAcquireMethod(prefix, defaultTtl) {
+    return async function acquire(key, options = {}) {
+        const lockKey = `${prefix}${key}`;
+        const ttl = options.ttl ?? defaultTtl;
+        const client = getRedisClient();
+        try {
+            // Use SET NX PX to acquire lock
+            const result = await client.set(lockKey, 'locked', 'PX', ttl, 'NX');
+            const acquired = result === 'OK';
+            const expires = new Date(Date.now() + ttl);
+            Logger.debug(`Lock acquisition attempt`, { key: lockKey, ttl, acquired });
+            void recordLockAttempt(prefix, acquired);
+            return {
+                key: lockKey,
+                ttl,
+                acquired,
+                expires,
+            };
+        }
+        catch (error) {
+            Logger.error(`Failed to acquire lock`, { key: lockKey, error });
+            throw error;
+        }
+    };
+}
+function normalizeLockKey(prefix, key) {
+    return key.startsWith(prefix) ? key : `${prefix}${key}`;
+}
+function createReleaseMethod(prefix) {
+    return async function release(lock) {
+        try {
+            const client = getRedisClient();
+            const lockKey = normalizeLockKey(prefix, lock.key);
+            await client.del(lockKey);
+            Logger.debug(`Lock release`, { key: lockKey });
+        }
+        catch (error) {
+            Logger.error(`Failed to release lock`, { key: lock.key, error });
+            throw error;
+        }
+    };
+}
+function createExtendMethod(prefix) {
+    return async function extend(lock, ttl) {
+        try {
+            const client = getRedisClient();
+            const lockKey = normalizeLockKey(prefix, lock.key);
+            // Use PEXPIRE to extend
+            const result = await client.pexpire(lockKey, ttl);
+            const success = result === 1;
+            if (success) {
+                const newExpires = new Date(Date.now() + ttl);
+                Logger.debug(`Lock extension`, { key: lockKey, ttl, newExpires });
+                lock.ttl = ttl;
+                lock.expires = newExpires;
+            }
+            return success;
+        }
+        catch (error) {
+            Logger.error(`Failed to extend lock`, { key: lock.key, error });
+            return false;
+        }
+    };
+}
+function createStatusMethod(prefix) {
+    return async function status(key) {
+        const lockKey = `${prefix}${key}`;
+        try {
+            const client = getRedisClient();
+            const ttl = await client.pttl(lockKey);
+            const exists = ttl > 0;
+            Logger.debug(`Lock status check`, { key: lockKey, exists, ttl });
+            return {
+                exists,
+                ttl: exists ? ttl : undefined,
+                expires: exists ? new Date(Date.now() + ttl) : undefined,
+            };
+        }
+        catch (error) {
+            Logger.error(`Failed to check lock status`, { key: lockKey, error });
+            return { exists: false };
+        }
+    };
+}
+function createListMethod(prefix) {
+    return async function list(pattern = '*') {
+        try {
+            const client = getRedisClient();
+            const searchPattern = `${prefix}${pattern}`;
+            const keys = [];
+            let cursor = '0';
+            do {
+                // SCAN to avoid blocking Redis in production environments
+                // eslint-disable-next-line no-await-in-loop
+                const [nextCursor, batch] = await client.scan(cursor, 'MATCH', searchPattern, 'COUNT', '200');
+                cursor = nextCursor;
+                keys.push(...batch);
+            } while (cursor !== '0');
+            return keys.map((k) => k.replace(prefix, ''));
+        }
+        catch (error) {
+            Logger.error(`Failed to list locks`, { pattern, error });
+            return [];
+        }
+    };
+}
+/**
+ * Redis-based Lock Provider Implementation
+ */
+export function createRedisLockProvider(config) {
+    const prefix = config.prefix ?? ZintrustLang.ZINTRUST_LOCKS_PREFIX;
+    const defaultTtl = config.defaultTtl ?? ZintrustLang.ZINTRUST_LOCKS_TTL;
+    return {
+        acquire: createAcquireMethod(prefix, defaultTtl),
+        release: createReleaseMethod(prefix),
+        extend: createExtendMethod(prefix),
+        status: createStatusMethod(prefix),
+        list: createListMethod(prefix),
+    };
+}
+/**
+ * Memory-based Lock Provider (for testing/sync driver)
+ */
+function globToRegExp(pattern) {
+    // Escape all regex metacharacters, then turn '*' into '.*' as a wildcard
+    const escaped = pattern.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+    const regexSource = escaped.replaceAll(String.raw `\*`, '.*');
+    return new RegExp(`^${regexSource}$`);
+}
+export function createMemoryLockProvider(config) {
+    const locks = new Map();
+    const prefix = config.prefix ?? ZintrustLang.MEMORY_LOCKS;
+    const defaultTtl = config.defaultTtl ?? ZintrustLang.ZINTRUST_LOCKS_TTL;
+    return {
+        async acquire(key, options = {}) {
+            const lockKey = `${prefix}${key}`;
+            const ttl = options.ttl ?? defaultTtl;
+            const expires = new Date(Date.now() + ttl);
+            if (locks.has(lockKey)) {
+                const existingLock = locks.get(lockKey);
+                if (existingLock !== undefined && existingLock.expires > new Date()) {
+                    return {
+                        key: lockKey,
+                        ttl,
+                        acquired: false,
+                        expires,
+                    };
+                }
+                // Lock expired, remove it
+                locks.delete(lockKey);
+            }
+            const lock = {
+                key: lockKey,
+                ttl,
+                acquired: true,
+                expires,
+            };
+            locks.set(lockKey, lock);
+            Logger.debug(`Memory lock acquired`, { key: lockKey, ttl });
+            return lock;
+        },
+        async release(lock) {
+            const lockKey = normalizeLockKey(prefix, lock.key);
+            locks.delete(lockKey);
+            Logger.debug(`Memory lock released`, { key: lockKey });
+        },
+        async extend(lock, ttl) {
+            const lockKey = normalizeLockKey(prefix, lock.key);
+            const existingLock = locks.get(lockKey);
+            if (!existingLock) {
+                return false;
+            }
+            existingLock.ttl = ttl;
+            existingLock.expires = new Date(Date.now() + ttl);
+            Logger.debug(`Memory lock extended`, { key: lockKey, ttl });
+            return true;
+        },
+        async status(key) {
+            const lockKey = `${prefix}${key}`;
+            const lock = locks.get(lockKey);
+            if (!lock) {
+                return { exists: false };
+            }
+            if (lock.expires <= new Date()) {
+                locks.delete(lockKey);
+                return { exists: false };
+            }
+            return {
+                exists: true,
+                ttl: lock.ttl,
+                expires: lock.expires,
+            };
+        },
+        async list(pattern = '*') {
+            // Simple glob-style match for memory provider ('*' as wildcard)
+            const regex = globToRegExp(pattern);
+            const keys = [];
+            for (const key of locks.keys()) {
+                const strippedKey = key.replace(prefix, '');
+                if (regex.test(strippedKey)) {
+                    keys.push(strippedKey);
+                }
+            }
+            return keys;
+        },
+    };
+}
+/**
+ * Lock Provider Registry
+ */
+const lockProviders = new Map();
+export function registerLockProvider(name, provider) {
+    lockProviders.set(name, provider);
+    Logger.info(`Lock provider registered`, { name });
+}
+export function getLockProvider(name) {
+    return lockProviders.get(name);
+}
+/**
+ * Clear all registered lock providers (for testing purposes)
+ * @internal
+ */
+export function clearLockProviders() {
+    lockProviders.clear();
+}
+/**
+ * Create lock provider based on configuration
+ */
+export function createLockProvider(config) {
+    switch (config.type) {
+        case ZintrustLang.REDIS:
+            return createRedisLockProvider(config);
+        case ZintrustLang.MEMORY:
+            return createMemoryLockProvider(config);
+        default:
+            throw ErrorFactory.createConfigError(`Unsupported lock provider type: ${config.type}`);
+    }
+}

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

@@ -0,0 +1,25 @@
+export type QueueMessage<T = unknown> = {
+    id: string;
+    payload: T;
+    attempts: number;
+};
+interface IQueueDriver {
+    enqueue<T = unknown>(queue: string, payload: T): Promise<string>;
+    dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string): Promise<void>;
+    length(queue: string): Promise<number>;
+    drain(queue: string): Promise<void>;
+}
+export declare const resolveLockPrefix: () => string;
+export declare const Queue: Readonly<{
+    register(name: string, driver: IQueueDriver): void;
+    reset(): void;
+    get(name?: string): IQueueDriver;
+    enqueue<T = unknown>(queue: string, payload: T, driverName?: string): Promise<string>;
+    dequeue<T = unknown>(queue: string, driverName?: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string, driverName?: string): Promise<void>;
+    length(queue: string, driverName?: string): Promise<number>;
+    drain(queue: string, driverName?: string): Promise<void>;
+}>;
+export default Queue;
+//# sourceMappingURL=Queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/Queue.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,UAAU,YAAY;IACpB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC1E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAID,eAAO,MAAM,iBAAiB,QAAO,MAQpC,CAAC;AAIF,eAAO,MAAM,KAAK;mBACD,MAAM,UAAU,YAAY;aAIlC,IAAI;eAIF,MAAM,GAAG,YAAY;YAUlB,CAAC,mBAAmB,MAAM,WAAW,CAAC,eAAe,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAM7E,CAAC,mBACN,MAAM,eACA,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;eAKtB,MAAM,MAAM,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;kBAKpD,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;iBAK9C,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;EAI9D,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/src/tools/queue/Queue.js

@@ -0,0 +1,53 @@
+import { ZintrustLang } from '../../lang/lang.js';
+import { Env } from '../../config/env.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+let redis_key_prefix;
+export const resolveLockPrefix = () => {
+    if (redis_key_prefix !== undefined) {
+        return redis_key_prefix;
+    }
+    const prefix = Env.get('QUEUE_LOCK_PREFIX', ZintrustLang.ZINTRUST_LOCKS_PREFIX).trim();
+    redis_key_prefix = prefix.length > 0 ? prefix : ZintrustLang.ZINTRUST_LOCKS_PREFIX;
+    return redis_key_prefix;
+};
+const drivers = new Map();
+export const Queue = Object.freeze({
+    register(name, driver) {
+        drivers.set(name.toLowerCase(), driver);
+    },
+    reset() {
+        drivers.clear();
+    },
+    get(name) {
+        const resolved = (name ?? Env.QUEUE_CONNECTION) || Env.QUEUE_DRIVER || 'inmemory';
+        const driverName = (resolved !== null && resolved !== undefined ? String(resolved) : 'inmemory')
+            .trim()
+            .toLowerCase();
+        const driver = drivers.get(driverName);
+        if (!driver)
+            throw ErrorFactory.createConfigError(`Queue driver not registered: ${driverName}`);
+        return driver;
+    },
+    async enqueue(queue, payload, driverName) {
+        const driver = Queue.get(driverName);
+        const jobId = await driver.enqueue(queue, payload);
+        return jobId;
+    },
+    async dequeue(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.dequeue(queue);
+    },
+    async ack(queue, id, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.ack(queue, id);
+    },
+    async length(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.length(queue);
+    },
+    async drain(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.drain(queue);
+    },
+});
+export default Queue;

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

@@ -0,0 +1,46 @@
+/**
+ * Queue Extensions - Backward Compatible Extensions
+ * Extends existing Queue functionality without breaking changes
+ */
+import type { AdvancedJobOptions, QueueConfig } from '../../types/Queue';
+import { createDeduplicationBuilder } from './DeduplicationBuilder';
+/**
+ * Extend existing Queue with advanced capabilities
+ * This provides a migration path for existing code
+ */
+export declare function extendQueue(config: QueueConfig): void;
+/**
+ * Enhanced enqueue method that supports advanced options
+ * This can be used as a drop-in replacement for Queue.enqueue
+ */
+export declare function enqueueAdvanced(name: string, payload: unknown, options?: AdvancedJobOptions): Promise<string>;
+/**
+ * Initialize default lock providers
+ */
+export declare function initializeDefaultLockProviders(): void;
+/**
+ * Get deduplication builder instance
+ */
+export declare function getDeduplicationBuilder(): ReturnType<typeof createDeduplicationBuilder>;
+/**
+ * Queue utilities for lock management
+ */
+export declare const QueueLocks: {
+    release: (key: string) => Promise<void>;
+    extend: (key: string, ttl: number) => Promise<boolean>;
+    status: (key: string) => Promise<boolean>;
+};
+/**
+ * Migration helpers for existing queue code
+ */
+export declare const MigrationHelpers: {
+    /**
+     * Convert existing job options to advanced options
+     */
+    toAdvancedOptions(existingOptions: Record<string, unknown>, uniqueId?: string): AdvancedJobOptions;
+    /**
+     * Add deduplication to existing job patterns
+     */
+    withDeduplication(existingOptions: Record<string, unknown>, deduplicationId: string, ttl?: number): AdvancedJobOptions;
+};
+//# sourceMappingURL=QueueExtensions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QueueExtensions.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueExtensions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAsB,WAAW,EAAE,MAAM,eAAe,CAAC;AAKzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAMzE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAWrD;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;GAEG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAuBrD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAkC3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;OAEG;uCAEgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAC7B,MAAM,GAChB,kBAAkB;IAOrB;;OAEG;uCAEgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,mBACvB,MAAM,QACjB,MAAM,GACX,kBAAkB;CAStB,CAAC"}

package/src/tools/queue/QueueExtensions.js

@@ -0,0 +1,129 @@
+/**
+ * Queue Extensions - Backward Compatible Extensions
+ * Extends existing Queue functionality without breaking changes
+ */
+import { Logger } from '../../config/logger.js';
+import { createValidationError } from '../../exceptions/ZintrustError.js';
+import { ZintrustLang } from '../../lang/lang.js';
+import { createAdvancedQueue } from './AdvancedQueue.js';
+import { createDeduplicationBuilder } from './DeduplicationBuilder.js';
+import { createLockProvider, registerLockProvider } from './LockProvider.js';
+import { Queue } from './Queue.js';
+let advancedQueueRef = null;
+/**
+ * Extend existing Queue with advanced capabilities
+ * This provides a migration path for existing code
+ */
+export function extendQueue(config) {
+    try {
+        const advancedQueue = createAdvancedQueue(config);
+        advancedQueueRef = advancedQueue;
+        Logger.info(`Queue extended with advanced capabilities`, { queueName: config.name });
+    }
+    catch (error) {
+        Logger.error(`Failed to extend queue with advanced capabilities`, { error });
+        throw error;
+    }
+}
+/**
+ * Enhanced enqueue method that supports advanced options
+ * This can be used as a drop-in replacement for Queue.enqueue
+ */
+export async function enqueueAdvanced(name, payload, options = {}) {
+    if (advancedQueueRef === null) {
+        Logger.warn(`Advanced queue not initialized, falling back to standard enqueue`);
+        return Queue.enqueue(name, payload);
+    }
+    return advancedQueueRef.enqueue(name, payload, options);
+}
+/**
+ * Initialize default lock providers
+ */
+export function initializeDefaultLockProviders() {
+    // Register memory lock provider for sync driver
+    registerLockProvider(ZintrustLang.MEMORY, createLockProvider({
+        type: ZintrustLang.MEMORY,
+        prefix: ZintrustLang.ZINTRUST_LOCKS_PREFIX,
+        defaultTtl: ZintrustLang.ZINTRUST_LOCKS_TTL,
+    }));
+    // Register Redis lock provider if Redis is available
+    try {
+        const redisConfig = {
+            type: ZintrustLang.REDIS,
+            prefix: ZintrustLang.ZINTRUST_LOCKS_PREFIX,
+            defaultTtl: ZintrustLang.ZINTRUST_LOCKS_TTL,
+        };
+        registerLockProvider('redis', createLockProvider(redisConfig));
+        Logger.info(`Redis lock provider registered`);
+    }
+    catch (error) {
+        Logger.warn(`Redis lock provider registration failed, using memory provider`, { error });
+    }
+}
+/**
+ * Get deduplication builder instance
+ */
+export function getDeduplicationBuilder() {
+    return createDeduplicationBuilder();
+}
+/**
+ * Queue utilities for lock management
+ */
+export const QueueLocks = {
+    /**
+     * Release a lock by key
+     */
+    async release(key) {
+        if (advancedQueueRef !== null) {
+            return advancedQueueRef.releaseLock(key);
+        }
+        throw createValidationError('Advanced queue not initialized. Call extendQueue() first.');
+    },
+    /**
+     * Extend a lock's TTL
+     */
+    async extend(key, ttl) {
+        if (advancedQueueRef !== null) {
+            return advancedQueueRef.extendLock(key, ttl);
+        }
+        throw createValidationError('Advanced queue not initialized. Call extendQueue() first.');
+    },
+    /**
+     * Check lock status
+     */
+    async status(key) {
+        const { getLockProvider } = await import('../../tools/queue/LockProvider.js');
+        const lockProvider = getLockProvider(ZintrustLang.MEMORY);
+        if (lockProvider !== undefined) {
+            const status = await lockProvider.status(key);
+            return status.exists;
+        }
+        return false;
+    },
+};
+/**
+ * Migration helpers for existing queue code
+ */
+export const MigrationHelpers = {
+    /**
+     * Convert existing job options to advanced options
+     */
+    toAdvancedOptions(existingOptions, uniqueId) {
+        return {
+            ...existingOptions,
+            ...(uniqueId !== null && uniqueId !== undefined && uniqueId !== '' && { uniqueId }),
+        };
+    },
+    /**
+     * Add deduplication to existing job patterns
+     */
+    withDeduplication(existingOptions, deduplicationId, ttl) {
+        return {
+            ...existingOptions,
+            deduplication: createDeduplicationBuilder()
+                .id(deduplicationId)
+                .expireAfter(ttl ?? ZintrustLang.ZINTRUST_LOCKS_TTL)
+                .build(),
+        };
+    },
+};

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

@@ -0,0 +1,11 @@
+import type { QueueConfig } from '../../config/queue';
+/**
+ * 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.
+ */
+export declare function registerQueuesFromRuntimeConfig(config: QueueConfig): 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":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAOjD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAazE"}

package/src/tools/queue/QueueRuntimeRegistration.js

@@ -0,0 +1,25 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { DatabaseQueue } from '../queue/drivers/Database.js';
+import { InMemoryQueue } from '../queue/drivers/InMemory.js';
+import { Queue } from '../queue/Queue.js';
+/**
+ * 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.
+ */
+export function registerQueuesFromRuntimeConfig(config) {
+    // Built-in drivers (core)
+    Queue.register('inmemory', InMemoryQueue);
+    Queue.register('db', 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');
+    }
+    const drv = Queue.get(defaultName);
+    Queue.register('default', drv);
+}

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

@@ -0,0 +1,23 @@
+import type { QueueMessage } from '../../queue/Queue';
+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;0BAsEtB,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"}