Improve type inference in @turf/helpers' geometry and geometryCollection

[mfedderly]

Cherry-picking some of the work from #2970 so that we can merge it today instead of waiting for a major release.

Specifically we can further narrow the return types of geometry and geometryCollection based on what the user sends in the arguments.

[mfedderly]

This as any casts are a little unfortunate. The case statements don't actually narrow our understanding of T, and so we need to reaffirm that we know what we're doing here.

microsoft/TypeScript#33014

[mfedderly]

I had considered making this a named interface and mapping against that instead (GeometryTypeNameToType), and referencing that instead of as any below, but I opted to not increase the public API for a mapping we only used in a single place.

[mfedderly]

In a simliar fashion, we could narrow this any[] based on T, but that would be a breaking change, we can file it against the 8.0 milestone. I suppose you could also just make the case that we should do this in 7.x, because it is explicitly a bug in the caller if they aren't passing in the correctly shaped coordinates. My only concern with that is some amount of weirdness with number[] vs [number, number] issues, which might crop up depending on how consumers wrote their own types.

[smallsaucepan]

The [number, number] thing is going to haunt us forever 😅

[smallsaucepan]

Does this need the satisfies as well? I wasn't sure if LineString is different from the others.

[mfedderly]

🤦 this was an intermediate state but I decided that the satisfies step didn't really add anything and I removed it (or at least I thought I removed it).

[smallsaucepan]

Looks good @mfedderly. While trying out a couple of things, I found the below a shade more readable. Produces the same result though, so only mentioning it in case you agree on the look of it. The helper doesn't need to be exported so shouldn't affect the public interface.

type GeometryByType<T extends Geometry["type"]> = Extract<
  Geometry,
  { type: T }
>;

export function geometry<
  T extends Exclude<Geometry, GeometryCollection>["type"],
>(
  type: T,
  coordinates: any[],
  _options: Record<string, never> = {}
): GeometryByType<T> {
  switch (type) {
    case "Point":
      return point(coordinates).geometry as GeometryByType<T>;
    case "LineString":
      return lineString(coordinates).geometry as GeometryByType<T>;
    case "Polygon":
      return polygon(coordinates).geometry as GeometryByType<T>;
    case "MultiPoint":
      return multiPoint(coordinates).geometry as GeometryByType<T>;
    case "MultiLineString":
      return multiLineString(coordinates).geometry as GeometryByType<T>;
    case "MultiPolygon":
      return multiPolygon(coordinates).geometry as GeometryByType<T>;
    default:
      throw new Error(type + " is invalid");
  }
}

[mfedderly]

The helper doesn't need to be exported so shouldn't affect the public interface.

I think this is actually untrue. Microsoft built a tool called api-extractor with a rule for exactly this circumstance. The docs page explains some of the pitfalls of not exporting referenced types.

https://api-extractor.com/pages/messages/ae-forgotten-export/

[smallsaucepan]

the pitfalls of not exporting referenced types

Which largely wouldn't apply in our case i.e. an internal type inference helper.

Even taking API extractor warnings as gospel, it doesn't have to be defined as a type - inlining Extract<Geometry, { type: T }> produces the same result. It's as readable and would at least avoid those casts to any, which I think is worth doing where we can 🤷‍♂️