geo-relative-position 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,604 @@
+/**
+ * Basic geographic coordinates
+ */
+interface Coordinates {
+    /** Latitude in degrees (-90 to 90) */
+    latitude: number;
+    /** Longitude in degrees (-180 to 180) */
+    longitude: number;
+}
+/**
+ * User's current position with optional motion data
+ */
+interface UserPosition extends Coordinates {
+    /** User's direction of travel in degrees (0-360, 0 = North, 90 = East) */
+    bearing?: number;
+    /** User's speed in meters per second */
+    speedMps?: number;
+    /** GPS accuracy radius in meters */
+    accuracy?: number;
+    /** Altitude in meters (for future 3D calculations) */
+    altitude?: number;
+}
+/**
+ * Point of Interest with optional boundary radius
+ */
+interface POI extends Coordinates {
+    /** Unique identifier for the POI */
+    id?: string | number;
+    /** Display name of the POI */
+    name?: string;
+    /** Radius in meters defining POI boundary (for large POIs like parks) */
+    radiusMeters?: number;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Simple 4-direction orientation
+ */
+type SimpleOrientation = 'ahead' | 'behind' | 'left' | 'right';
+/**
+ * Granular 8-direction orientation (compass points)
+ */
+type CompassOrientation = 'north' | 'northeast' | 'east' | 'southeast' | 'south' | 'southwest' | 'west' | 'northwest';
+/**
+ * Detailed relative orientation with angular precision
+ */
+type DetailedOrientation = 'directly_ahead' | 'ahead_left' | 'ahead_right' | 'left' | 'right' | 'behind_left' | 'behind_right' | 'directly_behind';
+/**
+ * Approach status indicating if user is moving toward or away from POI
+ */
+type ApproachStatus = 'approaching' | 'receding' | 'stationary' | 'unknown';
+/**
+ * Complete relative position result
+ */
+interface RelativePosition {
+    /** Distance from user to POI center in meters */
+    distanceMeters: number;
+    /** Distance from user to POI center in kilometers */
+    distanceKm: number;
+    /** Distance from user to POI edge (considering radius) in meters */
+    distanceToEdgeMeters: number;
+    /** Absolute bearing from user to POI (0-360, 0 = North) */
+    absoluteBearing: number;
+    /** Relative bearing from user's heading to POI (-180 to 180) */
+    relativeBearing: number;
+    /** Simple orientation (4-way) */
+    simpleOrientation: SimpleOrientation;
+    /** Compass orientation (8-way) */
+    compassOrientation: CompassOrientation;
+    /** Detailed orientation */
+    detailedOrientation: DetailedOrientation;
+    /** Whether user is currently within POI boundary */
+    isWithinPOI: boolean;
+    /** Whether user is approaching or receding from POI */
+    approachStatus: ApproachStatus;
+}
+/**
+ * Estimated Time of Arrival result
+ */
+interface ETAResult {
+    /** Estimated time to reach POI center in seconds */
+    etaSeconds: number;
+    /** Estimated time to reach POI edge in seconds (if POI has radius) */
+    etaToEdgeSeconds: number;
+    /** Formatted time string (e.g., "2 min 30 sec", "1 hr 15 min") */
+    formatted: string;
+    /** Formatted short time string (e.g., "2m", "1h 15m") */
+    formattedShort: string;
+    /** Whether ETA is valid (user moving toward POI) */
+    isValid: boolean;
+    /** Reason if ETA is invalid */
+    invalidReason?: 'stationary' | 'moving_away' | 'no_speed_data' | 'at_destination';
+}
+/**
+ * Closest point calculation result (for POIs with radius)
+ */
+interface ClosestPointResult {
+    /** Coordinates of closest point on POI boundary */
+    closestPoint: Coordinates;
+    /** Distance to closest point in meters */
+    distanceMeters: number;
+    /** Bearing to closest point */
+    bearing: number;
+    /** Whether user is inside the POI boundary */
+    isInside: boolean;
+}
+/**
+ * POI with calculated relative position data
+ */
+interface POIWithRelativePosition extends POI {
+    /** Calculated relative position data */
+    relativePosition: RelativePosition;
+    /** Optional ETA data (if user speed provided) */
+    eta?: ETAResult;
+}
+/**
+ * Cone filter configuration (for route-ahead queries)
+ */
+interface ConeFilter {
+    /** Center angle of cone in degrees (typically user's bearing) */
+    centerAngle: number;
+    /** Half-width of cone in degrees (e.g., 30 = 60 degree total cone) */
+    halfAngle: number;
+    /** Maximum distance in meters */
+    maxDistanceMeters: number;
+    /** Minimum distance in meters (optional, for excluding nearby POIs) */
+    minDistanceMeters?: number;
+}
+/**
+ * Proximity filter configuration
+ */
+interface ProximityFilter {
+    /** Maximum distance in meters */
+    maxDistanceMeters: number;
+    /** Minimum distance in meters (optional) */
+    minDistanceMeters?: number;
+    /** Only include POIs user is approaching */
+    approachingOnly?: boolean;
+}
+/**
+ * Sort configuration for batch operations
+ */
+interface SortConfig {
+    /** Sort field */
+    by: 'distance' | 'eta' | 'relativeBearing';
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Speed unit for conversion utilities
+ */
+type SpeedUnit = 'mps' | 'kmh' | 'mph';
+
+/**
+ * Earth's mean radius in meters (WGS84 approximation)
+ */
+declare const EARTH_RADIUS_METERS = 6371000;
+/**
+ * Threshold below which a user is considered stationary (m/s)
+ * Approximately 1.8 km/h or 1.1 mph
+ */
+declare const STATIONARY_SPEED_THRESHOLD = 0.5;
+/**
+ * Orientation angle thresholds (in degrees)
+ */
+declare const ORIENTATION_THRESHOLDS: {
+    /** Threshold for "directly ahead" (+/- degrees from 0) */
+    readonly DIRECTLY_AHEAD: 10;
+    /** Threshold for "ahead" region (within +/- degrees from 0) */
+    readonly AHEAD: 45;
+    /** Threshold for "behind" region (beyond +/- degrees from 0) */
+    readonly BEHIND: 135;
+    /** Threshold for "directly behind" (+/- degrees from 180) */
+    readonly DIRECTLY_BEHIND: 170;
+};
+/**
+ * Compass orientation boundaries (in degrees, clockwise from North)
+ */
+declare const COMPASS_BOUNDARIES: {
+    readonly NORTH_END: 22.5;
+    readonly NORTHEAST_END: 67.5;
+    readonly EAST_END: 112.5;
+    readonly SOUTHEAST_END: 157.5;
+    readonly SOUTH_END: 202.5;
+    readonly SOUTHWEST_END: 247.5;
+    readonly WEST_END: 292.5;
+    readonly NORTHWEST_END: 337.5;
+};
+
+/**
+ * Calculate the great-circle distance between two points using the Haversine formula.
+ * This is the shortest distance over the earth's surface.
+ *
+ * @param from - Starting coordinates
+ * @param to - Ending coordinates
+ * @returns Distance in meters
+ *
+ * @example
+ * const distance = getDistance(
+ *   { latitude: 37.7749, longitude: -122.4194 },  // San Francisco
+ *   { latitude: 34.0522, longitude: -118.2437 }   // Los Angeles
+ * );
+ * // Returns: approximately 559120 meters (~559 km)
+ */
+declare function getDistance(from: Coordinates, to: Coordinates): number;
+/**
+ * Calculate distance in kilometers
+ *
+ * @param from - Starting coordinates
+ * @param to - Ending coordinates
+ * @returns Distance in kilometers
+ */
+declare function getDistanceKm(from: Coordinates, to: Coordinates): number;
+
+/**
+ * Calculate the initial bearing (forward azimuth) from one point to another.
+ * Uses the spherical law of sines/cosines for accurate bearing calculation.
+ *
+ * @param from - Starting coordinates
+ * @param to - Ending coordinates
+ * @returns Bearing in degrees (0-360, where 0 = North, 90 = East)
+ *
+ * @example
+ * const bearing = getBearing(
+ *   { latitude: 37.7749, longitude: -122.4194 },  // San Francisco
+ *   { latitude: 34.0522, longitude: -118.2437 }   // Los Angeles
+ * );
+ * // Returns: approximately 136 (southeast)
+ */
+declare function getBearing(from: Coordinates, to: Coordinates): number;
+/**
+ * Calculate the relative bearing from user's heading to a target.
+ * Positive values indicate target is to the right, negative to the left.
+ *
+ * @param userBearing - User's current heading (0-360)
+ * @param targetBearing - Absolute bearing to target (0-360)
+ * @returns Relative bearing (-180 to 180, positive = right, negative = left)
+ *
+ * @example
+ * // User heading north (0), target is to the east (90)
+ * getRelativeBearing(0, 90);   // Returns: 90 (target is to the right)
+ *
+ * // User heading east (90), target is to the north (0)
+ * getRelativeBearing(90, 0);   // Returns: -90 (target is to the left)
+ *
+ * // User heading south (180), target is to the north (0)
+ * getRelativeBearing(180, 0);  // Returns: 180 or -180 (target is behind)
+ */
+declare function getRelativeBearing(userBearing: number, targetBearing: number): number;
+/**
+ * Calculate the final bearing (reverse azimuth) at the destination point.
+ * This is the direction you'd be facing when arriving at the destination.
+ *
+ * @param from - Starting coordinates
+ * @param to - Ending coordinates
+ * @returns Final bearing in degrees (0-360)
+ */
+declare function getFinalBearing(from: Coordinates, to: Coordinates): number;
+
+/**
+ * Get simple 4-way orientation from relative bearing
+ *
+ * @param relativeBearing - Relative bearing (-180 to 180)
+ * @returns Simple orientation: 'ahead', 'behind', 'left', or 'right'
+ *
+ * @example
+ * getSimpleOrientation(0);     // 'ahead'
+ * getSimpleOrientation(45);    // 'ahead' (within 45 degrees)
+ * getSimpleOrientation(90);    // 'right'
+ * getSimpleOrientation(-90);   // 'left'
+ * getSimpleOrientation(180);   // 'behind'
+ */
+declare function getSimpleOrientation(relativeBearing: number): SimpleOrientation;
+/**
+ * Get compass 8-way orientation from absolute bearing
+ *
+ * @param absoluteBearing - Absolute bearing (0-360, 0 = North)
+ * @returns Compass orientation: 'north', 'northeast', 'east', etc.
+ *
+ * @example
+ * getCompassOrientation(0);    // 'north'
+ * getCompassOrientation(45);   // 'northeast'
+ * getCompassOrientation(90);   // 'east'
+ * getCompassOrientation(180);  // 'south'
+ */
+declare function getCompassOrientation(absoluteBearing: number): CompassOrientation;
+/**
+ * Get detailed 8-way orientation with nuance from relative bearing
+ *
+ * @param relativeBearing - Relative bearing (-180 to 180)
+ * @returns Detailed orientation with directional nuance
+ *
+ * @example
+ * getDetailedOrientation(0);     // 'directly_ahead'
+ * getDetailedOrientation(5);     // 'directly_ahead' (within 10 degrees)
+ * getDetailedOrientation(30);    // 'ahead_right'
+ * getDetailedOrientation(90);    // 'right'
+ * getDetailedOrientation(150);   // 'behind_right'
+ * getDetailedOrientation(175);   // 'directly_behind'
+ */
+declare function getDetailedOrientation(relativeBearing: number): DetailedOrientation;
+/**
+ * Get human-readable description of orientation
+ *
+ * @param orientation - Any orientation type
+ * @returns Human-readable string
+ */
+declare function getOrientationDescription(orientation: SimpleOrientation | CompassOrientation | DetailedOrientation): string;
+
+/**
+ * Calculate the closest point on a POI's boundary to the user.
+ * For POIs with radius (large areas like parks), finds the edge point.
+ * For point POIs (no radius), returns the POI coordinates.
+ *
+ * @param user - User's coordinates
+ * @param poi - POI with optional radius
+ * @returns Closest point result with distance and bearing
+ *
+ * @example
+ * const closest = getClosestPoint(
+ *   { latitude: 37.7749, longitude: -122.4194 },
+ *   { latitude: 37.7700, longitude: -122.4200, radiusMeters: 500, name: 'Large Park' }
+ * );
+ */
+declare function getClosestPoint(user: Coordinates, poi: POI): ClosestPointResult;
+/**
+ * Calculate destination point given start, bearing, and distance.
+ * Uses the direct geodesic formula (inverse Haversine).
+ *
+ * @param start - Starting coordinates
+ * @param bearing - Bearing in degrees (0-360)
+ * @param distanceMeters - Distance in meters
+ * @returns Destination coordinates
+ *
+ * @example
+ * // Starting from San Francisco, travel 10km northeast
+ * const dest = destinationPoint(
+ *   { latitude: 37.7749, longitude: -122.4194 },
+ *   45,     // northeast bearing
+ *   10000   // 10 km
+ * );
+ */
+declare function destinationPoint(start: Coordinates, bearing: number, distanceMeters: number): Coordinates;
+/**
+ * Calculate the distance to the edge of a POI (considering its radius)
+ *
+ * @param user - User's coordinates
+ * @param poi - POI with optional radius
+ * @returns Distance to edge in meters (0 if inside, negative values not returned)
+ */
+declare function getDistanceToEdge(user: Coordinates, poi: POI): number;
+/**
+ * Check if a point is within a POI's boundary
+ *
+ * @param point - Coordinates to check
+ * @param poi - POI with optional radius
+ * @returns True if point is within the POI boundary
+ */
+declare function isWithinPOI(point: Coordinates, poi: POI): boolean;
+
+/**
+ * Calculate estimated time of arrival to a POI.
+ * Considers user's speed, bearing relative to POI, and POI radius.
+ *
+ * @param user - User position with speed data
+ * @param poi - Target POI
+ * @param relativePosition - Pre-calculated relative position (optional, for efficiency)
+ * @returns ETA result with validity check
+ *
+ * @example
+ * const eta = getETA(
+ *   { latitude: 37.7749, longitude: -122.4194, bearing: 45, speedMps: 13.4 }, // ~30 mph
+ *   { latitude: 37.7849, longitude: -122.4094, radiusMeters: 100 }
+ * );
+ * // Returns: { etaSeconds: 120, formatted: "2 min", isValid: true }
+ */
+declare function getETA(user: UserPosition, poi: POI, relativePosition?: Partial<RelativePosition>): ETAResult;
+/**
+ * Calculate simple ETA without considering approach angle
+ * Useful when user bearing is unknown or irrelevant
+ *
+ * @param distanceMeters - Distance to target in meters
+ * @param speedMps - Speed in meters per second
+ * @returns ETA in seconds, or Infinity if invalid
+ */
+declare function getSimpleETA(distanceMeters: number, speedMps: number): number;
+
+/**
+ * Calculate complete relative position between user and POI.
+ * This is the primary function combining distance, bearing, and orientation.
+ *
+ * @param user - User's current position with optional bearing and speed
+ * @param poi - Target POI with optional radius
+ * @returns Complete relative position data
+ */
+declare function getRelativePosition(user: UserPosition, poi: POI): RelativePosition;
+
+/**
+ * Calculate relative positions for multiple POIs and sort them.
+ * Efficient batch operation that calculates positions once and sorts.
+ *
+ * @param user - User position
+ * @param pois - Array of POIs
+ * @param config - Sort configuration (default: sort by distance ascending)
+ * @returns Sorted array of POIs with relative positions
+ *
+ * @example
+ * const sorted = sortByDistance(user, allPOIs);
+ * // Returns POIs sorted by distance, nearest first
+ *
+ * @example
+ * const sorted = sortByDistance(user, allPOIs, { by: 'eta', direction: 'asc' });
+ * // Returns POIs sorted by estimated arrival time
+ */
+declare function sortByDistance(user: UserPosition, pois: POI[], config?: SortConfig): POIWithRelativePosition[];
+/**
+ * Get the N nearest POIs to the user
+ *
+ * @param user - User position
+ * @param pois - Array of POIs
+ * @param count - Number of POIs to return
+ * @returns Array of nearest POIs with relative positions
+ */
+declare function getNearestPOIs(user: UserPosition, pois: POI[], count: number): POIWithRelativePosition[];
+/**
+ * Get the POIs with shortest ETA
+ *
+ * @param user - User position (must include speedMps)
+ * @param pois - Array of POIs
+ * @param count - Number of POIs to return
+ * @returns Array of POIs with shortest ETA
+ */
+declare function getNextArrivals(user: UserPosition, pois: POI[], count: number): POIWithRelativePosition[];
+
+/**
+ * Filter POIs by proximity and optionally by approach status.
+ *
+ * @param user - User position
+ * @param pois - Array of POIs
+ * @param filter - Proximity filter configuration
+ * @returns Filtered array of POIs with relative positions, sorted by distance
+ *
+ * @example
+ * // Get all POIs within 1km that user is approaching
+ * const nearby = filterByProximity(user, allPOIs, {
+ *   maxDistanceMeters: 1000,
+ *   approachingOnly: true
+ * });
+ */
+declare function filterByProximity(user: UserPosition, pois: POI[], filter: ProximityFilter): POIWithRelativePosition[];
+/**
+ * Filter POIs within a directional cone (for route-ahead queries).
+ * Useful for finding POIs along user's path of travel.
+ *
+ * @param user - User position with bearing
+ * @param pois - Array of POIs
+ * @param cone - Cone filter configuration
+ * @returns Filtered array of POIs within the cone, sorted by distance
+ *
+ * @example
+ * // Get POIs ahead within 30 degrees of heading, up to 5km
+ * const upcoming = filterByCone(user, allPOIs, {
+ *   centerAngle: user.bearing,
+ *   halfAngle: 30,
+ *   maxDistanceMeters: 5000
+ * });
+ */
+declare function filterByCone(user: UserPosition, pois: POI[], cone: ConeFilter): POIWithRelativePosition[];
+/**
+ * Filter POIs that the user is currently inside of (based on POI radius)
+ *
+ * @param user - User position
+ * @param pois - Array of POIs (should have radiusMeters set)
+ * @returns Array of POIs the user is currently within
+ */
+declare function filterInsidePOIs(user: UserPosition, pois: POI[]): POIWithRelativePosition[];
+/**
+ * Filter POIs by orientation (e.g., only POIs ahead or to the left)
+ *
+ * @param user - User position with bearing
+ * @param pois - Array of POIs
+ * @param orientations - Array of orientations to include
+ * @returns Filtered array of POIs
+ */
+declare function filterByOrientation(user: UserPosition, pois: POI[], orientations: Array<'ahead' | 'behind' | 'left' | 'right'>): POIWithRelativePosition[];
+
+/**
+ * Convert degrees to radians
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+declare function toRadians(degrees: number): number;
+/**
+ * Convert radians to degrees
+ * @param radians - Angle in radians
+ * @returns Angle in degrees
+ */
+declare function toDegrees(radians: number): number;
+/**
+ * Normalize angle to 0-360 range
+ * @param degrees - Angle in degrees (can be any value)
+ * @returns Normalized angle between 0 and 360
+ */
+declare function normalizeAngle(degrees: number): number;
+/**
+ * Normalize longitude to -180 to 180 range
+ * Handles international date line wraparound
+ * @param longitude - Longitude in degrees
+ * @returns Normalized longitude between -180 and 180
+ */
+declare function normalizeLongitude(longitude: number): number;
+/**
+ * Clamp a value between min and max
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Round a number to specified decimal places
+ * @param value - Value to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded value
+ */
+declare function roundTo(value: number, decimals: number): number;
+
+/**
+ * Format duration in seconds to human-readable string
+ * @param seconds - Duration in seconds
+ * @returns Formatted string (e.g., "2 min 30 sec", "1 hr 15 min")
+ */
+declare function formatDuration(seconds: number): string;
+/**
+ * Format duration in seconds to short human-readable string
+ * @param seconds - Duration in seconds
+ * @returns Short formatted string (e.g., "2m", "1h 15m")
+ */
+declare function formatDurationShort(seconds: number): string;
+/**
+ * Format distance in meters to human-readable string
+ * @param meters - Distance in meters
+ * @returns Formatted string (e.g., "500 m", "2.5 km")
+ */
+declare function formatDistance(meters: number): string;
+
+/**
+ * Check if coordinates are valid
+ * @param coords - Coordinates to validate
+ * @returns True if coordinates are valid
+ */
+declare function isValidCoordinates(coords: Coordinates): boolean;
+/**
+ * Check if a bearing value is valid
+ * @param bearing - Bearing in degrees
+ * @returns True if bearing is valid (0-360 or undefined)
+ */
+declare function isValidBearing(bearing: number | undefined): boolean;
+/**
+ * Check if a speed value is valid
+ * @param speed - Speed in meters per second
+ * @returns True if speed is valid (non-negative or undefined)
+ */
+declare function isValidSpeed(speed: number | undefined): boolean;
+/**
+ * Check if a radius value is valid
+ * @param radius - Radius in meters
+ * @returns True if radius is valid (non-negative or undefined)
+ */
+declare function isValidRadius(radius: number | undefined): boolean;
+/**
+ * Validate a UserPosition object
+ * @param user - User position to validate
+ * @returns Object with isValid flag and optional error message
+ */
+declare function validateUserPosition(user: UserPosition): {
+    isValid: boolean;
+    error?: string;
+};
+/**
+ * Validate a POI object
+ * @param poi - POI to validate
+ * @returns Object with isValid flag and optional error message
+ */
+declare function validatePOI(poi: POI): {
+    isValid: boolean;
+    error?: string;
+};
+
+/**
+ * Convert speed between units
+ *
+ * @param value - Speed value to convert
+ * @param from - Source unit
+ * @param to - Target unit
+ * @returns Converted speed value
+ *
+ * @example
+ * convertSpeed(60, 'kmh', 'mps');  // Returns: 16.67 (approx)
+ * convertSpeed(10, 'mps', 'mph');  // Returns: 22.37 (approx)
+ */
+declare function convertSpeed(value: number, from: 'mps' | 'kmh' | 'mph', to: 'mps' | 'kmh' | 'mph'): number;
+
+export { type ApproachStatus, COMPASS_BOUNDARIES, type ClosestPointResult, type CompassOrientation, type ConeFilter, type Coordinates, type DetailedOrientation, EARTH_RADIUS_METERS, type ETAResult, ORIENTATION_THRESHOLDS, type POI, type POIWithRelativePosition, type ProximityFilter, type RelativePosition, STATIONARY_SPEED_THRESHOLD, type SimpleOrientation, type SortConfig, type SpeedUnit, type UserPosition, clamp, convertSpeed, destinationPoint, filterByCone, filterByOrientation, filterByProximity, filterInsidePOIs, formatDistance, formatDuration, formatDurationShort, getBearing, getClosestPoint, getCompassOrientation, getDetailedOrientation, getDistance, getDistanceKm, getDistanceToEdge, getETA, getFinalBearing, getNearestPOIs, getNextArrivals, getOrientationDescription, getRelativeBearing, getRelativePosition, getSimpleETA, getSimpleOrientation, isValidBearing, isValidCoordinates, isValidRadius, isValidSpeed, isWithinPOI, normalizeAngle, normalizeLongitude, roundTo, sortByDistance, toDegrees, toRadians, validatePOI, validateUserPosition };