@lukeed/uuid !CI 

> 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

`js
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

$3


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