Adopt API extractor tool for @powersync/common

[simolus3]

We want to eventually split @powersync/common into multiple packages to avoid exposing implementation details to users. As a first step, we should be explicit about what is and what isn't a public API. tsdoc has @public and @internal annotations for this, adopting them consistently is a first step.

This also adopts @microsoft/api-extractor with the default configuration. This helps with:

1. TSDoc comments (correct syntax for @links, @params).
2. API visibility: Every element transitively exported from src/index.ts needs either a @public, @internal, @beta or @alpha annotation. This forces us to be explicit about where a member should be visible.
3. API stability: In the past, we've sometimes changed @powersync/common in ways we didn't intend. Thanks to TypeScript's structural typing and npm allowing multiple copies of a package, even subtle things like adding a new method to a class are breaking changes. We need to exercise much more caution when working on @powersync/common, having this tool makes API changes explicit (because etc/common.api.md needs to be re-generated).
4. API inconsistencies: We sometimes have public methods referencing private types in argumens or return types. api-extractor generates a warning for these in etc/common.api.md. There are around remaining 130 instances of this in @powersync/common, I'll investigate fixes as part of the v2 work after removing implementation details from that package.

A follow-up step (also on the v2 branch) is to not have a single @internal member in all of @powersync/common. Internal members should either be:

• Private to the package (things like DEFAULT_INDEX_COLUMN_OPTIONS which aren't used outside of @powersync/common).
• Internal to the SDK (AbstractRemote, AbstractStreamingSyncImplementation): We should move these into a @powersync/shared-internals package without a stable public API.

Some cases are a little trickier: AbstractPowerSyncDatabase (the class) should be internal, but it's type should be public to users. This is also v2 work.

This doesn't change our API or exported members in any way, so we can target main instead of the v2 branch. This also doesn't need a changeset entry for that reason.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8a0aa31

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[rkistner]

This looks like quite a nice approach! Some questions (mostly based on the description):

1. Do these annotations affect the generated types, or does it only serve as "documentation" at the moment?
2. If it does affect the types, how does this handle cases where we use the types in a different workspace package, but it's not intended for public consumption? Are those marked as internal or public?

[simolus3]

Do these annotations affect the generated types, or does it only serve as "documentation" at the moment?

api-extractor can be configured as a build tool to generate a index.d.ts that omits @internal items, but this PR doesn't adopt that. I don't think an @internal annotation in a comment affects TypeScript or rollup itself, these members are still exported from the package from a quick look.

how does this handle cases where we use the types in a different workspace package, but it's not intended for public consumption? Are those marked as internal or public?

We would mark those as @internal, but since it doesn't affect the types they're still available for everyone. I'll open another PR to move those internal types into a separate package to hide them from users, but that would be a breaking change.

[Chriztiaan]

Looking at the generated .md file, there were quite a few should be prefixed with an underscore because the declaration is marked as @internal messages. Do we want to adopt that suggestion?

[simolus3]

Looking at the generated .md file, there were quite a few should be prefixed with an underscore because the declaration is marked as @internal messages. Do we want to adopt that suggestion?

This would technically be a breaking change (since we still export these members from @powersync/common). The goal of this PR is to not alter exported members in any way apart from documentation comments. My preferred fix would be to simply not have any @internal members in @powersync/common, since:

• They're either implementation details of that package itself, in which case they shouldn't have been exported from index.ts.
• They're used across multiple SDKs, in which case we should move them to a say @powersync/shared-internals (name TBD) package.

So these warnings are todos in a sense, but we need the v2 branch to act on them :)