@t15i/webidl-types

webidl-types - TypeScript implementations of WebIDL types

Callable, interned type objects for the WebIDL type system. Each type is a function you call with a JavaScript value to get back the value converted according to its WebIDL rules. The conversion algorithms themselves — long wrapping, unsigned long clamping, DOMString stringification, and so on — are provided by @t15i/webspecs; this package wraps them into composable, introspectable Type objects.

Coverage is intentionally narrow — this is a knowledge base, not a polyfill. Only the types that have been ported so far are listed below; everything else is marked with ....

Install

npm install @t15i/webidl-types

@t15i/webspecs is a peer dependency and must be installed alongside it:

npm install @t15i/webspecs

Usage

Every type is exposed from a single entry point:

import {
  Long,
  DOMString,
  Nullable,
  Sequence,
  Union,
  Annotated,
  EnforceRange,
  // ...
} from "@t15i/webidl-types";

Types are converters

Call a type with a value to convert it per its WebIDL rules:

Long(42); // 42
Long("42"); // 42        (ToNumber, then integer conversion)
Long(4294967297); // 1   (wraps modulo 2^32)
Long(3.9); // 3          (truncates toward zero)

UnsignedLong(-1); // 4294967295
DOMString(123); // "123"
Boolean(0); // false

Types compose

The generic factories build compound types from other types. The result is itself a callable type:

const Ids = Sequence(Long);
Ids([1, 2, 3]); // [1, 2, 3]

const Name = Nullable(DOMString);
Name(null); // null

const Tags = FrozenArray(DOMString);
Object.isFrozen(Tags(["a", "b"])); // true

const Headers = Record(DOMString, DOMString);
const Id = Union(Long, DOMString);

Annotated types carry extended attributes

Wrap a type with WebIDL extended attributes to change how it converts. The attribute markers are re-exported from @t15i/webspecs:

import { Annotated, Long, Clamp, EnforceRange } from "@t15i/webidl-types";

Annotated({ [Clamp]: null }, Long)(4294967297); // 2147483647 (clamped)
Annotated({ [EnforceRange]: null }, Long)(4294967297); // throws TypeError

Types are interned

Structurally equal types are the same object, so you can compare them by identity. Building a type is memoized through the shared typeRegistry:

Nullable(Long) === Nullable(Long); // true
Union(Long, DOMString) === Union(Long, DOMString); // true

Each type also exposes its structural metadata — for example innerType on a Nullable, memberTypes on a Union, and K / V on a Record — which the registry uses to derive a stable id for interning.

What's implemented

A checklist of every WebIDL type. Checked items are implemented and exported by this package.

• any
• undefined → Undefined
• boolean → Boolean
• byte
• octet
• short
• unsigned short
• long → Long
• unsigned long → UnsignedLong
• long long
• unsigned long long
• float
• unrestricted float
• double → Double
• unrestricted double
• bigint → BigInt
• DOMString → DOMString
• ByteString
• USVString → USVString
• object
• symbol
• interface types → InterfaceType
• callback interface types
• dictionary types
• enumeration types
• callback function types
• nullable types → Nullable
• sequence types → Sequence
• async iterable types
• record types → Record
• promise types
• union types → Union
• annotated types → Annotated
• buffer source types
• frozen array types → FrozenArray
• observable array types

License

MIT