From 855a94599276c7608a12c1c4fb7a3dc90389fcc6 Mon Sep 17 00:00:00 2001 From: Robert Kieffer Date: Thu, 5 Sep 2024 15:11:16 -0700 Subject: [PATCH] docs: tweaks --- CHANGELOG.md | 4 ---- README.md | 31 ++++++++++++++++--------------- README_js.md | 31 ++++++++++++++++--------------- 3 files changed, 32 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e784e36..b8f539ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,11 +13,8 @@ All notable changes to this project will be documented in this file. See [standa ### Features -- add support for MAX uuid (new in RFC9562) ([#714](https://github.com/uuidjs/uuid/issues/714)) ([0385cd3](https://github.com/uuidjs/uuid/commit/0385cd3f18ae9920678b2849932fa7a9d9aee7d0)) - Port to TypeScript, closes [#762](https://github.com/uuidjs/uuid/issues/762) ([#763](https://github.com/uuidjs/uuid/issues/763)) ([1e0f987](https://github.com/uuidjs/uuid/commit/1e0f9870db864ca93f7a69db0d468b5e1b7605e7)) -- support v6 uuids ([#754](https://github.com/uuidjs/uuid/issues/754)) ([c4ed13e](https://github.com/uuidjs/uuid/commit/c4ed13e7159d87c9e42a349bdd9dc955f1af46b6)) - update node support matrix (only support node 16-20) ([#750](https://github.com/uuidjs/uuid/issues/750)) ([883b163](https://github.com/uuidjs/uuid/commit/883b163b9ab9d6655bfbd8a35e61a3c71674dfe1)) -- v8 support ([#759](https://github.com/uuidjs/uuid/issues/759)) ([35a5342](https://github.com/uuidjs/uuid/commit/35a53428202657e402e6b4aa68f56c08194541bf)) ### Bug Fixes @@ -25,7 +22,6 @@ All notable changes to this project will be documented in this file. See [standa - refactor v1 internal state and options logic ([#780](https://github.com/uuidjs/uuid/issues/780)) ([031b3d3](https://github.com/uuidjs/uuid/commit/031b3d3d738bc6694501ac0a37152b95ed500989)) - refactor v7 internal state and options logic, fixes [#764](https://github.com/uuidjs/uuid/issues/764) ([#779](https://github.com/uuidjs/uuid/issues/779)) ([9dbd1cd](https://github.com/uuidjs/uuid/commit/9dbd1cd4177c43fcaac961a3b16fb2d044c9940a)) - remove v4 options default assignment preventing native.randomUUID from being used ([#786](https://github.com/uuidjs/uuid/issues/786)) ([afe6232](https://github.com/uuidjs/uuid/commit/afe62323c4408a824755a39d7b971a8ae06f7199)), closes [#763](https://github.com/uuidjs/uuid/issues/763) -- revert "perf: remove superfluous call to toLowerCase ([#677](https://github.com/uuidjs/uuid/issues/677))" ([#738](https://github.com/uuidjs/uuid/issues/738)) ([e267b90](https://github.com/uuidjs/uuid/commit/e267b9073df1d0ce119ee53c0487fe76acb2be37)) - seq_hi shift for byte 6 ([#775](https://github.com/uuidjs/uuid/issues/775)) ([1d532ca](https://github.com/uuidjs/uuid/commit/1d532ca374f181932a24a83fa98f71a5bd4f3e96)) - tsconfig module type ([#778](https://github.com/uuidjs/uuid/issues/778)) ([7eff835](https://github.com/uuidjs/uuid/commit/7eff835cba334ad418f57768c00d15b918a9b419)) diff --git a/README.md b/README.md index da78241b..02cfa518 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,11 @@ For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (form > [!NOTE] -> `uuid@11` has the following breaking changes: -> * Passing `options` to `v1()`, `v6()`, and `v7()` now behaves slightly differently. [See details](#options-handling-for-timestamp-uuids) +> `uuid@11`(prerelease) is now available! Install "uuid@beta" to get the latest version. See the [CHANGELOG for details](./CHANGELOG.md). +> +> TL;DR: +> * TS types now included! (`@types/uuid` should no longer be needed) +> * The `options` arg is interpreted differently for `v1()`, `v6()`, and `v7()`. [See details](#options-handling-for-timestamp-uuids) > * Binary UUIDs are now of type `Uint8Array`. This may affect code utilizing `parse()`, `stringify()`, or that passes a `buf` argument to any of the `v1()`-`v7()` methods. ## Quickstart @@ -173,11 +176,11 @@ Create an RFC version 1 (timestamp) UUID | | | | --- | --- | | [`options`] | `Object` with one or more of the following properties: | -| [`options.node` ] | RFC "node" field as an `Array[6]` of byte values (per 4.1.6) | -| [`options.clockseq`] | RFC "clock sequence" as a `Number` between 0 - 0x3fff | -| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) | -| [`options.nsecs`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) | -| [`options.random`] | `Array` of 16 random bytes (0-255) | +| [`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`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | @@ -362,10 +365,10 @@ Create an RFC version 7 (random) UUID | | | | --- | --- | | [`options`] | `Object` with one or more of the following properties: | -| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch). Default = `Date.now()` | -| [`options.random`] | `Array` of 16 random bytes (0-255) | +| [`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`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help insure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | +| [`options.seq = (random)`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help insure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | | [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, 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` | @@ -473,12 +476,10 @@ defined by RFC9562 ## `options` Handling for Timestamp UUIDs -As of `uuid@11`, all timestamp-based UUID APIs (`v1()`, `v6()`, and `v7()`) now operate in two distinct modes: - -- Without `options`: If no `options` argument is passed, these APIs will make use of internal state such as a sequence counter to improve UUID uniqueness. -- With `options`: If an `options` argument of any kind is passed, no internal state is used or updated. Instead, appropriate defaults are used. See the respective APIs for details. +Prior to `uuid@11`, it was possible for `options` state to interfere with the internal state used to insure 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: -Prior to `uuid@11`, this distinction was less clear. Internal state was was being combined with `options` values in ways that were difficult to rationalize about, and that could lead to unpredictable behavior. Hence, this change. +- Without `options`: Methods use and update internal state such as a sequence counter to improve uniqueness. +- With `options`: Methods do **NOT** use or update internal state. Instead, appropriate defaults are used as needed. See individual method docs for details. --- diff --git a/README_js.md b/README_js.md index 97093c8c..ffd767fc 100644 --- a/README_js.md +++ b/README_js.md @@ -33,8 +33,11 @@ For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (form > [!NOTE] -> `uuid@11` has the following breaking changes: -> * Passing `options` to `v1()`, `v6()`, and `v7()` now behaves slightly differently. [See details](#options-handling-for-timestamp-uuids) +> `uuid@11`(prerelease) is now available! Install "uuid@beta" to get the latest version. See the [CHANGELOG for details](./CHANGELOG.md). +> +> TL;DR: +> * TS types now included! (`@types/uuid` should no longer be needed) +> * The `options` arg is interpreted differently for `v1()`, `v6()`, and `v7()`. [See details](#options-handling-for-timestamp-uuids) > * Binary UUIDs are now of type `Uint8Array`. This may affect code utilizing `parse()`, `stringify()`, or that passes a `buf` argument to any of the `v1()`-`v7()` methods. ## Quickstart @@ -181,11 +184,11 @@ Create an RFC version 1 (timestamp) UUID | | | | --- | --- | | [`options`] | `Object` with one or more of the following properties: | -| [`options.node` ] | RFC "node" field as an `Array[6]` of byte values (per 4.1.6) | -| [`options.clockseq`] | RFC "clock sequence" as a `Number` between 0 - 0x3fff | -| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) | -| [`options.nsecs`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) | -| [`options.random`] | `Array` of 16 random bytes (0-255) | +| [`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`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` | | [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` | @@ -370,10 +373,10 @@ Create an RFC version 7 (random) UUID | | | | --- | --- | | [`options`] | `Object` with one or more of the following properties: | -| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch). Default = `Date.now()` | -| [`options.random`] | `Array` of 16 random bytes (0-255) | +| [`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`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help insure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | +| [`options.seq = (random)`] | 32-bit sequence `Number` between 0 - 0xffffffff. This may be provided to help insure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value. | | [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, 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` | @@ -481,9 +484,7 @@ defined by RFC9562 ## `options` Handling for Timestamp UUIDs -As of `uuid@11`, all timestamp-based UUID APIs (`v1()`, `v6()`, and `v7()`) now operate in two distinct modes: - -- Without `options`: If no `options` argument is passed, these APIs will make use of internal state such as a sequence counter to improve UUID uniqueness. -- With `options`: If an `options` argument of any kind is passed, no internal state is used or updated. Instead, appropriate defaults are used. See the respective APIs for details. +Prior to `uuid@11`, it was possible for `options` state to interfere with the internal state used to insure 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: -Prior to `uuid@11`, this distinction was less clear. Internal state was was being combined with `options` values in ways that were difficult to rationalize about, and that could lead to unpredictable behavior. Hence, this change. +- Without `options`: Methods use and update internal state such as a sequence counter to improve uniqueness. +- With `options`: Methods do **NOT** use or update internal state. Instead, appropriate defaults are used as needed. See individual method docs for details.