@cdlab996/genid 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,316 @@
+//#region src/types/index.d.ts
+/**
+ * ID 生成算法类型
+ */
+declare enum GenidMethod {
+  /** 漂移算法（推荐用于高性能场景） */
+  DRIFT = 1,
+  /** 传统算法 */
+  TRADITIONAL = 2,
+}
+/**
+ * ID 生成器配置选项
+ */
+interface GenidOptions {
+  /** 工作节点/机器 ID（必须，范围 0 到 2^workerIdBitLength-1） */
+  workerId: number;
+  /** 算法类型（默认：GenidMethod.DRIFT） */
+  method?: GenidMethod;
+  /** 起始时间戳，单位：毫秒（默认：1577836800000，即 2020-01-01 00:00:00） */
+  baseTime?: number;
+  /** 工作节点 ID 的位数（范围：1-15，默认：6） */
+  workerIdBitLength?: number;
+  /** 序列号的位数（范围：3-21，默认：6） */
+  seqBitLength?: number;
+  /** 最大序列号（默认：2^seqBitLength - 1） */
+  maxSeqNumber?: number;
+  /** 最小序列号（默认：5，0-4 保留用于时钟回拨处理） */
+  minSeqNumber?: number;
+  /** 最大漂移次数，超过后等待下一毫秒（默认：2000） */
+  topOverCostCount?: 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';
+}
+/**
+ * 配置信息结果
+ */
+interface ConfigResult {
+  /** 算法类型（DRIFT: 漂移算法, TRADITIONAL: 传统算法） */
+  method: 'DRIFT' | 'TRADITIONAL';
+  /** 当前工作节点 ID */
+  workerId: number;
+  /** 工作节点 ID 范围（格式："0-63"） */
+  workerIdRange: string;
+  /** 序列号范围（格式："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
+/**
+ * 优化版 Snowflake ID 生成器
+ *
+ * 基于 Snowflake 算法的高性能分布式唯一 ID 生成器，支持漂移算法和时钟回拨处理。
+ *
+ * 特性：
+ * - 漂移算法：提升高并发下的性能
+ * - 优雅处理时钟回拨，不阻塞生成
+ * - 可配置的位长度，灵活性高
+ * - 支持传统和漂移两种生成方法
+ *
+ * ⚠️ 注意：此实例不是线程安全的，每个 Worker/进程应该创建独立的实例并使用不同的 workerId
+ */
+declare class GenidOptimized {
+  private method;
+  private baseTime;
+  private workerId;
+  private workerIdBitLength;
+  private seqBitLength;
+  private maxSeqNumber;
+  private minSeqNumber;
+  private topOverCostCount;
+  private _timestampShift;
+  private _currentSeqNumber;
+  private _lastTimeTick;
+  private _turnBackTimeTick;
+  private _turnBackIndex;
+  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} 当前时间戳
+   */
+  private _getCurrentTimeTick;
+  /**
+   * 等待下一毫秒
+   * @private
+   * @returns {bigint} 下一毫秒时间戳
+   */
+  private _getNextTimeTick;
+  /**
+   * 根据组件计算 ID
+   * @private
+   * @param {bigint} useTimeTick - 使用的时间戳
+   * @returns {bigint} 计算得到的 ID
+   */
+  private _calcId;
+  /**
+   * 计算时钟回拨时的 ID
+   * @private
+   * @param {bigint} useTimeTick - 使用的时间戳
+   * @returns {bigint} 计算得到的 ID
+   */
+  private _calcTurnBackId;
+  /**
+   * 处理漂移情况(漂移算法)
+   * @private
+   * @returns {bigint} 生成的 ID
+   */
+  private _nextOverCostId;
+  /**
+   * 正常生成 ID
+   * @private
+   * @returns {bigint} 生成的 ID
+   */
+  private _nextNormalId;
+  /**
+   * 钩子函数：开始漂移操作(可被子类重写)
+   * @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
+   */
+  nextNumber(): number;
+  /**
+   * 生成下一个 ID
+   *
+   * 如果 ID 在安全范围内返回 Number，否则返回 BigInt
+   *
+   * @returns {number|bigint} 唯一 ID
+   *
+   * @example
+   * const id = genid.nextId();
+   * console.log(typeof id); // 'number' 或 'bigint'
+   */
+  nextId(): number | bigint;
+  /**
+   * 生成下一个 ID
+   *
+   * @returns {bigint} 唯一 ID(BigInt 类型)
+   *
+   * @example
+   * const id = genid.nextBigId();
+   * console.log(id); // 123456789012345678n
+   */
+  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);
+   */
+  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 - 序列号
+   *
+   * @example
+   * const info = genid.parse(id);
+   * console.log(info);
+   * // {
+   * //   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 格式化为二进制字符串以便调试
+   *
+   * @param {number|bigint|string} id - 要格式化的 ID
+   * @returns {string} 格式化的二进制表示
+   */
+  formatBinary(id: number | bigint | string): string;
+}
+//#endregion
+export { GenidOptimized };

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+//#region src/types/index.d.ts
+/**
+ * ID 生成算法类型
+ */
+declare enum GenidMethod {
+  /** 漂移算法（推荐用于高性能场景） */
+  DRIFT = 1,
+  /** 传统算法 */
+  TRADITIONAL = 2,
+}
+/**
+ * ID 生成器配置选项
+ */
+interface GenidOptions {
+  /** 工作节点/机器 ID（必须，范围 0 到 2^workerIdBitLength-1） */
+  workerId: number;
+  /** 算法类型（默认：GenidMethod.DRIFT） */
+  method?: GenidMethod;
+  /** 起始时间戳，单位：毫秒（默认：1577836800000，即 2020-01-01 00:00:00） */
+  baseTime?: number;
+  /** 工作节点 ID 的位数（范围：1-15，默认：6） */
+  workerIdBitLength?: number;
+  /** 序列号的位数（范围：3-21，默认：6） */
+  seqBitLength?: number;
+  /** 最大序列号（默认：2^seqBitLength - 1） */
+  maxSeqNumber?: number;
+  /** 最小序列号（默认：5，0-4 保留用于时钟回拨处理） */
+  minSeqNumber?: number;
+  /** 最大漂移次数，超过后等待下一毫秒（默认：2000） */
+  topOverCostCount?: 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';
+}
+/**
+ * 配置信息结果
+ */
+interface ConfigResult {
+  /** 算法类型（DRIFT: 漂移算法, TRADITIONAL: 传统算法） */
+  method: 'DRIFT' | 'TRADITIONAL';
+  /** 当前工作节点 ID */
+  workerId: number;
+  /** 工作节点 ID 范围（格式："0-63"） */
+  workerIdRange: string;
+  /** 序列号范围（格式："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
+/**
+ * 优化版 Snowflake ID 生成器
+ *
+ * 基于 Snowflake 算法的高性能分布式唯一 ID 生成器，支持漂移算法和时钟回拨处理。
+ *
+ * 特性：
+ * - 漂移算法：提升高并发下的性能
+ * - 优雅处理时钟回拨，不阻塞生成
+ * - 可配置的位长度，灵活性高
+ * - 支持传统和漂移两种生成方法
+ *
+ * ⚠️ 注意：此实例不是线程安全的，每个 Worker/进程应该创建独立的实例并使用不同的 workerId
+ */
+declare class GenidOptimized {
+  private method;
+  private baseTime;
+  private workerId;
+  private workerIdBitLength;
+  private seqBitLength;
+  private maxSeqNumber;
+  private minSeqNumber;
+  private topOverCostCount;
+  private _timestampShift;
+  private _currentSeqNumber;
+  private _lastTimeTick;
+  private _turnBackTimeTick;
+  private _turnBackIndex;
+  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} 当前时间戳
+   */
+  private _getCurrentTimeTick;
+  /**
+   * 等待下一毫秒
+   * @private
+   * @returns {bigint} 下一毫秒时间戳
+   */
+  private _getNextTimeTick;
+  /**
+   * 根据组件计算 ID
+   * @private
+   * @param {bigint} useTimeTick - 使用的时间戳
+   * @returns {bigint} 计算得到的 ID
+   */
+  private _calcId;
+  /**
+   * 计算时钟回拨时的 ID
+   * @private
+   * @param {bigint} useTimeTick - 使用的时间戳
+   * @returns {bigint} 计算得到的 ID
+   */
+  private _calcTurnBackId;
+  /**
+   * 处理漂移情况(漂移算法)
+   * @private
+   * @returns {bigint} 生成的 ID
+   */
+  private _nextOverCostId;
+  /**
+   * 正常生成 ID
+   * @private
+   * @returns {bigint} 生成的 ID
+   */
+  private _nextNormalId;
+  /**
+   * 钩子函数：开始漂移操作(可被子类重写)
+   * @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
+   */
+  nextNumber(): number;
+  /**
+   * 生成下一个 ID
+   *
+   * 如果 ID 在安全范围内返回 Number，否则返回 BigInt
+   *
+   * @returns {number|bigint} 唯一 ID
+   *
+   * @example
+   * const id = genid.nextId();
+   * console.log(typeof id); // 'number' 或 'bigint'
+   */
+  nextId(): number | bigint;
+  /**
+   * 生成下一个 ID
+   *
+   * @returns {bigint} 唯一 ID(BigInt 类型)
+   *
+   * @example
+   * const id = genid.nextBigId();
+   * console.log(id); // 123456789012345678n
+   */
+  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);
+   */
+  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 - 序列号
+   *
+   * @example
+   * const info = genid.parse(id);
+   * console.log(info);
+   * // {
+   * //   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 格式化为二进制字符串以便调试
+   *
+   * @param {number|bigint|string} id - 要格式化的 ID
+   * @returns {string} 格式化的二进制表示
+   */
+  formatBinary(id: number | bigint | string): string;
+}
+//#endregion
+export { GenidOptimized };