@saber-usa/node-common 1.7.35 → 1.7.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saber-usa/node-common",
-  "version": "1.7.35",
+  "version": "1.7.37",
   "description": "Common node functions for Saber",
   "main": "src/index.js",
   "type": "module",
@@ -23,13 +23,13 @@
   "author": "Saber USA",
   "license": "ISC",
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1092.0",
+    "@aws-sdk/client-s3": "^3.1119.0",
     "date-fns": "^4.4.0",
     "lodash": "4.18.1",
     "mathjs": "^15.2.0",
     "pious-squid": "^2.3.0",
     "plotly": "^1.0.6",
-    "satellite.js": "^7.0.1",
+    "satellite.js": "^7.1.0",
     "solar-calculator": "^0.3.0",
     "three": "^0.185.1",
     "winston": "3.19.0"
@@ -41,16 +41,17 @@
     "@jest/globals": "^30.4.1",
     "@sonar/scan": "^5.0.0",
     "cross-env": "^10.1.0",
-    "eslint": "^10.7.0",
-    "eslint-plugin-jest": "^29.15.5",
-    "globals": "^17.7.0",
+    "eslint": "^10.9.1",
+    "eslint-plugin-jest": "^29.16.2",
+    "globals": "^17.11.0",
     "jest": "^30.4.2",
     "jest-diff": "^30.4.1",
     "nodemon": "3.1.14"
   },
   "overrides": {
     "braces": "3.0.3",
-    "brace-expansion": "2.1.2",
+    "brace-expansion": "2.1.4",
+    "js-yaml": "3.15.2",
     "lodash": "4.18.1"
   }
 }

package/src/astro.js

@@ -40,6 +40,7 @@ import {DEG2RAD,
     REGIMES,
     GRAV_CONST,
     EARTH_MASS,
+    MU,
     WGS72_EARTH_EQUATORIAL_RADIUS_KM,
     WGS84_EARTH_EQUATORIAL_RADIUS_KM,
     MILLIS_PER_DAY,
@@ -48,6 +49,8 @@ import {DEG2RAD,
 import TLEValidator from "./tle/TLEValidator.js";
 import MultiLineTLEValidator from "./tle/MultiLineTLEValidator.js";
 import {TLE_ERRORS} from "./tle/tleErrors.js";
+import {TleParseUtils} from "./tle/TleParseUtils.js";
+import {OrbitUtils} from "./OrbitUtils.js";
 
 // Solar Terminator
 // Returns sun latitude and longitude as -180/180
@@ -145,24 +148,24 @@ const validateTle = (line1, line2) => {
  * @return {boolean} true if the propagation output is valid, false otherwise
  */
 const isPropagateValid = (out) => {
-    if (out === null || out === undefined) {
+    if (!isDefined(out)) {
         return false;
     }
 
     if (out.position) {
         const pos = out.position;
-        if (pos.x === null || pos.x === undefined || Number.isNaN(pos.x)
-            || pos.y === null || pos.y === undefined || Number.isNaN(pos.y)
-            || pos.z === null || pos.z === undefined || Number.isNaN(pos.z)) {
+        if (!isDefined(pos.x) || Number.isNaN(pos.x)
+            || !isDefined(pos.y) || Number.isNaN(pos.y)
+            || !isDefined(pos.z) || Number.isNaN(pos.z)) {
             return false;
         }
     }
 
     if (out.velocity) {
         const vel = out.velocity;
-        if (vel.x === null || vel.x === undefined || Number.isNaN(vel.x)
-            || vel.y === null || vel.y === undefined || Number.isNaN(vel.y)
-            || vel.z === null || vel.z === undefined || Number.isNaN(vel.z)) {
+        if (!isDefined(vel.x) || Number.isNaN(vel.x)
+            || !isDefined(vel.y) || Number.isNaN(vel.y)
+            || !isDefined(vel.z) || Number.isNaN(vel.z)) {
             return false;
         }
     }
@@ -308,6 +311,28 @@ const getLonAndDrift = (line1, line2, datetime) => {
     }
 };
 
+/**
+ * Orbital period in minutes from semi-major axis and gravitational parameter.
+ * @param {number} aKm Semi-major axis (km)
+ * @param {number} muKm3s2 Standard gravitational parameter (km³/s²)
+ * @return {number|null} Period in minutes, or null if a ≤ 0
+ */
+const orbitalPeriodMinutes = (aKm, muKm3s2) => {
+    const periodSec = OrbitUtils.getPeriod(aKm, muKm3s2);
+    return periodSec === null ? null : periodSec / 60;
+};
+
+/**
+ * Mean motion in revolutions per day from semi-major axis and gravitational parameter.
+ * @param {number} aKm Semi-major axis (km)
+ * @param {number} muKm3s2 Standard gravitational parameter (km³/s²)
+ * @return {number} Mean motion in rev/day
+ */
+const orbitalMeanMotionRevPerDay = (aKm, muKm3s2) => {
+    const nRadS = OrbitUtils.getMeanMotion(aKm, muKm3s2);
+    return nRadS * 86400 / (2 * Math.PI);
+};
+
 /**
  * Given eccentricity, inclination, meanmotion, and period
  * Calculates & returns type of orbit to include LEO, MEO, HEO, GEO Drifter, GEO Inclined,GEO Stationary, and undetermined if applicable
@@ -1391,7 +1416,7 @@ const GetElsetUdlFromTle = (
         // and we may be unsure of entering true or false for any reason.
         if (isBoolean(isUct)) {
             elset.uct = isUct;
-        } else if (isUct === null || isUct === undefined) {
+        } else if (!isDefined(isUct)) {
             // Do nothing, do not populate nor put null.
         } else {
             throw new Error("Input uct flag is not of type boolean.");
@@ -1423,7 +1448,7 @@ const GetElsetUdlFromTle = (
         const date = julianToGregorian(satrec.jdsatepoch);
         elset.epoch = date.toISOString();
 
-        elset.satNo = Number.parseInt(satrec.satnum);
+        elset.satNo = TleParseUtils.getSatnoFromTle(satrec.satnum);
 
         // Eccentricity
         elset.eccentricity = satrec.ecco;
@@ -1747,11 +1772,9 @@ const cartesianToElsetElements = (pv, epoch) => {
         ArgOfPerigee: kepl.w,
     };
 
-    // Mean motion in radians per second
-    const mu = 3.986004418e14; // (m^3)/(s^2) WGS-84 Earth Mu
-    const meanMotion = Math.sqrt(mu/Math.pow((elset.SemiMajorAxis*1000), 3));
-
-    elset.MeanMotion = meanMotion / (2*Math.PI) * 60 * 60 * 24; // rads/s to revs per day
+    const muKm3s2 = MU / 1e9;
+    elset.MeanMotion = orbitalMeanMotionRevPerDay(elset.SemiMajorAxis, muKm3s2);
+    elset.Period = orbitalPeriodMinutes(elset.SemiMajorAxis, muKm3s2);
 
     const trueAnomaly = kepl.f;
 
@@ -1762,7 +1785,6 @@ const cartesianToElsetElements = (pv, epoch) => {
     // Compute Mean Anomaly from Eccentric Anomaly and Eccentricity
     elset.MeanAnomaly = (E - (elset.Eccentricity)*Math.sin(E)) * RAD2DEG;
 
-    elset.Period = 2*Math.PI/meanMotion / 60; // period in minutes
     elset.Apogee = elset.SemiMajorAxis * (1 + elset.Eccentricity); // km
     elset.Perigee = elset.SemiMajorAxis * (1 - elset.Eccentricity); // km
 
@@ -3589,6 +3611,8 @@ export {
 } from "satellite.js";
 export {
     calcRegime,
+    orbitalPeriodMinutes,
+    orbitalMeanMotionRevPerDay,
     altToRegime,
     cartesianToRIC,
     angleBetween3DCoords,

package/src/index.js

@@ -11,6 +11,7 @@ export * from "./OrbitUtils.js";
 export * from "./PropagateUtils.js";
 export * from "./ballisticPropagator.js";
 export * from "./NodeVector3D.js";
+export * from "./tle/TleParseUtils.js";
 
 // UDL exports are grouped; re-export individually and as namespace if needed
 import * as udl from "./udl.js";
@@ -30,6 +31,7 @@ import * as OrbitUtilsNS from "./OrbitUtils.js";
 import * as PropagateUtilsNS from "./PropagateUtils.js";
 import * as ballisticPropagatorNS from "./ballisticPropagator.js";
 import * as NodeVector3DNS from "./NodeVector3D.js";
+import * as TleParseUtilsNS from "./tle/TleParseUtils.js";
 
 const aggregate = {
     ...loggerFactoryNS,
@@ -44,6 +46,7 @@ const aggregate = {
     ...PropagateUtilsNS,
     ...ballisticPropagatorNS,
     ...NodeVector3DNS,
+    ...TleParseUtilsNS,
     ...udl,
 };
 

package/src/tle/TLEValidator.js

@@ -1,12 +1,13 @@
 import {formatChecksumError, formatLengthError, TLE_ERRORS} from "./tleErrors.js";
+import {TleParseUtils} from "./TleParseUtils.js";
 
 /**
  * NORAD TLE line-pair validator.
  * Logic derived from whatswrongwithmytle.com (Dr. TS Kelso's field guide).
+ * Catalog-number grammar is owned by TleParseUtils (Alpha-5 aware).
  */
 class TLEValidator {
     constructor() {
-        this.lineOneRegexCatalogNumber = /[0-Z]{5}[CSU]/;
         this.lineOneRegexInternationalDesignator = / (\d{5}[A-Z][ A-Z]{2}|\d{5}[ A-Z]{2}[A-Z]| {8})/;
         this.lineOneRegexEpoch = / \d{5}\.\d{8}/;
         this.lineOneRegexDMeanMotion = / [ +-]\.\d{8}/;
@@ -15,7 +16,6 @@ class TLEValidator {
         this.lineOneRegexEphemType = / [0-5]/;
         this.lineOneRegexSetNumber = / [ \d]{3}\d/;
 
-        this.lineTwoRegexCatalogNumber = /[0-Z]{5}/;
         this.lineTwoRegexInclination = / [ \d]{3}\.\d{4}/;
         this.lineTwoRegexRAAN = / [ \d]{3}\.\d{4}/;
         this.lineTwoRegexEccentricity = / \d{7}/;
@@ -57,7 +57,8 @@ class TLEValidator {
         if (line.length < 69) {
             return formatLengthError(TLE_ERRORS.LINE1_LENGTH, line.length);
         }
-        if (!this.lineOneRegexCatalogNumber.test(line.slice(2, 8))) {
+        if (!TleParseUtils.isValidSatelliteNumberField(line.slice(2, 7))
+            || !/[CSU]/.test(line.slice(7, 8))) {
             return TLE_ERRORS.LINE1_CATALOG_NUMBER;
         }
         if (!this.lineOneRegexInternationalDesignator.test(line.slice(8, 17))) {
@@ -96,7 +97,7 @@ class TLEValidator {
         if (line.length < 69) {
             return formatLengthError(TLE_ERRORS.LINE2_LENGTH, line.length);
         }
-        if (!this.lineTwoRegexCatalogNumber.test(line.slice(2, 7))) {
+        if (!TleParseUtils.isValidSatelliteNumberField(line.slice(2, 7))) {
             return TLE_ERRORS.LINE2_CATALOG_NUMBER;
         }
         if (!this.lineTwoRegexInclination.test(line.slice(7, 16))) {

package/src/tle/TleParseUtils.js

@@ -0,0 +1,168 @@
+import {isDefined} from "../utils.js";
+
+/**
+ * Utility class for TLE parsing, including Alpha-5 TLE satellite IDs.
+ * Ported from org.orekit.propagation.analytical.tle.ParseUtils / TLE.
+ *
+ * Alpha-5 extends the range of existing 5-digit TLE satellite numbers
+ * by allowing the first digit to be an upper case letter, ignoring 'I'
+ * and 'O' to avoid confusion with numbers '1' and '0'.
+ *
+ * @see https://www.space-track.org/documentation#tle-alpha5
+ */
+export class TleParseUtils {
+    /** Maximum satellite number representable with 5 numeric digits. */
+    static MAX_NUMERIC_SATNUM = 99999;
+
+    /** Scaling factor for Alpha-5 numbers. */
+    static ALPHA5_SCALING = 10000;
+
+    /** Letter → number map for Alpha-5 satellite numbers. */
+    static ALPHA5_NUMBERS = new Map();
+
+    /** Number → letter map for Alpha-5 satellite numbers. */
+    static ALPHA5_LETTERS = new Map();
+
+    static {
+        const alpha5Letters = [
+            "A", "B", "C", "D", "E", "F", "G", "H", "J",
+            "K", "L", "M", "N", "P", "Q", "R", "S", "T",
+            "U", "V", "W", "X", "Y", "Z",
+        ];
+        for (let i = 0; i < alpha5Letters.length; ++i) {
+            TleParseUtils.ALPHA5_NUMBERS.set(alpha5Letters[i], i + 10);
+            TleParseUtils.ALPHA5_LETTERS.set(i + 10, alpha5Letters[i]);
+        }
+    }
+
+    /** Private constructor for a utility class. */
+    constructor() {
+        throw new Error("TleParseUtils is a utility class and cannot be instantiated");
+    }
+
+    /**
+     * True if token is a valid 5-char TLE catalog field:
+     * five digits, or Alpha-5 letter (no I/O) plus four digits.
+     * @param {string} token
+     * @return {boolean}
+     */
+    static isValidSatelliteNumberField(token) {
+        if (typeof token !== "string" || token.length !== 5) {
+            return false;
+        }
+        if (/^\d{5}$/.test(token)) {
+            return true;
+        }
+        if (!TleParseUtils.ALPHA5_NUMBERS.has(token.charAt(0))) {
+            return false;
+        }
+        return /^\d{4}$/.test(token.substring(1));
+    }
+
+    /**
+     * Stricter int parser: accepts an optional sign plus digits only, else throws.
+     * Unlike Number.parseInt, rejects partial parses (e.g. "12abc").
+     * @param {string} string
+     * @return {number}
+     */
+    static #strictParseInt(string) {
+        if (!/^[+-]?\d+$/.test(string)) {
+            throw new Error(`Invalid integer: "${string}"`);
+        }
+        return Number.parseInt(string, 10);
+    }
+
+    /**
+     * Add padding characters to a string.
+     * Port of ParseUtils.addPadding.
+     * @param {string} name parameter name
+     * @param {string} string string to pad
+     * @param {string} c padding character
+     * @param {number} size desired size
+     * @param {boolean} rightJustified if true, pad on the left
+     * @param {number} satelliteNumber satellite number (for error context)
+     * @return {string} padded string
+     */
+    static addPadding(name, string, c, size, rightJustified, satelliteNumber) {
+        if (string.length > size) {
+            throw new Error(
+                `TLE invalid parameter: satelliteNumber=${satelliteNumber}, name=${name}, value=${string}`,
+            );
+        }
+
+        const padding = c.repeat(size);
+
+        if (rightJustified) {
+            const concatenated = padding + string;
+            const l = concatenated.length;
+            return concatenated.substring(l - size, l);
+        }
+
+        return (string + padding).substring(0, size);
+    }
+
+    /**
+     * Build an Alpha-5 (or numeric) satellite number field.
+     * Port of ParseUtils.buildSatelliteNumber.
+     * @param {number} satelliteNumber satellite number, that may exceed the 99999 limit
+     * @param {string} name parameter name (used in error messages)
+     * @return {string} satellite number in alpha5 / 5-digit representation
+     */
+    static buildSatelliteNumber(satelliteNumber, name) {
+        if (satelliteNumber > TleParseUtils.MAX_NUMERIC_SATNUM) {
+            const highDigits = Math.trunc(satelliteNumber / TleParseUtils.ALPHA5_SCALING);
+            const lowDigits = satelliteNumber - highDigits * TleParseUtils.ALPHA5_SCALING;
+
+            const alpha = TleParseUtils.ALPHA5_LETTERS.get(highDigits);
+            if (alpha === undefined) {
+                throw new Error(
+                    `TLE invalid parameter: satelliteNumber=${satelliteNumber}, name=${name}, value=null`,
+                );
+            }
+            return alpha + TleParseUtils.addPadding(
+                name, String(lowDigits), "0", 4, true, satelliteNumber,
+            );
+        }
+        return TleParseUtils.addPadding(
+            name, String(satelliteNumber), "0", 5, true, satelliteNumber,
+        );
+    }
+
+    /**
+     * Parse a satellite number from a string field (supports Alpha-5).
+     * Port of TLE.parseSatelliteNumber / ParseUtils.parseSatelliteNumber.
+     * @param {string} satNumberString the string to parse (e.g., "25544" or "A0001")
+     * @return {number} the satellite number as an integer
+     */
+    static getSatnoFromTle(satNumberString) {
+        if (!TleParseUtils.isValidSatelliteNumberField(satNumberString)) {
+            throw new Error(`Invalid satellite number field: "${satNumberString}"`);
+        }
+
+        const alpha = TleParseUtils.ALPHA5_NUMBERS.get(satNumberString.charAt(0));
+        if (alpha !== undefined) {
+            return (alpha * TleParseUtils.ALPHA5_SCALING)
+                + TleParseUtils.#strictParseInt(satNumberString.substring(1));
+        }
+        return TleParseUtils.#strictParseInt(satNumberString);
+    }
+
+    /**
+     * Lenient catalog NORAD ID decode: 5-char TLE field (digits or Alpha-5),
+     * or an unpadded plain integer string (e.g. "16", "900").
+     * Returns null for nullish / empty / non-numeric values instead of throwing.
+     * @param {string|number|null|undefined} value
+     * @return {number|null}
+     */
+    static parseCatalogSatno(value) {
+        if (!isDefined(value) || value === "") {
+            return null;
+        }
+        const token = String(value).trim();
+        if (TleParseUtils.isValidSatelliteNumberField(token)) {
+            return TleParseUtils.getSatnoFromTle(token);
+        }
+        const n = Number.parseInt(token, 10);
+        return Number.isNaN(n) ? null : n;
+    }
+}

package/src/transform.js

@@ -1,4 +1,5 @@
 import _ from "lodash";
+import {isDefined} from "./utils.js";
 
 const transformObjectKeys = (transform, object, deep = true) => _.cond([
     [
@@ -32,4 +33,15 @@ const pascalCaseObjectKeys = (transformItem, deep) => transformObjectKeys(
     deep,
 );
 
-export {transformObjectKeys, lowerCaseObjectKeys, pascalCaseObjectKeys, pascalCase};
+// Write a true SQL NULL instead of the *string* "null" (JSON.stringify(null) === "null")
+// when a value is absent, so nullable JSON/TEXT columns stay unambiguously empty.
+const jsonOrNull = (value) => (isDefined(value) ? JSON.stringify(value) : null);
+
+// As jsonOrNull, but additionally rejects non-array values (e.g. a provider returning the
+// string "OTHER" in place of a real array), coercing them to null rather than serializing them.
+const jsonArrayOrNull = (value) => (Array.isArray(value) ? JSON.stringify(value) : null);
+
+export {
+    transformObjectKeys, lowerCaseObjectKeys, pascalCaseObjectKeys, pascalCase,
+    jsonOrNull, jsonArrayOrNull,
+};

package/src/udl.js

@@ -5,12 +5,15 @@ import {
     getElsetUdlFromTle,
     getLonAndDrift,
     getRaanPrecession,
+    orbitalMeanMotionRevPerDay,
+    orbitalPeriodMinutes,
     raDecToAzEl,
     azElToRaDec,
     raDecToGeodetic,
     estimateSlantRange,
 } from "./astro.js";
-import {lowerCaseObjectKeys} from "./transform.js";
+import {REGIMES, MU} from "./constants.js";
+import {lowerCaseObjectKeys, jsonArrayOrNull} from "./transform.js";
 import {isDefined} from "./utils.js";
 import _ from "lodash";
 
@@ -327,6 +330,28 @@ const getSVSatno = (udlRow) => {
     return null;
 };
 
+const computeStateRegimeFromKeplerians = (keplerians) => {
+    const {a, e, i} = keplerians;
+    if (!isDefined(a) || a <= 0 || !isDefined(e) || e >= 1) {
+        return REGIMES.Undetermined;
+    }
+
+    const muKm3s2 = MU / 1e9;
+    const period = orbitalPeriodMinutes(a, muKm3s2);
+    const meanmotion = orbitalMeanMotionRevPerDay(a, muKm3s2);
+
+    if (period === null) {
+        return REGIMES.Undetermined;
+    }
+
+    return calcRegime({
+        eccentricity: e,
+        inclination: i,
+        meanmotion,
+        period,
+    });
+};
+
 const udlToNpsState = (udlRow) => {
     const Xpos = _.get(udlRow, "xpos", null); // kilometers
     const Ypos = _.get(udlRow, "ypos", null);
@@ -335,7 +360,7 @@ const udlToNpsState = (udlRow) => {
     const Xvel = _.get(udlRow, "xvel", null); // kilometers/second
     const Yvel = _.get(udlRow, "yvel", null);
     const Zvel = _.get(udlRow, "zvel", null);
-    const cov = _.get(udlRow, "cov", null );
+    const rawCov = _.get(udlRow, "cov", null );
     const covRefFrame = _.get(udlRow, "covReferenceFrame", null );
     let keplerians = {a: null, e: null, i: null, raan: null, w: null, f: null};
 
@@ -351,6 +376,8 @@ const udlToNpsState = (udlRow) => {
         keplerians = cartesianToKeplerian(pos, vel);
     }
 
+    const regime = computeStateRegimeFromKeplerians(keplerians);
+
     const npsState = lowerCaseObjectKeys({
         satno: getSVSatno(udlRow),
         Epoch: fixDate(_.get(udlRow, "epoch", null)),
@@ -368,7 +395,10 @@ const udlToNpsState = (udlRow) => {
         Xvel: Xvel,
         Yvel: Yvel,
         Zvel: Zvel,
-        Covariance: JSON.stringify(cov),
+        // Guard against providers returning a non-array `cov` (e.g. the string "null" or
+        // "OTHER" in place of a real covariance matrix), and write a true SQL NULL rather
+        // than the string "null" when there is no covariance at all.
+        Covariance: jsonArrayOrNull(rawCov),
         CovarianceRefFrame: covRefFrame,
         SemiMajorAxis: keplerians.a,
         Eccentricity: keplerians.e,
@@ -385,7 +415,7 @@ const udlToNpsState = (udlRow) => {
         Longitude: null,
         LonDriftDegreesPerDay: null,
         RaanPrecessionDegreesPerDay: null,
-        Regime: 1,
+        Regime: regime,
     });
     return npsState;
 };