@sodiumlabs/snowflake 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sodiumlabs
+
+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,74 @@
+<div align="center">
+    <h1>@sodiumlabs/snowflake</h1>
+    <p>
+        <a href="https://discord.gg/8PDXWSHH7k"><img src="https://img.shields.io/badge/join_us-on_discord-5865F2?logo=discord&logoColor=white" alt="Discord server" /></a>
+        <a href="https://www.npmjs.com/package/@sodiumlabs/snowflake"><img src="https://img.shields.io/npm/v/@sodiumlabs/snowflake.svg?maxAge=3600" alt="npm version" /></a>
+        <a href="https://www.npmjs.com/package/@sodiumlabs/snowflake"><img src="https://img.shields.io/npm/dt/@sodiumlabs/snowflake.svg?maxAge=3600" alt="npm downloads" /></a>
+        <a href="https://github.com/sodium-labs/utilities/commits/main/packages/snowflake"><img alt="Last commit" src="https://img.shields.io/github/last-commit/sodium-labs/utilities?logo=github&logoColor=ffffff&path=packages%2Fsnowflake" /></a>
+    </p>
+</div>
+
+## About
+
+Utility package to generate and deconstruct snowflakes. Snowflakes are unique IDs sortable by time and containing their creation timestamp within themselves. Read more about snowflakes on [Wikipedia](https://en.wikipedia.org/wiki/Snowflake_ID).
+
+## Installation
+
+Node.js 18 or newer is required.
+
+```sh
+npm install @sodiumlabs/snowflake
+```
+
+## Usage
+
+Using snowflakes
+
+```ts
+import { Snowflake } from "@sodiumlabs/snowflake";
+
+const epoch = new Date("2020-01-01T00:00:00.000Z");
+
+// Create an instance of Snowflake
+const snowflake = new Snowflake(epoch);
+
+// Generate a snowflake with the given epoch
+const uniqueId = snowflake.generate();
+```
+
+Snowflakes with Discord
+
+```ts
+import { discordSnowflake } from "@sodiumlabs/snowflake";
+
+// Extract only the timestamp from a snowflake
+const timestamp = discordSnowflake.timestampFrom("716068012414730320");
+// 1590794318060
+
+// Deconstruct the snowflake
+const data = discordSnowflake.deconstruct("716068012414730320");
+// {
+//   id: 716068012414730320n,
+//   timestamp: 1590794318060n,
+//   workerId: 0n,
+//   processId: 0n,
+//   increment: 80n,
+//   epoch: 1420070400000n
+// }
+```
+
+## Links
+
+- [Documentation](https://docs.sodiumlabs.xyz/docs/packages/snowflake/stable)
+- [Discord server](https://discord.gg/8PDXWSHH7k)
+- [GitHub](https://github.com/sodium-labs/utilities/tree/main/packages/snowflake)
+- [npm](https://npmjs.com/package/@sodiumlabs/snowflake)
+- [Sodium Labs](https://sodiumlabs.xyz)
+
+## Help
+
+Need help with the module? Ask on our [support server!](https://discord.gg/8PDXWSHH7k)
+
+# Credits
+
+This project also partially contains code derived or copied from [@sapphire/snowflake](https://github.com/sapphiredev/utilities/tree/main/packages/snowflake).

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+declare const IncrementSymbol: unique symbol;
+declare const EpochSymbol: unique symbol;
+declare const EpochNumberSymbol: unique symbol;
+declare const ProcessIdSymbol: unique symbol;
+declare const WorkerIdSymbol: unique symbol;
+/**
+ * The maximum value the `workerId` field accepts in snowflakes.
+ */
+declare const MaximumWorkerId = 31n;
+/**
+ * The maximum value the `processId` field accepts in snowflakes.
+ */
+declare const MaximumProcessId = 31n;
+/**
+ * The maximum value the `increment` field accepts in snowflakes.
+ */
+declare const MaximumIncrement = 4095n;
+/**
+ * A class for generating and deconstructing snowflakes.
+ *
+ * A {@link https://en.wikipedia.org/wiki/Snowflake_ID | 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
+ * ```
+ */
+declare class Snowflake {
+    /**
+     * Internal reference of the epoch passed in the constructor.
+     * @internal
+     */
+    private readonly [EpochSymbol];
+    /**
+     * Internal reference of the epoch passed in the constructor as a number.
+     * @internal
+     */
+    private readonly [EpochNumberSymbol];
+    /**
+     * Internal incrementor for generating snowflakes.
+     * @internal
+     */
+    private [IncrementSymbol];
+    /**
+     * The process ID that will be used by default in the generate method.
+     * @internal
+     */
+    private [ProcessIdSymbol];
+    /**
+     * The worker ID that will be used by default in the generate method.
+     * @internal
+     */
+    private [WorkerIdSymbol];
+    /**
+     * @param epoch - The epoch to use.
+     */
+    constructor(epoch: number | bigint | Date);
+    /**
+     * The epoch for this snowflake, as a bigint.
+     */
+    get epoch(): bigint;
+    /**
+     * The epoch for this snowflake, as a number.
+     */
+    get epochNumber(): number;
+    /**
+     * Gets or sets the configured process ID.
+     */
+    get processId(): bigint;
+    set processId(value: number | bigint);
+    /**
+     * Gets or sets the configured worker ID.
+     */
+    get workerId(): bigint;
+    set workerId(value: number | bigint);
+    /**
+     * Generates a snowflake given an epoch and optionally a timestamp.
+     *
+     * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.
+     *
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).generate();
+     * ```
+     *
+     * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.
+     * @returns A unique snowflake.
+     */
+    generate({ increment, timestamp, workerId, processId, }?: SnowflakeGenerateOptions): bigint;
+    /**
+     * Deconstructs a snowflake.
+     *
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+     * ```
+     *
+     * @param id - The snowflake to deconstruct.
+     * @returns A deconstructed snowflake.
+     */
+    deconstruct(id: string | bigint): 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): number;
+    /**
+     * Returns a number indicating whether a reference snowflake comes before,
+     * or after, or is same as the given snowflake in sort order.
+     *
+     * @example Sort snowflakes in ascending order
+     * ```typescript
+     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+     * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));
+     * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];
+     * ```
+     *
+     * @example Sort snowflakes in descending order
+     * ```typescript
+     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+     * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));
+     * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];
+     * ```
+     *
+     * @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, b: string | bigint): -1 | 0 | 1;
+}
+/**
+ * Options for `Snowflake#generate`.
+ */
+interface SnowflakeGenerateOptions {
+    /**
+     * Timestamp or date of the snowflake to generate.
+     *
+     * @defaultValue Date.now()
+     */
+    timestamp?: number | bigint | Date;
+    /**
+     * The increment to use.
+     *
+     * @defaultValue 0n
+     * @remarks keep in mind that this bigint is auto-incremented between generate calls.
+     */
+    increment?: bigint;
+    /**
+     * The worker ID to use, will be truncated to 5 bits (0-31).
+     *
+     * @defaultValue 0n
+     */
+    workerId?: bigint;
+    /**
+     * The process ID to use, will be truncated to 5 bits (0-31).
+     *
+     * @defaultValue 1n
+     */
+    processId?: bigint;
+}
+/**
+ * Object returned by `Snowflake#deconstruct`.
+ */
+interface DeconstructedSnowflake {
+    /**
+     * The id in BigInt form.
+     */
+    id: bigint;
+    /**
+     * The timestamp stored in the snowflake.
+     */
+    timestamp: bigint;
+    /**
+     * The worker id stored in the snowflake.
+     */
+    workerId: bigint;
+    /**
+     * The process id stored in the snowflake.
+     */
+    processId: bigint;
+    /**
+     * The increment stored in the snowflake.
+     */
+    increment: bigint;
+    /**
+     * The epoch to use in the snowflake.
+     */
+    epoch: bigint;
+}
+
+/**
+ * A class for parsing snowflake ids using Discord's snowflake epoch.
+ *
+ * The Discord epoch is `1420070400000` (`2015-01-01T00:00:00.000Z`), see {@link https://discord.com/developers/docs/reference#snowflakes}.
+ */
+declare const discordSnowflake: Snowflake;
+
+export { type DeconstructedSnowflake, MaximumIncrement, MaximumProcessId, MaximumWorkerId, Snowflake, type SnowflakeGenerateOptions, discordSnowflake };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+declare const IncrementSymbol: unique symbol;
+declare const EpochSymbol: unique symbol;
+declare const EpochNumberSymbol: unique symbol;
+declare const ProcessIdSymbol: unique symbol;
+declare const WorkerIdSymbol: unique symbol;
+/**
+ * The maximum value the `workerId` field accepts in snowflakes.
+ */
+declare const MaximumWorkerId = 31n;
+/**
+ * The maximum value the `processId` field accepts in snowflakes.
+ */
+declare const MaximumProcessId = 31n;
+/**
+ * The maximum value the `increment` field accepts in snowflakes.
+ */
+declare const MaximumIncrement = 4095n;
+/**
+ * A class for generating and deconstructing snowflakes.
+ *
+ * A {@link https://en.wikipedia.org/wiki/Snowflake_ID | 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
+ * ```
+ */
+declare class Snowflake {
+    /**
+     * Internal reference of the epoch passed in the constructor.
+     * @internal
+     */
+    private readonly [EpochSymbol];
+    /**
+     * Internal reference of the epoch passed in the constructor as a number.
+     * @internal
+     */
+    private readonly [EpochNumberSymbol];
+    /**
+     * Internal incrementor for generating snowflakes.
+     * @internal
+     */
+    private [IncrementSymbol];
+    /**
+     * The process ID that will be used by default in the generate method.
+     * @internal
+     */
+    private [ProcessIdSymbol];
+    /**
+     * The worker ID that will be used by default in the generate method.
+     * @internal
+     */
+    private [WorkerIdSymbol];
+    /**
+     * @param epoch - The epoch to use.
+     */
+    constructor(epoch: number | bigint | Date);
+    /**
+     * The epoch for this snowflake, as a bigint.
+     */
+    get epoch(): bigint;
+    /**
+     * The epoch for this snowflake, as a number.
+     */
+    get epochNumber(): number;
+    /**
+     * Gets or sets the configured process ID.
+     */
+    get processId(): bigint;
+    set processId(value: number | bigint);
+    /**
+     * Gets or sets the configured worker ID.
+     */
+    get workerId(): bigint;
+    set workerId(value: number | bigint);
+    /**
+     * Generates a snowflake given an epoch and optionally a timestamp.
+     *
+     * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.
+     *
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).generate();
+     * ```
+     *
+     * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.
+     * @returns A unique snowflake.
+     */
+    generate({ increment, timestamp, workerId, processId, }?: SnowflakeGenerateOptions): bigint;
+    /**
+     * Deconstructs a snowflake.
+     *
+     * @example
+     * ```typescript
+     * const epoch = new Date('2000-01-01T00:00:00.000Z');
+     * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+     * ```
+     *
+     * @param id - The snowflake to deconstruct.
+     * @returns A deconstructed snowflake.
+     */
+    deconstruct(id: string | bigint): 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): number;
+    /**
+     * Returns a number indicating whether a reference snowflake comes before,
+     * or after, or is same as the given snowflake in sort order.
+     *
+     * @example Sort snowflakes in ascending order
+     * ```typescript
+     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+     * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));
+     * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];
+     * ```
+     *
+     * @example Sort snowflakes in descending order
+     * ```typescript
+     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+     * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));
+     * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];
+     * ```
+     *
+     * @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, b: string | bigint): -1 | 0 | 1;
+}
+/**
+ * Options for `Snowflake#generate`.
+ */
+interface SnowflakeGenerateOptions {
+    /**
+     * Timestamp or date of the snowflake to generate.
+     *
+     * @defaultValue Date.now()
+     */
+    timestamp?: number | bigint | Date;
+    /**
+     * The increment to use.
+     *
+     * @defaultValue 0n
+     * @remarks keep in mind that this bigint is auto-incremented between generate calls.
+     */
+    increment?: bigint;
+    /**
+     * The worker ID to use, will be truncated to 5 bits (0-31).
+     *
+     * @defaultValue 0n
+     */
+    workerId?: bigint;
+    /**
+     * The process ID to use, will be truncated to 5 bits (0-31).
+     *
+     * @defaultValue 1n
+     */
+    processId?: bigint;
+}
+/**
+ * Object returned by `Snowflake#deconstruct`.
+ */
+interface DeconstructedSnowflake {
+    /**
+     * The id in BigInt form.
+     */
+    id: bigint;
+    /**
+     * The timestamp stored in the snowflake.
+     */
+    timestamp: bigint;
+    /**
+     * The worker id stored in the snowflake.
+     */
+    workerId: bigint;
+    /**
+     * The process id stored in the snowflake.
+     */
+    processId: bigint;
+    /**
+     * The increment stored in the snowflake.
+     */
+    increment: bigint;
+    /**
+     * The epoch to use in the snowflake.
+     */
+    epoch: bigint;
+}
+
+/**
+ * A class for parsing snowflake ids using Discord's snowflake epoch.
+ *
+ * The Discord epoch is `1420070400000` (`2015-01-01T00:00:00.000Z`), see {@link https://discord.com/developers/docs/reference#snowflakes}.
+ */
+declare const discordSnowflake: Snowflake;
+
+export { type DeconstructedSnowflake, MaximumIncrement, MaximumProcessId, MaximumWorkerId, Snowflake, type SnowflakeGenerateOptions, discordSnowflake };

package/dist/index.js

@@ -0,0 +1,219 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MaximumIncrement: () => MaximumIncrement,
+  MaximumProcessId: () => MaximumProcessId,
+  MaximumWorkerId: () => MaximumWorkerId,
+  Snowflake: () => Snowflake,
+  discordSnowflake: () => discordSnowflake
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/snowflake.ts
+var IncrementSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.increment");
+var EpochSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.epoch");
+var EpochNumberSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.epoch.number");
+var ProcessIdSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.processId");
+var WorkerIdSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.workerId");
+var MaximumWorkerId = 0b11111n;
+var MaximumProcessId = 0b11111n;
+var MaximumIncrement = 0b111111111111n;
+var Snowflake = class {
+  static {
+    __name(this, "Snowflake");
+  }
+  /**
+   * Internal reference of the epoch passed in the constructor.
+   * @internal
+   */
+  [EpochSymbol];
+  /**
+   * Internal reference of the epoch passed in the constructor as a number.
+   * @internal
+   */
+  [EpochNumberSymbol];
+  /**
+   * Internal incrementor for generating snowflakes.
+   * @internal
+   */
+  [IncrementSymbol] = 0n;
+  /**
+   * The process ID that will be used by default in the generate method.
+   * @internal
+   */
+  [ProcessIdSymbol] = 1n;
+  /**
+   * The worker ID that will be used by default in the generate method.
+   * @internal
+   */
+  [WorkerIdSymbol] = 0n;
+  /**
+   * @param epoch - The epoch to use.
+   */
+  constructor(epoch) {
+    this[EpochSymbol] = BigInt(epoch instanceof Date ? epoch.getTime() : epoch);
+    this[EpochNumberSymbol] = Number(this[EpochSymbol]);
+  }
+  /**
+   * The epoch for this snowflake, as a bigint.
+   */
+  get epoch() {
+    return this[EpochSymbol];
+  }
+  /**
+   * The epoch for this snowflake, as a number.
+   */
+  get epochNumber() {
+    return this[EpochNumberSymbol];
+  }
+  /**
+   * Gets or sets the configured process ID.
+   */
+  get processId() {
+    return this[ProcessIdSymbol];
+  }
+  set processId(value) {
+    this[ProcessIdSymbol] = BigInt(value) & MaximumProcessId;
+  }
+  /**
+   * Gets or sets the configured worker ID.
+   */
+  get workerId() {
+    return this[WorkerIdSymbol];
+  }
+  set workerId(value) {
+    this[WorkerIdSymbol] = BigInt(value) & MaximumWorkerId;
+  }
+  /**
+   * Generates a snowflake given an epoch and optionally a timestamp.
+   *
+   * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.
+   *
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).generate();
+   * ```
+   *
+   * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.
+   * @returns A unique snowflake.
+   */
+  generate({
+    increment,
+    timestamp = Date.now(),
+    workerId = this[WorkerIdSymbol],
+    processId = this[ProcessIdSymbol]
+  } = {}) {
+    if (timestamp instanceof Date) timestamp = BigInt(timestamp.getTime());
+    else if (typeof timestamp === "number") timestamp = BigInt(timestamp);
+    else if (typeof timestamp !== "bigint") {
+      throw new TypeError(
+        `"timestamp" argument must be a number, bigint, or Date (received ${typeof timestamp})`
+      );
+    }
+    if (typeof increment !== "bigint") {
+      increment = this[IncrementSymbol];
+      this[IncrementSymbol] = increment + 1n & MaximumIncrement;
+    }
+    return timestamp - this[EpochSymbol] << 22n | (workerId & MaximumWorkerId) << 17n | (processId & MaximumProcessId) << 12n | increment & MaximumIncrement;
+  }
+  /**
+   * Deconstructs a snowflake.
+   *
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+   * ```
+   *
+   * @param id - The snowflake to deconstruct.
+   * @returns A deconstructed snowflake.
+   */
+  deconstruct(id) {
+    const bigIntId = BigInt(id);
+    const epoch = this[EpochSymbol];
+    return {
+      id: bigIntId,
+      timestamp: (bigIntId >> 22n) + epoch,
+      workerId: bigIntId >> 17n & MaximumWorkerId,
+      processId: bigIntId >> 12n & MaximumProcessId,
+      increment: bigIntId & MaximumIncrement,
+      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) {
+    return Number((BigInt(id) >> 22n) + this.epoch);
+  }
+  /**
+   * Returns a number indicating whether a reference snowflake comes before,
+   * or after, or is same as the given snowflake in sort order.
+   *
+   * @example Sort snowflakes in ascending order
+   * ```typescript
+   * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+   * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));
+   * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];
+   * ```
+   *
+   * @example Sort snowflakes in descending order
+   * ```typescript
+   * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+   * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));
+   * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];
+   * ```
+   *
+   * @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) {
+    const typeA = typeof a;
+    return typeA === typeof b ? typeA === "string" ? cmpString(a, b) : cmpBigInt(a, b) : cmpBigInt(BigInt(a), BigInt(b));
+  }
+};
+function cmpBigInt(a, b) {
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+__name(cmpBigInt, "cmpBigInt");
+function cmpString(a, b) {
+  return a === b ? 0 : a.length < b.length ? -1 : a.length > b.length ? 1 : a < b ? -1 : 1;
+}
+__name(cmpString, "cmpString");
+
+// src/discord-snowflake.ts
+var discordSnowflake = new Snowflake(1420070400000n);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MaximumIncrement,
+  MaximumProcessId,
+  MaximumWorkerId,
+  Snowflake,
+  discordSnowflake
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/snowflake.ts","../src/discord-snowflake.ts"],"sourcesContent":["export * from \"./snowflake\";\nexport * from \"./discord-snowflake\";\n","const IncrementSymbol = Symbol(\"@sodiumlabs/snowflake.increment\");\nconst EpochSymbol = Symbol(\"@sodiumlabs/snowflake.epoch\");\nconst EpochNumberSymbol = Symbol(\"@sodiumlabs/snowflake.epoch.number\");\nconst ProcessIdSymbol = Symbol(\"@sodiumlabs/snowflake.processId\");\nconst WorkerIdSymbol = Symbol(\"@sodiumlabs/snowflake.workerId\");\n\n/**\n * The maximum value the `workerId` field accepts in snowflakes.\n */\nexport const MaximumWorkerId = 0b11111n;\n\n/**\n * The maximum value the `processId` field accepts in snowflakes.\n */\nexport const MaximumProcessId = 0b11111n;\n\n/**\n * The maximum value the `increment` field accepts in snowflakes.\n */\nexport const MaximumIncrement = 0b111111111111n;\n\n/**\n * A class for generating and deconstructing snowflakes.\n *\n * A {@link https://en.wikipedia.org/wiki/Snowflake_ID | 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 */\nexport class Snowflake {\n    /**\n     * Internal reference of the epoch passed in the constructor.\n     * @internal\n     */\n    private readonly [EpochSymbol]: bigint;\n\n    /**\n     * Internal reference of the epoch passed in the constructor as a number.\n     * @internal\n     */\n    private readonly [EpochNumberSymbol]: number;\n\n    /**\n     * Internal incrementor for generating snowflakes.\n     * @internal\n     */\n    private [IncrementSymbol] = 0n;\n\n    /**\n     * The process ID that will be used by default in the generate method.\n     * @internal\n     */\n    private [ProcessIdSymbol] = 1n;\n\n    /**\n     * The worker ID that will be used by default in the generate method.\n     * @internal\n     */\n    private [WorkerIdSymbol] = 0n;\n\n    /**\n     * @param epoch - The epoch to use.\n     */\n    public constructor(epoch: number | bigint | Date) {\n        this[EpochSymbol] = BigInt(epoch instanceof Date ? epoch.getTime() : epoch);\n        this[EpochNumberSymbol] = Number(this[EpochSymbol]);\n    }\n\n    /**\n     * The epoch for this snowflake, as a bigint.\n     */\n    public get epoch(): bigint {\n        return this[EpochSymbol];\n    }\n\n    /**\n     * The epoch for this snowflake, as a number.\n     */\n    public get epochNumber(): number {\n        return this[EpochNumberSymbol];\n    }\n\n    /**\n     * Gets or sets the configured process ID.\n     */\n    public get processId(): bigint {\n        return this[ProcessIdSymbol];\n    }\n\n    public set processId(value: number | bigint) {\n        this[ProcessIdSymbol] = BigInt(value) & MaximumProcessId;\n    }\n\n    /**\n     * Gets or sets the configured worker ID.\n     */\n    public get workerId(): bigint {\n        return this[WorkerIdSymbol];\n    }\n\n    public set workerId(value: number | bigint) {\n        this[WorkerIdSymbol] = BigInt(value) & MaximumWorkerId;\n    }\n\n    /**\n     * Generates a snowflake given an epoch and optionally a timestamp.\n     *\n     * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.\n     *\n     * @example\n     * ```typescript\n     * const epoch = new Date('2000-01-01T00:00:00.000Z');\n     * const snowflake = new Snowflake(epoch).generate();\n     * ```\n     *\n     * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.\n     * @returns A unique snowflake.\n     */\n    public generate({\n        increment,\n        timestamp = Date.now(),\n        workerId = this[WorkerIdSymbol],\n        processId = this[ProcessIdSymbol],\n    }: SnowflakeGenerateOptions = {}) {\n        if (timestamp instanceof Date) timestamp = BigInt(timestamp.getTime());\n        else if (typeof timestamp === \"number\") timestamp = BigInt(timestamp);\n        else if (typeof timestamp !== \"bigint\") {\n            throw new TypeError(\n                `\"timestamp\" argument must be a number, bigint, or Date (received ${typeof timestamp})`,\n            );\n        }\n\n        if (typeof increment !== \"bigint\") {\n            increment = this[IncrementSymbol];\n            this[IncrementSymbol] = (increment + 1n) & MaximumIncrement;\n        }\n\n        // timestamp, workerId, processId, increment\n        return (\n            ((timestamp - this[EpochSymbol]) << 22n) |\n            ((workerId & MaximumWorkerId) << 17n) |\n            ((processId & MaximumProcessId) << 12n) |\n            (increment & MaximumIncrement)\n        );\n    }\n\n    /**\n     * Deconstructs a snowflake.\n     *\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     * @param id - The snowflake to deconstruct.\n     * @returns A deconstructed snowflake.\n     */\n    public deconstruct(id: string | bigint): DeconstructedSnowflake {\n        const bigIntId = BigInt(id);\n        const epoch = this[EpochSymbol];\n        return {\n            id: bigIntId,\n            timestamp: (bigIntId >> 22n) + epoch,\n            workerId: (bigIntId >> 17n) & MaximumWorkerId,\n            processId: (bigIntId >> 12n) & MaximumProcessId,\n            increment: bigIntId & MaximumIncrement,\n            epoch,\n        };\n    }\n\n    /**\n     * Retrieves the timestamp field's value from a snowflake.\n     *\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): number {\n        return Number((BigInt(id) >> 22n) + this.epoch);\n    }\n\n    /**\n     * Returns a number indicating whether a reference snowflake comes before,\n     * or after, or is same as the given snowflake in sort order.\n     *\n     * @example Sort snowflakes in ascending order\n     * ```typescript\n     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];\n     * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));\n     * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];\n     * ```\n     *\n     * @example Sort snowflakes in descending order\n     * ```typescript\n     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];\n     * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));\n     * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];\n     * ```\n     *\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(a: string | bigint, b: string | bigint): -1 | 0 | 1 {\n        const typeA = typeof a;\n        return typeA === typeof b\n            ? typeA === \"string\"\n                ? cmpString(a as string, b as string)\n                : cmpBigInt(a as bigint, b as bigint)\n            : cmpBigInt(BigInt(a), BigInt(b));\n    }\n}\n\n/** @internal */\nfunction cmpBigInt(a: bigint, b: bigint) {\n    return a === b ? 0 : a < b ? -1 : 1;\n}\n\n/** @internal */\nfunction cmpString(a: string, b: string) {\n    return a === b ? 0 : a.length < b.length ? -1 : a.length > b.length ? 1 : a < b ? -1 : 1;\n}\n\n/**\n * Options for `Snowflake#generate`.\n */\nexport interface SnowflakeGenerateOptions {\n    /**\n     * Timestamp or date of the snowflake to generate.\n     *\n     * @defaultValue Date.now()\n     */\n    timestamp?: number | bigint | Date;\n    /**\n     * The increment to use.\n     *\n     * @defaultValue 0n\n     * @remarks keep in mind that this bigint is auto-incremented between generate calls.\n     */\n    increment?: bigint;\n    /**\n     * The worker ID to use, will be truncated to 5 bits (0-31).\n     *\n     * @defaultValue 0n\n     */\n    workerId?: bigint;\n    /**\n     * The process ID to use, will be truncated to 5 bits (0-31).\n     *\n     * @defaultValue 1n\n     */\n    processId?: bigint;\n}\n\n/**\n * Object returned by `Snowflake#deconstruct`.\n */\nexport interface DeconstructedSnowflake {\n    /**\n     * The id in BigInt form.\n     */\n    id: bigint;\n    /**\n     * The timestamp stored in the snowflake.\n     */\n    timestamp: bigint;\n    /**\n     * The worker id stored in the snowflake.\n     */\n    workerId: bigint;\n    /**\n     * The process id stored in the snowflake.\n     */\n    processId: bigint;\n    /**\n     * The increment stored in the snowflake.\n     */\n    increment: bigint;\n    /**\n     * The epoch to use in the snowflake.\n     */\n    epoch: bigint;\n}\n","import { Snowflake } from \"./snowflake\";\n\n/**\n * A class for parsing snowflake ids using Discord's snowflake epoch.\n *\n * The Discord epoch is `1420070400000` (`2015-01-01T00:00:00.000Z`), see {@link https://discord.com/developers/docs/reference#snowflakes}.\n */\nexport const discordSnowflake = new Snowflake(1420070400000n);\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,190 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/snowflake.ts
+var IncrementSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.increment");
+var EpochSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.epoch");
+var EpochNumberSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.epoch.number");
+var ProcessIdSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.processId");
+var WorkerIdSymbol = /* @__PURE__ */ Symbol("@sodiumlabs/snowflake.workerId");
+var MaximumWorkerId = 0b11111n;
+var MaximumProcessId = 0b11111n;
+var MaximumIncrement = 0b111111111111n;
+var Snowflake = class {
+  static {
+    __name(this, "Snowflake");
+  }
+  /**
+   * Internal reference of the epoch passed in the constructor.
+   * @internal
+   */
+  [EpochSymbol];
+  /**
+   * Internal reference of the epoch passed in the constructor as a number.
+   * @internal
+   */
+  [EpochNumberSymbol];
+  /**
+   * Internal incrementor for generating snowflakes.
+   * @internal
+   */
+  [IncrementSymbol] = 0n;
+  /**
+   * The process ID that will be used by default in the generate method.
+   * @internal
+   */
+  [ProcessIdSymbol] = 1n;
+  /**
+   * The worker ID that will be used by default in the generate method.
+   * @internal
+   */
+  [WorkerIdSymbol] = 0n;
+  /**
+   * @param epoch - The epoch to use.
+   */
+  constructor(epoch) {
+    this[EpochSymbol] = BigInt(epoch instanceof Date ? epoch.getTime() : epoch);
+    this[EpochNumberSymbol] = Number(this[EpochSymbol]);
+  }
+  /**
+   * The epoch for this snowflake, as a bigint.
+   */
+  get epoch() {
+    return this[EpochSymbol];
+  }
+  /**
+   * The epoch for this snowflake, as a number.
+   */
+  get epochNumber() {
+    return this[EpochNumberSymbol];
+  }
+  /**
+   * Gets or sets the configured process ID.
+   */
+  get processId() {
+    return this[ProcessIdSymbol];
+  }
+  set processId(value) {
+    this[ProcessIdSymbol] = BigInt(value) & MaximumProcessId;
+  }
+  /**
+   * Gets or sets the configured worker ID.
+   */
+  get workerId() {
+    return this[WorkerIdSymbol];
+  }
+  set workerId(value) {
+    this[WorkerIdSymbol] = BigInt(value) & MaximumWorkerId;
+  }
+  /**
+   * Generates a snowflake given an epoch and optionally a timestamp.
+   *
+   * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.
+   *
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).generate();
+   * ```
+   *
+   * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.
+   * @returns A unique snowflake.
+   */
+  generate({
+    increment,
+    timestamp = Date.now(),
+    workerId = this[WorkerIdSymbol],
+    processId = this[ProcessIdSymbol]
+  } = {}) {
+    if (timestamp instanceof Date) timestamp = BigInt(timestamp.getTime());
+    else if (typeof timestamp === "number") timestamp = BigInt(timestamp);
+    else if (typeof timestamp !== "bigint") {
+      throw new TypeError(
+        `"timestamp" argument must be a number, bigint, or Date (received ${typeof timestamp})`
+      );
+    }
+    if (typeof increment !== "bigint") {
+      increment = this[IncrementSymbol];
+      this[IncrementSymbol] = increment + 1n & MaximumIncrement;
+    }
+    return timestamp - this[EpochSymbol] << 22n | (workerId & MaximumWorkerId) << 17n | (processId & MaximumProcessId) << 12n | increment & MaximumIncrement;
+  }
+  /**
+   * Deconstructs a snowflake.
+   *
+   * @example
+   * ```typescript
+   * const epoch = new Date('2000-01-01T00:00:00.000Z');
+   * const snowflake = new Snowflake(epoch).deconstruct('3971046231244935168');
+   * ```
+   *
+   * @param id - The snowflake to deconstruct.
+   * @returns A deconstructed snowflake.
+   */
+  deconstruct(id) {
+    const bigIntId = BigInt(id);
+    const epoch = this[EpochSymbol];
+    return {
+      id: bigIntId,
+      timestamp: (bigIntId >> 22n) + epoch,
+      workerId: bigIntId >> 17n & MaximumWorkerId,
+      processId: bigIntId >> 12n & MaximumProcessId,
+      increment: bigIntId & MaximumIncrement,
+      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) {
+    return Number((BigInt(id) >> 22n) + this.epoch);
+  }
+  /**
+   * Returns a number indicating whether a reference snowflake comes before,
+   * or after, or is same as the given snowflake in sort order.
+   *
+   * @example Sort snowflakes in ascending order
+   * ```typescript
+   * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+   * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));
+   * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];
+   * ```
+   *
+   * @example Sort snowflakes in descending order
+   * ```typescript
+   * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];
+   * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));
+   * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];
+   * ```
+   *
+   * @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) {
+    const typeA = typeof a;
+    return typeA === typeof b ? typeA === "string" ? cmpString(a, b) : cmpBigInt(a, b) : cmpBigInt(BigInt(a), BigInt(b));
+  }
+};
+function cmpBigInt(a, b) {
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+__name(cmpBigInt, "cmpBigInt");
+function cmpString(a, b) {
+  return a === b ? 0 : a.length < b.length ? -1 : a.length > b.length ? 1 : a < b ? -1 : 1;
+}
+__name(cmpString, "cmpString");
+
+// src/discord-snowflake.ts
+var discordSnowflake = new Snowflake(1420070400000n);
+export {
+  MaximumIncrement,
+  MaximumProcessId,
+  MaximumWorkerId,
+  Snowflake,
+  discordSnowflake
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/snowflake.ts","../src/discord-snowflake.ts"],"sourcesContent":["const IncrementSymbol = Symbol(\"@sodiumlabs/snowflake.increment\");\nconst EpochSymbol = Symbol(\"@sodiumlabs/snowflake.epoch\");\nconst EpochNumberSymbol = Symbol(\"@sodiumlabs/snowflake.epoch.number\");\nconst ProcessIdSymbol = Symbol(\"@sodiumlabs/snowflake.processId\");\nconst WorkerIdSymbol = Symbol(\"@sodiumlabs/snowflake.workerId\");\n\n/**\n * The maximum value the `workerId` field accepts in snowflakes.\n */\nexport const MaximumWorkerId = 0b11111n;\n\n/**\n * The maximum value the `processId` field accepts in snowflakes.\n */\nexport const MaximumProcessId = 0b11111n;\n\n/**\n * The maximum value the `increment` field accepts in snowflakes.\n */\nexport const MaximumIncrement = 0b111111111111n;\n\n/**\n * A class for generating and deconstructing snowflakes.\n *\n * A {@link https://en.wikipedia.org/wiki/Snowflake_ID | 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 */\nexport class Snowflake {\n    /**\n     * Internal reference of the epoch passed in the constructor.\n     * @internal\n     */\n    private readonly [EpochSymbol]: bigint;\n\n    /**\n     * Internal reference of the epoch passed in the constructor as a number.\n     * @internal\n     */\n    private readonly [EpochNumberSymbol]: number;\n\n    /**\n     * Internal incrementor for generating snowflakes.\n     * @internal\n     */\n    private [IncrementSymbol] = 0n;\n\n    /**\n     * The process ID that will be used by default in the generate method.\n     * @internal\n     */\n    private [ProcessIdSymbol] = 1n;\n\n    /**\n     * The worker ID that will be used by default in the generate method.\n     * @internal\n     */\n    private [WorkerIdSymbol] = 0n;\n\n    /**\n     * @param epoch - The epoch to use.\n     */\n    public constructor(epoch: number | bigint | Date) {\n        this[EpochSymbol] = BigInt(epoch instanceof Date ? epoch.getTime() : epoch);\n        this[EpochNumberSymbol] = Number(this[EpochSymbol]);\n    }\n\n    /**\n     * The epoch for this snowflake, as a bigint.\n     */\n    public get epoch(): bigint {\n        return this[EpochSymbol];\n    }\n\n    /**\n     * The epoch for this snowflake, as a number.\n     */\n    public get epochNumber(): number {\n        return this[EpochNumberSymbol];\n    }\n\n    /**\n     * Gets or sets the configured process ID.\n     */\n    public get processId(): bigint {\n        return this[ProcessIdSymbol];\n    }\n\n    public set processId(value: number | bigint) {\n        this[ProcessIdSymbol] = BigInt(value) & MaximumProcessId;\n    }\n\n    /**\n     * Gets or sets the configured worker ID.\n     */\n    public get workerId(): bigint {\n        return this[WorkerIdSymbol];\n    }\n\n    public set workerId(value: number | bigint) {\n        this[WorkerIdSymbol] = BigInt(value) & MaximumWorkerId;\n    }\n\n    /**\n     * Generates a snowflake given an epoch and optionally a timestamp.\n     *\n     * **Note:** when `increment` is not provided it defaults to the private `increment` of the instance.\n     *\n     * @example\n     * ```typescript\n     * const epoch = new Date('2000-01-01T00:00:00.000Z');\n     * const snowflake = new Snowflake(epoch).generate();\n     * ```\n     *\n     * @param options - Options to pass into the generator, see {@link SnowflakeGenerateOptions}.\n     * @returns A unique snowflake.\n     */\n    public generate({\n        increment,\n        timestamp = Date.now(),\n        workerId = this[WorkerIdSymbol],\n        processId = this[ProcessIdSymbol],\n    }: SnowflakeGenerateOptions = {}) {\n        if (timestamp instanceof Date) timestamp = BigInt(timestamp.getTime());\n        else if (typeof timestamp === \"number\") timestamp = BigInt(timestamp);\n        else if (typeof timestamp !== \"bigint\") {\n            throw new TypeError(\n                `\"timestamp\" argument must be a number, bigint, or Date (received ${typeof timestamp})`,\n            );\n        }\n\n        if (typeof increment !== \"bigint\") {\n            increment = this[IncrementSymbol];\n            this[IncrementSymbol] = (increment + 1n) & MaximumIncrement;\n        }\n\n        // timestamp, workerId, processId, increment\n        return (\n            ((timestamp - this[EpochSymbol]) << 22n) |\n            ((workerId & MaximumWorkerId) << 17n) |\n            ((processId & MaximumProcessId) << 12n) |\n            (increment & MaximumIncrement)\n        );\n    }\n\n    /**\n     * Deconstructs a snowflake.\n     *\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     * @param id - The snowflake to deconstruct.\n     * @returns A deconstructed snowflake.\n     */\n    public deconstruct(id: string | bigint): DeconstructedSnowflake {\n        const bigIntId = BigInt(id);\n        const epoch = this[EpochSymbol];\n        return {\n            id: bigIntId,\n            timestamp: (bigIntId >> 22n) + epoch,\n            workerId: (bigIntId >> 17n) & MaximumWorkerId,\n            processId: (bigIntId >> 12n) & MaximumProcessId,\n            increment: bigIntId & MaximumIncrement,\n            epoch,\n        };\n    }\n\n    /**\n     * Retrieves the timestamp field's value from a snowflake.\n     *\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): number {\n        return Number((BigInt(id) >> 22n) + this.epoch);\n    }\n\n    /**\n     * Returns a number indicating whether a reference snowflake comes before,\n     * or after, or is same as the given snowflake in sort order.\n     *\n     * @example Sort snowflakes in ascending order\n     * ```typescript\n     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];\n     * console.log(ids.sort((a, b) => Snowflake.compare(a, b)));\n     * // → ['254360814063058944', '737141877803057244', '1056191128120082432'];\n     * ```\n     *\n     * @example Sort snowflakes in descending order\n     * ```typescript\n     * const ids = ['737141877803057244', '1056191128120082432', '254360814063058944'];\n     * console.log(ids.sort((a, b) => -Snowflake.compare(a, b)));\n     * // → ['1056191128120082432', '737141877803057244', '254360814063058944'];\n     * ```\n     *\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(a: string | bigint, b: string | bigint): -1 | 0 | 1 {\n        const typeA = typeof a;\n        return typeA === typeof b\n            ? typeA === \"string\"\n                ? cmpString(a as string, b as string)\n                : cmpBigInt(a as bigint, b as bigint)\n            : cmpBigInt(BigInt(a), BigInt(b));\n    }\n}\n\n/** @internal */\nfunction cmpBigInt(a: bigint, b: bigint) {\n    return a === b ? 0 : a < b ? -1 : 1;\n}\n\n/** @internal */\nfunction cmpString(a: string, b: string) {\n    return a === b ? 0 : a.length < b.length ? -1 : a.length > b.length ? 1 : a < b ? -1 : 1;\n}\n\n/**\n * Options for `Snowflake#generate`.\n */\nexport interface SnowflakeGenerateOptions {\n    /**\n     * Timestamp or date of the snowflake to generate.\n     *\n     * @defaultValue Date.now()\n     */\n    timestamp?: number | bigint | Date;\n    /**\n     * The increment to use.\n     *\n     * @defaultValue 0n\n     * @remarks keep in mind that this bigint is auto-incremented between generate calls.\n     */\n    increment?: bigint;\n    /**\n     * The worker ID to use, will be truncated to 5 bits (0-31).\n     *\n     * @defaultValue 0n\n     */\n    workerId?: bigint;\n    /**\n     * The process ID to use, will be truncated to 5 bits (0-31).\n     *\n     * @defaultValue 1n\n     */\n    processId?: bigint;\n}\n\n/**\n * Object returned by `Snowflake#deconstruct`.\n */\nexport interface DeconstructedSnowflake {\n    /**\n     * The id in BigInt form.\n     */\n    id: bigint;\n    /**\n     * The timestamp stored in the snowflake.\n     */\n    timestamp: bigint;\n    /**\n     * The worker id stored in the snowflake.\n     */\n    workerId: bigint;\n    /**\n     * The process id stored in the snowflake.\n     */\n    processId: bigint;\n    /**\n     * The increment stored in the snowflake.\n     */\n    increment: bigint;\n    /**\n     * The epoch to use in the snowflake.\n     */\n    epoch: bigint;\n}\n","import { Snowflake } from \"./snowflake\";\n\n/**\n * A class for parsing snowflake ids using Discord's snowflake epoch.\n *\n * The Discord epoch is `1420070400000` (`2015-01-01T00:00:00.000Z`), see {@link https://discord.com/developers/docs/reference#snowflakes}.\n */\nexport const discordSnowflake = new Snowflake(1420070400000n);\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+    "$schema": "https://json.schemastore.org/package.json",
+    "name": "@sodiumlabs/snowflake",
+    "version": "1.0.0",
+    "description": "Snowflake utility package",
+    "keywords": [
+        "id",
+        "snowflake",
+        "sodium",
+        "sodiumlabs",
+        "typescript",
+        "utility"
+    ],
+    "homepage": "https://github.com/sodium-labs/utilities/tree/main/packages/snowflake",
+    "bugs": {
+        "url": "https://github.com/sodium-labs/utilities/issues"
+    },
+    "license": "MIT",
+    "author": "sodiumlabs",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/sodium-labs/utilities.git",
+        "directory": "packages/snowflake"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "require": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            }
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "build:docs": "tsc -p tsconfig.docs.json",
+        "lint": "tsc --noEmit && oxlint && oxfmt --check",
+        "fmt": "oxfmt",
+        "test": "vitest run",
+        "docs": "npm run build:docs && api-extractor run --local"
+    },
+    "devDependencies": {
+        "@microsoft/api-extractor": "^7.55.2",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}