Where to put code for internal reuse within the monorepo

[smallsaucepan]

There are a couple of PRs at the moment that might involve code we want to reuse between packages though don't necessarily want to make part of the public API (#2357 and #2531 for example).

turf-helpers seems to be the default place to put bits and pieces, though might mean internal functions become unintentionally visible or available.

Is there a better / neater / more robust way to do this? Should this stuff all go into a seperate part of the repo that isn't directly published? Or should we use JSDoc or typescript tags to mark things as invisible / not to have documentation generated?

Some articles that might be relevant:

1. https://stackoverflow.com/questions/76273581/building-private-typescript-packages-in-a-monorepo
2. https://turbo.build/repo/docs/handbook/sharing-code/internal-packages
3. https://hamzawaleed.com/effective-code-sharing-in-react-native-with-monorepo-architecture#heading-module-boundaries-in-a-monorepo-architecture
4. https://javascript.plainenglish.io/sharing-typescript-with-nx-and-turborepo-part-1-introduction-to-monorepos-d8d54b805e46
5. https://medium.com/disdj/monorepo-scripts-strategies-naming-conventions-691c64b51acb

@mfedderly @twelch @MartinP-C @solarissmoke

[smallsaucepan]

A couple of examples of what we're talking about:

turf-contains and turf-within both have a function isPolyInPoly. Each package currently has its own similar but slightly different implementation. isPolyInPoly is probably too low level for our users (who just want to throw geojson at booleanContains) so probably doesn't warrant it's own public package. On the flipside though having duplicated code isn't great so it would be good to put a single isPolyInPoly somewhere both packages can use it.

Second example is in turf-boolean-equal and turf-boolean-overlap both use the (now unmaintained and in need of a fix geojson-equality library). #2531 pulls that into Turf as a class exported from turf-helpers. But we probably don't actually want to export that class to our end users.

[mfedderly]

This is an interesting discussion. I get the desire to limit the public-facing APIs, but I'm not actually sure how you accomplish the goal of code sharing without having it in another NPM package where it is eventually public. If you have someone bundling two consumers of the same underlying function, you really want them to be referencing the same file in the same package so that it only shows up once in their bundle.

Perhaps we want to grab a new namespace @turf-internal/* or perhaps @turf/*-internal. Perhaps we even throw @turf/meta in that new zone to discourage external use.

I'm open to better ideas than what I came up with :)

[solarissmoke]

I'm more familiar with the Python ecosystem than I am with JS, and there a common pattern is simply to document certain modules/utils as being internal (and to prefix them accordingly, e.g., with a _), and not subject to whatever compatibility constraints (e.g., semantic versioning) public APIs are. People can still use them if they wish, after taking note of this caveat.

Excluding such utils from auto-generated documentation would also help ensure that people only use them if they really know what they're doing.

[mfedderly]

#2538 (comment) Makes me think that there may be value in just exposing these "internal" methods and treating them as public and supported.