feat: update TS types to allowUint8Array subtypes for buffer option (#865)

Author: BurningEnlightenment

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` |
 

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` |
 

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;

src/types.ts

@@ -1,4 +1,4 @@
-export type UUIDTypes = string | Uint8Array;
+export type UUIDTypes<TBuf extends Uint8Array = Uint8Array> = string | TBuf;
 
 export type Version1Options = {
   node?: Uint8Array;

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<Buf extends Uint8Array = Uint8Array>(
+  options: Version1Options | undefined,
+  buf: Buf,
+  offset?: number
+): Buf;
+function v1<TBuf extends Uint8Array = Uint8Array>(
+  options?: Version1Options,
+  buf?: TBuf,
+  offset?: number
+): UUIDTypes<TBuf> {
   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

src/v3.ts

@@ -10,13 +10,18 @@ function v3(
   buf?: undefined,
   offset?: number
 ): string;
-function v3(
+function v3<TBuf extends Uint8Array = Uint8Array>(
+  value: string | Uint8Array,
+  namespace: UUIDTypes,
+  buf: TBuf,
+  offset?: number
+): TBuf;
+function v3<TBuf extends Uint8Array = Uint8Array>(
   value: string | Uint8Array,
   namespace: UUIDTypes,
-  buf: Uint8Array,
+  buf?: TBuf,
   offset?: number
-): Uint8Array;
-function v3(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) {
+): UUIDTypes<TBuf> {
   return v35(0x30, md5, value, namespace, buf, offset);
 }
 

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<TBuf extends Uint8Array = Uint8Array>(
   version: 0x30 | 0x50,
   hash: HashFunction,
   value: string | Uint8Array,
   namespace: UUIDTypes,
-  buf?: Uint8Array,
+  buf?: TBuf,
   offset?: number
-) {
+): UUIDTypes<TBuf> {
   const valueBytes: Uint8Array = typeof value === 'string' ? stringToBytes(value) : value;
   const namespaceBytes: Uint8Array = typeof namespace === 'string' ? parse(namespace) : namespace;
 

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<TBuf extends Uint8Array = Uint8Array>(
+  options: Version4Options | undefined,
+  buf: TBuf,
+  offset?: number
+): TBuf;
+function v4<TBuf extends Uint8Array = Uint8Array>(
+  options?: Version4Options,
+  buf?: TBuf,
+  offset?: number
+): UUIDTypes<TBuf> {
   if (native.randomUUID && !buf && !options) {
     return native.randomUUID();
   }

src/v5.ts

@@ -10,13 +10,18 @@ function v5(
   buf?: undefined,
   offset?: number
 ): string;
-function v5(
+function v5<TBuf extends Uint8Array = Uint8Array>(
+  value: string | Uint8Array,
+  namespace: UUIDTypes,
+  buf: TBuf,
+  offset?: number
+): TBuf;
+function v5<TBuf extends Uint8Array = Uint8Array>(
   value: string | Uint8Array,
   namespace: UUIDTypes,
-  buf: Uint8Array,
+  buf?: TBuf,
   offset?: number
-): Uint8Array;
-function v5(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) {
+): UUIDTypes<TBuf> {
   return v35(0x50, sha1, value, namespace, buf, offset);
 }
 

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<TBuf extends Uint8Array = Uint8Array>(
+  options: Version6Options | undefined,
+  buf: TBuf,
+  offset?: number
+): TBuf;
+function v6<TBuf extends Uint8Array = Uint8Array>(
+  options?: Version6Options,
+  buf?: TBuf,
+  offset?: number
+): UUIDTypes<TBuf> {
   options ??= {};
   offset ??= 0;