{"_id":"@arijitgupta/geo-bearing","name":"@arijitgupta/geo-bearing","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arijitgupta/geo-bearing","version":"1.0.0","description":"Calculate the initial bearing between geographic coordinates using decimal degrees or DMS notation.","type":"module","repository":{"type":"git","url":"git+https://github.com/ArijitGupta-in/geo-bearing.git"},"homepage":"https://github.com/ArijitGupta-in/geo-bearing","bugs":{"url":"https://github.com/ArijitGupta-in/geo-bearing/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","bearing","coordinates","navigation","azimuth","great-circle","latitude","longitude","dms"],"author":{"name":"Arijit Gupta"},"license":"MIT","devDependencies":{"markdownlint-cli2":"^0.23.2","typescript":"^7.0.2","vitest":"^4.1.11"},"gitHead":"130b391d23c1659c2c4ca60a183b3e50c246cf11","_id":"@arijitgupta/geo-bearing@1.0.0","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-2ssAxWwXlhRHFeDt/LX0BOaD/10blnGqjOm+wcmhM24biNoC9iDRpRUiVVSEiqQ+jsxSCv7OzVDs050qk6Vv6w==","shasum":"4cf312adb7e7f45b2b57534884a5849f915ddb0b","tarball":"https://registry.npmjs.org/@arijitgupta/geo-bearing/-/geo-bearing-1.0.0.tgz","fileCount":23,"unpackedSize":29998,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCLw0i8/X6krsmYarHWazH/y6FKrwqAXylRmcW9kZPvsgIhAKUuzBXY94dfX5mOsknuFmNW5OuN0xf3JZzX6I2DW2Uv"}]},"_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-bearing_1.0.0_1788623936203_0.1646720581796357"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-05T15:58:56.073Z","1.0.0":"2026-09-05T15:58:56.326Z","modified":"2026-09-05T15:58:56.557Z"},"maintainers":[{"name":"arijitgupta","email":"arijitdesignsit@gmail.com"}],"description":"Calculate the initial bearing between geographic coordinates using decimal degrees or DMS notation.","homepage":"https://github.com/ArijitGupta-in/geo-bearing","keywords":["geo","geospatial","bearing","coordinates","navigation","azimuth","great-circle","latitude","longitude","dms"],"repository":{"type":"git","url":"git+https://github.com/ArijitGupta-in/geo-bearing.git"},"author":{"name":"Arijit Gupta"},"bugs":{"url":"https://github.com/ArijitGupta-in/geo-bearing/issues"},"license":"MIT","readme":"# @arijitgupta/geo-bearing\r\n\r\n[![npm version](https://img.shields.io/npm/v/@arijitgupta/geo-bearing)](https://www.npmjs.com/package/@arijitgupta/geo-bearing)\r\n[![license](https://img.shields.io/npm/l/@arijitgupta/geo-bearing)](https://opensource.org/licenses/MIT)\r\n\r\nA lightweight, dependency-free TypeScript utility for calculating the initial bearing\r\nbetween two geographic coordinates along a great-circle path.\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-bearing\r\n```\r\n\r\n## Usage\r\n\r\n### Decimal degrees\r\n\r\n```ts\r\nimport {\r\n    bearingBetween,\r\n    type Coordinate,\r\n} from \"@arijitgupta/geo-bearing\";\r\n\r\nconst from: Coordinate = { latitude: 0, longitude: 0 };\r\nconst to: Coordinate = { latitude: 1, longitude: 0 };\r\n\r\nconst bearing = bearingBetween(from, to);\r\nconsole.log(bearing); // 0 degrees: due north\r\n```\r\n\r\nThe result is measured clockwise from true north and is normalized to the range `0 <= bearing < 360`.\r\n\r\n### DMS coordinates\r\n\r\n```ts\r\nimport {\r\n    bearingBetween,\r\n    type DMSCoordinate,\r\n} from \"@arijitgupta/geo-bearing\";\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 bearing = bearingBetween(kolkata, newDelhi);\r\nconsole.log(bearing); // initial bearing in degrees\r\n```\r\n\r\nMixed formats are supported: `from` and `to` can each be either a decimal-degree or DMS coordinate.\r\n\r\n### Converting DMS to decimal degrees\r\n\r\n```ts\r\nimport {\r\n    dmsToDecimal,\r\n    type DMSCoordinate,\r\n} from \"@arijitgupta/geo-bearing\";\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### `bearingBetween(from, to)`\r\n\r\nReturns the initial bearing from one geographic coordinate to another in degrees.\r\n\r\n| Parameter | Type | Description |\r\n| --- | --- | --- |\r\n| `from` | `Coordinate \\| DMSCoordinate` | Starting coordinate |\r\n| `to` | `Coordinate \\| DMSCoordinate` | Destination coordinate |\r\n\r\n**Returns:** `number` - initial bearing in degrees, measured clockwise from true north\r\nand normalized to `0 <= bearing < 360`.\r\n\r\n**Throws:** `RangeError` if the two coordinates are identical, a decimal coordinate\r\nis invalid, or a DMS component is out of range.\r\n\r\n### `dmsToDecimal(dms)`\r\n\r\nConverts a `DMSCoordinate` to a decimal-degree coordinate object.\r\n\r\n**Throws:** `RangeError` if any DMS component is out of range.\r\n\r\n### `validateCoordinate(coordinate)`\r\n\r\nValidates a decimal-degree coordinate.\r\n\r\n**Throws:** `RangeError` if latitude is outside `[-90, 90]`, longitude is outside\r\n`[-180, 180]`, or either value is not finite.\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]`; the combined value must not exceed 90 degrees.\r\n- `longitude.degrees` must be in `[0, 180]`; the combined value must not exceed 180 degrees.\r\n\r\n## Behavior\r\n\r\n- Uses spherical geometry to calculate the initial bearing, or forward azimuth, along\r\n    the great-circle path between two points on Earth.\r\n- Measures the result clockwise from true north.\r\n- Normalizes results to the range `0 <= bearing < 360`.\r\n- Accepts decimal-degree, DMS, and mixed coordinate formats.\r\n- Throws a `RangeError` when the bearing is undefined because both coordinates are identical.\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","_rev":"1-3c5d81082a8cc5f81a94f1226c75d0c3"}