@cdlab996/genid 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @cdlab996/genid
 
-一个基于 Snowflake 算法的高性能分布式唯一 ID 生成器。
+基于 Snowflake 算法的高性能分布式唯一 ID 生成器，支持漂移算法和时钟回拨处理，适用于分布式系统中的唯一标识生成需求。
 
 ## 特性
 
@@ -8,6 +8,7 @@
 - 🔄 **时钟回拨处理**：优雅处理时钟回拨，不阻塞 ID 生成
 - ⚙️ **灵活配置**：支持自定义位长度分配
 - 📊 **性能监控**：内置统计和调试功能
+- ✅ **ID 验证**：验证 ID 的有效性，支持严格/宽松模式
 
 ## 架构设计
 
@@ -47,12 +48,6 @@ graph TB
     
     Q --> R[更新统计]
     R --> S[返回 ID]
-    
-    style B fill:#fff4e6
-    style E fill:#e8f5e9
-    style K fill:#fce4ec
-    style Q fill:#f3e5f5
-    style S fill:#c8e6c9
 ```
 
 ### ID 结构（64-bit）
@@ -159,6 +154,46 @@ console.log(info)
 // }
 ```
 
+### 验证 ID
+
+#### `isValid(id, strictWorkerId?)`
+
+验证 ID 是否为有效的 Snowflake ID
+
+**参数**
+- `id` - 要验证的 ID（支持 Number、BigInt、String 类型）
+- `strictWorkerId` - 可选，是否严格验证 workerId 必须匹配当前实例（默认：false）
+
+**返回值**
+- `boolean` - ID 是否有效
+
+**验证规则**
+- ✅ ID 为正数
+- ✅ ID 在 64 位范围内
+- ✅ 时间戳在合理范围内（>= baseTime，<= 当前时间 + 1秒容差）
+- ✅ workerId 在有效范围内（0 到 2^workerIdBitLength-1）
+- ✅ 序列号在有效范围内（0 到 2^seqBitLength-1）
+- ✅ 严格模式下：workerId 必须匹配当前实例
+
+```typescript
+const genid = new GenidOptimized({ workerId: 1 })
+const id = genid.nextId()
+
+// 宽松模式：验证 ID 格式是否有效
+genid.isValid(id) // true
+genid.isValid(12345) // false（无效的 ID）
+genid.isValid(-1) // false（负数）
+genid.isValid('invalid') // false（无效格式）
+
+// 严格模式：验证 ID 是否由当前实例生成
+const genid2 = new GenidOptimized({ workerId: 2 })
+const id2 = genid2.nextId()
+
+genid.isValid(id2) // true（宽松模式，其他实例的 ID 也有效）
+genid.isValid(id2, true) // false（严格模式，workerId 不匹配）
+genid.isValid(id, true) // true（严格模式，workerId 匹配）
+```
+
 ### 统计与配置
 
 #### `getStats()`
@@ -248,6 +283,30 @@ const genid = new GenidOptimized({
 })
 ```
 
+### 验证 ID
+
+```typescript
+const genid = new GenidOptimized({ workerId: 1 })
+
+// 生成并验证 ID
+const id = genid.nextId()
+if (genid.isValid(id)) {
+  console.log('ID 有效')
+}
+
+// 验证外部 ID（例如从数据库或 API 获取的 ID）
+const externalId = '123456789012345'
+if (genid.isValid(externalId)) {
+  const info = genid.parse(externalId)
+  console.log('ID 有效，解析结果:', info)
+} else {
+  console.error('ID 无效')
+}
+
+// 严格验证（只接受当前实例生成的 ID）
+const isMyId = genid.isValid(id, true)
+```
+
 ### 监控性能
 
 ```typescript

package/dist/index.cjs

@@ -1,14 +1,15 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/types/index.ts
 /**
 * ID 生成算法类型
 */
-let GenidMethod = /* @__PURE__ */ function(GenidMethod$1) {
+let GenidMethod = /* @__PURE__ */ function(GenidMethod) {
 	/** 漂移算法（推荐用于高性能场景） */
-	GenidMethod$1[GenidMethod$1["DRIFT"] = 1] = "DRIFT";
+	GenidMethod[GenidMethod["DRIFT"] = 1] = "DRIFT";
 	/** 传统算法 */
-	GenidMethod$1[GenidMethod$1["TRADITIONAL"] = 2] = "TRADITIONAL";
-	return GenidMethod$1;
+	GenidMethod[GenidMethod["TRADITIONAL"] = 2] = "TRADITIONAL";
+	return GenidMethod;
 }({});
 
 //#endregion
@@ -183,7 +184,7 @@ var GenidOptimized = class {
 	*/
 	_calcTurnBackId(useTimeTick) {
 		const result = (BigInt(useTimeTick) << this._timestampShift) + (this.workerId << this.seqBitLength) + BigInt(this._turnBackIndex);
-		this._turnBackTimeTick--;
+		this._turnBackTimeTick++;
 		this._stats.totalGenerated++;
 		return result;
 	}
@@ -443,6 +444,41 @@ 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 匹配)
+	*/
+	isValid(id, strictWorkerId = false) {
+		try {
+			const idBigInt = BigInt(id);
+			if (idBigInt < 0n) return false;
+			if (idBigInt >= 18446744073709551616n) return false;
+			const timestamp = (idBigInt >> this._timestampShift) + this.baseTime;
+			const workerIdMask = (1n << this.workerIdBitLength) - 1n;
+			const workerId = idBigInt >> this.seqBitLength & workerIdMask;
+			const sequence = idBigInt & (1n << this.seqBitLength) - 1n;
+			if (timestamp < this.baseTime) return false;
+			if (timestamp > BigInt(Date.now()) + 1000n) return false;
+			const maxWorkerId = (1n << this.workerIdBitLength) - 1n;
+			if (workerId < 0n || workerId > maxWorkerId) return false;
+			if (strictWorkerId && workerId !== this.workerId) return false;
+			const maxSeq = (1n << this.seqBitLength) - 1n;
+			if (sequence < 0n || sequence > maxSeq) return false;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
 	* 将 ID 格式化为二进制字符串以便调试
 	*
 	* @param {number|bigint|string} id - 要格式化的 ID

package/dist/index.d.cts

@@ -6,7 +6,7 @@ declare enum GenidMethod {
   /** 漂移算法（推荐用于高性能场景） */
   DRIFT = 1,
   /** 传统算法 */
-  TRADITIONAL = 2,
+  TRADITIONAL = 2
 }
 /**
  * ID 生成器配置选项
@@ -304,6 +304,21 @@ declare class GenidOptimized {
    * @returns {Object} 配置详情
    */
   getConfig(): ConfigResult;
+  /**
+   * 验证 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 匹配)
+   */
+  isValid(id: number | bigint | string, strictWorkerId?: boolean): boolean;
   /**
    * 将 ID 格式化为二进制字符串以便调试
    *

package/dist/{index.d.ts → index.d.mts}

@@ -6,7 +6,7 @@ declare enum GenidMethod {
   /** 漂移算法（推荐用于高性能场景） */
   DRIFT = 1,
   /** 传统算法 */
-  TRADITIONAL = 2,
+  TRADITIONAL = 2
 }
 /**
  * ID 生成器配置选项
@@ -304,6 +304,21 @@ declare class GenidOptimized {
    * @returns {Object} 配置详情
    */
   getConfig(): ConfigResult;
+  /**
+   * 验证 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 匹配)
+   */
+  isValid(id: number | bigint | string, strictWorkerId?: boolean): boolean;
   /**
    * 将 ID 格式化为二进制字符串以便调试
    *

package/dist/{index.js → index.mjs}

@@ -2,12 +2,12 @@
 /**
 * ID 生成算法类型
 */
-let GenidMethod = /* @__PURE__ */ function(GenidMethod$1) {
+let GenidMethod = /* @__PURE__ */ function(GenidMethod) {
 	/** 漂移算法（推荐用于高性能场景） */
-	GenidMethod$1[GenidMethod$1["DRIFT"] = 1] = "DRIFT";
+	GenidMethod[GenidMethod["DRIFT"] = 1] = "DRIFT";
 	/** 传统算法 */
-	GenidMethod$1[GenidMethod$1["TRADITIONAL"] = 2] = "TRADITIONAL";
-	return GenidMethod$1;
+	GenidMethod[GenidMethod["TRADITIONAL"] = 2] = "TRADITIONAL";
+	return GenidMethod;
 }({});
 
 //#endregion
@@ -182,7 +182,7 @@ var GenidOptimized = class {
 	*/
 	_calcTurnBackId(useTimeTick) {
 		const result = (BigInt(useTimeTick) << this._timestampShift) + (this.workerId << this.seqBitLength) + BigInt(this._turnBackIndex);
-		this._turnBackTimeTick--;
+		this._turnBackTimeTick++;
 		this._stats.totalGenerated++;
 		return result;
 	}
@@ -442,6 +442,41 @@ 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 匹配)
+	*/
+	isValid(id, strictWorkerId = false) {
+		try {
+			const idBigInt = BigInt(id);
+			if (idBigInt < 0n) return false;
+			if (idBigInt >= 18446744073709551616n) return false;
+			const timestamp = (idBigInt >> this._timestampShift) + this.baseTime;
+			const workerIdMask = (1n << this.workerIdBitLength) - 1n;
+			const workerId = idBigInt >> this.seqBitLength & workerIdMask;
+			const sequence = idBigInt & (1n << this.seqBitLength) - 1n;
+			if (timestamp < this.baseTime) return false;
+			if (timestamp > BigInt(Date.now()) + 1000n) return false;
+			const maxWorkerId = (1n << this.workerIdBitLength) - 1n;
+			if (workerId < 0n || workerId > maxWorkerId) return false;
+			if (strictWorkerId && workerId !== this.workerId) return false;
+			const maxSeq = (1n << this.seqBitLength) - 1n;
+			if (sequence < 0n || sequence > maxSeq) return false;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
 	* 将 ID 格式化为二进制字符串以便调试
 	*
 	* @param {number|bigint|string} id - 要格式化的 ID

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cdlab996/genid",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "基于 Snowflake 算法的高性能分布式唯一 ID 生成器",
   "author": "wudi <wuchendi96@gmail.com>",
   "license": "MIT",
@@ -46,21 +46,27 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest --run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --project tsconfig.json"
-  },
   "devDependencies": {
-    "@types/node": "^22",
-    "tsdown": "^0.15.7",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25",
+    "tsdown": "^0.20.3",
+    "typescript": "^5",
+    "vitest": "^4.0.18"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest --run",
+    "test:index": "vitest --run tests/index.test.ts",
+    "test:performance": "vitest --run tests/performance.test.ts",
+    "test:stress": "vitest --run tests/stress.test.ts",
+    "lint": "biome check",
+    "format": "biome format --write",
+    "clean": "bash ./scripts/clean.sh",
+    "typecheck": "tsc --project tsconfig.json"
   }
-}
+}