Getting Turf back on track

The goal for Turf v3 was to create a system in which Turf could be coordinated as a set of modules, operating independently but uniform in style, management, and properly versioned together. Unfortunately, that’s no longer the case: the current codebase is heterogenous, hard to contribute to, and the guidelines for releases are nonexistent.

About half of the modules are in TypeScript, and about half of those modules have a tsconfig.json file. About 40% of modules name their main export main, and the rest call it index. Same with providing a module entry point, it’s about 50%. 3 modules have a .mjs module file, the rest have .es.js.

Basically, there are no real homogenous properties of Turf anymore. It’s a worst-case scenario for a mono-repo: it makes Turf maintenance feel much more like ‘maintaining 55 modules’ than it does ‘maintaining a mono-repo’.

Turf modules summary

name	tsconfig	main	module	in ts
turf		turf	turf.mjs	👍
along	👍	index		👍
angle	👍	index		👍
area	👍	index		👍
bbox	👍	index		👍
bbox-clip	👍	index		👍
bbox-polygon	👍	index		👍
bearing	👍	index		👍
bezier-spline	👍	index		👍
boolean-clockwise	👍	index		👍
boolean-concave	👍	index		👍
boolean-contains	👍	index		👍
boolean-crosses		index		👍
boolean-disjoint	👍	index		👍
boolean-equal		index		👍
boolean-intersects	👍	index		👍
boolean-overlap		index		👍
boolean-parallel		index		👍
boolean-point-in-polygon	👍	index		👍
boolean-point-on-line	👍	index		👍
boolean-touches		index		👍
boolean-valid		index		👍
boolean-within		index		👍
buffer		main.js	main.es.js
center		index		👍
center-mean		index		👍
center-median		index		👍
center-of-mass		index		👍
centroid		index		👍
circle		index		👍
clean-coords		index		👍
clone	👍	index		👍
clusters		index		👍
clusters-dbscan		index		👍
clusters-kmeans		index		👍
collect		index		👍
combine		index		👍
concave	👍	index		👍
convex	👍	index		👍
destination	👍	index		👍
difference		index	index.mjs
directional-mean	👍	index		👍
dissolve		main.js	main.es.js
distance		index		👍
distance-weight	👍	index		👍
ellipse		main.js	main.es.js
envelope		main.js	main.es.js
explode		main.js	main.es.js
flatten		main.js	main.es.js
flip		main.js	main.es.js
great-circle		main.js	main.es.js
helpers	👍	index		👍
hex-grid		index		👍
interpolate		main.js	main.es.js
intersect	👍	index		👍
invariant	👍	index		👍
isobands		main.js	main.es.js
isolines		main.js	main.es.js
kinks	👍	index		👍
length	👍	index		👍
line-arc	👍	index		👍
line-chunk		main.js	main.es.js
line-intersect	👍	index		👍
line-offset		main.js	main.es.js
line-overlap		index		👍
line-segment	👍	index		👍
line-slice		main.js	main.es.js
line-slice-along		main.js	main.es.js
line-split		main.js	main.es.js
line-to-polygon		index		👍
mask		main.js	main.es.js
meta		index	index.mjs
midpoint		main.js	main.es.js
moran-index	👍	index		👍
nearest-neighbor-analysis	👍	index		👍
nearest-point	👍	index		👍
nearest-point-on-line		index		👍
nearest-point-to-line	👍	index		👍
planepoint		main.js	main.es.js
point-grid		index		👍
point-on-feature		main.js	main.es.js
point-to-line-distance	👍	index		👍
points-within-polygon		main.js	main.es.js
polygon-smooth		main.js	main.es.js
polygon-tangents		main.js	main.es.js
polygon-to-line	👍	index		👍
polygonize		main.js	main.es.js
projection		index		👍
quadrat-analysis	👍	index		👍
random	👍	index		👍
rectangle-grid		index		👍
rewind		main.js	main.es.js
rhumb-bearing	👍	index		👍
rhumb-destination	👍	index		👍
rhumb-distance	👍	index		👍
sample		main.js	main.es.js
sector		main.js	main.es.js
shortest-path		main.js	main.es.js
simplify		main.js	main.es.js
square		main.js	main.es.js
square-grid	👍	index		👍
standard-deviational-ellipse		main.js	main.es.js
tag		main.js	main.es.js
tesselate		main.js	main.es.js
tin	👍	index		👍
transform-rotate		main.js	main.es.js
transform-scale		main.js	main.es.js
transform-translate		main.js	main.es.js
triangle-grid		index		👍
truncate		index		👍
union		index		👍
unkink-polygon		main.js	main.es.js
voronoi		main.js	main.es.js

---

Organizationally, Turf currently has a small chunk of cash, a much much smaller number of long-term maintainers, and zero institutional/company code contributors. This is pretty common for open source projects.

To propose a few ways forward:

Remove TypeScript

The TypeScript transition, while a very nice contribution, is unfinished and offers little to the project. We didn’t have many bugs caused by type mismatches before, and the resulting addition of complexity outweighs the benefit.

Would this be unpopular? Probably! But it’d be better to re-achieve stability and releasability, and make the project fit its actual contributors, than to perpetually be in a half-deployable state.

If this is the option, we could do it by basically configuring tsc to generate ES modules.

Move lerna.js back to fixed/locked mode

Per https://github.com/Turfjs/turf/pull/1247 the lerna config was switched to independent versioning. This makes collaboration harder: the intent of lerna was and is to make versioning automatic so that the project can be released always with lerna publish. There should not be a thought process for which modules need updating and releases.

Move releases/ back into changelog

This releases directory is the same as a central changelog. Let’s move these back to the changelog.

Use standard commits

Again, a common collaboration point - this will automate changelog generation and version more accurately

Write these contribution tips into CONTRIBUTING.md

And probably create a strong process for changing them. This stuff shouldn’t become wobbly; Turf should stay in a deployable, simple state that all the maintainers have a grasp on.

(Extreme solution) just move to a singular ES6 module

This would probably be even less popular than removing TypeScript: create one turf module (again), now that tree-shaking means that people using Rollup/Webpack/Parcel can efficiently import a subsection of a module without including all of the code. This would drastically reduce complexity and let advanced users continue to get the performance advantages of the current mini-modules, but it would leave people using old-fashioned require etc out in the cold.

Honestly I’m also in favor of this extreme solution: it’d be a huge decrease in complexity, and it’d do this for existing users:

1. Script-tag or browserify users: yep, would be slower
2. Node users: probably don’t mind the startup time or install size that much
3. Webpack/Rollup users: would work great
4. Future native-js module users: would easily be able to sub-import

---

This is intended to be a bit of a jumping-off point, none of these ways to victory are quick-fixes and we’d want to attain some consensus before embarking on them. Dividing this work up would also be useful, given that there are few maintainers, or if there is an institutional/company contributor who wants to take on some of this, it’d be more than welcome - Turf is definitely generating a lot of value out there in the world, much more than it captures.

[rowanwins]

Hi @tmcw

Thanks for taking the time to check in on the status of the project, this has certainly been weighing on my mind over the past couple of months.

That said I want to start by saying the following

• TurfJS has existed for the past few years largely on the back of the spare time, goodwill and interest of 3 people. This is important to recognise and thank - they’ve put in a huge effort and moved Turf forward a long way so thank you to my co-contributors @DenisCarriere & @stebogit 🙏
• Its worth remembering that in reality there are very few open source geospatial libs out there, and the bulk that exist piggyback on JTS, it’s a great reminder that we’re doing something that is complicated. We’ve also been doing it as volunteers in a JS world that is changing at great pace.

Re Typescript I’d be supportive of ditching the typescript-first approach

1. We only have/had one active maintainer (out of the 3 at the time the decision was made) who knew anything about Typescript
2. The Typescript definitions we’re using aren’t compatible with what other common mapping libraries are using which kind of seems to defeat the purpose IMHO.
3. I can’t think of any instances where I’ve had to provide support around people using incorrect geometry types for operations.
4. The previous approach allowed us to ship TS typings for those that were interested in using them but didn’t make TurfJS all in on TS.

On a personal & professional note I have no desire or need to learn TypeScript, TurfJS would be my sole reason for learning it.

Re Lerna

1. Yep I think moving back to fixed versioning makes sense, this was working well in my opinion (eg the past few years until early this year).
2. The other note about lerna & publishing is that for the past few years it’s always sat in the hands of one person, this obviously left a bit of a knowledge gap for the rest of the contributors. Lerna is it’s own beast and while I’ve published many libraries via npm attempting to go through the process with Turf with lerna was/is scary for a first-timer for fear of breaking things

Contributing.md Yeah agreed this is in dire need of an overhaul. Over the past 18 months there have been quite a number of changes to the various processes that have never been adequately captured.

Re All-in on ES6 So if I understand this correctly this would basically

1. do away with the need for lerna; and
2. npm would only contain a single turf package

Could you elaborate on use case 1 (‘Script-tag or browserify users’) - is that basically folks using Turf via a CDN? Why would that be slower under this proposal?

I think I cautiously support this approach. The bulk of browser apps (at least serious ones) are being built with some sort of bundling tool so I dont think we’d be leaving many out in the cold with this decision. My one proviso is that I think it would be nice to have some sort of basic bundled version (eg a CDN version) for people to hack with and learn with that doesn’t require them to get into the whole world of bundlers, it wouldn’t be the preferred method of usage but would be there to provide a low barrier of entry.

Anyway those are my initial thoughts - will ponder further and see if there is anything else that comes to mind.

Cheers Rowan

[rowanwins]

Thankfully after a few years hiatus Turf is back on track with a team of contributors helping on many fronts 🎉 We’ve now had a series of stables releases from v6.2.0 onwards. Still a lot of work to be done but lots of good progress is being made.