From 4802e8b288a067929280e83f6210487da29dd3c7 Mon Sep 17 00:00:00 2001 From: Christoph Tavan Date: Thu, 23 Jan 2020 14:58:09 +0100 Subject: [PATCH] docs: make v4 UUIDs more prominent in the docs Also add a reminder that v1 UUIDs may very often not be the ideal choice. This relates to the research from https://github.com/tc39/proposal-uuid/blob/master/analysis/README.md --- README.md | 142 ++++++++++++++++++++++++++------------------------- README_js.md | 114 +++++++++++++++++++++-------------------- 2 files changed, 132 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index b0d4fb3e..d3cbfca8 100644 --- a/README.md +++ b/README.md @@ -114,8 +114,81 @@ npm run build ## API +### Version 4 (Random) + +```javascript +const uuid = require('uuid'); + +// Incantations +uuid.v4(); +uuid.v4(options); +uuid.v4(options, buffer, offset); +``` + +Generate and return a RFC4122 v4 UUID. + +- `options` - (Object) Optional uuid state to apply. Properties may include: + - `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values. Takes precedence over `options.rng`. + - `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255). Alternative to `options.random`. +- `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. +- `offset` - (Number) Starting index in `buffer` at which to begin writing. + +Returns `buffer`, if specified, otherwise the string form of the UUID + +Example: Generate string UUID with predefined `random` values + +```javascript +const v4options = { + random: [ + 0x10, + 0x91, + 0x56, + 0xbe, + 0xc4, + 0xfb, + 0xc1, + 0xea, + 0x71, + 0xb4, + 0xef, + 0xe1, + 0x67, + 0x1c, + 0x58, + 0x36, + ], +}; +uuid.v4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836' + +``` + +Example: Generate two IDs in a single buffer + +```javascript +const buffer = new Array(); +uuid.v4(null, buffer, 0); // ⇨ + // [ + // 155, 29, 235, 77, 59, + // 125, 75, 173, 155, 221, + // 43, 13, 123, 61, 203, + // 109 + // ] +uuid.v4(null, buffer, 16); // ⇨ + // [ + // 155, 29, 235, 77, 59, 125, 75, 173, + // 155, 221, 43, 13, 123, 61, 203, 109, + // 27, 157, 107, 205, 187, 253, 75, 45, + // 155, 93, 171, 141, 251, 189, 75, 237 + // ] + +``` + ### Version 1 (Timestamp + Node) +⚠️⚠️⚠️ **Please make sure to check whether you really need the timestamp properties of Version 1 UUIDs +before using them. In many cases, Version 4 random UUIDs are the better choice. [This +FAQ](https://github.com/tc39/proposal-uuid#faq) covers more details.** ⚠️⚠️⚠️ + ```javascript const uuid = require('uuid'); @@ -203,75 +276,6 @@ uuid.v3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f608261724 ``` -### Version 4 (Random) - -```javascript -const uuid = require('uuid'); - -// Incantations -uuid.v4(); -uuid.v4(options); -uuid.v4(options, buffer, offset); -``` - -Generate and return a RFC4122 v4 UUID. - -- `options` - (Object) Optional uuid state to apply. Properties may include: - - `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values. Takes precedence over `options.rng`. - - `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255). Alternative to `options.random`. -- `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. -- `offset` - (Number) Starting index in `buffer` at which to begin writing. - -Returns `buffer`, if specified, otherwise the string form of the UUID - -Example: Generate string UUID with predefined `random` values - -```javascript -const v4options = { - random: [ - 0x10, - 0x91, - 0x56, - 0xbe, - 0xc4, - 0xfb, - 0xc1, - 0xea, - 0x71, - 0xb4, - 0xef, - 0xe1, - 0x67, - 0x1c, - 0x58, - 0x36, - ], -}; -uuid.v4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836' - -``` - -Example: Generate two IDs in a single buffer - -```javascript -const buffer = new Array(); -uuid.v4(null, buffer, 0); // ⇨ - // [ - // 155, 29, 235, 77, 59, - // 125, 75, 173, 155, 221, - // 43, 13, 123, 61, 203, - // 109 - // ] -uuid.v4(null, buffer, 16); // ⇨ - // [ - // 155, 29, 235, 77, 59, 125, 75, 173, - // 155, 221, 43, 13, 123, 61, 203, 109, - // 27, 157, 107, 205, 187, 253, 75, 45, - // 155, 93, 171, 141, 251, 189, 75, 237 - // ] - -``` - ### Version 5 (Namespace) ```javascript diff --git a/README_js.md b/README_js.md index 1f2c5d01..3d0aad2e 100644 --- a/README_js.md +++ b/README_js.md @@ -123,8 +123,67 @@ npm run build ## API +### Version 4 (Random) + +```javascript +const uuid = require('uuid'); + +// Incantations +uuid.v4(); +uuid.v4(options); +uuid.v4(options, buffer, offset); +``` + +Generate and return a RFC4122 v4 UUID. + +- `options` - (Object) Optional uuid state to apply. Properties may include: + - `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values. Takes precedence over `options.rng`. + - `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255). Alternative to `options.random`. +- `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. +- `offset` - (Number) Starting index in `buffer` at which to begin writing. + +Returns `buffer`, if specified, otherwise the string form of the UUID + +Example: Generate string UUID with predefined `random` values + +```javascript --run v4 +const v4options = { + random: [ + 0x10, + 0x91, + 0x56, + 0xbe, + 0xc4, + 0xfb, + 0xc1, + 0xea, + 0x71, + 0xb4, + 0xef, + 0xe1, + 0x67, + 0x1c, + 0x58, + 0x36, + ], +}; +uuid.v4(v4options); // RESULT +``` + +Example: Generate two IDs in a single buffer + +```javascript --run v4 +const buffer = new Array(); +uuid.v4(null, buffer, 0); // RESULT +uuid.v4(null, buffer, 16); // RESULT +``` + ### Version 1 (Timestamp + Node) +⚠️⚠️⚠️ **Please make sure to check whether you really need the timestamp properties of Version 1 UUIDs +before using them. In many cases, Version 4 random UUIDs are the better choice. [This +FAQ](https://github.com/tc39/proposal-uuid#faq) covers more details.** ⚠️⚠️⚠️ + ```javascript const uuid = require('uuid'); @@ -197,61 +256,6 @@ Example: uuid.v3('hello world', MY_NAMESPACE); // RESULT ``` -### Version 4 (Random) - -```javascript -const uuid = require('uuid'); - -// Incantations -uuid.v4(); -uuid.v4(options); -uuid.v4(options, buffer, offset); -``` - -Generate and return a RFC4122 v4 UUID. - -- `options` - (Object) Optional uuid state to apply. Properties may include: - - `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values. Takes precedence over `options.rng`. - - `rng` - (Function) Random # generator function that returns an Array[16] of byte values (0-255). Alternative to `options.random`. -- `buffer` - (Array | Buffer) Array or buffer where UUID bytes are to be written. -- `offset` - (Number) Starting index in `buffer` at which to begin writing. - -Returns `buffer`, if specified, otherwise the string form of the UUID - -Example: Generate string UUID with predefined `random` values - -```javascript --run v4 -const v4options = { - random: [ - 0x10, - 0x91, - 0x56, - 0xbe, - 0xc4, - 0xfb, - 0xc1, - 0xea, - 0x71, - 0xb4, - 0xef, - 0xe1, - 0x67, - 0x1c, - 0x58, - 0x36, - ], -}; -uuid.v4(v4options); // RESULT -``` - -Example: Generate two IDs in a single buffer - -```javascript --run v4 -const buffer = new Array(); -uuid.v4(null, buffer, 0); // RESULT -uuid.v4(null, buffer, 16); // RESULT -``` - ### Version 5 (Namespace) ```javascript