feat!: update the build to use api-extractor types

[matthewrobertson]

This commit updates our build config to use the types generated by the
API extractor. This prevents us exposing private implementation details
in our type declarations that are not marked @public

I also refactored our build scripts a bit so we can ensure api-extractor runs before we publish:

1. removed predocs
2. replaced clean with the first part of compile that deletes the /build dir
3. created a new build that runs clean, compile, docs
4. made prepare and alias for build

[grant]

While it's great to add the API extractor in our scripts, I don't suggest we make the tool run in the TS compilation script.

Moreover, this looks like a copy of && npm run docs.

We already have a predocs script that runs compile.

[matthewrobertson]

the reason I didn't make it && npm run docs is because we have a predocs that runs compile so it would have created a cycle...

[grant]

Right. However, we're repeating ourselves though with api-extractor run --local --verbose.

There are a few ways to avoid this. For example, creating a separate command like api-extractor and running the command there.

However, I'm not sure we want to run the doc extractor when we compile.

For example, it looks like this breaks our watch command:

npm run watch

> @google-cloud/functions-framework@1.10.1 watch
> npm run compile -- --watch


> @google-cloud/functions-framework@1.10.1 compile
> rm -rf ./build && tsc -p . && api-extractor run --local --verbose "--watch"


api-extractor 7.18.16  - https://api-extractor.com/

usage: api-extractor run [-h] [-c FILE] [-l] [-v] [--diagnostics]
                         [--typescript-compiler-folder PATH]
                         
api-extractor run: error: Unrecognized arguments: --watch.

[matthewrobertson]

hmm yeah, I think the key think is I want to make sure we run api-extractor before we publish (so in prepare). I will try to refactor this a bit

[matthewrobertson]

OK I refactored the scripts a bit:

1. removed predocs
2. replaced clean with the first part of compile
3. created a new build that runs clean, compile, docs
4. made prepare and alias for build

[grant]

Right. However, we're repeating ourselves though with api-extractor run --local --verbose.

There are a few ways to avoid this. For example, creating a separate command like api-extractor and running the command there.

However, I'm not sure we want to run the doc extractor when we compile.

For example, it looks like this breaks our watch command:

npm run watch

> @google-cloud/functions-framework@1.10.1 watch
> npm run compile -- --watch


> @google-cloud/functions-framework@1.10.1 compile
> rm -rf ./build && tsc -p . && api-extractor run --local --verbose "--watch"


api-extractor 7.18.16  - https://api-extractor.com/

usage: api-extractor run [-h] [-c FILE] [-l] [-v] [--diagnostics]
                         [--typescript-compiler-folder PATH]
                         
api-extractor run: error: Unrecognized arguments: --watch.

[grant]

1 requested change.

I didn't test to see if there were conflicting commands.

Otherwise lgtm.

[grant]

There shouldn't be a need to replace gts with a manual rimraf of the build folder declared in our tsconfig.

gts clean is the expected clean command we use in client libs and elsewhere in this library. It also provides better output via gts.

• https://github.com/google/gts/blob/main/src/clean.ts
• https://github.com/GoogleCloudPlatform/functions-framework-nodejs/blob/master/tsconfig.json#L5

This change is also a little tangential to the api-extractor change.

[matthewrobertson]

I changed it because gts clean doesn't work on my machine:

❯ npm run clean

> @google-cloud/functions-framework@1.10.1 clean /usr/local/google/home/mattrobertson/gcf/functions-framework-nodejs
> gts clean

version: 16
Error: Error: /usr/local/google/home/mattrobertson/gcf/functions-framework-nodejs/tsconfig.json
Error: /usr/local/google/home/mattrobertson/gcf/functions-framework-nodejs/gts/tsconfig-google.json
ENOENT: no such file or directory, open '/usr/local/google/home/mattrobertson/gcf/functions-framework-nodejs/gts/tsconfig-google.json'
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @google-cloud/functions-framework@1.10.1 clean: `gts clean`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the @google-cloud/functions-framework@1.10.1 clean script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /usr/local/google/home/mattrobertson/.npm/_logs/2021-11-10T17_43_50_564Z-debug.log

@grant does it work for you right now?

[matthewrobertson]

looks like our tsconfig should actually be extending ./node_modules/gts/tsconfig-google.json:

https://github.com/googleapis/nodejs-pubsub/blob/main/tsconfig.json#L2

I wonder how tsc is even working now...

[grant]

OK. It looks like that's a different issue.

It looks like this expects a global gts or something maybe changed when this was first created with linking. We can change it to the local gts with tsconfig:

"extends": "./node_modules/gts/tsconfig-google.json",

This config looks the same as other client libs.

We probably shouldn't inline rm rf because one of our scripts doesn't work as expected.