@shinsekai/snowflake 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 @shinsekai/snowflake contributors
+Copyright © 2020 The Sapphire Community and its contributors
+
+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

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @shinsekai/snowflake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Snowflake IDs as BigInts that are **unique and strictly increasing**, with a layout you can fit into a
+signed 64-bit column. Invalid input throws instead of silently producing a wrong id.
+
+No dependencies. ESM, CommonJS and a `<script>` build (global `ShinsekaiSnowflake`). Node 18+ and every modern browser.
+
+```ts
+import { Snowflake } from '@shinsekai/snowflake'
+
+const snowflake = new Snowflake({
+	epoch: new Date('2026-01-01T00:00:00.000Z'),
+	workerId: 3, // one worker / process pair per generator running at the same time
+	processId: 7
+})
+
+const id = snowflake.generate() // 1234567890123456n
+const json = snowflake.generateString() // '1234567890123456', safe for JSON
+snowflake.deconstruct(id) // { id, timestamp, workerId: 3n, processId: 7n, increment, epoch }
+snowflake.timestampFrom(id) // ms since the Unix epoch, exact
+```
+
+## Layout
+
+| bits  | 63 – 22   | 21 – 17 | 16 – 12 | 11 – 0    |
+| ----- | --------- | ------- | ------- | --------- |
+| field | timestamp | worker  | process | increment |
+| width | 42        | 5       | 5       | 12        |
+
+The timestamp is milliseconds after your epoch. With the default 64 bits it lasts ~139 years; with
+`bits: { total: 63 }` it lasts ~69 years and **every id fits a signed 64-bit integer** (PostgreSQL
+`bigint`, MySQL `BIGINT`, Java `long`). With the default 64-bit layout, ids pass 2^63 halfway through,
+which overflows those columns (with Discord's epoch: on 2084-09-06).
+
+```ts
+// For a database: 63 bits, epoch close to today
+const ids = new Snowflake({ epoch: Date.UTC(2026, 0, 1), bits: { total: 63 }, workerId: 1 })
+
+// Any layout: 10-bit machine id, no process field
+const custom = new Snowflake({ epoch: Date.UTC(2026, 0, 1), bits: { worker: 10, process: 0, increment: 12, total: 63 } })
+custom.layout // { totalBits: 63, timestampBits: 41, maxWorkerId: 1023n, ... }
+```
+
+## API
+
+### `new Snowflake(epoch | options)`
+
+- `epoch` — `number | bigint | Date`. You can pass the epoch alone instead of an options object.
+- `workerId` (default `0`), `processId` (default `1`) — must fit their fields, or a `RangeError` is thrown.
+- `bits` — `{ worker = 5, process = 5, increment = 12, total = 64 }`. At least 35 bits must be left for the timestamp.
+- `clock` — `() => number | bigint`, default `Date.now`. Inject one in tests.
+
+### `generate(options?)` / `generateString(options?)`
+
+With no options, ids come from the clock and a per-millisecond sequence:
+
+- The sequence restarts at 0 every millisecond, and ids are strictly increasing.
+- More than 4096 ids in a millisecond: the next id borrows the next millisecond instead of repeating.
+- The clock goes back (NTP, VM resume): the last timestamp is held until the clock catches up, so ids never repeat or go backwards.
+
+Options (all optional): `timestamp`, `increment`, `workerId`, `processId`.
+
+- `timestamp` — make an id for that time. Repeated calls with the same timestamp continue its sequence
+  and throw once it's full; a timestamp earlier than the last one used gets increment 0 and doesn't move the generator back.
+- `increment` — use exactly this sequence value (no state is touched).
+- Every value is range-checked. A timestamp before the epoch or past the last one the layout holds throws a `RangeError`.
+
+### Reading ids
+
+- `deconstruct(id)` / `decode(id)` — fields as bigints. `decode` is bound, so `ids.map(snowflake.decode)` works.
+- `timestampFrom(id)` — exact milliseconds as a number.
+- `minIdAt(time)` / `maxIdAt(time)` — id bounds for range queries: `WHERE id BETWEEN $1 AND $2`.
+- `Snowflake.compare(a, b)` — `-1 | 0 | 1` for strings or bigints, for sorting.
+
+Ids can be a bigint, a safe integer number or a decimal string. Anything else (`'12abc'`, negatives, ids
+wider than the layout, unsafe numbers) throws instead of producing a wrong answer.
+
+### Presets
+
+`DiscordEpoch`, `TwitterEpoch`, and shared `DiscordSnowflake` / `TwitterSnowflake` generators — handy for
+reading Discord or Twitter ids. To generate your own, create a generator per process with its own worker / process ids.
+
+## Guarantees
+
+- **Unique:** one generator never returns the same id twice, even past 4096 ids per millisecond.
+- **Ordered:** ids from one generator are strictly increasing, even when the clock goes back.
+- **Exact:** `timestampFrom` and `deconstruct` return exactly what went in; no floating-point rounding.
+- **Checked:** worker ids, process ids, increments and timestamps that don't fit their fields throw a `RangeError`
+  instead of being masked or overflowing. To fit a larger value such as a hash, mask it yourself: `workerId: hash & 31`.
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # vitest
+pnpm typecheck
+pnpm build      # dist/: ESM, CJS, IIFE, .d.ts
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,284 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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, {
+  DiscordEpoch: () => DiscordEpoch,
+  DiscordSnowflake: () => DiscordSnowflake,
+  MaximumIncrement: () => MaximumIncrement,
+  MaximumProcessId: () => MaximumProcessId,
+  MaximumWorkerId: () => MaximumWorkerId,
+  Snowflake: () => Snowflake,
+  TwitterEpoch: () => TwitterEpoch,
+  TwitterSnowflake: () => TwitterSnowflake
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Snowflake.ts
+var MaximumWorkerId = 0b11111n;
+var MaximumProcessId = 0b11111n;
+var MaximumIncrement = 0b111111111111n;
+var mask = (bits) => (1n << BigInt(bits)) - 1n;
+function toBigInt(value, name) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) throw new RangeError(`"${name}" must be a safe integer (received ${value})`);
+    return BigInt(value);
+  }
+  throw new TypeError(`"${name}" must be a number or bigint (received ${typeof value})`);
+}
+function toTime(value, name) {
+  if (value instanceof Date) {
+    const time = value.getTime();
+    if (Number.isNaN(time)) throw new RangeError(`"${name}" is an invalid Date`);
+    return BigInt(time);
+  }
+  if (typeof value === "number" || typeof value === "bigint") return toBigInt(value, name);
+  throw new TypeError(`"${name}" must be a number, bigint, or Date (received ${typeof value})`);
+}
+function inRange(value, max, name) {
+  const v = toBigInt(value, name);
+  if (v < 0n || v > max) throw new RangeError(`"${name}" must be between 0 and ${max} (received ${v})`);
+  return v;
+}
+function toId(id) {
+  let value;
+  if (typeof id === "bigint") value = id;
+  else if (typeof id === "string") {
+    if (!/^\d+$/.test(id)) throw new SyntaxError(`"${id}" is not a snowflake: expected decimal digits`);
+    value = BigInt(id);
+  } else if (typeof id === "number") value = toBigInt(id, "id");
+  else throw new TypeError(`A snowflake must be a bigint or decimal string (received ${typeof id})`);
+  if (value < 0n) throw new RangeError(`A snowflake can't be negative (received ${value})`);
+  return value;
+}
+var Snowflake = class {
+  #epoch;
+  #epochNumber;
+  #layout;
+  #clock;
+  #shiftTimestamp;
+  #shiftWorker;
+  #shiftProcess;
+  #workerId;
+  #processId;
+  /** Last millisecond (absolute) the sequence was used for, and the sequence value used. */
+  #lastTimestamp = -1n;
+  #sequence = 0n;
+  /**
+   * @param options the epoch alone (as `@sapphire/snowflake` takes it), or {@link SnowflakeOptions}
+   */
+  constructor(options) {
+    const opts = typeof options === "object" && !(options instanceof Date) ? options : { epoch: options };
+    this.#epoch = toTime(opts.epoch, "epoch");
+    if (this.#epoch < 0n) throw new RangeError(`"epoch" can't be before 1970 (received ${this.#epoch})`);
+    this.#epochNumber = Number(this.#epoch);
+    this.#clock = opts.clock ?? (() => Date.now());
+    const totalBits = opts.bits?.total ?? 64;
+    if (totalBits !== 63 && totalBits !== 64) throw new RangeError(`"bits.total" must be 63 or 64 (received ${totalBits})`);
+    const workerBits = opts.bits?.worker ?? 5;
+    const processBits = opts.bits?.process ?? 5;
+    const incrementBits = opts.bits?.increment ?? 12;
+    for (const [name, bits] of [["worker", workerBits], ["process", processBits], ["increment", incrementBits]]) {
+      if (!Number.isInteger(bits) || bits < 0) throw new RangeError(`"bits.${name}" must be a non-negative integer (received ${bits})`);
+    }
+    if (incrementBits < 1) throw new RangeError('"bits.increment" must be at least 1');
+    const timestampBits = totalBits - workerBits - processBits - incrementBits;
+    if (timestampBits < 35) throw new RangeError(`Only ${timestampBits} bits left for the timestamp: use fewer worker / process / increment bits`);
+    this.#layout = Object.freeze({
+      totalBits,
+      timestampBits,
+      workerBits,
+      processBits,
+      incrementBits,
+      maxWorkerId: mask(workerBits),
+      maxProcessId: mask(processBits),
+      maxIncrement: mask(incrementBits),
+      maxTimestampOffset: mask(timestampBits)
+    });
+    this.#shiftProcess = BigInt(incrementBits);
+    this.#shiftWorker = this.#shiftProcess + BigInt(processBits);
+    this.#shiftTimestamp = this.#shiftWorker + BigInt(workerBits);
+    this.#workerId = inRange(opts.workerId ?? 0n, this.#layout.maxWorkerId, "workerId");
+    this.#processId = inRange(opts.processId ?? (this.#layout.maxProcessId >= 1n ? 1n : 0n), this.#layout.maxProcessId, "processId");
+  }
+  /** The epoch, as a bigint. */
+  get epoch() {
+    return this.#epoch;
+  }
+  /** The epoch, as a number. */
+  get epochNumber() {
+    return this.#epochNumber;
+  }
+  /** Field widths and limits. */
+  get layout() {
+    return this.#layout;
+  }
+  /** The worker id used by default. */
+  get workerId() {
+    return this.#workerId;
+  }
+  /** Sets the default worker id. Throws a RangeError when it doesn't fit (it used to be silently masked). */
+  set workerId(value) {
+    this.#workerId = inRange(value, this.#layout.maxWorkerId, "workerId");
+  }
+  /** The process id used by default. */
+  get processId() {
+    return this.#processId;
+  }
+  /** Sets the default process id. Throws a RangeError when it doesn't fit (it used to be silently masked). */
+  set processId(value) {
+    this.#processId = inRange(value, this.#layout.maxProcessId, "processId");
+  }
+  /**
+   * Generates a snowflake.
+   *
+   * Without options, ids from one generator are unique and strictly increasing: the sequence
+   * restarts each millisecond; past its last value, or when the clock goes back, the id takes the
+   * next millisecond instead (ids may then run slightly ahead of the clock until it catches up).
+   */
+  generate(options = {}) {
+    const workerId = options.workerId === void 0 ? this.#workerId : inRange(options.workerId, this.#layout.maxWorkerId, "workerId");
+    const processId = options.processId === void 0 ? this.#processId : inRange(options.processId, this.#layout.maxProcessId, "processId");
+    let timestamp;
+    let increment;
+    if (options.increment !== void 0) {
+      increment = inRange(options.increment, this.#layout.maxIncrement, "increment");
+      timestamp = options.timestamp === void 0 ? this.#now() : toTime(options.timestamp, "timestamp");
+    } else if (options.timestamp !== void 0) {
+      timestamp = toTime(options.timestamp, "timestamp");
+      this.#offset(timestamp);
+      if (timestamp < this.#lastTimestamp) {
+        increment = 0n;
+      } else {
+        if (timestamp === this.#lastTimestamp) {
+          if (this.#sequence === this.#layout.maxIncrement) {
+            throw new RangeError(`No more ids for timestamp ${timestamp}: all ${this.#layout.maxIncrement + 1n} have been used`);
+          }
+          this.#sequence++;
+        } else {
+          this.#sequence = 0n;
+        }
+        this.#lastTimestamp = timestamp;
+        increment = this.#sequence;
+      }
+    } else {
+      timestamp = this.#next();
+      increment = this.#sequence;
+    }
+    return this.#compose(timestamp, workerId, processId, increment);
+  }
+  /** {@link generate}, as a decimal string: ready for JSON, which can't hold a bigint. */
+  generateString(options) {
+    return this.generate(options).toString();
+  }
+  /** Splits a snowflake into its fields. */
+  deconstruct(id) {
+    const value = this.#checkWidth(toId(id));
+    const { maxWorkerId, maxProcessId, maxIncrement } = this.#layout;
+    return {
+      id: value,
+      timestamp: (value >> this.#shiftTimestamp) + this.#epoch,
+      workerId: value >> this.#shiftWorker & maxWorkerId,
+      processId: value >> this.#shiftProcess & maxProcessId,
+      increment: value & maxIncrement,
+      epoch: this.#epoch
+    };
+  }
+  /** Alias for {@link deconstruct}, bound to this generator: it still works detached (`const { decode } = snowflake`). */
+  decode = (id) => this.deconstruct(id);
+  /**
+   * The timestamp stored in a snowflake, in milliseconds since the Unix epoch. Computed with
+   * bigints: going through a floating-point number could be a millisecond off.
+   */
+  timestampFrom(id) {
+    return Number(this.#checkWidth(toId(id)) >> this.#shiftTimestamp) + this.#epochNumber;
+  }
+  /** The smallest id possible at a timestamp: for "ids created from this time on" queries. */
+  minIdAt(timestamp) {
+    return this.#offset(toTime(timestamp, "timestamp")) << this.#shiftTimestamp;
+  }
+  /** The largest id possible at a timestamp: for "ids created up to this time" queries. */
+  maxIdAt(timestamp) {
+    return this.#offset(toTime(timestamp, "timestamp")) << this.#shiftTimestamp | mask(Number(this.#shiftTimestamp));
+  }
+  /**
+   * Orders two snowflakes: -1 if `a` is older than `b`, 0 if they are the same, 1 if `a` is newer.
+   * Works for any mix of bigints and decimal strings, leading zeros included.
+   */
+  static compare(a, b) {
+    const x = toId(a);
+    const y = toId(b);
+    return x === y ? 0 : x < y ? -1 : 1;
+  }
+  /** The next millisecond for an automatic id, with the sequence set for it. */
+  #next() {
+    const now = this.#now();
+    if (now > this.#lastTimestamp) {
+      this.#lastTimestamp = now;
+      this.#sequence = 0n;
+    } else if (this.#sequence < this.#layout.maxIncrement) {
+      this.#sequence++;
+    } else {
+      this.#lastTimestamp++;
+      this.#sequence = 0n;
+    }
+    return this.#lastTimestamp;
+  }
+  #now() {
+    return toTime(this.#clock(), "clock()");
+  }
+  /** Milliseconds after the epoch, checked to fit the timestamp field. */
+  #offset(timestamp) {
+    const offset = timestamp - this.#epoch;
+    if (offset < 0n) throw new RangeError(`Timestamp ${timestamp} is before the epoch (${this.#epoch})`);
+    if (offset > this.#layout.maxTimestampOffset) {
+      throw new RangeError(
+        `Timestamp ${timestamp} is past the last one this layout can hold (${this.#epoch + this.#layout.maxTimestampOffset}): use a later epoch`
+      );
+    }
+    return offset;
+  }
+  #compose(timestamp, workerId, processId, increment) {
+    return this.#offset(timestamp) << this.#shiftTimestamp | workerId << this.#shiftWorker | processId << this.#shiftProcess | increment;
+  }
+  #checkWidth(id) {
+    if (id > mask(this.#layout.totalBits)) throw new RangeError(`${id} is wider than ${this.#layout.totalBits} bits`);
+    return id;
+  }
+};
+
+// src/presets.ts
+var DiscordEpoch = 1420070400000n;
+var TwitterEpoch = 1288834974657n;
+var DiscordSnowflake = new Snowflake(DiscordEpoch);
+var TwitterSnowflake = new Snowflake(TwitterEpoch);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DiscordEpoch,
+  DiscordSnowflake,
+  MaximumIncrement,
+  MaximumProcessId,
+  MaximumWorkerId,
+  Snowflake,
+  TwitterEpoch,
+  TwitterSnowflake
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/Snowflake.ts","../src/presets.ts"],"sourcesContent":["export * from './presets'\nexport * from './Snowflake'\n","/**\n * Snowflake IDs: 64-bit (or 63-bit) integers made of a timestamp, a worker id, a process id and a\n * per-millisecond sequence, so they are unique and sort by creation time.\n *\n * Twitter / Discord layout (the default):\n * ```\n * 64                                          22     17     12          0\n *  000000111011000111100001101001000101000000  00001  00000  000000000000\n *           milliseconds since the epoch       worker  process  increment\n * ```\n *\n * A drop-in successor to `@sapphire/snowflake` that, on one generator, guarantees unique and\n * increasing IDs: the sequence restarts every millisecond, and when it runs out (more than 4096\n * IDs in a millisecond) or the clock goes back, generation carries on from the last millisecond\n * used instead of repeating or going backwards. Out-of-range input throws instead of being masked.\n */\n\n/** A point in time: milliseconds since the Unix epoch, or a Date. */\nexport type TimeInput = number | bigint | Date\n\n/** Something that becomes a non-negative integer. */\nexport type IntegerInput = number | bigint\n\nexport interface SnowflakeBits {\n\t/** Bits of the worker id. @default 5 */\n\tworker?: number\n\t/** Bits of the process id. @default 5 */\n\tprocess?: number\n\t/** Bits of the per-millisecond sequence. @default 12 */\n\tincrement?: number\n\t/**\n\t * Width of the whole id. 64 is the Twitter / Discord layout; 63 keeps every id positive in a\n\t * signed 64-bit integer, such as PostgreSQL's `bigint` or Java's `long`. The timestamp gets the bits left over.\n\t * @default 64\n\t */\n\ttotal?: 63 | 64\n}\n\nexport interface SnowflakeOptions {\n\t/** Where timestamps count from. Pick one close to today: the timestamp field fills up after 2^timestampBits ms. */\n\tepoch: TimeInput\n\t/** Default worker id for generated ids. Give every generator that runs at the same time its own worker / process pair. @default 0 */\n\tworkerId?: IntegerInput\n\t/** Default process id for generated ids. @default 1 */\n\tprocessId?: IntegerInput\n\t/** Field widths. */\n\tbits?: SnowflakeBits\n\t/** The clock, in milliseconds since the Unix epoch. Replace it in tests. @default Date.now */\n\tclock?: () => number | bigint\n}\n\nexport interface SnowflakeGenerateOptions {\n\t/**\n\t * Timestamp of the id. Without it the clock is used, and ids are guaranteed unique and increasing.\n\t * With it, the id belongs to that millisecond: it continues the sequence when it is the latest\n\t * millisecond used, and starts at 0 for an earlier one (which doesn't move the generator back).\n\t * @default the clock\n\t */\n\ttimestamp?: TimeInput\n\t/**\n\t * Use this sequence value as is (0 to 4095 by default), outside the generator's own sequence.\n\t * Uniqueness is then up to you.\n\t */\n\tincrement?: IntegerInput\n\t/** Worker id for this id only. */\n\tworkerId?: IntegerInput\n\t/** Process id for this id only. */\n\tprocessId?: IntegerInput\n}\n\n/** Object returned by {@link Snowflake.deconstruct}. */\nexport interface DeconstructedSnowflake {\n\t/** The id as a bigint. */\n\tid: bigint\n\t/** Milliseconds since the Unix epoch, when the id was made. */\n\ttimestamp: bigint\n\tworkerId: bigint\n\tprocessId: bigint\n\tincrement: bigint\n\t/** The epoch the generator counts from. */\n\tepoch: bigint\n}\n\n/** The resolved field widths and limits of a {@link Snowflake}. */\nexport interface SnowflakeLayout {\n\ttotalBits: number\n\ttimestampBits: number\n\tworkerBits: number\n\tprocessBits: number\n\tincrementBits: number\n\tmaxWorkerId: bigint\n\tmaxProcessId: bigint\n\tmaxIncrement: bigint\n\t/** Largest timestamp offset (ms after the epoch) that still fits. */\n\tmaxTimestampOffset: bigint\n}\n\n/** The largest worker id in the default layout. */\nexport const MaximumWorkerId = 0b11111n\n/** The largest process id in the default layout. */\nexport const MaximumProcessId = 0b11111n\n/** The largest per-millisecond sequence value in the default layout. */\nexport const MaximumIncrement = 0b111111111111n\n\nconst mask = (bits: number) => (1n << BigInt(bits)) - 1n\n\nfunction toBigInt(value: unknown, name: string): bigint {\n\tif (typeof value === 'bigint') return value\n\tif (typeof value === 'number') {\n\t\tif (!Number.isSafeInteger(value)) throw new RangeError(`\"${name}\" must be a safe integer (received ${value})`)\n\t\treturn BigInt(value)\n\t}\n\tthrow new TypeError(`\"${name}\" must be a number or bigint (received ${typeof value})`)\n}\n\nfunction toTime(value: unknown, name: string): bigint {\n\tif (value instanceof Date) {\n\t\tconst time = value.getTime()\n\t\tif (Number.isNaN(time)) throw new RangeError(`\"${name}\" is an invalid Date`)\n\t\treturn BigInt(time)\n\t}\n\tif (typeof value === 'number' || typeof value === 'bigint') return toBigInt(value, name)\n\tthrow new TypeError(`\"${name}\" must be a number, bigint, or Date (received ${typeof value})`)\n}\n\nfunction inRange(value: IntegerInput, max: bigint, name: string): bigint {\n\tconst v = toBigInt(value, name)\n\tif (v < 0n || v > max) throw new RangeError(`\"${name}\" must be between 0 and ${max} (received ${v})`)\n\treturn v\n}\n\n/** A snowflake as a bigint: from a bigint, a safe integer, or a decimal string. */\nfunction toId(id: unknown): bigint {\n\tlet value: bigint\n\tif (typeof id === 'bigint') value = id\n\telse if (typeof id === 'string') {\n\t\tif (!/^\\d+$/.test(id)) throw new SyntaxError(`\"${id}\" is not a snowflake: expected decimal digits`)\n\t\tvalue = BigInt(id)\n\t} else if (typeof id === 'number') value = toBigInt(id, 'id')\n\telse throw new TypeError(`A snowflake must be a bigint or decimal string (received ${typeof id})`)\n\tif (value < 0n) throw new RangeError(`A snowflake can't be negative (received ${value})`)\n\treturn value\n}\n\nexport class Snowflake {\n\treadonly #epoch: bigint\n\treadonly #epochNumber: number\n\treadonly #layout: SnowflakeLayout\n\treadonly #clock: () => number | bigint\n\treadonly #shiftTimestamp: bigint\n\treadonly #shiftWorker: bigint\n\treadonly #shiftProcess: bigint\n\t#workerId: bigint\n\t#processId: bigint\n\t/** Last millisecond (absolute) the sequence was used for, and the sequence value used. */\n\t#lastTimestamp = -1n\n\t#sequence = 0n\n\n\t/**\n\t * @param options the epoch alone (as `@sapphire/snowflake` takes it), or {@link SnowflakeOptions}\n\t */\n\tpublic constructor(options: TimeInput | SnowflakeOptions) {\n\t\tconst opts: SnowflakeOptions =\n\t\t\ttypeof options === 'object' && !(options instanceof Date) ? options : { epoch: options }\n\n\t\tthis.#epoch = toTime(opts.epoch, 'epoch')\n\t\tif (this.#epoch < 0n) throw new RangeError(`\"epoch\" can't be before 1970 (received ${this.#epoch})`)\n\t\tthis.#epochNumber = Number(this.#epoch)\n\t\tthis.#clock = opts.clock ?? (() => Date.now())\n\n\t\tconst totalBits = opts.bits?.total ?? 64\n\t\tif (totalBits !== 63 && totalBits !== 64) throw new RangeError(`\"bits.total\" must be 63 or 64 (received ${totalBits})`)\n\t\tconst workerBits = opts.bits?.worker ?? 5\n\t\tconst processBits = opts.bits?.process ?? 5\n\t\tconst incrementBits = opts.bits?.increment ?? 12\n\t\tfor (const [name, bits] of [['worker', workerBits], ['process', processBits], ['increment', incrementBits]] as const) {\n\t\t\tif (!Number.isInteger(bits) || bits < 0) throw new RangeError(`\"bits.${name}\" must be a non-negative integer (received ${bits})`)\n\t\t}\n\t\tif (incrementBits < 1) throw new RangeError('\"bits.increment\" must be at least 1')\n\t\tconst timestampBits = totalBits - workerBits - processBits - incrementBits\n\t\t// below ~35 bits the id space runs out within a year: almost certainly a mistake\n\t\tif (timestampBits < 35) throw new RangeError(`Only ${timestampBits} bits left for the timestamp: use fewer worker / process / increment bits`)\n\n\t\tthis.#layout = Object.freeze({\n\t\t\ttotalBits,\n\t\t\ttimestampBits,\n\t\t\tworkerBits,\n\t\t\tprocessBits,\n\t\t\tincrementBits,\n\t\t\tmaxWorkerId: mask(workerBits),\n\t\t\tmaxProcessId: mask(processBits),\n\t\t\tmaxIncrement: mask(incrementBits),\n\t\t\tmaxTimestampOffset: mask(timestampBits)\n\t\t})\n\t\tthis.#shiftProcess = BigInt(incrementBits)\n\t\tthis.#shiftWorker = this.#shiftProcess + BigInt(processBits)\n\t\tthis.#shiftTimestamp = this.#shiftWorker + BigInt(workerBits)\n\n\t\tthis.#workerId = inRange(opts.workerId ?? 0n, this.#layout.maxWorkerId, 'workerId')\n\t\tthis.#processId = inRange(opts.processId ?? (this.#layout.maxProcessId >= 1n ? 1n : 0n), this.#layout.maxProcessId, 'processId')\n\t}\n\n\t/** The epoch, as a bigint. */\n\tpublic get epoch(): bigint {\n\t\treturn this.#epoch\n\t}\n\n\t/** The epoch, as a number. */\n\tpublic get epochNumber(): number {\n\t\treturn this.#epochNumber\n\t}\n\n\t/** Field widths and limits. */\n\tpublic get layout(): Readonly<SnowflakeLayout> {\n\t\treturn this.#layout\n\t}\n\n\t/** The worker id used by default. */\n\tpublic get workerId(): bigint {\n\t\treturn this.#workerId\n\t}\n\n\t/** Sets the default worker id. Throws a RangeError when it doesn't fit (it used to be silently masked). */\n\tpublic set workerId(value: IntegerInput) {\n\t\tthis.#workerId = inRange(value, this.#layout.maxWorkerId, 'workerId')\n\t}\n\n\t/** The process id used by default. */\n\tpublic get processId(): bigint {\n\t\treturn this.#processId\n\t}\n\n\t/** Sets the default process id. Throws a RangeError when it doesn't fit (it used to be silently masked). */\n\tpublic set processId(value: IntegerInput) {\n\t\tthis.#processId = inRange(value, this.#layout.maxProcessId, 'processId')\n\t}\n\n\t/**\n\t * Generates a snowflake.\n\t *\n\t * Without options, ids from one generator are unique and strictly increasing: the sequence\n\t * restarts each millisecond; past its last value, or when the clock goes back, the id takes the\n\t * next millisecond instead (ids may then run slightly ahead of the clock until it catches up).\n\t */\n\tpublic generate(options: SnowflakeGenerateOptions = {}): bigint {\n\t\tconst workerId = options.workerId === undefined ? this.#workerId : inRange(options.workerId, this.#layout.maxWorkerId, 'workerId')\n\t\tconst processId = options.processId === undefined ? this.#processId : inRange(options.processId, this.#layout.maxProcessId, 'processId')\n\n\t\tlet timestamp: bigint\n\t\tlet increment: bigint\n\n\t\tif (options.increment !== undefined) {\n\t\t\t// a fixed increment: exactly the id asked for, outside the generator's sequence\n\t\t\tincrement = inRange(options.increment, this.#layout.maxIncrement, 'increment')\n\t\t\ttimestamp = options.timestamp === undefined ? this.#now() : toTime(options.timestamp, 'timestamp')\n\t\t} else if (options.timestamp !== undefined) {\n\t\t\ttimestamp = toTime(options.timestamp, 'timestamp')\n\t\t\t// check the range before touching the sequence, so a rejected timestamp leaves no trace\n\t\t\tthis.#offset(timestamp)\n\t\t\tif (timestamp < this.#lastTimestamp) {\n\t\t\t\t// an earlier millisecond: its first id, without moving the generator back\n\t\t\t\tincrement = 0n\n\t\t\t} else {\n\t\t\t\tif (timestamp === this.#lastTimestamp) {\n\t\t\t\t\tif (this.#sequence === this.#layout.maxIncrement) {\n\t\t\t\t\t\tthrow new RangeError(`No more ids for timestamp ${timestamp}: all ${this.#layout.maxIncrement + 1n} have been used`)\n\t\t\t\t\t}\n\t\t\t\t\tthis.#sequence++\n\t\t\t\t} else {\n\t\t\t\t\tthis.#sequence = 0n\n\t\t\t\t}\n\t\t\t\tthis.#lastTimestamp = timestamp\n\t\t\t\tincrement = this.#sequence\n\t\t\t}\n\t\t} else {\n\t\t\ttimestamp = this.#next()\n\t\t\tincrement = this.#sequence\n\t\t}\n\n\t\treturn this.#compose(timestamp, workerId, processId, increment)\n\t}\n\n\t/** {@link generate}, as a decimal string: ready for JSON, which can't hold a bigint. */\n\tpublic generateString(options?: SnowflakeGenerateOptions): string {\n\t\treturn this.generate(options).toString()\n\t}\n\n\t/** Splits a snowflake into its fields. */\n\tpublic deconstruct(id: string | bigint): DeconstructedSnowflake {\n\t\tconst value = this.#checkWidth(toId(id))\n\t\tconst { maxWorkerId, maxProcessId, maxIncrement } = this.#layout\n\t\treturn {\n\t\t\tid: value,\n\t\t\ttimestamp: (value >> this.#shiftTimestamp) + this.#epoch,\n\t\t\tworkerId: (value >> this.#shiftWorker) & maxWorkerId,\n\t\t\tprocessId: (value >> this.#shiftProcess) & maxProcessId,\n\t\t\tincrement: value & maxIncrement,\n\t\t\tepoch: this.#epoch\n\t\t}\n\t}\n\n\t/** Alias for {@link deconstruct}, bound to this generator: it still works detached (`const { decode } = snowflake`). */\n\tpublic readonly decode = (id: string | bigint): DeconstructedSnowflake => this.deconstruct(id)\n\n\t/**\n\t * The timestamp stored in a snowflake, in milliseconds since the Unix epoch. Computed with\n\t * bigints: going through a floating-point number could be a millisecond off.\n\t */\n\tpublic timestampFrom(id: string | bigint): number {\n\t\treturn Number(this.#checkWidth(toId(id)) >> this.#shiftTimestamp) + this.#epochNumber\n\t}\n\n\t/** The smallest id possible at a timestamp: for \"ids created from this time on\" queries. */\n\tpublic minIdAt(timestamp: TimeInput): bigint {\n\t\treturn this.#offset(toTime(timestamp, 'timestamp')) << this.#shiftTimestamp\n\t}\n\n\t/** The largest id possible at a timestamp: for \"ids created up to this time\" queries. */\n\tpublic maxIdAt(timestamp: TimeInput): bigint {\n\t\treturn (this.#offset(toTime(timestamp, 'timestamp')) << this.#shiftTimestamp) | mask(Number(this.#shiftTimestamp))\n\t}\n\n\t/**\n\t * Orders two snowflakes: -1 if `a` is older than `b`, 0 if they are the same, 1 if `a` is newer.\n\t * Works for any mix of bigints and decimal strings, leading zeros included.\n\t */\n\tpublic static compare(a: string | bigint, b: string | bigint): -1 | 0 | 1 {\n\t\tconst x = toId(a)\n\t\tconst y = toId(b)\n\t\treturn x === y ? 0 : x < y ? -1 : 1\n\t}\n\n\t/** The next millisecond for an automatic id, with the sequence set for it. */\n\t#next(): bigint {\n\t\tconst now = this.#now()\n\t\tif (now > this.#lastTimestamp) {\n\t\t\tthis.#lastTimestamp = now\n\t\t\tthis.#sequence = 0n\n\t\t} else if (this.#sequence < this.#layout.maxIncrement) {\n\t\t\t// same millisecond, or the clock went back: keep counting in the last one used\n\t\t\tthis.#sequence++\n\t\t} else {\n\t\t\t// sequence used up: borrow the next millisecond rather than repeat an id or wait\n\t\t\tthis.#lastTimestamp++\n\t\t\tthis.#sequence = 0n\n\t\t}\n\t\treturn this.#lastTimestamp\n\t}\n\n\t#now(): bigint {\n\t\treturn toTime(this.#clock(), 'clock()')\n\t}\n\n\t/** Milliseconds after the epoch, checked to fit the timestamp field. */\n\t#offset(timestamp: bigint): bigint {\n\t\tconst offset = timestamp - this.#epoch\n\t\tif (offset < 0n) throw new RangeError(`Timestamp ${timestamp} is before the epoch (${this.#epoch})`)\n\t\tif (offset > this.#layout.maxTimestampOffset) {\n\t\t\tthrow new RangeError(\n\t\t\t\t`Timestamp ${timestamp} is past the last one this layout can hold (${this.#epoch + this.#layout.maxTimestampOffset}): use a later epoch`\n\t\t\t)\n\t\t}\n\t\treturn offset\n\t}\n\n\t#compose(timestamp: bigint, workerId: bigint, processId: bigint, increment: bigint): bigint {\n\t\treturn (this.#offset(timestamp) << this.#shiftTimestamp) | (workerId << this.#shiftWorker) | (processId << this.#shiftProcess) | increment\n\t}\n\n\t#checkWidth(id: bigint): bigint {\n\t\tif (id > mask(this.#layout.totalBits)) throw new RangeError(`${id} is wider than ${this.#layout.totalBits} bits`)\n\t\treturn id\n\t}\n}\n","import { Snowflake } from './Snowflake'\n\n/**\n * Discord's epoch: 2015-01-01T00:00:00.000Z.\n * {@link https://discord.com/developers/docs/reference#snowflakes}\n */\nexport const DiscordEpoch = 1420070400000n\n\n/**\n * Twitter's epoch: 2010-11-04T01:42:54.657Z, from the archived snowflake repository.\n * {@link https://github.com/twitter-archive/snowflake/blob/b3f6a3c6ca8e1b6847baa6ff42bf72201e2c2231/src/main/scala/com/twitter/service/snowflake/IdWorker.scala#L25}\n */\nexport const TwitterEpoch = 1288834974657n\n\n/**\n * Shared generator with Discord's epoch, mainly for reading Discord ids. To generate ids of your\n * own, make a `new Snowflake({ epoch: DiscordEpoch, workerId, processId })` per process instead,\n * so concurrent generators never share a worker / process pair.\n */\nexport const DiscordSnowflake = new Snowflake(DiscordEpoch)\n\n/** Shared generator with Twitter's epoch; same advice as {@link DiscordSnowflake}. */\nexport const TwitterSnowflake = new Snowflake(TwitterEpoch)\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,165 @@
+/**
+ * Snowflake IDs: 64-bit (or 63-bit) integers made of a timestamp, a worker id, a process id and a
+ * per-millisecond sequence, so they are unique and sort by creation time.
+ *
+ * Twitter / Discord layout (the default):
+ * ```
+ * 64                                          22     17     12          0
+ *  000000111011000111100001101001000101000000  00001  00000  000000000000
+ *           milliseconds since the epoch       worker  process  increment
+ * ```
+ *
+ * A drop-in successor to `@sapphire/snowflake` that, on one generator, guarantees unique and
+ * increasing IDs: the sequence restarts every millisecond, and when it runs out (more than 4096
+ * IDs in a millisecond) or the clock goes back, generation carries on from the last millisecond
+ * used instead of repeating or going backwards. Out-of-range input throws instead of being masked.
+ */
+/** A point in time: milliseconds since the Unix epoch, or a Date. */
+type TimeInput = number | bigint | Date;
+/** Something that becomes a non-negative integer. */
+type IntegerInput = number | bigint;
+interface SnowflakeBits {
+    /** Bits of the worker id. @default 5 */
+    worker?: number;
+    /** Bits of the process id. @default 5 */
+    process?: number;
+    /** Bits of the per-millisecond sequence. @default 12 */
+    increment?: number;
+    /**
+     * Width of the whole id. 64 is the Twitter / Discord layout; 63 keeps every id positive in a
+     * signed 64-bit integer, such as PostgreSQL's `bigint` or Java's `long`. The timestamp gets the bits left over.
+     * @default 64
+     */
+    total?: 63 | 64;
+}
+interface SnowflakeOptions {
+    /** Where timestamps count from. Pick one close to today: the timestamp field fills up after 2^timestampBits ms. */
+    epoch: TimeInput;
+    /** Default worker id for generated ids. Give every generator that runs at the same time its own worker / process pair. @default 0 */
+    workerId?: IntegerInput;
+    /** Default process id for generated ids. @default 1 */
+    processId?: IntegerInput;
+    /** Field widths. */
+    bits?: SnowflakeBits;
+    /** The clock, in milliseconds since the Unix epoch. Replace it in tests. @default Date.now */
+    clock?: () => number | bigint;
+}
+interface SnowflakeGenerateOptions {
+    /**
+     * Timestamp of the id. Without it the clock is used, and ids are guaranteed unique and increasing.
+     * With it, the id belongs to that millisecond: it continues the sequence when it is the latest
+     * millisecond used, and starts at 0 for an earlier one (which doesn't move the generator back).
+     * @default the clock
+     */
+    timestamp?: TimeInput;
+    /**
+     * Use this sequence value as is (0 to 4095 by default), outside the generator's own sequence.
+     * Uniqueness is then up to you.
+     */
+    increment?: IntegerInput;
+    /** Worker id for this id only. */
+    workerId?: IntegerInput;
+    /** Process id for this id only. */
+    processId?: IntegerInput;
+}
+/** Object returned by {@link Snowflake.deconstruct}. */
+interface DeconstructedSnowflake {
+    /** The id as a bigint. */
+    id: bigint;
+    /** Milliseconds since the Unix epoch, when the id was made. */
+    timestamp: bigint;
+    workerId: bigint;
+    processId: bigint;
+    increment: bigint;
+    /** The epoch the generator counts from. */
+    epoch: bigint;
+}
+/** The resolved field widths and limits of a {@link Snowflake}. */
+interface SnowflakeLayout {
+    totalBits: number;
+    timestampBits: number;
+    workerBits: number;
+    processBits: number;
+    incrementBits: number;
+    maxWorkerId: bigint;
+    maxProcessId: bigint;
+    maxIncrement: bigint;
+    /** Largest timestamp offset (ms after the epoch) that still fits. */
+    maxTimestampOffset: bigint;
+}
+/** The largest worker id in the default layout. */
+declare const MaximumWorkerId = 31n;
+/** The largest process id in the default layout. */
+declare const MaximumProcessId = 31n;
+/** The largest per-millisecond sequence value in the default layout. */
+declare const MaximumIncrement = 4095n;
+declare class Snowflake {
+    #private;
+    /**
+     * @param options the epoch alone (as `@sapphire/snowflake` takes it), or {@link SnowflakeOptions}
+     */
+    constructor(options: TimeInput | SnowflakeOptions);
+    /** The epoch, as a bigint. */
+    get epoch(): bigint;
+    /** The epoch, as a number. */
+    get epochNumber(): number;
+    /** Field widths and limits. */
+    get layout(): Readonly<SnowflakeLayout>;
+    /** The worker id used by default. */
+    get workerId(): bigint;
+    /** Sets the default worker id. Throws a RangeError when it doesn't fit (it used to be silently masked). */
+    set workerId(value: IntegerInput);
+    /** The process id used by default. */
+    get processId(): bigint;
+    /** Sets the default process id. Throws a RangeError when it doesn't fit (it used to be silently masked). */
+    set processId(value: IntegerInput);
+    /**
+     * Generates a snowflake.
+     *
+     * Without options, ids from one generator are unique and strictly increasing: the sequence
+     * restarts each millisecond; past its last value, or when the clock goes back, the id takes the
+     * next millisecond instead (ids may then run slightly ahead of the clock until it catches up).
+     */
+    generate(options?: SnowflakeGenerateOptions): bigint;
+    /** {@link generate}, as a decimal string: ready for JSON, which can't hold a bigint. */
+    generateString(options?: SnowflakeGenerateOptions): string;
+    /** Splits a snowflake into its fields. */
+    deconstruct(id: string | bigint): DeconstructedSnowflake;
+    /** Alias for {@link deconstruct}, bound to this generator: it still works detached (`const { decode } = snowflake`). */
+    readonly decode: (id: string | bigint) => DeconstructedSnowflake;
+    /**
+     * The timestamp stored in a snowflake, in milliseconds since the Unix epoch. Computed with
+     * bigints: going through a floating-point number could be a millisecond off.
+     */
+    timestampFrom(id: string | bigint): number;
+    /** The smallest id possible at a timestamp: for "ids created from this time on" queries. */
+    minIdAt(timestamp: TimeInput): bigint;
+    /** The largest id possible at a timestamp: for "ids created up to this time" queries. */
+    maxIdAt(timestamp: TimeInput): bigint;
+    /**
+     * Orders two snowflakes: -1 if `a` is older than `b`, 0 if they are the same, 1 if `a` is newer.
+     * Works for any mix of bigints and decimal strings, leading zeros included.
+     */
+    static compare(a: string | bigint, b: string | bigint): -1 | 0 | 1;
+}
+
+/**
+ * Discord's epoch: 2015-01-01T00:00:00.000Z.
+ * {@link https://discord.com/developers/docs/reference#snowflakes}
+ */
+declare const DiscordEpoch = 1420070400000n;
+/**
+ * Twitter's epoch: 2010-11-04T01:42:54.657Z, from the archived snowflake repository.
+ * {@link https://github.com/twitter-archive/snowflake/blob/b3f6a3c6ca8e1b6847baa6ff42bf72201e2c2231/src/main/scala/com/twitter/service/snowflake/IdWorker.scala#L25}
+ */
+declare const TwitterEpoch = 1288834974657n;
+/**
+ * Shared generator with Discord's epoch, mainly for reading Discord ids. To generate ids of your
+ * own, make a `new Snowflake({ epoch: DiscordEpoch, workerId, processId })` per process instead,
+ * so concurrent generators never share a worker / process pair.
+ */
+declare const DiscordSnowflake: Snowflake;
+/** Shared generator with Twitter's epoch; same advice as {@link DiscordSnowflake}. */
+declare const TwitterSnowflake: Snowflake;
+
+export { type DeconstructedSnowflake, DiscordEpoch, DiscordSnowflake, type IntegerInput, MaximumIncrement, MaximumProcessId, MaximumWorkerId, Snowflake, type SnowflakeBits, type SnowflakeGenerateOptions, type SnowflakeLayout, type SnowflakeOptions, type TimeInput, TwitterEpoch, TwitterSnowflake };