@webfeet/webidl

This package implements the WebIDL type coercion rules, with exceptions for some edge cases to keep the library lightweight.

Deviations from WebIDL

• integer types that are clamped to their value range use Math.round() rules for rounding rather than rounding to the closest even number for halfway values (such that 0.5 rounds to 1 rather than 0 for instance).

TODO

Currently, scalar values (boolean, integer and floating-point numbers, bigint, strings, and symbol) as well as object, callback functions, arrays (sequence and FrozenArray), interface types, enumeration types, records, and Promise are implemented; This means that only unions and buffer sources (typed arrays and array views) are missing.

API

This package exports functions whose name starts with coerceTo, that take a value as their single argument, and return that value coerced to the according IDL type. IDL integer types come with variants prefixed with Clamped and Enforced corresponding to the [Clamp] and [EnforceRange] extended attributes respectively. The callback function type has a Legacy variant corresponding to the [LegacyTreatNonObjectAsNull] extended attribute.

const coerced = coerceToLong("-12.3"); // ← -12 as a JavaScript number

A few exported functions, for complex types, take additional arguments. Those always come first, and the value to coerce as the last argument, to make it easier to curry them. Those functions are listed in a separate table below.

const coerced = coerceToSequence(coerceToLong, ["-12.3"]);

The package also exports as @webfeet/webidl/decorators.js a set of ECMAScript decorators to coerce a setter's or auto-accessor property setter's value. The decorators follow the same naming rule as the coercion functions they wrap but without the coerceTo prefix.

class Foo {
  @long accessor bar;

  #baz;
  get baz() {
    return this.#baz;
  }
  @long set baz(value) {
    // `value` has been coerced to a `long`
    this.#baz = value;
  }
}

The coercion functions that take additional arguments have corresponding decorator factories taking those same arguments and returning a decorator.

class Foo {
  @sequence(coerceToLong) accessor bar;
}

| IDL Type | Function | Decorator | | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------- | | any | coerceToAny | any | | undefined | coerceToUndefined | undefined | | boolean | coerceToBoolean | boolean | | byte | coerceToByte | byte | | [Clamp] byte | coerceToClampedByte | clampedByte | | [EnforceRange] byte | coerceToEnforcedByte | enforcedByte | | octet | coerceToOctet | octet | | [Clamp] octet | coerceToClampedOctet | clampedOctet | | [EnforceRange] octet | coerceToEnforcedOctet | enforcedOctet | | short | coerceToShort | short | | [Clamp] short | coerceToClampedShort | clampedShort | | [EnforceRange] short | coerceToEnforcedShort | enforcedShort | | unsigned short | coerceToUnsignedShort | unsignedShort | | [Clamp] unsigned short | coerceToClampedUnsignedShort | clampedUnsignedShort | | [EnforceRange] unsigned short | coerceToEnforcedUnsignedShort | enforcedUnsignedShort | | long | coerceToLong | long | | [Clamp] long | coerceToClampedLong | clampedLong | | [EnforceRange] long | coerceToEnforcedLong | enforcedLong | | unsigned long | coerceToUnsignedLong | unsignedLong | | [Clamp] unsigned long | coerceToClampedUnsignedLong | clampedUnsignedLong | | [EnforceRange] unsigned long | coerceToEnforcedUnsignedLong | enforcedUnsignedLong | | long long | coerceToLongLong | longLong | | [Clamp] long long | coerceToClampedLongLong | clampedLongLong | | [EnforceRange] long long | coerceToEnforcedLongLong | enforcedLongLong | | unsigned long long | coerceToUnsignedLongLong | unsignedLonglong | | [Clamp] unsigned long long | coerceToClampedUnsignedLongLong | clampedUnsignedLongLong | | [EnforceRange] unsigned long long | coerceToEnforcedUnsignedLongLong | enforcedUnsignedLongLong | | float | coerceToFloat | float | | unrestricted float | coerceToUnrestrictedFloat | unrestrictedFloat | | double | coerceToDouble | double | | unrestricted double | coerceToUnrestrictedDouble | unrestrictedDouble | | bigint | coerceToBigInt | bigInt | | DOMString | coerceToDOMString | domString | | ByteString | coerceToByteString | byteString | | USVString | coerceToUSVString | usvString | | object | coerceToObject | object | | symbol | coerceToSymbol | symbol | | callback function | coerceToCallbackFunction | callbackFunction | | [LegacyTreatNonObjectAsNull] callback function | coerceToLegacyCallbackFunction | legacyCallbackFunction |

| IDL Type | Function | Decorator | Additional arguments | | :--------------------------------------------------------------------------- | :---------------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | numeric type or bigint | coerceToBigIntOrNumericType | bigIntOrNumericType | Another coercion function to be applied to a numeric value, defaults to coerceToUnrestrictedDouble | | interface type | coerceToInterface | interfaceType | An interface type, such as HTMLElement | | enumeration type | coerceToEnumeration | enumeration | An array (or rest arguments for the decorator) of allowed string values | | sequence<T> | coerceToSequence | sequence | Another coercion function to be applied to each sequence member, defaults to coerceToAny | | record<K,V> | coerceToRecord | record | Two coercion functions to be applied to each record key and value respectively, where the key has to be a string type, default to coerceToDOMString and coerceToAny | | Promise<T> | coerceToPromise | promise | Another coercion function to be applied to the resolved value | | FrozenArray<T> | coerceToFrozenArray | frozenArray | Another coercion function to be applied to each sequence member, defaults to coerceToAny |