feat: add new Event support for extensible params (#218)

Author: MarshallOfSound

base/base_header.ts

@@ -5,5 +5,5 @@
 
 /// <reference types="node" />
 
-type GlobalEvent = Event & { returnValue: any };
+type DOMEvent = Event;
 type GlobalResponse = Response;

base/base_inner.ts

@@ -1,5 +1,10 @@
   const NodeEventEmitter: typeof import('events').EventEmitter;
 
-  class Accelerator extends String {
+  type EmptyParams = {};
+  type Event<Params extends object, Sender extends NodeJS.EventEmitter> = {
+    preventDefault: () => void;
+    readonly defaultPrevented: boolean;
+    sender: Sender;
+  } & Params;
 
-  }
+  class Accelerator extends String {}

package.json

@@ -21,7 +21,7 @@
   "license": "MIT",
   "devDependencies": {
     "@continuous-auth/semantic-release-npm": "^3.0.0",
-    "@electron/docs-parser": "^1.0.1",
+    "@electron/docs-parser": "^1.1.0",
     "@types/debug": "^4.1.4",
     "@types/fs-extra": "^5.0.5",
     "@types/lodash": "^4.14.123",

src/dynamic-param-interfaces.ts

@@ -118,8 +118,7 @@ const flushParamInterfaces = (
       )
       .forEach(paramKey => {
         if (paramKey === 'Event') {
-          delete paramInterfacesToDeclare[paramKey];
-          return;
+          throw 'Unexpected dynamic Event type, should be routed through the Event handler';
         }
         if (declared[paramKey]) {
           const toDeclareCheck: ParamInterface = Object.assign(

src/module-declaration.ts

@@ -13,6 +13,9 @@ import {
   DetailedFunctionType,
   ElementDocumentationContainer,
   DocumentationTag,
+  PropertyDocumentationBlock,
+  DetailedEventType,
+  DetailedEventReferenceType,
 } from '@electron/docs-parser';
 
 const modules: Record<string, string[]> = {};
@@ -100,16 +103,17 @@ export const generateModuleDeclaration = (
 
           moduleEvent.parameters.forEach((eventListenerArg, index) => {
             let argString = '';
-            if (eventListenerArg.description) {
+            const additionalTags = (eventListenerArg as any).additionalTags || [];
+            if (eventListenerArg.description || additionalTags.length) {
               if (index === 0) argString += `\n${indent}`;
               argString += utils
-                .wrapComment(eventListenerArg.description)
+                .wrapComment(eventListenerArg.description, additionalTags)
                 .map((l, i) => `${l}\n${indent}`)
                 .join('');
             }
 
             let argType: string | null = null;
-            const objectListenerArg = eventListenerArg as DetailedObjectType &
+            const objectListenerArg = eventListenerArg as (DetailedObjectType) &
               DocumentationBlock &
               TypeInformation & { required: boolean };
             if (
@@ -127,6 +131,38 @@ export const generateModuleDeclaration = (
               );
             }
 
+            const eventGenericListenerArg = eventListenerArg as (DetailedEventType) &
+              DocumentationBlock &
+              TypeInformation & { required: boolean };
+            const eventReferenceListenerArg = eventListenerArg as (DetailedEventReferenceType) &
+              DocumentationBlock &
+              TypeInformation & { required: boolean };
+
+            if (eventGenericListenerArg.type === 'Event') {
+              let eventParamsType = 'EmptyParams';
+              if (
+                eventGenericListenerArg.eventProperties &&
+                eventGenericListenerArg.eventProperties.length
+              ) {
+                const fakeObject: any = {
+                  name: 'EventParams',
+                  type: 'Object',
+                  collection: false,
+                  properties: eventGenericListenerArg.eventProperties,
+                };
+                eventParamsType = DynamicParamInterfaces.createParamInterface(
+                  fakeObject,
+                  `${_.upperFirst(_.camelCase(module.name))}${_.upperFirst(
+                    _.camelCase(moduleEvent.name),
+                  )}`,
+                );
+              }
+              if (eventReferenceListenerArg.eventPropertiesReference) {
+                eventParamsType = utils.typify(eventReferenceListenerArg.eventPropertiesReference);
+              }
+              argType = `Event<${eventParamsType}, Electron.${_.upperFirst(module.name)}>`;
+            }
+
             let newType = argType || utils.typify(eventListenerArg);
             const functionListenerArg = (eventListenerArg as any) as DetailedFunctionType &
               DocumentationBlock &
@@ -163,15 +199,15 @@ export const generateModuleDeclaration = (
           moduleAPI,
           utils.wrapComment(domEvent.description, domEvent.additionalTags),
         );
-        let eventType = 'Event';
+        let eventType = 'DOMEvent';
 
         if (domEvent.parameters && domEvent.parameters.length) {
           const fakeObject: any = {
             name: 'event',
             type: 'Object',
             collection: false,
             properties: [],
-            extends: 'Event',
+            extends: 'DOMEvent',
           };
 
           domEvent.parameters.forEach((eventListenerProp, index) => {
@@ -365,6 +401,15 @@ export const generateModuleDeclaration = (
           : '';
         type = type || utils.typify(paramType);
 
+        if (type === 'Function') {
+          type = utils.genMethodString(
+            DynamicParamInterfaces,
+            module,
+            p as any, // FIXME: <--
+            undefined,
+          );
+        }
+
         utils.extendArray(moduleAPI, utils.wrapComment(p.description, p.additionalTags));
         if (module.name === 'process' && p.name === 'versions') return;
 

src/utils.ts

@@ -28,9 +28,9 @@ export const extendArray = <T>(arr1: T[], arr2: T[]): T[] => {
 };
 
 export const wrapComment = (comment: string, additionalTags: DocumentationTag[] = []): string[] => {
-  if (!comment) return [];
+  if (!comment && !additionalTags.length) return [];
   comment = comment.replace(/^\(optional\)(?: - )?/gi, '');
-  if (!comment) return [];
+  if (!comment && !additionalTags.length) return [];
   const result = ['/**'];
   while (comment.length > 0) {
     let index = 0;
@@ -48,7 +48,7 @@ export const wrapComment = (comment: string, additionalTags: DocumentationTag[]
     comment = comment.substring(index + 1);
   }
   if (additionalTags.length) {
-    result.push(' *');
+    if (result.length > 1) result.push(' *');
     const nodePlatforms: string[] = [];
     result.push(
       ...additionalTags
@@ -241,7 +241,6 @@ export const paramify = (paramName: string) => {
 // TODO: Infer through electron-docs-linter/parser
 export const isEmitter = (module: Pick<ModuleDocumentationContainer, 'name'>) => {
   const nonEventEmitters = [
-    'menu',
     'menuitem',
     'nativeimage',
     'shell',

yarn.lock

@@ -34,10 +34,10 @@
     semver "^7.1.2"
     tempy "^1.0.0"
 
-"@electron/docs-parser@^1.0.1":
-  version "1.0.1"
-  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-1.0.1.tgz#f9856d00ec1663a0fb6301f55bc674f44c7dc543"
-  integrity sha512-jqUHwo3MWUhWusHtTVpSHTZqWSVuc1sPUfavI5Zwdx64q7qd4phqOPGoxScWS3JthKt7Wydvo/eReIUNDJ0gRg==
+"@electron/docs-parser@^1.1.0":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-1.1.0.tgz#ba095def41746bde56bee731feaf22272bf0b765"
+  integrity sha512-qrjIKJk8t4/xAYldDVNQgcF8zdAAuG260bzPxdh/xI3p/yddm61bftoct+Tx2crnWFnOfOkr6nGERsDknNiT8A==
   dependencies:
     "@types/markdown-it" "^12.0.0"
     chai "^4.2.0"