@andrew_l/snowflake 0.2.20

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Andrew L. <andrew.io.dev@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# Snowflake - Generate unique IDs in a distributed environment at scale
+
+[![npm version][npm-version-src]][npm-version-href]
+![license][license-src]
+[![bundle][bundle-src]][bundle-href]
+
+There is a bit improved version of [@sapphire/snowflake](https://github.com/sapphiredev/utilities/tree/main/packages/snowflake) package by using javascript numbers and Uint8Array buffer.
+
+⚡ **Benchmark**
+
+```
+  name                               hz      rme   samples
+· sapphire                10,690,009.83   ±0.62%  10690010
+· andrew (bigint)         11,704,038.89   ±0.03%  11704039
+· andrew (buffer)         13,808,748.82   ±0.37%  13808749
+· andrew (buffer unsafe)  16,023,413.95   ±0.04%  16023414   fastest
+```
+
+<!-- install placeholder -->
+
+## 🚀 Example Usage
+
+### Basic Example
+
+```javascript
+import { Snowflake } from '@andrew_l/snowflake';
+
+// Define a custom epoch
+const epoch = 1751810749563;
+
+// Create an instance of Snowflake
+const snowflake = new Snowflake({ epoch });
+
+// Generate a snowflake with the given epoch
+const uniqueId = snowflake.generate();
+
+// Generate a snowflake with the given epoch
+const uniqueIdBuffer = snowflake.generateBuffer();
+```
+
+### Stripe Style
+
+```javascript
+import { Snowflake } from '@andrew_l/snowflake';
+import { base62, bigIntFromBytes } from '@andrew_l/toolkit';
+
+// Create an instance of Snowflake
+const snowflake = new Snowflake({ epoch: 1288834974657 });
+
+// Generate a snowflake with the given epoch
+const customerId = 'cus_' + base62.encode(snowflake.generateBuffer());
+
+// e.g. cus_2JRkp89kSZs
+console.log('customer id  =', customerId);
+
+// Extract the numeric value by decoding the base62 portion
+const customerIdNumber = bigIntFromBytes(base62.decode(customerId.slice(4)));
+
+// e.g. 1941863457523503104n
+console.log('customer id (number) =', customerIdNumber);
+```
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@andrew_l/snowflake?style=flat
+[npm-version-href]: https://npmjs.com/package/@andrew_l/snowflake
+[bundle-src]: https://img.shields.io/bundlephobia/min/@andrew_l/snowflake?style=flat
+[bundle-href]: https://bundlephobia.com/result?p=@andrew_l/snowflake
+[license-src]: https://img.shields.io/npm/l/@andrew_l/snowflake?style=flat

package/dist/index.cjs

@@ -0,0 +1,230 @@
+'use strict';
+
+const toolkit = require('@andrew_l/toolkit');
+
+var MAX_WORKER_ID = 31;
+var MAX_PROCESS_ID = 31;
+var MAX_INCREMENT = 4095;
+class Snowflake {
+  /**
+   * Alias for {@link deconstruct}
+   */
+  decode = this.deconstruct;
+  /**
+   * Internal reference of the epoch passed in the constructor
+   * @internal
+   */
+  _epoch;
+  /**
+   * Internal incrementor for generating snowflakes
+   * @internal
+   */
+  _increment = 0;
+  /**
+   * The process ID that will be used by default in the generate method
+   * @internal
+   */
+  _processId = 1;
+  /**
+   * The worker ID that will be used by default in the generate method
+   * @internal
+   */
+  _workerId = 0;
+  /**
+   * @internal
+   */
+  _buffer;
+  /**
+   * @param epoch the epoch to use
+   */
+  constructor(opts) {
+    if (toolkit.isDate(opts) || toolkit.isNumber(opts)) {
+      this._epoch = toolkit.timestampMs(opts);
+    } else if (toolkit.isBigInt(opts)) {
+      this._epoch = toolkit.timestampMs(Number(opts));
+    } else {
+      const { increment = 0, processId = 1, workerId = 0, epoch } = opts;
+      this._epoch = toolkit.timestampMs(toolkit.isBigInt(epoch) ? Number(epoch) : epoch);
+      this.workerId = workerId;
+      this.processId = processId;
+      this._increment = Number(increment) & MAX_INCREMENT;
+    }
+    this._buffer = new Uint8Array(8);
+  }
+  /**
+   * The epoch for this snowflake, as a number
+   */
+  get epoch() {
+    return this._epoch;
+  }
+  /**
+   * Gets the configured process ID
+   */
+  get processId() {
+    return this._processId;
+  }
+  /**
+   * Sets the process ID that will be used by default for the {@link generate} method
+   * @param value The new value, will be masked with `0b11111`
+   */
+  set processId(value) {
+    this._processId = Number(value) & MAX_PROCESS_ID;
+  }
+  /**
+   * Gets the configured worker ID
+   */
+  get workerId() {
+    return this._workerId;
+  }
+  /**
+   * Sets the worker ID that will be used by default for the {@link generate} method
+   * @param value The new value, will be masked with `0b11111`
+   */
+  set workerId(value) {
+    this._workerId = Number(value) & MAX_WORKER_ID;
+  }
+  /**
+   * Generates a Snowflake ID as a `Uint8Array` buffer.
+   */
+  generate(timestamp = Date.now()) {
+    if (timestamp instanceof Date) timestamp = timestamp.getTime();
+    if (!toolkit.isNumber(timestamp)) {
+      throw new Error(
+        `"timestamp" argument must be a number or Date (received ${typeof timestamp})`
+      );
+    }
+    var increment = this._increment;
+    this._increment = this._increment + 1 & MAX_INCREMENT;
+    return BigInt(timestamp - this._epoch) << 22n | BigInt(this._workerId & MAX_WORKER_ID) << 17n | BigInt(this._processId & MAX_PROCESS_ID) << 12n | BigInt(increment & MAX_INCREMENT);
+  }
+  /**
+   * Generates a Snowflake ID as a `Uint8Array` buffer.
+   *
+   * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.
+   * Its contents may be overwritten on the next ID generation call.
+   *
+   * This method is intended for high-performance scenarios where you
+   * immediately transform the buffer (e.g., to base62) before calling again.
+   * Avoid storing or mutating the returned buffer directly.
+   */
+  generateBufferUnsafe(timestamp = Date.now()) {
+    if (timestamp instanceof Date) timestamp = timestamp.getTime();
+    if (!toolkit.isNumber(timestamp)) {
+      throw new Error(
+        `"timestamp" argument must be a number or Date (received ${typeof timestamp})`
+      );
+    }
+    var increment = this._increment;
+    this._increment = this._increment + 1 & MAX_INCREMENT;
+    var timestampDelta = timestamp - this._epoch;
+    var timestampHigh = Math.floor(timestampDelta / 4294967295);
+    var timestampLow = timestampDelta >>> 0;
+    var high32 = (timestampHigh << 22 | timestampLow >>> 10) >>> 0;
+    var low32 = (timestampLow << 22 | this._workerId << 17 | this._processId << 12 | increment & MAX_INCREMENT) >>> 0;
+    var buffer = this._buffer;
+    buffer[0] = high32 >>> 24;
+    buffer[1] = high32 >>> 16;
+    buffer[2] = high32 >>> 8;
+    buffer[3] = high32;
+    buffer[4] = low32 >>> 24;
+    buffer[5] = low32 >>> 16;
+    buffer[6] = low32 >>> 8;
+    buffer[7] = low32;
+    return buffer;
+  }
+  /**
+   * Generates a snowflake given an epoch and optionally a timestamp
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake({ epoch }).generate();
+   * ```
+   * @returns A unique snowflake as Uint8Array
+   */
+  generateBuffer(timestamp = Date.now()) {
+    this.generateBufferUnsafe(timestamp);
+    return new Uint8Array(this._buffer);
+  }
+  /**
+   * Deconstructs a snowflake given a snowflake ID
+   * @param id the snowflake to deconstruct
+   * @returns a deconstructed snowflake
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+   * ```
+   */
+  deconstruct(id) {
+    var high32, low32;
+    if (id instanceof Uint8Array) {
+      high32 = (id[0] << 24 | id[1] << 16 | id[2] << 8 | id[3]) >>> 0;
+      low32 = (id[4] << 24 | id[5] << 16 | id[6] << 8 | id[7]) >>> 0;
+    } else if (toolkit.isBigInt(id)) {
+      return this.deconstruct(toolkit.bigIntBytes(id));
+    } else {
+      return this.deconstruct(toolkit.bigIntBytes(BigInt(id)));
+    }
+    return {
+      id: BigInt(high32) * 0x100000000n + BigInt(low32),
+      timestamp: high32 * 1024 + (low32 >>> 22) + this._epoch,
+      workerId: low32 >>> 17 & MAX_WORKER_ID,
+      processId: low32 >>> 12 & MAX_PROCESS_ID,
+      increment: low32 & MAX_INCREMENT,
+      epoch: this._epoch
+    };
+  }
+  /**
+   * Retrieves the timestamp field's value from a snowflake.
+   * @param id The snowflake to get the timestamp value from.
+   * @returns The UNIX timestamp that is stored in `id`.
+   */
+  timestampFrom(id) {
+    if (toolkit.isString(id) || toolkit.isBigInt(id)) {
+      return this.timestampFrom(Snowflake.bufferFrom(id));
+    }
+    var high32 = (id[0] << 24 | id[1] << 16 | id[2] << 8 | id[3]) >>> 0;
+    var low32 = (id[4] << 24 | id[5] << 16 | id[6] << 8 | id[7]) >>> 0;
+    return high32 * 1024 + (low32 >>> 22) + this._epoch;
+  }
+  /**
+   * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given
+   * snowflake in sort order.
+   * @param a The first snowflake to compare.
+   * @param b The second snowflake to compare.
+   * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.
+   */
+  static compare(a, b) {
+    if (toolkit.isString(a)) {
+      a = BigInt(a);
+    } else if (a instanceof Uint8Array) {
+      a = toolkit.bigIntFromBytes(a);
+    }
+    if (toolkit.isString(b)) {
+      b = BigInt(b);
+    } else if (b instanceof Uint8Array) {
+      b = toolkit.bigIntFromBytes(b);
+    }
+    return a === b ? 0 : a < b ? -1 : 1;
+  }
+  /**
+   * Parse value as Uint8Array buffer
+   */
+  static bufferFrom(value) {
+    if (toolkit.isString(value)) value = BigInt(value);
+    var buf = toolkit.bigIntBytes(value);
+    var bufSize = buf.byteLength;
+    if (buf.byteLength < 8) {
+      var buf2 = new Uint8Array(8);
+      buf2.set(buf, 8 - bufSize);
+      buf = buf2;
+    }
+    return buf;
+  }
+}
+
+exports.MAX_INCREMENT = MAX_INCREMENT;
+exports.MAX_PROCESS_ID = MAX_PROCESS_ID;
+exports.MAX_WORKER_ID = MAX_WORKER_ID;
+exports.Snowflake = Snowflake;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/Snowflake.ts"],"sourcesContent":["/**\n * Based on: https://github.com/sapphiredev/utilities/blob/main/packages/snowflake/src/lib/Snowflake.ts\n */\nimport {\n  bigIntBytes,\n  bigIntFromBytes,\n  isBigInt,\n  isDate,\n  isNumber,\n  isString,\n  timestampMs,\n} from '@andrew_l/toolkit';\n\n/**\n * Object returned by Snowflake#deconstruct\n */\nexport interface DeconstructedSnowflake {\n  /**\n   * The id as a number\n   */\n  id: bigint;\n\n  /**\n   * The timestamp stored in the snowflake\n   */\n  timestamp: number;\n\n  /**\n   * The worker id stored in the snowflake\n   */\n  workerId: number;\n\n  /**\n   * The process id stored in the snowflake\n   */\n  processId: number;\n\n  /**\n   * The increment stored in the snowflake\n   */\n  increment: number;\n\n  /**\n   * The epoch to use in the snowflake\n   */\n  epoch: number;\n}\n\n/**\n * Options for Snowflake\n */\nexport interface SnowflakeOptions {\n  /**\n   * Timestamp or date of the snowflake to generate\n   */\n  epoch: number | bigint | Date;\n\n  /**\n   * The increment to use\n   * @default 0\n   * @remark keep in mind that this number is auto-incremented between generate calls\n   */\n  increment?: number | bigint;\n\n  /**\n   * The worker ID to use, will be truncated to 5 bits (0-31)\n   * @default 0\n   */\n  workerId?: number | bigint;\n\n  /**\n   * The process ID to use, will be truncated to 5 bits (0-31)\n   * @default 1\n   */\n  processId?: number | bigint;\n}\n\n/**\n * The maximum value the `workerId` field accepts in snowflakes.\n */\nexport var MAX_WORKER_ID = 0x1f;\n\n/**\n * The maximum value the `processId` field accepts in snowflakes.\n */\nexport var MAX_PROCESS_ID = 0x1f;\n\n/**\n * The maximum value the `increment` field accepts in snowflakes.\n */\nexport var MAX_INCREMENT = 0xfff;\n\n/**\n * A class for generating and deconstructing Twitter snowflakes.\n *\n * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}\n * is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.\n *\n * If we have a snowflake `266241948824764416` we can represent it as binary:\n * ```\n * 64                                          22     17     12          0\n *  000000111011000111100001101001000101000000  00001  00000  000000000000\n *           number of ms since epoch           worker  pid    increment\n * ```\n *\n * @group Main\n */\nexport class Snowflake {\n  /**\n   * Alias for {@link deconstruct}\n   */\n  public decode = this.deconstruct;\n\n  /**\n   * Internal reference of the epoch passed in the constructor\n   * @internal\n   */\n  private readonly _epoch: number;\n\n  /**\n   * Internal incrementor for generating snowflakes\n   * @internal\n   */\n  private _increment = 0;\n\n  /**\n   * The process ID that will be used by default in the generate method\n   * @internal\n   */\n  private _processId = 1;\n\n  /**\n   * The worker ID that will be used by default in the generate method\n   * @internal\n   */\n  private _workerId = 0;\n\n  /**\n   * @internal\n   */\n  private _buffer: Uint8Array;\n\n  /**\n   * @param epoch the epoch to use\n   */\n  public constructor(opts: SnowflakeOptions | Date | number | bigint) {\n    if (isDate(opts) || isNumber(opts)) {\n      this._epoch = timestampMs(opts);\n    } else if (isBigInt(opts)) {\n      this._epoch = timestampMs(Number(opts));\n    } else {\n      const { increment = 0, processId = 1, workerId = 0, epoch } = opts;\n      this._epoch = timestampMs(isBigInt(epoch) ? Number(epoch) : epoch);\n      this.workerId = workerId;\n      this.processId = processId;\n      this._increment = Number(increment) & MAX_INCREMENT;\n    }\n\n    this._buffer = new Uint8Array(8);\n  }\n\n  /**\n   * The epoch for this snowflake, as a number\n   */\n  public get epoch(): number {\n    return this._epoch;\n  }\n\n  /**\n   * Gets the configured process ID\n   */\n  public get processId(): number {\n    return this._processId;\n  }\n\n  /**\n   * Sets the process ID that will be used by default for the {@link generate} method\n   * @param value The new value, will be masked with `0b11111`\n   */\n  public set processId(value: number | bigint) {\n    this._processId = Number(value) & MAX_PROCESS_ID;\n  }\n\n  /**\n   * Gets the configured worker ID\n   */\n  public get workerId(): number {\n    return this._workerId;\n  }\n\n  /**\n   * Sets the worker ID that will be used by default for the {@link generate} method\n   * @param value The new value, will be masked with `0b11111`\n   */\n  public set workerId(value: number | bigint) {\n    this._workerId = Number(value) & MAX_WORKER_ID;\n  }\n\n  /**\n   * Generates a Snowflake ID as a `Uint8Array` buffer.\n   */\n  public generate(timestamp: Date | number = Date.now()): bigint {\n    if (timestamp instanceof Date) timestamp = timestamp.getTime();\n    if (!isNumber(timestamp)) {\n      throw new Error(\n        `\"timestamp\" argument must be a number or Date (received ${typeof timestamp})`,\n      );\n    }\n\n    var increment = this._increment;\n    this._increment = (this._increment + 1) & MAX_INCREMENT;\n\n    return (\n      (BigInt(timestamp - this._epoch) << 22n) |\n      (BigInt(this._workerId & MAX_WORKER_ID) << 17n) |\n      (BigInt(this._processId & MAX_PROCESS_ID) << 12n) |\n      BigInt(increment & MAX_INCREMENT)\n    );\n  }\n\n  /**\n   * Generates a Snowflake ID as a `Uint8Array` buffer.\n   *\n   * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.\n   * Its contents may be overwritten on the next ID generation call.\n   *\n   * This method is intended for high-performance scenarios where you\n   * immediately transform the buffer (e.g., to base62) before calling again.\n   * Avoid storing or mutating the returned buffer directly.\n   */\n  public generateBufferUnsafe(timestamp: Date | number = Date.now()) {\n    if (timestamp instanceof Date) timestamp = timestamp.getTime();\n    if (!isNumber(timestamp)) {\n      throw new Error(\n        `\"timestamp\" argument must be a number or Date (received ${typeof timestamp})`,\n      );\n    }\n\n    var increment = this._increment;\n    this._increment = (this._increment + 1) & MAX_INCREMENT;\n\n    // Calculate the timestamp delta\n    var timestampDelta = timestamp - this._epoch;\n\n    // Split into 32-bit parts for bitwise operations\n    var timestampHigh = Math.floor(timestampDelta / 0xffffffff);\n    var timestampLow = timestampDelta >>> 0;\n\n    var high32 = ((timestampHigh << 22) | (timestampLow >>> 10)) >>> 0;\n    var low32 =\n      ((timestampLow << 22) |\n        (this._workerId << 17) |\n        (this._processId << 12) |\n        (increment & MAX_INCREMENT)) >>>\n      0;\n\n    var buffer = this._buffer;\n\n    buffer[0] = high32 >>> 24;\n    buffer[1] = high32 >>> 16;\n    buffer[2] = high32 >>> 8;\n    buffer[3] = high32;\n    buffer[4] = low32 >>> 24;\n    buffer[5] = low32 >>> 16;\n    buffer[6] = low32 >>> 8;\n    buffer[7] = low32;\n\n    return buffer;\n  }\n\n  /**\n   * Generates a snowflake given an epoch and optionally a timestamp\n   * @example\n   * ```typescript\n   * const epoch = new Date('2000-01-01T00:00:00.000Z');\n   * const snowflake = new Snowflake({ epoch }).generate();\n   * ```\n   * @returns A unique snowflake as Uint8Array\n   */\n  public generateBuffer(timestamp: Date | number = Date.now()) {\n    this.generateBufferUnsafe(timestamp);\n    return new Uint8Array(this._buffer);\n  }\n\n  /**\n   * Deconstructs a snowflake given a snowflake ID\n   * @param id the snowflake to deconstruct\n   * @returns a deconstructed snowflake\n   * @example\n   * ```typescript\n   * const epoch = new Date('2000-01-01T00:00:00.000Z');\n   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');\n   * ```\n   */\n  public deconstruct(id: string | bigint | Uint8Array): DeconstructedSnowflake {\n    var high32: number, low32: number;\n\n    if (id instanceof Uint8Array) {\n      // Convert from Uint8Array\n      high32 = ((id[0] << 24) | (id[1] << 16) | (id[2] << 8) | id[3]) >>> 0;\n      low32 = ((id[4] << 24) | (id[5] << 16) | (id[6] << 8) | id[7]) >>> 0;\n    } else if (isBigInt(id)) {\n      return this.deconstruct(bigIntBytes(id));\n    } else {\n      // Convert from string\n      return this.deconstruct(bigIntBytes(BigInt(id)));\n    }\n\n    return {\n      id: BigInt(high32) * 0x100000000n + BigInt(low32),\n      timestamp: high32 * 0x400 + (low32 >>> 22) + this._epoch,\n      workerId: (low32 >>> 17) & MAX_WORKER_ID,\n      processId: (low32 >>> 12) & MAX_PROCESS_ID,\n      increment: low32 & MAX_INCREMENT,\n      epoch: this._epoch,\n    };\n  }\n\n  /**\n   * Retrieves the timestamp field's value from a snowflake.\n   * @param id The snowflake to get the timestamp value from.\n   * @returns The UNIX timestamp that is stored in `id`.\n   */\n  public timestampFrom(id: string | bigint | Uint8Array): number {\n    if (isString(id) || isBigInt(id)) {\n      return this.timestampFrom(Snowflake.bufferFrom(id));\n    }\n\n    var high32 = ((id[0] << 24) | (id[1] << 16) | (id[2] << 8) | id[3]) >>> 0;\n    var low32 = ((id[4] << 24) | (id[5] << 16) | (id[6] << 8) | id[7]) >>> 0;\n\n    return high32 * 0x400 + (low32 >>> 22) + this._epoch;\n  }\n\n  /**\n   * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given\n   * snowflake in sort order.\n   * @param a The first snowflake to compare.\n   * @param b The second snowflake to compare.\n   * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.\n   */\n  public static compare(\n    a: string | bigint | Uint8Array,\n    b: string | bigint | Uint8Array,\n  ): -1 | 0 | 1 {\n    if (isString(a)) {\n      a = BigInt(a);\n    } else if (a instanceof Uint8Array) {\n      a = bigIntFromBytes(a);\n    }\n\n    if (isString(b)) {\n      b = BigInt(b);\n    } else if (b instanceof Uint8Array) {\n      b = bigIntFromBytes(b);\n    }\n\n    return a === b ? 0 : a < b ? -1 : 1;\n  }\n\n  /**\n   * Parse value as Uint8Array buffer\n   */\n  public static bufferFrom(value: bigint | string): Uint8Array {\n    if (isString(value)) value = BigInt(value);\n\n    var buf = bigIntBytes(value);\n    var bufSize = buf.byteLength;\n\n    // Add padding\n    if (buf.byteLength < 8) {\n      var buf2 = new Uint8Array(8);\n      buf2.set(buf, 8 - bufSize);\n      buf = buf2;\n    }\n\n    return buf;\n  }\n}\n"],"names":["isDate","isNumber","timestampMs","isBigInt","bigIntBytes","isString","bigIntFromBytes"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,193 @@
+/**
+ * Object returned by Snowflake#deconstruct
+ */
+interface DeconstructedSnowflake {
+    /**
+     * The id as a number
+     */
+    id: bigint;
+    /**
+     * The timestamp stored in the snowflake
+     */
+    timestamp: number;
+    /**
+     * The worker id stored in the snowflake
+     */
+    workerId: number;
+    /**
+     * The process id stored in the snowflake
+     */
+    processId: number;
+    /**
+     * The increment stored in the snowflake
+     */
+    increment: number;
+    /**
+     * The epoch to use in the snowflake
+     */
+    epoch: number;
+}
+/**
+ * Options for Snowflake
+ */
+interface SnowflakeOptions {
+    /**
+     * Timestamp or date of the snowflake to generate
+     */
+    epoch: number | bigint | Date;
+    /**
+     * The increment to use
+     * @default 0
+     * @remark keep in mind that this number is auto-incremented between generate calls
+     */
+    increment?: number | bigint;
+    /**
+     * The worker ID to use, will be truncated to 5 bits (0-31)
+     * @default 0
+     */
+    workerId?: number | bigint;
+    /**
+     * The process ID to use, will be truncated to 5 bits (0-31)
+     * @default 1
+     */
+    processId?: number | bigint;
+}
+/**
+ * The maximum value the `workerId` field accepts in snowflakes.
+ */
+declare var MAX_WORKER_ID: number;
+/**
+ * The maximum value the `processId` field accepts in snowflakes.
+ */
+declare var MAX_PROCESS_ID: number;
+/**
+ * The maximum value the `increment` field accepts in snowflakes.
+ */
+declare var MAX_INCREMENT: number;
+/**
+ * A class for generating and deconstructing Twitter snowflakes.
+ *
+ * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}
+ * is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.
+ *
+ * If we have a snowflake `266241948824764416` we can represent it as binary:
+ * ```
+ * 64                                          22     17     12          0
+ *  000000111011000111100001101001000101000000  00001  00000  000000000000
+ *           number of ms since epoch           worker  pid    increment
+ * ```
+ *
+ * @group Main
+ */
+declare class Snowflake {
+    /**
+     * Alias for {@link deconstruct}
+     */
+    decode: (id: string | bigint | Uint8Array) => DeconstructedSnowflake;
+    /**
+     * Internal reference of the epoch passed in the constructor
+     * @internal
+     */
+    private readonly _epoch;
+    /**
+     * Internal incrementor for generating snowflakes
+     * @internal
+     */
+    private _increment;
+    /**
+     * The process ID that will be used by default in the generate method
+     * @internal
+     */
+    private _processId;
+    /**
+     * The worker ID that will be used by default in the generate method
+     * @internal
+     */
+    private _workerId;
+    /**
+     * @internal
+     */
+    private _buffer;
+    /**
+     * @param epoch the epoch to use
+     */
+    constructor(opts: SnowflakeOptions | Date | number | bigint);
+    /**
+     * The epoch for this snowflake, as a number
+     */
+    get epoch(): number;
+    /**
+     * Gets the configured process ID
+     */
+    get processId(): number;
+    /**
+     * Sets the process ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set processId(value: number | bigint);
+    /**
+     * Gets the configured worker ID
+     */
+    get workerId(): number;
+    /**
+     * Sets the worker ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set workerId(value: number | bigint);
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     */
+    generate(timestamp?: Date | number): bigint;
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     *
+     * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.
+     * Its contents may be overwritten on the next ID generation call.
+     *
+     * This method is intended for high-performance scenarios where you
+     * immediately transform the buffer (e.g., to base62) before calling again.
+     * Avoid storing or mutating the returned buffer directly.
+     */
+    generateBufferUnsafe(timestamp?: Date | number): Uint8Array;
+    /**
+     * Generates a snowflake given an epoch and optionally a timestamp
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake({ epoch }).generate();
+     * ```
+     * @returns A unique snowflake as Uint8Array
+     */
+    generateBuffer(timestamp?: Date | number): Uint8Array;
+    /**
+     * Deconstructs a snowflake given a snowflake ID
+     * @param id the snowflake to deconstruct
+     * @returns a deconstructed snowflake
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+     * ```
+     */
+    deconstruct(id: string | bigint | Uint8Array): DeconstructedSnowflake;
+    /**
+     * Retrieves the timestamp field's value from a snowflake.
+     * @param id The snowflake to get the timestamp value from.
+     * @returns The UNIX timestamp that is stored in `id`.
+     */
+    timestampFrom(id: string | bigint | Uint8Array): number;
+    /**
+     * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given
+     * snowflake in sort order.
+     * @param a The first snowflake to compare.
+     * @param b The second snowflake to compare.
+     * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.
+     */
+    static compare(a: string | bigint | Uint8Array, b: string | bigint | Uint8Array): -1 | 0 | 1;
+    /**
+     * Parse value as Uint8Array buffer
+     */
+    static bufferFrom(value: bigint | string): Uint8Array;
+}
+
+export { type DeconstructedSnowflake, MAX_INCREMENT, MAX_PROCESS_ID, MAX_WORKER_ID, Snowflake, type SnowflakeOptions };

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+/**
+ * Object returned by Snowflake#deconstruct
+ */
+interface DeconstructedSnowflake {
+    /**
+     * The id as a number
+     */
+    id: bigint;
+    /**
+     * The timestamp stored in the snowflake
+     */
+    timestamp: number;
+    /**
+     * The worker id stored in the snowflake
+     */
+    workerId: number;
+    /**
+     * The process id stored in the snowflake
+     */
+    processId: number;
+    /**
+     * The increment stored in the snowflake
+     */
+    increment: number;
+    /**
+     * The epoch to use in the snowflake
+     */
+    epoch: number;
+}
+/**
+ * Options for Snowflake
+ */
+interface SnowflakeOptions {
+    /**
+     * Timestamp or date of the snowflake to generate
+     */
+    epoch: number | bigint | Date;
+    /**
+     * The increment to use
+     * @default 0
+     * @remark keep in mind that this number is auto-incremented between generate calls
+     */
+    increment?: number | bigint;
+    /**
+     * The worker ID to use, will be truncated to 5 bits (0-31)
+     * @default 0
+     */
+    workerId?: number | bigint;
+    /**
+     * The process ID to use, will be truncated to 5 bits (0-31)
+     * @default 1
+     */
+    processId?: number | bigint;
+}
+/**
+ * The maximum value the `workerId` field accepts in snowflakes.
+ */
+declare var MAX_WORKER_ID: number;
+/**
+ * The maximum value the `processId` field accepts in snowflakes.
+ */
+declare var MAX_PROCESS_ID: number;
+/**
+ * The maximum value the `increment` field accepts in snowflakes.
+ */
+declare var MAX_INCREMENT: number;
+/**
+ * A class for generating and deconstructing Twitter snowflakes.
+ *
+ * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}
+ * is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.
+ *
+ * If we have a snowflake `266241948824764416` we can represent it as binary:
+ * ```
+ * 64                                          22     17     12          0
+ *  000000111011000111100001101001000101000000  00001  00000  000000000000
+ *           number of ms since epoch           worker  pid    increment
+ * ```
+ *
+ * @group Main
+ */
+declare class Snowflake {
+    /**
+     * Alias for {@link deconstruct}
+     */
+    decode: (id: string | bigint | Uint8Array) => DeconstructedSnowflake;
+    /**
+     * Internal reference of the epoch passed in the constructor
+     * @internal
+     */
+    private readonly _epoch;
+    /**
+     * Internal incrementor for generating snowflakes
+     * @internal
+     */
+    private _increment;
+    /**
+     * The process ID that will be used by default in the generate method
+     * @internal
+     */
+    private _processId;
+    /**
+     * The worker ID that will be used by default in the generate method
+     * @internal
+     */
+    private _workerId;
+    /**
+     * @internal
+     */
+    private _buffer;
+    /**
+     * @param epoch the epoch to use
+     */
+    constructor(opts: SnowflakeOptions | Date | number | bigint);
+    /**
+     * The epoch for this snowflake, as a number
+     */
+    get epoch(): number;
+    /**
+     * Gets the configured process ID
+     */
+    get processId(): number;
+    /**
+     * Sets the process ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set processId(value: number | bigint);
+    /**
+     * Gets the configured worker ID
+     */
+    get workerId(): number;
+    /**
+     * Sets the worker ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set workerId(value: number | bigint);
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     */
+    generate(timestamp?: Date | number): bigint;
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     *
+     * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.
+     * Its contents may be overwritten on the next ID generation call.
+     *
+     * This method is intended for high-performance scenarios where you
+     * immediately transform the buffer (e.g., to base62) before calling again.
+     * Avoid storing or mutating the returned buffer directly.
+     */
+    generateBufferUnsafe(timestamp?: Date | number): Uint8Array;
+    /**
+     * Generates a snowflake given an epoch and optionally a timestamp
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake({ epoch }).generate();
+     * ```
+     * @returns A unique snowflake as Uint8Array
+     */
+    generateBuffer(timestamp?: Date | number): Uint8Array;
+    /**
+     * Deconstructs a snowflake given a snowflake ID
+     * @param id the snowflake to deconstruct
+     * @returns a deconstructed snowflake
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+     * ```
+     */
+    deconstruct(id: string | bigint | Uint8Array): DeconstructedSnowflake;
+    /**
+     * Retrieves the timestamp field's value from a snowflake.
+     * @param id The snowflake to get the timestamp value from.
+     * @returns The UNIX timestamp that is stored in `id`.
+     */
+    timestampFrom(id: string | bigint | Uint8Array): number;
+    /**
+     * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given
+     * snowflake in sort order.
+     * @param a The first snowflake to compare.
+     * @param b The second snowflake to compare.
+     * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.
+     */
+    static compare(a: string | bigint | Uint8Array, b: string | bigint | Uint8Array): -1 | 0 | 1;
+    /**
+     * Parse value as Uint8Array buffer
+     */
+    static bufferFrom(value: bigint | string): Uint8Array;
+}
+
+export { type DeconstructedSnowflake, MAX_INCREMENT, MAX_PROCESS_ID, MAX_WORKER_ID, Snowflake, type SnowflakeOptions };

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Object returned by Snowflake#deconstruct
+ */
+interface DeconstructedSnowflake {
+    /**
+     * The id as a number
+     */
+    id: bigint;
+    /**
+     * The timestamp stored in the snowflake
+     */
+    timestamp: number;
+    /**
+     * The worker id stored in the snowflake
+     */
+    workerId: number;
+    /**
+     * The process id stored in the snowflake
+     */
+    processId: number;
+    /**
+     * The increment stored in the snowflake
+     */
+    increment: number;
+    /**
+     * The epoch to use in the snowflake
+     */
+    epoch: number;
+}
+/**
+ * Options for Snowflake
+ */
+interface SnowflakeOptions {
+    /**
+     * Timestamp or date of the snowflake to generate
+     */
+    epoch: number | bigint | Date;
+    /**
+     * The increment to use
+     * @default 0
+     * @remark keep in mind that this number is auto-incremented between generate calls
+     */
+    increment?: number | bigint;
+    /**
+     * The worker ID to use, will be truncated to 5 bits (0-31)
+     * @default 0
+     */
+    workerId?: number | bigint;
+    /**
+     * The process ID to use, will be truncated to 5 bits (0-31)
+     * @default 1
+     */
+    processId?: number | bigint;
+}
+/**
+ * The maximum value the `workerId` field accepts in snowflakes.
+ */
+declare var MAX_WORKER_ID: number;
+/**
+ * The maximum value the `processId` field accepts in snowflakes.
+ */
+declare var MAX_PROCESS_ID: number;
+/**
+ * The maximum value the `increment` field accepts in snowflakes.
+ */
+declare var MAX_INCREMENT: number;
+/**
+ * A class for generating and deconstructing Twitter snowflakes.
+ *
+ * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}
+ * is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.
+ *
+ * If we have a snowflake `266241948824764416` we can represent it as binary:
+ * ```
+ * 64                                          22     17     12          0
+ *  000000111011000111100001101001000101000000  00001  00000  000000000000
+ *           number of ms since epoch           worker  pid    increment
+ * ```
+ *
+ * @group Main
+ */
+declare class Snowflake {
+    /**
+     * Alias for {@link deconstruct}
+     */
+    decode: (id: string | bigint | Uint8Array) => DeconstructedSnowflake;
+    /**
+     * Internal reference of the epoch passed in the constructor
+     * @internal
+     */
+    private readonly _epoch;
+    /**
+     * Internal incrementor for generating snowflakes
+     * @internal
+     */
+    private _increment;
+    /**
+     * The process ID that will be used by default in the generate method
+     * @internal
+     */
+    private _processId;
+    /**
+     * The worker ID that will be used by default in the generate method
+     * @internal
+     */
+    private _workerId;
+    /**
+     * @internal
+     */
+    private _buffer;
+    /**
+     * @param epoch the epoch to use
+     */
+    constructor(opts: SnowflakeOptions | Date | number | bigint);
+    /**
+     * The epoch for this snowflake, as a number
+     */
+    get epoch(): number;
+    /**
+     * Gets the configured process ID
+     */
+    get processId(): number;
+    /**
+     * Sets the process ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set processId(value: number | bigint);
+    /**
+     * Gets the configured worker ID
+     */
+    get workerId(): number;
+    /**
+     * Sets the worker ID that will be used by default for the {@link generate} method
+     * @param value The new value, will be masked with `0b11111`
+     */
+    set workerId(value: number | bigint);
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     */
+    generate(timestamp?: Date | number): bigint;
+    /**
+     * Generates a Snowflake ID as a `Uint8Array` buffer.
+     *
+     * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.
+     * Its contents may be overwritten on the next ID generation call.
+     *
+     * This method is intended for high-performance scenarios where you
+     * immediately transform the buffer (e.g., to base62) before calling again.
+     * Avoid storing or mutating the returned buffer directly.
+     */
+    generateBufferUnsafe(timestamp?: Date | number): Uint8Array;
+    /**
+     * Generates a snowflake given an epoch and optionally a timestamp
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake({ epoch }).generate();
+     * ```
+     * @returns A unique snowflake as Uint8Array
+     */
+    generateBuffer(timestamp?: Date | number): Uint8Array;
+    /**
+     * Deconstructs a snowflake given a snowflake ID
+     * @param id the snowflake to deconstruct
+     * @returns a deconstructed snowflake
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+     * ```
+     */
+    deconstruct(id: string | bigint | Uint8Array): DeconstructedSnowflake;
+    /**
+     * Retrieves the timestamp field's value from a snowflake.
+     * @param id The snowflake to get the timestamp value from.
+     * @returns The UNIX timestamp that is stored in `id`.
+     */
+    timestampFrom(id: string | bigint | Uint8Array): number;
+    /**
+     * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given
+     * snowflake in sort order.
+     * @param a The first snowflake to compare.
+     * @param b The second snowflake to compare.
+     * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.
+     */
+    static compare(a: string | bigint | Uint8Array, b: string | bigint | Uint8Array): -1 | 0 | 1;
+    /**
+     * Parse value as Uint8Array buffer
+     */
+    static bufferFrom(value: bigint | string): Uint8Array;
+}
+
+export { type DeconstructedSnowflake, MAX_INCREMENT, MAX_PROCESS_ID, MAX_WORKER_ID, Snowflake, type SnowflakeOptions };

package/dist/index.mjs

@@ -0,0 +1,225 @@
+import { isDate, isNumber, timestampMs, isBigInt, bigIntBytes, isString, bigIntFromBytes } from '@andrew_l/toolkit';
+
+var MAX_WORKER_ID = 31;
+var MAX_PROCESS_ID = 31;
+var MAX_INCREMENT = 4095;
+class Snowflake {
+  /**
+   * Alias for {@link deconstruct}
+   */
+  decode = this.deconstruct;
+  /**
+   * Internal reference of the epoch passed in the constructor
+   * @internal
+   */
+  _epoch;
+  /**
+   * Internal incrementor for generating snowflakes
+   * @internal
+   */
+  _increment = 0;
+  /**
+   * The process ID that will be used by default in the generate method
+   * @internal
+   */
+  _processId = 1;
+  /**
+   * The worker ID that will be used by default in the generate method
+   * @internal
+   */
+  _workerId = 0;
+  /**
+   * @internal
+   */
+  _buffer;
+  /**
+   * @param epoch the epoch to use
+   */
+  constructor(opts) {
+    if (isDate(opts) || isNumber(opts)) {
+      this._epoch = timestampMs(opts);
+    } else if (isBigInt(opts)) {
+      this._epoch = timestampMs(Number(opts));
+    } else {
+      const { increment = 0, processId = 1, workerId = 0, epoch } = opts;
+      this._epoch = timestampMs(isBigInt(epoch) ? Number(epoch) : epoch);
+      this.workerId = workerId;
+      this.processId = processId;
+      this._increment = Number(increment) & MAX_INCREMENT;
+    }
+    this._buffer = new Uint8Array(8);
+  }
+  /**
+   * The epoch for this snowflake, as a number
+   */
+  get epoch() {
+    return this._epoch;
+  }
+  /**
+   * Gets the configured process ID
+   */
+  get processId() {
+    return this._processId;
+  }
+  /**
+   * Sets the process ID that will be used by default for the {@link generate} method
+   * @param value The new value, will be masked with `0b11111`
+   */
+  set processId(value) {
+    this._processId = Number(value) & MAX_PROCESS_ID;
+  }
+  /**
+   * Gets the configured worker ID
+   */
+  get workerId() {
+    return this._workerId;
+  }
+  /**
+   * Sets the worker ID that will be used by default for the {@link generate} method
+   * @param value The new value, will be masked with `0b11111`
+   */
+  set workerId(value) {
+    this._workerId = Number(value) & MAX_WORKER_ID;
+  }
+  /**
+   * Generates a Snowflake ID as a `Uint8Array` buffer.
+   */
+  generate(timestamp = Date.now()) {
+    if (timestamp instanceof Date) timestamp = timestamp.getTime();
+    if (!isNumber(timestamp)) {
+      throw new Error(
+        `"timestamp" argument must be a number or Date (received ${typeof timestamp})`
+      );
+    }
+    var increment = this._increment;
+    this._increment = this._increment + 1 & MAX_INCREMENT;
+    return BigInt(timestamp - this._epoch) << 22n | BigInt(this._workerId & MAX_WORKER_ID) << 17n | BigInt(this._processId & MAX_PROCESS_ID) << 12n | BigInt(increment & MAX_INCREMENT);
+  }
+  /**
+   * Generates a Snowflake ID as a `Uint8Array` buffer.
+   *
+   * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.
+   * Its contents may be overwritten on the next ID generation call.
+   *
+   * This method is intended for high-performance scenarios where you
+   * immediately transform the buffer (e.g., to base62) before calling again.
+   * Avoid storing or mutating the returned buffer directly.
+   */
+  generateBufferUnsafe(timestamp = Date.now()) {
+    if (timestamp instanceof Date) timestamp = timestamp.getTime();
+    if (!isNumber(timestamp)) {
+      throw new Error(
+        `"timestamp" argument must be a number or Date (received ${typeof timestamp})`
+      );
+    }
+    var increment = this._increment;
+    this._increment = this._increment + 1 & MAX_INCREMENT;
+    var timestampDelta = timestamp - this._epoch;
+    var timestampHigh = Math.floor(timestampDelta / 4294967295);
+    var timestampLow = timestampDelta >>> 0;
+    var high32 = (timestampHigh << 22 | timestampLow >>> 10) >>> 0;
+    var low32 = (timestampLow << 22 | this._workerId << 17 | this._processId << 12 | increment & MAX_INCREMENT) >>> 0;
+    var buffer = this._buffer;
+    buffer[0] = high32 >>> 24;
+    buffer[1] = high32 >>> 16;
+    buffer[2] = high32 >>> 8;
+    buffer[3] = high32;
+    buffer[4] = low32 >>> 24;
+    buffer[5] = low32 >>> 16;
+    buffer[6] = low32 >>> 8;
+    buffer[7] = low32;
+    return buffer;
+  }
+  /**
+   * Generates a snowflake given an epoch and optionally a timestamp
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake({ epoch }).generate();
+   * ```
+   * @returns A unique snowflake as Uint8Array
+   */
+  generateBuffer(timestamp = Date.now()) {
+    this.generateBufferUnsafe(timestamp);
+    return new Uint8Array(this._buffer);
+  }
+  /**
+   * Deconstructs a snowflake given a snowflake ID
+   * @param id the snowflake to deconstruct
+   * @returns a deconstructed snowflake
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+   * ```
+   */
+  deconstruct(id) {
+    var high32, low32;
+    if (id instanceof Uint8Array) {
+      high32 = (id[0] << 24 | id[1] << 16 | id[2] << 8 | id[3]) >>> 0;
+      low32 = (id[4] << 24 | id[5] << 16 | id[6] << 8 | id[7]) >>> 0;
+    } else if (isBigInt(id)) {
+      return this.deconstruct(bigIntBytes(id));
+    } else {
+      return this.deconstruct(bigIntBytes(BigInt(id)));
+    }
+    return {
+      id: BigInt(high32) * 0x100000000n + BigInt(low32),
+      timestamp: high32 * 1024 + (low32 >>> 22) + this._epoch,
+      workerId: low32 >>> 17 & MAX_WORKER_ID,
+      processId: low32 >>> 12 & MAX_PROCESS_ID,
+      increment: low32 & MAX_INCREMENT,
+      epoch: this._epoch
+    };
+  }
+  /**
+   * Retrieves the timestamp field's value from a snowflake.
+   * @param id The snowflake to get the timestamp value from.
+   * @returns The UNIX timestamp that is stored in `id`.
+   */
+  timestampFrom(id) {
+    if (isString(id) || isBigInt(id)) {
+      return this.timestampFrom(Snowflake.bufferFrom(id));
+    }
+    var high32 = (id[0] << 24 | id[1] << 16 | id[2] << 8 | id[3]) >>> 0;
+    var low32 = (id[4] << 24 | id[5] << 16 | id[6] << 8 | id[7]) >>> 0;
+    return high32 * 1024 + (low32 >>> 22) + this._epoch;
+  }
+  /**
+   * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given
+   * snowflake in sort order.
+   * @param a The first snowflake to compare.
+   * @param b The second snowflake to compare.
+   * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.
+   */
+  static compare(a, b) {
+    if (isString(a)) {
+      a = BigInt(a);
+    } else if (a instanceof Uint8Array) {
+      a = bigIntFromBytes(a);
+    }
+    if (isString(b)) {
+      b = BigInt(b);
+    } else if (b instanceof Uint8Array) {
+      b = bigIntFromBytes(b);
+    }
+    return a === b ? 0 : a < b ? -1 : 1;
+  }
+  /**
+   * Parse value as Uint8Array buffer
+   */
+  static bufferFrom(value) {
+    if (isString(value)) value = BigInt(value);
+    var buf = bigIntBytes(value);
+    var bufSize = buf.byteLength;
+    if (buf.byteLength < 8) {
+      var buf2 = new Uint8Array(8);
+      buf2.set(buf, 8 - bufSize);
+      buf = buf2;
+    }
+    return buf;
+  }
+}
+
+export { MAX_INCREMENT, MAX_PROCESS_ID, MAX_WORKER_ID, Snowflake };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/Snowflake.ts"],"sourcesContent":["/**\n * Based on: https://github.com/sapphiredev/utilities/blob/main/packages/snowflake/src/lib/Snowflake.ts\n */\nimport {\n  bigIntBytes,\n  bigIntFromBytes,\n  isBigInt,\n  isDate,\n  isNumber,\n  isString,\n  timestampMs,\n} from '@andrew_l/toolkit';\n\n/**\n * Object returned by Snowflake#deconstruct\n */\nexport interface DeconstructedSnowflake {\n  /**\n   * The id as a number\n   */\n  id: bigint;\n\n  /**\n   * The timestamp stored in the snowflake\n   */\n  timestamp: number;\n\n  /**\n   * The worker id stored in the snowflake\n   */\n  workerId: number;\n\n  /**\n   * The process id stored in the snowflake\n   */\n  processId: number;\n\n  /**\n   * The increment stored in the snowflake\n   */\n  increment: number;\n\n  /**\n   * The epoch to use in the snowflake\n   */\n  epoch: number;\n}\n\n/**\n * Options for Snowflake\n */\nexport interface SnowflakeOptions {\n  /**\n   * Timestamp or date of the snowflake to generate\n   */\n  epoch: number | bigint | Date;\n\n  /**\n   * The increment to use\n   * @default 0\n   * @remark keep in mind that this number is auto-incremented between generate calls\n   */\n  increment?: number | bigint;\n\n  /**\n   * The worker ID to use, will be truncated to 5 bits (0-31)\n   * @default 0\n   */\n  workerId?: number | bigint;\n\n  /**\n   * The process ID to use, will be truncated to 5 bits (0-31)\n   * @default 1\n   */\n  processId?: number | bigint;\n}\n\n/**\n * The maximum value the `workerId` field accepts in snowflakes.\n */\nexport var MAX_WORKER_ID = 0x1f;\n\n/**\n * The maximum value the `processId` field accepts in snowflakes.\n */\nexport var MAX_PROCESS_ID = 0x1f;\n\n/**\n * The maximum value the `increment` field accepts in snowflakes.\n */\nexport var MAX_INCREMENT = 0xfff;\n\n/**\n * A class for generating and deconstructing Twitter snowflakes.\n *\n * A {@link https://developer.twitter.com/en/docs/twitter-ids Twitter snowflake}\n * is a 64-bit unsigned integer with 4 fields that have a fixed epoch value.\n *\n * If we have a snowflake `266241948824764416` we can represent it as binary:\n * ```\n * 64                                          22     17     12          0\n *  000000111011000111100001101001000101000000  00001  00000  000000000000\n *           number of ms since epoch           worker  pid    increment\n * ```\n *\n * @group Main\n */\nexport class Snowflake {\n  /**\n   * Alias for {@link deconstruct}\n   */\n  public decode = this.deconstruct;\n\n  /**\n   * Internal reference of the epoch passed in the constructor\n   * @internal\n   */\n  private readonly _epoch: number;\n\n  /**\n   * Internal incrementor for generating snowflakes\n   * @internal\n   */\n  private _increment = 0;\n\n  /**\n   * The process ID that will be used by default in the generate method\n   * @internal\n   */\n  private _processId = 1;\n\n  /**\n   * The worker ID that will be used by default in the generate method\n   * @internal\n   */\n  private _workerId = 0;\n\n  /**\n   * @internal\n   */\n  private _buffer: Uint8Array;\n\n  /**\n   * @param epoch the epoch to use\n   */\n  public constructor(opts: SnowflakeOptions | Date | number | bigint) {\n    if (isDate(opts) || isNumber(opts)) {\n      this._epoch = timestampMs(opts);\n    } else if (isBigInt(opts)) {\n      this._epoch = timestampMs(Number(opts));\n    } else {\n      const { increment = 0, processId = 1, workerId = 0, epoch } = opts;\n      this._epoch = timestampMs(isBigInt(epoch) ? Number(epoch) : epoch);\n      this.workerId = workerId;\n      this.processId = processId;\n      this._increment = Number(increment) & MAX_INCREMENT;\n    }\n\n    this._buffer = new Uint8Array(8);\n  }\n\n  /**\n   * The epoch for this snowflake, as a number\n   */\n  public get epoch(): number {\n    return this._epoch;\n  }\n\n  /**\n   * Gets the configured process ID\n   */\n  public get processId(): number {\n    return this._processId;\n  }\n\n  /**\n   * Sets the process ID that will be used by default for the {@link generate} method\n   * @param value The new value, will be masked with `0b11111`\n   */\n  public set processId(value: number | bigint) {\n    this._processId = Number(value) & MAX_PROCESS_ID;\n  }\n\n  /**\n   * Gets the configured worker ID\n   */\n  public get workerId(): number {\n    return this._workerId;\n  }\n\n  /**\n   * Sets the worker ID that will be used by default for the {@link generate} method\n   * @param value The new value, will be masked with `0b11111`\n   */\n  public set workerId(value: number | bigint) {\n    this._workerId = Number(value) & MAX_WORKER_ID;\n  }\n\n  /**\n   * Generates a Snowflake ID as a `Uint8Array` buffer.\n   */\n  public generate(timestamp: Date | number = Date.now()): bigint {\n    if (timestamp instanceof Date) timestamp = timestamp.getTime();\n    if (!isNumber(timestamp)) {\n      throw new Error(\n        `\"timestamp\" argument must be a number or Date (received ${typeof timestamp})`,\n      );\n    }\n\n    var increment = this._increment;\n    this._increment = (this._increment + 1) & MAX_INCREMENT;\n\n    return (\n      (BigInt(timestamp - this._epoch) << 22n) |\n      (BigInt(this._workerId & MAX_WORKER_ID) << 17n) |\n      (BigInt(this._processId & MAX_PROCESS_ID) << 12n) |\n      BigInt(increment & MAX_INCREMENT)\n    );\n  }\n\n  /**\n   * Generates a Snowflake ID as a `Uint8Array` buffer.\n   *\n   * ⚠️ Returns a reference to the **same** internal `Uint8Array` instance.\n   * Its contents may be overwritten on the next ID generation call.\n   *\n   * This method is intended for high-performance scenarios where you\n   * immediately transform the buffer (e.g., to base62) before calling again.\n   * Avoid storing or mutating the returned buffer directly.\n   */\n  public generateBufferUnsafe(timestamp: Date | number = Date.now()) {\n    if (timestamp instanceof Date) timestamp = timestamp.getTime();\n    if (!isNumber(timestamp)) {\n      throw new Error(\n        `\"timestamp\" argument must be a number or Date (received ${typeof timestamp})`,\n      );\n    }\n\n    var increment = this._increment;\n    this._increment = (this._increment + 1) & MAX_INCREMENT;\n\n    // Calculate the timestamp delta\n    var timestampDelta = timestamp - this._epoch;\n\n    // Split into 32-bit parts for bitwise operations\n    var timestampHigh = Math.floor(timestampDelta / 0xffffffff);\n    var timestampLow = timestampDelta >>> 0;\n\n    var high32 = ((timestampHigh << 22) | (timestampLow >>> 10)) >>> 0;\n    var low32 =\n      ((timestampLow << 22) |\n        (this._workerId << 17) |\n        (this._processId << 12) |\n        (increment & MAX_INCREMENT)) >>>\n      0;\n\n    var buffer = this._buffer;\n\n    buffer[0] = high32 >>> 24;\n    buffer[1] = high32 >>> 16;\n    buffer[2] = high32 >>> 8;\n    buffer[3] = high32;\n    buffer[4] = low32 >>> 24;\n    buffer[5] = low32 >>> 16;\n    buffer[6] = low32 >>> 8;\n    buffer[7] = low32;\n\n    return buffer;\n  }\n\n  /**\n   * Generates a snowflake given an epoch and optionally a timestamp\n   * @example\n   * ```typescript\n   * const epoch = new Date('2000-01-01T00:00:00.000Z');\n   * const snowflake = new Snowflake({ epoch }).generate();\n   * ```\n   * @returns A unique snowflake as Uint8Array\n   */\n  public generateBuffer(timestamp: Date | number = Date.now()) {\n    this.generateBufferUnsafe(timestamp);\n    return new Uint8Array(this._buffer);\n  }\n\n  /**\n   * Deconstructs a snowflake given a snowflake ID\n   * @param id the snowflake to deconstruct\n   * @returns a deconstructed snowflake\n   * @example\n   * ```typescript\n   * const epoch = new Date('2000-01-01T00:00:00.000Z');\n   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');\n   * ```\n   */\n  public deconstruct(id: string | bigint | Uint8Array): DeconstructedSnowflake {\n    var high32: number, low32: number;\n\n    if (id instanceof Uint8Array) {\n      // Convert from Uint8Array\n      high32 = ((id[0] << 24) | (id[1] << 16) | (id[2] << 8) | id[3]) >>> 0;\n      low32 = ((id[4] << 24) | (id[5] << 16) | (id[6] << 8) | id[7]) >>> 0;\n    } else if (isBigInt(id)) {\n      return this.deconstruct(bigIntBytes(id));\n    } else {\n      // Convert from string\n      return this.deconstruct(bigIntBytes(BigInt(id)));\n    }\n\n    return {\n      id: BigInt(high32) * 0x100000000n + BigInt(low32),\n      timestamp: high32 * 0x400 + (low32 >>> 22) + this._epoch,\n      workerId: (low32 >>> 17) & MAX_WORKER_ID,\n      processId: (low32 >>> 12) & MAX_PROCESS_ID,\n      increment: low32 & MAX_INCREMENT,\n      epoch: this._epoch,\n    };\n  }\n\n  /**\n   * Retrieves the timestamp field's value from a snowflake.\n   * @param id The snowflake to get the timestamp value from.\n   * @returns The UNIX timestamp that is stored in `id`.\n   */\n  public timestampFrom(id: string | bigint | Uint8Array): number {\n    if (isString(id) || isBigInt(id)) {\n      return this.timestampFrom(Snowflake.bufferFrom(id));\n    }\n\n    var high32 = ((id[0] << 24) | (id[1] << 16) | (id[2] << 8) | id[3]) >>> 0;\n    var low32 = ((id[4] << 24) | (id[5] << 16) | (id[6] << 8) | id[7]) >>> 0;\n\n    return high32 * 0x400 + (low32 >>> 22) + this._epoch;\n  }\n\n  /**\n   * Returns a number indicating whether a reference snowflake comes before, or after, or is same as the given\n   * snowflake in sort order.\n   * @param a The first snowflake to compare.\n   * @param b The second snowflake to compare.\n   * @returns `-1` if `a` is older than `b`, `0` if `a` and `b` are equals, `1` if `a` is newer than `b`.\n   */\n  public static compare(\n    a: string | bigint | Uint8Array,\n    b: string | bigint | Uint8Array,\n  ): -1 | 0 | 1 {\n    if (isString(a)) {\n      a = BigInt(a);\n    } else if (a instanceof Uint8Array) {\n      a = bigIntFromBytes(a);\n    }\n\n    if (isString(b)) {\n      b = BigInt(b);\n    } else if (b instanceof Uint8Array) {\n      b = bigIntFromBytes(b);\n    }\n\n    return a === b ? 0 : a < b ? -1 : 1;\n  }\n\n  /**\n   * Parse value as Uint8Array buffer\n   */\n  public static bufferFrom(value: bigint | string): Uint8Array {\n    if (isString(value)) value = BigInt(value);\n\n    var buf = bigIntBytes(value);\n    var bufSize = buf.byteLength;\n\n    // Add padding\n    if (buf.byteLength < 8) {\n      var buf2 = new Uint8Array(8);\n      buf2.set(buf, 8 - bufSize);\n      buf = buf2;\n    }\n\n    return buf;\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@andrew_l/snowflake",
+  "version": "0.2.20",
+  "description": "Another implementation of snowflake id generator.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "snowflake",
+    "binary",
+    "buffer",
+    "serialization",
+    "deserialization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/men232/toolkit.git",
+    "directory": "packages/snowflake"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@andrew_l/toolkit": "0.2.20"
+  },
+  "devDependencies": {
+    "@sapphire/snowflake": "^3.5.5",
+    "@types/node": "22.10.5",
+    "typescript": "~5.6.2",
+    "unbuild": "3.0.0-rc.11",
+    "vitest": "^2.1.3"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest watch --typecheck",
+    "benchmark": "vitest bench watch ./benchmark",
+    "benchmark:watch": "vitest bench watch ./benchmark"
+  }
+}