@airframes/acars-decoder 1.8.13 → 1.9.0

package/License.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Airframes contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,7 @@
-# Node.js Support Policy
-
-- Runtime support: Node.js >= 18
-- Development and CI: validated on Node 18.x, 20.x, 22.x, and 24.x
-- TypeScript development uses the latest stable Node types (currently v24) without forcing consumers to use a specific Node types version, since `@types/node` is a devDependency.
-- The published builds are compiled targeting Node 18 runtime via `tsup` so they remain compatible across supported Node versions.
-
-# @airframes/acars-decoder
-
-This is a no-op documentation tweak to verify repository access, build/lint, tests, and PR workflow. No functional code changes are included.
-
 # acars-decoder-typescript
 
 [![NPM Version](https://badge.fury.io/js/@airframes%2Facars-decoder.svg)](https://badge.fury.io/js/@airframes%2Facars-decoder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./License.md)
 [![GitHub Actions Workflow Status](https://github.com/airframesio/acars-decoder-typescript/actions/workflows/yarn-test.yml/badge.svg)
 ](https://github.com/airframesio/acars-decoder-typescript/actions/workflows/yarn-test.yml)
 ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/airframesio/acars-decoder-typescript?utm_source=oss&utm_medium=github&utm_campaign=airframesio%2Facars-decoder-typescript&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
@@ -27,6 +17,13 @@ It has been written in TypeScript (which compiles to Javascript) and is publishe
 
 You are welcome to contribute (please see https://github.com/airframesio/acars-message-documentation where we collaborate to research and document the various types of messages), and while it was primarily developed to power [Airframes](https://app.airframes.io) and [AcarsHub](https://sdr-e.com/docker-acarshub), you may use this library in your own applications freely.
 
+# Node.js Support Policy
+
+- Runtime support: Node.js >= 18
+- Development and CI: validated on Node 18.x, 20.x, 22.x, and 24.x
+- TypeScript development uses the latest stable Node types (currently v24) without forcing consumers to use a specific Node types version, since `@types/node` is a devDependency.
+- The published builds are compiled targeting Node 18 runtime via `tsup` so they remain compatible across supported Node versions.
+
 # Installation
 
 Add the `@airframes/acars-decoder` library to your JavaScript or TypeScript project.

package/dist/index.d.mts

@@ -6,6 +6,70 @@ declare class IcaoDecoder {
     isMilitary(): boolean;
 }
 
+/**
+ * Represenation of a waypoint.
+ *
+ * Usually used in Routes which is an array of waypoints.
+ * Airways/Jetways can also be represented as a waypoint, by just the name.
+ * There is no distinction between the two currently because there is no difference from the current messages
+ * Distinction must be determined from tne name.
+ * In the event that a waypoint is a GPS position, the name can be the raw position string (N12345W012345)
+ */
+interface Waypoint {
+    /** unique identifier of the waypoint*/
+    name: string;
+    /**
+     * latitude in decimal degrees
+     *
+     * if set, longitude must be provided
+     */
+    latitude?: number;
+    /** longitude in decimal degrees
+     *
+     * if set, latitude must be provided
+     */
+    longitude?: number;
+    /**
+     * time of arrival. If in future, it is an ETA.
+     */
+    time?: number;
+    /**
+     * offset from the actual waypoint
+     *
+     * bearing: degrees from the waypoint
+     * distance: distance in nautical miles
+     */
+    offset?: {
+        bearing: number;
+        distance: number;
+    };
+}
+
+/**
+ * Representation of a route
+ *
+ * Typically a list of waypoints, this can also be a named company route.
+ */
+interface Route {
+    /** optional name. If not set, `waypoints` is required */
+    name?: string;
+    /** optional runway */
+    runway?: string;
+    /** optional list of waypoints. If not set, `name` is required */
+    waypoints?: Waypoint[];
+}
+
+interface Wind {
+    waypoint: Waypoint;
+    flightLevel: number;
+    windDirection: number;
+    windSpeed: number;
+    temperature?: {
+        flightLevel: number;
+        degreesC: number;
+    };
+}
+
 /**
  * Representation of a Message
  */
@@ -20,6 +84,87 @@ interface Message {
 interface Options {
     debug?: boolean;
 }
+/**
+ * Known fields that can appear on DecodeResult.raw.
+ * The index signature allows plugin-specific fields without losing type safety
+ * on the well-known ones.
+ */
+interface RawFields {
+    position?: {
+        latitude: number;
+        longitude: number;
+    };
+    altitude?: number;
+    heading?: number;
+    groundspeed?: number;
+    airspeed?: number;
+    mach?: number;
+    flight_number?: string;
+    callsign?: string;
+    tail?: string;
+    departure_icao?: string;
+    departure_iata?: string;
+    arrival_icao?: string;
+    arrival_iata?: string;
+    alternate_icao?: string;
+    departure_runway?: string;
+    arrival_runway?: string;
+    alternate_runway?: string;
+    message_timestamp?: number;
+    eta_time?: number;
+    out_time?: number;
+    off_time?: number;
+    on_time?: number;
+    in_time?: number;
+    engine_start_time?: number;
+    engine_stop_time?: number;
+    day?: number | string;
+    month?: number;
+    departure_day?: number;
+    arrival_day?: number;
+    fuel_on_board?: number;
+    fuel_burned?: number;
+    fuel_remaining?: number;
+    fuel_in_tons?: number;
+    out_fuel?: number;
+    off_fuel?: number;
+    on_fuel?: number;
+    in_fuel?: number;
+    start_fuel?: number;
+    outside_air_temperature?: number;
+    total_air_temperature?: number;
+    center_of_gravity?: number;
+    cg_lower_limit?: number;
+    cg_upper_limit?: number;
+    mac?: number;
+    trim?: number;
+    route?: Route;
+    wind_data?: Wind[];
+    requested_alts?: number[];
+    desired_alt?: number;
+    start_point?: string;
+    route_number?: string;
+    flight_plan?: string;
+    label?: string;
+    sublabel?: string;
+    preamble?: string;
+    version?: number;
+    checksum_algorithm?: string;
+    checksum?: number;
+    sequence_number?: number;
+    sequence_response?: number;
+    ground_address?: string;
+    text?: string;
+    state_change?: {
+        from: string;
+        to: string;
+    };
+    door_event?: {
+        door: string;
+        state: string;
+    };
+    [key: string]: unknown;
+}
 /**
  * Results from decoding a message
  */
@@ -41,7 +186,7 @@ interface DecodeResult {
         }[];
     };
     message?: Message;
-    raw: any;
+    raw: RawFields;
     remaining: {
         text?: string;
     };
@@ -51,7 +196,7 @@ interface Qualifiers {
     preambles?: string[];
 }
 interface DecoderPluginInterface {
-    decode(message: Message): DecodeResult;
+    decode(message: Message, options?: Options): DecodeResult;
     meetsStateRequirements(): boolean;
     qualifiers(): Qualifiers;
 }
@@ -60,9 +205,16 @@ declare class MessageDecoder {
     name: string;
     plugins: Array<DecoderPluginInterface>;
     debug: boolean;
+    /** Maps a label string to the candidate entries (wildcard + label-specific) in registration order. */
+    private candidatesByLabel;
+    /** Wildcard entries (plugins that register the '*' label). */
+    private wildcardEntries;
+    /** Membership set for wildcard entries to dedupe when a plugin also registers a specific label. */
+    private wildcardSet;
     constructor();
     registerPlugin(plugin: DecoderPluginInterface): boolean;
     decode(message: Message, options?: Options): DecodeResult;
+    private matchesPreambles;
 }
 
 export { IcaoDecoder, MessageDecoder };

package/dist/index.d.ts

@@ -6,6 +6,70 @@ declare class IcaoDecoder {
     isMilitary(): boolean;
 }
 
+/**
+ * Represenation of a waypoint.
+ *
+ * Usually used in Routes which is an array of waypoints.
+ * Airways/Jetways can also be represented as a waypoint, by just the name.
+ * There is no distinction between the two currently because there is no difference from the current messages
+ * Distinction must be determined from tne name.
+ * In the event that a waypoint is a GPS position, the name can be the raw position string (N12345W012345)
+ */
+interface Waypoint {
+    /** unique identifier of the waypoint*/
+    name: string;
+    /**
+     * latitude in decimal degrees
+     *
+     * if set, longitude must be provided
+     */
+    latitude?: number;
+    /** longitude in decimal degrees
+     *
+     * if set, latitude must be provided
+     */
+    longitude?: number;
+    /**
+     * time of arrival. If in future, it is an ETA.
+     */
+    time?: number;
+    /**
+     * offset from the actual waypoint
+     *
+     * bearing: degrees from the waypoint
+     * distance: distance in nautical miles
+     */
+    offset?: {
+        bearing: number;
+        distance: number;
+    };
+}
+
+/**
+ * Representation of a route
+ *
+ * Typically a list of waypoints, this can also be a named company route.
+ */
+interface Route {
+    /** optional name. If not set, `waypoints` is required */
+    name?: string;
+    /** optional runway */
+    runway?: string;
+    /** optional list of waypoints. If not set, `name` is required */
+    waypoints?: Waypoint[];
+}
+
+interface Wind {
+    waypoint: Waypoint;
+    flightLevel: number;
+    windDirection: number;
+    windSpeed: number;
+    temperature?: {
+        flightLevel: number;
+        degreesC: number;
+    };
+}
+
 /**
  * Representation of a Message
  */
@@ -20,6 +84,87 @@ interface Message {
 interface Options {
     debug?: boolean;
 }
+/**
+ * Known fields that can appear on DecodeResult.raw.
+ * The index signature allows plugin-specific fields without losing type safety
+ * on the well-known ones.
+ */
+interface RawFields {
+    position?: {
+        latitude: number;
+        longitude: number;
+    };
+    altitude?: number;
+    heading?: number;
+    groundspeed?: number;
+    airspeed?: number;
+    mach?: number;
+    flight_number?: string;
+    callsign?: string;
+    tail?: string;
+    departure_icao?: string;
+    departure_iata?: string;
+    arrival_icao?: string;
+    arrival_iata?: string;
+    alternate_icao?: string;
+    departure_runway?: string;
+    arrival_runway?: string;
+    alternate_runway?: string;
+    message_timestamp?: number;
+    eta_time?: number;
+    out_time?: number;
+    off_time?: number;
+    on_time?: number;
+    in_time?: number;
+    engine_start_time?: number;
+    engine_stop_time?: number;
+    day?: number | string;
+    month?: number;
+    departure_day?: number;
+    arrival_day?: number;
+    fuel_on_board?: number;
+    fuel_burned?: number;
+    fuel_remaining?: number;
+    fuel_in_tons?: number;
+    out_fuel?: number;
+    off_fuel?: number;
+    on_fuel?: number;
+    in_fuel?: number;
+    start_fuel?: number;
+    outside_air_temperature?: number;
+    total_air_temperature?: number;
+    center_of_gravity?: number;
+    cg_lower_limit?: number;
+    cg_upper_limit?: number;
+    mac?: number;
+    trim?: number;
+    route?: Route;
+    wind_data?: Wind[];
+    requested_alts?: number[];
+    desired_alt?: number;
+    start_point?: string;
+    route_number?: string;
+    flight_plan?: string;
+    label?: string;
+    sublabel?: string;
+    preamble?: string;
+    version?: number;
+    checksum_algorithm?: string;
+    checksum?: number;
+    sequence_number?: number;
+    sequence_response?: number;
+    ground_address?: string;
+    text?: string;
+    state_change?: {
+        from: string;
+        to: string;
+    };
+    door_event?: {
+        door: string;
+        state: string;
+    };
+    [key: string]: unknown;
+}
 /**
  * Results from decoding a message
  */
@@ -41,7 +186,7 @@ interface DecodeResult {
         }[];
     };
     message?: Message;
-    raw: any;
+    raw: RawFields;
     remaining: {
         text?: string;
     };
@@ -51,7 +196,7 @@ interface Qualifiers {
     preambles?: string[];
 }
 interface DecoderPluginInterface {
-    decode(message: Message): DecodeResult;
+    decode(message: Message, options?: Options): DecodeResult;
     meetsStateRequirements(): boolean;
     qualifiers(): Qualifiers;
 }
@@ -60,9 +205,16 @@ declare class MessageDecoder {
     name: string;
     plugins: Array<DecoderPluginInterface>;
     debug: boolean;
+    /** Maps a label string to the candidate entries (wildcard + label-specific) in registration order. */
+    private candidatesByLabel;
+    /** Wildcard entries (plugins that register the '*' label). */
+    private wildcardEntries;
+    /** Membership set for wildcard entries to dedupe when a plugin also registers a specific label. */
+    private wildcardSet;
     constructor();
     registerPlugin(plugin: DecoderPluginInterface): boolean;
     decode(message: Message, options?: Options): DecodeResult;
+    private matchesPreambles;
 }
 
 export { IcaoDecoder, MessageDecoder };