Set up chrome-types for upcoming schema changes.

tests/lib/traverse.js

@@ -152,7 +152,6 @@ test('expandFunctionParams returns', t => {
 
 });
 
-
 test('expandFunctionParams returns_async', t => {
   const filter = () => true;
   const tc = new traverse.TraverseContext(filter);
@@ -197,6 +196,37 @@ test('expandFunctionParams returns_async', t => {
   ]);
 });
 
+test('expandFunctionParams returns_async does_not_support_promises', t => {
+  const filter = () => true;
+  const tc = new traverse.TraverseContext(filter);
+
+  /** @type {chromeTypes.TypeSpec} */
+  const returnsAsyncFunction = {
+    type: 'function',
+    parameters: [
+      { type: 'string', name: 's' },
+    ],
+    returns_async: {
+      name: 'callback',
+      type: 'function',
+      does_not_support_promises: 'For testing',
+      parameters: [{ type: 'number', name: 'whatever' }],
+    },
+  };
+
+  const returnsAsyncFunctionExpansions = tc.expandFunctionParams(
+    cloneObject(returnsAsyncFunction),
+    'api:test',
+  );
+  // Since this does not support promises, we expect to only get the callback signature.
+  t.deepEqual(returnsAsyncFunctionExpansions, [
+    [
+      { type: 'void', name: 'return' },
+      { type: 'string', name: 's' },
+      { ...returnsAsyncFunction.returns_async },
+    ]
+  ]);
+});
 
 test('filter', t => {
   /** @type {(spec: chromeTypes.TypeSpec, id: string) => boolean} */

tools/lib/traverse.js

@@ -146,6 +146,24 @@ export class TraverseContext {
     if (!returns_async) {
       return undefined;
     }
+
+    /** @type {chromeTypes.TypeSpec} */
+    let callbackParameter = {
+      ...returns_async,
+      type: 'function',
+    };
+    // If this signature doesn't support promises we just convert the "returns_async" field to a
+    // callback.
+    if (returns_async.does_not_support_promises) {
+      return {
+        withCallback: {
+          ...clone,
+          parameters: [...spec.parameters ?? [], callbackParameter],
+        },
+      };
+    }
+
+    // Otherwise this is a promise signature, so we can do a few checks to make sure it is valid.
     if (spec.returns) {
       throw new Error(`got returns_async and returns on function spec: ${JSON.stringify(spec)}`);
     }
@@ -168,15 +186,8 @@ export class TraverseContext {
       };
     }
 
-    // We convert the "returns_async" field to a callback (it has all the same values).
-    // Force it to be optional: by definition if it's omitted then we'll have a Promise-returning
-    // version. This isn't done correctly in the source.
-    /** @type {chromeTypes.TypeSpec} */
-    const callbackParameter = {
-      ...returns_async,
-      type: 'function',
-      optional: true,
-    };
+    // For promise supporting functions, the callback in inheriently optional, so we force that here.
+    callbackParameter.optional = true;
 
     return {
       withPromise: {
@@ -198,7 +209,7 @@ export class TraverseContext {
 
   /**
    * Chrome supports "early" optional parameters, as well as a special "returns_async" parameter
-   * which actually means that this returns a `Promise` OR supports a callback.
+   * which actually means that this API may return a `Promise` OR supports a callback.
    *
    * This expands all possible combinations for rendering as multiple signatures. The return type
    * includes the signature's return in the 0th position, followed by all parameters.
@@ -208,12 +219,17 @@ export class TraverseContext {
    * @return {[chromeTypes.NamedTypeSpec, ...chromeTypes.NamedTypeSpec[]][]}
    */
   expandFunctionParams(spec, id) {
-    // If this is actually a Promise-supporting API, then we call ourselves again to support both
-    // callback and Promise-based versions.
+    // If this function uses "returns_asyc", expand it out and call ourselves again to generate
+    // the valid signatures (either just callback or Promise and callback).
     const expanded = this._maybeExpandFunctionReturnsAsync(spec);
     if (expanded) {
+      if (expanded.withPromise && expanded.withCallback) {
+        return [
+          ...this.expandFunctionParams(expanded.withPromise, id),
+          ...this.expandFunctionParams(expanded.withCallback, id),
+        ];
+      }
       return [
-        ...this.expandFunctionParams(expanded.withPromise, id),
         ...this.expandFunctionParams(expanded.withCallback, id),
       ];
     }