@lukeed/uuid

What is @lukeed/uuid?

@lukeed/uuid is a lightweight and fast library for generating universally unique identifiers (UUIDs). It supports generating UUIDs of versions 1, 4, and 5, making it versatile for various use cases where unique identifiers are required.

What are @lukeed/uuid's main functionalities?

Generate UUID v1

Generates a UUID of version 1, which is based on the current timestamp and the MAC address of the machine.

const { v1 } = require('@lukeed/uuid');
const uuidV1 = v1();
console.log(uuidV1);

Generate UUID v4

Generates a UUID of version 4, which is based on random numbers.

const { v4 } = require('@lukeed/uuid');
const uuidV4 = v4();
console.log(uuidV4);

Generate UUID v5

Generates a UUID of version 5, which is based on a namespace and a name using SHA-1 hashing.

const { v5 } = require('@lukeed/uuid');
const uuidV5 = v5('namespace', 'name');
console.log(uuidV5);

Other packages similar to @lukeed/uuid

uuid

The 'uuid' package is one of the most popular libraries for generating UUIDs. It supports versions 1, 3, 4, and 5. Compared to @lukeed/uuid, it is more widely used and has a larger community, but it is also slightly larger in size.

short-uuid

The 'short-uuid' package generates shorter, URL-friendly UUIDs. It is useful when you need a more compact representation of UUIDs. Unlike @lukeed/uuid, it focuses on providing shorter UUIDs rather than adhering strictly to the UUID standard.

nanoid

The 'nanoid' package is a tiny, secure, URL-friendly unique string ID generator. It is much smaller in size compared to @lukeed/uuid and is often used for generating unique IDs in web applications where size and performance are critical.

README

@lukeed/uuid

A tiny (~230B) and fast UUID (v4) generator for Node and the browser.

This module offers two modes for your needs:

• @lukeed/uuid
  The default is "non-secure", which uses Math.random to produce UUIDs.
• @lukeed/uuid/secure
  The "secure" mode produces cryptographically secure (CSPRNG) UUIDs using the current environment's crypto module.

Important:
Version 1.0.0 only offered a "secure" implementation.
In v2.0.0, this is now exported as the "@lukeed/uuid/secure" entry.

Additionally, this module is preconfigured for native ESM support in Node.js with fallback to CommonJS. It will also work with any Rollup and webpack configuration.

Install

$ npm install --save @lukeed/uuid

Modes

There are two "versions" of @lukeed/uuid available:

@lukeed/uuid

Size (gzip): 231 bytes
Availability: CommonJS, ES Module, UMD

Relies on Math.random, which means that, while faster, this mode is not cryptographically secure.
Works in Node.js and all browsers.

@lukeed/uuid/secure

Size (gzip): 235 bytes
Availability: CommonJS, ES Module, UMD

Relies on the environment's crypto module in order to produce cryptographically secure (CSPRNG) values.
Works in all versions of Node.js. Works in all browsers with crypto.getRandomValues() support.

Usage

import { v4 as uuid } from '@lukeed/uuid';
import { v4 as secure } from '@lukeed/uuid/secure';

uuid(); //=> '400fa120-5e9f-411e-94bd-2a23f6695704'
uuid(); //=> 'cd6ffb4d-2eda-4c84-aef5-71eb360ac8c5'

secure(); //=> '8641f70e-8112-4168-9d81-d38170bfa612'
secure(); //=> 'd175fabc-2a4d-475f-be56-29ba8104c2f2'

API

uuid.v4()

Returns: string

Creates a new Version 4 (random) RFC4122 UUID.

Benchmarks

Running on Node.js v12.18.4

Validation:
  ✔ String.replace(Math.random)
  ✔ String.replace(crypto)
  ✔ uuid/v4
  ✔ @lukeed/uuid
  ✔ @lukeed/uuid/secure

Benchmark:
  String.replace(Math.random)  x    381,358 ops/sec ±0.31% (93 runs sampled)
  String.replace(crypto)       x     15,842 ops/sec ±1.16% (86 runs sampled)
  uuid/v4                      x  1,259,600 ops/sec ±0.45% (91 runs sampled)
  @lukeed/uuid                 x  6,384,840 ops/sec ±0.22% (95 runs sampled)
  @lukeed/uuid/secure          x  5,439,096 ops/sec ±0.23% (98 runs sampled)

Running on Chrome v85.0.4183.121

Validation:
  ✔ String.replace(Math.random)
  ✔ uuid/v4
  ✔ @lukeed/uuid
  ✔ @lukeed/uuid/secure

Benchmark:
  String.replace(Math.random)  x    313,213 ops/sec ±0.58% (65 runs sampled)
  uuid/v4                      x    302,914 ops/sec ±0.94% (64 runs sampled)
  @lukeed/uuid                 x  5,881,761 ops/sec ±1.29% (62 runs sampled)
  @lukeed/uuid/secure          x    852,939 ops/sec ±0.88% (65 runs sampled)

Performance

The reason why this UUID.V4 implementation is so much faster is two-fold:

1. It composes an output with hexadecimal pairs (from a cached dictionary) instead of single characters.
2. It allocates a larger Buffer/ArrayBuffer up front (expensive) and slices off chunks as needed (cheap).

The @lukeed/uuid/secure module maintains an internal ArrayBuffer of 4096 bytes, which supplies 256 uuid.v4() invocations. However, the default module preallocates 256 invocations using less memory upfront. Both implementations will regenerate its internal allocation as needed.

A larger buffer would result in higher performance over time, but I found this to be a good balance of performance and memory space.

License

MIT © Luke Edwards