@ingissa/navcore-simulator 1.0.3 → 1.0.7

package/src/core/SimulatorEngine.ts

@@ -0,0 +1,364 @@
+/**
+ * SimulatorEngine — The headless GPS simulation core.
+ *
+ * Works in Node.js for CI tests. NO React, NO Expo APIs.
+ * All timers are cleaned up on destroy(). No memory leaks.
+ *
+ * State machine: idle → running ⇄ paused → complete
+ */
+
+import { NoiseEngine } from './NoiseEngine';
+import { RouteWalker } from './RouteWalker';
+import { ScenarioInjector } from '../scenarios/ScenarioInjector';
+import type { SimPosition, SimulatorConfig, SimSession, Scenario } from './types';
+
+/** Generate a UUID v4 without external dependencies */
+function uuidV4(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export type EngineState = 'idle' | 'running' | 'paused' | 'complete';
+
+export class SimulatorEngine {
+  // ── Config ──────────────────────────────────────────────────────────────────
+  private readonly config: Required<
+    Omit<SimulatorConfig, 'onPositionUpdate' | 'onRouteComplete' | 'onScenarioStart' | 'onScenarioEnd'>
+  > & Pick<SimulatorConfig, 'onPositionUpdate' | 'onRouteComplete' | 'onScenarioStart' | 'onScenarioEnd'>;
+
+  // ── Internal components ──────────────────────────────────────────────────────
+  private walker: RouteWalker;
+  private noise: NoiseEngine;
+  private injector: ScenarioInjector;
+
+  // ── State ────────────────────────────────────────────────────────────────────
+  private _state: EngineState = 'idle';
+  private _position: SimPosition | null = null;
+  private _speedMultiplier: 1 | 2 | 4 | 8;
+  private _timer: ReturnType<typeof setInterval> | null = null;
+  private _lastTick: number = 0;
+
+  private static readonly TICK_MS = 50; // 20 FPS for smooth movement
+
+  // ── Recording ────────────────────────────────────────────────────────────────
+  private _recording = false;
+  private _recordedPositions: SimPosition[] = [];
+  private _recordedScenarios: Array<{ scenario: Scenario; firedAt: number }> = [];
+  private _sessionId: string | null = null;
+  private _sessionStart: number | null = null;
+  private _noiseSamplesAdded = 0;
+
+  constructor(config: SimulatorConfig) {
+    const geometry = config.routeGeometry;
+    if (!geometry || geometry.length < 2) {
+      throw new Error('SimulatorEngine: routeGeometry must have at least 2 points');
+    }
+
+    this._speedMultiplier = config.speedMultiplier ?? 1;
+
+    this.config = {
+      routeGeometry: geometry,
+      speedKmh: config.speedKmh ?? 50,
+      speedMultiplier: this._speedMultiplier,
+      noiseProfile: config.noiseProfile ?? NoiseEngine.STANDARD,
+      loop: config.loop ?? false,
+      startIndex: config.startIndex ?? 0,
+      autoStart: config.autoStart ?? false,
+      onPositionUpdate: config.onPositionUpdate,
+      onRouteComplete: config.onRouteComplete,
+      onScenarioStart: config.onScenarioStart,
+      onScenarioEnd: config.onScenarioEnd,
+    };
+
+    this.walker = new RouteWalker(geometry, this.config.startIndex);
+    this.noise = new NoiseEngine(this.config.noiseProfile);
+
+    this.injector = new ScenarioInjector(
+      (s) => {
+        if (this._recording) {
+          this._recordedScenarios.push({ scenario: s, firedAt: Date.now() });
+        }
+        try { this.config.onScenarioStart?.(s); } catch (_) { /* never throw */ }
+      },
+      (s) => {
+        try { this.config.onScenarioEnd?.(s); } catch (_) { /* never throw */ }
+      },
+    );
+
+    if (this.config.autoStart) {
+      this.start();
+    }
+  }
+
+  // ── Playback controls ────────────────────────────────────────────────────────
+
+  start(): void {
+    if (this._state === 'running') return;
+    if (this._state === 'complete') return;
+    this._state = 'running';
+    this._startTimer();
+  }
+
+  stop(): void {
+    this._stopTimer();
+    this._state = 'idle';
+    this._position = null;
+  }
+
+  pause(): void {
+    if (this._state !== 'running') return;
+    this._stopTimer();
+    this._state = 'paused';
+  }
+
+  resume(): void {
+    if (this._state !== 'paused') return;
+    this._state = 'running';
+    this._startTimer();
+  }
+
+  /**
+   * Jump to any geometry index.
+   * Bearing is recalculated from the new segment — seek() is always bearing-safe.
+   */
+  seek(geometryIndex: number): void {
+    const wasRunning = this._state === 'running';
+    if (wasRunning) this._stopTimer();
+
+    const pos = this.walker.seek(geometryIndex);
+    this._buildAndEmitPosition(pos.coord, pos.bearing, pos.distanceTravelled, false);
+
+    // Reset the completion flag so simulation can continue from the new index
+    if (this._state === 'complete' && !pos.isComplete) {
+      this._state = 'idle';
+    }
+
+    if (wasRunning && !pos.isComplete) {
+      this._state = 'running';
+      this._startTimer();
+    }
+  }
+
+  setSpeed(multiplier: 1 | 2 | 4 | 8): void {
+    this._speedMultiplier = multiplier;
+    if (this._state === 'running') {
+      this._stopTimer();
+      this._startTimer();
+    }
+  }
+
+  // ── Scenario management ──────────────────────────────────────────────────────
+
+  addScenario(scenario: Scenario): void {
+    this.injector.register(scenario);
+  }
+
+  removeScenario(name: string): void {
+    this.injector.remove(name);
+  }
+
+  clearScenarios(): void {
+    this.injector.clear();
+  }
+
+  // ── State accessors ──────────────────────────────────────────────────────────
+
+  get state(): EngineState {
+    return this._state;
+  }
+
+  get position(): SimPosition | null {
+    return this._position;
+  }
+
+  get progress(): number {
+    if (this.walker.totalPoints <= 1) return 0;
+    return Math.min(1, this.walker.currentIndex / (this.walker.totalPoints - 1));
+  }
+
+  // ── Session recording ────────────────────────────────────────────────────────
+
+  startRecording(sessionId?: string): void {
+    this._recording = true;
+    this._recordedPositions = [];
+    this._recordedScenarios = [];
+    this._sessionId = sessionId ?? uuidV4();
+    this._sessionStart = Date.now();
+    this._noiseSamplesAdded = 0;
+  }
+
+  stopRecording(): SimSession {
+    this._recording = false;
+    const endedAt = Date.now();
+    const startedAt = this._sessionStart ?? endedAt;
+
+    const positions = this._recordedPositions;
+    const durationMs = endedAt - startedAt;
+
+    let distanceTravelledM = 0;
+    if (positions.length > 0) {
+      distanceTravelledM = positions[positions.length - 1]?.metadata?.distanceTravelled ?? 0;
+    }
+
+    const avgSpeedKmh =
+      durationMs > 0
+        ? ((distanceTravelledM / (durationMs / 1000)) * 3.6)
+        : 0;
+
+    return {
+      id: this._sessionId ?? uuidV4(),
+      startedAt: new Date(startedAt).toISOString(),
+      endedAt: new Date(endedAt).toISOString(),
+      route: this.config.routeGeometry,
+      positions,
+      scenarios: this._recordedScenarios,
+      stats: {
+        durationMs,
+        distanceTravelledM,
+        avgSpeedKmh,
+        noiseSamplesAdded: this._noiseSamplesAdded,
+        scenariosFired: this._recordedScenarios.length,
+      },
+    };
+  }
+
+  // ── Destroy ──────────────────────────────────────────────────────────────────
+
+  destroy(): void {
+    this._stopTimer();
+    this.injector.destroy();
+    this._state = 'idle';
+    this._position = null;
+    this._recording = false;
+    this._recordedPositions = [];
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────────
+
+  private _startTimer(): void {
+    this._lastTick = Date.now();
+    const intervalMs = Math.round(1000 / this._speedMultiplier);
+    this._timer = setInterval(() => this._tick(), intervalMs);
+  }
+
+  private _stopTimer(): void {
+    if (this._timer !== null) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+
+  private _tick(): void {
+    if (this._state !== 'running') return;
+
+    const now = Date.now();
+    this._lastTick = now;
+
+    const speedMs = (this.config.speedKmh / 3.6);
+    const walkerPos = this.walker.advance(1);
+
+    // Fire any scenarios at this index
+    const activeScenarioName = this.injector.tick(walkerPos.index);
+
+    // Apply noise (skip if GPS_BLACKOUT scenario is active)
+    const activeScenario = this.injector.activeScenario;
+    let coord = walkerPos.coord;
+    let isNoisy = false;
+
+    if (activeScenario?.type !== 'GPS_BLACKOUT') {
+      coord = this.noise.apply(walkerPos.coord);
+      isNoisy = this.noise.currentProfile.stdDevM > 0;
+      if (isNoisy) this._noiseSamplesAdded++;
+    }
+
+    // Compute speed — apply speed spike if active
+    //let speedMs = (this.config.speedKmh / 3.6);
+    if (activeScenario?.type === 'SPEED_SPIKE') {
+      const spikeKmh = (activeScenario.params?.['spikeKmh'] as number | undefined) ?? this.config.speedKmh;
+      //speedMs = spikeKmh / 3.6;
+    }
+
+    // Compute accuracy — degrade if ACCURACY_DROP scenario is active
+    let accuracy = 8 + Math.random() * 6;
+    if (activeScenario?.type === 'ACCURACY_DROP') {
+      accuracy = (activeScenario.params?.['newAccuracyM'] as number | undefined) ?? accuracy;
+    }
+
+    this._buildAndEmitPosition(coord, walkerPos.bearing, walkerPos.distanceTravelled, isNoisy, {
+      speedMs,
+      accuracy,
+      activeScenarioName,
+      segmentIndex: Math.floor(walkerPos.index),
+    });
+
+    if (walkerPos.isComplete) {
+      this._stopTimer();
+
+      if (this.config.loop) {
+        // Restart from the beginning
+        this.walker = new RouteWalker(this.config.routeGeometry, 0);
+        this._startTimer();
+      } else {
+        this._state = 'complete';
+      }
+
+      try { this.config.onRouteComplete?.(); } catch (_) { /* never throw */ }
+    }
+  }
+
+  private _buildAndEmitPosition(
+    coord: [number, number],
+    bearing: number,
+    distanceTravelled: number,
+    isNoisy: boolean,
+    opts?: {
+      speedMs?: number;
+      accuracy?: number;
+      activeScenarioName?: string;
+      segmentIndex?: number;
+    },
+  ): void {
+    const speedMs = opts?.speedMs ?? (this.config.speedKmh / 3.6);
+    const accuracy = opts?.accuracy ?? 8;
+    const ts = Date.now();
+    const locationCoords = {
+      latitude: coord[1],
+      longitude: coord[0],
+      altitude: 0,
+      accuracy,
+      altitudeAccuracy: null,
+      heading: bearing,
+      speed: speedMs,
+    };
+
+    const pos: SimPosition = {
+      coord: coord as [number, number],
+      bearing,
+      speed: speedMs,
+      accuracy,
+      timestamp: ts,
+      coords: locationCoords,
+      location: {
+        coords: locationCoords,
+        timestamp: ts,
+      },
+      metadata: {
+        segmentIndex: opts?.segmentIndex ?? Math.floor(this.walker.currentIndex),
+        distanceTravelled,
+        isNoisy,
+        scenarioActive: opts?.activeScenarioName,
+      },
+    };
+
+    this._position = pos;
+
+    if (this._recording) {
+      this._recordedPositions.push(pos);
+    }
+
+    try { this.config.onPositionUpdate?.(pos); } catch (_) { /* never throw */ }
+  }
+}

package/src/core/__tests__/NoiseEngine.test.ts

@@ -0,0 +1,131 @@
+/**
+ * NoiseEngine unit tests
+ */
+import { describe, it, expect } from 'vitest';
+import { NoiseEngine } from '@ingissa/navcore-simulator';
+import type { Coordinate } from '@ingissa/navcore-core';
+
+const ORIGIN: Coordinate = [0.0, 0.0];
+const RUNS = 500; // statistical test runs
+
+/** Sample standard deviation of an array */
+function stdDev(values: number[]): number {
+  const mean = values.reduce((a, b) => a + b, 0) / values.length;
+  const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+  return Math.sqrt(variance);
+}
+
+describe('NoiseEngine', () => {
+  describe('NONE profile', () => {
+    it('returns the exact same coordinate', () => {
+      const engine = new NoiseEngine(NoiseEngine.NONE);
+      const result = engine.apply(ORIGIN);
+      expect(result[0]).toBe(ORIGIN[0]);
+      expect(result[1]).toBe(ORIGIN[1]);
+    });
+
+    it('never mutates the input coordinate', () => {
+      const engine = new NoiseEngine(NoiseEngine.NONE);
+      const coord: Coordinate = [1.234, 5.678];
+      engine.apply(coord);
+      expect(coord[0]).toBe(1.234);
+      expect(coord[1]).toBe(5.678);
+    });
+  });
+
+  describe('STANDARD profile (12m stddev)', () => {
+    it('applies noise that shifts the coordinate', () => {
+      const engine = new NoiseEngine(NoiseEngine.STANDARD);
+      const result = engine.apply(ORIGIN);
+      // There's a tiny probability of hitting exactly 0 — this test is still valid
+      const changed = result[0] !== ORIGIN[0] || result[1] !== ORIGIN[1];
+      expect(changed).toBe(true);
+    });
+
+    it('stddev of longitude offsets is within expected range (~12m ± 50%)', () => {
+      const engine = new NoiseEngine(NoiseEngine.STANDARD);
+      // 1° longitude ≈ 111320m
+      const lngOffsets: number[] = [];
+      for (let i = 0; i < RUNS; i++) {
+        const r = engine.apply(ORIGIN);
+        lngOffsets.push((r[0] - ORIGIN[0]) * 111320);
+      }
+      const sd = stdDev(lngOffsets);
+      // Should be roughly 12m (allow 50% tolerance for statistical variation)
+      expect(sd).toBeGreaterThan(6);
+      expect(sd).toBeLessThan(24);
+    });
+  });
+
+  describe('Seed determinism', () => {
+    it('same seed produces identical sequence', () => {
+      const profile = { ...NoiseEngine.STANDARD, seed: 42 };
+      const engineA = new NoiseEngine(profile);
+      const engineB = new NoiseEngine(profile);
+
+      for (let i = 0; i < 20; i++) {
+        const a = engineA.apply(ORIGIN);
+        const b = engineB.apply(ORIGIN);
+        expect(a[0]).toBe(b[0]);
+        expect(a[1]).toBe(b[1]);
+      }
+    });
+
+    it('different seeds produce different sequences', () => {
+      const engineA = new NoiseEngine({ ...NoiseEngine.STANDARD, seed: 1 });
+      const engineB = new NoiseEngine({ ...NoiseEngine.STANDARD, seed: 2 });
+
+      const resultsA = Array.from({ length: 10 }, () => engineA.apply(ORIGIN));
+      const resultsB = Array.from({ length: 10 }, () => engineB.apply(ORIGIN));
+
+      // At least one result should differ
+      const anyDiff = resultsA.some((a, i) => a[0] !== resultsB[i]![0]);
+      expect(anyDiff).toBe(true);
+    });
+  });
+
+  describe('CUSTOM profile', () => {
+    it('delegates to customFn', () => {
+      let callCount = 0;
+      const engine = new NoiseEngine({
+        type: 'CUSTOM',
+        stdDevM: 0,
+        customFn: (idx) => {
+          callCount++;
+          return [idx * 0.001, idx * 0.0005];
+        },
+      });
+
+      const r0 = engine.apply(ORIGIN);
+      const r1 = engine.apply(ORIGIN);
+
+      expect(callCount).toBe(2);
+      expect(r0[0]).toBeCloseTo(0 * 0.001, 6);
+      expect(r1[0]).toBeCloseTo(1 * 0.001, 6);
+    });
+
+    it('returns original coord if customFn is missing', () => {
+      const engine = new NoiseEngine({ type: 'CUSTOM', stdDevM: 0 });
+      const result = engine.apply(ORIGIN);
+      expect(result[0]).toBe(ORIGIN[0]);
+    });
+  });
+
+  describe('setProfile', () => {
+    it('hot-swaps from STANDARD to NONE mid-simulation', () => {
+      const engine = new NoiseEngine(NoiseEngine.STANDARD);
+      engine.setProfile(NoiseEngine.NONE);
+      const result = engine.apply([1.0, 2.0]);
+      expect(result[0]).toBe(1.0);
+      expect(result[1]).toBe(2.0);
+    });
+  });
+
+  describe('Static presets', () => {
+    it('CLEAN has stdDevM: 3', () => expect(NoiseEngine.CLEAN.stdDevM).toBe(3));
+    it('STANDARD has stdDevM: 12', () => expect(NoiseEngine.STANDARD.stdDevM).toBe(12));
+    it('URBAN has stdDevM: 25', () => expect(NoiseEngine.URBAN.stdDevM).toBe(25));
+    it('DEGRADED has stdDevM: 50', () => expect(NoiseEngine.DEGRADED.stdDevM).toBe(50));
+    it('NONE has stdDevM: 0', () => expect(NoiseEngine.NONE.stdDevM).toBe(0));
+  });
+});

package/src/core/__tests__/RouteWalker.test.ts

@@ -0,0 +1,139 @@
+/**
+ * RouteWalker unit tests
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RouteWalker } from '@ingissa/navcore-simulator';
+import type { Coordinate } from '@ingissa/navcore-core';
+
+// Simple 5-point straight line going east
+// Each point is ~111m apart (1 second at 400 km/h, but fine for geometry tests)
+const STRAIGHT: Coordinate[] = [
+  [0.000, 0.000],
+  [0.001, 0.000],
+  [0.002, 0.000],
+  [0.003, 0.000],
+  [0.004, 0.000],
+];
+
+describe('RouteWalker', () => {
+  let walker: RouteWalker;
+
+  beforeEach(() => {
+    walker = new RouteWalker(STRAIGHT);
+  });
+
+  it('throws with fewer than 2 points', () => {
+    expect(() => new RouteWalker([[0, 0]])).toThrow();
+    expect(() => new RouteWalker([])).toThrow();
+  });
+
+  it('initialises at index 0 and is not complete', () => {
+    expect(walker.currentIndex).toBe(0);
+    expect(walker.isComplete).toBe(false);
+  });
+
+  it('advance(1) moves to index 1', () => {
+    const pos = walker.advance(1);
+    expect(pos.index).toBe(1);
+    expect(walker.currentIndex).toBe(1);
+    expect(pos.isComplete).toBe(false);
+  });
+
+  it('advance(N) reaches the last point and marks complete', () => {
+    const pos = walker.advance(STRAIGHT.length - 1);
+    expect(pos.isComplete).toBe(true);
+    expect(walker.isComplete).toBe(true);
+  });
+
+  it('advance beyond end clamps to last point', () => {
+    walker.advance(100);
+    expect(walker.currentIndex).toBe(STRAIGHT.length - 1);
+    expect(walker.isComplete).toBe(true);
+  });
+
+  it('advance does nothing after completion', () => {
+    walker.advance(100);
+    const pos = walker.advance(1);
+    expect(pos.index).toBe(STRAIGHT.length - 1);
+  });
+
+  it('interpolate returns midpoint correctly', () => {
+    const mid = walker.interpolate(0, 0.5);
+    expect(mid[0]).toBeCloseTo(0.0005, 5);
+    expect(mid[1]).toBeCloseTo(0.0, 5);
+  });
+
+  it('interpolate clamps fraction to [0, 1]', () => {
+    const start = walker.interpolate(0, -0.5);
+    const startExpected = STRAIGHT[0]!;
+    expect(start[0]).toBeCloseTo(startExpected[0], 5);
+
+    const end = walker.interpolate(0, 1.5);
+    const endExpected = STRAIGHT[1]!;
+    expect(end[0]).toBeCloseTo(endExpected[0], 5);
+  });
+
+  it('bearingAt returns ~90° for eastward segment', () => {
+    const bearing = walker.bearingAt(0);
+    // Should be roughly east (90°)
+    expect(bearing).toBeGreaterThan(85);
+    expect(bearing).toBeLessThan(95);
+  });
+
+  it('bearingAt on last index returns bearing of last segment', () => {
+    const bearing = walker.bearingAt(STRAIGHT.length - 1);
+    expect(bearing).toBeGreaterThan(85);
+    expect(bearing).toBeLessThan(95);
+  });
+
+  it('distanceToIndex(0) is 0', () => {
+    expect(walker.distanceToIndex(0)).toBe(0);
+  });
+
+  it('distanceToIndex increases monotonically', () => {
+    for (let i = 1; i < STRAIGHT.length; i++) {
+      expect(walker.distanceToIndex(i)).toBeGreaterThan(walker.distanceToIndex(i - 1));
+    }
+  });
+
+  it('totalDistanceM is positive and equals distanceToIndex(last)', () => {
+    const total = walker.totalDistanceM;
+    expect(total).toBeGreaterThan(0);
+    expect(total).toBeCloseTo(walker.distanceToIndex(STRAIGHT.length - 1), 1);
+  });
+
+  it('totalPoints equals geometry length', () => {
+    expect(walker.totalPoints).toBe(STRAIGHT.length);
+  });
+
+  it('seek jumps to the correct index', () => {
+    const pos = walker.seek(3);
+    expect(pos.index).toBe(3);
+    expect(walker.currentIndex).toBe(3);
+    expect(pos.isComplete).toBe(false);
+  });
+
+  it('seek recalculates bearing at new position', () => {
+    const pos = walker.seek(2);
+    // Eastward segment → bearing ~90°
+    expect(pos.bearing).toBeGreaterThan(85);
+    expect(pos.bearing).toBeLessThan(95);
+  });
+
+  it('seek to last index marks complete', () => {
+    const pos = walker.seek(STRAIGHT.length - 1);
+    expect(pos.isComplete).toBe(true);
+  });
+
+  it('startIndex constructor param positions correctly', () => {
+    const w = new RouteWalker(STRAIGHT, 2);
+    expect(w.currentIndex).toBe(2);
+    expect(w.distanceToIndex(2)).toBeGreaterThan(0);
+  });
+
+  it('advance with fractional steps interpolates coord', () => {
+    const pos = walker.advance(0.5);
+    // Should be halfway between point 0 and 1
+    expect(pos.coord[0]).toBeCloseTo(0.0005, 4);
+  });
+});