An alternative to union types

[skreborn]

This discussion is in regards to finding a viable alternative to TypeScript's union types (as mentioned in #56) for use in generic function implementations like nearestPointOnLine, which is supposed to accept any of LineString, MultiLineString, Feature<LineString>, and Feature<MultiLineString>.

Proposal

I'm proposing using interfaces that unify certain geometry classes into groups by function - much like a trait in Rust. This admittedly adds some complexity to the library code, but it certainly improves usage, readability, and type safety for its consumers.

Example

Interface

abstract class AsPoint {
  Position asPoint();
}

Implementation

class Position extends CoordinateType implements AsPoint {
  // ...

  @override
  Position asPoint() => this;
}

class Point extends GeometryType<Position> implements AsPoint {
  // ...

  @override
  Position asPoint() => coordinates;
}

Example

num bearing(AsPoint start, AsPoint end, {bool calcFinal = false}) {
  final startPoint = start.asPoint();
  final endPoint = end.asPoint();

  // Reverse calculation
  if (calcFinal == true) {
    return calculateFinalBearing(startPoint, endPoint);
  }

  num lng1 = degreesToRadians(startPoint.lng);
  num lng2 = degreesToRadians(endPoint.lng);
  num lat1 = degreesToRadians(startPoint.lat);
  num lat2 = degreesToRadians(endPoint.lat);
  num a = sin(lng2 - lng1) * cos(lat2);
  num b = cos(lat1) * sin(lat2) - sin(lat1) * cos(lat2) * cos(lng2 - lng1);

  return radiansToDegrees(atan2(a, b));
}

num calculateFinalBearing(AsPoint start, AsPoint end) {
  // Swap start & end
  num reverseBearing = bearing(end, start) + 180;
  return reverseBearing.remainder(360);
}

Additional notes

This still doesn't allow the usage of T | Feature<T>, but that's unfortunately not possible due to Dart's constraints; we can't specialize interfaces based on generic types. However, this is something I believe we can live with, as the library consumer is only ever a feature.geometry call away from converting it to a type that will fit.

To start off, I would implement the following interfaces:

// Implemented for any type convertible to a single point: `Position` and `Point`
abstract class AsPoint {
  Position asPoint();
}

// Implemented for any type convertible to one or more points: `Position` and `GeometryType`
abstract class AsPoints {
  List<Position> asPoints();
}

// Implemented for any type convertible to a single line: `MultiPoint`, and `LineString`
abstract class AsLine {
  List<Position> asLine();
}

// Implemented for any type convertible to one or more lines: `MultiPoint`, `LineString`,
// `MultiLineString`, `Polygon`, and `MultiPolygon`
abstract class AsLines {
  List<List<Position>> asLines();
}

// Implemented for any type convertible to a single polygon: `Polygon`
abstract class AsPolygon {
  List<List<Position>> asPolygon();
}

// Implemented for any type convertible to one or more polygons: `Polygon`, and `MultiPolygon`
abstract class AsPolygons {
  List<List<List<Position>>> asPolygons();
}

These are just off the top of my head, so Turf.js documentation needs to be scanned thoroughly to determine if any additional unifying interfaces are necessary and warranted, of course.

[lukas-h]

I‘d say we keep this discussion open for some time and gather other parts of the library that have a similar problem and then decide. Let’s first work without it!

[jsiedentop]

The Turf interface is oriented towards the possibilities of JavaScript/Typescript. Since TurfDart is a direct port, we use what is available in Dart to stay as close as possible to the TurfJS interface (and documentation). I'm a fan of explicit approaches and like your suggestion. Also, we definitely have the potential to adapt the interface to the possibilities of Dart. But I agree with @lukas-h, now is not the right time. At the moment the priority is to port the complete functionality from TurfJS. It is also much easier to reprogram a feature in Dart if the implementation is as similar as possible to TurfJS.

However, I was very happy to read about your suggestion. The idea of how to improve the library interface has also been on my mind for the last few days.