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

Lines changed: 4 additions & 4 deletions
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

Lines changed: 4 additions & 4 deletions
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

Lines changed: 8 additions & 0 deletions
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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 11 additions & 3 deletions
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

Lines changed: 9 additions & 4 deletions
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

Lines changed: 3 additions & 3 deletions
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

Lines changed: 10 additions & 2 deletions
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

Lines changed: 9 additions & 4 deletions
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

Lines changed: 10 additions & 2 deletions
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

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy