chore: Generating separate API reports for module entry points

[hiranya911]

So far we have been exporting all API declarations through default-namespace.d.ts in order to generate a single API report that includes all of our APIs. However, we do not want to export everything from the above file. Since it is the declaration of the top-level admin namespace, it should only export the direct members of admin such as admin.initializeApp() and admin.auth. There are also other technical reasons why we cannot export everything from this file. For example, both RTDB and Firestore modules export a member named Query. Trying to export both these types from the same file results in an error.

Fixing this means we have to change how we generate API reports, and adopt a one report per module entry point scheme. API Extractor doesn't support this natively yet, and therefore I'm implementing a simple script that generates separate API reports for each entry point. I declare the following map of entry points:

const entryPoints = {
  'firebase-admin': './lib/default-namespace.d.ts',
  'firebase-admin/app': './lib/app/index.d.ts',
  'firebase-admin/auth': './lib/auth/index.d.ts',
  'firebase-admin/database': './lib/database/index.d.ts',
  'firebase-admin/instance-id': './lib/instance-id/index.d.ts',
};

Then I iterate over the map, invoking API Extractor on each entry point. Generated reports are added under the etc/ directory.

While this results in a set of comprehensive API reports (while enabling us to only export the necessary elements from default-namespace.d.ts), there are also a few caveats:

1. The API report of the top-level firebase-admin module which contains all the namespaces like admin.auth and admin.database, ends up with a lot of ae-forgotten-export warnings. This is because we export type aliases from each of the namespaces, without directly exporting the alias target. For example firebase-admin exports the admin.auth.UserRecord type alias, but not what it points to. This gets reported as a warning in the generated report:

// Warning: (ae-forgotten-export) The symbol "UserRecord" needs to be exported by the entry point default-namespace.d.ts

2. Other service-level API reports emit an ae-forgotten-export warnings for the App type which comes from a separate module outside the immediate entry point.

// Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts

Hopefully, we shall decommission the top-level admin namespace some day making the 1st issue irrelevant. 2nd issue is more of an annoyance at this point, and might get fixed if API Extractor starts supporting multiple entry points in the future.

[hiranya911]

Check the end of CI build logs to see the new script in action.

[hiranya911]

@Feiyang1 adding you for a quick look as well. This is my current solution to the multiple entry points problem with API Extractor. I'm ignoring the whole documentation issue for now (I'm hoping we can continue to use Typedoc or use a custom API Documenter plugin for that). But this gets us to a point where we can generate API reports for each entry point.

[lahirumaramba]

Thanks for making this change. The custom script makes sense to me.

[Feiyang1]

LGTM.

You can also try the AE fork I published ("api-extractor-me": "0.1.1"), which supports multiple entry points and generates one api report per entry point.

See
https://github.com/firebase/firebase-js-sdk/blob/master/packages/firestore/api-extractor.json for how to define multiple entrypoints.