groupmq-plus 1.3.1 → 1.3.2

package/dist/index.d.mts

@@ -140,6 +140,28 @@ interface LoggerInterface {
 }
 //#endregion
 //#region src/queue.d.ts
+/**
+ * Group 的配置信息
+ * concurrency 是核心字段，影响 Lua 脚本行为
+ * 其他字段为策略层使用的元数据（如 priority, weight 等）
+ */
+type GroupConfig = {
+  /** 并发限制 (Core Engine 使用) */
+  concurrency?: number;
+  /** 允许存储任意元数据供 Strategy 使用 */
+  [key: string]: any;
+};
+/**
+ * 组配置选项（用于 queue.add 的 groupConfig 参数）
+ */
+type GroupOptions = {
+  /** 组优先级 (被 PriorityStrategy 使用) */
+  priority?: number;
+  /** 并发限制 (被 Core 使用) */
+  concurrency?: number;
+  /** 允许传入任意其他策略需要的元数据 */
+  [key: string]: any;
+};
 /**
  * Flow child result type with explicit status
  */
@@ -148,6 +170,17 @@ type FlowChildResult<R = any> = {
   status: 'completed' | 'failed';
   result: R;
 };
+/**
+ * Reserve result type with explicit status distinction between success, limit exceeded, and empty
+ */
+type ReserveResult<T = any> = {
+  status: 'success';
+  job: ReservedJob<T>;
+} | {
+  status: 'limit_exceeded';
+} | {
+  status: 'empty';
+};
 /**
  * Options for configuring a GroupMQ queue
  */
@@ -504,6 +537,19 @@ type AddOptions<T> = {
    * - Deduplication: Prevent duplicate jobs from being created
    */
   jobId?: string;
+  /**
+   * (新增) 设置或更新组的配置
+   * 这些配置将随任务一起原子性写入 Redis
+   *
+   * @example { priority: 10 } // 设置组优先级
+   * @example { concurrency: 5 } // 设置组并发限制
+   * @example { priority: 10, concurrency: 3 } // 同时设置多个配置
+   *
+   * **When to use:**
+   * - 入队即配置：在添加任务时同时设置组配置
+   * - 动态调整：根据任务特性动态调整组优先级
+   */
+  groupConfig?: GroupOptions;
 };
 type ReservedJob<T = any> = {
   id: string;
@@ -543,6 +589,27 @@ declare class Queue<T = any> {
   private batchBuffer;
   private batchTimer?;
   private flushing;
+  readonly groups: {
+    /**
+     * 设置组的配置和元数据
+     * 我们将使用 Hash 存储这些配置: groupmq:{ns}:config:{groupId}
+     * @param groupId 组 ID
+     * @param config 配置对象。concurrency 会影响核心调度，其他字段供 Strategy 使用。
+     */
+    setConfig: (groupId: string, config: GroupOptions) => Promise<void>;
+    /** 获取当前配置 */
+    getConfig: (groupId: string) => Promise<GroupOptions>;
+    /**
+     * 设置指定组的并发上限
+     * @param groupId 组 ID
+     * @param limit 并发数 (必须 >= 1)
+     */
+    setConcurrency: (groupId: string, limit: number) => Promise<void>;
+    /**
+     * 获取指定组的并发上限
+     */
+    getConcurrency: (groupId: string) => Promise<number>;
+  };
   constructor(opts: QueueOptions);
   get redis(): Redis;
   get namespace(): string;
@@ -741,37 +808,16 @@ declare class Queue<T = any> {
   reserveBlocking(timeoutSec?: number, blockUntil?: number, blockingClient?: ioredis0.default): Promise<ReservedJob<T> | null>;
   /**
    * Reserve a job from a specific group atomically (eliminates race conditions)
+   * Returns an explicit status to distinguish between success, limit exceeded, and empty states
    * @param groupId - The group to reserve from
    */
-  reserveAtomic(groupId: string): Promise<ReservedJob<T> | null>;
+  reserveAtomic(groupId: string): Promise<ReserveResult<T>>;
   /**
    * 获取处于 Ready 状态的 Group 列表
    * @param start
    * @param end
    */
   getReadyGroups(start?: number, end?: number): Promise<string[]>;
-  /**
-   * 设置组的元数据 (优先级/并发度)
-   * 我们将使用 Hash 存储这些配置: groupmq:{ns}:config:{groupId}
-   */
-  setGroupConfig(groupId: string, config: {
-    priority?: number;
-    concurrency?: number;
-  }): Promise<void>;
-  getGroupConfig(groupId: string): Promise<{
-    priority: number;
-    concurrency: number;
-  }>;
-  /**
-   * 设置指定组的并发上限
-   * @param groupId 组 ID
-   * @param limit 并发数 (必须 >= 1)
-   */
-  setGroupConcurrency(groupId: string, limit: number): Promise<void>;
-  /**
-   * 获取指定组的并发上限
-   */
-  getGroupConcurrency(groupId: string): Promise<number>;
   /**
    * 获取组内最老任务的入队时间戳
    * 用于 PriorityStrategy 的 aging 算法
@@ -971,10 +1017,29 @@ declare class BullBoardGroupMQAdapter<T = any> extends BaseAdapter {
 //#region src/strategies/dispatch-strategy.d.ts
 interface DispatchStrategy {
   /**
-   * 决定下一个应该处理的 Group ID。
-   * 如果返回 null，表示根据策略当前没有合适的 Group 需要处理（或者队列为空）。
+   * 尝试获取下一个可执行的任务
+   *
+   * 策略内部负责完整的获取流程：
+   * 1. 批量获取处于 Ready 状态的 Group
+   * 2. 应用优先级排序逻辑
+   * 3. 循环尝试从排序后的 Group 中获取任务
+   * 4. 处理"并发已满 (E_LIMIT)"和"队列为空"两种失败状态
+   * 5. 返回第一个成功获取的任务，或 null（无可用任务）
+   *
+   * 此接口设计体现了 IoC（控制反转）原则：
+   * - Worker 只需简单调用此方法，无需关心具体选择逻辑
+   * - Strategy 掌控"如何获取"的全过程
+   * - 不同的 Strategy 可以实现不同的分派算法（优先级、加权、衰减等）
+   *
+   * @param queue - Queue 实例，用于获取 Group 和尝试保留任务
+   * @returns 成功获取的任务，或 null（暂无可用任务）
+   */
+  acquireJob(queue: Queue<any>): Promise<ReservedJob<any> | null>;
+  /**
+   * 当 acquireJob 返回 null (无任务) 时，建议 Worker 休眠的时间 (毫秒)
+   * 如果未定义，Worker 将使用默认值
    */
-  getNextGroup(queue: Queue<any>): Promise<string | null>;
+  readonly idleInterval: number;
 }
 //#endregion
 //#region src/worker.d.ts
@@ -1199,12 +1264,6 @@ type WorkerOptions<T> = {
    * 转而使用策略轮询模式。
    */
   strategy?: DispatchStrategy;
-  /**
-   * 策略模式下的轮询间隔 (ms)
-   * 当使用 Strategy 时，我们无法使用阻塞读取 (BZPOPMIN)，必须退化为短轮询
-   * @default 50
-   */
-  strategyPollInterval?: number;
   /**
    * 是否自动启动 Worker
    * 设置为 false 时，需要手动调用 run() 方法启动 Worker
@@ -1376,126 +1435,113 @@ declare function getWorkersStatus<T = any>(workers: Worker<T>[]): {
 };
 //#endregion
 //#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% 的概率被选中
-   */
+  /** 最低权重比例，默认 0.1 */
   minWeightRatio?: number;
 };
-/**
- * 时间衰减算法
- * 等待时间越长，优先级加成越高，确保所有任务最终都会被执行
- */
+/** 时间衰减算法：等待时间越长，优先级加成越高 */
 type AgingAlgorithmConfig = {
   type: 'aging';
-  /**
-   * 每等待多少毫秒增加 1 点优先级，默认 60000（1分钟）
-   * 例如：VIP 优先级 100，普通用户优先级 1
-   * 普通用户等待 100 分钟后，优先级变为 1 + 100 = 101，超过 VIP
-   */
+  /** 每增加1点优先级需要的等待毫秒数，默认 60000 */
   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 }
+   * 调度算法类型
+   * @default { type: 'weighted-random' }
    */
   algorithm?: AlgorithmConfig;
-  /** 默认优先级（未配置的组使用此值），默认 1 */
+  /**
+   * 默认优先级（当无法从 Redis 获取配置时的回退值）
+   * @default 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;
-   * }
+   * 当没有任务时，Worker 的轮询间隔 (ms)
+   * @default 50
    */
-  onGetPriority?: OnGetPriority;
+  pollInterval?: number;
 }
+/**
+ * 基于优先级的调度策略
+ *
+ * 此策略负责根据 Group 的优先级决定处理顺序。
+ * 它支持多种排序算法（严格优先、加权随机、时间衰减），
+ * 并实现了"快速试错"（Fallthrough）机制以应对并发限制。
+ *
+ * 性能特性：
+ * - 使用 Lua 脚本 (Deep Scan) 一次性获取所有候选组及其配置。
+ * - 零网络往返延迟 (N+1 free)。
+ * - 无本地缓存，实时响应 Redis 配置变更。
+ */
 declare class PriorityStrategy implements DispatchStrategy {
-  /** 本地缓存：groupId -> { priority, expiresAt } */
-  private cache;
-  /** 手动覆盖的优先级（优先级最高） */
-  private overrides;
   private algorithmConfig;
   private defaultPriority;
-  private cacheTtlMs;
-  private onGetPriority?;
+  readonly idleInterval: number;
   constructor(options?: PriorityStrategyOptions);
   /**
-   * 手动覆盖某个组的优先级（优先级高于 Redis 配置和 getPriority）
-   * 主要用于测试或临时调整
+   * 获取下一个可执行的任务
+   */
+  acquireJob(queue: Queue<any>): Promise<ReservedJob<any> | null>;
+  /**
+   * 根据算法类型分发排序逻辑
    */
-  setPriority(groupId: string, priority: number): void;
+  private sortGroupsByPriority;
   /**
-   * 清除手动覆盖，恢复使用 Redis 配置或 getPriority
+   * 严格优先级排序：Priority 大的排前面
    */
-  clearPriority(groupId: string): void;
+  private sortByStrict;
   /**
-   * 获取组的基础优先级
-   * 优先级来源顺序：overrides > cache > onGetPriority(config) 或 config.priority
+   * 加权随机排序：Priority 越高，排在前面的概率越大
    */
-  private resolvePriority;
+  private sortByWeightedRandom;
   /**
-   * 严格优先级算法：总是返回优先级最高的组
+   * 时间衰减排序：Priority + 等待时间加成
    */
-  private selectByStrict;
+  private sortByAging;
+}
+//#endregion
+//#region src/strategies/round-robin-strategy.d.ts
+interface RoundRobinStrategyOptions {
   /**
-   * 加权随机算法：根据优先级计算概率选择
-   * 使用 minWeightRatio 确保低优先级组也有机会
+   * 每次轮询获取的候选 Group 数量
+   * 数量越大，公平性范围越广，但 Redis 读取负载略微增加
+   * @default 50
    */
-  private selectByWeightedRandom;
+  batchSize?: number;
+  pollInterval?: number;
+}
+/**
+ * 公平轮询策略 (Round Robin)
+ *
+ * 适用场景：
+ * - 多租户系统 (SaaS)
+ * - 需要防止某个 Group 的海量任务 "饿死" 其他 Group 的场景
+ *
+ * 工作原理：
+ * 1. 从 Redis 获取一批当前等待最久的 Group (Batch Fetch)
+ * 2. 在本地对这批 Group 进行随机洗牌 (Shuffle)
+ * 3. 依次尝试获取任务
+ * 4. 遇到并发限制 (Limit Exceeded) 自动跳过，尝试下一个
+ */
+declare class RoundRobinStrategy implements DispatchStrategy {
+  private batchSize;
+  readonly idleInterval: number;
+  constructor(options?: RoundRobinStrategyOptions);
+  acquireJob(queue: Queue<any>): Promise<ReservedJob<any> | null>;
   /**
-   * 时间衰减算法：等待时间越长，优先级加成越高
+   * Fisher-Yates 洗牌算法
+   * 将数组元素原地随机打乱
    */
-  private selectByAging;
-  getNextGroup(queue: Queue<any>): Promise<string | null>;
+  private shuffle;
 }
 //#endregion
-export { AddOptions, AgingAlgorithmConfig, AlgorithmConfig, BackoffStrategy, BullBoardGroupMQAdapter, DispatchStrategy, FlowChildResult, FlowJob, FlowOptions, GroupMQBullBoardAdapterOptions, Job, OnGetPriority, PriorityStrategy, PriorityStrategyOptions, Queue, QueueOptions, RepeatOptions, ReservedJob, StrictAlgorithmConfig, UnrecoverableError, WeightedRandomAlgorithmConfig, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
+export { AddOptions, AgingAlgorithmConfig, AlgorithmConfig, BackoffStrategy, BullBoardGroupMQAdapter, DispatchStrategy, FlowChildResult, FlowJob, FlowOptions, GroupConfig, GroupMQBullBoardAdapterOptions, GroupOptions, Job, PriorityStrategy, PriorityStrategyOptions, Queue, QueueOptions, RepeatOptions, ReserveResult, ReservedJob, RoundRobinStrategy, RoundRobinStrategyOptions, StrictAlgorithmConfig, UnrecoverableError, WeightedRandomAlgorithmConfig, Worker, WorkerEvents, WorkerOptions, getWorkersStatus, waitForQueueToEmpty };
 //# sourceMappingURL=index.d.mts.map