lib: refactor internal webidl converters

Rework lib/internal/webidl.js into a documented shared converter
module that follows the Web IDL conversion algorithms more closely.

Improvements:
- Add documented converters and helper factories for dictionaries,
  enums, sequences, interfaces, required arguments, and integers.
- Move WebCrypto to the shared converters, keeping compatibility
  wrappers for existing BufferSource and BigInteger behavior.
- Use shared converters from Blob, Performance, Web Locks, and
  structured clone option handling.
- Add focused tests for core converters, WebCrypto converters,
  integer conversion, and buffer source behavior.

Fixes:
- Make core BufferSource and Uint8Array reject resizable ArrayBuffer
  and growable SharedArrayBuffer backing stores unless allowed.
  This is non-breaking because the core behavior has no runtime
  consumers other than WebCrypto. WebCrypto keeps its legacy behavior
  until a semver-major follow-up opts in to the correct behavior.
- Use Web IDL ToNumber and ToString behavior for BigInt, Symbol, and
  object primitive conversion.
- Use exact BigInt modulo for 64-bit ConvertToInt wrapping and
  document the Number approximation behavior.
- Normalize mathematical modulo results to +0 where Web IDL requires it.
- Cover detached buffers, resizable-backed views, growable-backed
  views, cross-realm buffer sources, and mutation-after-call behavior.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>

Author: panva

lib/internal/blob.js

@@ -54,7 +54,6 @@ const {
 const { inspect } = require('internal/util/inspect');
 const {
   converters,
-  convertToInt,
   createSequenceConverter,
 } = require('internal/webidl');
 
@@ -245,10 +244,14 @@ class Blob {
     if (!isBlob(this))
       throw new ERR_INVALID_THIS('Blob');
 
-    // Coerce values to int
-    const opts = { __proto__: null, signed: true };
-    start = convertToInt('start', start, 64, opts);
-    end = convertToInt('end', end, 64, opts);
+    start = converters['long long'](
+      start,
+      { __proto__: null, context: 'start' },
+    );
+    end = converters['long long'](
+      end,
+      { __proto__: null, context: 'end' },
+    );
 
     if (start < 0) {
       start = MathMax(this[kLength] + start, 0);

lib/internal/crypto/webidl.js

@@ -1,101 +1,33 @@
 'use strict';
 
-// Adapted from the following sources
-// - https://github.com/jsdom/webidl-conversions
-//   Copyright Domenic Denicola. Licensed under BSD-2-Clause License.
-//   Original license at https://github.com/jsdom/webidl-conversions/blob/master/LICENSE.md.
-// - https://github.com/denoland/deno
-//   Copyright Deno authors. Licensed under MIT License.
-//   Original license at https://github.com/denoland/deno/blob/main/LICENSE.md.
-// Changes include using primordials and stripping the code down to only what
-// WebCryptoAPI needs.
-
 const {
-  ArrayBufferIsView,
   ArrayPrototypeIncludes,
-  ArrayPrototypePush,
-  ArrayPrototypeSort,
   MathPow,
-  MathTrunc,
-  Number,
-  NumberIsFinite,
   NumberParseInt,
   ObjectPrototypeHasOwnProperty,
-  ObjectPrototypeIsPrototypeOf,
   SafeArrayIterator,
-  String,
   StringPrototypeStartsWith,
   StringPrototypeToLowerCase,
-  TypedArrayPrototypeGetBuffer,
-  TypedArrayPrototypeGetSymbolToStringTag,
 } = primordials;
 
-const {
-  converters: sharedConverters,
-  makeException,
-  createEnumConverter,
-  createSequenceConverter,
-} = require('internal/webidl');
-
 const {
   lazyDOMException,
   kEmptyObject,
-  setOwnProperty,
 } = require('internal/util');
 const { CryptoKey } = require('internal/crypto/webcrypto');
 const {
   validateMaxBufferLength,
   kNamedCurveAliases,
 } = require('internal/crypto/util');
-const { isSharedArrayBuffer } = require('internal/util/types');
-
-// https://tc39.es/ecma262/#sec-tonumber
-function toNumber(value, opts = kEmptyObject) {
-  switch (typeof value) {
-    case 'number':
-      return value;
-    case 'bigint':
-      throw makeException(
-        'is a BigInt and cannot be converted to a number.',
-        opts);
-    case 'symbol':
-      throw makeException(
-        'is a Symbol and cannot be converted to a number.',
-        opts);
-    default:
-      return Number(value);
-  }
-}
-
-function type(V) {
-  if (V === null)
-    return 'Null';
-
-  switch (typeof V) {
-    case 'undefined':
-      return 'Undefined';
-    case 'boolean':
-      return 'Boolean';
-    case 'number':
-      return 'Number';
-    case 'string':
-      return 'String';
-    case 'symbol':
-      return 'Symbol';
-    case 'bigint':
-      return 'BigInt';
-    case 'object': // Fall through
-    case 'function': // Fall through
-    default:
-      // Per ES spec, typeof returns an implementation-defined value that is not
-      // any of the existing ones for uncallable non-standard exotic objects.
-      // Yet Type() which the Web IDL spec depends on returns Object for such
-      // cases. So treat the default case as an object.
-      return 'Object';
-  }
-}
-
-const integerPart = MathTrunc;
+const {
+  converters: webidl,
+  createDictionaryConverter,
+  createEnumConverter,
+  createInterfaceConverter,
+  createSequenceConverter,
+  requiredArguments,
+  type,
+} = require('internal/webidl');
 
 function validateByteLength(buf, name, target) {
   if (buf.byteLength !== target) {
@@ -119,79 +51,7 @@ function namedCurveValidator(V, dict) {
       'NotSupportedError');
 }
 
-// This was updated to only consider bitlength up to 32 used by WebCryptoAPI
-function createIntegerConversion(bitLength) {
-  const lowerBound = 0;
-  const upperBound = MathPow(2, bitLength) - 1;
-
-  const twoToTheBitLength = MathPow(2, bitLength);
-
-  return (V, opts = kEmptyObject) => {
-    let x = toNumber(V, opts);
-
-    if (opts.enforceRange) {
-      if (!NumberIsFinite(x)) {
-        throw makeException(
-          'is not a finite number.',
-          opts);
-      }
-
-      x = integerPart(x);
-
-      if (x < lowerBound || x > upperBound) {
-        throw makeException(
-          `is outside the expected range of ${lowerBound} to ${upperBound}.`,
-          { __proto__: null, ...opts, code: 'ERR_OUT_OF_RANGE' },
-        );
-      }
-
-      return x;
-    }
-
-    if (!NumberIsFinite(x) || x === 0) {
-      return 0;
-    }
-
-    x = integerPart(x);
-
-    if (x >= lowerBound && x <= upperBound) {
-      return x;
-    }
-
-    x = x % twoToTheBitLength;
-
-    return x;
-  };
-}
-
-const converters = {};
-
-converters.boolean = (val) => !!val;
-converters.octet = createIntegerConversion(8);
-converters['unsigned short'] = createIntegerConversion(16);
-converters['unsigned long'] = createIntegerConversion(32);
-
-converters.DOMString = function(V, opts = kEmptyObject) {
-  if (typeof V === 'string') {
-    return V;
-  } else if (typeof V === 'symbol') {
-    throw makeException(
-      'is a Symbol and cannot be converted to a string.',
-      opts);
-  }
-
-  return String(V);
-};
-
-converters.object = (V, opts) => {
-  if (type(V) !== 'Object') {
-    throw makeException(
-      'is not an object.',
-      opts);
-  }
-
-  return V;
-};
+const converters = { ...webidl };
 
 /**
  * @param {string | object} V - The hash algorithm identifier (string or object).
@@ -205,117 +65,6 @@ function ensureSHA(V, label) {
       `Only SHA hashes are supported in ${label}`, 'NotSupportedError');
 }
 
-converters.Uint8Array = (V, opts = kEmptyObject) => {
-  if (!ArrayBufferIsView(V) ||
-    TypedArrayPrototypeGetSymbolToStringTag(V) !== 'Uint8Array') {
-    throw makeException(
-      'is not an Uint8Array object.',
-      opts);
-  }
-  if (isSharedArrayBuffer(TypedArrayPrototypeGetBuffer(V))) {
-    throw makeException(
-      'is a view on a SharedArrayBuffer, which is not allowed.',
-      opts);
-  }
-
-  return V;
-};
-
-converters.BufferSource = sharedConverters.BufferSource;
-
-converters['sequence<DOMString>'] = createSequenceConverter(
-  converters.DOMString);
-
-function requiredArguments(length, required, opts = kEmptyObject) {
-  if (length < required) {
-    throw makeException(
-      `${required} argument${
-        required === 1 ? '' : 's'
-      } required, but only ${length} present.`,
-      { __proto__: null, ...opts, context: '', code: 'ERR_MISSING_ARGS' });
-  }
-}
-
-function createDictionaryConverter(name, dictionaries) {
-  let hasRequiredKey = false;
-  const allMembers = [];
-  for (let i = 0; i < dictionaries.length; i++) {
-    const member = dictionaries[i];
-    if (member.required) {
-      hasRequiredKey = true;
-    }
-    ArrayPrototypePush(allMembers, member);
-  }
-  ArrayPrototypeSort(allMembers, (a, b) => {
-    if (a.key === b.key) {
-      return 0;
-    }
-    return a.key < b.key ? -1 : 1;
-  });
-
-  return function(V, opts = kEmptyObject) {
-    const typeV = type(V);
-    switch (typeV) {
-      case 'Undefined':
-      case 'Null':
-      case 'Object':
-        break;
-      default:
-        throw makeException(
-          'can not be converted to a dictionary',
-          opts);
-    }
-    const esDict = V;
-    const idlDict = {};
-
-    // Fast path null and undefined.
-    if (V == null && !hasRequiredKey) {
-      return idlDict;
-    }
-
-    for (const member of new SafeArrayIterator(allMembers)) {
-      const key = member.key;
-
-      let esMemberValue;
-      if (typeV === 'Undefined' || typeV === 'Null') {
-        esMemberValue = undefined;
-      } else {
-        esMemberValue = esDict[key];
-      }
-
-      if (esMemberValue !== undefined) {
-        const context = `'${key}' of '${name}'${
-          opts.context ? ` (${opts.context})` : ''
-        }`;
-        const idlMemberValue = member.converter(esMemberValue, {
-          __proto__: null,
-          ...opts,
-          context,
-        });
-        member.validator?.(idlMemberValue, esDict);
-        setOwnProperty(idlDict, key, idlMemberValue);
-      } else if (member.required) {
-        throw makeException(
-          `can not be converted to '${name}' because '${key}' is required in '${name}'.`,
-          { __proto__: null, ...opts, code: 'ERR_MISSING_OPTION' });
-      }
-    }
-
-    return idlDict;
-  };
-}
-
-function createInterfaceConverter(name, prototype) {
-  return (V, opts) => {
-    if (!ObjectPrototypeIsPrototypeOf(prototype, V)) {
-      throw makeException(
-        `is not of type ${name}.`,
-        opts);
-    }
-    return V;
-  };
-}
-
 converters.AlgorithmIdentifier = (V, opts) => {
   // Union for (object or DOMString)
   if (type(V) === 'Object') {
@@ -365,7 +114,27 @@ const dictAlgorithm = [
 converters.Algorithm = createDictionaryConverter(
   'Algorithm', dictAlgorithm);
 
-converters.BigInteger = converters.Uint8Array;
+// TODO(panva): Reject resizable backing stores in a semver-major with:
+// converters.BigInteger = webidl.Uint8Array;
+converters.BigInteger = (V, opts = kEmptyObject) => {
+  return webidl.Uint8Array(V, {
+    __proto__: null,
+    ...opts,
+    allowResizable: true,
+    allowShared: false,
+  });
+};
+
+// TODO(panva): Reject resizable backing stores in a semver-major by
+// removing this altogether.
+converters.BufferSource = (V, opts = kEmptyObject) => {
+  return webidl.BufferSource(V, {
+    __proto__: null,
+    ...opts,
+    allowResizable: opts.allowResizable === undefined ?
+      true : opts.allowResizable,
+  });
+};
 
 const dictRsaKeyGenParams = [
   ...new SafeArrayIterator(dictAlgorithm),

lib/internal/locks.js

@@ -43,7 +43,7 @@ const kConstructLock = Symbol('kConstructLock');
 const kConstructLockManager = Symbol('kConstructLockManager');
 
 // WebIDL dictionary LockOptions
-const convertLockOptions = createDictionaryConverter([
+const convertLockOptions = createDictionaryConverter('LockOptions', [
   {
     key: 'mode',
     converter: createEnumConverter('LockMode', [

lib/internal/perf/performance.js

@@ -44,7 +44,7 @@ const timerify = require('internal/perf/timerify');
 const { customInspectSymbol: kInspect, kEnumerableProperty, kEmptyObject } = require('internal/util');
 const { inspect } = require('util');
 const { validateThisInternalField } = require('internal/validators');
-const { convertToInt } = require('internal/webidl');
+const { converters } = require('internal/webidl');
 
 const kPerformanceBrand = Symbol('performance');
 
@@ -144,8 +144,10 @@ class Performance extends EventTarget {
     if (arguments.length === 0) {
       throw new ERR_MISSING_ARGS('maxSize');
     }
-    // unsigned long
-    maxSize = convertToInt('maxSize', maxSize, 32);
+    maxSize = converters['unsigned long'](
+      maxSize,
+      { __proto__: null, context: 'maxSize' },
+    );
     return setResourceTimingBufferSize(maxSize);
   }