webidl-conversions

What is webidl-conversions?

The webidl-conversions npm package is used to convert JavaScript values to WebIDL types, as specified in the WebIDL specification. It is often used in the context of web development when implementing interfaces defined in WebIDL that need to interact with JavaScript code.

What are webidl-conversions's main functionalities?

Converting basic types

Converts a JavaScript string to a WebIDL 'long' type.

const conversions = require('webidl-conversions');
let myValue = '123';
let convertedValue = conversions.long(myValue);

Converting with options

Converts a JavaScript string to a WebIDL 'long' type with clamping enabled, which means the value will be clamped to the nearest allowed value if it's out of range.

const conversions = require('webidl-conversions');
let myValue = '123';
let convertedValue = conversions.long(myValue, { clamp: true });

Handling nullable types

Converts a null value to a WebIDL 'DOMString' type, treating null as an empty string.

const conversions = require('webidl-conversions');
let myValue = null;
let convertedValue = conversions.DOMString(myValue, { treatNullAsEmptyString: true });

Other packages similar to webidl-conversions

heya-unify

Heya-unify is a library for unifying JavaScript values with type descriptions. It is similar to webidl-conversions in that it deals with type conversions, but it is more focused on unification patterns and not specifically on WebIDL types.

typescript

TypeScript is a superset of JavaScript that adds static types. While not a direct alternative to webidl-conversions, it provides a type system that can help ensure that values match expected types at compile time, rather than performing runtime conversions.

README

Web IDL Type Conversions on JavaScript Values

This package implements, in JavaScript, the algorithms to convert a given JavaScript value according to a given Web IDL type.

The goal is that you should be able to write code like

"use strict";
const conversions = require("webidl-conversions");

function doStuff(x, y) {
    x = conversions["boolean"](x);
    y = conversions["unsigned long"](y);
    // actual algorithm code here
}

and your function doStuff will behave the same as a Web IDL operation declared as

void doStuff(boolean x, unsigned long y);

API

This package's main module's default export is an object with a variety of methods, each corresponding to a different Web IDL type. Each method, when invoked on a JavaScript value, will give back the new JavaScript value that results after passing through the Web IDL conversion rules. (See below for more details on what that means.) Alternately, the method could throw an error, if the Web IDL algorithm is specified to do so: for example conversions["float"](NaN) will throw a TypeError.

Each method also accepts a second, optional, parameter for miscellaneous options. For conversion methods that throw errors, a string option { context } may be provided to provide more information in the error message. (For example, conversions["float"](NaN, { context: "Argument 1 of Interface's operation" }) will throw an error with message "Argument 1 of Interface's operation is not a finite floating-point value.") Specific conversions may also accept other options, the details of which can be found below.

Conversions implemented

Conversions for all of the basic types from the Web IDL specification are implemented:

• any
• void
• boolean
• Integer types, which can additionally be provided the boolean options { clamp, enforceRange } as a second parameter
• float, unrestricted float
• double, unrestricted double
• DOMString, which can additionally be provided the boolean option { treatNullAsEmptyString } as a second parameter
• ByteString, USVString
• object
• Error
• Buffer source types

Additionally, for convenience, the following derived type definitions are implemented:

• ArrayBufferView
• BufferSource
• DOMTimeStamp
• Function
• VoidFunction (although it will not censor the return type)

Derived types, such as nullable types, promise types, sequences, records, etc. are not handled by this library. You may wish to investigate the webidl2js project.

A note on the long long types

The long long and unsigned long long Web IDL types can hold values that cannot be stored in JavaScript numbers, so the conversion is imperfect. For example, converting the JavaScript number 18446744073709552000 to a Web IDL long long is supposed to produce the Web IDL value -18446744073709551232. Since we are representing our Web IDL values in JavaScript, we can't represent -18446744073709551232, so we instead the best we could do is -18446744073709552000 as the output.

This library actually doesn't even get that far. Producing those results would require doing accurate modular arithmetic on 64-bit intermediate values, but JavaScript does not make this easy. We could pull in a big-integer library as a dependency, but in lieu of that, we for now have decided to just produce inaccurate results if you pass in numbers that are not strictly between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER.

Background

What's actually going on here, conceptually, is pretty weird. Let's try to explain.

Web IDL, as part of its madness-inducing design, has its own type system. When people write algorithms in web platform specs, they usually operate on Web IDL values, i.e. instances of Web IDL types. For example, if they were specifying the algorithm for our doStuff operation above, they would treat x as a Web IDL value of Web IDL type boolean. Crucially, they would not treat x as a JavaScript variable whose value is either the JavaScript true or false. They're instead working in a different type system altogether, with its own rules.

Separately from its type system, Web IDL defines a "binding" of the type system into JavaScript. This contains rules like: when you pass a JavaScript value to the JavaScript method that manifests a given Web IDL operation, how does that get converted into a Web IDL value? For example, a JavaScript true passed in the position of a Web IDL boolean argument becomes a Web IDL true. But, a JavaScript true passed in the position of a Web IDL unsigned long becomes a Web IDL 1. And so on.

Finally, we have the actual implementation code. This is usually C++, although these days some smart people are using Rust. The implementation, of course, has its own type system. So when they implement the Web IDL algorithms, they don't actually use Web IDL values, since those aren't "real" outside of specs. Instead, implementations apply the Web IDL binding rules in such a way as to convert incoming JavaScript values into C++ values. For example, if code in the browser called doStuff(true, true), then the implementation code would eventually receive a C++ bool containing true and a C++ uint32_t containing 1.

The upside of all this is that implementations can abstract all the conversion logic away, letting Web IDL handle it, and focus on implementing the relevant methods in C++ with values of the correct type already provided. That is payoff of Web IDL, in a nutshell.

And getting to that payoff is the goal of this project—but for JavaScript implementations, instead of C++ ones. That is, this library is designed to make it easier for JavaScript developers to write functions that behave like a given Web IDL operation. So conceptually, the conversion pipeline, which in its general form is JavaScript values ↦ Web IDL values ↦ implementation-language values, in this case becomes JavaScript values ↦ Web IDL values ↦ JavaScript values. And that intermediate step is where all the logic is performed: a JavaScript true becomes a Web IDL 1 in an unsigned long context, which then becomes a JavaScript 1.

Don't use this

Seriously, why would you ever use this? You really shouldn't. Web IDL is … strange, and you shouldn't be emulating its semantics. If you're looking for a generic argument-processing library, you should find one with better rules than those from Web IDL. In general, your JavaScript should not be trying to become more like Web IDL; if anything, we should fix Web IDL to make it more like JavaScript.

The only people who should use this are those trying to create faithful implementations (or polyfills) of web platform interfaces defined in Web IDL. Its main consumer is the jsdom project.