bearing-angle-calculator 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# Bearing Angle 🧭 Calculator
+
+A lightweight JavaScript utility library for calculating bearing angles between geographic coordinates.
+
+## Installation
+
+```bash
+npm install bearing-calculator
+```
+
+## Usage
+
+```javascript
+import { calculateBearing, getCompassDirection, calculateDistance } from 'bearing-calculator';
+
+// Calculate bearing from New York to London
+const bearing = calculateBearing(40.7128, -74.0060, 51.5074, -0.1278);
+console.log(bearing); // ~51.2°
+
+// Get compass direction
+const direction = getCompassDirection(bearing);
+console.log(direction); // "NE"
+
+// Calculate distance
+const distance = calculateDistance(40.7128, -74.0060, 51.5074, -0.1278, 'km');
+console.log(distance); // ~5570 km
+```
+
+### CommonJS
+
+```javascript
+const { calculateBearing, getCompassDirection } = require('bearing-calculator');
+```
+
+## API Reference
+
+### `calculateBearing(startLat, startLng, endLat, endLng)`
+
+Returns bearing angle (0-360°) from start to end point.
+
+### `getCompassDirection(bearing)`
+
+Returns 8-point compass direction (N, NE, E, SE, S, SW, W, NW).
+
+### `getDetailedCompassDirection(bearing)`
+
+Returns 16-point compass direction (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW).
+
+### `calculateDistance(startLat, startLng, endLat, endLng, unit)`
+
+Returns distance between points.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `startLat` | number | Starting latitude (-90 to 90) |
+| `startLng` | number | Starting longitude (-180 to 180) |
+| `endLat` | number | Ending latitude (-90 to 90) |
+| `endLng` | number | Ending longitude (-180 to 180) |
+| `unit` | string | `'km'` (default), `'miles'`, or `'meters'` |
+
+### `toRadians(degrees)`
+
+Converts degrees to radians.
+
+### `toDegrees(radians)`
+
+Converts radians to degrees.
+
+## License
+
+MIT

package/bearing.js

@@ -0,0 +1,147 @@
+/**
+ * Bearing Calculator Utilities
+ * Calculate bearing angle between two geographic coordinates
+ */
+
+/**
+ * Convert degrees to radians
+ * @param {number} degrees - Angle in degrees
+ * @returns {number} Angle in radians
+ */
+function toRadians(degrees) {
+  return degrees * (Math.PI / 180);
+}
+
+/**
+ * Convert radians to degrees
+ * @param {number} radians - Angle in radians
+ * @returns {number} Angle in degrees
+ */
+function toDegrees(radians) {
+  return radians * (180 / Math.PI);
+}
+
+/**
+ * Calculate the bearing angle between two geographic points
+ * The bearing is the compass direction from the start point to the end point
+ * 
+ * @param {number} startLat - Starting point latitude (-90 to 90)
+ * @param {number} startLng - Starting point longitude (-180 to 180)
+ * @param {number} endLat - Ending point latitude (-90 to 90)
+ * @param {number} endLng - Ending point longitude (-180 to 180)
+ * @returns {number} Bearing angle in degrees (0-360), where 0/360 is North
+ */
+function calculateBearing(startLat, startLng, endLat, endLng) {
+  // Validate inputs
+  if (typeof startLat !== 'number' || typeof startLng !== 'number' ||
+      typeof endLat !== 'number' || typeof endLng !== 'number') {
+    throw new Error('All coordinates must be numbers');
+  }
+
+  if (startLat < -90 || startLat > 90 || endLat < -90 || endLat > 90) {
+    throw new Error('Latitude must be between -90 and 90 degrees');
+  }
+
+  if (startLng < -180 || startLng > 180 || endLng < -180 || endLng > 180) {
+    throw new Error('Longitude must be between -180 and 180 degrees');
+  }
+
+  // Convert to radians
+  const startLatRad = toRadians(startLat);
+  const startLngRad = toRadians(startLng);
+  const endLatRad = toRadians(endLat);
+  const endLngRad = toRadians(endLng);
+
+  // Calculate the difference in longitude
+  const dLng = endLngRad - startLngRad;
+
+  // Calculate bearing using the forward azimuth formula
+  const x = Math.sin(dLng) * Math.cos(endLatRad);
+  const y = Math.cos(startLatRad) * Math.sin(endLatRad) -
+            Math.sin(startLatRad) * Math.cos(endLatRad) * Math.cos(dLng);
+
+  // Calculate bearing in radians and convert to degrees
+  let bearing = toDegrees(Math.atan2(x, y));
+
+  // Normalize to 0-360 range
+  bearing = (bearing + 360) % 360;
+
+  return bearing;
+}
+
+/**
+ * Get the compass cardinal/intercardinal direction from a bearing angle
+ * 
+ * @param {number} bearing - Bearing angle in degrees (0-360)
+ * @returns {string} Compass direction (N, NE, E, SE, S, SW, W, NW)
+ */
+function getCompassDirection(bearing) {
+  if (typeof bearing !== 'number' || bearing < 0 || bearing > 360) {
+    throw new Error('Bearing must be a number between 0 and 360');
+  }
+
+  const directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
+  const index = Math.round(bearing / 45) % 8;
+  return directions[index];
+}
+
+/**
+ * Get detailed compass direction (16-point)
+ * 
+ * @param {number} bearing - Bearing angle in degrees (0-360)
+ * @returns {string} Detailed compass direction (N, NNE, NE, ENE, E, etc.)
+ */
+function getDetailedCompassDirection(bearing) {
+  if (typeof bearing !== 'number' || bearing < 0 || bearing > 360) {
+    throw new Error('Bearing must be a number between 0 and 360');
+  }
+
+  const directions = [
+    'N', 'NNE', 'NE', 'ENE',
+    'E', 'ESE', 'SE', 'SSE',
+    'S', 'SSW', 'SW', 'WSW',
+    'W', 'WNW', 'NW', 'NNW'
+  ];
+  const index = Math.round(bearing / 22.5) % 16;
+  return directions[index];
+}
+
+/**
+ * Calculate distance between two points using Haversine formula
+ * 
+ * @param {number} startLat - Starting point latitude
+ * @param {number} startLng - Starting point longitude
+ * @param {number} endLat - Ending point latitude
+ * @param {number} endLng - Ending point longitude
+ * @param {string} unit - Unit of measurement ('km', 'miles', 'meters')
+ * @returns {number} Distance in specified unit
+ */
+function calculateDistance(startLat, startLng, endLat, endLng, unit = 'km') {
+  const R = {
+    km: 6371,
+    miles: 3959,
+    meters: 6371000
+  };
+
+  const radius = R[unit] || R.km;
+
+  const dLat = toRadians(endLat - startLat);
+  const dLng = toRadians(endLng - startLng);
+
+  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+            Math.cos(toRadians(startLat)) * Math.cos(toRadians(endLat)) *
+            Math.sin(dLng / 2) * Math.sin(dLng / 2);
+
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+  return radius * c;
+}
+
+module.exports = {
+  calculateBearing,
+  getCompassDirection,
+  getDetailedCompassDirection,
+  calculateDistance,
+  toRadians,
+  toDegrees
+};

package/index.d.ts

@@ -0,0 +1,57 @@
+// Type definitions for bearing-calculator
+
+/**
+ * Convert degrees to radians
+ */
+export function toRadians(degrees: number): number;
+
+/**
+ * Convert radians to degrees
+ */
+export function toDegrees(radians: number): number;
+
+/**
+ * Calculate bearing angle between two geographic points
+ * @param startLat Starting latitude (-90 to 90)
+ * @param startLng Starting longitude (-180 to 180)
+ * @param endLat Ending latitude (-90 to 90)
+ * @param endLng Ending longitude (-180 to 180)
+ * @returns Bearing angle in degrees (0-360)
+ */
+export function calculateBearing(
+  startLat: number,
+  startLng: number,
+  endLat: number,
+  endLng: number
+): number;
+
+/**
+ * Get 8-point compass direction from bearing
+ * @param bearing Bearing angle (0-360)
+ * @returns Cardinal direction (N, NE, E, SE, S, SW, W, NW)
+ */
+export function getCompassDirection(bearing: number): string;
+
+/**
+ * Get 16-point compass direction from bearing
+ * @param bearing Bearing angle (0-360)
+ * @returns Detailed compass direction (N, NNE, NE, ENE, etc.)
+ */
+export function getDetailedCompassDirection(bearing: number): string;
+
+/**
+ * Calculate distance between two geographic points
+ * @param startLat Starting latitude
+ * @param startLng Starting longitude
+ * @param endLat Ending latitude
+ * @param endLng Ending longitude
+ * @param unit Unit of measurement ('km', 'miles', 'meters')
+ * @returns Distance in specified unit
+ */
+export function calculateDistance(
+  startLat: number,
+  startLng: number,
+  endLat: number,
+  endLng: number,
+  unit?: 'km' | 'miles' | 'meters'
+): number;

package/index.js

@@ -0,0 +1,27 @@
+/**
+ * Bearing Calculator
+ * Calculate bearing angles between geographic coordinates
+ * 
+ * @module bearing-calculator
+ */
+
+// Core utilities
+const {
+  calculateBearing,
+  getCompassDirection,
+  getDetailedCompassDirection,
+  calculateDistance,
+  toRadians,
+  toDegrees
+} = require('./bearing');
+
+module.exports = {
+  // Core functions
+  calculateBearing,
+  getCompassDirection,
+  getDetailedCompassDirection,
+  calculateDistance,
+  toRadians,
+  toDegrees,
+
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "bearing-angle-calculator",
+  "version": "1.0.0",
+  "description": "Calculate bearing angle between two geographic coordinates for React applications",
+  "keywords": [
+    "react",
+    "bearing",
+    "latitude",
+    "longitude",
+    "bearing-angle",
+    "compass",
+    "navigation",
+    "geolocation"
+  ],
+  "license": "MIT",
+  "author": "rajath002",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bearing.js",
+    "useBearing.js",
+    "BearingIndicator.jsx",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rajath002/bearing-calculator"
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}