flight-planner/dist/planner.d.ts

Plan and route VFR flights

import { Advisory, AerodromeService, AircraftService, WeatherService } from './index.js';
import { Aerodrome, ReportingPoint, Waypoint } from './waypoint.types.js';
import { Wind } from './metar.types.js';
import { Aircraft } from './aircraft.js';
/**
 * Represents a course vector with distance and track.
 *
 * @interface CourseVector
 * @property {number} distance - The distance of the course vector in nautical miles.
 * @property {number} track - The true track heading in degrees.
 * @property {number} magneticTrack - The magnetic track heading in degrees, if available.
 */
export interface CourseVector {
    distance: number;
    track: number;
    magneticTrack: number;
}
/**
 * Interface representing the performance characteristics of an aircraft.
 *
 * @interface RouteLegPerformance
 * @property {number} headWind - The component of wind directly opposing the aircraft's motion, measured in knots.
 * @property {number} crossWind - The component of wind perpendicular to the aircraft's motion, measured in knots.
 * @property {number} trueAirspeed - The speed of the aircraft relative to the air mass it's flying through, measured in knots.
 * @property {number} windCorrectionAngle - The angle between the aircraft's heading and its track, measured in degrees.
 * @property {number} trueHeading - The heading of the aircraft relative to true north, measured in degrees.
 * @property {number} magneticHeading - The heading of the aircraft corrected for magnetic declination, measured in degrees.
 * @property {number} groundSpeed - The actual speed of the aircraft over the ground, measured in knots.
 * @property {number} duration - The time duration for a segment of flight, typically measured in minutes.
 * @property {number} [fuelConsumption] - Optional property representing the fuel consumption rate, typically measured in gallons or liters per hour.
 */
export interface RouteLegPerformance {
    headWind: number;
    crossWind: number;
    trueAirspeed: number;
    windCorrectionAngle: number;
    trueHeading: number;
    magneticHeading: number;
    groundSpeed: number;
    duration: number;
    fuelConsumption?: number;
}
/**
 * Represents a segment of a flight route between two waypoints.
 *
 * @interface RouteLeg
 * @property {RouteSegment} start - The starting waypoint of the leg.
 * @property {RouteSegment} end - The ending waypoint of the leg.
 * @property {CourseVector} course - The course vector of the leg, containing distance and track information.
 * @property {Wind} [wind] - Optional wind conditions for this leg.
 * @property {Date | undefined} arrivalDate - The estimated arrival date and time at the end waypoint.
 * @property {AircraftPerformance} [performance] - Optional performance calculations for this leg.
 */
export interface RouteLeg {
    start: RouteSegment;
    end: RouteSegment;
    course: CourseVector;
    wind?: Wind;
    arrivalDate?: Date;
    performance?: RouteLegPerformance;
}
/**
 * Represents a complete route trip with multiple legs.
 * Contains information about the route's path, distances, duration, and optionally fuel consumption and timing.
 *
 * @interface RouteTrip
 * @property {RouteLeg[]} route - Array of route legs that make up the complete trip
 * @property {RouteLeg} [routeAlternate] - Optional alternate route leg for the trip
 * @property {number} totalDistance - Total distance of the trip in nautical miles
 * @property {number} totalDuration - Total duration of the trip in minutes
 * @property {number} [totalTripFuel] - Optional total fuel consumption for the trip in gallons or liters
 * @property {Date} [departureDate] - Optional planned departure date and time
 * @property {Date} [arrivalDate] - Optional estimated arrival date and time
 * @property {Date} generatedAt - The date and time when the trip was generated
 * @property {string} [remarks] - Optional remarks or notes about the trip
 */
export interface RouteTrip {
    route: RouteLeg[];
    routeAlternate?: RouteLeg;
    totalDistance: number;
    totalDuration: number;
    totalTripFuel?: number;
    fuelBreakdown?: {
        trip: number;
        reserve: number;
        takeoff?: number;
        landing?: number;
        taxi?: number;
        alternate?: number;
    };
    departureDate?: Date;
    arrivalDate?: Date;
    generatedAt: Date;
    remarks?: string;
}
/**
 * Options for configuring a flight route.
 *
 * @interface RouteOptions
 * @property {number} [defaultAltitude] - The default altitude for the route in feet.
 * @property {Date} [departureDate] - The scheduled departure date and time.
 * @property {Aircraft} [aircraft] - The aircraft to be used for the flight.
 * @property {Aerodrome} [alternate] - An alternate aerodrome for the flight plan.
 * @property {number} [reserveFuel] - The amount of reserve fuel to carry in liters.
 * @property {number} [reserveFuelDuration] - The duration for which reserve fuel is calculated in minutes.
 * @property {number} [taxiFuel] - The amount of fuel required for taxiing liters.
 * @property {number} [takeoffFuel] - The amount of fuel required for takeoff in liters.
 * @property {number} [landingFuel] - The amount of fuel required for landing in liters.
 */
export interface RouteOptions {
    defaultAltitude?: number;
    departureDate?: Date;
    aircraft?: Aircraft;
    alternate?: Aerodrome;
    alternateRadius?: number;
    reserveFuel?: number;
    reserveFuelDuration?: number;
    taxiFuel?: number;
    takeoffFuel?: number;
    landingFuel?: number;
}
/**
 * Represents the possible types for a waypoint in a route.
 * Can be an Aerodrome, a ReportingPoint, or a generic Waypoint.
 */
type WaypointType = Aerodrome | ReportingPoint | Waypoint;
/**
 * Represents a segment of a flight route, containing a waypoint and optional altitude.
 *
 * @interface RouteSegment
 * @property {WaypointType} waypoint - The waypoint for this segment, which can be an Aerodrome, ReportingPoint, or Waypoint.
 * @property {number} [altitude] - Optional altitude for the segment in feet.
 */
interface RouteSegment {
    waypoint: WaypointType;
    altitude?: number;
}
/**
 * Checks if a given track is eastbound (0-179 degrees).
 *
 * @param {number} track - The track in degrees.
 * @returns {boolean} True if the track is eastbound, false otherwise.
 */
export declare const isEastbound: (track: number) => boolean;
/**
 * Checks if a given track is westbound (180-359 degrees).
 *
 * @param {number} track - The track in degrees.
 * @returns {boolean} True if the track is westbound, false otherwise.
 */
export declare const isWestbound: (track: number) => boolean;
/**
 * Calculates the appropriate VFR cruising altitude based on the track and desired minimum altitude.
 *
 * Eastbound flights (0-179 degrees) use odd thousands + 500 feet (e.g., 3500, 5500).
 * Westbound flights (180-359 degrees) use even thousands + 500 feet (e.g., 4500, 6500).
 * The function returns the lowest VFR cruising altitude that is at or above the given minimum altitude.
 *
 * @param {number} track - The true track in degrees.
 * @param {number} altitude - The minimum desired altitude in feet.
 * @returns {number} The calculated VFR cruising altitude in feet.
 */
export declare const calculateVFRCruisingAltitude: (track: number, altitude: number) => number;
/**
 * Converts an altitude in feet to the corresponding flight level.
 * Flight levels are typically expressed in hundreds of feet, so the function divides the altitude by 1000.
 *
 * @param {number} altitude - The altitude in feet.
 * @returns {number} The flight level (FL) corresponding to the given altitude.
 */
export declare const flightLevel: (altitude: number) => number;
/**
 * Finds the closest route leg to a given location.
 *
 * @param routeTrip - The route trip to search within.
 * @param location - The location to find the closest leg to, as a [longitude, latitude] tuple.
 * @returns The closest route leg, or undefined if no route legs are found or the input is invalid.
 */
export declare const closestRouteLeg: (routeTrip: RouteTrip, location: [number, number]) => RouteLeg | undefined;
/**
 * Finds the closest waypoint in a route trip to a given location.
 *
 * @param routeTrip - The route trip to search within.
 * @param location - The location to find the closest waypoint to, as a [longitude, latitude] tuple.
 * @returns The closest waypoint, or undefined if no waypoints are found or the input is invalid.
 */
export declare const closestWaypoint: (routeTrip: RouteTrip, location: [number, number]) => WaypointType | undefined;
/**
 * Maps a route trip to an array of unique waypoints.
 *
 * This function extracts all waypoints from a route trip by taking the start and end
 * waypoints of each leg and removing duplicates.
 *
 * @param routeTrip - The route trip containing legs with start and end waypoints
 * @returns An array of unique waypoints representing all points in the route trip
 */
export declare const routeTripWaypoints: (routeTrip: RouteTrip) => WaypointType[];
/**
 * Gets the departure waypoint from a route trip.
 *
 * @param routeTrip - The route trip from which to extract the departure waypoint
 * @returns The departure waypoint, which is the first waypoint in the route
 */
export declare const routeTripDepartureWaypoint: (routeTrip: RouteTrip) => WaypointType;
/**
 * Gets the arrival waypoint from a route trip.
 *
 * @param routeTrip - The route trip from which to extract the arrival waypoint
 * @returns The arrival waypoint, which is the last waypoint in the route
 */
export declare const routeTripArrivalWaypoint: (routeTrip: RouteTrip) => WaypointType;
/**
 * Parses a route string into an array of waypoints.
 *
 * This function accepts a route string containing various waypoint formats and converts them
 * into standardized waypoint objects. It supports ICAO airport codes and coordinate-based waypoints.
 *
 * @async
 * @function parseRouteString
 * @param {AerodromeService} aerodromeService - Service for looking up aerodrome information by ICAO codes
 * @param {string} routeString - The route string to parse, containing waypoints separated by spaces, semicolons, or newlines
 * @returns {Promise<WaypointType[]>} A promise that resolves to an array of parsed waypoints
 *
 * @description
 * Supported waypoint formats:
 * - ICAO codes: 4-letter airport identifiers (e.g., "KJFK", "EGLL")
 * - Coordinate waypoints: WP(latitude,longitude) format (e.g., "WP(40.7128,-74.0060)")
 *
 * The function performs the following operations:
 * 1. Splits the route string by whitespace, semicolons, and newlines
 * 2. Filters out empty parts
 * 3. Converts all input to uppercase for consistency
 * 4. For each part, attempts to match against supported formats:
 *    - If ICAO code: looks up aerodrome using the provided service
 *    - If coordinate waypoint: creates a waypoint with the specified coordinates
 * 5. Collects parsing errors and throws if no valid waypoints are found
 *
 * @throws {Error} Throws an error if the route string cannot be parsed or contains no valid waypoints
 */
export declare const parseRouteString: (aerodromeService: AerodromeService, routeString: string) => Promise<WaypointType[]>;
/**
 * Creates a flight plan from a route string, aircraft registration, and optional route options.
 *
 * This function parses the route string into waypoints, attaches weather data, finds an alternate aerodrome if not provided,
 * and constructs a flight plan with segments and performance calculations.
 *
 * @param planner - The PlannerService instance used for parsing and finding waypoints.
 * @param routeString - The route string to parse into waypoints.
 * @param aircraftRegistration - The registration of the aircraft to be used in the flight plan.
 * @param options - Optional parameters for the flight plan, including default altitude, departure date, and reserve fuel.
 * @returns A promise that resolves to a RouteTrip object representing the flight plan.
 */
export declare function createFlightPlanFromString(weatherService: WeatherService, aerodromeService: AerodromeService, aircrafService: AircraftService, routeString: string, aircraftRegistration: string, options?: RouteOptions): Promise<RouteTrip & {
    advisory?: Advisory[];
}>;
/**
 * Generates a flight plan based on the provided route segments, alternate segment, aircraft, and options.
 *
 * This function calculates the route legs, total distance, duration, fuel consumption, and other performance metrics.
 * It returns a RouteTrip object containing all relevant information about the flight plan.
 *
 * @param segments - An array of RouteSegment objects representing the waypoints and altitudes for the flight.
 * @param alternateSegment - An optional RouteSegment representing an alternate aerodrome for the flight.
 * @param aircraft - The Aircraft object containing performance data for the flight.
 * @param options - Optional parameters for the flight plan, including departure date and reserve fuel duration.
 * @returns A RouteTrip object containing the calculated flight plan details.
 */
export declare function flightPlan(segments: RouteSegment[], alternateSegment: RouteSegment | undefined, aircraft: Aircraft | undefined, options?: RouteOptions): RouteTrip;
export {};