@cdlab996/genid 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -1,31 +1,56 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
-//#region src/types/index.ts
-/**
-* ID 生成算法类型
-*/
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/types.ts
+/** ID 生成算法类型 */
 let GenidMethod = /* @__PURE__ */ function(GenidMethod) {
-	/** 漂移算法（推荐用于高性能场景） */
+	/** 漂移算法（推荐，高并发下可突破每毫秒序列号上限） */
 	GenidMethod[GenidMethod["DRIFT"] = 1] = "DRIFT";
-	/** 传统算法 */
+	/** 传统算法（序列号耗尽时等待下一毫秒） */
 	GenidMethod[GenidMethod["TRADITIONAL"] = 2] = "TRADITIONAL";
 	return GenidMethod;
 }({});
-
 //#endregion
-//#region src/index.ts
+//#region src/config.ts
+/** 将用户配置与默认值合并，返回完整内部配置 */
+function initConfig(options) {
+	const config = {
+		workerId: options.workerId,
+		method: options.method === GenidMethod.TRADITIONAL ? GenidMethod.TRADITIONAL : GenidMethod.DRIFT,
+		baseTime: options.baseTime && options.baseTime > 0 ? options.baseTime : (/* @__PURE__ */ new Date("2020-01-01")).valueOf(),
+		workerIdBitLength: options.workerIdBitLength && options.workerIdBitLength > 0 ? options.workerIdBitLength : 6,
+		seqBitLength: options.seqBitLength && options.seqBitLength > 0 ? options.seqBitLength : 6,
+		maxSeqNumber: 0,
+		minSeqNumber: 0,
+		topOverCostCount: 0
+	};
+	config.maxSeqNumber = options.maxSeqNumber && options.maxSeqNumber > 0 ? options.maxSeqNumber : (1 << config.seqBitLength) - 1;
+	config.minSeqNumber = options.minSeqNumber && options.minSeqNumber > 0 ? options.minSeqNumber : 5;
+	config.topOverCostCount = options.topOverCostCount && options.topOverCostCount > 0 ? options.topOverCostCount : 2e3;
+	return config;
+}
+/** 校验配置合法性，不合法则抛出 Error */
+function validateConfig(config) {
+	const { workerId, baseTime, workerIdBitLength, seqBitLength, minSeqNumber, maxSeqNumber } = config;
+	if (baseTime > Date.now()) throw new Error("[GenidOptimized] baseTime 不能大于当前时间");
+	if (workerIdBitLength < 1 || workerIdBitLength > 15) throw new Error("[GenidOptimized] workerIdBitLength 必须在 1 到 15 之间");
+	if (seqBitLength < 3 || seqBitLength > 21) throw new Error("[GenidOptimized] seqBitLength 必须在 3 到 21 之间");
+	if (workerIdBitLength + seqBitLength > 22) throw new Error("[GenidOptimized] workerIdBitLength + seqBitLength 不能超过 22");
+	const maxWorkerId = (1 << workerIdBitLength) - 1;
+	if (workerId < 0 || workerId > maxWorkerId) throw new Error(`[GenidOptimized] workerId 必须在 0 到 ${maxWorkerId} 之间`);
+	if (minSeqNumber < 5) throw new Error("[GenidOptimized] minSeqNumber 必须至少为 5(0-4 保留)");
+	if (maxSeqNumber < minSeqNumber) throw new Error("[GenidOptimized] maxSeqNumber 必须大于或等于 minSeqNumber");
+}
+//#endregion
+//#region src/genid.ts
 /**
-* 优化版 Snowflake ID 生成器
+* 基于 Snowflake 算法的分布式唯一 ID 生成器
 *
-* 基于 Snowflake 算法的高性能分布式唯一 ID 生成器，支持漂移算法和时钟回拨处理。
+* - 漂移算法：高并发下借用未来时间戳，突破每毫秒序列号上限
+* - 时钟回拨：使用保留序列号（0-4）优雅降级，不阻塞生成
+* - 非线程安全，每个 Worker/进程应使用独立实例和不同 workerId
 *
-* 特性：
-* - 漂移算法：提升高并发下的性能
-* - 优雅处理时钟回拨，不阻塞生成
-* - 可配置的位长度，灵活性高
-* - 支持传统和漂移两种生成方法
-*
-* ⚠️ 注意：此实例不是线程安全的，每个 Worker/进程应该创建独立的实例并使用不同的 workerId
+* @example
+* const genid = new GenidOptimized({ workerId: 1 });
+* const id = genid.nextId();
 */
 var GenidOptimized = class {
 	method;
@@ -44,29 +69,10 @@ var GenidOptimized = class {
 	_isOverCost;
 	_overCostCountInOneTerm;
 	_stats;
-	/**
-	* 构造函数，初始化 ID 生成器
-	*
-	* @param {Object} options - 配置选项
-	* @param {number} options.workerId - 工作节点/机器 ID(必须，范围 0 到 2^workerIdBitLength-1)
-	* @param {GenidMethod} [options.method=GenidMethod.DRIFT] - 算法类型
-	* @param {number} [options.baseTime=1577836800000] - 起始时间戳(毫秒，默认：2020-01-01)
-	* @param {number} [options.workerIdBitLength=6] - 工作节点 ID 的位数(1-15，默认：6)
-	* @param {number} [options.seqBitLength=6] - 序列号的位数(3-21，默认：6)
-	* @param {number} [options.maxSeqNumber] - 最大序列号(默认：2^seqBitLength-1)
-	* @param {number} [options.minSeqNumber=5] - 最小序列号(默认：5，0-4 保留)
-	* @param {number} [options.topOverCostCount=2000] - 最大漂移次数(默认：2000)
-	*
-	* @throws {Error} 如果缺少 workerId 或配置无效
-	*
-	* @example
-	* const genid = new GenidOptimized({ workerId: 1 });
-	* const id = genid.nextId();
-	*/
 	constructor(options) {
 		if (options.workerId === void 0 || options.workerId === null) throw new Error("[GenidOptimized] workerId 是必须参数");
-		const config = this._initConfig(options);
-		this._validateConfig(config);
+		const config = initConfig(options);
+		validateConfig(config);
 		this._initVariables(config);
 		this._stats = {
 			totalGenerated: 0n,
@@ -75,49 +81,6 @@ var GenidOptimized = class {
 			startTime: Date.now()
 		};
 	}
-	/**
-	* 初始化配置，设置默认值
-	* @private
-	* @param {Object} options - 用户提供的配置
-	* @returns {Object} 合并后的配置对象
-	*/
-	_initConfig(options) {
-		const config = {
-			workerId: options.workerId,
-			method: options.method === GenidMethod.TRADITIONAL ? GenidMethod.TRADITIONAL : GenidMethod.DRIFT,
-			baseTime: options.baseTime && options.baseTime > 0 ? options.baseTime : (/* @__PURE__ */ new Date("2020-01-01")).valueOf(),
-			workerIdBitLength: options.workerIdBitLength && options.workerIdBitLength > 0 ? options.workerIdBitLength : 6,
-			seqBitLength: options.seqBitLength && options.seqBitLength > 0 ? options.seqBitLength : 6,
-			maxSeqNumber: 0,
-			minSeqNumber: 0,
-			topOverCostCount: 0
-		};
-		config.maxSeqNumber = options.maxSeqNumber && options.maxSeqNumber > 0 ? options.maxSeqNumber : (1 << config.seqBitLength) - 1;
-		config.minSeqNumber = options.minSeqNumber && options.minSeqNumber > 0 ? options.minSeqNumber : 5;
-		config.topOverCostCount = options.topOverCostCount && options.topOverCostCount > 0 ? options.topOverCostCount : 2e3;
-		return config;
-	}
-	/**
-	* 验证配置参数的有效性
-	* @private
-	* @param {Object} config - 配置对象
-	* @throws {Error} 如果配置无效
-	*/
-	_validateConfig(config) {
-		const { workerId, workerIdBitLength, seqBitLength, minSeqNumber, maxSeqNumber } = config;
-		if (workerIdBitLength < 1 || workerIdBitLength > 15) throw new Error("[GenidOptimized] workerIdBitLength 必须在 1 到 15 之间");
-		if (seqBitLength < 3 || seqBitLength > 21) throw new Error("[GenidOptimized] seqBitLength 必须在 3 到 21 之间");
-		if (workerIdBitLength + seqBitLength > 22) throw new Error("[GenidOptimized] workerIdBitLength + seqBitLength 不能超过 22");
-		const maxWorkerId = (1 << workerIdBitLength) - 1;
-		if (workerId < 0 || workerId > maxWorkerId) throw new Error(`[GenidOptimized] workerId 必须在 0 到 ${maxWorkerId} 之间`);
-		if (minSeqNumber < 5) throw new Error("[GenidOptimized] minSeqNumber 必须至少为 5(0-4 保留)");
-		if (maxSeqNumber < minSeqNumber) throw new Error("[GenidOptimized] maxSeqNumber 必须大于或等于 minSeqNumber");
-	}
-	/**
-	* 初始化实例变量
-	* @private
-	* @param {Object} config - 配置对象
-	*/
 	_initVariables(config) {
 		this.method = BigInt(config.method);
 		this.baseTime = BigInt(config.baseTime);
@@ -135,64 +98,37 @@ var GenidOptimized = class {
 		this._isOverCost = false;
 		this._overCostCountInOneTerm = 0n;
 	}
-	/**
-	* 获取当前时间戳(相对于 baseTime 的毫秒数)
-	* @private
-	* @returns {bigint} 当前时间戳
-	*/
+	/** 获取相对于 baseTime 的当前时间戳 */
 	_getCurrentTimeTick() {
 		return BigInt(Date.now()) - this.baseTime;
 	}
-	/**
-	* 等待下一毫秒
-	* @private
-	* @returns {bigint} 下一毫秒时间戳
-	*/
+	/** 自旋等待直到时间前进到下一毫秒 */
 	_getNextTimeTick() {
 		let timeTick = this._getCurrentTimeTick();
 		let spinCount = 0;
 		const maxSpinCount = 1e6;
 		while (timeTick <= this._lastTimeTick) {
 			spinCount++;
-			if (spinCount > maxSpinCount)
- /**
-			* 如果自旋太多次，强制返回当前时间 + 1
-			* 这种情况理论上不应该发生，除非系统时间出现严重问题
-			*/
-			return this._lastTimeTick + 1n;
+			if (spinCount > maxSpinCount) return this._lastTimeTick + 1n;
 			timeTick = this._getCurrentTimeTick();
 		}
 		return timeTick;
 	}
-	/**
-	* 根据组件计算 ID
-	* @private
-	* @param {bigint} useTimeTick - 使用的时间戳
-	* @returns {bigint} 计算得到的 ID
-	*/
+	/** 组装 ID：timestamp | workerId | sequence，并自增序列号 */
 	_calcId(useTimeTick) {
 		const result = (BigInt(useTimeTick) << this._timestampShift) + (this.workerId << this.seqBitLength) + this._currentSeqNumber;
 		this._currentSeqNumber++;
 		this._stats.totalGenerated++;
 		return result;
 	}
-	/**
-	* 计算时钟回拨时的 ID
-	* @private
-	* @param {bigint} useTimeTick - 使用的时间戳
-	* @returns {bigint} 计算得到的 ID
-	*/
+	/** 时钟回拨时组装 ID，使用保留序列号（0-4）避免冲突 */
 	_calcTurnBackId(useTimeTick) {
 		const result = (BigInt(useTimeTick) << this._timestampShift) + (this.workerId << this.seqBitLength) + BigInt(this._turnBackIndex);
 		this._turnBackTimeTick++;
 		this._stats.totalGenerated++;
 		return result;
 	}
-	/**
-	* 处理漂移情况(漂移算法)
-	* @private
-	* @returns {bigint} 生成的 ID
-	*/
+	/** 漂移状态下生成 ID */
 	_nextOverCostId() {
 		const currentTimeTick = this._getCurrentTimeTick();
 		if (currentTimeTick > this._lastTimeTick) {
@@ -228,11 +164,7 @@ var GenidOptimized = class {
 		}
 		return this._calcId(this._lastTimeTick);
 	}
-	/**
-	* 正常生成 ID
-	* @private
-	* @returns {bigint} 生成的 ID
-	*/
+	/** 正常状态下生成 ID */
 	_nextNormalId() {
 		const currentTimeTick = this._getCurrentTimeTick();
 		if (currentTimeTick < this._lastTimeTick) {
@@ -249,6 +181,13 @@ var GenidOptimized = class {
 				this._beginTurnBackAction(this._turnBackTimeTick);
 				this._stats.turnBackCount++;
 			}
+			if (this._turnBackTimeTick >= this._lastTimeTick) {
+				this._turnBackTimeTick = 0n;
+				this._turnBackIndex = 0;
+				this._lastTimeTick = this._getNextTimeTick();
+				this._currentSeqNumber = this.minSeqNumber;
+				return this._calcId(this._lastTimeTick);
+			}
 			return this._calcTurnBackId(this._turnBackTimeTick);
 		}
 		if (this._turnBackTimeTick > 0) {
@@ -262,6 +201,11 @@ var GenidOptimized = class {
 			return this._calcId(this._lastTimeTick);
 		}
 		if (this._currentSeqNumber > this.maxSeqNumber) {
+			if (this.method === BigInt(GenidMethod.TRADITIONAL)) {
+				this._lastTimeTick = this._getNextTimeTick();
+				this._currentSeqNumber = this.minSeqNumber;
+				return this._calcId(this._lastTimeTick);
+			}
 			this._beginOverCostAction(currentTimeTick);
 			this._lastTimeTick++;
 			this._currentSeqNumber = this.minSeqNumber;
@@ -272,83 +216,29 @@ var GenidOptimized = class {
 		}
 		return this._calcId(this._lastTimeTick);
 	}
+	_beginOverCostAction(_useTimeTick) {}
+	_endOverCostAction(_useTimeTick) {}
+	_beginTurnBackAction(_useTimeTick) {}
+	_endTurnBackAction(_useTimeTick) {}
 	/**
-	* 钩子函数：开始漂移操作(可被子类重写)
-	* @protected
-	* @param {bigint} useTimeTick - 当前时间戳
-	*/
-	_beginOverCostAction(useTimeTick) {}
-	/**
-	* 钩子函数：结束漂移操作(可被子类重写)
-	* @protected
-	* @param {bigint} useTimeTick - 当前时间戳
-	*/
-	_endOverCostAction(useTimeTick) {}
-	/**
-	* 钩子函数：开始时钟回拨操作(可被子类重写)
-	* @protected
-	* @param {bigint} useTimeTick - 当前时间戳
-	*/
-	_beginTurnBackAction(useTimeTick) {}
-	/**
-	* 钩子函数：结束时钟回拨操作(可被子类重写)
-	* @protected
-	* @param {bigint} useTimeTick - 当前时间戳
-	*/
-	_endTurnBackAction(useTimeTick) {}
-	/**
-	* 生成下一个 ID
-	*
-	* @returns {number} 唯一 ID(Number 类型)
-	* @throws {Error} 如果 ID 超出 JavaScript 安全整数范围
-	*
-	* @example
-	* const id = genid.nextNumber();
-	* console.log(id); // 123456789012345
+	* 生成 ID，返回 number。超出安全整数范围时抛错。
+	* @throws 当 ID >= Number.MAX_SAFE_INTEGER + 1 时
 	*/
 	nextNumber() {
 		const id = this._isOverCost ? this._nextOverCostId() : this._nextNormalId();
 		if (id >= 9007199254740992n) throw new Error(`[GenidOptimized] 生成的 ID ${id.toString()} 超出 JavaScript 安全整数范围 (9007199254740992)。请使用 nextBigId() 方法。`);
 		return Number(id);
 	}
-	/**
-	* 生成下一个 ID
-	*
-	* 如果 ID 在安全范围内返回 Number，否则返回 BigInt
-	*
-	* @returns {number|bigint} 唯一 ID
-	*
-	* @example
-	* const id = genid.nextId();
-	* console.log(typeof id); // 'number' 或 'bigint'
-	*/
+	/** 生成 ID，安全范围内返回 number，否则返回 bigint */
 	nextId() {
 		const id = this._isOverCost ? this._nextOverCostId() : this._nextNormalId();
 		return id >= 9007199254740992n ? id : Number(id);
 	}
-	/**
-	* 生成下一个 ID
-	*
-	* @returns {bigint} 唯一 ID(BigInt 类型)
-	*
-	* @example
-	* const id = genid.nextBigId();
-	* console.log(id); // 123456789012345678n
-	*/
+	/** 生成 ID，始终返回 bigint */
 	nextBigId() {
 		return this._isOverCost ? this._nextOverCostId() : this._nextNormalId();
 	}
-	/**
-	* 批量生成 ID
-	*
-	* @param {number} count - 要生成的 ID 数量
-	* @param {boolean} [asBigInt=false] - 是否返回 BigInt 数组
-	* @returns {Array<number|bigint>} 唯一 ID 数组
-	*
-	* @example
-	* const ids = genid.nextBatch(100);
-	* const bigIds = genid.nextBatch(100, true);
-	*/
+	/** 批量生成 ID */
 	nextBatch(count, asBigInt = false) {
 		if (count <= 0) throw new Error("[GenidOptimized] 批量生成数量必须大于 0");
 		const ids = [];
@@ -356,24 +246,11 @@ var GenidOptimized = class {
 		return ids;
 	}
 	/**
-	* 解析 ID，提取其组成部分
-	*
-	* @param {number|bigint|string} id - 要解析的 ID
-	* @returns {Object} 解析结果
-	* @returns {Date} return.timestamp - 生成时间戳
-	* @returns {number} return.timestampMs - 时间戳(毫秒)
-	* @returns {number} return.workerId - 工作节点 ID
-	* @returns {number} return.sequence - 序列号
+	* 解析 ID，提取时间戳、workerId、序列号
 	*
 	* @example
-	* const info = genid.parse(id);
-	* console.log(info);
-	* // {
-	* //   timestamp: Date,
-	* //   timestampMs: 1609459200000,
-	* //   workerId: 1,
-	* //   sequence: 42
-	* // }
+	* genid.parse(id)
+	* // { timestamp: Date, timestampMs: 1609459200000, workerId: 1, sequence: 42 }
 	*/
 	parse(id) {
 		const idBigInt = BigInt(id);
@@ -389,15 +266,7 @@ var GenidOptimized = class {
 			sequence: Number(sequence)
 		};
 	}
-	/**
-	* 获取生成器统计信息
-	*
-	* @returns {Object} 统计数据
-	*
-	* @example
-	* const stats = genid.getStats();
-	* console.log(stats);
-	*/
+	/** 获取运行统计信息 */
 	getStats() {
 		const uptime = Date.now() - this._stats.startTime;
 		const totalGenerated = Number(this._stats.totalGenerated);
@@ -410,9 +279,7 @@ var GenidOptimized = class {
 			currentState: this._isOverCost ? "OVER_COST" : "NORMAL"
 		};
 	}
-	/**
-	* 重置统计数据
-	*/
+	/** 重置统计数据 */
 	resetStats() {
 		this._stats = {
 			totalGenerated: 0n,
@@ -421,11 +288,7 @@ var GenidOptimized = class {
 			startTime: Date.now()
 		};
 	}
-	/**
-	* 获取配置信息
-	*
-	* @returns {Object} 配置详情
-	*/
+	/** 获取当前配置信息 */
 	getConfig() {
 		const maxWorkerId = (1 << Number(this.workerIdBitLength)) - 1;
 		const maxSequence = (1 << Number(this.seqBitLength)) - 1;
@@ -444,18 +307,8 @@ var GenidOptimized = class {
 		};
 	}
 	/**
-	* 验证 ID 是否为有效的 Snowflake ID
-	*
-	* @param {number|bigint|string} id - 要验证的 ID
-	* @param {boolean} [strictWorkerId=false] - 是否严格验证 workerId 必须匹配当前实例
-	* @returns {boolean} ID 是否有效
-	*
-	* @example
-	* const genid = new GenidOptimized({ workerId: 1 });
-	* const id = genid.nextId();
-	* genid.isValid(id); // true
-	* genid.isValid(12345); // false
-	* genid.isValid(id, true); // true (workerId 匹配)
+	* 验证 ID 是否为当前配置下合法的 Snowflake ID
+	* @param strictWorkerId - 为 true 时要求 workerId 匹配当前实例
 	*/
 	isValid(id, strictWorkerId = false) {
 		try {
@@ -478,12 +331,7 @@ var GenidOptimized = class {
 			return false;
 		}
 	}
-	/**
-	* 将 ID 格式化为二进制字符串以便调试
-	*
-	* @param {number|bigint|string} id - 要格式化的 ID
-	* @returns {string} 格式化的二进制表示
-	*/
+	/** 将 ID 格式化为带标注的二进制字符串（调试用） */
 	formatBinary(id) {
 		const idBigInt = BigInt(id);
 		if (idBigInt < 0n) throw new Error("[GenidOptimized] ID 不能为负数");
@@ -501,6 +349,6 @@ var GenidOptimized = class {
 		].join("\n");
 	}
 };
-
 //#endregion
-exports.GenidOptimized = GenidOptimized;
+exports.GenidMethod = GenidMethod;
+exports.GenidOptimized = GenidOptimized;