diff --git a/README.md b/README.md index 5773eaf1..83ae737e 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ Create an RFC version 1 (timestamp) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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 | @@ -244,7 +244,7 @@ Create an RFC version 4 (random) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | @@ -292,7 +292,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID | --- | --- | | `name` | `String \| Array` | | `namespace` | `String \| Array[16]` Namespace UUID | -| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | @@ -367,7 +367,7 @@ Create an RFC version 7 (random) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | diff --git a/README_js.md b/README_js.md index 139251ba..9f9283cf 100644 --- a/README_js.md +++ b/README_js.md @@ -189,7 +189,7 @@ Create an RFC version 1 (timestamp) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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 | @@ -253,7 +253,7 @@ Create an RFC version 4 (random) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | @@ -301,7 +301,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID | --- | --- | | `name` | `String \| Array` | | `namespace` | `String \| Array[16]` Namespace UUID | -| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | @@ -376,7 +376,7 @@ Create an RFC version 7 (random) UUID | [`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` If provided, binary UUID is written into the array, starting at `offset` | +| [`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` | diff --git a/examples/typescript/buffer.test.ts b/examples/typescript/buffer.test.ts new file mode 100644 index 00000000..cb1f07b5 --- /dev/null +++ b/examples/typescript/buffer.test.ts @@ -0,0 +1,8 @@ +/* eslint-disable @typescript-eslint/ban-ts-comment */ +import { v1 } from 'uuid'; + +v1(undefined, new Uint8Array(16)) satisfies Uint8Array; +v1(undefined, Buffer.alloc(16)) satisfies Buffer; + +// @ts-expect-error +v1(undefined, new Uint8Array(16)) satisfies Buffer; diff --git a/src/types.ts b/src/types.ts index d3d8d96c..6c801b8e 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,4 +1,4 @@ -export type UUIDTypes = string | Uint8Array; +export type UUIDTypes = string | TBuf; export type Version1Options = { node?: Uint8Array; diff --git a/src/v1.ts b/src/v1.ts index 24390517..35bee134 100644 --- a/src/v1.ts +++ b/src/v1.ts @@ -25,8 +25,16 @@ type V1State = { const _state: V1State = {}; function v1(options?: Version1Options, buf?: undefined, offset?: number): string; -function v1(options: Version1Options | undefined, buf: Uint8Array, offset?: number): Uint8Array; -function v1(options?: Version1Options, buf?: Uint8Array, offset?: number): UUIDTypes { +function v1( + options: Version1Options | undefined, + buf: Buf, + offset?: number +): Buf; +function v1( + options?: Version1Options, + buf?: TBuf, + offset?: number +): UUIDTypes { let bytes: Uint8Array; // Extract _v6 flag from options, clearing options if appropriate @@ -73,7 +81,7 @@ function v1(options?: Version1Options, buf?: Uint8Array, offset?: number): UUIDT ); } - return buf ? bytes : unsafeStringify(bytes); + return buf ?? unsafeStringify(bytes); } // (Private!) Do not use. This method is only exported for testing purposes diff --git a/src/v3.ts b/src/v3.ts index 66a3c409..447bce1c 100644 --- a/src/v3.ts +++ b/src/v3.ts @@ -10,13 +10,18 @@ function v3( buf?: undefined, offset?: number ): string; -function v3( +function v3( + value: string | Uint8Array, + namespace: UUIDTypes, + buf: TBuf, + offset?: number +): TBuf; +function v3( value: string | Uint8Array, namespace: UUIDTypes, - buf: Uint8Array, + buf?: TBuf, offset?: number -): Uint8Array; -function v3(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) { +): UUIDTypes { return v35(0x30, md5, value, namespace, buf, offset); } diff --git a/src/v35.ts b/src/v35.ts index faaf0456..6b445a5f 100644 --- a/src/v35.ts +++ b/src/v35.ts @@ -20,14 +20,14 @@ export const URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'; type HashFunction = (bytes: Uint8Array) => Uint8Array; -export default function v35( +export default function v35( version: 0x30 | 0x50, hash: HashFunction, value: string | Uint8Array, namespace: UUIDTypes, - buf?: Uint8Array, + buf?: TBuf, offset?: number -) { +): UUIDTypes { const valueBytes: Uint8Array = typeof value === 'string' ? stringToBytes(value) : value; const namespaceBytes: Uint8Array = typeof namespace === 'string' ? parse(namespace) : namespace; diff --git a/src/v4.ts b/src/v4.ts index 0459b59b..1eb52aad 100644 --- a/src/v4.ts +++ b/src/v4.ts @@ -4,8 +4,16 @@ import { unsafeStringify } from './stringify.js'; import { UUIDTypes, Version4Options } from './types.js'; function v4(options?: Version4Options, buf?: undefined, offset?: number): string; -function v4(options: Version4Options | undefined, buf: Uint8Array, offset?: number): Uint8Array; -function v4(options?: Version4Options, buf?: Uint8Array, offset?: number): UUIDTypes { +function v4( + options: Version4Options | undefined, + buf: TBuf, + offset?: number +): TBuf; +function v4( + options?: Version4Options, + buf?: TBuf, + offset?: number +): UUIDTypes { if (native.randomUUID && !buf && !options) { return native.randomUUID(); } diff --git a/src/v5.ts b/src/v5.ts index c72ac1fc..b35f8896 100644 --- a/src/v5.ts +++ b/src/v5.ts @@ -10,13 +10,18 @@ function v5( buf?: undefined, offset?: number ): string; -function v5( +function v5( + value: string | Uint8Array, + namespace: UUIDTypes, + buf: TBuf, + offset?: number +): TBuf; +function v5( value: string | Uint8Array, namespace: UUIDTypes, - buf: Uint8Array, + buf?: TBuf, offset?: number -): Uint8Array; -function v5(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) { +): UUIDTypes { return v35(0x50, sha1, value, namespace, buf, offset); } diff --git a/src/v6.ts b/src/v6.ts index 1469c226..4173c432 100644 --- a/src/v6.ts +++ b/src/v6.ts @@ -4,8 +4,16 @@ import v1 from './v1.js'; import v1ToV6 from './v1ToV6.js'; function v6(options?: Version6Options, buf?: undefined, offset?: number): string; -function v6(options: Version6Options | undefined, buf: Uint8Array, offset?: number): Uint8Array; -function v6(options?: Version6Options, buf?: Uint8Array, offset?: number): UUIDTypes { +function v6( + options: Version6Options | undefined, + buf: TBuf, + offset?: number +): TBuf; +function v6( + options?: Version6Options, + buf?: TBuf, + offset?: number +): UUIDTypes { options ??= {}; offset ??= 0; diff --git a/src/v7.ts b/src/v7.ts index 95198788..b55f64c9 100644 --- a/src/v7.ts +++ b/src/v7.ts @@ -10,8 +10,16 @@ type V7State = { const _state: V7State = {}; function v7(options?: Version7Options, buf?: undefined, offset?: number): string; -function v7(options: Version7Options | undefined, buf: Uint8Array, offset?: number): Uint8Array; -function v7(options?: Version7Options, buf?: Uint8Array, offset?: number): UUIDTypes { +function v7( + options: Version7Options | undefined, + buf: TBuf, + offset?: number +): TBuf; +function v7( + options?: Version7Options, + buf?: TBuf, + offset?: number +): UUIDTypes { let bytes: Uint8Array; if (options) { @@ -33,7 +41,7 @@ function v7(options?: Version7Options, buf?: Uint8Array, offset?: number): UUIDT bytes = v7Bytes(rnds, _state.msecs, _state.seq, buf, offset); } - return buf ? bytes : unsafeStringify(bytes); + return buf ?? unsafeStringify(bytes); } // (Private!) Do not use. This method is only exported for testing purposes