groupmq-plus 1.1.2 → 1.1.3

package/dist/index.d.cts

@@ -1349,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

@@ -1349,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

package/dist/index.js

@@ -2761,5 +2761,117 @@ function sleep(ms) {
 }
 
 //#endregion
-export { BullBoardGroupMQAdapter, Job, Queue, UnrecoverableError, Worker, getWorkersStatus, waitForQueueToEmpty };
+//#region src/strategies/priority-strategy.ts
+var PriorityStrategy = class {
+	constructor(options = {}) {
+		this.cache = /* @__PURE__ */ new Map();
+		this.overrides = /* @__PURE__ */ new Map();
+		this.algorithmConfig = options.algorithm ?? { type: "weighted-random" };
+		this.defaultPriority = options.defaultPriority ?? 1;
+		this.cacheTtlMs = options.cacheTtlMs ?? 5e3;
+		this.onGetPriority = options.onGetPriority;
+	}
+	/**
+	* 手动覆盖某个组的优先级（优先级高于 Redis 配置和 getPriority）
+	* 主要用于测试或临时调整
+	*/
+	setPriority(groupId, priority) {
+		this.overrides.set(groupId, priority);
+	}
+	/**
+	* 清除手动覆盖，恢复使用 Redis 配置或 getPriority
+	*/
+	clearPriority(groupId) {
+		this.overrides.delete(groupId);
+	}
+	/**
+	* 获取组的基础优先级
+	* 优先级来源顺序：overrides > cache > onGetPriority(config) 或 config.priority
+	*/
+	async resolvePriority(queue, groupId) {
+		const override = this.overrides.get(groupId);
+		if (override !== void 0) return override;
+		const now = Date.now();
+		const cached = this.cache.get(groupId);
+		if (cached && cached.expiresAt > now) return cached.priority;
+		const config = await queue.getGroupConfig(groupId);
+		let priority;
+		if (this.onGetPriority) priority = await this.onGetPriority(groupId, config);
+		else priority = config.priority !== 1 ? config.priority : this.defaultPriority;
+		if (this.cacheTtlMs > 0) this.cache.set(groupId, {
+			priority,
+			expiresAt: now + this.cacheTtlMs
+		});
+		return priority;
+	}
+	/**
+	* 严格优先级算法：总是返回优先级最高的组
+	*/
+	selectByStrict(groups) {
+		groups.sort((a, b) => b.priority - a.priority);
+		return groups[0].groupId;
+	}
+	/**
+	* 加权随机算法：根据优先级计算概率选择
+	* 使用 minWeightRatio 确保低优先级组也有机会
+	*/
+	selectByWeightedRandom(groups) {
+		if (groups.length === 1) return groups[0].groupId;
+		const minWeightRatio = this.algorithmConfig.minWeightRatio ?? .1;
+		const minWeight = Math.max(...groups.map((g) => g.priority)) * minWeightRatio;
+		const weights = groups.map((g) => ({
+			groupId: g.groupId,
+			weight: Math.max(g.priority, minWeight)
+		}));
+		const totalWeight = weights.reduce((sum, w) => sum + w.weight, 0);
+		let random = Math.random() * totalWeight;
+		for (const w of weights) {
+			random -= w.weight;
+			if (random <= 0) return w.groupId;
+		}
+		return groups[0].groupId;
+	}
+	/**
+	* 时间衰减算法：等待时间越长，优先级加成越高
+	*/
+	selectByAging(groups) {
+		const now = Date.now();
+		const intervalMs = this.algorithmConfig.intervalMs ?? 6e4;
+		const adjustedGroups = groups.map((g) => {
+			let ageBonus = 0;
+			if (g.oldestTimestamp) {
+				const waitTime = now - g.oldestTimestamp;
+				ageBonus = Math.floor(waitTime / intervalMs);
+			}
+			return {
+				groupId: g.groupId,
+				adjustedPriority: g.priority + ageBonus
+			};
+		});
+		adjustedGroups.sort((a, b) => b.adjustedPriority - a.adjustedPriority);
+		return adjustedGroups[0].groupId;
+	}
+	async getNextGroup(queue) {
+		const readyGroups = await queue.getReadyGroups(0, 100);
+		if (readyGroups.length === 0) return null;
+		const groupInfos = await Promise.all(readyGroups.map(async (groupId) => {
+			const priority = await this.resolvePriority(queue, groupId);
+			const info = {
+				groupId,
+				priority
+			};
+			if (this.algorithmConfig.type === "aging") info.oldestTimestamp = await queue.getGroupOldestTimestamp(groupId);
+			return info;
+		}));
+		switch (this.algorithmConfig.type) {
+			case "strict": return this.selectByStrict(groupInfos);
+			case "aging": return this.selectByAging(groupInfos);
+			case "weighted-random":
+			default: return this.selectByWeightedRandom(groupInfos);
+		}
+	}
+};
+
+//#endregion
+export { BullBoardGroupMQAdapter, Job, PriorityStrategy, Queue, UnrecoverableError, Worker, getWorkersStatus, waitForQueueToEmpty };
 //# sourceMappingURL=index.js.map