Merge branch 'master' into fix/h1-crc-buffer-web-apis

Author: makrsmark

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.

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.

lib/DateTimeUtils.test.ts

@@ -0,0 +1,25 @@
+import { DateTimeUtils } from './DateTimeUtils';
+
+describe('DateTimeUtils.UTCDateTimeToString', () => {
+  it('decodes a DDMMYY date with the ACARS 1-12 month convention', () => {
+    // ACARS "150226" = day 15, month 02 (Feb), year 26 -> 15 Feb 2026
+    const out = DateTimeUtils.UTCDateTimeToString('150226', '1230');
+    expect(out).toContain('Feb');
+    expect(out).toContain('15');
+    expect(out).toContain('2026');
+  });
+
+  it('parses DDMMYY = 280226 as 28 Feb 2026, not a later month', () => {
+    // ACARS month 02 must map to JS month 1 (February). Before the fix,
+    // passing the raw digit 2 to setUTCMonth produced March. Assert the
+    // returned UTC string matches the canonical Date.UTC value directly.
+    const out = DateTimeUtils.UTCDateTimeToString('280226', '1230');
+    const expected = new Date(Date.UTC(2026, 1, 28, 12, 30, 0)).toUTCString();
+    expect(out).toBe(expected);
+  });
+
+  it('handles a six-digit time with seconds', () => {
+    const out = DateTimeUtils.UTCDateTimeToString('150226', '123045');
+    expect(out).toContain('12:30:45');
+  });
+});

lib/DateTimeUtils.ts

@@ -9,25 +9,20 @@ export class DateTimeUtils {
   // Expects a six digit date string and a four digit UTC time string
   // (DDMMYY) (HHMM)
   public static UTCDateTimeToString(dateString: string, timeString: string) {
-    let utcDate = new Date();
-    utcDate.setUTCDate(+dateString.substr(0, 2));
-    utcDate.setUTCMonth(+dateString.substr(2, 2));
-    if (dateString.length === 6) {
-      utcDate.setUTCFullYear(2000 + +dateString.substr(4, 2));
-    }
-    if (timeString.length === 6) {
-      utcDate.setUTCHours(
-        +timeString.substr(0, 2),
-        +timeString.substr(2, 2),
-        +timeString.substr(4, 2),
-      );
-    } else {
-      utcDate.setUTCHours(
-        +timeString.substr(0, 2),
-        +timeString.substr(2, 2),
-        0,
-      );
-    }
+    const day = +dateString.substr(0, 2);
+    // ACARS month is 1-12; JS Date months are 0-11, so subtract one.
+    const month = +dateString.substr(2, 2) - 1;
+    const year =
+      dateString.length === 6
+        ? 2000 + +dateString.substr(4, 2)
+        : new Date().getUTCFullYear();
+    const hours = +timeString.substr(0, 2);
+    const minutes = +timeString.substr(2, 2);
+    const seconds = timeString.length === 6 ? +timeString.substr(4, 2) : 0;
+    // Build the date in one call so an incremental setUTC* on a Date that
+    // was initialised to "now" can't roll the month forward when the
+    // current real-world day is later than the last day of the target.
+    const utcDate = new Date(Date.UTC(year, month, day, hours, minutes, seconds));
     return utcDate.toUTCString();
   }
 

lib/MessageDecoder.labelindex.test.ts

@@ -109,6 +109,41 @@ describe('MessageDecoder label index', () => {
     expect(result.decoder.name).toBe('catch-all');
   });
 
+  test('wildcard registration order is preserved across existing label buckets', () => {
+    // Regression test: when a wildcard plugin is registered AFTER a label
+    // bucket has already been created, it must be inserted at the end of
+    // the wildcard section, not at the front. Otherwise later-registered
+    // wildcards would incorrectly take precedence over earlier ones for
+    // labels that already had buckets, and wildcard order would diverge
+    // from buckets created later (which seed from wildcardEntries.slice()).
+    const decoder = new MessageDecoder();
+
+    // 1. Register a label-specific plugin for '99' — this creates a
+    //    bucket with no wildcards yet (existing wildcards from the
+    //    constructor are in, but that's fine; we only care about the
+    //    relative order of stubs registered here).
+    const labelSpecific = new StubPlugin(decoder, 'label-99-specific', ['99']);
+    decoder.registerPlugin(labelSpecific);
+
+    // 2. Register two new wildcard stubs in order.
+    const firstWildcard = new StubPlugin(decoder, 'wild-first', ['*']);
+    decoder.registerPlugin(firstWildcard);
+    const secondWildcard = new StubPlugin(decoder, 'wild-second', ['*']);
+    decoder.registerPlugin(secondWildcard);
+
+    // 3. For a label-99 message, the first-registered wildcard must run
+    //    before the second-registered wildcard. Since both succeed, the
+    //    decoder.name tells us which one won the race.
+    const result = decoder.decode({ label: '99', text: 'anything' });
+    expect(result.decoded).toBe(true);
+    expect(result.decoder.name).toBe('wild-first');
+
+    // 4. The same ordering must hold for a brand-new label that didn't
+    //    have a bucket yet (it gets seeded from wildcardEntries.slice()).
+    const newLabel = decoder.decode({ label: 'ZZ', text: 'anything' });
+    expect(newLabel.decoder.name).toBe('wild-first');
+  });
+
   test('preamble-based plugins only match correct preambles', () => {
     const decoder = new MessageDecoder();
     const stub = new StubPlugin(

lib/MessageDecoder.ts

@@ -80,15 +80,27 @@ const pluginClasses = [
   Plugins.Label_QS,
 ];
 
+/**
+ * Per-plugin metadata captured at registration time so that decode() can
+ * avoid re-invoking plugin.qualifiers() (and re-allocating its arrays) on
+ * every message.
+ */
+interface PluginEntry {
+  plugin: DecoderPluginInterface;
+  preambles: string[] | undefined;
+}
+
 export class MessageDecoder {
   name: string;
   plugins: Array<DecoderPluginInterface>;
   debug: boolean;
 
-  /** Maps a label string to the plugins registered for it, preserving registration order. */
-  private labelIndex: Map<string, DecoderPluginInterface[]> = new Map();
-  /** Plugins that match all labels (qualifier label '*'). */
-  private wildcardPlugins: DecoderPluginInterface[] = [];
+  /** Maps a label string to the candidate entries (wildcard + label-specific) in registration order. */
+  private candidatesByLabel: Map<string, PluginEntry[]> = new Map();
+  /** Wildcard entries (plugins that register the '*' label). */
+  private wildcardEntries: PluginEntry[] = [];
+  /** Membership set for wildcard entries to dedupe when a plugin also registers a specific label. */
+  private wildcardSet: Set<DecoderPluginInterface> = new Set();
 
   constructor() {
     this.name = 'acars-decoder-typescript';
@@ -104,47 +116,59 @@ export class MessageDecoder {
     this.plugins.push(plugin);
 
     const qualifiers = plugin.qualifiers();
+    const entry: PluginEntry = {
+      plugin,
+      preambles:
+        qualifiers.preambles && qualifiers.preambles.length > 0
+          ? qualifiers.preambles
+          : undefined,
+    };
+
     for (const label of qualifiers.labels) {
       if (label === '*') {
-        this.wildcardPlugins.push(plugin);
+        if (!this.wildcardSet.has(plugin)) {
+          this.wildcardEntries.push(entry);
+          this.wildcardSet.add(plugin);
+          // Insert the new wildcard at the end of the wildcard section
+          // in every existing label bucket so that wildcard plugins are
+          // still tried before label-specific ones while preserving
+          // registration order among wildcard plugins (matching how new
+          // buckets are seeded via wildcardEntries.slice() below).
+          const wildcardInsertIndex = this.wildcardEntries.length - 1;
+          for (const bucket of this.candidatesByLabel.values()) {
+            bucket.splice(wildcardInsertIndex, 0, entry);
+          }
+        }
       } else {
-        let bucket = this.labelIndex.get(label);
+        let bucket = this.candidatesByLabel.get(label);
         if (!bucket) {
-          bucket = [];
-          this.labelIndex.set(label, bucket);
+          // Seed new bucket with all wildcard entries (in registration order)
+          // so they remain ahead of label-specific plugins.
+          bucket = this.wildcardEntries.slice();
+          this.candidatesByLabel.set(label, bucket);
+        }
+        // Skip if this plugin is a wildcard plugin already in the bucket.
+        if (!this.wildcardSet.has(plugin)) {
+          bucket.push(entry);
         }
-        bucket.push(plugin);
       }
     }
 
     return true;
   }
 
   decode(message: Message, options: Options = {}): DecodeResult {
-    // Build candidate list: wildcard plugins first (e.g. CBand wrapper),
-    // then label-specific plugins, preserving registration order.
-    // Use a Set to prevent duplicate execution if a plugin registers both '*' and a specific label.
-    const labelPlugins = this.labelIndex.get(message.label) ?? [];
-    const seen = new Set<DecoderPluginInterface>();
-    const candidates: DecoderPluginInterface[] = [];
-    for (const plugin of [...this.wildcardPlugins, ...labelPlugins]) {
-      if (!seen.has(plugin)) {
-        seen.add(plugin);
-        candidates.push(plugin);
-      }
-    }
-
-    const usablePlugins = candidates.filter((plugin) => {
-      const preambles = plugin.qualifiers().preambles;
-      if (!preambles || preambles.length === 0) {
-        return true;
-      }
-      return preambles.some((p: string) => message.text.startsWith(p));
-    });
+    const text = message.text;
+    const candidates =
+      this.candidatesByLabel.get(message.label) ?? this.wildcardEntries;
 
     if (options.debug) {
       console.log('Usable plugins');
-      console.log(usablePlugins);
+      console.log(
+        candidates
+          .filter((e) => this.matchesPreambles(text, e.preambles))
+          .map((e) => e.plugin),
+      );
     }
 
     let result: DecodeResult = {
@@ -157,7 +181,7 @@ export class MessageDecoder {
       },
       message: message,
       remaining: {
-        text: message.text,
+        text: text,
       },
       raw: {},
       formatted: {
@@ -166,9 +190,12 @@ export class MessageDecoder {
       },
     };
 
-    for (let i = 0; i < usablePlugins.length; i++) {
-      const plugin = usablePlugins[i];
-      result = plugin.decode(message, options);
+    for (let i = 0; i < candidates.length; i++) {
+      const entry = candidates[i];
+      if (!this.matchesPreambles(text, entry.preambles)) {
+        continue;
+      }
+      result = entry.plugin.decode(message, options);
       if (result.decoded) {
         break;
       }
@@ -181,4 +208,19 @@ export class MessageDecoder {
 
     return result;
   }
+
+  private matchesPreambles(
+    text: string,
+    preambles: string[] | undefined,
+  ): boolean {
+    if (!preambles) {
+      return true;
+    }
+    for (let i = 0; i < preambles.length; i++) {
+      if (text.startsWith(preambles[i])) {
+        return true;
+      }
+    }
+    return false;
+  }
 }

lib/plugins/ARINC_702.test.ts

@@ -0,0 +1,62 @@
+import { MessageDecoder } from '../MessageDecoder';
+import { Arinc702 } from './ARINC_702';
+
+describe('ARINC_702 wildcard wrapper', () => {
+  let plugin: Arinc702;
+  const message = { label: 'H1', text: '' };
+
+  beforeEach(() => {
+    const decoder = new MessageDecoder();
+    plugin = new Arinc702(decoder);
+  });
+
+  test('matches wildcard qualifier', () => {
+    expect(plugin.qualifiers()).toEqual({ labels: ['*'] });
+    expect(plugin.name).toBe('arinc-702');
+  });
+
+  test('strips embedded CR/LF before delegating to the H1 helper', () => {
+    // Inserting newlines into a known-good H1 REQ POS payload should not
+    // prevent it from being decoded.
+    message.text = 'REQ\nPOS\r037B';
+    const result = plugin.decode(message);
+
+    expect(result.decoded).toBe(true);
+    expect(result.decoder.decodeLevel).toBe('full');
+    expect(result.raw.checksum).toBe(0x037b);
+    expect(result.formatted.description).toBe('Request for Position Report');
+  });
+
+  test('peels a leading / header before delegating', () => {
+    // /HDQDLUA.<H1 message body>
+    message.text = '/HDQDLUA.REQPOS037B';
+    const result = plugin.decode(message);
+
+    expect(result.decoded).toBe(true);
+    // The delegated H1 body must actually be decoded — assert the
+    // REQ POS fields landed in the result, proving the '/HDQDLUA.'
+    // prefix was peeled before delegation.
+    expect(result.formatted.description).toBe('Request for Position Report');
+    expect(result.raw.checksum).toBe(0x037b);
+    // The unparsed header also ends up in remaining text.
+    expect(result.remaining.text).toContain('/HDQDLUA');
+  });
+
+  test('returns not-decoded when nothing matches', () => {
+    message.text = 'totally bogus payload that no H1 rule matches';
+    const result = plugin.decode(message);
+
+    expect(result.decoded).toBe(false);
+    expect(result.decoder.decodeLevel).toBe('none');
+    // The full original text should be present in the remaining text the
+    // wrapper accumulates (the wrapper may also emit prefix fragments).
+    expect(result.remaining.text).toContain(message.text);
+  });
+
+  test('end-to-end via MessageDecoder routes ARINC 702 wildcard for H1', () => {
+    const decoder = new MessageDecoder();
+    const result = decoder.decode({ label: 'H1', text: 'REQPOS037B' });
+    expect(result.decoded).toBe(true);
+    expect(result.formatted.description).toBe('Request for Position Report');
+  });
+});