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
uuidjs · Jan 27, 2020 · 4802e8b · 4802e8b
1 parent 261cec5
commit 4802e8b
Show file tree

Hide file tree

Showing 2 changed files with 132 additions and 124 deletions.
diff --git 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
@@ -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