@holo-js/queue 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { Job, ConnectionOptions } from 'bullmq';
-
 type QueueJsonPrimitive = string | number | boolean | null;
 type QueueJsonValue = QueueJsonPrimitive | readonly QueueJsonValue[] | {
     readonly [key: string]: QueueJsonValue;
@@ -102,7 +100,7 @@ interface QueuePendingDispatch<TPayload extends QueueJsonValue = QueueJsonValue>
 interface QueueConnectionFacade {
     readonly name: string;
     dispatch<TJobName extends KnownQueueJobName>(jobName: TJobName, payload: QueuePayloadFor<TJobName>, options?: QueueDispatchOptions): QueuePendingDispatch<QueuePayloadFor<TJobName>>;
-    dispatch<TPayload extends QueueJsonValue = QueueJsonValue>(jobName: string, payload: TPayload, options?: QueueDispatchOptions): QueuePendingDispatch<TPayload>;
+    dispatch<TJobName extends Exclude<string, KnownQueueJobName>, TPayload extends QueueJsonValue = QueueJsonValue>(jobName: TJobName, payload: TPayload, options?: QueueDispatchOptions): QueuePendingDispatch<TPayload>;
     dispatchSync<TJobName extends KnownQueueJobName>(jobName: TJobName, payload: QueuePayloadFor<TJobName>): Promise<QueueResultFor<TJobName>>;
     dispatchSync<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown>(jobName: string, payload: TPayload): Promise<TResult>;
 }
@@ -225,10 +223,17 @@ interface QueueFailedStoreConfig {
 }
 interface QueueRedisConnectionConfig {
     readonly driver: 'redis';
+    readonly connection?: string;
     readonly queue?: string;
     readonly retryAfter?: number | string;
     readonly blockFor?: number | string;
     readonly redis?: {
+        readonly url?: string;
+        readonly clusters?: readonly {
+            readonly url?: string;
+            readonly host?: string;
+            readonly port?: number | string;
+        }[];
         readonly host?: string;
         readonly port?: number | string;
         readonly password?: string;
@@ -267,10 +272,17 @@ interface NormalizedQueueSyncConnectionConfig {
 interface NormalizedQueueRedisConnectionConfig {
     readonly name: string;
     readonly driver: 'redis';
+    readonly connection: string;
     readonly queue: string;
     readonly retryAfter: number;
     readonly blockFor: number;
     readonly redis: {
+        readonly url?: string;
+        readonly clusters?: readonly {
+            readonly url?: string;
+            readonly host: string;
+            readonly port: number;
+        }[];
         readonly host: string;
         readonly port: number;
         readonly password?: string;
@@ -278,6 +290,24 @@ interface NormalizedQueueRedisConnectionConfig {
         readonly db: number;
     };
 }
+interface QueueSharedRedisConnectionConfig {
+    readonly name: string;
+    readonly url?: string;
+    readonly clusters?: readonly {
+        readonly url?: string;
+        readonly host: string;
+        readonly port: number;
+    }[];
+    readonly host: string;
+    readonly port: number;
+    readonly password?: string;
+    readonly username?: string;
+    readonly db: number;
+}
+interface QueueSharedRedisConfig {
+    readonly default: string;
+    readonly connections: Readonly<Record<string, QueueSharedRedisConnectionConfig>>;
+}
 interface NormalizedQueueDatabaseConnectionConfig {
     readonly name: string;
     readonly driver: 'database';
@@ -312,7 +342,7 @@ declare const DEFAULT_DATABASE_QUEUE_TABLE = "jobs";
 declare function parseInteger(value: number | string | undefined, fallback: number, label: string, options?: {
     minimum?: number;
 }): number;
-declare function normalizeQueueConfig(config?: HoloQueueConfig): NormalizedHoloQueueConfig;
+declare function normalizeQueueConfig(config?: HoloQueueConfig, redisConfig?: QueueSharedRedisConfig): NormalizedHoloQueueConfig;
 declare const holoQueueDefaults: Readonly<NormalizedHoloQueueConfig>;
 declare const queueInternals: {
     parseInteger: typeof parseInteger;
@@ -332,54 +362,64 @@ declare const queueRegistryInternals: {
     deriveJobNameFromSourcePath: typeof deriveJobNameFromSourcePath;
 };
 
+type RedisDriverModule = {
+    redisQueueDriverFactory: QueueDriverFactory<NormalizedQueueRedisConnectionConfig>;
+};
 type RedisQueuedEnvelope = QueueJobEnvelope<QueueJsonValue>;
-type BullJobInstance = Job<RedisQueuedEnvelope, unknown, string>;
+declare function loadRedisDriverModule(): Promise<RedisDriverModule>;
 declare function normalizeRedisErrorMessage(error: unknown): string;
-declare function isQueueEnvelope(value: unknown): value is QueueJobEnvelope<QueueJsonValue>;
-declare function resolveBullConnectionOptions(connection: NormalizedQueueRedisConnectionConfig): ConnectionOptions;
+declare function isQueueEnvelope(value: unknown): value is RedisQueuedEnvelope;
+type RedisConnectionOptions = {
+    url?: string;
+    clusters?: readonly {
+        readonly url?: string;
+        readonly host: string;
+        readonly port: number;
+    }[];
+    host?: string;
+    port?: number;
+    path?: string;
+    username?: string;
+    password?: string;
+    db: number;
+    maxRetriesPerRequest: null;
+};
+declare function toRedisSocketPath(value: string): string;
+declare function resolveBullConnectionOptions(connection: NormalizedQueueRedisConnectionConfig): RedisConnectionOptions;
 declare class RedisQueueDriverError extends Error {
     constructor(connectionName: string, action: string, cause: unknown);
 }
 declare function wrapRedisError(connectionName: string, action: string, error: unknown): RedisQueueDriverError;
-declare function resolveAttempts(job: BullJobInstance): number;
+declare function resolveAttempts(job: {
+    attemptsStarted?: number;
+    attemptsMade?: number;
+}): number;
 declare class RedisQueueDriver implements QueueAsyncDriver {
+    private readonly connection;
     private readonly context;
     readonly name: string;
     readonly driver: "redis";
     readonly mode: "async";
-    private readonly connection;
-    private readonly bullConnection;
-    private readonly queues;
-    private readonly workers;
-    private readonly reservations;
-    private queueCursor;
+    private driverInstance?;
+    private pending?;
     constructor(connection: NormalizedQueueRedisConnectionConfig, context: QueueDriverFactoryContext);
-    private getQueue;
-    private getWorker;
-    private normalizeQueueNames;
-    private rotateQueueNames;
-    private createReservedJob;
-    private getReservation;
-    private settleReservation;
+    private resolveDriver;
     dispatch<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown>(job: QueueJobEnvelope<TPayload>): Promise<QueueDriverDispatchResult<TResult>>;
-    reserve<TPayload extends QueueJsonValue = QueueJsonValue>(input: {
-        readonly queueNames: readonly string[];
-        readonly workerId: string;
-    }): Promise<QueueReservedJob<TPayload> | null>;
+    reserve<TPayload extends QueueJsonValue = QueueJsonValue>(input: Parameters<QueueAsyncDriver['reserve']>[0]): Promise<QueueReservedJob<TPayload> | null>;
     acknowledge(job: QueueReservedJob): Promise<void>;
     release(job: QueueReservedJob, options?: QueueReleaseOptions): Promise<void>;
     delete(job: QueueReservedJob): Promise<void>;
-    clear(input?: {
-        readonly queueNames?: readonly string[];
-    }): Promise<number>;
+    clear(input?: Parameters<QueueAsyncDriver['clear']>[0]): Promise<number>;
     close(): Promise<void>;
 }
 declare const redisQueueDriverFactory: QueueDriverFactory<NormalizedQueueRedisConnectionConfig>;
 declare const redisQueueDriverInternals: {
     isQueueEnvelope: typeof isQueueEnvelope;
+    loadRedisDriverModule: typeof loadRedisDriverModule;
     normalizeRedisErrorMessage: typeof normalizeRedisErrorMessage;
     resolveAttempts: typeof resolveAttempts;
     resolveBullConnectionOptions: typeof resolveBullConnectionOptions;
+    toRedisSocketPath: typeof toRedisSocketPath;
     wrapRedisError: typeof wrapRedisError;
 };
 
@@ -409,6 +449,7 @@ type QueuePayloadValidationState = {
 };
 type ConfigureQueueRuntimeOptions = {
     readonly config?: HoloQueueConfig | NormalizedHoloQueueConfig;
+    readonly redisConfig?: QueueSharedRedisConfig;
     readonly driverFactories?: ReadonlyArray<QueueDriverFactory> | ReadonlyMap<string, QueueDriverFactory>;
     readonly failedJobStore?: QueueFailedJobStore;
 };
@@ -446,7 +487,9 @@ declare function resetQueueRuntime(): void;
 declare function getQueueRuntime(): QueueRuntimeBinding;
 declare function useQueueConnection(name?: string): QueueConnectionFacade;
 declare function dispatchSync<TJobName extends Extract<keyof HoloQueueJobRegistry, string>>(jobName: TJobName, payload: QueuePayloadFor<TJobName>, options?: QueueDispatchOptions): Promise<QueueResultFor<TJobName>>;
+declare function dispatchSync<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown>(jobName: string, payload: TPayload, options?: QueueDispatchOptions): Promise<TResult>;
 declare function dispatch<TJobName extends Extract<keyof HoloQueueJobRegistry, string>>(jobName: TJobName, payload: QueuePayloadFor<TJobName>, options?: QueueDispatchOptions): QueuePendingDispatch<QueuePayloadFor<TJobName>>;
+declare function dispatch<TJobName extends Exclude<string, Extract<keyof HoloQueueJobRegistry, string>>, TPayload extends QueueJsonValue = QueueJsonValue>(jobName: TJobName, payload: TPayload, options?: QueueDispatchOptions): QueuePendingDispatch<TPayload>;
 declare const Queue: {
     connection(name?: string): QueueConnectionFacade;
     dispatch: typeof dispatch;
@@ -557,4 +600,6 @@ declare const queueWorkerInternals: {
     sleep: typeof sleep;
 };
 
-export { DEFAULT_DATABASE_QUEUE_TABLE, DEFAULT_FAILED_JOBS_CONNECTION, DEFAULT_FAILED_JOBS_TABLE, DEFAULT_QUEUE_BLOCK_FOR, DEFAULT_QUEUE_CONNECTION, DEFAULT_QUEUE_NAME, DEFAULT_QUEUE_RETRY_AFTER, DEFAULT_QUEUE_SLEEP, type ExportedQueueJobDefinition, type HoloQueueConfig, type HoloQueueJobRegistry, type NormalizedHoloQueueConfig, type NormalizedQueueConnectionConfig, type NormalizedQueueDatabaseConnectionConfig, type NormalizedQueueFailedStoreConfig, type NormalizedQueueRedisConnectionConfig, type NormalizedQueueSyncConnectionConfig, Queue, type QueueAsyncDriver, type QueueClearInput, type QueueConnectionConfig, type QueueConnectionFacade, type QueueDatabaseConnectionConfig, type QueueDelayValue, type QueueDispatchCompletedHook, type QueueDispatchFailedHook, type QueueDispatchOptions, type QueueDispatchResult, type QueueDriver, type QueueDriverDispatchResult, type QueueDriverFactory, type QueueDriverFactoryContext, type QueueEnqueueResult, type QueueFailedJobRecord, type QueueFailedJobStore, type QueueFailedStoreConfig, QueueFailedStoreError, type QueueJobContext, type QueueJobContextOverrides, type QueueJobDefinition, type QueueJobEnvelope, type QueueJsonValue, type QueuePayloadFor, type QueuePendingDispatch, type QueueRedisConnectionConfig, type QueueRegisteredJob, type QueueReleaseOptions, QueueReleaseUnsupportedError, type QueueReserveInput, type QueueReservedJob, type QueueResultFor, type QueueRuntimeBinding, type QueueSyncConnectionConfig, type QueueSyncDriver, type QueueWorkerHooks, type QueueWorkerJobEvent, type QueueWorkerOptions, type QueueWorkerResult, type QueueWorkerRunOptions, QueueWorkerTimeoutError, QueueWorkerUnsupportedDriverError, RedisQueueDriver, RedisQueueDriverError, type RegisterQueueJobOptions, type RegisterableQueueJobDefinition, clearQueueConnection, configureQueueRuntime, defineJob, dispatch, dispatchSync, flushFailedQueueJobs, forgetFailedQueueJob, getQueueRuntime, getRegisteredQueueJob, holoQueueDefaults, isQueueJobDefinition, listFailedQueueJobs, listRegisteredQueueJobs, normalizeQueueConfig, normalizeQueueJobDefinition, persistFailedQueueJob, queueFailedInternals, queueInternals, queueJobInternals, queueRegistryInternals, queueRuntimeInternals, queueWorkerInternals, redisQueueDriverFactory, redisQueueDriverInternals, registerQueueJob, registerQueueJobs, resetQueueRegistry, resetQueueRuntime, retryFailedQueueJobs, runQueueWorker, shutdownQueueRuntime, syncQueueDriverFactory, syncQueueDriverInternals, unregisterQueueJob, useQueueConnection };
+declare function defineQueueConfig<TConfig extends HoloQueueConfig>(config: TConfig): Readonly<TConfig>;
+
+export { DEFAULT_DATABASE_QUEUE_TABLE, DEFAULT_FAILED_JOBS_CONNECTION, DEFAULT_FAILED_JOBS_TABLE, DEFAULT_QUEUE_BLOCK_FOR, DEFAULT_QUEUE_CONNECTION, DEFAULT_QUEUE_NAME, DEFAULT_QUEUE_RETRY_AFTER, DEFAULT_QUEUE_SLEEP, type ExportedQueueJobDefinition, type HoloQueueConfig, type HoloQueueJobRegistry, type NormalizedHoloQueueConfig, type NormalizedQueueConnectionConfig, type NormalizedQueueDatabaseConnectionConfig, type NormalizedQueueFailedStoreConfig, type NormalizedQueueRedisConnectionConfig, type NormalizedQueueSyncConnectionConfig, Queue, type QueueAsyncDriver, type QueueClearInput, type QueueConnectionConfig, type QueueConnectionFacade, type QueueDatabaseConnectionConfig, type QueueDelayValue, type QueueDispatchCompletedHook, type QueueDispatchFailedHook, type QueueDispatchOptions, type QueueDispatchResult, type QueueDriver, type QueueDriverDispatchResult, type QueueDriverFactory, type QueueDriverFactoryContext, type QueueEnqueueResult, type QueueFailedJobRecord, type QueueFailedJobStore, type QueueFailedStoreConfig, QueueFailedStoreError, type QueueJobContext, type QueueJobContextOverrides, type QueueJobDefinition, type QueueJobEnvelope, type QueueJsonValue, type QueuePayloadFor, type QueuePendingDispatch, type QueueRedisConnectionConfig, type QueueRegisteredJob, type QueueReleaseOptions, QueueReleaseUnsupportedError, type QueueReserveInput, type QueueReservedJob, type QueueResultFor, type QueueRuntimeBinding, type QueueSharedRedisConfig, type QueueSharedRedisConnectionConfig, type QueueSyncConnectionConfig, type QueueSyncDriver, type QueueWorkerHooks, type QueueWorkerJobEvent, type QueueWorkerOptions, type QueueWorkerResult, type QueueWorkerRunOptions, QueueWorkerTimeoutError, QueueWorkerUnsupportedDriverError, RedisQueueDriver, RedisQueueDriverError, type RegisterQueueJobOptions, type RegisterableQueueJobDefinition, clearQueueConnection, configureQueueRuntime, defineJob, defineQueueConfig, dispatch, dispatchSync, flushFailedQueueJobs, forgetFailedQueueJob, getQueueRuntime, getRegisteredQueueJob, holoQueueDefaults, isQueueJobDefinition, listFailedQueueJobs, listRegisteredQueueJobs, normalizeQueueConfig, normalizeQueueJobDefinition, persistFailedQueueJob, queueFailedInternals, queueInternals, queueJobInternals, queueRegistryInternals, queueRuntimeInternals, queueWorkerInternals, redisQueueDriverFactory, redisQueueDriverInternals, registerQueueJob, registerQueueJobs, resetQueueRegistry, resetQueueRuntime, retryFailedQueueJobs, runQueueWorker, shutdownQueueRuntime, syncQueueDriverFactory, syncQueueDriverInternals, unregisterQueueJob, useQueueConnection };

package/dist/index.mjs

@@ -134,11 +134,34 @@ function normalizeSyncConnection(name, config) {
     queue: normalizeQueueName(config.queue)
   });
 }
-function normalizeRedisConnection(name, config) {
-  const redis = config.redis ?? {};
+function resolveSharedRedisConnection(redisConfig, connectionName) {
+  const resolvedConnection = redisConfig.connections[connectionName];
+  if (!resolvedConnection) {
+    const availableConnections = Object.keys(redisConfig.connections);
+    throw new Error(
+      `[Holo Queue] Queue Redis connection "${connectionName}" was not found in shared Redis config. Available connections: ${availableConnections.join(", ") || "(none)"}.`
+    );
+  }
+  return resolvedConnection;
+}
+function normalizeRedisConnection(name, config, redisConfig) {
+  const explicitConnectionName = config.connection?.trim();
+  const connectionName = explicitConnectionName || redisConfig?.default;
+  if (!connectionName) {
+    throw new Error(
+      `[Holo Queue] Queue Redis connection "${name}" requires a shared Redis config with a default connection or an explicit connection name.`
+    );
+  }
+  if (!redisConfig) {
+    throw new Error(
+      `[Holo Queue] Queue Redis connection "${name}" references shared Redis connection "${connectionName}" but no shared Redis config was provided.`
+    );
+  }
+  const resolvedRedisConnection = resolveSharedRedisConnection(redisConfig, connectionName);
   return Object.freeze({
     name,
     driver: "redis",
+    connection: resolvedRedisConnection.name,
     queue: normalizeQueueName(config.queue),
     retryAfter: parseInteger(config.retryAfter, DEFAULT_QUEUE_RETRY_AFTER, `queue connection "${name}" retryAfter`, {
       minimum: 0
@@ -147,15 +170,13 @@ function normalizeRedisConnection(name, config) {
       minimum: 0
     }),
     redis: Object.freeze({
-      host: redis.host?.trim() || "127.0.0.1",
-      port: parseInteger(redis.port, 6379, `queue connection "${name}" redis.port`, {
-        minimum: 1
-      }),
-      password: redis.password?.trim() || void 0,
-      username: redis.username?.trim() || void 0,
-      db: parseInteger(redis.db, 0, `queue connection "${name}" redis.db`, {
-        minimum: 0
-      })
+      ...typeof resolvedRedisConnection.url === "undefined" ? {} : { url: resolvedRedisConnection.url },
+      ...typeof resolvedRedisConnection.clusters === "undefined" ? {} : { clusters: resolvedRedisConnection.clusters },
+      host: resolvedRedisConnection.host,
+      port: resolvedRedisConnection.port,
+      password: resolvedRedisConnection.password,
+      username: resolvedRedisConnection.username,
+      db: resolvedRedisConnection.db
     })
   });
 }
@@ -174,25 +195,25 @@ function normalizeDatabaseConnection(name, config) {
     table: config.table?.trim() || DEFAULT_DATABASE_QUEUE_TABLE
   });
 }
-function normalizeConnectionConfig(name, config) {
+function normalizeConnectionConfig(name, config, redisConfig) {
   switch (config.driver) {
     case "sync":
       return normalizeSyncConnection(name, config);
     case "redis":
-      return normalizeRedisConnection(name, config);
+      return normalizeRedisConnection(name, config, redisConfig);
     case "database":
       return normalizeDatabaseConnection(name, config);
     default:
       throw new Error(`[Holo Queue] Unsupported queue driver "${String(config.driver)}" on connection "${name}".`);
   }
 }
-function normalizeConnections(connections) {
+function normalizeConnections(connections, redisConfig) {
   if (!connections || Object.keys(connections).length === 0) {
     return DEFAULT_QUEUE_CONFIG.connections;
   }
   const normalizedEntries = Object.entries(connections).map(([name, config]) => {
     const normalizedName = normalizeConnectionName(name, "Queue connection name");
-    return [normalizedName, normalizeConnectionConfig(normalizedName, config)];
+    return [normalizedName, normalizeConnectionConfig(normalizedName, config, redisConfig)];
   });
   return Object.freeze(Object.fromEntries(normalizedEntries));
 }
@@ -210,8 +231,8 @@ function normalizeFailedStore(config) {
     table: normalized.table?.trim() || DEFAULT_FAILED_JOBS_TABLE
   });
 }
-function normalizeQueueConfig(config = {}) {
-  const connections = normalizeConnections(config.connections);
+function normalizeQueueConfig(config = {}, redisConfig) {
+  const connections = normalizeConnections(config.connections, redisConfig);
   const connectionNames = Object.keys(connections);
   const defaultConnection = config.default?.trim() || connectionNames[0];
   if (!connections[defaultConnection]) {
@@ -298,11 +319,22 @@ var queueRegistryInternals = {
 };
 
 // src/drivers/redis.ts
-import { randomUUID } from "crypto";
-import {
-  Queue as BullQueue,
-  Worker as BullWorker
-} from "bullmq";
+function isModuleNotFoundError(error) {
+  return !!error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND";
+}
+async function loadRedisDriverModule() {
+  try {
+    const specifier = "@holo-js/queue-redis";
+    return await import(specifier);
+  } catch (error) {
+    if (isModuleNotFoundError(error)) {
+      throw new Error("[@holo-js/queue] Redis queue support requires @holo-js/queue-redis to be installed.", {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
 function normalizeRedisErrorMessage(error) {
   if (error instanceof Error) {
     return error.message;
@@ -315,10 +347,19 @@ function isRecord(value) {
 function isQueueEnvelope(value) {
   return isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && typeof value.connection === "string" && typeof value.queue === "string" && "payload" in value && typeof value.attempts === "number" && Number.isInteger(value.attempts) && value.attempts >= 0 && typeof value.maxAttempts === "number" && Number.isInteger(value.maxAttempts) && value.maxAttempts >= 1 && typeof value.createdAt === "number" && Number.isFinite(value.createdAt) && (typeof value.availableAt === "undefined" || typeof value.availableAt === "number" && Number.isFinite(value.availableAt));
 }
+function isRedisSocketConnectionTarget(value) {
+  return value.startsWith("unix://") || value.startsWith("/");
+}
+function toRedisSocketPath(value) {
+  return value.startsWith("unix://") ? value.slice("unix://".length) : value;
+}
 function resolveBullConnectionOptions(connection) {
+  const redisHost = connection.redis.host;
   return {
-    host: connection.redis.host,
-    port: connection.redis.port,
+    ...typeof connection.redis.url === "string" ? { url: connection.redis.url } : connection.redis.clusters && connection.redis.clusters.length > 0 ? { clusters: connection.redis.clusters } : typeof redisHost === "string" && isRedisSocketConnectionTarget(redisHost) ? { path: toRedisSocketPath(redisHost) } : {
+      host: redisHost,
+      port: connection.redis.port
+    },
     username: connection.redis.username,
     password: connection.redis.password,
     db: connection.redis.db,
@@ -341,230 +382,64 @@ function wrapRedisError(connectionName, action, error) {
   return new RedisQueueDriverError(connectionName, action, error);
 }
 function resolveAttempts(job) {
+  const attemptsStarted = typeof job.attemptsStarted === "number" && Number.isInteger(job.attemptsStarted) ? job.attemptsStarted : 0;
+  const attemptsMade = typeof job.attemptsMade === "number" && Number.isInteger(job.attemptsMade) ? job.attemptsMade : 0;
   return Math.max(
-    Number.isInteger(job.attemptsStarted) ? job.attemptsStarted - 1 : 0,
-    Number.isInteger(job.attemptsMade) ? job.attemptsMade : 0,
+    attemptsStarted > 0 ? attemptsStarted - 1 : 0,
+    attemptsMade,
     0
   );
 }
 var RedisQueueDriver = class {
   constructor(connection, context) {
+    this.connection = connection;
     this.context = context;
     this.name = connection.name;
-    this.connection = connection;
-    this.bullConnection = resolveBullConnectionOptions(connection);
   }
   name;
   driver = "redis";
   mode = "async";
-  connection;
-  bullConnection;
-  queues = /* @__PURE__ */ new Map();
-  workers = /* @__PURE__ */ new Map();
-  reservations = /* @__PURE__ */ new Map();
-  queueCursor = 0;
-  getQueue(queueName) {
-    const cached = this.queues.get(queueName);
-    if (cached) {
-      return cached;
-    }
-    const queue = new BullQueue(queueName, {
-      connection: this.bullConnection,
-      defaultJobOptions: {
-        removeOnComplete: true,
-        removeOnFail: true
-      }
-    });
-    this.queues.set(queueName, queue);
-    return queue;
-  }
-  async getWorker(queueName) {
-    const cached = this.workers.get(queueName);
-    if (cached) {
-      return cached;
+  driverInstance;
+  pending;
+  async resolveDriver() {
+    if (this.driverInstance) {
+      return this.driverInstance;
     }
-    const worker = new BullWorker(
-      queueName,
-      null,
-      {
-        autorun: false,
-        concurrency: 1,
-        connection: this.bullConnection,
-        drainDelay: this.connection.blockFor,
-        lockDuration: this.connection.retryAfter * 1e3,
-        removeOnComplete: { count: 0 },
-        removeOnFail: { count: 0 }
+    this.pending ??= loadRedisDriverModule().then((module) => {
+      const driver = module.redisQueueDriverFactory.create(this.connection, this.context);
+      if (driver.mode !== "async") {
+        throw new Error("[Holo Queue] Redis queue driver must be async.");
       }
-    );
-    await worker.waitUntilReady();
-    this.workers.set(queueName, worker);
-    return worker;
-  }
-  normalizeQueueNames(queueNames) {
-    if (!queueNames || queueNames.length === 0) {
-      return [.../* @__PURE__ */ new Set([
-        this.connection.queue,
-        ...this.queues.keys(),
-        ...this.workers.keys()
-      ])];
-    }
-    return [...new Set(queueNames)];
-  }
-  rotateQueueNames(queueNames) {
-    if (queueNames.length <= 1) {
-      return queueNames;
-    }
-    const offset = this.queueCursor % queueNames.length;
-    this.queueCursor = (this.queueCursor + 1) % queueNames.length;
-    return Object.freeze([
-      ...queueNames.slice(offset),
-      ...queueNames.slice(0, offset)
-    ]);
-  }
-  createReservedJob(job, token, queueName) {
-    if (!job.id) {
-      throw new Error("BullMQ returned a reserved job without an id.");
-    }
-    if (!isQueueEnvelope(job.data)) {
-      throw new Error(`BullMQ returned a malformed payload for job "${job.id}".`);
-    }
-    const attempts = resolveAttempts(job);
-    const envelope = Object.freeze({
-      id: job.id,
-      name: job.data.name,
-      connection: job.data.connection,
-      queue: job.data.queue || queueName,
-      payload: job.data.payload,
-      attempts,
-      maxAttempts: job.data.maxAttempts,
-      ...typeof job.data.availableAt === "number" ? { availableAt: job.data.availableAt } : {},
-      createdAt: job.data.createdAt
-    });
-    this.reservations.set(token, {
-      job,
-      token
+      this.driverInstance = driver;
+      return driver;
+    }).finally(() => {
+      this.pending = void 0;
     });
-    return {
-      reservationId: token,
-      envelope,
-      reservedAt: Date.now()
-    };
-  }
-  getReservation(reserved) {
-    const reservation = this.reservations.get(reserved.reservationId);
-    if (!reservation) {
-      throw new Error(`Queue reservation "${reserved.reservationId}" is not active.`);
-    }
-    return reservation;
-  }
-  async settleReservation(reserved, action, callback) {
-    const reservation = this.getReservation(reserved);
-    try {
-      await callback(reservation);
-    } catch (error) {
-      throw wrapRedisError(this.name, action, error);
-    } finally {
-      this.reservations.delete(reserved.reservationId);
-    }
+    return this.pending;
   }
   async dispatch(job) {
-    try {
-      const delay = typeof job.availableAt === "number" ? Math.max(job.availableAt - Date.now(), 0) : void 0;
-      const queued = await this.getQueue(job.queue).add(job.name, job, {
-        attempts: job.maxAttempts,
-        ...typeof delay === "number" ? { delay } : {},
-        jobId: job.id,
-        removeOnComplete: true,
-        removeOnFail: true,
-        timestamp: job.createdAt
-      });
-      return {
-        jobId: queued.id ?? job.id,
-        synchronous: false
-      };
-    } catch (error) {
-      throw wrapRedisError(this.name, "enqueue job", error);
-    }
+    return (await this.resolveDriver()).dispatch(job);
   }
   async reserve(input) {
-    try {
-      const queueNames = this.rotateQueueNames(this.normalizeQueueNames(input.queueNames));
-      for (const queueName of queueNames) {
-        const token2 = `${input.workerId}:${randomUUID()}`;
-        const worker2 = await this.getWorker(queueName);
-        const job2 = await worker2.getNextJob(token2, { block: false });
-        if (job2) {
-          return this.createReservedJob(job2, token2, queueName);
-        }
-      }
-      const [blockingQueue] = queueNames;
-      if (!blockingQueue || this.connection.blockFor <= 0) {
-        return null;
-      }
-      const token = `${input.workerId}:${randomUUID()}`;
-      const worker = await this.getWorker(blockingQueue);
-      const job = await worker.getNextJob(token, { block: true });
-      if (!job) {
-        return null;
-      }
-      return this.createReservedJob(job, token, blockingQueue);
-    } catch (error) {
-      throw wrapRedisError(this.name, "reserve job", error);
-    }
+    return (await this.resolveDriver()).reserve(input);
   }
   async acknowledge(job) {
-    await this.settleReservation(job, "acknowledge job", async (reservation) => {
-      await reservation.job.moveToCompleted(null, reservation.token, false);
-    });
+    await (await this.resolveDriver()).acknowledge(job);
   }
   async release(job, options) {
-    await this.settleReservation(job, "release job", async (reservation) => {
-      if (typeof options?.delaySeconds === "number" && options.delaySeconds > 0) {
-        await reservation.job.moveToDelayed(Date.now() + options.delaySeconds * 1e3, reservation.token);
-        return;
-      }
-      await reservation.job.moveToWait(reservation.token);
-    });
+    await (await this.resolveDriver()).release(job, options);
   }
   async delete(job) {
-    await this.settleReservation(job, "delete job", async (reservation) => {
-      reservation.job.discard();
-      await reservation.job.moveToFailed(new Error("[Holo Queue] Job deleted."), reservation.token, false);
-    });
+    await (await this.resolveDriver()).delete(job);
   }
   async clear(input) {
-    try {
-      const queueNames = this.normalizeQueueNames(input?.queueNames);
-      let cleared = 0;
-      for (const queueName of queueNames) {
-        const queue = this.getQueue(queueName);
-        cleared += await queue.getJobCountByTypes("wait", "waiting", "paused", "prioritized", "delayed");
-        await queue.drain(true);
-      }
-      return cleared;
-    } catch (error) {
-      throw wrapRedisError(this.name, "clear queued jobs", error);
-    }
+    return (await this.resolveDriver()).clear(input);
   }
   async close() {
-    const resources = [
-      ...this.workers.values(),
-      ...this.queues.values()
-    ];
-    this.reservations.clear();
-    this.workers.clear();
-    this.queues.clear();
-    const results = await Promise.allSettled(resources.map(async (resource) => {
-      if (resource instanceof BullWorker) {
-        await resource.close(true);
-        return;
-      }
-      await resource.close();
-    }));
-    const rejection = results.find((result) => result.status === "rejected");
-    if (rejection) {
-      throw wrapRedisError(this.name, "close driver", rejection.reason);
+    if (!this.driverInstance && !this.pending) {
+      return;
     }
+    await (await this.resolveDriver()).close();
   }
 };
 var redisQueueDriverFactory = {
@@ -575,9 +450,11 @@ var redisQueueDriverFactory = {
 };
 var redisQueueDriverInternals = {
   isQueueEnvelope,
+  loadRedisDriverModule,
   normalizeRedisErrorMessage,
   resolveAttempts,
   resolveBullConnectionOptions,
+  toRedisSocketPath,
   wrapRedisError
 };
 
@@ -616,7 +493,7 @@ var syncQueueDriverInternals = {
 };
 
 // src/runtime.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
 var INLINE_SYNC_DRIVER_KEY = "__inline_sync__";
 var QueueReleaseUnsupportedError = class extends Error {
   constructor() {
@@ -683,6 +560,11 @@ function normalizeQueueName2(name) {
   }
   return normalized;
 }
+function isNormalizedQueueConfig(config) {
+  return typeof config.default === "string" && typeof config.connections === "object" && config.connections !== null && Object.values(config.connections).every((connection) => {
+    return typeof connection === "object" && connection !== null && "name" in connection && "driver" in connection && "queue" in connection && typeof connection.name === "string" && typeof connection.driver === "string" && typeof connection.queue === "string";
+  });
+}
 function normalizeDispatchCompletedHook(callback) {
   if (typeof callback !== "function") {
     throw new Error("[Holo Queue] Queue dispatch onComplete hook must be a function.");
@@ -901,7 +783,7 @@ function createJobEnvelope(jobName, payload, options) {
   );
   const queue = normalizeQueueName2(options.queue ?? registered.definition.queue ?? connection.queue ?? DEFAULT_QUEUE_NAME);
   return Object.freeze({
-    id: randomUUID2(),
+    id: randomUUID(),
     name: registered.name,
     connection: connection.name,
     queue,
@@ -1041,7 +923,7 @@ function configureQueueRuntime(options = {}) {
   const state = getQueueRuntimeState();
   let shouldResetDrivers = false;
   if (options.config) {
-    state.config = normalizeQueueConfig(options.config);
+    state.config = isNormalizedQueueConfig(options.config) ? options.config : normalizeQueueConfig(options.config, options.redisConfig);
     shouldResetDrivers = true;
   }
   if (options.driverFactories) {
@@ -1241,7 +1123,7 @@ var queueFailedInternals = {
 };
 
 // src/worker.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 var QueueWorkerUnsupportedDriverError = class extends Error {
   constructor(connectionName, driverName) {
     super(
@@ -1484,7 +1366,7 @@ async function runQueueWorker(options = {}) {
   const sleepSeconds = normalizeNonNegativeInteger(options.sleep, "Queue worker sleep") ?? ("sleep" in connection && typeof connection.sleep === "number" ? connection.sleep : 1);
   const maxJobs = normalizePositiveInteger(options.maxJobs, "Queue worker maxJobs");
   const maxTime = normalizePositiveInteger(options.maxTime, "Queue worker maxTime");
-  const workerId = options.workerId?.trim() || randomUUID3();
+  const workerId = options.workerId?.trim() || randomUUID2();
   const sleepFn = options.sleepFn ?? sleep;
   const driver = requireAsyncDriver(queueRuntimeInternals.resolveConnectionDriver(connection.name), connection.name);
   const startedAt = Date.now();
@@ -1584,6 +1466,14 @@ var queueWorkerInternals = {
   runWithTimeout,
   sleep
 };
+
+// src/index.ts
+function defineConfig(config) {
+  return Object.freeze({ ...config });
+}
+function defineQueueConfig(config) {
+  return defineConfig(config);
+}
 export {
   DEFAULT_DATABASE_QUEUE_TABLE,
   DEFAULT_FAILED_JOBS_CONNECTION,
@@ -1603,6 +1493,7 @@ export {
   clearQueueConnection,
   configureQueueRuntime,
   defineJob,
+  defineQueueConfig,
   dispatch,
   dispatchSync,
   flushFailedQueueJobs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/queue",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Holo-JS Framework - queue contracts and config helpers",
   "type": "module",
   "license": "MIT",
@@ -22,10 +22,16 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest --run"
   },
-  "dependencies": {
-    "bullmq": "^5.71.0"
+  "peerDependencies": {
+    "@holo-js/queue-redis": "^0.1.3"
+  },
+  "peerDependenciesMeta": {
+    "@holo-js/queue-redis": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@holo-js/queue-redis": "workspace:*",
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",