From 2a042d4924259915abcd8fd75d8cbd7e25d2dd55 Mon Sep 17 00:00:00 2001 From: Matthew Fedderly <24275386+mfedderly@users.noreply.github.com> Date: Mon, 5 Jan 2026 11:01:26 -0500 Subject: [PATCH 1/2] WIP readme rework around precision and supported js environments --- README.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3f63130d3e..119223b626 100644 --- a/README.md +++ b/README.md @@ -26,18 +26,39 @@ Or explore the Turf API and examples at [turfjs.org](https://turfjs.org/). ## Runtime support -Turf is currently published to work with any reasonably modern Javascript runtime. +Turf is currently published to work with any reasonably modern JavaScript runtime. Node is a first class citizen, and we recommend using an [Active or Maintenance LTS](https://nodejs.org/en/about/previous-releases) release. Other runtimes, such as Deno or Bun, are not officially supported. We would be very interested to hear your experiences though. +## Precision + +Although we make a reasonable effort for accuracy in our implementations, we are ultimately limited by the fact that we are handling GeoJSON data. +For lots of consumer devices, GPS accuracy is within a few meters of the actual point. When using latitude and longitude, 6 digits after the decimal +works out to an [error around 10cm](https://datatracker.ietf.org/doc/html/rfc7946#section-11.2). Although libraries exist to provide arbitrary +precision math, we try to use JavaScript's built in numeric type (64 bit floating point) for performance reasons. + +Although it is possible to specify GeoJSON positions with more than 6 digits of precision, Turf cannot guarantee correctness at these scales. +Certain operations may run into issues when the distances involved are very small, at the limit of what our Number type can represent. + +We may close bugs that cannot be reproduced after the GeoJSON has been run through @turf/truncate to 6 digits. + +We may return results with additional precision to avoid having to perform truncation, but that +[should not be interpreted](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.10) as the level of real precision in the result. + ## Browser support -Turf uses Babel to transpile to a JavaScript version usable by most -modern browsers. Any browser that matches the following criteria as defined by [Browserslist](https://github.com/browserslist/browserslist): +@turf/turf includes a `browser` target which can be useful to load from a CDN. This uses Babel to transpile to a JavaScript version usable by most modern browsers. +This will include any browser that matches the `default` criteria as defined by [Browserslist](https://browsersl.ist/#q=defaults). +We may roll forward and drop support for older browsers within a given major release, please pin an exact version if you need to preserve specific browser compatibility. + +## NPM package syntax + +All of the individual @turf/* packages are written in TypeScript and are compiled to target ESNext. That means that we may use new syntax features without changing the major version. +If you have specific browser support requirements please apply Babel, SWC, or another tool in your own bundling step in order to control the amount of supporting code. -[> 0.25%, last 2 versions, fully supports es5, not dead](https://browsersl.ist/#q=%3E+0.25%25%2C+last+2+versions%2C+fully+supports+es5%2C+not+dead) +Note: Our ability to adopt the latest syntax will still be restricted by the supported Node versions for a given major version of Turf. ## Contributors From 163394a261e13515005c4034d00fa50aede12e2a Mon Sep 17 00:00:00 2001 From: Matthew Fedderly <24275386+mfedderly@users.noreply.github.com> Date: Tue, 6 Jan 2026 08:32:07 -0500 Subject: [PATCH 2/2] Updated per CR --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 119223b626..e5d893c8f6 100644 --- a/README.md +++ b/README.md @@ -34,10 +34,10 @@ Other runtimes, such as Deno or Bun, are not officially supported. We would be v ## Precision -Although we make a reasonable effort for accuracy in our implementations, we are ultimately limited by the fact that we are handling GeoJSON data. +Although we make a reasonable effort for precision in our implementations, we are ultimately limited by the fact that we are handling GeoJSON data. For lots of consumer devices, GPS accuracy is within a few meters of the actual point. When using latitude and longitude, 6 digits after the decimal works out to an [error around 10cm](https://datatracker.ietf.org/doc/html/rfc7946#section-11.2). Although libraries exist to provide arbitrary -precision math, we try to use JavaScript's built in numeric type (64 bit floating point) for performance reasons. +precision math, we try to use JavaScript's built in types for performance reasons. Although it is possible to specify GeoJSON positions with more than 6 digits of precision, Turf cannot guarantee correctness at these scales. Certain operations may run into issues when the distances involved are very small, at the limit of what our Number type can represent. @@ -47,6 +47,9 @@ We may close bugs that cannot be reproduced after the GeoJSON has been run throu We may return results with additional precision to avoid having to perform truncation, but that [should not be interpreted](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.10) as the level of real precision in the result. +If you have stricter precision needs or aren't using latitude/longitude, you may want to use Turf as a reference for your own implementation, +carefully controlling the projection and library call steps. + ## Browser support @turf/turf includes a `browser` target which can be useful to load from a CDN. This uses Babel to transpile to a JavaScript version usable by most modern browsers. @@ -58,6 +61,8 @@ We may roll forward and drop support for older browsers within a given major rel All of the individual @turf/* packages are written in TypeScript and are compiled to target ESNext. That means that we may use new syntax features without changing the major version. If you have specific browser support requirements please apply Babel, SWC, or another tool in your own bundling step in order to control the amount of supporting code. +Some of the packages are implemented using other NPM libraries, which may also need to be transformed. + Note: Our ability to adopt the latest syntax will still be restricted by the supported Node versions for a given major version of Turf. ## Contributors