@saber-usa/node-common 1.7.22 → 1.7.24-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saber-usa/node-common",
-  "version": "1.7.22",
+  "version": "1.7.24-alpha.1",
   "description": "Common node functions for Saber",
   "main": "src/index.js",
   "type": "module",

package/src/PropagateUtils.js

@@ -6,7 +6,7 @@ import {RungeKutta4Propagator,
     ClassicalElements} from "pious-squid";
 import {sgp4} from "satellite.js";
 import {NodeVector3D} from "./NodeVector3D.js";
-import {checkTle} from "./astro.js";
+import {validateTle} from "./astro.js";
 import {OrbitUtils} from "./OrbitUtils.js";
 
 const ReferenceFrame = {
@@ -87,10 +87,11 @@ class PropagateUtils {
     static tlePropagator(tle, time) {
         const line1 = tle[0];
         const line2 = tle[1];
-        const satrec = checkTle(line1, line2);
-        if (!satrec) {
-            throw new Error("Invalid TLE data");
+        const tleResult = validateTle(line1, line2);
+        if (!tleResult.ok) {
+            throw new Error(tleResult.errors.join("; "));
         }
+        const satrec = tleResult.satrec;
         const result = sgp4(satrec, time);
         return result;
     }

package/src/astro.js

@@ -45,6 +45,9 @@ import {DEG2RAD,
     MILLIS_PER_DAY,
     GEO_ALTITUDE_KM,
     ERROR_CODES} from "./constants.js";
+import TLEValidator from "./tle/TLEValidator.js";
+import MultiLineTLEValidator from "./tle/MultiLineTLEValidator.js";
+import {TLE_ERRORS} from "./tle/tleErrors.js";
 
 // Solar Terminator
 // Returns sun latitude and longitude as -180/180
@@ -58,6 +61,11 @@ const sunPosAt = (dt) => {
     ];
 };
 
+/**
+ * @deprecated Use validateTle() for structured validation results.
+ * Retained with original semantics (satrec | false, no format checks)
+ * for external consumers of @saber-usa/node-common.
+ */
 const checkTle = (line1, line2) => {
     try {
         // Initialize a satellite record
@@ -77,6 +85,50 @@ const checkTle = (line1, line2) => {
     }
 };
 
+const propagateTleToSatrec = (line1, line2) => {
+    const satrec = twoline2satrec(line1, line2);
+    satrec.epoch = dateToMySqlDate(julianToGregorian(satrec.jdsatepoch));
+    const pv = sgp4(satrec, 0);
+    if (Number.isNaN(pv.position.x)
+        || Number.isNaN(pv.position.y)
+        || Number.isNaN(pv.position.z)) {
+        return null;
+    }
+    return satrec;
+};
+
+/**
+ * Validates a NORAD TLE line pair with format checks and propagation gate.
+ * @param {string} line1 TLE line 1
+ * @param {string} line2 TLE line 2
+ * @return {{ ok: 0|1, satrec: object|null, errors: string[] }}
+ */
+const validateTle = (line1, line2) => {
+    const l1 = String(line1 ?? "").trim();
+    const l2 = String(line2 ?? "").trim();
+    const errors = [];
+    const tleStatus = new TLEValidator().validate(l1, l2);
+    if (tleStatus.lineOneStatus !== null) {
+        errors.push(tleStatus.lineOneStatus);
+    }
+    if (tleStatus.lineTwoStatus !== null) {
+        errors.push(tleStatus.lineTwoStatus);
+    }
+    if (errors.length > 0) {
+        return {ok: 0, satrec: null, errors};
+    }
+    try {
+        const satrec = propagateTleToSatrec(l1, l2);
+        if (!satrec) {
+            return {ok: 0, satrec: null, errors: [TLE_ERRORS.PROPAGATE_FAILED]};
+        }
+        return {ok: 1, satrec, errors: []};
+    } catch (e) {
+        console.error(e);
+        return {ok: 0, satrec: null, errors: [TLE_ERRORS.PROPAGATE_FAILED]};
+    }
+};
+
 /**
  * Validates the output of the satellite.js propagate function.
  * The satellite.js propagate function returns a object with the following properties:
@@ -1328,9 +1380,9 @@ const GetElsetUdlFromTle = (
     descriptor = null,
 ) => {
     try {
-        // Check the TLE lines, or exit early
-        if (!checkTle(l1, l2)) {
-            throw new Error("Input TLE lines have bad format.");
+        const tleResult = validateTle(l1, l2);
+        if (!tleResult.ok) {
+            throw new Error(tleResult.errors.join("; "));
         }
 
         const elset = {};
@@ -1833,8 +1885,8 @@ const assembleLeoRpoResult = (s, pEphem, sEphem, includeRIC=false) => {
 
 const getLeoRpoData = (line1, line2, sats, startTime, endTime, includeRIC=false) => {
     const results = [];
-    const pSatRec = checkTle(line1, line2);
-    if (!isDefined(pSatRec)) {return results;}
+    const tleResult = validateTle(line1, line2);
+    if (!tleResult.ok) {return results;}
 
     const start = new Date(startTime).getTime();
     const end = new Date(endTime).getTime();
@@ -3474,6 +3526,11 @@ export {
     getLonAndDrift,
     getRaanPrecession,
     checkTle,
+    validateTle,
+    propagateTleToSatrec,
+    TLEValidator,
+    MultiLineTLEValidator,
+    TLE_ERRORS,
     sunPosAt,
     distGeodetic,
     getSemiMajorAxis,

package/src/tle/MultiLineTLEValidator.js

@@ -0,0 +1,114 @@
+import TLEValidator from "./TLEValidator.js";
+import {TLE_ERRORS} from "./tleErrors.js";
+
+/**
+ * Validates multiple TLE lines, pairing line 1 with line 2.
+ * Logic derived from whatswrongwithmytle.com (Dr. TS Kelso's field guide).
+ */
+class MultiLineTLEValidator {
+    constructor() {
+        this.reset();
+    }
+
+    reset() {
+        this.recentLine = null;
+        this.pairs = [];
+        this.orphans = [];
+        this.tleValidator = new TLEValidator();
+    }
+
+    validateLines(lines) {
+        this.reset();
+        for (const line of lines) {
+            this.validateLine(line);
+        }
+        this.flushRecentLine();
+        return this.getResults();
+    }
+
+    flushRecentLine() {
+        if (this.recentLine === null) {
+            return;
+        }
+        if (this.recentLine.startsWith("1 ")) {
+            this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE1});
+        } else if (this.recentLine.startsWith("2 ")) {
+            this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE2});
+        } else {
+            this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE1});
+        }
+        this.recentLine = null;
+    }
+
+    validateLine(line = "") {
+        const sanitized = this.sanitizeLine(line);
+        if (sanitized === null) {
+            return null;
+        }
+
+        if (this.recentLine === null) {
+            this.recentLine = sanitized;
+            return null;
+        }
+
+        if (this.recentLine.startsWith("1 ")) {
+            if (sanitized.startsWith("2 ")) {
+                this.recordPair(this.recentLine, sanitized);
+                this.recentLine = null;
+            } else {
+                this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE1});
+                this.recentLine = sanitized;
+            }
+            return null;
+        }
+
+        if (this.recentLine.startsWith("2 ")) {
+            this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE2});
+            this.recentLine = sanitized;
+            return null;
+        }
+
+        this.orphans.push({line: this.recentLine, error: TLE_ERRORS.ORPHAN_LINE1});
+        this.recentLine = sanitized;
+        return null;
+    }
+
+    recordPair(line1, line2) {
+        const tleStatus = this.tleValidator.validate(line1, line2);
+        const errors = [];
+        if (tleStatus.lineOneStatus !== null) {
+            errors.push(tleStatus.lineOneStatus);
+        }
+        if (tleStatus.lineTwoStatus !== null) {
+            errors.push(tleStatus.lineTwoStatus);
+        }
+        this.pairs.push({
+            line1,
+            line2,
+            ok: errors.length === 0,
+            errors,
+        });
+    }
+
+    sanitizeLine(line) {
+        if (line.startsWith("✅") || line.startsWith("🚩")) {
+            return null;
+        }
+        if (line.includes("✅")) {
+            return line.slice(0, line.indexOf("✅"));
+        }
+        if (line.includes("🚩")) {
+            return line.slice(0, line.indexOf("🚩"));
+        }
+        return line;
+    }
+
+    getResults() {
+        return {
+            pairs: this.pairs,
+            orphans: this.orphans,
+        };
+    }
+}
+
+export default MultiLineTLEValidator;

package/src/tle/TLEValidator.js

@@ -0,0 +1,135 @@
+import {formatChecksumError, formatLengthError, TLE_ERRORS} from "./tleErrors.js";
+
+/**
+ * NORAD TLE line-pair validator.
+ * Logic derived from whatswrongwithmytle.com (Dr. TS Kelso's field guide).
+ */
+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}/;
+        this.lineOneRegexDDMeanMotion = / [ +-]\d{5}[-+]\d/;
+        this.lineOneRegexBSTAR = / [ +-]\d{5}[-+]\d/;
+        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}/;
+        this.lineTwoRegexArgumentOfPerigee = / [ \d]{3}\.\d{4}/;
+        this.lineTwoRegexMeanAnomaly = / [ \d]{3}\.\d{4}/;
+        this.lineTwoRegexMeanMotion = / [ \d]{2}\.\d{8}/;
+        this.lineTwoRegexRevNumber = /[ \d]{4}\d/;
+    }
+
+    computeChecksum(line) {
+        let sum = 0;
+        for (let i = 0; i < 68; i += 1) {
+            const char = line[i];
+            const val = Number.parseInt(char, 10);
+            if (!Number.isNaN(val)) {
+                sum += val;
+            } else if (char === "-") {
+                sum += 1;
+            }
+        }
+        return sum % 10;
+    }
+
+    validate(lineOne, lineTwo) {
+        const lineOneStatus = this.validateLineOne(lineOne);
+        const lineTwoStatus = this.validateLineTwo(lineTwo);
+        if (lineOneStatus === null
+            && lineTwoStatus === null
+            && lineOne.slice(2, 7) !== lineTwo.slice(2, 7)) {
+            return {
+                lineOneStatus: null,
+                lineTwoStatus: TLE_ERRORS.CATALOG_MISMATCH,
+            };
+        }
+        return {lineOneStatus, lineTwoStatus};
+    }
+
+    validateLineOne(line) {
+        if (line.length < 69) {
+            return formatLengthError(TLE_ERRORS.LINE1_LENGTH, line.length);
+        }
+        if (!this.lineOneRegexCatalogNumber.test(line.slice(2, 8))) {
+            return TLE_ERRORS.LINE1_CATALOG_NUMBER;
+        }
+        if (!this.lineOneRegexInternationalDesignator.test(line.slice(8, 17))) {
+            return TLE_ERRORS.LINE1_INTERNATIONAL_DESIGNATOR;
+        }
+        if (!this.lineOneRegexEpoch.test(line.slice(17, 32))) {
+            return TLE_ERRORS.LINE1_EPOCH;
+        }
+        if (!this.lineOneRegexDMeanMotion.test(line.slice(32, 43))) {
+            return TLE_ERRORS.LINE1_D_MEAN_MOTION;
+        }
+        if (!this.lineOneRegexDDMeanMotion.test(line.slice(43, 52))) {
+            return TLE_ERRORS.LINE1_DD_MEAN_MOTION;
+        }
+        if (!this.lineOneRegexBSTAR.test(line.slice(52, 61))) {
+            return TLE_ERRORS.LINE1_BSTAR;
+        }
+        if (!this.lineOneRegexEphemType.test(line.slice(61, 63))) {
+            return TLE_ERRORS.LINE1_EPHEM_TYPE;
+        }
+        if (!this.lineOneRegexSetNumber.test(line.slice(63, 68))) {
+            return TLE_ERRORS.LINE1_SET_NUMBER;
+        }
+        if (line.length > 69) {
+            return TLE_ERRORS.LINE1_EXTRA_CHARS;
+        }
+
+        const checksum = this.computeChecksum(line);
+        if (checksum !== Number.parseInt(line[68], 10)) {
+            return formatChecksumError(TLE_ERRORS.LINE1_CHECKSUM, checksum);
+        }
+        return null;
+    }
+
+    validateLineTwo(line) {
+        if (line.length < 69) {
+            return formatLengthError(TLE_ERRORS.LINE2_LENGTH, line.length);
+        }
+        if (!this.lineTwoRegexCatalogNumber.test(line.slice(2, 7))) {
+            return TLE_ERRORS.LINE2_CATALOG_NUMBER;
+        }
+        if (!this.lineTwoRegexInclination.test(line.slice(7, 16))) {
+            return TLE_ERRORS.LINE2_INCLINATION;
+        }
+        if (!this.lineTwoRegexRAAN.test(line.slice(16, 25))) {
+            return TLE_ERRORS.LINE2_RAAN;
+        }
+        if (!this.lineTwoRegexEccentricity.test(line.slice(25, 33))) {
+            return TLE_ERRORS.LINE2_ECCENTRICITY;
+        }
+        if (!this.lineTwoRegexArgumentOfPerigee.test(line.slice(33, 42))) {
+            return TLE_ERRORS.LINE2_ARGUMENT_OF_PERIGEE;
+        }
+        if (!this.lineTwoRegexMeanAnomaly.test(line.slice(42, 51))) {
+            return TLE_ERRORS.LINE2_MEAN_ANOMALY;
+        }
+        if (!this.lineTwoRegexMeanMotion.test(line.slice(51, 63))) {
+            return TLE_ERRORS.LINE2_MEAN_MOTION;
+        }
+        if (!this.lineTwoRegexRevNumber.test(line.slice(63, 68))) {
+            return TLE_ERRORS.LINE2_REV_NUMBER;
+        }
+        if (line.length > 69) {
+            return TLE_ERRORS.LINE2_EXTRA_CHARS;
+        }
+
+        const checksum = this.computeChecksum(line);
+        if (checksum !== Number.parseInt(line[68], 10)) {
+            return formatChecksumError(TLE_ERRORS.LINE2_CHECKSUM, checksum);
+        }
+        return null;
+    }
+}
+
+export default TLEValidator;

package/src/tle/tleErrors.js

@@ -0,0 +1,36 @@
+/**
+ * TLE validation error message constants.
+ * Logic derived from whatswrongwithmytle.com (Dr. TS Kelso's field guide).
+ */
+export const TLE_ERRORS = {
+    LINE1_LENGTH: "TLE line 1 must be 69 characters",
+    LINE2_LENGTH: "TLE line 2 must be 69 characters",
+    LINE1_EXTRA_CHARS: "TLE line 1: extra character(s) detected",
+    LINE2_EXTRA_CHARS: "TLE line 2: extra character(s) detected",
+    LINE1_CATALOG_NUMBER: "TLE line 1: fix catalog number",
+    LINE1_INTERNATIONAL_DESIGNATOR: "TLE line 1: fix international designator or leave it blank",
+    LINE1_EPOCH: "TLE line 1: fix epoch",
+    LINE1_D_MEAN_MOTION: "TLE line 1: fix first derivative of mean motion",
+    LINE1_DD_MEAN_MOTION: "TLE line 1: fix second derivative of mean motion",
+    LINE1_BSTAR: "TLE line 1: fix BSTAR",
+    LINE1_EPHEM_TYPE: "TLE line 1: ephemeris type should be zero",
+    LINE1_SET_NUMBER: "TLE line 1: fix element set number",
+    LINE1_CHECKSUM: "TLE line 1: checksum should be",
+    LINE2_CATALOG_NUMBER: "TLE line 2: fix catalog number",
+    LINE2_INCLINATION: "TLE line 2: fix inclination",
+    LINE2_RAAN: "TLE line 2: fix right ascension",
+    LINE2_ECCENTRICITY: "TLE line 2: fix eccentricity",
+    LINE2_ARGUMENT_OF_PERIGEE: "TLE line 2: fix argument of perigee",
+    LINE2_MEAN_ANOMALY: "TLE line 2: fix mean anomaly",
+    LINE2_MEAN_MOTION: "TLE line 2: fix mean motion",
+    LINE2_REV_NUMBER: "TLE line 2: fix revolution number",
+    LINE2_CHECKSUM: "TLE line 2: checksum should be",
+    CATALOG_MISMATCH: "TLE catalog numbers must match between lines",
+    ORPHAN_LINE1: "Found line 1, missing line 2",
+    ORPHAN_LINE2: "Found line 2, missing line one",
+    PROPAGATE_FAILED: "TLE propagation failed",
+};
+
+export const formatLengthError = (baseMessage, length) => `${baseMessage} (got ${length})`;
+
+export const formatChecksumError = (baseMessage, checksum) => `${baseMessage} ${checksum}`;

package/src/udl.js

@@ -1,6 +1,7 @@
 import {fixDate} from "./fixDate.js";
 import {
     calcRegime,
+    cartesianToKeplerian,
     getElsetUdlFromTle,
     getLonAndDrift,
     getRaanPrecession,
@@ -310,4 +311,83 @@ const enrichUdlFields = (npsOb) => {
     return npsOb;
 };
 
-export {udlToNpsElset, udlToNpsGroundSite, udlToNpsConjunction, enrichUdlFields};
+const getSVSatno = (udlRow) => {
+    if (udlRow.satNo) {return udlRow.satNo;}
+    if (udlRow.idOnOrbit) {return udlRow.idOnOrbit;}
+    if (!udlRow.origObjectId) {return null;}
+
+    const id = udlRow.origObjectId;
+    if (
+        /^\d+$/.test(id)
+        || /^\d+~~.+$/.test(id) // KBR
+    ) {
+        return Number.parseInt(id); // parse int will ignore everything after an invalid character
+    }
+
+    return null;
+};
+
+const udlToNpsState = (udlRow) => {
+    const Xpos = _.get(udlRow, "xpos", null); // kilometers
+    const Ypos = _.get(udlRow, "ypos", null);
+    const Zpos = _.get(udlRow, "zpos", null);
+
+    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 covRefFrame = _.get(udlRow, "covReferenceFrame", null );
+    let keplerians = {a: null, e: null, i: null, raan: null, w: null, f: null};
+
+    if (Xpos !== null && Ypos !== null && Zpos !== null
+        && Xvel !== null && Yvel !== null && Zvel !== null) {
+        const KM_TO_M = 1000;
+
+        const pos = [Xpos * KM_TO_M, Ypos * KM_TO_M, Zpos * KM_TO_M]; // Position, in meters
+        const vel = [Xvel * KM_TO_M, Yvel * KM_TO_M, Zvel * KM_TO_M]; // Velocity, in m/s
+
+        // [ a, e, i, Ω, ω, θ ]
+        // sma (km), eccentricity, inclination (deg), raan (deg), arg of perigee (deg), true anomaly (deg)
+        keplerians = cartesianToKeplerian(pos, vel);
+    }
+
+    const npsState = lowerCaseObjectKeys({
+        satno: getSVSatno(udlRow),
+        Epoch: fixDate(_.get(udlRow, "epoch", null)),
+        idStateVector: _.get(udlRow, "idStateVector", null),
+        classificationMarking: _.get(udlRow, "classificationMarking", null),
+        referenceFrame: _.get(udlRow, "referenceFrame", null),
+        Pedigree: _.get(udlRow, "pedigree", null),
+        uct: _.get(udlRow, "uct", null),
+        idOnOrbit: _.get(udlRow, "idOnOrbit", null),
+        origObjectId: _.get(udlRow, "origObjectId", null),
+        descriptor: _.get(udlRow, "descriptor", null),
+        Xpos: Xpos,
+        Ypos: Ypos,
+        Zpos: Zpos,
+        Xvel: Xvel,
+        Yvel: Yvel,
+        Zvel: Zvel,
+        Covariance: JSON.stringify(cov),
+        CovarianceRefFrame: covRefFrame,
+        SemiMajorAxis: keplerians.a,
+        Eccentricity: keplerians.e,
+        Inclination: keplerians.i,
+        Raan: keplerians.raan,
+        ArgOfPerigee: keplerians.w,
+        TrueAnomaly: keplerians.f,
+
+        source: _.get(udlRow, "source", null),
+        dataMode: _.get(udlRow, "dataMode", null),
+        createdat: fixDate(_.get(udlRow, "createdAt", null)),
+
+        Latitude: null,
+        Longitude: null,
+        LonDriftDegreesPerDay: null,
+        RaanPrecessionDegreesPerDay: null,
+        Regime: 1,
+    });
+    return npsState;
+};
+
+export {udlToNpsElset, udlToNpsGroundSite, udlToNpsConjunction, udlToNpsState, enrichUdlFields};

package/src/wasmProp/wasmAstro.js

@@ -13,7 +13,7 @@ import {
     buildWaterfallBreakpoints,
     decorateWaterfallSegment,
     assembleWaterfallRows,
-    checkTle,
+    validateTle,
     getLonAndDrift,
     getEclipseStatus,
 } from "../astro.js";
@@ -53,8 +53,8 @@ import {RAD2DEG} from "../constants.js";
  */
 const getLeoRpoDataBulk = async (line1, line2, sats, startTime, endTime, includeRIC=false) => {
     const results = [];
-    const pSatRec = checkTle(line1, line2);
-    if (!isDefined(pSatRec)) {return results;}
+    const tleResult = validateTle(line1, line2);
+    if (!tleResult.ok) {return results;}
 
     const start = new Date(startTime).getTime();
     const end = new Date(endTime).getTime();