@holo-js/queue 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -76,10 +76,11 @@ interface QueueRegisteredJob<TPayload extends QueueJsonValue = QueueJsonValue, T
 interface HoloQueueJobRegistry {
 }
 type KnownQueueJobName = Extract<keyof HoloQueueJobRegistry, string>;
-type ResolveRegisteredQueueJobDefinition<TJobName extends string> = TJobName extends KnownQueueJobName ? Extract<HoloQueueJobRegistry[TJobName], QueueJobDefinition> extends never ? QueueJobDefinition : Extract<HoloQueueJobRegistry[TJobName], QueueJobDefinition> : QueueJobDefinition;
-type ExportedQueueJobDefinition<TValue> = Extract<TValue, QueueJobDefinition> extends never ? QueueJobDefinition : Extract<TValue, QueueJobDefinition>;
-type QueuePayloadFor<TJobName extends string> = ResolveRegisteredQueueJobDefinition<TJobName> extends QueueJobDefinition<infer TPayload, unknown> ? TPayload : QueueJsonValue;
-type QueueResultFor<TJobName extends string> = ResolveRegisteredQueueJobDefinition<TJobName> extends QueueJobDefinition<QueueJsonValue, infer TResult> ? TResult : unknown;
+type DynamicQueueJobName<TJobName extends string> = [KnownQueueJobName] extends [never] ? TJobName : TJobName extends KnownQueueJobName ? never : KnownQueueJobName extends TJobName ? never : TJobName;
+type ResolveRegisteredQueueJobDefinition<TJobName extends string> = TJobName extends KnownQueueJobName ? HoloQueueJobRegistry[TJobName] extends QueueJobDefinition<infer TPayload, infer TResult> ? QueueJobDefinition<TPayload, TResult> : QueueJobDefinition : QueueJobDefinition;
+type ExportedQueueJobDefinition<TValue> = TValue extends QueueJobDefinition<infer TPayload, infer TResult> ? QueueJobDefinition<TPayload, TResult> : QueueJobDefinition;
+type QueuePayloadFor<TJobName extends string> = ResolveRegisteredQueueJobDefinition<TJobName> extends QueueJobDefinition<infer TPayload, infer _TResult> ? TPayload : QueueJsonValue;
+type QueueResultFor<TJobName extends string> = ResolveRegisteredQueueJobDefinition<TJobName> extends QueueJobDefinition<infer _TPayload, infer TResult> ? TResult : unknown;
 interface RegisterQueueJobOptions {
     readonly name?: string;
     readonly sourcePath?: string;
@@ -100,9 +101,9 @@ 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<TJobName extends Exclude<string, KnownQueueJobName>, TPayload extends QueueJsonValue = QueueJsonValue>(jobName: TJobName, payload: TPayload, options?: QueueDispatchOptions): QueuePendingDispatch<TPayload>;
+    dispatch<TPayload extends QueueJsonValue = QueueJsonValue, const TJobName extends string = string>(jobName: TJobName & DynamicQueueJobName<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>;
+    dispatchSync<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown, const TJobName extends string = string>(jobName: TJobName & DynamicQueueJobName<TJobName>, payload: TPayload): Promise<TResult>;
 }
 interface QueueEnqueueResult {
     readonly jobId: string;
@@ -486,10 +487,12 @@ declare function shutdownQueueRuntime(): Promise<void>;
 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>;
+type KnownRuntimeQueueJobName = Extract<keyof HoloQueueJobRegistry, string>;
+type DynamicRuntimeQueueJobName<TJobName extends string> = [KnownRuntimeQueueJobName] extends [never] ? TJobName : TJobName extends KnownRuntimeQueueJobName ? never : KnownRuntimeQueueJobName extends TJobName ? never : TJobName;
+declare function dispatchSync<TJobName extends KnownRuntimeQueueJobName>(jobName: TJobName, payload: QueuePayloadFor<TJobName>, options?: QueueDispatchOptions): Promise<QueueResultFor<TJobName>>;
+declare function dispatchSync<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown, const TJobName extends string = string>(jobName: TJobName & DynamicRuntimeQueueJobName<TJobName>, payload: TPayload, options?: QueueDispatchOptions): Promise<TResult>;
+declare function dispatch<TJobName extends KnownRuntimeQueueJobName>(jobName: TJobName, payload: QueuePayloadFor<TJobName>, options?: QueueDispatchOptions): QueuePendingDispatch<QueuePayloadFor<TJobName>>;
+declare function dispatch<TPayload extends QueueJsonValue = QueueJsonValue, const TJobName extends string = string>(jobName: TJobName & DynamicRuntimeQueueJobName<TJobName>, payload: TPayload, options?: QueueDispatchOptions): QueuePendingDispatch<TPayload>;
 declare const Queue: {
     connection(name?: string): QueueConnectionFacade;
     dispatch: typeof dispatch;
@@ -578,6 +581,7 @@ declare function normalizeNonNegativeInteger(value: number | undefined, label: s
 declare function normalizePositiveInteger(value: number | undefined, label: string): number | undefined;
 declare function createWorkerEvent(envelope: QueueJobEnvelope, maxAttempts: number): QueueWorkerJobEvent;
 declare function resolveRetryDelaySeconds(definition: QueueJobDefinition, attempt: number): number | undefined;
+declare function runWorkerHook(jobName: string, hookName: 'onJobFailed' | 'onJobProcessed' | 'onJobReleased', callback: () => void | Promise<void>): Promise<void>;
 declare function runWithTimeout<TResult>(callback: Promise<TResult>, jobName: string, timeoutSeconds: number | undefined, onTimeout?: () => void): Promise<TResult>;
 declare function processReservedJob(driver: QueueAsyncDriver, reserved: QueueReservedJob<QueueJsonValue>, options: Pick<QueueWorkerRunOptions, 'timeout' | 'tries' | 'onJobFailed' | 'onJobProcessed' | 'onJobReleased'>): Promise<QueueWorkerProcessingOutcome>;
 declare function resolveWorkerStopReason(options: QueueWorkerOptions, state: {
@@ -597,6 +601,7 @@ declare const queueWorkerInternals: {
     resolveRetryDelaySeconds: typeof resolveRetryDelaySeconds;
     resolveWorkerStopReason: typeof resolveWorkerStopReason;
     runWithTimeout: typeof runWithTimeout;
+    runWorkerHook: typeof runWorkerHook;
     sleep: typeof sleep;
 };
 

package/dist/index.mjs

@@ -89,6 +89,9 @@ var DEFAULT_QUEUE_SLEEP = 1;
 var DEFAULT_FAILED_JOBS_CONNECTION = "default";
 var DEFAULT_FAILED_JOBS_TABLE = "failed_jobs";
 var DEFAULT_DATABASE_QUEUE_TABLE = "jobs";
+var DEFAULT_REDIS_HOST = "127.0.0.1";
+var DEFAULT_REDIS_PORT = 6379;
+var DEFAULT_REDIS_DB = 0;
 var DEFAULT_QUEUE_CONFIG = Object.freeze({
   default: DEFAULT_QUEUE_CONNECTION,
   failed: Object.freeze({
@@ -108,14 +111,18 @@ function parseInteger(value, fallback, label, options = {}) {
   if (typeof value === "undefined") {
     return fallback;
   }
-  const normalized = typeof value === "number" ? value : Number.parseInt(value, 10);
-  if (!Number.isInteger(normalized)) {
+  const normalized = typeof value === "number" ? value : value.trim();
+  if (typeof normalized === "string" && !/^[+-]?\d+$/.test(normalized)) {
     throw new Error(`[Holo Queue] ${label} must be an integer.`);
   }
-  if (typeof options.minimum === "number" && normalized < options.minimum) {
+  const integer = typeof normalized === "number" ? normalized : Number(normalized);
+  if (!Number.isInteger(integer)) {
+    throw new Error(`[Holo Queue] ${label} must be an integer.`);
+  }
+  if (typeof options.minimum === "number" && integer < options.minimum) {
     throw new Error(`[Holo Queue] ${label} must be greater than or equal to ${options.minimum}.`);
   }
-  return normalized;
+  return integer;
 }
 function normalizeConnectionName(value, label) {
   const normalized = value?.trim();
@@ -127,6 +134,9 @@ function normalizeConnectionName(value, label) {
 function normalizeQueueName(value) {
   return value?.trim() || DEFAULT_QUEUE_NAME;
 }
+function normalizeOptionalRedisString(value) {
+  return value?.trim() || void 0;
+}
 function normalizeSyncConnection(name, config) {
   return Object.freeze({
     name,
@@ -144,24 +154,92 @@ function resolveSharedRedisConnection(redisConfig, connectionName) {
   }
   return resolvedConnection;
 }
+function parseRedisDatabaseFromUrl(url, label) {
+  if (typeof url === "undefined") {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    throw new Error(`[Holo Queue] ${label} is invalid: ${String(error)}`);
+  }
+  if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+    throw new Error(`[Holo Queue] ${label} is invalid: unsupported protocol "${parsed.protocol}".`);
+  }
+  const pathname = parsed.pathname.replace(/^\/+/, "");
+  if (!pathname) {
+    return void 0;
+  }
+  const [databaseSegment] = pathname.split("/");
+  if (!databaseSegment || !/^\d+$/.test(databaseSegment) || pathname !== databaseSegment) {
+    throw new Error(`[Holo Queue] ${label} must include at most one integer database path segment.`);
+  }
+  return Number(databaseSegment);
+}
+function normalizeRedisClusterNodes(connectionName, nodes) {
+  if (!nodes || nodes.length === 0) {
+    return void 0;
+  }
+  return Object.freeze(nodes.map((node, index) => {
+    const label = `queue connection "${connectionName}" redis cluster node ${index + 1}`;
+    const url = normalizeOptionalRedisString(node.url);
+    if (typeof url !== "undefined") {
+      const database = parseRedisDatabaseFromUrl(url, `${label} url`);
+      if (typeof database !== "undefined") {
+        throw new Error(`[Holo Queue] ${label} url cannot include a database path in cluster mode.`);
+      }
+    }
+    return Object.freeze({
+      ...typeof url === "undefined" ? {} : { url },
+      host: normalizeOptionalRedisString(node.host) ?? DEFAULT_REDIS_HOST,
+      port: parseInteger(node.port, DEFAULT_REDIS_PORT, `${label} port`, {
+        minimum: 1
+      })
+    });
+  }));
+}
+function normalizeRedisOptions(connectionName, base, overrides) {
+  const hasTargetOverride = typeof overrides?.url !== "undefined" || typeof overrides?.clusters !== "undefined" || typeof overrides?.host !== "undefined" || typeof overrides?.port !== "undefined";
+  const url = normalizeOptionalRedisString(overrides?.url) ?? (hasTargetOverride ? void 0 : base?.url);
+  const clusters = typeof overrides?.clusters === "undefined" ? hasTargetOverride ? void 0 : base?.clusters : normalizeRedisClusterNodes(connectionName, overrides.clusters);
+  const dbFromUrl = parseRedisDatabaseFromUrl(url, `queue connection "${connectionName}" redis url`);
+  const db = parseInteger(overrides?.db ?? base?.db ?? dbFromUrl, DEFAULT_REDIS_DB, `queue connection "${connectionName}" redis db`, {
+    minimum: 0
+  });
+  if (typeof clusters !== "undefined" && db !== 0) {
+    throw new Error(`[Holo Queue] queue connection "${connectionName}" cannot select redis.db=${db} in cluster mode; Redis Cluster only supports database 0.`);
+  }
+  return Object.freeze({
+    ...typeof url === "undefined" ? {} : { url },
+    ...typeof clusters === "undefined" ? {} : { clusters },
+    host: normalizeOptionalRedisString(overrides?.host) ?? base?.host ?? DEFAULT_REDIS_HOST,
+    port: parseInteger(overrides?.port ?? base?.port, DEFAULT_REDIS_PORT, `queue connection "${connectionName}" redis port`, {
+      minimum: 1
+    }),
+    password: normalizeOptionalRedisString(overrides?.password) ?? base?.password,
+    username: normalizeOptionalRedisString(overrides?.username) ?? base?.username,
+    db
+  });
+}
 function normalizeRedisConnection(name, config, redisConfig) {
   const explicitConnectionName = config.connection?.trim();
   const connectionName = explicitConnectionName || redisConfig?.default;
-  if (!connectionName) {
+  if (!connectionName && !config.redis) {
     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) {
+  if (!redisConfig && !config.redis) {
     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);
+  const resolvedRedisConnection = redisConfig && connectionName ? resolveSharedRedisConnection(redisConfig, connectionName) : void 0;
   return Object.freeze({
     name,
     driver: "redis",
-    connection: resolvedRedisConnection.name,
+    connection: resolvedRedisConnection?.name ?? connectionName ?? name,
     queue: normalizeQueueName(config.queue),
     retryAfter: parseInteger(config.retryAfter, DEFAULT_QUEUE_RETRY_AFTER, `queue connection "${name}" retryAfter`, {
       minimum: 0
@@ -169,15 +247,7 @@ function normalizeRedisConnection(name, config, redisConfig) {
     blockFor: parseInteger(config.blockFor, DEFAULT_QUEUE_BLOCK_FOR, `queue connection "${name}" blockFor`, {
       minimum: 0
     }),
-    redis: Object.freeze({
-      ...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
-    })
+    redis: normalizeRedisOptions(name, resolvedRedisConnection, config.redis)
   });
 }
 function normalizeDatabaseConnection(name, config) {
@@ -1200,6 +1270,17 @@ function resolveRetryDelaySeconds(definition, attempt) {
   }
   return backoff[Math.min(Math.max(attempt - 1, 0), backoff.length - 1)];
 }
+function normalizeHookError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+async function runWorkerHook(jobName, hookName, callback) {
+  try {
+    await callback();
+  } catch (error) {
+    const resolvedError = normalizeHookError(error);
+    console.warn(`[Holo Queue] ${hookName} hook failed for job "${jobName}": ${resolvedError.message}`);
+  }
+}
 async function runWithTimeout(callback, jobName, timeoutSeconds, onTimeout) {
   if (typeof timeoutSeconds === "undefined") {
     return await callback;
@@ -1258,10 +1339,14 @@ async function processReservedJob(driver, reserved, options) {
     );
     if (action === "release") {
       await driver.release(reserved, typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : void 0);
-      await options.onJobReleased?.({
-        ...event,
-        ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {}
-      });
+      if (options.onJobReleased) {
+        await runWorkerHook(envelope.name, "onJobReleased", async () => {
+          await options.onJobReleased?.({
+            ...event,
+            ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {}
+          });
+        });
+      }
       return {
         kind: "released",
         ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {}
@@ -1274,17 +1359,25 @@ async function processReservedJob(driver, reserved, options) {
       await queueRuntimeInternals.executeRegisteredQueueJobFailedHook(envelope, failure, {
         maxAttempts
       });
-      await options.onJobFailed?.({
-        ...event,
-        error: failure
-      });
+      if (options.onJobFailed) {
+        await runWorkerHook(envelope.name, "onJobFailed", async () => {
+          await options.onJobFailed?.({
+            ...event,
+            error: failure
+          });
+        });
+      }
       return {
         kind: "failed",
         error: failure
       };
     }
     await driver.acknowledge(reserved);
-    await options.onJobProcessed?.(event);
+    if (options.onJobProcessed) {
+      await runWorkerHook(envelope.name, "onJobProcessed", async () => {
+        await options.onJobProcessed?.(event);
+      });
+    }
     return { kind: "processed" };
   } catch (error) {
     const resolvedError = error instanceof Error ? error : new Error(String(error));
@@ -1295,10 +1388,14 @@ async function processReservedJob(driver, reserved, options) {
       await queueRuntimeInternals.executeRegisteredQueueJobFailedHook(envelope, failure, {
         maxAttempts
       });
-      await options.onJobFailed?.({
-        ...event,
-        error: failure
-      });
+      if (options.onJobFailed) {
+        await runWorkerHook(envelope.name, "onJobFailed", async () => {
+          await options.onJobFailed?.({
+            ...event,
+            error: failure
+          });
+        });
+      }
       return {
         kind: "failed",
         error: failure
@@ -1306,11 +1403,15 @@ async function processReservedJob(driver, reserved, options) {
     }
     if (action === "release") {
       await driver.release(reserved, typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : void 0);
-      await options.onJobReleased?.({
-        ...event,
-        ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {},
-        error: failure
-      });
+      if (options.onJobReleased) {
+        await runWorkerHook(envelope.name, "onJobReleased", async () => {
+          await options.onJobReleased?.({
+            ...event,
+            ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {},
+            error: failure
+          });
+        });
+      }
       return {
         kind: "released",
         ...typeof requestedReleaseDelay === "number" ? { delaySeconds: requestedReleaseDelay } : {},
@@ -1323,10 +1424,14 @@ async function processReservedJob(driver, reserved, options) {
       await queueRuntimeInternals.executeRegisteredQueueJobFailedHook(envelope, failure, {
         maxAttempts
       });
-      await options.onJobFailed?.({
-        ...event,
-        error: failure
-      });
+      if (options.onJobFailed) {
+        await runWorkerHook(envelope.name, "onJobFailed", async () => {
+          await options.onJobFailed?.({
+            ...event,
+            error: failure
+          });
+        });
+      }
       return {
         kind: "failed",
         error: failure
@@ -1334,11 +1439,15 @@ async function processReservedJob(driver, reserved, options) {
     }
     const delaySeconds = resolveRetryDelaySeconds(definition, event.attempt);
     await driver.release(reserved, typeof delaySeconds === "number" ? { delaySeconds } : void 0);
-    await options.onJobReleased?.({
-      ...event,
-      ...typeof delaySeconds === "number" ? { delaySeconds } : {},
-      error: failure
-    });
+    if (options.onJobReleased) {
+      await runWorkerHook(envelope.name, "onJobReleased", async () => {
+        await options.onJobReleased?.({
+          ...event,
+          ...typeof delaySeconds === "number" ? { delaySeconds } : {},
+          error: failure
+        });
+      });
+    }
     return {
       kind: "released",
       ...typeof delaySeconds === "number" ? { delaySeconds } : {},
@@ -1464,6 +1573,7 @@ var queueWorkerInternals = {
   resolveRetryDelaySeconds,
   resolveWorkerStopReason,
   runWithTimeout,
+  runWorkerHook,
   sleep
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/queue",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Holo-JS Framework - queue contracts and config helpers",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "test": "vitest --run"
   },
   "peerDependencies": {
-    "@holo-js/queue-redis": "^0.1.4"
+    "@holo-js/queue-redis": "^0.1.5"
   },
   "peerDependenciesMeta": {
     "@holo-js/queue-redis": {
@@ -31,10 +31,10 @@
     }
   },
   "devDependencies": {
-    "@holo-js/queue-redis": "workspace:*",
+    "@holo-js/queue-redis": "^0.1.5",
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.5"
   }
 }