webidl2js - npm Package Compare versions

Comparing version 7.3.0 to 7.4.0

lib/constructs/iterable.js

@@ -57,3 +57,3 @@ "use strict";
         ${this.obj.name}.prototype.keys = Array.prototype.keys;
-        ${this.obj.name}.prototype.values = Array.prototype.values;
+        ${this.obj.name}.prototype.values = Array.prototype[Symbol.iterator];
       `;
@@ -60,0 +60,0 @@ }

lib/parameters.js

@@ -79,7 +79,37 @@ "use strict";
 
+      // For variadic operations, we only try to fully support non-overloaded variadic operations right now. It is a
+      // TODO to support overloaded variadic functions. The decision to only support the simplest cases of variadic
+      // operations is made, because overload resolution for overloaded variadic operations is non-trivial but hardly
+      // used in the Web platform (or at least the jsdom-supported subset of it), and because the entire overload
+      // resolution apparatus will require a rewrite for https://github.com/jsdom/webidl2js/issues/29.
+      //
+      // To determine that the current argument we are processing is the variadic one, the following three-fold
+      // algorithm is used:
+      //
+      // 1. The current argument must the last one.
+      // 2. The effective overload set must have a length of two (one with the final variadic argument, one without).
+      // 3. The current argument must have an optionality value of "variadic" in either one of the overloads.
+      const curIsVariadic = i + 1 === maxArguments && overloads.length === 2 &&
+                            (overloads[0].optionalityList[i] === "variadic" ||
+                             overloads[1].optionalityList[i] === "variadic");
+      let msg = `"${errPrefix}parameter ${i + 1}"`;
+      let lvalue = `args[${i}]`;
+
+      if (curIsVariadic) {
+        msg = `"${errPrefix}parameter " + (i + 1)`;
+        lvalue = `args[i]`;
+        str += `for (let i = ${i}; i < arguments.length; ++i) {`;
+
+        // The object will not be re-used outside of this function, so mutating it is fine here.
+        typeConversions[i].optional = false;
+      }
+
       const conv = generateVarConversion(
-        ctx, `args[${i}]`, typeConversions[i], maxConstructor.operation.arguments[i].extAttrs, parentName,
-        `"${errPrefix}parameter ${i + 1}"`);
+        ctx, lvalue, typeConversions[i], maxConstructor.operation.arguments[i].extAttrs, parentName, msg);
       requires.merge(conv.requires);
       str += conv.body;
+
+      if (curIsVariadic) {
+        str += "}";
+      }
     }
@@ -86,0 +116,0 @@ }

package.json

 {
   "name": "webidl2js",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Auto-generates class structures for WebIDL specifications",
@@ -5,0 +5,0 @@ "main": "lib/transformer.js",

README.md

@@ -231,4 +231,46 @@ # JavaScript bindings generator for Web IDL
 
-One other subtlety here is overloads: if the IDL file defines overloads for a given operation, webidl2js is not always as helpful as it could be. It does not dispatch to separate implementation class methods, but instead performs the overload resolution algorithm and then sends the result to the same backing method. In some cases, it won't even unwrap incoming wrappers into impls. We're hoping to fix this ([#29](https://github.com/jsdom/webidl2js/issues/29)), but in the meantime, properly implementing overloads requires doing some extra type-checking (often using appropriate `isImpl()` functions) to determine which case of the overload you ended up in, and manual unwrapping.
+#### Overloaded operations
 
+One other subtlety here is overloads: if the IDL file defines overloads for a given operation, webidl2js is not always as helpful as it could be.
+
+1. webidl2js does not yet implement the [overload resolution algorithm](https://heycam.github.io/webidl/#dfn-overload-resolution-algorithm) fully. Take the `overload1()` operations below:
+
+   ```webidl
+   void overload1(DOMString first, long second);
+   void overload1(DOMString first, long second, DOMString third);
+   ```
+
+   webidl2js fully handles type conversion for both `first` and `second` arguments, but does not try to convert the third argument even if it is provided.
+
+   Similarly, consider the following `overload2()` operations:
+
+   ```webidl
+   void overload2(Blob first, long second);
+   void overload2(long first, long second);
+   ```
+
+   webidl2js only converts `second` argument because its type is unambiguous, and calls the implementation method with `first` unconverted. In particular, this means that webidl2js will not try to unwrap the `first` argument into a `Blob` implementation class, even if it is a `Blob`.
+
+2. webidl2js does not dispatch overloaded operations to separate implementation class methods, but instead performs type conversions if possible and then sends the result to the same backing method.
+
+We're hoping to fix both of these problems in [#29](https://github.com/jsdom/webidl2js/issues/29). But in the meantime, properly implementing overloads requires doing some extra type-checking (often using appropriate [`is()`](#isvalue) functions) to determine which case of the overload you ended up in, and manual conversion with [webidl-conversions][] and/or unwrapping.
+
+#### Variadic operations
+
+Variadic operations are fully supported by webidl2js, but only if the particular operation is not overloaded. So while type conversions for the `simple1` and `simple2` operations below are fully implemented, webidl2js will not provide any variadic semantics for `overloaded1()` or `overloaded2()`.
+
+```webidl
+void simple1(DOMString... strings);
+
+void simple2(DOMString first, URL... urls);
+
+void overloaded1(DOMString... strings);
+void overloaded1(unsigned long... numbers);
+
+void overloaded2(DOMString first, DOMString... strings);
+void overloaded2(unsigned long first, DOMString... strings);
+```
+
+We hope to fix this problem in the overload resolution overhaul ([#29](https://github.com/jsdom/webidl2js/issues/29)). Right now, however, manual conversions will be needed for overloaded variadic operations.
+
 ### Properties implementing IDL attributes
@@ -240,2 +282,26 @@
 
+### toString method implementing IDL stringifier
+
+Web IDL allows stringifiers to be either *aliased* to a specific attribute or named operation, or *standalone*. If the interface defines a standalone stringifier, the implementation class should define a string-returning `toString` method implementing the stringification behavior of that interface. The method is not needed if the stringifier is aliased: webidl2js will just call the attribute getter or named operation for stringification.
+
+```webidl
+stringifier;                                 // `toString()` is needed on the implementation class.
+stringifier attribute DOMString attr;        // `toString()` is not needed.
+stringifier           DOMString operation(); // `toString()` is not needed.
+```
+
+### Indexed and named properties
+
+IDL indexed and named properties require multiple things on the implementation class to work properly.
+
+The first is the getters, (optional) setters, and (optional) deleters operations. Much like stringifiers, getters, setters, and deleters can either be standalone or aliased to a named operation (though not an attribute). If an operation is standalone, then the implementation class must implement following symbol-named methods. The `utils` object below refers to the default export from the generated utilities file `utils.js`.
+
+- Getters: `utils.indexedGet`, `utils.namedGet`
+- Setters: `utils.indexedSetNew`, `utils.indexedSetExisting`, `utils.namedSetNew`, `utils.namedSetExisting`
+- Deleters: `utils.namedDelete`
+
+The second is the interface's supported property indices/names. By default, the implementation class should implement both a Boolean-returning `utils.supportsPropertyIndex`/`utils.supportsPropertyName` method that takes a single Number or String argument, respectively, and an iterable-returning `utils.supportedPropertyIndices`/`utils.supportedPropertyNames` for each variety of getters the interface exposes.
+
+If the getter function always returns a constant value for unsupported properties, webidl2js also offers a non-standard extended attribute `[WebIDL2JSValueAsUnsupported]` (documented below) that would simply call the getter function to check if a property index/name is supported, so that `supportsPropertyIndex`/`supportsPropertyName` would not need to be implemented separately. However, when using the extended attribute, be very sure that the value specified in the attribute is returned *if and only if* the property is unsupported.
+
 ### Other, non-exposed data and functionality
@@ -289,2 +355,3 @@
   - Stringifiers
+  - Named and indexed `getter`/`setter`/`deleter` declarations
   - `iterable<>` declarations
@@ -302,6 +369,6 @@ - Class strings (with the semantics of [heycam/webidl#357](https://github.com/heycam/webidl/pull/357))
 - Partial interfaces and dictionaries
-- Basic types (via [webidl-conversions](https://github.com/jsdom/webidl-conversions))
+- Basic types (via [webidl-conversions][])
 - Mixins, i.e. `implements` (with a [notable bug](https://github.com/jsdom/webidl2js/issues/49))
-- Overload resolution (although [tricky cases are not easy on the implementation class](https://github.com/jsdom/webidl2js/issues/29))
-- Variadic arguments
+- Overload resolution (although [tricky cases are not easy on the implementation class](#overloaded-operations))
+- Variadic arguments ([only non-overloaded operations](#variadic-operations) are supported though)
 - `[Clamp]`
@@ -311,2 +378,5 @@ - `[Constructor]`
 - `[Exposed]` and `[NoInterfaceObject]` (by exporting metadata on where/whether it is exposed)
+- `[LegacyArrayClass]`
+- `[LegacyUnenumerableNamedProperties]`
+- `[OverrideBuiltins]`
 - `[PutForwards]`
@@ -321,7 +391,5 @@ - `[Replaceable]`
 
-- Legacy platform objects, i.e. those using `getter`/`setter`/`deleter` declarations ([in progress](https://github.com/jsdom/webidl2js/pull/48))
 - Namespaces
 - Enumeration types ([#28](https://github.com/jsdom/webidl2js/issues/28))
 - Callback interfaces
-- Named constructors
 - `maplike<>` and `setlike<>`
@@ -331,4 +399,2 @@ - `[AllowShared]`
 - `[Global]` and `[PrimaryGlobal]`'s various consequences, including the named properties object and `[[SetPrototypeOf]]`
-- `[LegacyArrayClass]`
-- `[LegacyUnemerableNamedProperties]`
 - `[LegacyWindowAlias]`
@@ -338,3 +404,2 @@ - `[LenientSetter]`
 - `[NamedConstructor]`
-- `[OverrideBuiltins]` ([in progress](https://github.com/jsdom/webidl2js/pull/48))
 - `[SecureContext]`
@@ -362,1 +427,9 @@ - `[TreatNonObjectAsNull]`
 It is currently used by [jsdom](https://github.com/tmpvar/jsdom) for classes which need to specialize their behavior per `Window` object; by default [jsdom shares classes across all `Window`s](https://github.com/tmpvar/jsdom#shared-constructors-and-prototypes), but with `[WebIDL2JSFactory]`, an exception can be made for certain classes that need it.
+
+### `[WebIDL2JSValueAsUnsupported=value]`
+
+This extended attribute can be applied to named or indexed getters or setters. It says that whether the interface supports a given property name/index can be automatically derived by looking at the return value of its indexed getter/setter: whenever `value` is returned, the name/index is unsupported. Typically, `value` is either `undefined` or `null`.
+
+In practice, this means that the implementation class only needs to implement a single method (the named/indexed getter method), and doesn't need to implement the `[idlUtils.supportsPropertyName]()` or `[idlUtils.supportsPropertyIndex]()` method separately.
+
+[webidl-conversions]: https://github.com/jsdom/webidl-conversions

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

122602

increased by5.65%

Lines of code

2907

increased by0.9%

Number of lines in readme file

427

increased by20.62%

No dependency changes