Merge pull request #4698 from nirshar/api-extractor-export-namespace-fix

[api-extractor] Add support for export namespace syntax

Author: octogonz

apps/api-extractor/src/analyzer/AstNamespaceExport.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { AstNamespaceImport, type IAstNamespaceImportOptions } from './AstNamespaceImport';
+
+export interface IAstNamespaceExportOptions extends IAstNamespaceImportOptions {}
+
+/**
+ * `AstNamespaceExport` represents a namespace that is created implicitly and exported by a statement
+ * such as `export * as example from "./file";`
+ *
+ * @remarks
+ *
+ * A typical input looks like this:
+ * ```ts
+ * // Suppose that example.ts exports two functions f1() and f2().
+ * export * as example from "./file";
+ * ```
+ *
+ * API Extractor's .d.ts rollup will transform it into an explicit namespace, like this:
+ * ```ts
+ * declare f1(): void;
+ * declare f2(): void;
+ *
+ * export declare namespace example {
+ *   export {
+ *     f1,
+ *     f2
+ *   }
+ * }
+ * ```
+ *
+ * The current implementation does not attempt to relocate f1()/f2() to be inside the `namespace`
+ * because other type signatures may reference them directly (without using the namespace qualifier).
+ * The AstNamespaceExports behaves the same as AstNamespaceImport, it just also has the inline export for the craeted namespace.
+ */
+
+export class AstNamespaceExport extends AstNamespaceImport {
+  public constructor(options: IAstNamespaceExportOptions) {
+    super(options);
+  }
+}

apps/api-extractor/src/analyzer/ExportAnalyzer.ts

@@ -14,6 +14,7 @@ import type { IFetchAstSymbolOptions } from './AstSymbolTable';
 import type { AstEntity } from './AstEntity';
 import { AstNamespaceImport } from './AstNamespaceImport';
 import { SyntaxHelpers } from './SyntaxHelpers';
+import { AstNamespaceExport } from './AstNamespaceExport';
 
 /**
  * Exposes the minimal APIs from AstSymbolTable that are needed by ExportAnalyzer.
@@ -562,11 +563,9 @@ export class ExportAnalyzer {
         //   SemicolonToken:  pre=[;]
 
         // Issue tracking this feature: https://github.com/microsoft/rushstack/issues/2780
-        throw new Error(
-          `The "export * as ___" syntax is not supported yet; as a workaround,` +
-            ` use "import * as ___" with a separate "export { ___ }" declaration\n` +
-            SourceFileLocationFormatter.formatDeclaration(declaration)
-        );
+
+        const astModule: AstModule = this._fetchSpecifierAstModule(exportDeclaration, declarationSymbol);
+        return this._getAstNamespaceExport(astModule, declarationSymbol, declaration);
       } else {
         throw new InternalError(
           `Unimplemented export declaration kind: ${declaration.getText()}\n` +
@@ -594,6 +593,25 @@ export class ExportAnalyzer {
     return undefined;
   }
 
+  private _getAstNamespaceExport(
+    astModule: AstModule,
+    declarationSymbol: ts.Symbol,
+    declaration: ts.Declaration
+  ): AstNamespaceExport {
+    const imoprtNamespace: AstNamespaceImport = this._getAstNamespaceImport(
+      astModule,
+      declarationSymbol,
+      declaration
+    );
+
+    return new AstNamespaceExport({
+      namespaceName: imoprtNamespace.localName,
+      astModule: astModule,
+      declaration,
+      symbol: declarationSymbol
+    });
+  }
+
   private _tryMatchImportDeclaration(
     declaration: ts.Declaration,
     declarationSymbol: ts.Symbol
@@ -621,18 +639,7 @@ export class ExportAnalyzer {
 
         if (externalModulePath === undefined) {
           const astModule: AstModule = this._fetchSpecifierAstModule(importDeclaration, declarationSymbol);
-          let namespaceImport: AstNamespaceImport | undefined =
-            this._astNamespaceImportByModule.get(astModule);
-          if (namespaceImport === undefined) {
-            namespaceImport = new AstNamespaceImport({
-              namespaceName: declarationSymbol.name,
-              astModule: astModule,
-              declaration: declaration,
-              symbol: declarationSymbol
-            });
-            this._astNamespaceImportByModule.set(astModule, namespaceImport);
-          }
-          return namespaceImport;
+          return this._getAstNamespaceImport(astModule, declarationSymbol, declaration);
         }
 
         // Here importSymbol=undefined because {@inheritDoc} and such are not going to work correctly for
@@ -759,6 +766,25 @@ export class ExportAnalyzer {
     return undefined;
   }
 
+  private _getAstNamespaceImport(
+    astModule: AstModule,
+    declarationSymbol: ts.Symbol,
+    declaration: ts.Declaration
+  ): AstNamespaceImport {
+    let namespaceImport: AstNamespaceImport | undefined = this._astNamespaceImportByModule.get(astModule);
+    if (namespaceImport === undefined) {
+      namespaceImport = new AstNamespaceImport({
+        namespaceName: declarationSymbol.name,
+        astModule: astModule,
+        declaration: declaration,
+        symbol: declarationSymbol
+      });
+      this._astNamespaceImportByModule.set(astModule, namespaceImport);
+    }
+
+    return namespaceImport;
+  }
+
   private static _getIsTypeOnly(importDeclaration: ts.ImportDeclaration): boolean {
     if (importDeclaration.importClause) {
       return !!importDeclaration.importClause.isTypeOnly;

apps/api-extractor/src/collector/CollectorEntity.ts

@@ -7,6 +7,7 @@ import { AstSymbol } from '../analyzer/AstSymbol';
 import { Collector } from './Collector';
 import { Sort } from '@rushstack/node-core-library';
 import type { AstEntity } from '../analyzer/AstEntity';
+import { AstNamespaceExport } from '../analyzer/AstNamespaceExport';
 
 /**
  * This is a data structure used by the Collector to track an AstEntity that may be emitted in the *.d.ts file.
@@ -82,6 +83,11 @@ export class CollectorEntity {
    * such as "export class X { }" instead of "export { X }".
    */
   public get shouldInlineExport(): boolean {
+    // We export the namespace directly
+    if (this.astEntity instanceof AstNamespaceExport) {
+      return true;
+    }
+
     // We don't inline an AstImport
     if (this.astEntity instanceof AstSymbol) {
       // We don't inline a symbol with more than one exported name