Registry / serialization / webidl-conversions

webidl-conversions

JSON →
library8.0.1jsnpmunverified

webidl-conversions is a JavaScript library that rigorously implements the Web IDL specification's algorithms for converting JavaScript values to and from Web IDL types. It ensures strict adherence to the Web IDL type conversion rules, including handling edge cases, type coercion, and error conditions, to provide consistent behavior as if the operations were natively defined in Web IDL. The current stable version is 8.0.1, with major version updates typically occurring annually to align with Node.js version requirements and Web IDL specification changes. Key differentiators include its meticulous adherence to the spec, support for multiple JavaScript realms, and options for customizing conversion behavior like clamping integers or allowing shared/resizable buffers, making it a critical component for libraries implementing Web APIs in JavaScript.

npm install webidl-conversions
INSTALL
IMPORT
SIG · WEBIDL-CONVERSIONS
W
webidl-conversions
serializationjavascriptv8.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

conversions
✓ const conversions = require('webidl-conversions');
The package's main module exports an object containing all conversion methods for CommonJS environments.
conversions
✓ import conversions from 'webidl-conversions';
✗ import { boolean, unsignedLong } from 'webidl-conversions';
For ES Modules, the default export is the 'conversions' object. Individual conversion functions are properties of this object, not named exports.
booleanConversion
✓ const booleanConversion = conversions.boolean;
✗ import { boolean } from 'webidl-conversions';
Individual Web IDL type conversion functions (e.g., 'boolean', 'unsigned long') are accessed as properties of the main 'conversions' object.

This quickstart demonstrates how to import and use the `webidl-conversions` library to emulate Web IDL type conversions for function arguments, showcasing common types like `DOMString`, `unsigned long`, `float`, and `object`, along with options like `treatNullAsEmptyString` and `clamp`.

import conversions from 'webidl-conversions'; // Example: Implementing a function that mirrors a Web IDL operation function doWebIDLStuff(name, count) { try { // Convert 'name' to DOMString, treating null as empty string const domName = conversions.DOMString(name, { treatNullAsEmptyString: true }); // Convert 'count' to unsigned long, clamping if out of range const ulCount = conversions['unsigned long'](count, { enforceRange: true, clamp: true }); console.log(`Processing item: "${domName}" with count: ${ulCount}`); // Demonstrate another conversion: float const floatValue = conversions.float(Math.PI / 2); console.log(`Float value of PI/2: ${floatValue}`); // Demonstrate object conversion const obj = conversions.object({ a: 1, b: 'hello' }); console.log('Object conversion successful:', obj); return `Processed ${domName} ${ulCount} times.`; } catch (error) { if (error instanceof TypeError) { console.error(`Web IDL Conversion Error: ${error.message}`); return `Failed to process: ${error.message}`; } else { throw error; } } } // Run some examples console.log(doWebIDLStuff('Widget A', 10)); console.log(doWebIDLStuff(null, -5)); // treatNullAsEmptyString and clamp will handle this console.log(doWebIDLStuff('Item C', '100')); // String '100' converts to number 100 console.log(doWebIDLStuff('Invalid Float', NaN)); // float(NaN) will throw a TypeError console.log(doWebIDLStuff('Large Number', 999999999999)); // To run this: save as .mjs and run with Node.js >= 20
Debug
Known issues
breakingVersion 8.0.0 and newer require Node.js version 20 or greater. Attempting to use it with older Node.js versions will result in errors.
fix
Upgrade your Node.js environment to version 20 or higher, or use an older version of `webidl-conversions` compatible with your Node.js runtime (e.g., v7.x for Node.js >=12, v6.x for Node.js >=10.4).
affects: >=8.0.0
breakingIn v8.0.0, support for environments without SharedArrayBuffer was removed. The `allowShared` option was removed from the `ArrayBuffer` export, and a new `SharedArrayBuffer` export was added, aligning with Web IDL spec updates.
fix
If you rely on SharedArrayBuffer conversion logic, ensure your environment supports it. For `ArrayBuffer` conversions, remove the `allowShared` option. Use the new `SharedArrayBuffer` export for explicit conversions.
affects: >=8.0.0
breakingVersion 7.0.0 removed the `Function` and `VoidFunction` exports. These types are now recommended to be handled by `webidl2js`.
fix
Remove direct calls to `conversions.Function` or `conversions.VoidFunction`. If you need to convert JavaScript functions according to Web IDL rules, consider using `webidl2js`.
affects: >=7.0.0
breakingIn version 7.0.0, the `void` export was renamed to `undefined` to reflect updates in the Web IDL specification.
fix
Update any code that references `conversions.void` to use `conversions.undefined` instead.
affects: >=7.0.0
breakingVersion 5.0.0 removed the `Error` export, as the `Error` type was removed from the Web IDL specification.
fix
Remove any code that uses `conversions.Error`. Handle JavaScript error objects directly or use appropriate Web IDL types for error-like scenarios.
affects: >=5.0.0
breakingVersion 4.0.0 removed the `Date` and `RegExp` exports because these types were also removed from the Web IDL specification.
fix
Discontinue use of `conversions.Date` and `conversions.RegExp`. Convert these types using standard JavaScript methods if needed.
affects: >=4.0.0
gotchaConversions for `float` and `unrestricted float` will throw a `TypeError` if the input value is `NaN`, as per the Web IDL specification (float values must be finite).
fix
Always ensure inputs to `conversions.float` or `conversions['unrestricted float']` are finite numbers. Perform a `Number.isFinite()` check before conversion or wrap the conversion in a `try-catch` block.
affects: >=4.0.0
Errors
Common errors & fixes
TypeError: Argument X of Y is not a finite floating-point value.
Attempting to convert a non-finite number (like `NaN` or `Infinity`) using `conversions.float` or `conversions['unrestricted float']`, which, according to Web IDL, must be finite.
fix
Before converting to `float`, ensure the value is finite using `Number.isFinite(value)`. If it's not finite, handle the condition gracefully or provide a finite default.
ReferenceError: require is not defined in ES module scope
Attempting to use `require('webidl-conversions')` inside an ES module (e.g., in a `.mjs` file or when `type: 'module'` is set in `package.json`).
fix
Use the ES module import syntax: `import conversions from 'webidl-conversions';`.
TypeError: conversions.Function is not a function
Calling `conversions.Function` or `conversions.VoidFunction` after upgrading to version 7.0.0 or later, where these exports were removed.
fix
Remove usage of `conversions.Function` and `conversions.VoidFunction`. These are no longer part of the library and typically handled by `webidl2js` for interface binding.
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for .../node_modules/webidl-conversions/index.ts
This package is not published as TypeScript source files that need transpilation by the consumer, but rather compiled JavaScript. This error might indicate a misconfiguration in a build system or an incorrect environment.
fix
Ensure your Node.js environment meets the minimum version requirement (>=20 for v8.x) and that your module resolution is correctly configured. `webidl-conversions` is distributed as plain JavaScript; this error typically suggests a problem external to the library itself, possibly with how your project is trying to import or transpile modules.
SyntaxError: The requested module 'webidl-conversions' does not provide an export named 'boolean'
Attempting to destructure individual conversion functions like `boolean` or `unsignedLong` directly from the `webidl-conversions` package in an ES module import statement.
fix
The library's default export is an object containing all conversion functions as properties. Import the entire object and then access the functions: `import conversions from 'webidl-conversions'; const booleanValue = conversions.boolean(input);`
Upgrade
Version history
8.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
OpenAI (training)
1
Resources