`IntegerTypedArray` type required for use with `crypto.getRandomValues`

[lionel-rowe]

⚙ Compilation target

any

⚙ Library

latest

Missing / Incorrect Definition

The current DOM types <T extends ArrayBufferView | null> are wrong for crypto.getRandomValues. null is never accepted, and ArrayBufferView is too broad as float arrays also aren't accepted.

However, fixing in TypeScript-DOM-lib-generator requires conditional inclusion of BigInt64Array | BigUint64Array depending on ES2020 availability. I don't think there's a way to fix that within TypeScript-DOM-lib-generator without this upstream change in TypeScript.

es5.d.ts:

interface IntegerTypedArrayTypes {
    Int8Array: Int8Array;
    Int16Array: Int16Array;
    Int32Array: Int32Array;
    Uint8Array: Uint8Array;
    Uint16Array: Uint16Array;
    Uint32Array: Uint32Array;
    Uint8ClampedArray: Uint8ClampedArray;
}

type IntegerTypedArray = IntegerTypedArrayTypes[keyof IntegerTypedArrayTypes];

es2020.bigint.d.ts:

interface IntegerTypedArrayTypes {
    BigInt64Array: BigInt64Array;
    BigUint64Array: BigUint64Array;
}

Sample Code

// Unused '@ts-expect-error' directive.(2578)
// @ts-expect-error
crypto.getRandomValues(null)
// Unused '@ts-expect-error' directive.(2578)
// @ts-expect-error
crypto.getRandomValues(new Float64Array())

declare const arr: Parameters<typeof crypto.getRandomValues>[0]
const values = crypto.getRandomValues(arr)

// 'values' is possibly 'null'.(18047)
values.BYTES_PER_ELEMENT

// Property 'BYTES_PER_ELEMENT' does not exist on type 'ArrayBufferView<ArrayBufferLike>'.(2339)
values!.BYTES_PER_ELEMENT

Documentation Link

10.1.1 The getRandomValues method - Web Cryptography Level 2

If array is not an Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, or BigUint64Array, then throw a TypeMismatchError and terminate the algorithm.

[aryzing]

Seems the same would apply to crypto.subtle.importKey:

• https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#keydata

[RyanCavanaugh]

crypto.getRandomValues still accepts Float64Array in TypeScript 6.0.3 and the current native compiler, although browsers reject it. Its return type also loses the typed-array members of an argument obtained from Parameters<typeof crypto.getRandomValues>.

The concise code that demonstrates the result is:

// Expected: getRandomValues should reject Float64Array and return the specific typed-array argument type.
// Actual: Float64Array is accepted, and a Parameters-derived argument produces a return type without BYTES_PER_ELEMENT.
crypto.getRandomValues(new Float64Array(1));

declare const array: Parameters<typeof crypto.getRandomValues>[0];
const values = crypto.getRandomValues(array);
values.BYTES_PER_ELEMENT;

With --strict, 6.0.3 and current native report TS2339 on values.BYTES_PER_ELEMENT but no diagnostic for the Float64Array call. In the current browser, an integer typed array is accepted and returned, while Float64Array throws TypeMismatchError and null throws TypeError.