@ulrik.ek/wgs84 1.1.0 → 1.1.3

package/doc/README.md

@@ -0,0 +1,74 @@
+**@ulrik.ek/wgs84**
+
+***
+
+# wgs84
+
+## Introduction
+
+A tiny library fully implemented in Typescript to handle WGS84 coordinates in GeoJson and "small" distances between them with very high accuracy (~1 cm), based on a local, flat earth approximation.
+
+- All functions uses degrees for latitude and longitude, and meters for distances.
+- Parses and gives output in GeoJson using the [Point definition](https://en.wikipedia.org/wiki/GeoJSON). If you already have imported the typescript definition for Point in the geojson package you can use that (that is what I do in unit testing). Otherwise you can import `Point` from this package.
+- No dependencies to other NPM modules.
+- The math is based on [Aviation Formulary V1.47 by Ed Williams](https://edwilliams.org/avform147.htm#flat).
+- Functions will throw `Error` if fed impossible values, e.g. incorrectly formatted GeoJSON or lat >= 90 degrees (math will not work!). _Make sure to handle that!_
+
+## Getting Started
+
+Include in your project as any other NPM package
+
+> npm install @ulrik.ek/wgs84
+
+## Usage
+
+```typescript
+import * as wgs84 from '@ulrik.ek/wgs84'; // The functions can obviously also be imported separately
+
+// helper function to construct a GeoJSON Point
+const lat = 15;
+const lon = 25;
+const p: wgs84.Point = wgs84.point(lat, lon);
+
+// Getting a new point 300m north and 400m east of the first point
+const p1: wgs84.Point = wgs84.pointEastOf(wgs84.pointNorthOf(p, 300), 400);
+const newLat = p1.coordinates[1]; // GeoJSON uses [lon, lat] order!
+const newLon = p1.coordinates[0];
+console.log(`lat=${newLat}, lon=${newLon}`);
+
+// get the distance along north between the 2 points
+console.log(`Distance along north=${wgs84.distanceNorth(p, p1)}`);
+console.log(`Distance along east=${wgs84.distanceEast(p, p1)}`);
+console.log(`Total distance=${wgs84.distance(p, p1)}`);
+```
+
+This will produce the following output
+
+> lat=15.002711283642645, lon=25.003719230339353  
+> Distance along north=300.00000000009265  
+> Distance along east=400.00504064747975  
+> Total distance=500.0040325271862
+
+## Documentation
+
+The following functions are available:
+
+```Typescript
+point(lat: number, lon: number, height?: number): Point;
+R1(position: Point): number;
+R2(position: Point): number;
+distanceNorth(origin: Point, target: Point): number;
+distanceEast(origin: Point, target: Point): number;
+distanceUp(origin: Point, target: Point): number;
+distance(origin: Point, target: Point): number;
+bearing(origin: Point, target: Point): number;
+pointNorthOf(origin: Point, dN: number): Point;
+pointEastOf(origin: Point, dE: number): Point;
+pointAbove(origin: Point, dH: number): Point;
+```
+
+[Full Typedoc documentation](https://github.com/UEk/wgs84/blob/main/doc/globals.md)
+
+# Build and Test
+
+All functions are unit tested.

package/doc/functions/R1.md

@@ -0,0 +1,28 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / R1
+
+# Function: R1()
+
+> **R1**(`position`): `number`
+
+Defined in: [index.ts:193](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L193)
+
+The meridional radius of curvature at a certain geographical position
+will throw for impossible input
+
+## Parameters
+
+### position
+
+[`Point`](../interfaces/Point.md)
+
+The current position in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/R2.md

@@ -0,0 +1,28 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / R2
+
+# Function: R2()
+
+> **R2**(`position`): `number`
+
+Defined in: [index.ts:205](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L205)
+
+The radius of curvature in the prime vertical at a certain geographical position
+will throw for impossible input
+
+## Parameters
+
+### position
+
+[`Point`](../interfaces/Point.md)
+
+The current position in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/bearing.md

@@ -0,0 +1,35 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / bearing
+
+# Function: bearing()
+
+> **bearing**(`origin`, `target`): `number`
+
+Defined in: [index.ts:41](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L41)
+
+Calculates the bearing from origin to target in the plane
+with 0 degrees being north, and 90 degrees being east
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the origin point in GeoJson
+
+### target
+
+[`Point`](../interfaces/Point.md)
+
+the target point in GeoJson
+
+## Returns
+
+`number`
+
+degrees

package/doc/functions/distance.md

@@ -0,0 +1,35 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / distance
+
+# Function: distance()
+
+> **distance**(`origin`, `target`): `number`
+
+Defined in: [index.ts:59](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L59)
+
+Calculates the distance in meters between origin and target
+Will take height into consideration, if given for both points
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the origin point in GeoJson
+
+### target
+
+[`Point`](../interfaces/Point.md)
+
+the resulting point in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/distanceEast.md

@@ -0,0 +1,34 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / distanceEast
+
+# Function: distanceEast()
+
+> **distanceEast**(`origin`, `target`): `number`
+
+Defined in: [index.ts:80](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L80)
+
+Calculates the distance in meters along an eastern meridian
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the starting point in GeoJson
+
+### target
+
+[`Point`](../interfaces/Point.md)
+
+the ending point in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/distanceNorth.md

@@ -0,0 +1,34 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / distanceNorth
+
+# Function: distanceNorth()
+
+> **distanceNorth**(`origin`, `target`): `number`
+
+Defined in: [index.ts:102](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L102)
+
+Calculates the distance in meters along a northern meridian
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the starting point in GeoJson
+
+### target
+
+[`Point`](../interfaces/Point.md)
+
+the ending point in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/distanceUp.md

@@ -0,0 +1,33 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / distanceUp
+
+# Function: distanceUp()
+
+> **distanceUp**(`origin`, `target`): `number`
+
+Defined in: [index.ts:116](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L116)
+
+Calculates the vertical distance in meters
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the starting point in GeoJson
+
+### target
+
+[`Point`](../interfaces/Point.md)
+
+the ending point in GeoJson
+
+## Returns
+
+`number`
+
+meters

package/doc/functions/point.md

@@ -0,0 +1,40 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / point
+
+# Function: point()
+
+> **point**(`lat`, `lon`, `height?`): [`Point`](../interfaces/Point.md)
+
+Defined in: [index.ts:18](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L18)
+
+creates a GeoJSON Point
+will throw for impossible input
+
+## Parameters
+
+### lat
+
+`number`
+
+in degrees, has to be -90 < lat < 90
+
+### lon
+
+`number`
+
+in degrees, has to be -180 <= lon <= 180
+
+### height?
+
+`number`
+
+in meters
+
+## Returns
+
+[`Point`](../interfaces/Point.md)
+
+GeoJSON Point

package/doc/functions/pointAbove.md

@@ -0,0 +1,34 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / pointAbove
+
+# Function: pointAbove()
+
+> **pointAbove**(`origin`, `dH`): [`Point`](../interfaces/Point.md)
+
+Defined in: [index.ts:131](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L131)
+
+Gives a new point at a height dH above the current point
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the origin point in GeoJson
+
+### dH
+
+`number`
+
+the distance up in meters, negative number gives a lower height
+
+## Returns
+
+[`Point`](../interfaces/Point.md)
+
+GeoJson Point

package/doc/functions/pointEastOf.md

@@ -0,0 +1,34 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / pointEastOf
+
+# Function: pointEastOf()
+
+> **pointEastOf**(`origin`, `dE`): [`Point`](../interfaces/Point.md)
+
+Defined in: [index.ts:146](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L146)
+
+Gives a new point at a distance dE east of the current point
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the origin point in GeoJson
+
+### dE
+
+`number`
+
+the distance in meters along an eastern meridian, negative number gives distance to west
+
+## Returns
+
+[`Point`](../interfaces/Point.md)
+
+GeoJson Point

package/doc/functions/pointNorthOf.md

@@ -0,0 +1,34 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / pointNorthOf
+
+# Function: pointNorthOf()
+
+> **pointNorthOf**(`origin`, `dN`): [`Point`](../interfaces/Point.md)
+
+Defined in: [index.ts:172](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L172)
+
+Gives a new point at a distance dN north of the current point
+will throw for impossible input
+
+## Parameters
+
+### origin
+
+[`Point`](../interfaces/Point.md)
+
+the origin point in GeoJson
+
+### dN
+
+`number`
+
+the distance in meters along a northern meridian, negative number gives distance to south
+
+## Returns
+
+[`Point`](../interfaces/Point.md)
+
+GeoJson Point

package/doc/globals.md

@@ -0,0 +1,23 @@
+[**@ulrik.ek/wgs84**](README.md)
+
+***
+
+# @ulrik.ek/wgs84
+
+## Interfaces
+
+- [Point](interfaces/Point.md)
+
+## Functions
+
+- [bearing](functions/bearing.md)
+- [distance](functions/distance.md)
+- [distanceEast](functions/distanceEast.md)
+- [distanceNorth](functions/distanceNorth.md)
+- [distanceUp](functions/distanceUp.md)
+- [point](functions/point.md)
+- [pointAbove](functions/pointAbove.md)
+- [pointEastOf](functions/pointEastOf.md)
+- [pointNorthOf](functions/pointNorthOf.md)
+- [R1](functions/R1.md)
+- [R2](functions/R2.md)

package/doc/interfaces/Point.md

@@ -0,0 +1,12 @@
+[**@ulrik.ek/wgs84**](../README.md)
+
+***
+
+[@ulrik.ek/wgs84](../globals.md) / Point
+
+# Interface: Point
+
+Defined in: [index.ts:5](https://github.com/UEk/wgs84/blob/e8e4bbfd1d8ff81410dce1ae7afe5436fa6e0608/src/index.ts#L5)
+
+GeoJSON definition from
+https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/geojson/index.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ulrik.ek/wgs84",
-    "version": "1.1.0",
+    "version": "1.1.3",
     "description": "Basic library for computing small distances between WGS84 coordinates using a flat earth approximation.",
     "author": "Ulrik E.",
     "license": "MIT",
@@ -9,6 +9,12 @@
         "doc": "doc",
         "test": "test"
     },
+    "files": [
+        "dist",
+        "doc",
+        "README.md",
+        "LICENSE"
+    ],
     "type": "commonjs",
     "scripts": {
         "audit": "npm audit --registry=https://registry.npmjs.org",
@@ -27,21 +33,19 @@
     "devDependencies": {
         "@eslint/js": "^10.0.1",
         "@types/geojson": "^7946.0.16",
-        "@types/jest": "^30.0.0",
-        "@types/node": "^25.5.2",
-        "@vitest/coverage-v8": "^4.1.2",
-        "eslint": "^10.2.0",
-        "eslint-plugin-perfectionist": "^5.8.0",
-        "globals": "^17.4.0",
-        "prettier": "^3.8.1",
+        "@types/node": "^25.6.0",
+        "@vitest/coverage-v8": "^4.1.4",
+        "eslint": "^10.2.1",
+        "eslint-plugin-perfectionist": "^5.9.0",
+        "globals": "^17.5.0",
+        "prettier": "^3.8.3",
         "shx": "^0.4.0",
-        "ts-jest": "^29.4.9",
         "tsx": "^4.21.0",
-        "typedoc": "^0.28.18",
+        "typedoc": "^0.28.19",
         "typedoc-plugin-markdown": "^4.11.0",
-        "typescript": "^6.0.2",
-        "typescript-eslint": "^8.58.0",
-        "vitest": "^4.1.2"
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.58.2",
+        "vitest": "^4.1.4"
     },
     "types": "./dist/index.d.ts",
     "repository": {

package/eslint.config.mjs

@@ -1,79 +0,0 @@
-// @ts-check
-import eslint from '@eslint/js';
-import tseslint from 'typescript-eslint';
-import perfectionist from 'eslint-plugin-perfectionist';
-import globals from 'globals';
-
-export default tseslint.config(
-  // 1. Globala ignoreringar (ersätter din gamla ignores-block)
-  {
-    ignores: [
-      'dist/**',
-      'coverage/**',
-      'report/**',
-      'node_modules/**',
-      'doc/**',
-      '*.config.*'
-    ],
-  },
-
-  // 2. Bas-konfiguration (JS & TS Rekommenderat + Sortering)
-  eslint.configs.recommended,
-  ...tseslint.configs.recommended,
-  perfectionist.configs['recommended-natural'],
-
-  // 3. Gemensamma inställningar för alla filer
-  {
-    languageOptions: {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-      globals: {
-        ...globals.node,
-        ...globals.vitest, // Lägger till describe, it, expect etc. automatiskt
-      },
-    },
-    rules: {
-      // Allmänna regler
-      'no-console': 'error',
-      'no-var': 'error',
-      'prefer-const': 'error',
-      'eqeqeq': ['error', 'always'],
-      'curly': 'error',
-      'no-throw-literal': 'error',
-      
-      // TypeScript-specifika regler (utan typ-check krav)
-      '@typescript-eslint/no-unused-vars': 'warn',
-      '@typescript-eslint/explicit-function-return-type': 'error',
-      '@typescript-eslint/no-explicit-any': 'warn',
-      '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'as' }],
-
-      // Perfectionist sköter nu all sortering (imports, keys, class members)
-      // Du behöver inte längre definiera order[] manuellt om du inte vill ha en special-ordning.
-    },
-  },
-
-  // 4. Konfiguration för källkod med strikt typ-check
-  {
-    files: ['src/**/*.ts'],
-    languageOptions: {
-      parserOptions: {
-        project: './tsconfig.json',
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-    rules: {
-      // Här kan du lägga till regler som kräver projekt-context
-      '@typescript-eslint/prefer-readonly': 'error',
-      '@typescript-eslint/require-array-sort-compare': 'error',
-    },
-  },
-
-  // 5. Undantag för tester och exempel (tillåt console etc.)
-  {
-    files: ['test/**/*.ts', 'example/**/*.ts'],
-    rules: {
-      'no-console': 'off', // Tillåt console i exempel och tester
-      '@typescript-eslint/no-explicit-any': 'off',
-    },
-  }
-);

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.ts"],"version":"6.0.2"}

package/vitest.config.ts

@@ -1,12 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-    test: {
-        globals: true, // Gör att 'describe', 'it', 'expect' finns tillgängliga globalt (som i Jest)
-        environment: 'node',
-        coverage: {
-            provider: 'v8',
-            reporter: ['text', 'json', 'html']
-        }
-    }
-});