Skip to content

Commit a5231e7

Browse files
BurningEnlightenmentBurningEnlightenment
authored
feat: update TS types to allowUint8Array subtypes for buffer option (#865)
1 parent aeabb60 commit a5231e7

File tree

11 files changed

+80
-30
lines changed

11 files changed

+80
-30
lines changed

‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ Create an RFC version 1 (timestamp) UUID
180180
| [`options.nsecs = 0`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) |
181181
| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
182182
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
183-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
183+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
184184
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
185185
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
186186
| _throws_ | `Error` if more than 10M UUIDs/sec are requested |
@@ -244,7 +244,7 @@ Create an RFC version 4 (random) UUID
244244
| [`options`] | `Object` with one or more of the following properties: |
245245
| [`options.random`] | `Array` of 16 random bytes (0-255) |
246246
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
247-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
247+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
248248
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
249249
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
250250

@@ -292,7 +292,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID
292292
| --- | --- |
293293
| `name` | `String \| Array` |
294294
| `namespace` | `String \| Array[16]` Namespace UUID |
295-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
295+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
296296
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
297297
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
298298

@@ -367,7 +367,7 @@ Create an RFC version 7 (random) UUID
367367
| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
368368
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
369369
| [`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. |
370-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
370+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
371371
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
372372
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
373373

‎README_js.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ Create an RFC version 1 (timestamp) UUID
189189
| [`options.nsecs = 0`] | RFC "timestamp" field (`Number` of nanoseconds to add to `msecs`, should be 0-10,000) |
190190
| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
191191
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
192-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
192+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
193193
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
194194
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
195195
| _throws_ | `Error` if more than 10M UUIDs/sec are requested |
@@ -253,7 +253,7 @@ Create an RFC version 4 (random) UUID
253253
| [`options`] | `Object` with one or more of the following properties: |
254254
| [`options.random`] | `Array` of 16 random bytes (0-255) |
255255
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
256-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
256+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
257257
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
258258
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
259259

@@ -301,7 +301,7 @@ Create an RFC version 5 (namespace w/ SHA-1) UUID
301301
| --- | --- |
302302
| `name` | `String \| Array` |
303303
| `namespace` | `String \| Array[16]` Namespace UUID |
304-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
304+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
305305
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
306306
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
307307

@@ -376,7 +376,7 @@ Create an RFC version 7 (random) UUID
376376
| [`options.random = (random)`] | `Array` of 16 random bytes (0-255) used to generate other fields, above |
377377
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
378378
| [`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. |
379-
| [`buffer`] | `Uint8Array` If provided, binary UUID is written into the array, starting at `offset` |
379+
| [`buffer`] | `Uint8Array` or `Uint8Array` subtype (e.g. Node.js `Buffer`). If provided, binary UUID is written into the array, starting at `offset` |
380380
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
381381
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
382382

‎examples/typescript/buffer.test.ts

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/* eslint-disable @typescript-eslint/ban-ts-comment */
2+
import { v1 } from 'uuid';
3+
4+
v1(undefined, new Uint8Array(16)) satisfies Uint8Array;
5+
v1(undefined, Buffer.alloc(16)) satisfies Buffer;
6+
7+
// @ts-expect-error
8+
v1(undefined, new Uint8Array(16)) satisfies Buffer;

‎src/types.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
export type UUIDTypes = string | Uint8Array;
1+
export type UUIDTypes<TBuf extends Uint8Array = Uint8Array> = string | TBuf;
22

33
export type Version1Options = {
44
node?: Uint8Array;

‎src/v1.ts

+11-3
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,16 @@ type V1State = {
2525
const _state: V1State = {};
2626

2727
function v1(options?: Version1Options, buf?: undefined, offset?: number): string;
28-
function v1(options: Version1Options | undefined, buf: Uint8Array, offset?: number): Uint8Array;
29-
function v1(options?: Version1Options, buf?: Uint8Array, offset?: number): UUIDTypes {
28+
function v1<Buf extends Uint8Array = Uint8Array>(
29+
options: Version1Options | undefined,
30+
buf: Buf,
31+
offset?: number
32+
): Buf;
33+
function v1<TBuf extends Uint8Array = Uint8Array>(
34+
options?: Version1Options,
35+
buf?: TBuf,
36+
offset?: number
37+
): UUIDTypes<TBuf> {
3038
let bytes: Uint8Array;
3139

3240
// Extract _v6 flag from options, clearing options if appropriate
@@ -73,7 +81,7 @@ function v1(options?: Version1Options, buf?: Uint8Array, offset?: number): UUIDT
7381
);
7482
}
7583

76-
return buf ? bytes : unsafeStringify(bytes);
84+
return buf ?? unsafeStringify(bytes);
7785
}
7886

7987
// (Private!) Do not use. This method is only exported for testing purposes

‎src/v3.ts

+9-4
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,18 @@ function v3(
1010
buf?: undefined,
1111
offset?: number
1212
): string;
13-
function v3(
13+
function v3<TBuf extends Uint8Array = Uint8Array>(
14+
value: string | Uint8Array,
15+
namespace: UUIDTypes,
16+
buf: TBuf,
17+
offset?: number
18+
): TBuf;
19+
function v3<TBuf extends Uint8Array = Uint8Array>(
1420
value: string | Uint8Array,
1521
namespace: UUIDTypes,
16-
buf: Uint8Array,
22+
buf?: TBuf,
1723
offset?: number
18-
): Uint8Array;
19-
function v3(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) {
24+
): UUIDTypes<TBuf> {
2025
return v35(0x30, md5, value, namespace, buf, offset);
2126
}
2227

‎src/v35.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,14 @@ export const URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
2020

2121
type HashFunction = (bytes: Uint8Array) => Uint8Array;
2222

23-
export default function v35(
23+
export default function v35<TBuf extends Uint8Array = Uint8Array>(
2424
version: 0x30 | 0x50,
2525
hash: HashFunction,
2626
value: string | Uint8Array,
2727
namespace: UUIDTypes,
28-
buf?: Uint8Array,
28+
buf?: TBuf,
2929
offset?: number
30-
) {
30+
): UUIDTypes<TBuf> {
3131
const valueBytes: Uint8Array = typeof value === 'string' ? stringToBytes(value) : value;
3232
const namespaceBytes: Uint8Array = typeof namespace === 'string' ? parse(namespace) : namespace;
3333

‎src/v4.ts

+10-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,16 @@ import { unsafeStringify } from './stringify.js';
44
import { UUIDTypes, Version4Options } from './types.js';
55

66
function v4(options?: Version4Options, buf?: undefined, offset?: number): string;
7-
function v4(options: Version4Options | undefined, buf: Uint8Array, offset?: number): Uint8Array;
8-
function v4(options?: Version4Options, buf?: Uint8Array, offset?: number): UUIDTypes {
7+
function v4<TBuf extends Uint8Array = Uint8Array>(
8+
options: Version4Options | undefined,
9+
buf: TBuf,
10+
offset?: number
11+
): TBuf;
12+
function v4<TBuf extends Uint8Array = Uint8Array>(
13+
options?: Version4Options,
14+
buf?: TBuf,
15+
offset?: number
16+
): UUIDTypes<TBuf> {
917
if (native.randomUUID && !buf && !options) {
1018
return native.randomUUID();
1119
}

‎src/v5.ts

+9-4
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,18 @@ function v5(
1010
buf?: undefined,
1111
offset?: number
1212
): string;
13-
function v5(
13+
function v5<TBuf extends Uint8Array = Uint8Array>(
14+
value: string | Uint8Array,
15+
namespace: UUIDTypes,
16+
buf: TBuf,
17+
offset?: number
18+
): TBuf;
19+
function v5<TBuf extends Uint8Array = Uint8Array>(
1420
value: string | Uint8Array,
1521
namespace: UUIDTypes,
16-
buf: Uint8Array,
22+
buf?: TBuf,
1723
offset?: number
18-
): Uint8Array;
19-
function v5(value: string | Uint8Array, namespace: UUIDTypes, buf?: Uint8Array, offset?: number) {
24+
): UUIDTypes<TBuf> {
2025
return v35(0x50, sha1, value, namespace, buf, offset);
2126
}
2227

‎src/v6.ts

+10-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,16 @@ import v1 from './v1.js';
44
import v1ToV6 from './v1ToV6.js';
55

66
function v6(options?: Version6Options, buf?: undefined, offset?: number): string;
7-
function v6(options: Version6Options | undefined, buf: Uint8Array, offset?: number): Uint8Array;
8-
function v6(options?: Version6Options, buf?: Uint8Array, offset?: number): UUIDTypes {
7+
function v6<TBuf extends Uint8Array = Uint8Array>(
8+
options: Version6Options | undefined,
9+
buf: TBuf,
10+
offset?: number
11+
): TBuf;
12+
function v6<TBuf extends Uint8Array = Uint8Array>(
13+
options?: Version6Options,
14+
buf?: TBuf,
15+
offset?: number
16+
): UUIDTypes<TBuf> {
917
options ??= {};
1018
offset ??= 0;
1119

‎src/v7.ts

+11-3
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,16 @@ type V7State = {
1010
const _state: V7State = {};
1111

1212
function v7(options?: Version7Options, buf?: undefined, offset?: number): string;
13-
function v7(options: Version7Options | undefined, buf: Uint8Array, offset?: number): Uint8Array;
14-
function v7(options?: Version7Options, buf?: Uint8Array, offset?: number): UUIDTypes {
13+
function v7<TBuf extends Uint8Array = Uint8Array>(
14+
options: Version7Options | undefined,
15+
buf: TBuf,
16+
offset?: number
17+
): TBuf;
18+
function v7<TBuf extends Uint8Array = Uint8Array>(
19+
options?: Version7Options,
20+
buf?: TBuf,
21+
offset?: number
22+
): UUIDTypes<TBuf> {
1523
let bytes: Uint8Array;
1624

1725
if (options) {
@@ -33,7 +41,7 @@ function v7(options?: Version7Options, buf?: Uint8Array, offset?: number): UUIDT
3341
bytes = v7Bytes(rnds, _state.msecs, _state.seq, buf, offset);
3442
}
3543

36-
return buf ? bytes : unsafeStringify(bytes);
44+
return buf ?? unsafeStringify(bytes);
3745
}
3846

3947
// (Private!) Do not use. This method is only exported for testing purposes

0 commit comments

Comments
 (0)