Welcome to the Lounge

// result = 340 ms
console.time('createUniqueId');
for (let x = 0; x <= 100000; x++) createUniqueId();
console.timeEnd('createUniqueId');

import crypto from 'node:crypto';

/**
 * This module contains routines to assist with creating unique identifiers.
 * @module Identify
 */

// used for the base62 conversion
const CHARSET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';

// no need to go to Number.MAX_SAFE_INTEGER for this as 65,535 is plenty of entropy
const MAX_COUNT = 0xFFFF;

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/**
 * This will calculate a UUID that is able to identify a resource in a globally safe manner. It should be unique
 * and safe to distribute accross disconnected systems. To save space however, the UUID is converted to base 62
 * after removing any unnecessary characters such as hyphens. Do be aware that it uses version 4 of the UUID
 * specification, which has a teeny, tiny chance of a collision.
 *
 * The odds of collision between any two UUIDs is 1 in 2.71 x 10^18 though. To put it another way, one would need
 * to generate 1 billion v4 UUIDs per second for 85 years to have a 50% chance of a single collision. So, the odds
 * are very low; however, this routine will also internally store an incremented counter and add it to part of
 * the result. This will effectively guarantee the returned ID will be unique across any system.
 *
 * The nature of base 62 encoding means the returned ID is case sensitive.
 * @see {@link https://en.wikipedia.org/wiki/Universally_unique_identifier WikiPedia} for more information on the
 * v4 UUID format.
 * @returns {string} Returns a globally unique ID encoded as a base 62 string or null on error.
 */

export function createUniqueId(): string | null {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const self = createUniqueId as any;
  const count: number = (self.count && (self.count < MAX_COUNT)) ? self.count : 0;

  let result = '';
  const uuid = crypto.randomUUID();
  const parts = uuid.split('-');

  if (parts.length === 5) {
    // do not use nullish coalescing for these, also only add the counter to the second
    // part as doing this will allow us to deconstruct the UUID later on if needed
    const one = toBase62(parseInt(parts[0], 16) || 0).padStart(6, '0');
    const two = toBase62((parseInt(parts[1], 16) || 0) + count).padStart(3, '0');
    const three = toBase62(parseInt(parts[2], 16) || 0).padStart(3, '0');
    const four = toBase62(parseInt(parts[3], 16) || 0).padStart(3, '0');
    const five = toBase62(parseInt(parts[4], 16) || 0).padStart(9, '0');

    result = `${one}${two}${three}${four}${five}`;
  }

  // we have to store this here to have it available for the next invocation of this routine
  self.count = count + 1;

  // do not use nullish coalescing for this
  return result || null;
}

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/**
 * This will a encode an integral number as a base62 value, that is to say a value that uses all the characters
 * 0-9, a-z, and A-Z to represent a digit. By the nature of mixing lowercase and uppercase letters, the return
 * value is inherently case sensitive. The algorithm used was borrowed from the `base62.js` library but we added
 * one extra sanity check for decimals and leverage ES6 string indexing to avoid the array conversion.
 *
 * Also note, that when using letters as digits, as with hex, the uppercase version of a letter was tradionally
 * used. But, in modern times the lowercase version is used. Since both cases are used in base62, we start with
 * the lowercase version to better align with more modern formats. As such, the number `10` would equal `a` and
 * not `A`. This is important to be aware of because unlike with hex case matters in base 62.
 * @see {@link https://github.com/base62/base62.js base62.js} for more information on the basis of this algorithm.
 * @see {@link https://dev.to/joshduffney/what-is-base62-conversion-13o0 dev.to} for even more information about
 * the algorithm being implemented.
 * @see {@link https://microsoft.github.io/makecode-csp/unit-6/day-14/base63-url-shorteners Microsoft's GitHub Page} for
 * even more, more information about base62 and how they are used in URL shorteners.
 * @see {@link https://normaltool.com/dencoders/base62-encoder normaltool.com} for an online convert to test with.
 * @returns {string} Returns a case sensitive base 62 number as a string.
 */

export function toBase62(number: number): string {
  let n = Math.floor(number);
  if (n === 0) return CHARSET[0];

  let result = '';

  // js engines will optimize the division these days
  while (n > 0) {
    result = CHARSET[n % 62] + result;
    n = Math.floor(n / 62); // eslint-disable-line no-param-reassign
  }

  return result;
}

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////