feat(dts-generator): improve support for function types (#487)

- support 'construct' functions using a "new:" parameter
 - allow to specify a 'this' type for a function, using 'this:' parameter
 - support marking parameters as optional by appending a '=' to the
   parameter's type (JSDoc notation)

The parsing of JSDoc types supported these features already, but the
transformation to the dts-generator's AST and the code generation still
had to support it.

Author: codeworrior

packages/dts-generator/src/phases/dts-code-gen.ts

@@ -861,10 +861,13 @@ function genType(ast: Type, usage: string = "unknown"): string {
       return intersectionTypes.join(" & ");
     case "FunctionType":
       text = "";
+      if (ast.isConstructor) {
+        text += "new ";
+      }
       if (!_.isEmpty(ast.typeParameters)) {
         text += `<${_.map(ast.typeParameters, (param) => param.name).join(", ")}>`; // TODO defaults, constraints, expressions
       }
-      text += `(${_.map(ast.parameters, (param) => `${param.name}: ${genType(param.type, "parameter")}`).join(", ")})`;
+      text += `(${_.map(ast.parameters, (param) => `${param.name}${param.optional ? "?" : ""}: ${genType(param.type, "parameter")}`).join(", ")})`;
       text += ` => ${ast.type ? genType(ast.type, "returnValue") : "void"}`;
       return text;
     case "NativeTSTypeExpression":

packages/dts-generator/src/types/ast.d.ts

@@ -238,6 +238,7 @@ export interface FunctionType {
   parameters: Parameter[];
   typeParameters?: TypeParameter[];
   type?: Type;
+  isConstructor?: boolean;
 }
 
 export interface LiteralType {

packages/dts-generator/src/utils/ts-ast-type-builder.ts

@@ -6,6 +6,7 @@ import {
   TypeReference,
   UnionType,
   TypeLiteral,
+  Parameter,
 } from "../types/ast.js";
 
 /**
@@ -109,18 +110,25 @@ export class TSASTTypeBuilder {
     thisType: Type,
     constructorType: Type,
   ): FunctionType {
+    const parameters: Parameter[] = paramTypes.map((param, idx) => ({
+      kind: "Parameter",
+      name: "p" + (idx + 1), // JSDoc function types don't allow parameter names -> generate names
+      type: param,
+      optional: (param as any).optional,
+    }));
+    if (thisType != null) {
+      // for TS, a 'this' type is specified as the first parameter type of a function
+      parameters.unshift({
+        kind: "Parameter",
+        name: "this",
+        type: thisType,
+      });
+    }
     return {
       kind: "FunctionType",
-      parameters: paramTypes.map((param, idx) => ({
-        kind: "Parameter",
-        name: "p" + (idx + 1), // JSDoc function types don't allow parameter names -> generate names
-        type: param,
-      })),
-      type: returnType,
-      /* TODO not supported yet:
-			"this": thisType,
-			constructor: constructorType
-			*/
+      parameters,
+      type: constructorType ?? returnType,
+      isConstructor: constructorType != null,
     };
   }
   structure(structure: {

packages/dts-generator/src/utils/type-parser.ts

@@ -134,6 +134,12 @@ export function TypeParser(
         next(":");
         returnType = parseType();
       }
+      if (constructorType != null && returnType != null) {
+        throw new SyntaxError(
+          `A function signature must either use the 'new' keyword or have a return type, ` +
+            `but not both (pos: ${rLexer.lastIndex}, input='${input}')`,
+        );
+      }
       type = builder.function(
         paramTypes,
         returnType,