Skip to content

Commit

Permalink
chore: v11 prerelease (#792)
Browse files Browse the repository at this point in the history
  • Loading branch information
broofa authored Sep 6, 2024
1 parent 1d1130a commit 8a8c858
Show file tree
Hide file tree
Showing 3 changed files with 32 additions and 34 deletions.
4 changes: 0 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,15 @@ 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

- missing v7 expectations in browser spec ([#751](https://github.com/uuidjs/uuid/issues/751)) ([f54a866](https://github.com/uuidjs/uuid/commit/f54a866cedb2b3b96581157c1f4ac935a0b11411))
- 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))

Expand Down
31 changes: 16 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,11 @@ For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (form

<!-- prettier-ignore -->
> [!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
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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.

---

Expand Down
31 changes: 16 additions & 15 deletions README_js.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,11 @@ For the creation of [RFC9562](https://www.rfc-editor.org/rfc/rfc9562.html) (form

<!-- prettier-ignore -->
> [!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
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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.

0 comments on commit 8a8c858

Please sign in to comment.