Gathering detailed insights and metrics for webidl-conversions
The total size of the npm registry is estimated to be over 4 terabytes. This includes all the packages, versions, and metadata stored in the registry.
Gathering detailed insights and metrics for webidl-conversions
The total size of the npm registry is estimated to be over 4 terabytes. This includes all the packages, versions, and metadata stored in the registry.
npm install webidl-conversions
99.5
Supply Chain
99.5
Quality
82
Maintenance
100
Vulnerability
31 Stars
82 Commits
16 Forks
8 Watching
1 Branches
6 Contributors
Updated on 11 May 2024
Minified
Minified + Gzipped
JavaScript (100%)
Cumulative downloads
Total Downloads
Last day
12.6%
15,992,804
Compared to previous day
Last week
14.3%
82,560,414
Compared to previous week
Last month
11.9%
337,322,909
Compared to previous month
Last year
9.4%
3,629,776,838
Compared to previous year
4
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
1"use strict"; 2const conversions = require("webidl-conversions"); 3 4function doStuff(x, y) { 5 x = conversions["boolean"](x); 6 y = conversions["unsigned long"](y); 7 // actual algorithm code here 8}
and your function doStuff
will behave the same as a Web IDL operation declared as
1undefined doStuff(boolean x, unsigned long y);
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."
)
If we are dealing with multiple JavaScript realms (such as those created using Node.js' vm module or the HTML iframe
element), and exceptions from another realm need to be thrown, one can supply an object option globals
containing the following properties:
1{ 2 globals: { 3 Number, 4 String, 5 TypeError 6 } 7}
Those specific functions will be used when throwing exceptions.
Specific conversions may also accept other options, the details of which can be found below.
Conversions for all of the basic types from the Web IDL specification are implemented:
any
undefined
boolean
{ clamp, enforceRange }
as a second parameterfloat
, unrestricted float
double
, unrestricted double
DOMString
, which can additionally be provided the boolean option { treatNullAsEmptyString }
as a second parameterByteString
, USVString
object
{ allowShared }
as a second parameterAdditionally, for convenience, the following derived type definitions are implemented:
ArrayBufferView
, which can additionally be provided with the boolean option { allowShared }
as a second parameterBufferSource
DOMTimeStamp
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.
long long
typesThe long long
and unsigned long long
Web IDL types can hold values that cannot be stored in JavaScript numbers. Conversions are still accurate as we make use of BigInt in the conversion process, but in the case of unsigned long long
we simply cannot represent some possible output values in JavaScript. For example, converting the JavaScript number -1
to a Web IDL unsigned long long
is supposed to produce the Web IDL value 18446744073709551615
. Since we are representing our Web IDL values in JavaScript, we can't represent 18446744073709551615
, so we instead the best we could do is 18446744073709551616
as the output.
To mitigate this, we could return the raw BigInt value from the conversion function, but right now it is not implemented. If your use case requires such precision, file an issue.
On the other hand, long long
conversion is always accurate, since the input value can never be more precise than the output value.
BufferSource
typesAll of the BufferSource
types will throw when the relevant ArrayBuffer
has been detached. This technically is not part of the specified conversion algorithm, but instead part of the getting a reference/getting a copy algorithms. We've consolidated them here for convenience and ease of implementation, but if there is a need to separate them in the future, please open an issue so we can investigate.
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
.
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.
No vulnerabilities found.
Reason
license file detected
Details
Reason
no binaries found in the repo
Reason
no dangerous workflow patterns detected
Reason
security policy file detected
Details
Reason
Found 8/27 approved changesets -- score normalized to 2
Reason
9 existing vulnerabilities detected
Details
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
Reason
project is not fuzzed
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Score
Last Scanned on 2024-11-04
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More