@apexsoftwaresolutions/uuidv4

UUIDv4

The UUIDv4 specification requires that the UUIDv4 value is a 128-bit number represented by a string of hexadecimal digits, which means that we need to generate a 16-byte buffer to store the random bits that make up the UUIDv4 value.

A UUIDv4 value is generated by selecting 128 bits at random, which are then formatted as a string of hexadecimal digits with the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, where x is any hexadecimal digit and y is either 8, 9, A, or B.

To generate the random bits, we use the crypto.randomBytes method from Node's built-in crypto module, which generates a secure, random byte sequence of the specified length. In this case, we need 16 bytes, or 128 bits, to generate a valid UUIDv4 value.

Once we have the 16-byte buffer, we can then set the version number and variant number bits as required by the UUIDv4 specification and convert the buffer to a string of hexadecimal digits with the correct format.

  // Set the version number to 4 (0100)
  buffer[6] = (buffer[6] & 0x0f) | 0x40;

This line of code sets the version number bits of the UUIDv4 value in the 7th octet of the 16-byte buffer.

According to the UUIDv4 specification, the version number bits of a UUIDv4 value are defined as follows:

• The four most significant bits of the 7th octet are set to 0100 (binary) or 4 (hexadecimal) to indicate a version number of 4. To set the version number bits in the buffer, we use a bit mask to clear the four most significant bits of the 7th octet and then set them to 0100 (binary) or 4 (hexadecimal).

The line of code you asked about achieves this by performing the following steps:

• buffer[6] & 0x0f clears the four most significant bits of the 7th octet by performing a bitwise AND operation with the hexadecimal value 0x0f, which has the binary value 00001111.
• | 0x40 sets the four most significant bits of the 7th octet to 0100 (binary) or 4 (hexadecimal) by performing a bitwise OR operation with the hexadecimal value 0x40, which has the binary value 01000000.

By setting the version number bits in the buffer, we ensure that the generated UUIDv4 value has a version number of 4, as required by the UUIDv4 specification.

---

  // Set the variant number to 2 (10)
  buffer[8] = (buffer[8] & 0x3f) | 0x80;

This line of code sets the variant number bits of the UUIDv4 value in the 9th octet of the 16-byte buffer.

According to the UUIDv4 specification, the variant number bits of a UUIDv4 value are defined as follows:

• The two most significant bits of the 9th octet are set to 10 (binary) or 8 or 9 or A or B (hexadecimal) to indicate a variant number of 10x, where x can be any value.

To set the variant number bits in the buffer, we use a bit mask to clear the two most significant bits of the 9th octet and then set them to 10 (binary) or 8 or 9 or A or B (hexadecimal). The line of code you asked about achieves this by performing the following steps:

• buffer[8] & 0x3f clears the two most significant bits of the 9th octet by performing a bitwise AND operation with the hexadecimal value 0x3f, which has the binary value 00111111.
• | 0x80 sets the two most significant bits of the 9th octet to 10 (binary) or 8 or 9 or A or B (hexadecimal) by performing a bitwise OR operation with the hexadecimal value 0x80, which has the binary value 10000000.

By setting the variant number bits in the buffer, we ensure that the generated UUIDv4 value has a variant number of 10x, where x can be any value, as required by the UUIDv4 specification.

---

const uuid = buffer.toString("hex").toLowerCase();

This line of code converts the 16-byte buffer, which contains the random bits that make up the UUIDv4 value, to a string of hexadecimal digits with the correct format.

The buffer.toString("hex") method converts the buffer to a hexadecimal string representation. The "hex" argument specifies the encoding to use when converting the buffer to a string.

The toLowerCase() method converts all the alphabetic characters in the hexadecimal string to lowercase, as required by the UUIDv4 specification.

By converting the buffer to a string of hexadecimal digits with the correct format, we obtain the final UUIDv4 value, which can be used in a variety of contexts.

---

return `${uuid.substring(0, 8)}-${uuid.substring(8, 12)}-${uuid.substring(
    12,
    16
  )}-${uuid.substring(16, 20)}-${uuid.substring(20)}`

This line of code formats the final UUIDv4 value as a string with the correct format of xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.

The substring method is used to extract the different parts of the UUIDv4 string from the uuid string. Each call to substring extracts a specific part of the UUIDv4 string based on its position within the string.

The following code:

${uuid.substring(0, 8)}-${uuid.substring(8, 12)}-${uuid.substring(12, 16)}-${uuid.substring(16, 20)}-${uuid.substring(20)}

extracts the five parts of the UUIDv4 string and separates them with hyphens to create the final formatted UUIDv4 string. Here's what each part corresponds to:

• uuid.substring(0, 8): the first eight characters of the UUIDv4 string.
• uuid.substring(8, 12): the next four characters of the UUIDv4 string.
• uuid.substring(12, 16): the next four characters of the UUIDv4 string.
• uuid.substring(16, 20): the next four characters of the UUIDv4 string.
• uuid.substring(20): the final 12 characters of the UUIDv4 string.

By extracting and concatenating these parts in the correct order with hyphens, we obtain the final UUIDv4 string with the correct format of xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.