Improve TS types

[tordans]

It would be great to be able to learn more about the library right from VS Code by using the types, function comments and type files.

Function comments:

It looks like the function comments can be shared between Rust and TS right away, like it is done for debugRenderGraph:

• Comment in https://github.com/dabreegster/route_snapper/blob/main/route-snapper/src/lib.rs#L696
• … is visible in VS Code and TS as …

  /**
  * Render the graph as GeoJSON points and line-strings, for debugging.
  * @returns {string}
  */
    debugRenderGraph(): string;

So one step would be to write more detailed function comments that cover the cases in https://github.com/dabreegster/route_snapper/blob/main/user_guide.md#wasm-api. I don't know if new lines will be accepted there, but that would be helpful (like a full JS Doc description block).

Input/output types:

The other part is having detailed input / output types. Right now a lot of them are just string or any. One has to explore the shape of the files even though they are pretty defined by the library:

Example:

/**
- * @param {any} raw_waypoints
+ * @param {{ lon: number, lat: number, snapped: boolean }[]} raw_waypoints
*/
-  editExisting(raw_waypoints: any): void;
+  editExisting(raw_waypoints: { lon: number, lat: number, snapped: boolean }[]): void;

I looked into this a bit (this article sounded good) and it sounded like one need an extra crate like https://lib.rs/crates/tsify to create those better types. Some will auto generate but one can customize this as well.

[dabreegster]

Thanks for finding tsify and an article walking through it! This indeed looks promising. I'll try and start on this during this week. There are some unknowns, like expressing the output of renderGeojson -- the Point features and LineString features have different properties. To express that precisely, I might need to write some interesting new types on the Rust side and make sure they serialize to GeoJSON the right way. Or it might be simpler to use some of the wasm-bindgen options to specify a manually written TS block, and not actually have the Rust compilation process verify this is the shape of the output.