Improving the public API

[Martin Fischer]

The @arethetypeswrong/core package currently exports two functions checkTgz and checkPackage, which both take an optional implementation of the following interface:

export interface Host {
  createPackageFS: (packageName: string, packageVersion?: string) => Promise<FS>;
  createPackageFSFromTarball: (tgz: Uint8Array) => Promise<FS>;
}

This API really doesn't make much sense to me ... especially since these two interface methods are completely unrelated and the two exported functions are only very small:

export async function checkTgz(tgz: Uint8Array, host: Host = fetchTarballHost): Promise<CheckResult> {
  const packageFS = await host.createPackageFSFromTarball(tgz);
  return checkPackageWorker(packageFS);
}

export async function checkPackage(
  packageName: string,
  packageVersion?: string,
  host: Host = fetchTarballHost
): Promise<CheckResult> {
  const packageFS = await host.createPackageFS(packageName, packageVersion);
  return checkPackageWorker(packageFS);
}

so there's really no need to customize their behavior with this Host interface ... it's just unnecessarily convoluted.

I think it would make much more sense to:

1. Export the checkPackageWorker function accepting an FS and rename it to checkPackage and rename the FS interface to Package so that we end up with the signature:

    export async function checkPackage(package: Package): Promise<CheckResult> { ... }

2. Remove checkTgz and checkPackage and replace them with public packageFromTarball and packageFromNPM functions, both returning Package.

So the public API usage would then look like:

const checkResult = await checkPackage(await packageFromNPM('foobar', '1.0.0'));

(which has the advantage that you can easily provide your own package that fulfills the required interface ... and it's clear how to do that)

This would be of course a breaking change but the core README already says:

⚠️ This package is in major version v0 and the API may change significantly in patch and minor releases.

[Andrew Branch]

I do have plans to rework these functions at the same time that I move some of the CLI’s customization options into core itself. You’re right that the customization point in Host didn’t work out and I was definitely planning on removing it. I like the suggestion for how these functions could look 👍