feat: custom snowflake epoch, various fixes

README.md

@@ -104,13 +104,13 @@ static generate(
     {
         timestamp?: Date | number;
         shard_id?: number;
-        epoch?: number;
+        epoch?: Date | number;
     }
 ): string;
 ```
 
 ```
-static parse(snowflake: string | number | bigint): {
+static parse(snowflake: string | number | bigint, epoch?: Date | number): {
     timestamp: number;
     shard_id: number;
     binary: string;

dist/index.d.ts

@@ -14,28 +14,39 @@ export declare class Snowflake {
      *
      * @type {number}
      */
-    static SHARD_ID: number | null;
+    static SHARD_ID: number;
+    /**
+     * The sequence of the current running generator.
+     *
+     * Defaults to "1".
+     *
+     * @type {number}
+     */
+    static SEQUENCE: number;
     /**
      * Generates a single snowflake.
      * @param {Date|number} [timestamp = Date.now] - Timestamp to generate from
-     * @returns {bigint}
+     * @param {number} [shard_id = Snowflake.SHARD_ID] - Shard ID for the snowflake
+     * @param {Date|number} [epoch = Snowflake.EPOCH] - Epoch for the snowflake
+     * @returns {string}
      */
-    static generate({ timestamp, shard_id, sequence, }?: {
+    static generate({ timestamp, shard_id, epoch, }?: {
         timestamp?: Date | number;
         shard_id?: number;
-        sequence?: number;
+        epoch?: Date | number;
     }): string;
     /**
      * Deconstruct a snowflake to its values using the `Generator.epoch`.
-     * @param {SnowflakeResolvable|SnowflakeResolvable[]} snowflake - Snowflake(s) to deconstruct
-     * @returns {DeconstructedSnowflake|DeconstructedSnowflake[]}
+     * @param {SnowflakeResolvable} snowflake - Snowflake to deconstruct
+     * @param {Date|number} epoch - The epoch of the snowflake
+     * @returns {DeconstructedSnowflake}
      */
-    static parse(snowflake: SnowflakeResolvable): DeconstructedSnowflake;
+    static parse(snowflake: SnowflakeResolvable, epoch?: Date | number): DeconstructedSnowflake;
     static isValid(snowflake: string): boolean;
     /**
      * Extract bits and their values from a snowflake.
      * @param {SnowflakeResolvable} snowflake - Snowflake to extract from
-     * @param {number|bigint} shift - Number of bits to shift before extracting
+     * @param {number|bigint} start - Number of bits to shift before extracting
      * @param {number|bigint} length - Number of bits to extract before stopping
      * @returns {bigint}
      */

src/index.ts

@@ -39,22 +39,29 @@ export class Snowflake {
   /**
    * Generates a single snowflake.
    * @param {Date|number} [timestamp = Date.now] - Timestamp to generate from
-   * @returns {bigint}
+   * @param {number} [shard_id = Snowflake.SHARD_ID] - Shard ID for the snowflake
+   * @param {Date|number} [epoch = Snowflake.EPOCH] - Epoch for the snowflake
+   * @returns {string}
    */
   /* c8 ignore end */
 
   static generate({
     timestamp = Date.now(),
     shard_id = Snowflake.SHARD_ID,
+    epoch = Snowflake.EPOCH,
   }: {
     timestamp?: Date | number;
     shard_id?: number;
+    epoch?: Date | number;
   } = {}): string {
     if (timestamp instanceof Date) timestamp = timestamp.valueOf();
     else timestamp = new Date(timestamp).valueOf();
 
+    if (epoch instanceof Date) epoch = epoch.valueOf();
+    else epoch = new Date(epoch).valueOf();
+
     // tslint:disable:no-bitwise
-    let result = (BigInt(timestamp) - BigInt(Snowflake.EPOCH)) << BigInt(22);
+    let result = (BigInt(timestamp) - BigInt(epoch)) << BigInt(22);
     result = result | (BigInt(shard_id % 1024) << BigInt(12));
     result = result | BigInt(Snowflake.SEQUENCE++ % 4096);
     // tslint:enable:no-bitwise
@@ -63,22 +70,25 @@ export class Snowflake {
 
   /**
    * Deconstruct a snowflake to its values using the `Generator.epoch`.
-   * @param {SnowflakeResolvable|SnowflakeResolvable[]} snowflake - Snowflake(s) to deconstruct
-   * @returns {DeconstructedSnowflake|DeconstructedSnowflake[]}
+   * @param {SnowflakeResolvable} snowflake - Snowflake to deconstruct
+   * @param {Date|number} epoch - The epoch of the snowflake
+   * @returns {DeconstructedSnowflake}
    */
 
-  static parse(snowflake: SnowflakeResolvable): DeconstructedSnowflake {
+  static parse(snowflake: SnowflakeResolvable, epoch?: Date | number): DeconstructedSnowflake {
     const binary = Snowflake.binary(snowflake);
     return {
-      timestamp: Snowflake.extractBits(snowflake, 1, 41),
+      timestamp: Number(
+        (BigInt(snowflake) >> BigInt(22)) + BigInt(new Date(epoch ?? Snowflake.EPOCH).valueOf())
+      ),
       shard_id: Snowflake.extractBits(snowflake, 42, 10),
       sequence: Snowflake.extractBits(snowflake, 52),
       binary,
     };
   }
 
   static isValid(snowflake: string) {
-    if (!/^[\d]{19}$/.test(snowflake)) {
+    if (!/^[\d]{17,22}$/.test(snowflake)) {
       return false;
     }
     try {
@@ -92,7 +102,7 @@ export class Snowflake {
   /**
    * Extract bits and their values from a snowflake.
    * @param {SnowflakeResolvable} snowflake - Snowflake to extract from
-   * @param {number|bigint} shift - Number of bits to shift before extracting
+   * @param {number|bigint} start - Number of bits to shift before extracting
    * @param {number|bigint} length - Number of bits to extract before stopping
    * @returns {bigint}
    */