[api-extractor] Support "export { x }" for converting a source file's exports into a named module

[donahut]

Given an index.ts such as:

import * as d from './d';

export * from './A';
export * from './B';
export * from './C';

export {
    d
};

The generated .apt.ts only produces valid output for A, B and C, whereas d produces things like:
// WARNING: The name ""<path>/lib/dts/d/index"" contains unsupported characters; API names should use only letters, numbers, and underscores
and
module "<path>/lib/dts/d/index" {

This sort of local namespacing and export pattern is used throughout our codebase, so any workarounds would be welcome.

[octogonz]

This should get fixed during June as part of our sprint to convert the *.api.ts files to be generated using the new analysis engine that was created for the *.d.ts rollups.

[adventure-yunfei]

@pgonzal is this sovled now? still get this error.

[southpolesteve]

I ran into this issue too. Was able to work around a by refactoring some of our exported types.

[octogonz]

I had actually not looked very closely at the original example. There are two unsupported things going on here:

// 1. Converting a source file's exports into a named module
import * as d from './d';

// 2. Exporting a symbol that was locally defined earlier in the same file
export { d };

Thanks for bringing this to my attention. I've actually never seen this pattern in real usage before heheh. From a "TypeScript: the good parts" mindset, it strikes me as slightly odd: We tend to take the perspective that when you write a declaration, you are defining an API, versus defining a piece of plumbing that other files might combine to produce the final API. This philosophy has several practical benefits:

• Our own unit tests and internal code should use the API in the same way that a third-party developer would use it.
• We try to avoid giving two different names to the same type. It would be confusing. For example, it would make it harder for people to search a large code base to find all references to a given declaration, which is a pretty important scenario.
• API definitions should correspond to a small palette of common stereotypes, that are easy for people to recognize, and that the documentation system can represent nicely.

For the case of export { d };, it's unclear where the doc comment for d should even go. The places I can think of (above 1, above 2, or as a first doc comment in the original source file) all have technical complexities due to how the parser handles "trivia" between ast nodes.

That said, I believe that the .d.ts rollup engine should support this feature. Right now API Extractor fails hard with Error: Unsupported export: blah on this input, which is not expected behavior.

[octogonz]

The fix for this is related to Issue #949 . We'll tackle them together after AE7 is released.

[adventure-yunfei]

@pgonzal I thought this issue is fixed by #773, still not working? I'm using this syntax and it works fine for me. (tested with lastest version - api-extractor@6.1.6 and api-documenter@1.5.56)

[octogonz]

I thought this issue is fixed by #773, still not working? I'm using this syntax and it works fine for me. (tested with lastest version - api-extractor@6.1.6 and api-documenter@1.5.56)

@adventure-yunfei are you using .d.ts rollups? Or just generating API documentation? That might be the difference.

This sort of local namespacing and export pattern is used throughout our codebase, so any workarounds would be welcome.

@donahut BTW the workaround is pretty easy. For example, instead of this:

d.ts

  /**
    * (Doc comment for Example) 
    * @public 
    */
export class Example { }

index.ts

import * as d from './d';

// (doc comment won't be recognized here)
export { d };

...you could replace it with this:

d.ts

/**
  * (Doc comment for d) 
  * @public 
  */
export namespace d {
  /**
    * (Doc comment for Example) 
    * @public 
    */
  export class Example { }
}

index.ts

export { d } from './d';