@holo-js/queue 0.2.4 → 0.2.6

package/dist/index.d.ts

@@ -2,6 +2,16 @@ type QueueJsonPrimitive = string | number | boolean | null;
 type QueueJsonValue = QueueJsonPrimitive | readonly QueueJsonValue[] | {
     readonly [key: string]: QueueJsonValue;
 };
+type QueueJobDispatcher = <TPayload extends QueueJsonValue>(jobName: string, payload: TPayload) => QueuePendingDispatch<TPayload>;
+type QueueJobSyncDispatcher = <TPayload extends QueueJsonValue, TResult>(jobName: string, payload: TPayload) => Promise<TResult>;
+declare function setQueueJobDispatcher(dispatcher: QueueJobDispatcher): void;
+declare function setQueueJobSyncDispatcher(dispatcher: QueueJobSyncDispatcher): void;
+declare function setQueueJobDefinitionName(definition: object, name: string): void;
+declare function deleteQueueJobDefinitionName(name: string): void;
+declare function clearQueueJobDefinitionNames(): void;
+declare function resolveQueueJobDefinitionName(definition: object): string;
+declare function dispatchDefinedQueueJob<TPayload extends QueueJsonValue>(definition: object, payload: TPayload): QueuePendingDispatch<TPayload>;
+declare function dispatchDefinedQueueJobSync<TPayload extends QueueJsonValue, TResult>(definition: object, payload: TPayload): Promise<TResult>;
 declare function normalizeOptionalString(value: string | undefined, label: string): string | undefined;
 declare function normalizeOptionalInteger(value: number | undefined, label: string, options?: {
     minimum?: number;
@@ -34,6 +44,10 @@ interface QueueJobDefinition<TPayload extends QueueJsonValue = QueueJsonValue, T
     readonly onFailed?: QueueJobFailedHook<TPayload>;
     handle(payload: TPayload, context: QueueJobContext): Promise<TResult> | TResult;
 }
+interface DefinedQueueJobDefinition<TPayload extends QueueJsonValue = QueueJsonValue, TResult = unknown> extends QueueJobDefinition<TPayload, TResult> {
+    dispatch(payload: TPayload): QueuePendingDispatch<TPayload>;
+    dispatchSync(payload: TPayload): Promise<TResult>;
+}
 interface QueueJobEnvelope<TPayload extends QueueJsonValue = QueueJsonValue> {
     readonly id: string;
     readonly name: string;
@@ -215,8 +229,8 @@ interface QueueFailedJobStore {
     flushFailedJobs(): Promise<number>;
 }
 declare function isQueueJobDefinition(value: unknown): value is QueueJobDefinition;
-declare function normalizeQueueJobDefinition<TJob extends QueueJobDefinition>(job: TJob): TJob;
-declare function defineJob<TJob extends QueueJobDefinition>(job: TJob): TJob;
+declare function normalizeQueueJobDefinition<TPayload extends QueueJsonValue, TResult, TJob extends QueueJobDefinition<TPayload, TResult>>(job: TJob): TJob;
+declare function defineJob<TPayload extends QueueJsonValue, TResult = unknown>(job: QueueJobDefinition<TPayload, TResult>): DefinedQueueJobDefinition<TPayload, TResult>;
 interface QueueFailedStoreConfig {
     readonly driver?: 'database';
     readonly connection?: string;
@@ -325,11 +339,19 @@ interface NormalizedHoloQueueConfig {
     readonly connections: Readonly<Record<string, NormalizedQueueConnectionConfig>>;
 }
 declare const queueJobInternals: {
+    clearQueueJobDefinitionNames: typeof clearQueueJobDefinitionNames;
+    deleteQueueJobDefinitionName: typeof deleteQueueJobDefinitionName;
+    dispatchDefinedQueueJob: typeof dispatchDefinedQueueJob;
+    dispatchDefinedQueueJobSync: typeof dispatchDefinedQueueJobSync;
     normalizeQueueJobDefinition: typeof normalizeQueueJobDefinition;
     normalizeBackoff: typeof normalizeBackoff;
     normalizeOptionalHook: typeof normalizeOptionalHook;
     normalizeOptionalInteger: typeof normalizeOptionalInteger;
     normalizeOptionalString: typeof normalizeOptionalString;
+    resolveQueueJobDefinitionName: typeof resolveQueueJobDefinitionName;
+    setQueueJobDefinitionName: typeof setQueueJobDefinitionName;
+    setQueueJobDispatcher: typeof setQueueJobDispatcher;
+    setQueueJobSyncDispatcher: typeof setQueueJobSyncDispatcher;
 };
 
 declare const DEFAULT_QUEUE_CONNECTION = "sync";
@@ -607,4 +629,4 @@ declare const queueWorkerInternals: {
 
 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 };
+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 DefinedQueueJobDefinition, 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

@@ -1,4 +1,132 @@
 // src/contracts.ts
+function getQueueJobDispatcher() {
+  return globalThis.__holoQueueJobDispatcher__;
+}
+function setQueueJobDispatcher(dispatcher) {
+  const runtime = globalThis;
+  runtime.__holoQueueJobDispatcher__ = dispatcher;
+}
+function getQueueJobSyncDispatcher() {
+  return globalThis.__holoQueueJobSyncDispatcher__;
+}
+function setQueueJobSyncDispatcher(dispatcher) {
+  const runtime = globalThis;
+  runtime.__holoQueueJobSyncDispatcher__ = dispatcher;
+}
+function getQueueJobDefinitionNames() {
+  const runtime = globalThis;
+  runtime.__holoQueueJobDefinitionNames__ ??= /* @__PURE__ */ new WeakMap();
+  return runtime.__holoQueueJobDefinitionNames__;
+}
+function getQueueJobDefinitionFingerprints() {
+  const runtime = globalThis;
+  runtime.__holoQueueJobDefinitionFingerprints__ ??= /* @__PURE__ */ new Map();
+  return runtime.__holoQueueJobDefinitionFingerprints__;
+}
+function getQueueJobDefinitionOptionFingerprints() {
+  const runtime = globalThis;
+  runtime.__holoQueueJobDefinitionOptionFingerprints__ ??= /* @__PURE__ */ new Map();
+  return runtime.__holoQueueJobDefinitionOptionFingerprints__;
+}
+function createQueueJobDefinitionOptionsFingerprint(definition) {
+  return JSON.stringify({
+    connection: definition.connection,
+    queue: definition.queue,
+    tries: definition.tries,
+    backoff: definition.backoff,
+    timeout: definition.timeout
+  });
+}
+function getQueueJobDefinitionFingerprint(definition) {
+  if (!isQueueJobDefinition(definition)) {
+    return void 0;
+  }
+  return JSON.stringify({
+    options: createQueueJobDefinitionOptionsFingerprint(definition),
+    handle: definition.handle.toString()
+  });
+}
+function addQueueJobDefinitionNameByFingerprint(fingerprints, fingerprint, name) {
+  const names = fingerprints.get(fingerprint) ?? /* @__PURE__ */ new Set();
+  names.add(name);
+  fingerprints.set(fingerprint, names);
+}
+function setQueueJobDefinitionName(definition, name) {
+  getQueueJobDefinitionNames().set(definition, name);
+  if (!isQueueJobDefinition(definition)) {
+    return;
+  }
+  addQueueJobDefinitionNameByFingerprint(
+    getQueueJobDefinitionFingerprints(),
+    getQueueJobDefinitionFingerprint(definition),
+    name
+  );
+  addQueueJobDefinitionNameByFingerprint(
+    getQueueJobDefinitionOptionFingerprints(),
+    createQueueJobDefinitionOptionsFingerprint(definition),
+    name
+  );
+}
+function deleteQueueJobDefinitionName(name) {
+  for (const fingerprints of [
+    getQueueJobDefinitionFingerprints(),
+    getQueueJobDefinitionOptionFingerprints()
+  ]) {
+    for (const [fingerprint, names] of fingerprints) {
+      names.delete(name);
+      if (names.size === 0) {
+        fingerprints.delete(fingerprint);
+      }
+    }
+  }
+}
+function clearQueueJobDefinitionNames() {
+  getQueueJobDefinitionFingerprints().clear();
+  getQueueJobDefinitionOptionFingerprints().clear();
+}
+function resolveSingleQueueJobDefinitionFingerprintName(names) {
+  if (!names) {
+    return void 0;
+  }
+  if (names.size === 1) {
+    return [...names][0];
+  }
+  throw new Error("[Holo Queue] Job definition dispatch is ambiguous because multiple registered jobs match the same definition.");
+}
+function resolveQueueJobDefinitionName(definition) {
+  const name = getQueueJobDefinitionNames().get(definition);
+  if (name) {
+    return name;
+  }
+  const fingerprint = getQueueJobDefinitionFingerprint(definition);
+  const fingerprintName = fingerprint ? resolveSingleQueueJobDefinitionFingerprintName(getQueueJobDefinitionFingerprints().get(fingerprint)) : void 0;
+  if (fingerprintName) {
+    return fingerprintName;
+  }
+  if (isQueueJobDefinition(definition)) {
+    const optionFingerprintName = resolveSingleQueueJobDefinitionFingerprintName(
+      getQueueJobDefinitionOptionFingerprints().get(createQueueJobDefinitionOptionsFingerprint(definition))
+    );
+    if (optionFingerprintName) {
+      return optionFingerprintName;
+    }
+  }
+  throw new Error("[Holo Queue] Job definitions cannot dispatch before the job is registered.");
+}
+function dispatchDefinedQueueJob(definition, payload) {
+  const dispatcher = getQueueJobDispatcher();
+  if (!dispatcher) {
+    throw new Error("[Holo Queue] Job definitions cannot dispatch before the queue runtime is loaded.");
+  }
+  return dispatcher(resolveQueueJobDefinitionName(definition), payload);
+}
+function dispatchDefinedQueueJobSync(definition, payload) {
+  const dispatcher = getQueueJobSyncDispatcher();
+  if (!dispatcher) {
+    throw new Error("[Holo Queue] Job definitions cannot dispatch before the queue runtime is loaded.");
+  }
+  return dispatcher(resolveQueueJobDefinitionName(definition), payload);
+}
 function normalizeOptionalString(value, label) {
   if (typeof value === "undefined") {
     return void 0;
@@ -70,14 +198,35 @@ function normalizeQueueJobDefinition(job) {
   };
 }
 function defineJob(job) {
-  return Object.freeze(normalizeQueueJobDefinition(job));
+  const normalized = normalizeQueueJobDefinition(job);
+  Object.defineProperty(normalized, "dispatch", {
+    value(payload) {
+      return dispatchDefinedQueueJob(normalized, payload);
+    },
+    enumerable: false
+  });
+  Object.defineProperty(normalized, "dispatchSync", {
+    value(payload) {
+      return dispatchDefinedQueueJobSync(normalized, payload);
+    },
+    enumerable: false
+  });
+  return Object.freeze(normalized);
 }
 var queueJobInternals = {
+  clearQueueJobDefinitionNames,
+  deleteQueueJobDefinitionName,
+  dispatchDefinedQueueJob,
+  dispatchDefinedQueueJobSync,
   normalizeQueueJobDefinition,
   normalizeBackoff,
   normalizeOptionalHook,
   normalizeOptionalInteger,
-  normalizeOptionalString
+  normalizeOptionalString,
+  resolveQueueJobDefinitionName,
+  setQueueJobDefinitionName,
+  setQueueJobDispatcher,
+  setQueueJobSyncDispatcher
 };
 
 // src/config.ts
@@ -366,6 +515,8 @@ function registerQueueJob(definition, options = {}) {
       ...normalizedDefinition
     })
   });
+  queueJobInternals.setQueueJobDefinitionName(definition, name);
+  queueJobInternals.setQueueJobDefinitionName(normalizedDefinition, name);
   registry.set(name, entry);
   return entry;
 }
@@ -379,10 +530,15 @@ function listRegisteredQueueJobs() {
   return Object.freeze([...getQueueRegistryState().jobs.values()].sort((left, right) => left.name.localeCompare(right.name)));
 }
 function unregisterQueueJob(name) {
-  return getQueueRegistryState().jobs.delete(name);
+  const deleted = getQueueRegistryState().jobs.delete(name);
+  if (deleted) {
+    queueJobInternals.deleteQueueJobDefinitionName(name);
+  }
+  return deleted;
 }
 function resetQueueRegistry() {
   getQueueRegistryState().jobs.clear();
+  queueJobInternals.clearQueueJobDefinitionNames();
 }
 var queueRegistryInternals = {
   deriveJobNameFromSourcePath
@@ -1049,6 +1205,8 @@ async function dispatchSync(jobName, payload, options = {}) {
 function dispatch(jobName, payload, options = {}) {
   return new PendingQueueDispatch(jobName, payload, options);
 }
+queueJobInternals.setQueueJobDispatcher(dispatch);
+queueJobInternals.setQueueJobSyncDispatcher(dispatchSync);
 var Queue = {
   connection(name) {
     return createQueueConnection(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/queue",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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.2.4"
+    "@holo-js/queue-redis": "^0.2.6"
   },
   "peerDependenciesMeta": {
     "@holo-js/queue-redis": {
@@ -31,7 +31,7 @@
     }
   },
   "devDependencies": {
-    "@holo-js/queue-redis": "^0.2.4",
+    "@holo-js/queue-redis": "^0.2.6",
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",