groupmq-plus 1.1.1 → 1.1.3

package/dist/index.d.cts

@@ -37,6 +37,7 @@ declare class Job<T = any> {
   readonly timestamp: number;
   readonly orderMs?: number;
   readonly status: Status$1 | 'unknown';
+  readonly parentId?: string;
   constructor(args: {
     queue: Queue<T>;
     id: string;
@@ -56,6 +57,7 @@ declare class Job<T = any> {
     timestamp: number;
     orderMs?: number;
     status?: Status$1 | 'unknown';
+    parentId?: string;
   });
   getState(): Promise<Status$1 | 'stuck' | 'waiting-children' | 'prioritized' | 'unknown'>;
   toJSON(): {
@@ -89,6 +91,26 @@ declare class Job<T = any> {
    * @param timeoutMs Optional timeout in milliseconds (0 = no timeout)
    */
   waitUntilFinished(timeoutMs?: number): Promise<unknown>;
+  /**
+   * Get all child jobs of this job (if it's a parent in a flow).
+   * @returns Array of child Job instances
+   */
+  getChildren(): Promise<Job<any>[]>;
+  /**
+   * Get the return values of all child jobs in a flow.
+   * @returns Object mapping child job IDs to their return values
+   */
+  getChildrenValues(): Promise<Record<string, any>>;
+  /**
+   * Get the number of remaining child jobs that haven't completed yet.
+   * @returns Number of remaining dependencies, or null if not a parent job
+   */
+  getDependenciesCount(): Promise<number | null>;
+  /**
+   * Get the parent job of this job (if it's a child in a flow).
+   * @returns Parent Job instance, or undefined if no parent or parent was deleted
+   */
+  getParent(): Promise<Job<any> | undefined>;
   static fromReserved<T = any>(queue: Queue<T>, reserved: ReservedJob<T>, meta?: {
     processedOn?: number;
     finishedOn?: number;
@@ -537,6 +559,18 @@ declare class Queue<T = any> {
    * @returns An object mapping child job IDs to their results
    */
   getFlowResults(parentId: string): Promise<Record<string, any>>;
+  /**
+   * Gets all child job IDs for a parent job in a flow.
+   * @param parentId The ID of the parent job
+   * @returns An array of child job IDs
+   */
+  getFlowChildrenIds(parentId: string): Promise<string[]>;
+  /**
+   * Gets all child jobs for a parent job in a flow.
+   * @param parentId The ID of the parent job
+   * @returns An array of Job instances for all children
+   */
+  getFlowChildren(parentId: string): Promise<Job<any>[]>;
   private addSingle;
   private flushBatch;
   reserve(): Promise<ReservedJob<T> | null>;
@@ -967,10 +1001,10 @@ type WorkerOptions<T> = {
   name?: string;
   /**
    * The function that processes jobs. Must be async and handle job failures gracefully.
-   * @param job The reserved job to process
+   * @param job The Job instance to process, with access to all Job methods
    * @returns Promise that resolves when job is complete
    */
-  handler: (job: ReservedJob<T>) => Promise<unknown>;
+  handler: (job: Job<T>) => Promise<unknown>;
   /**
    * Heartbeat interval in milliseconds to keep jobs alive during processing.
    * Prevents jobs from timing out during long-running operations.
@@ -987,9 +1021,9 @@ type WorkerOptions<T> = {
   /**
    * Error handler called when job processing fails or worker encounters errors
    * @param err The error that occurred
-   * @param job The job that failed (if applicable)
+   * @param job The Job instance that failed (if applicable)
    */
-  onError?: (err: unknown, job?: ReservedJob<T>) => void;
+  onError?: (err: unknown, job?: Job<T>) => void;
   /**
    * Maximum number of retry attempts for failed jobs at the worker level.
    * This overrides the queue's default maxAttempts setting.
@@ -1256,14 +1290,14 @@ declare class _Worker<T = any> extends TypedEventEmitter<WorkerEvents<T>> {
    * For concurrency > 1, returns the oldest job in progress
    */
   getCurrentJob(): {
-    job: ReservedJob<T>;
+    job: Job<T>;
     processingTimeMs: number;
   } | null;
   /**
    * Get information about all currently processing jobs
    */
   getCurrentJobs(): Array<{
-    job: ReservedJob<T>;
+    job: Job<T>;
     processingTimeMs: number;
   }>;
   /**
@@ -1315,5 +1349,127 @@ declare function getWorkersStatus<T = any>(workers: Worker<T>[]): {
   }>;
 };
 //#endregion
-export { AddOptions, BackoffStrategy, BullBoardGroupMQAdapter, FlowJob, FlowOptions, GroupMQBullBoardAdapterOptions, Job, Queue, QueueOptions, RepeatOptions, ReservedJob, UnrecoverableError, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
+//#region src/strategies/priority-strategy.d.ts
+type GroupConfig = {
+  priority: number;
+  concurrency: number;
+};
+/**
+ * 自定义优先级计算函数
+ * @param groupId 组 ID
+ * @param config 从 Redis 读取的组配置
+ * @returns 优先级数值（数字越大优先级越高）
+ */
+type OnGetPriority = (groupId: string, config: GroupConfig) => number | Promise<number>;
+/**
+ * 严格优先级算法
+ * 总是选择优先级最高的组，可能导致低优先级组饥饿
+ */
+type StrictAlgorithmConfig = {
+  type: 'strict';
+};
+/**
+ * 加权随机算法（默认）
+ * 根据优先级计算概率选择，确保低优先级组也有机会被执行
+ */
+type WeightedRandomAlgorithmConfig = {
+  type: 'weighted-random';
+  /**
+   * 最低优先级组的保底权重比例，默认 0.1（10%）
+   * 例如：VIP 优先级 100，普通用户优先级 1
+   * 普通用户的权重会被提升到 100 * 0.1 = 10，而不是 1
+   * 这样普通用户大约有 10/(100+10) ≈ 9% 的概率被选中
+   */
+  minWeightRatio?: number;
+};
+/**
+ * 时间衰减算法
+ * 等待时间越长，优先级加成越高，确保所有任务最终都会被执行
+ */
+type AgingAlgorithmConfig = {
+  type: 'aging';
+  /**
+   * 每等待多少毫秒增加 1 点优先级，默认 60000（1分钟）
+   * 例如：VIP 优先级 100，普通用户优先级 1
+   * 普通用户等待 100 分钟后，优先级变为 1 + 100 = 101，超过 VIP
+   */
+  intervalMs?: number;
+};
+/**
+ * 算法配置类型
+ */
+type AlgorithmConfig = StrictAlgorithmConfig | WeightedRandomAlgorithmConfig | AgingAlgorithmConfig;
+interface PriorityStrategyOptions {
+  /**
+   * 调度算法配置，默认 { type: 'weighted-random' }
+   *
+   * @example
+   * // 严格优先级（VIP 绝对优先）
+   * algorithm: { type: 'strict' }
+   *
+   * // 加权随机（默认，平衡公平性）
+   * algorithm: { type: 'weighted-random', minWeightRatio: 0.1 }
+   *
+   * // 时间衰减（确保无饥饿）
+   * algorithm: { type: 'aging', intervalMs: 60000 }
+   */
+  algorithm?: AlgorithmConfig;
+  /** 默认优先级（未配置的组使用此值），默认 1 */
+  defaultPriority?: number;
+  /** 优先级缓存 TTL（毫秒），默认 5000ms。设为 0 禁用缓存 */
+  cacheTtlMs?: number;
+  /**
+   * 自定义优先级计算函数
+   * 如果提供，将使用此函数计算优先级，否则直接使用 config.priority
+   *
+   * @example
+   * // 根据 VIP 等级计算优先级
+   * onGetPriority: (groupId, config) => {
+   *   if (groupId.startsWith('vip:')) return config.priority * 10;
+   *   return config.priority;
+   * }
+   */
+  onGetPriority?: OnGetPriority;
+}
+declare class PriorityStrategy implements DispatchStrategy {
+  /** 本地缓存：groupId -> { priority, expiresAt } */
+  private cache;
+  /** 手动覆盖的优先级（优先级最高） */
+  private overrides;
+  private algorithmConfig;
+  private defaultPriority;
+  private cacheTtlMs;
+  private onGetPriority?;
+  constructor(options?: PriorityStrategyOptions);
+  /**
+   * 手动覆盖某个组的优先级（优先级高于 Redis 配置和 getPriority）
+   * 主要用于测试或临时调整
+   */
+  setPriority(groupId: string, priority: number): void;
+  /**
+   * 清除手动覆盖，恢复使用 Redis 配置或 getPriority
+   */
+  clearPriority(groupId: string): void;
+  /**
+   * 获取组的基础优先级
+   * 优先级来源顺序：overrides > cache > onGetPriority(config) 或 config.priority
+   */
+  private resolvePriority;
+  /**
+   * 严格优先级算法：总是返回优先级最高的组
+   */
+  private selectByStrict;
+  /**
+   * 加权随机算法：根据优先级计算概率选择
+   * 使用 minWeightRatio 确保低优先级组也有机会
+   */
+  private selectByWeightedRandom;
+  /**
+   * 时间衰减算法：等待时间越长，优先级加成越高
+   */
+  private selectByAging;
+  getNextGroup(queue: Queue<any>): Promise<string | null>;
+}
+//#endregion
+export { AddOptions, AgingAlgorithmConfig, AlgorithmConfig, BackoffStrategy, BullBoardGroupMQAdapter, DispatchStrategy, FlowJob, FlowOptions, GroupMQBullBoardAdapterOptions, Job, OnGetPriority, PriorityStrategy, PriorityStrategyOptions, Queue, QueueOptions, RepeatOptions, ReservedJob, StrictAlgorithmConfig, UnrecoverableError, WeightedRandomAlgorithmConfig, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -37,6 +37,7 @@ declare class Job<T = any> {
   readonly timestamp: number;
   readonly orderMs?: number;
   readonly status: Status$1 | 'unknown';
+  readonly parentId?: string;
   constructor(args: {
     queue: Queue<T>;
     id: string;
@@ -56,6 +57,7 @@ declare class Job<T = any> {
     timestamp: number;
     orderMs?: number;
     status?: Status$1 | 'unknown';
+    parentId?: string;
   });
   getState(): Promise<Status$1 | 'stuck' | 'waiting-children' | 'prioritized' | 'unknown'>;
   toJSON(): {
@@ -89,6 +91,26 @@ declare class Job<T = any> {
    * @param timeoutMs Optional timeout in milliseconds (0 = no timeout)
    */
   waitUntilFinished(timeoutMs?: number): Promise<unknown>;
+  /**
+   * Get all child jobs of this job (if it's a parent in a flow).
+   * @returns Array of child Job instances
+   */
+  getChildren(): Promise<Job<any>[]>;
+  /**
+   * Get the return values of all child jobs in a flow.
+   * @returns Object mapping child job IDs to their return values
+   */
+  getChildrenValues(): Promise<Record<string, any>>;
+  /**
+   * Get the number of remaining child jobs that haven't completed yet.
+   * @returns Number of remaining dependencies, or null if not a parent job
+   */
+  getDependenciesCount(): Promise<number | null>;
+  /**
+   * Get the parent job of this job (if it's a child in a flow).
+   * @returns Parent Job instance, or undefined if no parent or parent was deleted
+   */
+  getParent(): Promise<Job<any> | undefined>;
   static fromReserved<T = any>(queue: Queue<T>, reserved: ReservedJob<T>, meta?: {
     processedOn?: number;
     finishedOn?: number;
@@ -537,6 +559,18 @@ declare class Queue<T = any> {
    * @returns An object mapping child job IDs to their results
    */
   getFlowResults(parentId: string): Promise<Record<string, any>>;
+  /**
+   * Gets all child job IDs for a parent job in a flow.
+   * @param parentId The ID of the parent job
+   * @returns An array of child job IDs
+   */
+  getFlowChildrenIds(parentId: string): Promise<string[]>;
+  /**
+   * Gets all child jobs for a parent job in a flow.
+   * @param parentId The ID of the parent job
+   * @returns An array of Job instances for all children
+   */
+  getFlowChildren(parentId: string): Promise<Job<any>[]>;
   private addSingle;
   private flushBatch;
   reserve(): Promise<ReservedJob<T> | null>;
@@ -967,10 +1001,10 @@ type WorkerOptions<T> = {
   name?: string;
   /**
    * The function that processes jobs. Must be async and handle job failures gracefully.
-   * @param job The reserved job to process
+   * @param job The Job instance to process, with access to all Job methods
    * @returns Promise that resolves when job is complete
    */
-  handler: (job: ReservedJob<T>) => Promise<unknown>;
+  handler: (job: Job<T>) => Promise<unknown>;
   /**
    * Heartbeat interval in milliseconds to keep jobs alive during processing.
    * Prevents jobs from timing out during long-running operations.
@@ -987,9 +1021,9 @@ type WorkerOptions<T> = {
   /**
    * Error handler called when job processing fails or worker encounters errors
    * @param err The error that occurred
-   * @param job The job that failed (if applicable)
+   * @param job The Job instance that failed (if applicable)
    */
-  onError?: (err: unknown, job?: ReservedJob<T>) => void;
+  onError?: (err: unknown, job?: Job<T>) => void;
   /**
    * Maximum number of retry attempts for failed jobs at the worker level.
    * This overrides the queue's default maxAttempts setting.
@@ -1256,14 +1290,14 @@ declare class _Worker<T = any> extends TypedEventEmitter<WorkerEvents<T>> {
    * For concurrency > 1, returns the oldest job in progress
    */
   getCurrentJob(): {
-    job: ReservedJob<T>;
+    job: Job<T>;
     processingTimeMs: number;
   } | null;
   /**
    * Get information about all currently processing jobs
    */
   getCurrentJobs(): Array<{
-    job: ReservedJob<T>;
+    job: Job<T>;
     processingTimeMs: number;
   }>;
   /**
@@ -1315,5 +1349,127 @@ declare function getWorkersStatus<T = any>(workers: Worker<T>[]): {
   }>;
 };
 //#endregion
-export { AddOptions, BackoffStrategy, BullBoardGroupMQAdapter, FlowJob, FlowOptions, GroupMQBullBoardAdapterOptions, Job, Queue, QueueOptions, RepeatOptions, ReservedJob, UnrecoverableError, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
+//#region src/strategies/priority-strategy.d.ts
+type GroupConfig = {
+  priority: number;
+  concurrency: number;
+};
+/**
+ * 自定义优先级计算函数
+ * @param groupId 组 ID
+ * @param config 从 Redis 读取的组配置
+ * @returns 优先级数值（数字越大优先级越高）
+ */
+type OnGetPriority = (groupId: string, config: GroupConfig) => number | Promise<number>;
+/**
+ * 严格优先级算法
+ * 总是选择优先级最高的组，可能导致低优先级组饥饿
+ */
+type StrictAlgorithmConfig = {
+  type: 'strict';
+};
+/**
+ * 加权随机算法（默认）
+ * 根据优先级计算概率选择，确保低优先级组也有机会被执行
+ */
+type WeightedRandomAlgorithmConfig = {
+  type: 'weighted-random';
+  /**
+   * 最低优先级组的保底权重比例，默认 0.1（10%）
+   * 例如：VIP 优先级 100，普通用户优先级 1
+   * 普通用户的权重会被提升到 100 * 0.1 = 10，而不是 1
+   * 这样普通用户大约有 10/(100+10) ≈ 9% 的概率被选中
+   */
+  minWeightRatio?: number;
+};
+/**
+ * 时间衰减算法
+ * 等待时间越长，优先级加成越高，确保所有任务最终都会被执行
+ */
+type AgingAlgorithmConfig = {
+  type: 'aging';
+  /**
+   * 每等待多少毫秒增加 1 点优先级，默认 60000（1分钟）
+   * 例如：VIP 优先级 100，普通用户优先级 1
+   * 普通用户等待 100 分钟后，优先级变为 1 + 100 = 101，超过 VIP
+   */
+  intervalMs?: number;
+};
+/**
+ * 算法配置类型
+ */
+type AlgorithmConfig = StrictAlgorithmConfig | WeightedRandomAlgorithmConfig | AgingAlgorithmConfig;
+interface PriorityStrategyOptions {
+  /**
+   * 调度算法配置，默认 { type: 'weighted-random' }
+   *
+   * @example
+   * // 严格优先级（VIP 绝对优先）
+   * algorithm: { type: 'strict' }
+   *
+   * // 加权随机（默认，平衡公平性）
+   * algorithm: { type: 'weighted-random', minWeightRatio: 0.1 }
+   *
+   * // 时间衰减（确保无饥饿）
+   * algorithm: { type: 'aging', intervalMs: 60000 }
+   */
+  algorithm?: AlgorithmConfig;
+  /** 默认优先级（未配置的组使用此值），默认 1 */
+  defaultPriority?: number;
+  /** 优先级缓存 TTL（毫秒），默认 5000ms。设为 0 禁用缓存 */
+  cacheTtlMs?: number;
+  /**
+   * 自定义优先级计算函数
+   * 如果提供，将使用此函数计算优先级，否则直接使用 config.priority
+   *
+   * @example
+   * // 根据 VIP 等级计算优先级
+   * onGetPriority: (groupId, config) => {
+   *   if (groupId.startsWith('vip:')) return config.priority * 10;
+   *   return config.priority;
+   * }
+   */
+  onGetPriority?: OnGetPriority;
+}
+declare class PriorityStrategy implements DispatchStrategy {
+  /** 本地缓存：groupId -> { priority, expiresAt } */
+  private cache;
+  /** 手动覆盖的优先级（优先级最高） */
+  private overrides;
+  private algorithmConfig;
+  private defaultPriority;
+  private cacheTtlMs;
+  private onGetPriority?;
+  constructor(options?: PriorityStrategyOptions);
+  /**
+   * 手动覆盖某个组的优先级（优先级高于 Redis 配置和 getPriority）
+   * 主要用于测试或临时调整
+   */
+  setPriority(groupId: string, priority: number): void;
+  /**
+   * 清除手动覆盖，恢复使用 Redis 配置或 getPriority
+   */
+  clearPriority(groupId: string): void;
+  /**
+   * 获取组的基础优先级
+   * 优先级来源顺序：overrides > cache > onGetPriority(config) 或 config.priority
+   */
+  private resolvePriority;
+  /**
+   * 严格优先级算法：总是返回优先级最高的组
+   */
+  private selectByStrict;
+  /**
+   * 加权随机算法：根据优先级计算概率选择
+   * 使用 minWeightRatio 确保低优先级组也有机会
+   */
+  private selectByWeightedRandom;
+  /**
+   * 时间衰减算法：等待时间越长，优先级加成越高
+   */
+  private selectByAging;
+  getNextGroup(queue: Queue<any>): Promise<string | null>;
+}
+//#endregion
+export { AddOptions, AgingAlgorithmConfig, AlgorithmConfig, BackoffStrategy, BullBoardGroupMQAdapter, DispatchStrategy, FlowJob, FlowOptions, GroupMQBullBoardAdapterOptions, Job, OnGetPriority, PriorityStrategy, PriorityStrategyOptions, Queue, QueueOptions, RepeatOptions, ReservedJob, StrictAlgorithmConfig, UnrecoverableError, WeightedRandomAlgorithmConfig, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
 //# sourceMappingURL=index.d.ts.map