signalk-racer 1.1.0 → 1.1.2

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(git -C /home/gregw/src/signalk-racer tag -l)",
+      "Bash(git -C /home/gregw/src/signalk-racer log --oneline -5)",
+      "Bash(git -C /home/gregw/src/signalk-racer status -sb)",
+      "Bash(git -C /home/gregw/src/signalk-racer remote -v)"
+    ]
+  }
+}

package/README.md

@@ -189,4 +189,41 @@ npm install
 npm link
 cd ~/.signalk
 npm link signalk-racer
-```
+```
+
+---
+## 🚀 Releasing
+
+Releases are cut manually from a clean `main` checkout and published to npm.
+
+### Pre-flight
+
+1. Confirm `main` is up to date and clean: `git checkout main && git pull && git status`.
+2. Run the test suite: `npm test`.
+3. Review commits since the last release: `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
+4. Decide the version bump (semver): `patch` for bug fixes, `minor` for features, `major` for breaking changes.
+
+### Cut the release
+
+1. Update `ReleaseNotes.md` — add a new entry at the top with the new version and a short bullet list of changes, then `git add ReleaseNotes.md`.
+2. Bump the version and create the git tag in one step (note the non-default tag prefix so it matches the existing `signalk-racer-X.Y.Z` convention):
+   ```
+   npm version <patch|minor|major> --tag-version-prefix=signalk-racer-
+   ```
+   This rewrites `package.json`, includes any staged files (e.g. `ReleaseNotes.md`) in the bump commit, and creates tag `signalk-racer-X.Y.Z`.
+3. Push the commit and the tag:
+   ```
+   git push origin main
+   git push origin signalk-racer-X.Y.Z
+   ```
+
+### Publish to npm
+
+1. Confirm npm auth: `npm whoami` (login with `npm login` if needed).
+2. Dry-run the publish to inspect the tarball contents: `npm publish --dry-run`.
+3. Publish: `npm publish` (the package is public and unscoped; no `--access` flag needed).
+
+### After release
+
+1. Verify on npm: `npm view signalk-racer version` should report the new version.
+2. (Optional) Create a GitHub release from the new tag with notes copied from `ReleaseNotes.md`.

package/ReleaseNotes.md

@@ -1,3 +1,13 @@
+## 1.1.2 TTL fixes
+ + use a FIFO queue for VMGs towards the line.
+ + avoid undefined values in deltas
+
+## 1.1.1 Unit tests
++ split into index.js and racing.js for unit testing
++ unit tested TTL 
++ allows negative TTB
++ added configurations for VMG calculations
+
 ## 1.1.0 Named lines
 + Added Named lines support
 + Refactored distance to line calculations

package/index.js

@@ -2,11 +2,6 @@ module.exports = (app) => {
     const state = {
         startLineName: null,
         startLine: null,
-
-        vmgToLinePos: [],  // VMG towards the line (not OCS to line)
-        vmgToLineNeg: [],  // VMG away from the line (OCS to line)
-        vmgToZonePort: [], // Motion along the line towards the PORT end (pin)
-        vmgToZoneStb: [],  // Motion along the line towards the STARBOARD end (boat)
     };
     const geolib = require('geolib')
     const racerSchema = {
@@ -43,7 +38,26 @@ module.exports = (app) => {
                 title: 'Start Timer default initial period in seconds',
                 default: 300
             },
-
+            maxSamples : {
+                type: 'number',
+                title: 'Number of samples to collect for VMG calculations',
+                default: 600
+            },
+            percentile: {
+                type: 'number',
+                title: 'Percentile used to select sample for VMG calculations (0-1)',
+                default: 0.9
+            },
+            minSog: {
+                type: 'number',
+                title: 'Minimum speed over ground (SOG) in knots to consider for VMG calculations',
+                default: 1.0
+            },
+            maxDistance: {
+                type: 'number',
+                title: 'Maximum distance to line and/or line zone in meters to consider for VMG calculations',
+                default: 2000
+            },
             lines: {
                 type: 'array',
                 title: 'Named lines',
@@ -84,7 +98,16 @@ module.exports = (app) => {
             }
         }
     }
-    const { v4: uuidv4 } = require('uuid')
+    const { v4: uuidv4 } = require('uuid');
+    const {
+        initRacer,
+        toDegrees,
+        toRadians,
+        collectVmgSamples,
+        resetVmgSamples,
+        computeTimeToLine
+    } = require('./racer');
+
     const unsubscribes = [];
 
     // Update meta data for non standard paths
@@ -173,19 +196,22 @@ module.exports = (app) => {
     });
 
     // send multiple deltas, each in the form of { path, value }
+    // null values are preserved (meaningful in SignalK for clearing a value);
+    // undefined values are dropped to avoid "Delta is missing value" warnings.
     function sendDeltas(updatesArray) {
-        const timestamp = new Date().toISOString();
+        const values = updatesArray
+            .filter(({value}) => value !== undefined)
+            .map(({path, value}) => ({path, value}));
+
+        if (values.length === 0) return;
 
         const delta = {
             context: 'vessels.self',
             updates: [
                 {
                     source: {label: 'signalk-racer'},
-                    timestamp: timestamp,
-                    values: updatesArray.map(({path, value}) => ({
-                        path,
-                        value
-                    }))
+                    timestamp: new Date().toISOString(),
+                    values
                 }
             ]
         };
@@ -210,16 +236,6 @@ module.exports = (app) => {
         }
     }
 
-    function toDegrees(rad) {
-        if (rad === null || rad === undefined) return null;
-        return rad * (180 / Math.PI);
-    }
-
-    function toRadians(degrees) {
-        if (degrees === null || degrees === undefined) return null;
-        return degrees * (Math.PI / 180);
-    }
-
     function toOtherEnd(end) {
         switch (end) {
             case 'port' :
@@ -672,10 +688,7 @@ module.exports = (app) => {
 
                     app.debug(`STARTLINE: startLinePort: ${JSON.stringify(startLine)}`);
                     state.startLine = startLine;
-                    state.vmgToLineNeg = [];
-                    state.vmgToLinePos = [];
-                    state.vmgToZoneStb = [];
-                    state.vmgToZonePort = [];
+                    resetVmgSamples();
                     deltas = [
                         {path: 'navigation.racing.startLinePort', value: startLine.port},
                         {path: 'navigation.racing.startLineStb', value: startLine.stb},
@@ -802,8 +815,8 @@ module.exports = (app) => {
             if (cog != null && sog != null) {
                 collectVmgSamples(cog, sog, startLine.bearing, toZoneVz, perpToLineVx);
             }
-            const ttl = computeTimeToLine(cog, sog, startLine.bearing, toZoneVz, perpToLineVx, ocs, closestEnd);
-            const ttb = !ocs && state.timerRunning && state.timeToStart > 0 ? Math.max(0, state.timeToStart - ttl) : null;
+            const ttl = computeTimeToLine(cog, sog, startLine.bearing, toZoneVz, perpToLineVx, ocs, closestEnd, state.timeToStart ?? 0);
+            const ttb = !ocs && state.timerRunning && state.timeToStart > 0 && ttl != null ? (state.timeToStart - ttl) : null;
 
             sendDeltas([
                 {path: 'navigation.racing.distanceStartline', value: distanceToLine},
@@ -822,121 +835,6 @@ module.exports = (app) => {
         }
     }
 
-    function collectVmgSamples(cog, sog, lineBearing, toZoneVz, perpToLineVx) {
-        try {
-            // TODO configure these rejection values
-            if (sog < 1.0) return;   // ignore drifting / tacking stalls
-            if (toZoneVz > 1000 || perpToLineVx > 1000) return; // to far away from the line
-
-            // Compute angle boatDir-relative to line bearing
-            let angleRad = cog - toRadians(lineBearing);
-
-            // VMG components
-            const vmgNormal = sog * Math.sin(angleRad);  // +ve = towards line, -ve = away
-            const vmgTangent = sog * Math.cos(angleRad); // +ve = towards pin, -ve = towards stb
-
-            // Insert vmg arrays
-            insertSample(state.vmgToLinePos, vmgNormal);
-            insertSample(state.vmgToLineNeg, -vmgNormal);
-            insertSample(state.vmgToZonePort, vmgTangent);
-            insertSample(state.vmgToZoneStb, -vmgTangent);
-        } catch (err) {
-            app.error(err);
-        }
-    }
-
-    function insertSample(arr, value) {
-        if (value <= 1.0) return; // reject low VMGs
-        if (arr.length >= 600) arr.shift(); // Keep up to 10 minutes at 1Hz
-
-        let lo = 0, hi = arr.length;
-        while (lo < hi) {
-            const mid = (lo + hi) >> 1;
-            if (arr[mid] < value) lo = mid + 1;
-            else hi = mid;
-        }
-        arr.splice(lo, 0, value);
-    }
-
-    function computeTimeToLine(cog, sog, lineBearing, toZoneVz, perpToLineVx, ocs, closestEnd) {
-
-        let vmgNormalSigned = 0;
-        let vmgTangentSigned = 0;
-
-        if (cog != null && sog != null) {
-            const lineBearingRad = toRadians(lineBearing);
-            if (lineBearingRad === null) {
-                return 0;
-            }
-
-            // Angle between boat COG and line bearing
-            const angleRad = cog - lineBearingRad;
-
-            // Signed VMG components from *current* COG/SOG
-            vmgNormalSigned = sog * Math.sin(angleRad); // normal to line
-            vmgTangentSigned = sog * Math.cos(angleRad); // along line (stb->port is +)
-        }
-
-        // 1. Effective VMG normal (perpendicular to line)
-        //
-        // History:
-        //  - if OCS, use vmgToLineNeg (away from line => back towards line in this case)
-        //  - otherwise, use vmgToLinePos
-        const histNormal = percentileFromSorted(ocs ? state.vmgToLineNeg : state.vmgToLinePos, 0.9);
-
-        // Instantaneous VMG in the *required* direction
-        // if we are OCS, then the required direction is the opposite of the effective direction
-        let vmgInstNormal = ocs ? -vmgNormalSigned : vmgNormalSigned;
-        const vmgEffNormal = Math.max(histNormal || 0, vmgInstNormal || 0);
-
-        // 2. Effective VMG along the line (towards the chosen zone entry)
-        let vmgHistParallel = 0;
-        let vmgInstParallel = 0;
-
-        if (toZoneVz > 0) {
-            if (closestEnd === 'port') {
-                // Coming from the pin end, we will sail from PORT towards STB
-                // => use STB-direction samples.
-                vmgHistParallel = percentileFromSorted(state.vmgToZoneStb, 0.9);
-                if (vmgTangentSigned < 0) {
-                    vmgInstParallel = -vmgTangentSigned; // towards stb
-                }
-            } else {
-                // Coming from the boat end, we will sail from STB towards PORT
-                // => use PORT-direction samples.
-                vmgHistParallel = percentileFromSorted(state.vmgToZonePort, 0.9);
-                if (vmgTangentSigned > 0) {
-                    vmgInstParallel = vmgTangentSigned; // towards port
-                }
-            }
-        }
-
-        const vmgEffectParallel = Math.max(vmgHistParallel || 0, vmgInstParallel || 0);
-
-        // 3. Combine legs: along to zone, then perpendicular to line
-        let ttl = 0;
-
-        // Outside the start zone: first go along the line (or zone boundary)
-        if (toZoneVz > 0 && vmgEffectParallel > 0) {
-            ttl += toZoneVz / vmgEffectParallel;
-        }
-
-        // Then go perpendicular to the line to actually hit it
-        if (perpToLineVx > 0 && vmgEffNormal > 0) {
-            ttl += perpToLineVx / vmgEffNormal;
-        }
-
-        app.debug(`computeTimeToLine: ${closestEnd} ${toZoneVz} ${perpToLineVx} ${vmgEffectParallel} ${vmgEffNormal} = ${ttl}`);
-        // If we still somehow have zero (no speed or distances), just return time to start so TTB logic doesn't explode.
-        return ttl <= 0 ? state.timeToStart : ttl;
-    }
-
-    function percentileFromSorted(arr, p) {
-        if (!arr || !arr.length) return 0;
-        const idx = Math.floor(p * (arr.length - 1));
-        return arr[idx];
-    }
-
     function processWind(twd) {
         if (!twd) {
             twd = app.getSelfPath('environment.wind.directionTrue');
@@ -1073,6 +971,14 @@ module.exports = (app) => {
                 app.error('Missing waypoint names: startLinePort and/or startLineStb not configured.');
                 return;
             }
+
+            initRacer({
+                minSog: options.minSog ?? 1.0,
+                maxDistance: options.maxDistance ?? 2000,
+                maxSamples: options.maxSamples ?? 600,
+                percentile: options.percentile ?? 0.9
+            }, app);
+
             app.debug('startLinePort:' + options.startLinePort);
             app.debug('startLineStb:' + options.startLineStb);
             app.debug('app.selfId:' + app.selfId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-racer",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Signalk plugin to calculate values of interest to sail racers, such as: Time to Start; Time of Start, Time to Burn; Distance to Line; Next leg TWA.",
   "main": "index.js",
   "repository": {
@@ -26,5 +26,11 @@
   "dependencies": {
     "geolib": "^3.3.4",
     "uuid": "^8.1.0"
+  },
+  "devDependencies": {
+    "jest": "^30.0.0"
+  },
+  "scripts": {
+    "test": "jest"
   }
 }

package/public/index.html

@@ -1,4 +1,5 @@
 <!DOCTYPE html>
+<!-- public/index.html -->
 <html lang="en">
 <head>
     <meta charset="UTF-8">

package/racer.js

@@ -0,0 +1,183 @@
+// lib/racerMath.js
+'use strict';
+
+let cfg = {
+    minSog: 1.0,
+    maxDistance: 2000,
+    maxSamples: 600,
+    percentile: 0.9
+};
+
+let log = {
+    debug: () => {
+    }
+};
+
+function initRacer(config = {}, logger = null) {
+    cfg = {...cfg, ...config};
+    if (logger?.debug) log = logger;
+}
+
+// VMG sample state is kept private to this module.
+// Each entry has a `sorted` array (ascending, for O(1) percentile) and a
+// `queue` array (insertion-order FIFO, for correct oldest-first eviction).
+const vmgState = {
+    vmgToLinePos: {sorted: [], queue: []},  // VMG towards the line (not OCS to line)
+    vmgToLineNeg: {sorted: [], queue: []},  // VMG away from the line (OCS to line)
+    vmgToZonePort: {sorted: [], queue: []}, // Motion along the line towards the PORT end (pin)
+    vmgToZoneStb: {sorted: [], queue: []}, // Motion along the line towards the STARBOARD end (boat)
+};
+
+function resetVmgSamples() {
+    for (const vmg of Object.values(vmgState)) {
+        vmg.sorted.length = 0;
+        vmg.queue.length = 0;
+    }
+}
+
+function toDegrees(rad) {
+    if (rad === null || rad === undefined) return null;
+    return rad * (180 / Math.PI);
+}
+
+function toRadians(deg) {
+    if (deg === null || deg === undefined) return null;
+    return deg * (Math.PI / 180);
+}
+
+function percentile(vmg, p) {
+    if (!vmg.sorted.length) return 0;
+    const idx = Math.floor(p * (vmg.sorted.length - 1));
+    return vmg.sorted[idx];
+}
+
+function collectVmgSamples(cog, sog, lineBearing, toZoneVz, perpToLineVx) {
+    if (sog < cfg.minSog) return;   // ignore drifting / tacking stalls
+    if (toZoneVz > cfg.maxDistance || perpToLineVx > cfg.maxDistance) return; // to far away from the line
+
+    // Compute angle boatDir-relative to line bearing
+    let angleRad = cog - toRadians(lineBearing);
+
+    // VMG components
+    const vmgNormal = sog * Math.sin(angleRad);  // +ve = towards line, -ve = away
+    const vmgTangent = sog * Math.cos(angleRad); // +ve = towards pin, -ve = towards stb
+
+    // Insert vmg arrays
+    insertSample(vmgState.vmgToLinePos, vmgNormal);
+    insertSample(vmgState.vmgToLineNeg, -vmgNormal);
+    insertSample(vmgState.vmgToZonePort, vmgTangent);
+    insertSample(vmgState.vmgToZoneStb, -vmgTangent);
+}
+
+function insertSample(vmg, value) {
+    if (value <= 1.0)
+        return; // reject low VMGs
+    if (vmg.queue.length >= cfg.maxSamples) {
+        const oldest = vmg.queue.shift(); // evict oldest from FIFO
+        // remove oldest from sorted (binary search)
+        let lo = 0, hi = vmg.sorted.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (vmg.sorted[mid] < oldest)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        vmg.sorted.splice(lo, 1);
+    }
+    // insert value into sorted (binary search)
+    let lo = 0, hi = vmg.sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (vmg.sorted[mid] < value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    vmg.sorted.splice(lo, 0, value);
+    vmg.queue.push(value);
+}
+
+function computeTimeToLine(cog, sog, lineBearing, toZoneVz, perpToLineVx, ocs, closestEnd, timeToStart = 0) {
+    let vmgNormalSigned = 0;
+    let vmgTangentSigned = 0;
+
+    if (cog != null && sog != null) {
+        const lineBearingRad = toRadians(lineBearing);
+        if (lineBearingRad === null) {
+            return 0;
+        }
+
+        // Angle between boat COG and line bearing
+        const angleRad = cog - lineBearingRad;
+
+        // Signed VMG components from *current* COG/SOG
+        vmgNormalSigned = sog * Math.sin(angleRad); // normal to line
+        vmgTangentSigned = sog * Math.cos(angleRad); // along line (stb->port is +)
+    }
+
+    // 1. Effective VMG normal (perpendicular to line)
+    //
+    // History:
+    //  - if OCS, use vmgToLineNeg (away from line => back towards line in this case)
+    //  - otherwise, use vmgToLinePos
+    const histNormal = percentile(ocs ? vmgState.vmgToLineNeg : vmgState.vmgToLinePos, cfg.percentile);
+
+    // Instantaneous VMG in the *required* direction
+    // if we are OCS, then the required direction is the opposite of the effective direction
+    let vmgInstNormal = ocs ? -vmgNormalSigned : vmgNormalSigned;
+    const vmgEffNormal = Math.max(histNormal || 0, vmgInstNormal || 0);
+
+    // 2. Effective VMG along the line (towards the chosen zone entry)
+    let vmgHistParallel = 0;
+    let vmgInstParallel = 0;
+
+    if (toZoneVz > 0) {
+        if (closestEnd === 'port') {
+            // Coming from the pin end, we will sail from PORT towards STB
+            // => use STB-direction samples.
+            vmgHistParallel = percentile(vmgState.vmgToZoneStb, cfg.percentile);
+            if (vmgTangentSigned < 0) {
+                vmgInstParallel = -vmgTangentSigned; // towards stb
+            }
+        } else {
+            // Coming from the boat end, we will sail from STB towards PORT
+            // => use PORT-direction samples.
+            vmgHistParallel = percentile(vmgState.vmgToZonePort, cfg.percentile);
+            if (vmgTangentSigned > 0) {
+                vmgInstParallel = vmgTangentSigned; // towards port
+            }
+        }
+    }
+
+    const vmgEffectParallel = Math.max(vmgHistParallel || 0, vmgInstParallel || 0);
+
+    // 3. Combine legs: along to zone, then perpendicular to line
+    let ttl = 0;
+
+    // Outside the start zone: first go along the line (or zone boundary)
+    if (toZoneVz > 0 && vmgEffectParallel > 0) {
+        ttl += toZoneVz / vmgEffectParallel;
+    }
+
+    // Then go perpendicular to the line to actually hit it
+    if (perpToLineVx > 0 && vmgEffNormal > 0) {
+        ttl += perpToLineVx / vmgEffNormal;
+    }
+
+    // If we still somehow have zero (no speed or distances), just return time to start so TTB logic doesn't explode.
+    return ttl <= 0 ? timeToStart : ttl;
+}
+
+module.exports = {
+    initRacer,
+    toDegrees,
+    toRadians,
+    resetVmgSamples,
+    collectVmgSamples,
+    computeTimeToLine,
+
+    _percentile: percentile, // for testing purposes only
+    _vmgState: vmgState // for testing purposes only
+
+};

package/tests/racer-maths.test.js

@@ -0,0 +1,36 @@
+// tests/racerMath.test.js
+/* global describe, test, expect */
+'use strict';
+
+const {
+    toDegrees,
+    toRadians,
+    _percentile,
+} = require('../racer');
+
+describe('racer math', () => {
+    test('toDegrees: test maths', () => {
+        expect(toDegrees(Math.PI)).toBeCloseTo(180);
+        expect(toDegrees(Math.PI / 2)).toBeCloseTo(90);
+        expect(toDegrees(0)).toBeCloseTo(0);
+        expect(toDegrees(null)).toBeNull();
+        expect(toDegrees(undefined)).toBeNull();
+    });
+    test('toRadians: test maths', () => {
+        expect(toRadians(180)).toBeCloseTo(Math.PI);
+        expect(toRadians(90)).toBeCloseTo(Math.PI / 2);
+        expect(toRadians(0)).toBeCloseTo(0);
+        expect(toRadians(null)).toBeNull();
+        expect(toRadians(undefined)).toBeNull();
+    });
+    test('percentile: test maths', () => {
+        const vmg = (arr) => ({ sorted: arr, queue: [] });
+        expect(_percentile(vmg([]), 0.5)).toBe(0);
+        expect(_percentile(vmg([10]), 0.5)).toBe(10);
+        expect(_percentile(vmg([10, 20, 30]), 0)).toBe(10);
+        expect(_percentile(vmg([10, 20, 30]), 0.5)).toBe(20);
+        expect(_percentile(vmg([10, 20, 30]), 0.9)).toBe(20);
+        expect(_percentile(vmg([10, 20, 30]), 1)).toBe(30);
+        expect(_percentile(vmg([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), 0.75)).toBe(7);
+    })
+});

package/tests/racer-ttl.test.js

@@ -0,0 +1,103 @@
+// tests/racerMath.test.js
+/* global describe, test, expect */
+'use strict';
+
+const {
+    toRadians,
+    computeTimeToLine,
+    resetVmgSamples,
+    _vmgState
+} = require('../racer');
+
+
+describe('racer ttl', () => {
+    test('timeToLineNoVMG: no VMG', () => {
+        resetVmgSamples();
+        expect(computeTimeToLine(toRadians(0), 10, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        // Fallback: ttl computed as 0, so returns the supplied timeToStart.
+        expect(computeTimeToLine(toRadians(0), 10, 270, 100, 0, false, 'stb', 300)).toBe(300);
+        // Default timeToStart parameter is 0.
+        expect(computeTimeToLine(toRadians(0), 10, 270, 100, 0, false, 'stb')).toBe(0);
+    });
+
+    test('timeToLineSmallVmg: small VMG', () => {
+        resetVmgSamples();
+        _vmgState.vmgToLinePos.sorted.push(1, 1, 1);
+        _vmgState.vmgToLineNeg.sorted.push(2, 2, 2);
+        _vmgState.vmgToZonePort.sorted.push(1, 1, 1);
+        _vmgState.vmgToZoneStb.sorted.push(2, 2, 2);
+
+        expect(computeTimeToLine(toRadians(-1), 10, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(0), 10, 270, 100, 0, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(1), 10, 270, 100, 100, false, 'stb')).toBeCloseTo(110);
+
+        expect(computeTimeToLine(toRadians(89), 10, 270, 0, 100, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(90), 10, 270, 100, 0, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(91), 10, 270, 100, 100, false, 'stb')).toBeCloseTo(200);
+
+        expect(computeTimeToLine(toRadians(179), 10, 270, 0, 100, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(180), 10, 270, 100, 0, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(181), 10, 270, 100, 100, false, 'stb')).toBeCloseTo(200);
+
+        expect(computeTimeToLine(toRadians(271), 10, 270, 0, 100, false, 'stb')).toBeCloseTo(100);
+        expect(computeTimeToLine(toRadians(269), 10, 270, 100, 0, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(270), 10, 270, 100, 100, false, 'stb')).toBeCloseTo(110);
+
+        expect(computeTimeToLine(toRadians(359), 10, 270, 0, 100, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(0), 10, 270, 100, 0, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(1), 10, 270, 100, 100, true, 'port')).toBeCloseTo(100);
+
+        expect(computeTimeToLine(toRadians(89), 10, 270, 0, 100, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(90), 10, 270, 100, 0, true, 'port')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(91), 10, 270, 100, 100, true, 'port')).toBeCloseTo(60);
+
+        expect(computeTimeToLine(toRadians(179), 10, 270, 0, 100, true, 'port')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(180), 10, 270, 100, 0, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(181), 10, 270, 100, 100, true, 'port')).toBeCloseTo(60);
+
+        expect(computeTimeToLine(toRadians(271), 10, 270, 0, 100, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(269), 10, 270, 100, 0, true, 'port')).toBeCloseTo(50);
+        expect(computeTimeToLine(toRadians(270), 10, 270, 100, 100, true, 'port')).toBeCloseTo(100);
+    });
+
+    test('timeToLineSmallInstant: small instant', () => {
+        resetVmgSamples();
+        _vmgState.vmgToLinePos.sorted.push(10, 10, 10, 10, 10, 10, 10, 10, 10, 15);
+        _vmgState.vmgToLineNeg.sorted.push(20, 20, 20, 20, 20, 20, 20, 20, 20, 25);
+        _vmgState.vmgToZonePort.sorted.push(10, 10, 10, 10, 10, 10, 10, 10, 10, 15);
+        _vmgState.vmgToZoneStb.sorted.push(20, 20, 20, 20, 20, 20, 20, 20, 20, 25);
+
+        expect(computeTimeToLine(toRadians(-1), 1, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(0), 1, 270, 100, 0, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(1), 1, 270, 100, 100, false, 'stb')).toBeCloseTo(20);
+
+        expect(computeTimeToLine(toRadians(89), 1, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(90), 1, 270, 100, 0, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(91), 1, 270, 100, 100, false, 'stb')).toBeCloseTo(20);
+
+        expect(computeTimeToLine(toRadians(179), 1, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(180), 1, 270, 100, 0, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(181), 1, 270, 100, 100, false, 'stb')).toBeCloseTo(20);
+
+        expect(computeTimeToLine(toRadians(271), 1, 270, 0, 100, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(269), 1, 270, 100, 0, false, 'stb')).toBeCloseTo(10);
+        expect(computeTimeToLine(toRadians(270), 1, 270, 100, 100, false, 'stb')).toBeCloseTo(20);
+
+        expect(computeTimeToLine(toRadians(359), 1, 270, 0, 100, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(0), 1, 270, 100, 0, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(1), 1, 270, 100, 100, true, 'port')).toBeCloseTo(10);
+
+        expect(computeTimeToLine(toRadians(89), 1, 270, 0, 100, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(90), 1, 270, 100, 0, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(91), 1, 270, 100, 100, true, 'port')).toBeCloseTo(10);
+
+        expect(computeTimeToLine(toRadians(179), 1, 270, 0, 100, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(180), 1, 270, 100, 0, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(181), 1, 270, 100, 100, true, 'port')).toBeCloseTo(10);
+
+        expect(computeTimeToLine(toRadians(271), 1, 270, 0, 100, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(269), 1, 270, 100, 0, true, 'port')).toBeCloseTo(5);
+        expect(computeTimeToLine(toRadians(270), 1, 270, 100, 100, true, 'port')).toBeCloseTo(10);
+    });
+
+});

package/tests/racer-vmg.test.js

@@ -0,0 +1,168 @@
+// tests/racerMath.test.js
+/* global describe, test, expect */
+'use strict';
+
+const {
+    toRadians,
+    collectVmgSamples,
+    resetVmgSamples,
+    _vmgState
+} = require('../racer');
+
+describe('racer vmg', () => {
+    test('resetVmgSamples: test arrays are cleared', () => {
+        _vmgState.vmgToLinePos.sorted.push(1, 2, 3);
+        _vmgState.vmgToLinePos.queue.push(1, 2, 3);
+        _vmgState.vmgToLineNeg.sorted.push(4, 5, 6);
+        _vmgState.vmgToLineNeg.queue.push(4, 5, 6);
+        _vmgState.vmgToZonePort.sorted.push(7, 8, 9);
+        _vmgState.vmgToZonePort.queue.push(7, 8, 9);
+        _vmgState.vmgToZoneStb.sorted.push(10, 11, 12);
+        _vmgState.vmgToZoneStb.queue.push(10, 11, 12);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(3);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        resetVmgSamples();
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(0);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(0);
+    });
+
+
+    test('collectVmgSamplesEastWestNarrow: test east west line, with perpendicular and narrow approaches', () => {
+        resetVmgSamples();
+        collectVmgSamples(toRadians(0), 19.7, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(1);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(19.7);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(0);
+
+        collectVmgSamples(toRadians(8.21), 19.7, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(19.5);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(19.7);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(1);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(2.81);
+    });
+
+
+    test('collectVmgSamplesEastWest: test east west line with circle', () => {
+        resetVmgSamples();
+        collectVmgSamples(toRadians(0), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(1);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBe(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(0);
+
+        collectVmgSamples(toRadians(36.87), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBe(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(1);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+
+        collectVmgSamples(toRadians(90), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(2);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(5);
+
+        collectVmgSamples(toRadians(90 + 36.87), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(1);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted[2]).toBeCloseTo(5);
+
+        collectVmgSamples(toRadians(180), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(0);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted[2]).toBeCloseTo(5);
+
+        collectVmgSamples(toRadians(180 + 53.13), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(3);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[1]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[2]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(1);
+        expect(_vmgState.vmgToZonePort.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted[2]).toBeCloseTo(5);
+
+        collectVmgSamples(toRadians(270), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(2);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(3);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[1]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[2]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(2);
+        expect(_vmgState.vmgToZonePort.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZonePort.sorted[1]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted[2]).toBeCloseTo(5);
+
+        collectVmgSamples(-toRadians(53.13), 5, 270, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(3);
+        expect(_vmgState.vmgToLinePos.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLinePos.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToLinePos.sorted[2]).toBeCloseTo(5);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(3);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[1]).toBeCloseTo(3);
+        expect(_vmgState.vmgToLineNeg.sorted[2]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZonePort.sorted[0]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZonePort.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZonePort.sorted[2]).toBeCloseTo(5);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(3);
+        expect(_vmgState.vmgToZoneStb.sorted[0]).toBeCloseTo(3);
+        expect(_vmgState.vmgToZoneStb.sorted[1]).toBeCloseTo(4);
+        expect(_vmgState.vmgToZoneStb.sorted[2]).toBeCloseTo(5);
+
+    });
+
+    test('collectVmgSamplesNW2SE: test NW to SE line approached obliquely', () => {
+        resetVmgSamples();
+        collectVmgSamples(toRadians(0), 19.7, 8.21, 0, 0);
+        expect(_vmgState.vmgToLinePos.sorted.length).toBe(0);
+        expect(_vmgState.vmgToLineNeg.sorted.length).toBe(1);
+        expect(_vmgState.vmgToLineNeg.sorted[0]).toBeCloseTo(2.81);
+        expect(_vmgState.vmgToZonePort.sorted.length).toBe(1);
+        expect(_vmgState.vmgToZonePort.sorted[0]).toBeCloseTo(19.5);
+        expect(_vmgState.vmgToZoneStb.sorted.length).toBe(0);
+    });
+});