uuid 2.0.3 → 11.1.1

package/LICENSE.md

@@ -1,2 +1,9 @@
-Copyright (c) 2010-2012 Robert Kieffer
-MIT License - http://opensource.org/licenses/mit-license.php
+The MIT License (MIT)
+
+Copyright (c) 2010-2020 Robert Kieffer and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,205 +1,510 @@
-# uuid [![Build Status](https://secure.travis-ci.org/defunctzombie/node-uuid.svg?branch=master)](http://travis-ci.org/defunctzombie/node-uuid) #
+<!--
+  -- This file is auto-generated from README_js.md. Changes should be made there.
+  -->
 
-[![browser support](https://ci.testling.com/defunctzombie/node-uuid.png)](https://ci.testling.com/defunctzombie/node-uuid)
+# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions/workflows/browser.yml)
 
-Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDS.
+For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (formerly [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html)) UUIDs
 
-Features:
+- **Complete** - Support for all RFC9562 UUID versions
+- **Cross-platform** - Support for...
+  - ESM & Common JS
+  - [Typescript](#support)
+  - [Chrome, Safari, Firefox, and Edge](#support)
+  - [NodeJS](#support)
+  - [React Native / Expo](#react-native--expo)
+- **Secure** - Uses modern `crypto` API for random values
+- **Compact** - Zero-dependency, [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking)
+- **CLI** - [`uuid` command line](#command-line) utility
 
-* Generate RFC4122 version 1 or version 4 UUIDs
-* Runs in node.js and all browsers.
-* Cryptographically strong random # generation on supporting platforms
-* 1185 bytes minified and gzip'ed  (Want something smaller?  Check this [crazy shit](https://gist.github.com/982883) out! )
-* [Annotated source code](http://broofa.github.com/node-uuid/docs/uuid.html)
+<!-- prettier-ignore -->
+> [!NOTE]
+> `uuid@11` is now available:  See the [CHANGELOG](./CHANGELOG.md) for details. TL;DR:
+> * TypeScript support is now included  (remove `@types/uuid` from your dependencies)
+> * Subtle changes to how the `options` arg is interpreted for `v1()`, `v6()`, and `v7()`. [See details](#options-handling-for-timestamp-uuids)
+> * Binary UUIDs are now `Uint8Array`s.  (May impact callers of `parse()`, `stringify()`,  or that pass an `option#buf` argument to `v1()`-`v7()`.)
 
-## Getting Started
+## Quickstart
 
-Install it in your browser:
+**1. Install**
 
-```html
-<script src="uuid.js"></script>
+```shell
+npm install uuid
 ```
 
-Or in node.js:
+**2. Create a UUID**
+
+ESM-syntax (must use named exports):
 
+```javascript
+import { v4 as uuidv4 } from 'uuid';
+uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
 ```
-npm install uuid
+
+... CommonJS:
+
+```javascript
+const { v4: uuidv4 } = require('uuid');
+uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
 ```
 
+For timestamp UUIDs, namespace UUIDs, and other options read on ...
+
+## API Summary
+
+|  |  |  |
+| --- | --- | --- |
+| [`uuid.NIL`](#uuidnil) | The nil UUID string (all zeros) | New in `uuid@8.3` |
+| [`uuid.MAX`](#uuidmax) | The max UUID string (all ones) | New in `uuid@9.1` |
+| [`uuid.parse()`](#uuidparsestr) | Convert UUID string to array of bytes | New in `uuid@8.3` |
+| [`uuid.stringify()`](#uuidstringifyarr-offset) | Convert array of bytes to UUID string | New in `uuid@8.3` |
+| [`uuid.v1()`](#uuidv1options-buffer-offset) | Create a version 1 (timestamp) UUID |  |
+| [`uuid.v1ToV6()`](#uuidv1tov6uuid) | Create a version 6 UUID from a version 1 UUID | New in `uuid@10` |
+| [`uuid.v3()`](#uuidv3name-namespace-buffer-offset) | Create a version 3 (namespace w/ MD5) UUID |  |
+| [`uuid.v4()`](#uuidv4options-buffer-offset) | Create a version 4 (random) UUID |  |
+| [`uuid.v5()`](#uuidv5name-namespace-buffer-offset) | Create a version 5 (namespace w/ SHA-1) UUID |  |
+| [`uuid.v6()`](#uuidv6options-buffer-offset) | Create a version 6 (timestamp, reordered) UUID | New in `uuid@10` |
+| [`uuid.v6ToV1()`](#uuidv6tov1uuid) | Create a version 1 UUID from a version 6 UUID | New in `uuid@10` |
+| [`uuid.v7()`](#uuidv7options-buffer-offset) | Create a version 7 (Unix Epoch time-based) UUID | New in `uuid@10` |
+| ~~[`uuid.v8()`](#uuidv8)~~ | "Intentionally left blank" |  |
+| [`uuid.validate()`](#uuidvalidatestr) | Test a string to see if it is a valid UUID | New in `uuid@8.3` |
+| [`uuid.version()`](#uuidversionstr) | Detect RFC version of a UUID | New in `uuid@8.3` |
+
+## API
+
+### uuid.NIL
+
+The nil UUID string (all zeros).
+
+Example:
+
 ```javascript
-var uuid = require('uuid');
+import { NIL as NIL_UUID } from 'uuid';
 
-// Generate a v1 (time-based) id
-uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
+NIL_UUID; // ⇨ '00000000-0000-0000-0000-000000000000'
+```
+
+### uuid.MAX
+
+The max UUID string (all ones).
+
+Example:
+
+```javascript
+import { MAX as MAX_UUID } from 'uuid';
 
-// Generate a v4 (random) id
-uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'
+MAX_UUID; // ⇨ 'ffffffff-ffff-ffff-ffff-ffffffffffff'
 ```
 
-## API
+### uuid.parse(str)
+
+Convert UUID string to array of bytes
+
+|           |                                          |
+| --------- | ---------------------------------------- |
+| `str`     | A valid UUID `String`                    |
+| _returns_ | `Uint8Array[16]`                         |
+| _throws_  | `TypeError` if `str` is not a valid UUID |
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.
+
+Example:
 
-### uuid.v1([`options` [, `buffer` [, `offset`]]])
+```javascript
+import { parse as uuidParse } from 'uuid';
+
+// Parse a UUID
+uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨
+// Uint8Array(16) [
+//   110, 192, 189, 127,  17,
+//   192,  67, 218, 151,  94,
+//    42, 138, 217, 235, 174,
+//    11
+// ]
+```
+
+### uuid.stringify(arr[, offset])
+
+Convert array of bytes to UUID string
 
-Generate and return a RFC4122 v1 (timestamp-based) UUID.
+|                |                                                                              |
+| -------------- | ---------------------------------------------------------------------------- |
+| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255. |
+| [`offset` = 0] | `Number` Starting index in the Array                                         |
+| _returns_      | `String`                                                                     |
+| _throws_       | `TypeError` if a valid UUID string cannot be generated                       |
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.
+
+Example:
 
-* `options` - (Object) Optional uuid state to apply. Properties may include:
+```javascript
+import { stringify as uuidStringify } from 'uuid';
+
+const uuidBytes = Uint8Array.of(
+  0x6e,
+  0xc0,
+  0xbd,
+  0x7f,
+  0x11,
+  0xc0,
+  0x43,
+  0xda,
+  0x97,
+  0x5e,
+  0x2a,
+  0x8a,
+  0xd9,
+  0xeb,
+  0xae,
+  0x0b
+);
+
+uuidStringify(uuidBytes); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
+```
 
-  * `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID.  See note 1.
-  * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence.  Default: An internally maintained clockseq is used.
-  * `msecs` - (Number | Date) Time in milliseconds since unix Epoch.  Default: The current time is used.
-  * `nsecs` - (Number between 0-9999) additional time, in 100-nanosecond units. Ignored if `msecs` is unspecified. Default: internal uuid counter is used, as per 4.2.1.2.
+### uuid.v1([options[, buffer[, offset]]])
 
-* `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
-* `offset` - (Number) Starting index in `buffer` at which to begin writing.
+Create an RFC version 1 (timestamp) UUID
 
-Returns `buffer`, if specified, otherwise the string form of the UUID
+|  |  |
+| --- | --- |
+| [`options`] | `Object` with one or more of the following properties: |
+| [`options.node = (random)` ] | RFC "node" field as an `Array[6]` of byte values (per 4.1.6) |
+| [`options.clockseq = (random)`] | RFC "clock sequence" as a `Number` between 0 - 0x3fff |
+| [`options.msecs = (current time)`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) |
+| [`options.nsecs = 0`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) |
+| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
+| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
+| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
+| _throws_ | `Error` if more than 10M UUIDs/sec are requested |
 
-Notes:
+<!-- prettier-ignore -->
+> [!NOTE]
+> The default [node id](https://datatracker.ietf.org/doc/html/rfc9562#section-5.1) (the last 12 digits in the UUID) is generated once, randomly, on process startup, and then remains unchanged for the duration of the process.
 
-1. The randomly generated node id is only guaranteed to stay constant for the lifetime of the current JS runtime. (Future versions of this module may use persistent storage mechanisms to extend this guarantee.)
+<!-- prettier-ignore -->
+> [!NOTE]
+> `options.random` and `options.rng` are only meaningful on the very first call to `v1()`, where they may be passed to initialize the internal `node` and `clockseq` fields.
 
-Example: Generate string UUID with fully-specified options
+Example:
 
 ```javascript
-uuid.v1({
-  node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
+import { v1 as uuidv1 } from 'uuid';
+
+uuidv1(); // ⇨ '2c5ea4c0-4067-11e9-9bdd-2b0d7b3dcb6d'
+```
+
+Example using `options`:
+
+```javascript
+import { v1 as uuidv1 } from 'uuid';
+
+const options = {
+  node: Uint8Array.of(0x01, 0x23, 0x45, 0x67, 0x89, 0xab),
   clockseq: 0x1234,
   msecs: new Date('2011-11-01').getTime(),
-  nsecs: 5678
-});   // -> "710b962e-041c-11e1-9234-0123456789ab"
+  nsecs: 5678,
+};
+uuidv1(options); // ⇨ '710b962e-041c-11e1-9234-0123456789ab'
 ```
 
-Example: In-place generation of two binary IDs
+### uuid.v1ToV6(uuid)
+
+Convert a UUID from version 1 to version 6
 
 ```javascript
-// Generate two ids in an array
-var arr = new Array(32); // -> []
-uuid.v1(null, arr, 0);   // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
-uuid.v1(null, arr, 16);  // -> [02 a2 ce 90 14 32 11 e1 85 58 0b 48 8e 4f c1 15 02 a3 1c b0 14 32 11 e1 85 58 0b 48 8e 4f c1 15]
+import { v1ToV6 } from 'uuid';
 
-// Optionally use uuid.unparse() to get stringify the ids
-uuid.unparse(buffer);    // -> '02a2ce90-1432-11e1-8558-0b488e4fc115'
-uuid.unparse(buffer, 16) // -> '02a31cb0-1432-11e1-8558-0b488e4fc115'
+v1ToV6('92f62d9e-22c4-11ef-97e9-325096b39f47'); // ⇨ '1ef22c49-2f62-6d9e-97e9-325096b39f47'
 ```
 
-### uuid.v4([`options` [, `buffer` [, `offset`]]])
+### uuid.v3(name, namespace[, buffer[, offset]])
 
-Generate and return a RFC4122 v4 UUID.
+Create an RFC version 3 (namespace w/ MD5) UUID
 
-* `options` - (Object) Optional uuid state to apply. Properties may include:
+API is identical to `v5()`, but uses "v3" instead.
 
-  * `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values
-  * `rng` - (Function) Random # generator to use.  Set to one of the built-in generators - `uuid.mathRNG` (all platforms), `uuid.nodeRNG` (node.js only), `uuid.whatwgRNG` (WebKit only) - or a custom function that returns an array[16] of byte values.
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Per the RFC, "_If backward compatibility is not an issue, SHA-1 [Version 5] is preferred_."
 
-* `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written.
-* `offset` - (Number) Starting index in `buffer` at which to begin writing.
+### uuid.v4([options[, buffer[, offset]]])
 
-Returns `buffer`, if specified, otherwise the string form of the UUID
+Create an RFC version 4 (random) UUID
 
-Example: Generate string UUID with fully-specified options
+|  |  |
+| --- | --- |
+| [`options`] | `Object` with one or more of the following properties: |
+| [`options.random`] | `Array` of 16 random bytes (0-255) |
+| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
+| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
+
+Example:
 
 ```javascript
-uuid.v4({
-  random: [
-    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
-    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
-  ]
-});
-// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
+import { v4 as uuidv4 } from 'uuid';
+
+uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
 ```
 
-Example: Generate two IDs in a single buffer
+Example using predefined `random` values:
 
 ```javascript
-var buffer = new Array(32); // (or 'new Buffer' in node.js)
-uuid.v4(null, buffer, 0);
-uuid.v4(null, buffer, 16);
+import { v4 as uuidv4 } from 'uuid';
+
+const v4options = {
+  random: Uint8Array.of(
+    0x10,
+    0x91,
+    0x56,
+    0xbe,
+    0xc4,
+    0xfb,
+    0xc1,
+    0xea,
+    0x71,
+    0xb4,
+    0xef,
+    0xe1,
+    0x67,
+    0x1c,
+    0x58,
+    0x36
+  ),
+};
+uuidv4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'
 ```
 
-### uuid.parse(id[, buffer[, offset]])
-### uuid.unparse(buffer[, offset])
+### uuid.v5(name, namespace[, buffer[, offset]])
 
-Parse and unparse UUIDs
+Create an RFC version 5 (namespace w/ SHA-1) UUID
 
-  * `id` - (String) UUID(-like) string
-  * `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. Default: A new Array or Buffer is used
-  * `offset` - (Number) Starting index in `buffer` at which to begin writing. Default: 0
+|  |  |
+| --- | --- |
+| `name` | `String \| Array` |
+| `namespace` | `String \| Array[16]` Namespace UUID |
+| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
 
-Example parsing and unparsing a UUID string
+<!-- prettier-ignore -->
+> [!NOTE]
+> The RFC `DNS` and `URL` namespaces are available as `v5.DNS` and `v5.URL`.
+
+Example with custom namespace:
 
 ```javascript
-var bytes = uuid.parse('797ff043-11eb-11e1-80d6-510998755d10'); // -> <Buffer 79 7f f0 43 11 eb 11 e1 80 d6 51 09 98 75 5d 10>
-var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'
+import { v5 as uuidv5 } from 'uuid';
+
+// Define a custom namespace.  Readers, create your own using something like
+// https://www.uuidgenerator.net/
+const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';
+
+uuidv5('Hello, World!', MY_NAMESPACE); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'
 ```
 
-### uuid.noConflict()
+Example with RFC `URL` namespace:
 
-(Browsers only) Set `uuid` property back to it's previous value.
+```javascript
+import { v5 as uuidv5 } from 'uuid';
 
-Returns the uuid object.
+uuidv5('https://www.w3.org/', uuidv5.URL); // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'
+```
 
-Example:
+### uuid.v6([options[, buffer[, offset]]])
+
+Create an RFC version 6 (timestamp, reordered) UUID
+
+This method takes the same arguments as uuid.v1().
 
 ```javascript
-var myUuid = uuid.noConflict();
-myUuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'
+import { v6 as uuidv6 } from 'uuid';
+
+uuidv6(); // ⇨ '1e940672-c5ea-64c0-9b5d-ab8dfbbd4bed'
 ```
 
-## Deprecated APIs
+Example using `options`:
 
-Support for the following v1.2 APIs is available in v1.3, but is deprecated and will be removed in the next major version.
+```javascript
+import { v6 as uuidv6 } from 'uuid';
 
-### uuid([format [, buffer [, offset]]])
+const options = {
+  node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
+  clockseq: 0x1234,
+  msecs: new Date('2011-11-01').getTime(),
+  nsecs: 5678,
+};
+uuidv6(options); // ⇨ '1e1041c7-10b9-662e-9234-0123456789ab'
+```
 
-uuid() has become uuid.v4(), and the `format` argument is now implicit in the `buffer` argument. (i.e. if you specify a buffer, the format is assumed to be binary).
+### uuid.v6ToV1(uuid)
 
-## Testing
+Convert a UUID from version 6 to version 1
 
-In node.js
+```javascript
+import { v6ToV1 } from 'uuid';
 
+v6ToV1('1ef22c49-2f62-6d9e-97e9-325096b39f47'); // ⇨ '92f62d9e-22c4-11ef-97e9-325096b39f47'
 ```
-> cd test
-> node test.js
+
+### uuid.v7([options[, buffer[, offset]]])
+
+Create an RFC version 7 (random) UUID
+
+|  |  |
+| --- | --- |
+| [`options`] | `Object` with one or more of the following properties: |
+| [`options.msecs = (current time)`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) |
+| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
+| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
+| [`options.seq = (random)`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help ensure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. |
+| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
+
+Example:
+
+```javascript
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7(); // ⇨ '01695553-c90c-705a-b56d-778dfbbd4bed'
+```
+
+### ~~uuid.v8()~~
+
+**_"Intentionally left blank"_**
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Version 8 (experimental) UUIDs are "[for experimental or vendor-specific use cases](https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-8)".  The RFC does not define a creation algorithm for them, which is why this package does not offer a `v8()` method.  The `validate()` and `version()` methods do work with such UUIDs, however.
+
+### uuid.validate(str)
+
+Test a string to see if it is a valid UUID
+
+|           |                                                     |
+| --------- | --------------------------------------------------- |
+| `str`     | `String` to validate                                |
+| _returns_ | `true` if string is a valid UUID, `false` otherwise |
+
+Example:
+
+```javascript
+import { validate as uuidValidate } from 'uuid';
+
+uuidValidate('not a UUID'); // ⇨ false
+uuidValidate('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ true
 ```
 
-In Browser
+Using `validate` and `version` together it is possible to do per-version validation, e.g. validate for only v4 UUIds.
+
+```javascript
+import { version as uuidVersion } from 'uuid';
+import { validate as uuidValidate } from 'uuid';
 
+function uuidValidateV4(uuid) {
+  return uuidValidate(uuid) && uuidVersion(uuid) === 4;
+}
+
+const v1Uuid = 'd9428888-122b-11e1-b85c-61cd3cbb3210';
+const v4Uuid = '109156be-c4fb-41ea-b1b4-efe1671c5836';
+
+uuidValidateV4(v4Uuid); // ⇨ true
+uuidValidateV4(v1Uuid); // ⇨ false
 ```
-open test/test.html
+
+### uuid.version(str)
+
+Detect RFC version of a UUID
+
+|           |                                          |
+| --------- | ---------------------------------------- |
+| `str`     | A valid UUID `String`                    |
+| _returns_ | `Number` The RFC version of the UUID     |
+| _throws_  | `TypeError` if `str` is not a valid UUID |
+
+Example:
+
+```javascript
+import { version as uuidVersion } from 'uuid';
+
+uuidVersion('45637ec4-c85f-11ea-87d0-0242ac130003'); // ⇨ 1
+uuidVersion('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ 4
 ```
 
-### Benchmarking
+<!-- prettier-ignore -->
+> [!NOTE]
+> This method returns `0` for the `NIL` UUID, and `15` for the `MAX` UUID.
 
-Requires node.js
+## Command Line
 
+UUIDs can be generated from the command line using `uuid`.
+
+```shell
+$ npx uuid
+ddeb27fb-d9a0-4624-be4d-4615062daed4
 ```
-cd benchmark/
-npm install
-node benchmark.js
+
+The default is to generate version 4 UUIDS, however the other versions are supported. Type `uuid --help` for details:
+
+```shell
+$ npx uuid --help
+
+Usage:
+  uuid
+  uuid v1
+  uuid v3 <name> <namespace uuid>
+  uuid v4
+  uuid v5 <name> <namespace uuid>
+  uuid v7
+  uuid --help
+
+Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs
+defined by RFC9562
 ```
 
-For a more complete discussion of uuid performance, please see the `benchmark/README.md` file, and the [benchmark wiki](https://github.com/broofa/uuid/wiki/Benchmark)
+## `options` Handling for Timestamp UUIDs
+
+Prior to `uuid@11`, it was possible for `options` state to interfere with the internal state used to ensure uniqueness of timestamp-based UUIDs (the `v1()`, `v6()`, and `v7()` methods). Starting with `uuid@11`, this issue has been addressed by using the presence of the `options` argument as a flag to select between two possible behaviors:
+
+- Without `options`: Internal state is utilized to improve UUID uniqueness.
+- With `options`: Internal state is **NOT** used and, instead, appropriate defaults are applied as needed.
 
-For browser performance [checkout the JSPerf tests](http://jsperf.com/node-uuid-performance).
+## Support
 
-## Release notes
+**Browsers**: `uuid` [builds are tested](/uuidjs/uuid/blob/main/wdio.conf.js) against the latest version of desktop Chrome, Safari, Firefox, and Edge. Mobile versions of these same browsers are expected to work but aren't currently tested.
 
-### 2.0.0
- 
-* Removed uuid.BufferClass
+**Node**: `uuid` [builds are tested](https://github.com/uuidjs/uuid/blob/main/.github/workflows/ci.yml#L26-L27) against node ([LTS releases](https://github.com/nodejs/Release)), plus one prior. E.g. `node@18` is in maintainence mode, and `node@22` is the current LTS release. So `uuid` supports `node@16`-`node@22`.
 
-### 1.4.0
+**Typescript**: TS versions released within the past two years are supported. [source](https://github.com/microsoft/TypeScript/issues/49088#issuecomment-2468723715)
 
-* Improved module context detection
-* Removed public RNG functions
+## Known issues
 
-### 1.3.2
+<!-- This header is referenced as an anchor in src/rng-browser.ts -->
 
-* Improve tests and handling of v1() options (Issue #24)
-* Expose RNG option to allow for perf testing with different generators
+### "getRandomValues() not supported"
+
+This error occurs in environments where the standard [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) API is not supported. This issue can be resolved by adding an appropriate polyfill:
+
+#### React Native / Expo
+
+1. Install [`react-native-get-random-values`](https://github.com/LinusU/react-native-get-random-values#readme)
+1. Import it _before_ `uuid`. Since `uuid` might also appear as a transitive dependency of some other imports it's safest to just import `react-native-get-random-values` as the very first thing in your entry point:
+
+```javascript
+import 'react-native-get-random-values';
+import { v4 as uuidv4 } from 'uuid';
+```
 
-### 1.3.0
+---
 
-* Support for version 1 ids, thanks to [@ctavan](https://github.com/ctavan)!
-* Support for node.js crypto API
-* De-emphasizing performance in favor of a) cryptographic quality PRNGs where available and b) more manageable code
+Markdown generated from [README_js.md](README_js.md) by <a href="https://github.com/broofa/runmd"><image height="13" src="https://camo.githubusercontent.com/5c7c603cd1e6a43370b0a5063d457e0dabb74cf317adc7baba183acb686ee8d0/687474703a2f2f692e696d6775722e636f6d2f634a4b6f3662552e706e67" /></a>

package/dist/cjs/index.d.ts

@@ -0,0 +1,15 @@
+export type * from './types.js';
+export { default as MAX } from './max.js';
+export { default as NIL } from './nil.js';
+export { default as parse } from './parse.js';
+export { default as stringify } from './stringify.js';
+export { default as v1 } from './v1.js';
+export { default as v1ToV6 } from './v1ToV6.js';
+export { default as v3 } from './v3.js';
+export { default as v4 } from './v4.js';
+export { default as v5 } from './v5.js';
+export { default as v6 } from './v6.js';
+export { default as v6ToV1 } from './v6ToV1.js';
+export { default as v7 } from './v7.js';
+export { default as validate } from './validate.js';
+export { default as version } from './version.js';