oh-my-pi/packages/utils/src/snowflake.ts

function randu32() {
	return crypto.getRandomValues(new Uint32Array(1))[0];
}

const EPOCH = 1420070400000;
const MAX_SEQ = 0x3fffff;

// Snowflake as a hex string (16 chars, zero-padded).
//
// Since this is not distributed (no machine ID needed), we use an extended
// 22-bit sequence instead of the standard 10-bit machine ID + 12-bit sequence.
//
type Snowflake = string & { readonly __brand: unique symbol };

namespace Snowflake {
	// Hex string validation pattern (16 lowercase hex chars).
	//
	export const PATTERN = /^[0-9a-f]{16}$/;

	// Epoch timestamp.
	//
	export const EPOCH_TIMESTAMP = EPOCH;

	// Maximum sequence number.
	//
	export const MAX_SEQUENCE = MAX_SEQ;

	// Formats a sequence and timestamp into a snowflake hex string.
	//
	// dt fits well within BigInt range: (dt << 22) | seq stays under 2^64 for
	// any dt < 2^42 (~year 2154), so a single 64-bit format is exact — and
	// measures ~1.7x faster than stitching four 16-bit hex segments.
	//
	export function formatParts(dt: number, seq: number): Snowflake {
		return ((BigInt(dt) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
	}

	// Snowflake generator type.
	//
	export class Source {
		#seq = 0;
		constructor(sequence: number = randu32() & MAX_SEQ) {
			this.#seq = sequence & MAX_SEQ;
		}

		// Sequence number.
		//
		get sequence() {
			return this.#seq & MAX_SEQ;
		}
		set sequence(v: number) {
			this.#seq = v & MAX_SEQ;
		}
		reset() {
			this.#seq = 0;
		}

		// Generates the next value as a hex string.
		//
		generate(timestamp: number): Snowflake {
			const seq = (this.#seq + 1) & MAX_SEQ;
			const dt = timestamp - EPOCH;
			this.#seq = seq;
			return formatParts(dt, seq);
		}
	}

	// Gets the next snowflake given the timestamp.
	//
	let defaultSource: Source | undefined;
	export function next(timestamp = Date.now()): Snowflake {
		defaultSource ??= new Source();
		return defaultSource.generate(timestamp);
	}

	// Validates a snowflake hex string.
	//
	export function valid(value: string): value is Snowflake {
		return value.length === 16 && PATTERN.test(value);
	}

	// Returns the upper/lower boundaries for the given timestamp.
	//
	export function lowerbound(timelike: Date | number | Snowflake): Snowflake {
		switch (typeof timelike) {
			case "object": // Date
				return formatParts(timelike.getTime() - EPOCH, 0);
			case "number":
				return formatParts(timelike - EPOCH, 0);
			case "string": // Snowflake hex string
				return timelike;
		}
	}
	export function upperbound(timelike: Date | number | Snowflake): Snowflake {
		switch (typeof timelike) {
			case "object": // Date
				return formatParts(timelike.getTime() - EPOCH, MAX_SEQ);
			case "number":
				return formatParts(timelike - EPOCH, MAX_SEQ);
			case "string": // Snowflake hex string
				return timelike;
		}
	}

	// Returns the individual bits given the snowflake.
	//
	export function getSequence(value: Snowflake) {
		return Number.parseInt(value.substring(8, 16), 16) & MAX_SEQ;
	}
	export function getTimestamp(value: Snowflake) {
		const hi = Number.parseInt(value.substring(0, 8), 16);
		const lo = Number.parseInt(value.substring(8, 16), 16);
		// (hi:lo) >> 22 == hi * 2^10 + (lo >>> 22); at most ~2^42, exact in a double.
		return hi * 1024 + (lo >>> 22) + EPOCH;
	}
	export function getDate(value: Snowflake) {
		return new Date(getTimestamp(value));
	}
}

export { Snowflake };