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-conversionsVerified import paths — ran on the pinned version, not inferred.
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`.
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).
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.
Remove direct calls to `conversions.Function` or `conversions.VoidFunction`. If you need to convert JavaScript functions according to Web IDL rules, consider using `webidl2js`.
Update any code that references `conversions.void` to use `conversions.undefined` instead.
Remove any code that uses `conversions.Error`. Handle JavaScript error objects directly or use appropriate Web IDL types for error-like scenarios.
Discontinue use of `conversions.Date` and `conversions.RegExp`. Convert these types using standard JavaScript methods if needed.
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.
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.
Use the ES module import syntax: `import conversions from 'webidl-conversions';`.
Remove usage of `conversions.Function` and `conversions.VoidFunction`. These are no longer part of the library and typically handled by `webidl2js` for interface binding.
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.
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);`
No dependency data recorded yet.