@cdlab996/genid 1.2.1 → 1.4.0

package/dist/index.d.cts

@@ -1,103 +1,103 @@
-//#region src/types/index.d.ts
-/**
- * ID 生成算法类型
- */
+//#region src/types.d.ts
+/** ID 生成算法类型 */
 declare enum GenidMethod {
-  /** 漂移算法（推荐用于高性能场景） */
+  /** 漂移算法（推荐，高并发下可突破每毫秒序列号上限） */
   DRIFT = 1,
-  /** 传统算法 */
+  /** 传统算法（序列号耗尽时等待下一毫秒） */
   TRADITIONAL = 2
 }
-/**
- * ID 生成器配置选项
- */
+/** ID 生成器构造选项 */
 interface GenidOptions {
-  /** 工作节点/机器 ID（必须，范围 0 到 2^workerIdBitLength-1） */
+  /** 工作节点 ID（必须，范围 0 到 2^workerIdBitLength-1） */
   workerId: number;
-  /** 算法类型（默认：GenidMethod.DRIFT） */
+  /** 算法类型（默认：DRIFT） */
   method?: GenidMethod;
-  /** 起始时间戳，单位：毫秒（默认：1577836800000，即 2020-01-01 00:00:00） */
+  /** 起始时间戳/毫秒（默认：2020-01-01） */
   baseTime?: number;
-  /** 工作节点 ID 的位数（范围：1-15，默认：6） */
+  /** 工作节点 ID 位数（1-15，默认：6） */
   workerIdBitLength?: number;
-  /** 序列号的位数（范围：3-21，默认：6） */
+  /** 序列号位数（3-21，默认：6） */
   seqBitLength?: number;
   /** 最大序列号（默认：2^seqBitLength - 1） */
   maxSeqNumber?: number;
-  /** 最小序列号（默认：5，0-4 保留用于时钟回拨处理） */
+  /** 最小序列号（默认：5，0-4 保留用于时钟回拨） */
   minSeqNumber?: number;
-  /** 最大漂移次数，超过后等待下一毫秒（默认：2000） */
+  /** 最大漂移次数（默认：2000） */
   topOverCostCount?: number;
 }
-/**
- * ID 解析结果
- */
+/** 内部配置（所有字段必填，由 initConfig 生成） */
+interface GenidConfig {
+  workerId: number;
+  method: GenidMethod;
+  baseTime: number;
+  workerIdBitLength: number;
+  seqBitLength: number;
+  maxSeqNumber: number;
+  minSeqNumber: number;
+  topOverCostCount: number;
+}
+/** 内部统计数据（BigInt 确保大数精度） */
+interface Stats {
+  totalGenerated: bigint;
+  overCostCount: bigint;
+  turnBackCount: bigint;
+  startTime: number;
+}
+/** ID 解析结果 */
 interface ParseResult {
-  /** ID 生成时间（Date 对象） */
+  /** 生成时间 */
   timestamp: Date;
-  /** ID 生成时间戳，单位：毫秒 */
+  /** 生成时间戳/毫秒 */
   timestampMs: number;
   /** 工作节点 ID */
   workerId: number;
   /** 序列号 */
   sequence: number;
 }
-/**
- * 统计信息结果（对外暴露，使用 Number 类型）
- */
+/** 对外统计信息 */
 interface StatsResult {
-  /** 总生成 ID 数量 */
   totalGenerated: number;
-  /** 漂移次数 */
   overCostCount: number;
-  /** 时钟回拨次数 */
   turnBackCount: number;
-  /** 运行时长，单位：毫秒 */
+  /** 运行时长/毫秒 */
   uptimeMs: number;
-  /** 平均每秒生成 ID 数量 */
   avgPerSecond: number;
-  /** 当前状态（OVER_COST: 漂移中, NORMAL: 正常） */
   currentState: 'OVER_COST' | 'NORMAL';
 }
-/**
- * 配置信息结果
- */
+/** isValid 校验选项 */
+interface ValidateOptions {
+  /** 为 true 时要求 workerId 匹配当前实例（默认：false） */
+  strictWorkerId?: boolean;
+  /** ID 的生成时间不得早于此时间戳/毫秒（默认：baseTime） */
+  afterTime?: number;
+}
+/** 配置信息 */
 interface ConfigResult {
-  /** 算法类型（DRIFT: 漂移算法, TRADITIONAL: 传统算法） */
   method: 'DRIFT' | 'TRADITIONAL';
-  /** 当前工作节点 ID */
   workerId: number;
-  /** 工作节点 ID 范围（格式："0-63"） */
+  /** 格式："0-63" */
   workerIdRange: string;
-  /** 序列号范围（格式："5-63"） */
+  /** 格式："5-63" */
   sequenceRange: string;
-  /** 最大序列号值 */
   maxSequence: number;
-  /** 每毫秒可生成的 ID 数量 */
   idsPerMillisecond: number;
-  /** 起始时间（Date 对象） */
   baseTime: Date;
-  /** 时间戳占用的位数 */
   timestampBits: number;
-  /** 工作节点 ID 占用的位数 */
   workerIdBits: number;
-  /** 序列号占用的位数 */
   sequenceBits: number;
 }
 //#endregion
-//#region src/index.d.ts
+//#region src/genid.d.ts
 /**
- * 优化版 Snowflake ID 生成器
- *
- * 基于 Snowflake 算法的高性能分布式唯一 ID 生成器，支持漂移算法和时钟回拨处理。
+ * 基于 Snowflake 算法的分布式唯一 ID 生成器
  *
- * 特性：
- * - 漂移算法：提升高并发下的性能
- * - 优雅处理时钟回拨，不阻塞生成
- * - 可配置的位长度，灵活性高
- * - 支持传统和漂移两种生成方法
+ * - 漂移算法：高并发下借用未来时间戳，突破每毫秒序列号上限
+ * - 时钟回拨：使用保留序列号（0-4）优雅降级，不阻塞生成
+ * - 非线程安全，每个 Worker/进程应使用独立实例和不同 workerId
  *
- * ⚠️ 注意：此实例不是线程安全的，每个 Worker/进程应该创建独立的实例并使用不同的 workerId
+ * @example
+ * const genid = new GenidOptimized({ workerId: 1 });
+ * const id = genid.nextId();
  */
 declare class GenidOptimized {
   private method;
@@ -116,216 +116,63 @@ declare class GenidOptimized {
   private _isOverCost;
   private _overCostCountInOneTerm;
   private _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: GenidOptions);
-  /**
-   * 初始化配置，设置默认值
-   * @private
-   * @param {Object} options - 用户提供的配置
-   * @returns {Object} 合并后的配置对象
-   */
-  private _initConfig;
-  /**
-   * 验证配置参数的有效性
-   * @private
-   * @param {Object} config - 配置对象
-   * @throws {Error} 如果配置无效
-   */
-  private _validateConfig;
-  /**
-   * 初始化实例变量
-   * @private
-   * @param {Object} config - 配置对象
-   */
   private _initVariables;
-  /**
-   * 获取当前时间戳(相对于 baseTime 的毫秒数)
-   * @private
-   * @returns {bigint} 当前时间戳
-   */
+  /** 获取相对于 baseTime 的当前时间戳 */
   private _getCurrentTimeTick;
-  /**
-   * 等待下一毫秒
-   * @private
-   * @returns {bigint} 下一毫秒时间戳
-   */
+  /** 自旋等待直到时间前进到下一毫秒 */
   private _getNextTimeTick;
-  /**
-   * 根据组件计算 ID
-   * @private
-   * @param {bigint} useTimeTick - 使用的时间戳
-   * @returns {bigint} 计算得到的 ID
-   */
+  /** 组装 ID：timestamp | workerId | sequence，并自增序列号 */
   private _calcId;
-  /**
-   * 计算时钟回拨时的 ID
-   * @private
-   * @param {bigint} useTimeTick - 使用的时间戳
-   * @returns {bigint} 计算得到的 ID
-   */
+  /** 时钟回拨时组装 ID，使用保留序列号（0-4）避免冲突 */
   private _calcTurnBackId;
-  /**
-   * 处理漂移情况(漂移算法)
-   * @private
-   * @returns {bigint} 生成的 ID
-   */
+  /** 漂移状态下生成 ID */
   private _nextOverCostId;
-  /**
-   * 正常生成 ID
-   * @private
-   * @returns {bigint} 生成的 ID
-   */
+  /** 正常状态下生成 ID */
   private _nextNormalId;
+  protected _beginOverCostAction(_useTimeTick: bigint): void;
+  protected _endOverCostAction(_useTimeTick: bigint): void;
+  protected _beginTurnBackAction(_useTimeTick: bigint): void;
+  protected _endTurnBackAction(_useTimeTick: bigint): void;
   /**
-   * 钩子函数：开始漂移操作(可被子类重写)
-   * @protected
-   * @param {bigint} useTimeTick - 当前时间戳
-   */
-  protected _beginOverCostAction(useTimeTick: bigint): void;
-  /**
-   * 钩子函数：结束漂移操作(可被子类重写)
-   * @protected
-   * @param {bigint} useTimeTick - 当前时间戳
-   */
-  protected _endOverCostAction(useTimeTick: bigint): void;
-  /**
-   * 钩子函数：开始时钟回拨操作(可被子类重写)
-   * @protected
-   * @param {bigint} useTimeTick - 当前时间戳
-   */
-  protected _beginTurnBackAction(useTimeTick: bigint): void;
-  /**
-   * 钩子函数：结束时钟回拨操作(可被子类重写)
-   * @protected
-   * @param {bigint} useTimeTick - 当前时间戳
-   */
-  protected _endTurnBackAction(useTimeTick: bigint): void;
-  /**
-   * 生成下一个 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(): number;
-  /**
-   * 生成下一个 ID
-   *
-   * 如果 ID 在安全范围内返回 Number，否则返回 BigInt
-   *
-   * @returns {number|bigint} 唯一 ID
-   *
-   * @example
-   * const id = genid.nextId();
-   * console.log(typeof id); // 'number' 或 'bigint'
-   */
+  /** 生成 ID，安全范围内返回 number，否则返回 bigint */
   nextId(): number | bigint;
-  /**
-   * 生成下一个 ID
-   *
-   * @returns {bigint} 唯一 ID(BigInt 类型)
-   *
-   * @example
-   * const id = genid.nextBigId();
-   * console.log(id); // 123456789012345678n
-   */
+  /** 生成 ID，始终返回 bigint */
   nextBigId(): bigint;
-  /**
-   * 批量生成 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: number, asBigInt?: boolean): Array<number | bigint>;
   /**
-   * 解析 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: number | bigint | string): ParseResult;
-  /**
-   * 获取生成器统计信息
-   *
-   * @returns {Object} 统计数据
-   *
-   * @example
-   * const stats = genid.getStats();
-   * console.log(stats);
-   */
+  /** 获取运行统计信息 */
   getStats(): StatsResult;
-  /**
-   * 重置统计数据
-   */
+  /** 重置统计数据 */
   resetStats(): void;
-  /**
-   * 获取配置信息
-   *
-   * @returns {Object} 配置详情
-   */
+  /** 获取当前配置信息 */
   getConfig(): ConfigResult;
   /**
-   * 验证 ID 是否为有效的 Snowflake ID
+   * 验证 ID 是否为当前配置下合法的 Snowflake ID
    *
-   * @param {number|bigint|string} id - 要验证的 ID
-   * @param {boolean} [strictWorkerId=false] - 是否严格验证 workerId 必须匹配当前实例
-   * @returns {boolean} ID 是否有效
+   * @param options - 校验选项，或传 boolean 表示 strictWorkerId（向后兼容）
    *
    * @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 格式化为二进制字符串以便调试
-   *
-   * @param {number|bigint|string} id - 要格式化的 ID
-   * @returns {string} 格式化的二进制表示
+   * genid.isValid(id)                            // 宽松校验
+   * genid.isValid(id, true)                      // 要求 workerId 匹配
+   * genid.isValid(id, { strictWorkerId: true })  // 同上
+   * genid.isValid(id, { afterTime: startupTime }) // 要求 ID 生成时间晚于 startupTime
    */
+  isValid(id: number | bigint | string, options?: boolean | ValidateOptions): boolean;
+  /** 将 ID 格式化为带标注的二进制字符串（调试用） */
   formatBinary(id: number | bigint | string): string;
 }
 //#endregion
-export { GenidOptimized };
+export { ConfigResult, GenidConfig, GenidMethod, GenidOptimized, GenidOptions, ParseResult, Stats, StatsResult, ValidateOptions };