{"_id":"@arijitgupta/geo-distance","_rev":"3-551bbfd04ea3bb7533e885b0ac17be03","name":"@arijitgupta/geo-distance","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@arijitgupta/geo-distance","version":"1.0.0","keywords":["geo","geospatial","distance","coordinates","haversine"],"author":{"name":"Arijit Gupta"},"license":"MIT","_id":"@arijitgupta/geo-distance@1.0.0","maintainers":[{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"}],"dist":{"shasum":"170d92d3aaa37b7de16a6a2e21e6219ede5d87ec","tarball":"https://registry.npmjs.org/@arijitgupta/geo-distance/-/geo-distance-1.0.0.tgz","fileCount":13,"integrity":"sha512-njGIGV4fja2clcAvqgvl77c0LrpmZ41kruDAdC5RBGR+ueic6g5419J3PJSiU5NcBB9wmNJ3G9M4Na7vv8zLFg==","signatures":[{"sig":"MEUCIQDkDxiEgl6o0FjOoEbyHBkgFVQ70OMdT8wO3bCVwr4UBAIgNEFC/glIHyVXfWPb/ld3BSoDBRf1FmpuK6ppybP1jJU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4912},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"8d104c22976c7a99b7fd3a1940b6d3437101bbf7","scripts":{"test":"vitest run","build":"tsc","check":"tsc --noEmit","prepublishOnly":"npm run check && npm test && npm run build"},"_npmUser":{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"},"_npmVersion":"11.19.0","description":"Calculate geographic distances between coordinates.","directories":{},"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","typescript":"^7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/geo-distance_1.0.0_1788285469469_0.9690764077282952","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@arijitgupta/geo-distance","version":"1.0.1","keywords":["geo","geospatial","distance","coordinates","haversine"],"author":{"name":"Arijit Gupta"},"license":"MIT","_id":"@arijitgupta/geo-distance@1.0.1","maintainers":[{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"}],"homepage":"https://github.com/ArijitGupta-in/geo-distance","bugs":{"url":"https://github.com/ArijitGupta-in/geo-distance/issues"},"dist":{"shasum":"8120a280093923903c7dae99b976eb4a728143f8","tarball":"https://registry.npmjs.org/@arijitgupta/geo-distance/-/geo-distance-1.0.1.tgz","fileCount":14,"integrity":"sha512-yoJhh1p/71MdHibE3Bu5/BkFcFC2V/Q8Tu2x44Oz58pbXzn2Qz/HsbhREXwujhNPlwbtjfb+tv60AN5zO1t43Q==","signatures":[{"sig":"MEUCIHZScBQf/gePvtEWGPgSXC3ISEPWK4kXOZ+CLoHIo6fGAiEAm7iABnNtdYe3ogMTgCfF3hgGRxFYmwzWJKNL92G0J0o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7099},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"005af5d8b7c28d03b8558ef737d00512efae191a","scripts":{"test":"vitest run","build":"tsc","check":"tsc --noEmit","prepublishOnly":"npm run check && npm test && npm run build"},"_npmUser":{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"},"repository":{"url":"git+https://github.com/ArijitGupta-in/geo-distance.git","type":"git"},"_npmVersion":"11.19.0","description":"Calculate geographic distances between coordinates.","directories":{},"_nodeVersion":"24.20.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11","typescript":"^7.0.2","markdownlint-cli2":"^0.23.2"},"_npmOperationalInternal":{"tmp":"tmp/geo-distance_1.0.1_1788287573206_0.15853705642416172","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@arijitgupta/geo-distance","version":"1.1.0","description":"Estimate great-circle distances between geographic coordinates in meters, kilometers, miles, or feet using the Haversine formula, with decimal-degree and DMS support.","type":"module","repository":{"type":"git","url":"git+https://github.com/ArijitGupta-in/geo-distance.git"},"homepage":"https://github.com/ArijitGupta-in/geo-distance","bugs":{"url":"https://github.com/ArijitGupta-in/geo-distance/issues"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","test":"vitest run","check":"tsc --noEmit","prepublishOnly":"npm run check && npm test && npm run build"},"keywords":["geo","geospatial","distance","coordinates","haversine","great-circle","latitude","longitude","dms","geography","kilometers","miles","feet","distance-conversion"],"author":{"name":"Arijit Gupta"},"license":"MIT","devDependencies":{"markdownlint-cli2":"^0.23.2","typescript":"^7.0.2","vitest":"^4.1.11"},"gitHead":"02f365b641bf6dfa547a7aecc571880fb7474eac","_id":"@arijitgupta/geo-distance@1.1.0","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-A+atMwEstQICm16EHGomdTXsQTZ4+hVYgcwe1onfrSG4H7wKOxGh49s4P3lOBFLE+E8DQwjqKBQuKvZ/OaDrJA==","shasum":"1694b30b106a9a96fb4c0c2061e53b9fda8bd637","tarball":"https://registry.npmjs.org/@arijitgupta/geo-distance/-/geo-distance-1.1.0.tgz","fileCount":19,"unpackedSize":25748,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDPzEdl+IFLIKijqwlI6Phil1ZJsiGW6S4IenVxfe9WLAIhANfOLTkJpnR5FigAQMbh12WD/aQlJ/5iWwLSomoO/Uie"}]},"_npmUser":{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"},"directories":{},"maintainers":[{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/geo-distance_1.1.0_1788624091109_0.6116297434037041"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-01T17:57:49.308Z","modified":"2026-09-05T16:01:31.396Z","1.0.0":"2026-09-01T17:57:49.605Z","1.0.1":"2026-09-01T18:32:53.348Z","1.1.0":"2026-09-05T16:01:31.256Z"},"bugs":{"url":"https://github.com/ArijitGupta-in/geo-distance/issues"},"author":{"name":"Arijit Gupta"},"license":"MIT","homepage":"https://github.com/ArijitGupta-in/geo-distance","keywords":["geo","geospatial","distance","coordinates","haversine","great-circle","latitude","longitude","dms","geography","kilometers","miles","feet","distance-conversion"],"repository":{"type":"git","url":"git+https://github.com/ArijitGupta-in/geo-distance.git"},"description":"Estimate great-circle distances between geographic coordinates in meters, kilometers, miles, or feet using the Haversine formula, with decimal-degree and DMS support.","maintainers":[{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"}],"readme":"# @arijitgupta/geo-distance\r\n\r\n[![npm version](https://img.shields.io/npm/v/@arijitgupta/geo-distance)](https://www.npmjs.com/package/@arijitgupta/geo-distance)\r\n[![license](https://img.shields.io/npm/l/@arijitgupta/geo-distance)](https://opensource.org/licenses/MIT)\r\n\r\nA lightweight, dependency-free TypeScript utility for estimating the great-circle distance between two\r\ngeographic coordinates using the Haversine formula.\r\n\r\nAccepts coordinates in **decimal degrees** or **Degrees, Minutes, Seconds (DMS)** format.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @arijitgupta/geo-distance\r\n```\r\n\r\n## Usage\r\n\r\n### Decimal degrees\r\n\r\n```ts\r\nimport {\r\n    distanceBetween,\r\n    type Coordinate,\r\n} from \"@arijitgupta/geo-distance\";\r\n\r\nconst from: Coordinate = { latitude: 0, longitude: 0 };\r\nconst to: Coordinate = { latitude: 0, longitude: 1 };\r\n\r\ndistanceBetween(from, to);               // ~111,195 meters (default)\r\ndistanceBetween(from, to, \"kilometers\"); // ~111.195 km\r\ndistanceBetween(from, to, \"miles\");      // ~69.09 miles\r\ndistanceBetween(from, to, \"feet\");       // ~364,813 feet\r\n```\r\n\r\n### DMS coordinates\r\n\r\n```ts\r\nimport {\r\n    distanceBetween,\r\n    type DMSCoordinate,\r\n} from \"@arijitgupta/geo-distance\";\r\n\r\nconst kolkata: DMSCoordinate = {\r\n    latitude:  { degrees: 22, minutes: 34, seconds: 21.36, direction: \"N\" },\r\n    longitude: { degrees: 88, minutes: 21, seconds: 50.04, direction: \"E\" },\r\n};\r\n\r\nconst newDelhi: DMSCoordinate = {\r\n    latitude:  { degrees: 28, minutes: 38, seconds: 12,   direction: \"N\" },\r\n    longitude: { degrees: 77, minutes: 12, seconds: 36,   direction: \"E\" },\r\n};\r\n\r\nconst distanceInMeters: number = distanceBetween(kolkata, newDelhi);\r\nconsole.log(distanceInMeters); // ~1,306,000 meters\r\n```\r\n\r\nMixed formats are supported — `from` and `to` can each be either type independently.\r\n\r\n### Converting DMS to decimal degrees\r\n\r\n```ts\r\nimport { dmsToDecimal, type DMSCoordinate } from \"@arijitgupta/geo-distance\";\r\n\r\nconst dms: DMSCoordinate = {\r\n    latitude:  { degrees: 22, minutes: 34, seconds: 21.36, direction: \"N\" },\r\n    longitude: { degrees: 88, minutes: 21, seconds: 50.04, direction: \"E\" },\r\n};\r\n\r\nconst decimal = dmsToDecimal(dms);\r\n// { latitude: 22.5726, longitude: 88.3639 }\r\n```\r\n\r\n## API\r\n\r\n### `distanceBetween(from, to, unit?)`\r\n\r\nReturns the estimated great-circle distance between two coordinates.\r\n\r\n| Parameter | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| `from` | `Coordinate \\| DMSCoordinate` | — | Starting coordinate |\r\n| `to` | `Coordinate \\| DMSCoordinate` | — | Destination coordinate |\r\n| `unit` | `DistanceUnit` | `\"meters\"` | Output unit |\r\n\r\n**`DistanceUnit`:** `\"meters\"` \\| `\"kilometers\"` \\| `\"miles\"` \\| `\"feet\"`\r\n\r\n**Returns:** `number` — distance in the requested unit.\r\n\r\n**Throws:** `RangeError` if a coordinate component is invalid (including non-finite\r\ndecimal values, latitude outside `[-90, 90]`, longitude outside `[-180, 180]`, or\r\nan invalid DMS component).  \r\n**Throws:** `TypeError` if `unit` is not a supported `DistanceUnit`.\r\n\r\n### `validateCoordinate(coord)`\r\n\r\nValidates a decimal-degree `Coordinate`. Useful for checking inputs before passing them to `distanceBetween`.\r\n\r\n**Throws:** `RangeError` if `latitude` or `longitude` is outside its valid range, or\r\nif either value is not finite.\r\n\r\n### `dmsToDecimal(dms)`\r\n\r\nConverts a `DMSCoordinate` to a decimal-degree `Coordinate`.\r\n\r\n**Throws:** `RangeError` if any DMS component is out of range.\r\n\r\n### `Coordinate`\r\n\r\n```ts\r\ninterface Coordinate {\r\n    latitude: number;   // -90 to 90\r\n    longitude: number;  // -180 to 180\r\n}\r\n```\r\n\r\n### `DMSCoordinate`\r\n\r\n```ts\r\ninterface DMSCoordinate {\r\n    latitude:  LatitudeDMS;\r\n    longitude: LongitudeDMS;\r\n}\r\n\r\ninterface LatitudeDMS {\r\n    degrees:   number;             // 0–90\r\n    minutes:   number;             // 0–59\r\n    seconds:   number;             // 0–<60\r\n    direction: \"N\" | \"S\";\r\n}\r\n\r\ninterface LongitudeDMS {\r\n    degrees:   number;             // 0–180\r\n    minutes:   number;             // 0–59\r\n    seconds:   number;             // 0–<60\r\n    direction: \"E\" | \"W\";\r\n}\r\n```\r\n\r\n**Validation rules:**\r\n\r\n- `minutes` must be in `[0, 60)`.\r\n- `seconds` must be in `[0, 60)`.\r\n- `latitude.degrees` must be in `[0, 90]`; combined value must not exceed 90°.\r\n- `longitude.degrees` must be in `[0, 180]`; combined value must not exceed 180°.\r\n\r\n## Behavior\r\n\r\n- Uses the Haversine formula to compute the great-circle distance between two points on Earth.\r\n- Returns a result in the requested unit, using meters by default and a fixed Earth\r\n    radius of `6,371,000` meters.\r\n- Accurate to within ~0.5% for most distances. Error increases at high latitudes due to Earth's oblate shape.\r\n- DMS coordinates are normalized to decimal degrees before the distance calculation.\r\n- Has no runtime dependencies.\r\n\r\n## Development\r\n\r\n```bash\r\nnpm install       # install dev dependencies\r\nnpm test          # run tests with Vitest\r\nnpm run check     # type-check without emitting output\r\nnpm run build     # compile TypeScript to dist/\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}