Introduction
In this tutorial we will learn how to generate and validate UUIDs (Universally Unique IDentifiers) in JavaScript, using the uuid package.
This package supports the generation of UUIDs accordingly to versions 1, 3, 4 and 5 of RFC4122 [1]. In this tutorial we are not going to cover the details of each version, but I encourage you to check this very interesting post about their differences, to better understand the code we are going to write. You can also check more information here.
For the documentation about the package, please check its GitHub page here.
To install the package using NPM, we simply need to send the following command:
npm install uuid
Note that it is also common to use the term GUIDs (Globally Unique IDentifiers) to refer to UUIDs [2].
The code from the sections below was tested using Node.js, Visual Studio Code and the Code Runner extension.
A simple example to generate a UUID
In this section we will write a very simple code snippet to generate a v4 UUID. We will start by importing the uuid package we have just installed.
const uuid = require('uuid');
After that, we will simply call the v4 function of this module, to generate a version 4 UUID. We will print the result of this function call directly to the console.
console.log(uuid.v4());
The complete code can be seen below.
const uuid = require('uuid');
console.log(uuid.v4());
Upon running the code, you should get a result similar to figure 1, which shows a v4 UUID. Naturally, you will obtain a UUID different from mine and, if you run the code multiple times, you should also obtain different values.
You can use this online tool to confirm that the UUID is indeed compliant with version 4, as shown in figure 2 below.
Just to illustrate that this function call returns different values, we will write a slightly more complex code sample where we will call it and print the resulting value inside a loop. I’ll be printing ten UUIDs, but you can change the loop limit value to print less or more.
const uuid = require('uuid');
for(let x = 0; x<10; x++){
console.log(uuid.v4());
}
Upon running the code, you should get a result similar to figure 3. As can be seen, the UUIDs obtained are all different, as expected.
Just as a final note regarding the v4 function, it can receive some optional parameters as input, to change its behavior. We are not going to cover these parameters on this tutorial, but you can check them here.
Different UUID versions
In this section we will test the generation of UUIDs of the different versions supported by the package. The code is similar to the one we have covered before, except that we will call the functions that correspond to each different UUID version: v1, v3, v4 and v5.
Note that both v1 and v4 can be called without passing any parameters but, for v3 and v5, we need to pass the name (a string) and the namespace identifier (a UUID), in this order. For an explanation behind the need for these parameters, please check the articles mentioned in the introductory section.
const uuid = require('uuid');
console.log("v1: " + uuid.v1());
console.log("v3: " + uuid.v3('Test v3', 'cdb3c65c-84ee-11eb-8dcd-0242ac130003'));
console.log("v4: " + uuid.v4());
console.log("v5: " + uuid.v5('Test v5', '5dd74eb6-84ef-11eb-8dcd-0242ac130003'));
Upon running the code, you should get a result similar to figure 4. Note that for the v1 and v4 UUIDs you should get values different from mine, and different every time you run the code. On the contrary, for v3 and v5, you should obtain exactly the same values as mine, and it should be repeatable everytime you run the code.
Once again, you can test the generated UUIDs against the online tool we used in the previous section. Figure 5 exemplifies the result for the v3 UUID. As can be seen, the tool identifies it as a valid v3 UUID.
Validating UUIDs
Although we have been using an online tool to validate the UUIDs we have been generating, this package also supports validating a given UUID and checking its version. As such, we are going to write a code snippet to use these functionalities.
As before, we start by importing the uuid package.
const uuid = require('uuid');
To validate if a given string is a UUID or not, we simply need to call the validate function. This function returns a Boolean indicating if the string is a valid UUID (true) or not (false). We will test it both against an arbitrary string and to a v4 UUID.
console.log(uuid.validate('something'));
console.log(uuid.validate('83dc308b-ac4e-4d1e-9e0b-9e49041308c4'));
To obtain the version of a given valid UUID, we simply need to call the version function, passing as input the UUID as a string. As output, it will return a number with the RFC version of the UUID. If the parameter is not a valid UUID, then this function call will throw a TypeError exception.
console.log(uuid.version('83dc308b-ac4e-4d1e-9e0b-9e49041308c4'));
The complete code snippet can be seen below.
const uuid = require('uuid');
console.log(uuid.validate('something'));
console.log(uuid.validate('83dc308b-ac4e-4d1e-9e0b-9e49041308c4'));
console.log(uuid.version('83dc308b-ac4e-4d1e-9e0b-9e49041308c4'));
Upon running the code, you should obtain a result similar to figure 6. For the arbitrary string we passed to the validate function, we obtained the value false, since it was not a valid UUID. Then, when we passed a valid v4 UUID, we obtained the value true, as expected. For the call to the version function, we obtained the value 4, which corresponds to the RFC version of the UUID passed as input.
References
[1] https://github.com/uuidjs/uuid
[2] https://www.ietf.org/rfc/rfc4122.txt