@grkndev/snowflakeid/src/index.ts

A simple Snowflake ID generator for JavaScript and TypeScript

/**
 * The default epoch timestamp used for Snowflake ID generation.
 * Set to 2021-01-01T00:00:00Z (1609459200000 in milliseconds since Unix epoch).
 */
const DEFAULT_EPOCH = 1609459200000;

/**
 * Options for customizing Snowflake ID generation.
 */
interface SnowflakeOptions {
  /** Custom epoch timestamp (in milliseconds since Unix epoch) */
  epoch?: number;
  /** Node ID (0-1023) for distributed systems */
  nodeId?: number;
  /** Initial sequence number (0-4095) */
  sequence?: number;
}
interface RandomIdOptions {
  useChars?: boolean;
  useNumbers?: boolean;
}

let globalSequence = 0;
let lastTimestamp = -1;

/**
 * Generates a Snowflake ID.
 *
 * @param {SnowflakeOptions} options - Custom options for ID generation
 * @param {number} [options.epoch=DEFAULT_EPOCH] - Custom epoch timestamp
 * @param {number} [options.nodeId=1] - Node ID for distributed systems
 * @param {number} [options.sequence] - Initial sequence number
 * @returns {string} The generated Snowflake ID as a string
 * @throws {Error} If nodeId is invalid or if the clock moves backwards
 */
function generateSnowflakeId(options: SnowflakeOptions = {}): string {
  const {
    epoch = DEFAULT_EPOCH,
    nodeId = 1,
    sequence: initialSequence,
  } = options;

  if (nodeId < 0 || nodeId > 1023) {
    throw new Error("Node ID must be between 0 and 1023");
  }

  if (epoch < 0 || epoch > Date.now()) {
    throw new Error("Epoch must be a valid timestamp not in the future");
  }

  let timestamp = Date.now();
  let sequence = initialSequence !== undefined ? initialSequence : globalSequence;

  if (timestamp < lastTimestamp) {
    throw new Error("Clock moved backwards. Refusing to generate id");
  }

  if (timestamp === lastTimestamp) {
    sequence = (sequence + 1) & 4095;
    if (sequence === 0) {
      timestamp = waitNextMillis(lastTimestamp);
    }
  } else {
    sequence = initialSequence !== undefined ? initialSequence : 0;
  }

  lastTimestamp = timestamp;
  globalSequence = sequence;

  const id =
    (BigInt(timestamp - epoch) << 22n) |
    (BigInt(nodeId) << 12n) |
    BigInt(sequence);

  return id.toString();
}

/**
 * Waits until the next millisecond.
 *
 * @param {number} lastTimestamp - The last timestamp generated
 * @returns {number} The next available timestamp
 */
function waitNextMillis(lastTimestamp: number): number {
  let timestamp = Date.now();
  while (timestamp <= lastTimestamp) {
    timestamp = Date.now();
  }
  return timestamp;
}

/**
 * Parses a Snowflake ID into its component parts.
 *
 * @param {string} id - The Snowflake ID to parse
 * @param {number} [epoch=DEFAULT_EPOCH] - The epoch used in ID generation
 * @returns {{timestamp: Date, nodeId: number, sequence: number}} Parsed components of the Snowflake ID
 */
function parseSnowflakeId(
  id: string,
  epoch: number = DEFAULT_EPOCH
): {
  timestamp: Date;
  nodeId: number;
  sequence: number;
} {
  const snowflake = BigInt(id);

  const timestamp = Number(snowflake >> 22n) + epoch;
  const nodeId = Number((snowflake >> 12n) & 1023n);
  const sequence = Number(snowflake & 4095n);

  return {
    timestamp: new Date(timestamp),
    nodeId,
    sequence,
  };
}

/**
 * Generates a random ID with a specified length.
 * @param {number} [length=6] - The length of the random ID (must be >= 1)
 * @param {RandomIdOptions} [options] - Custom options for ID generation
 * @param {boolean} [options.useChars=false] - Use characters in the ID
 * @param {boolean} [options.useNumbers=true] - Use numbers in the ID
 * @returns {string} The generated random ID (example: "aBc123")
 * @throws {Error} If length is less than 1 or if neither useChars nor useNumbers is true
 */
function randomId(
  length: number = 6,
  options: RandomIdOptions = {}
): string {
  if (length < 1) {
    throw new Error("Length must be at least 1");
  }

  // If no options provided, default to numbers only
  // If options provided, use explicit values (undefined = false)
  const useChars = options.useChars ?? false;
  const useNumbers = options.useNumbers ?? (options.useChars === undefined ? true : false);

  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
  const numbers = "0123456789";
  let result = "";
  let characters = "";

  if (useChars) characters += chars;
  if (useNumbers) characters += numbers;

  if (characters.length === 0) {
    throw new Error("At least one of useChars or useNumbers must be true");
  }

  for (let i = 0; i < length; i++) {
    result += characters.charAt(Math.floor(Math.random() * characters.length));
  }

  return result;
}

/**
 * Generates a pseudo-UUID string using random alphanumeric characters.
 * Note: This is NOT a standard UUID (RFC 4122). It generates a random
 * alphanumeric string split into segments for readability.
 * For cryptographically secure UUIDs, use crypto.randomUUID() instead.
 * @param {number} [split=4] - The number of 8-character segments to generate (must be >= 1)
 * @returns {string} The generated pseudo-UUID (example: "aBcD1234-EfGh5678-iJkL9012-MnOp3456")
 * @throws {Error} If split is less than 1
 */
function uuid(split: number = 4): string {
  if (split < 1) {
    throw new Error("Split must be at least 1");
  }

  const id = randomId(8 * split, { useChars: true, useNumbers: true });
  const result: string[] = [];
  for (let i = 0; i < split; i++) {
    result.push(id.substring(i * 8, (i + 1) * 8));
  }
  return result.join("-");
}

export { generateSnowflakeId, parseSnowflakeId, randomId, uuid };
export type { SnowflakeOptions, RandomIdOptions };

// CommonJS default export compatibility
export default {
  generateSnowflakeId,
  parseSnowflakeId,
  randomId,
  uuid
};