@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