@kinesisjs/core

Pure-TypeScript interpolation engine — framework-agnostic, ~5 KB minified+gzipped.

Mathematical engine for smooth movement between periodic position updates. No dependency on any map library or UI framework; extends through the adapter pattern.

Scope

• rAF-based clock — 60fps tick, no tab-background catch-up jumps
• Interpolation modes — linear, cubic, geodesic, smooth (3-point Catmull-Rom), none, adaptive
• Playout buffer — playout: { pace, bufferMs } | 'auto' re-times jittery ingest into a constant per-segment render pace
• Web Worker mode — worker: true runs the tick loop off the main thread (adapter stays on it)
• Bounded memory — ring slot pattern, allocation-free hot path
• Multi-state lifecycle — active / warning / stale / completed + markCompleted API
• Sanity checks — anomalous-jump (distance vs. speed) and sharp-turn (heading) detection
• Typed event bus — tick, vehicleadded, vehiclewarning, vehiclestale, vehiclecompleted, vehicleremoved, ingest, error
• TrackAdapter interface — map adapters implement this contract
• CustomInterpolator interface — sync/async; the extension point behind @kinesisjs/route-aware
• math-utils — haversineDistance, shortestArcDiff, linearLerp, catmullRomLerp as public exports

Out of scope

• Map feature lifecycle → adapter packages
• Framework lifecycle → wrapper packages
• Data fetching, WebSocket management → application code

Installation

pnpm add @kinesisjs/core

Usage

import { Tracker } from '@kinesisjs/core';
import type { TrackAdapter, TrailPoint, Position } from '@kinesisjs/core';

class MyAdapter implements TrackAdapter {
  addVehicle(id: string, p: TrailPoint): void {
    /* draw on your map */
  }
  updatePosition(id: string, p: TrailPoint): void {
    /* feature.setCoordinates */
  }
  removeVehicle(id: string): void {
    /* remove from layer */
  }
  destroy(): void {
    /* cleanup */
  }
  // Optional: updateOpacity(id, opacity), getMemoryEstimate()
}

const tracker = new Tracker({
  adapter: new MyAdapter(),
  interpolation: 'adaptive',
});

tracker.start();
tracker.on('vehiclestale', ({ vehicleId }) => console.log(`${vehicleId} stale`));
tracker.on('error', (e) => console.warn(`[${e.code}]`, e.message));

// From your WebSocket handler:
const positions: Position[] = [{ id: 'v1', lng: 29, lat: 41 }];
tracker.ingest(positions);

Jittery feeds

When the gap between fixes varies (e.g. 0.5–3 s), pair the playout buffer with smooth interpolation — smooth shapes the geometry (no kinks at waypoints), playout flattens the tempo:

const tracker = new Tracker({
  adapter: new MyAdapter(),
  interpolation: 'smooth', // 3-point Catmull-Rom
  playout: 'auto', // measure ingest cadence, equalise the render pace
});

Public API

// Classes
export { Tracker, WorkerTracker, Clock, Interpolator, AdaptiveInterpolator, EventBus, Sweeper };

// Utilities
export { catmullRomLerp, haversineDistance, linearLerp, shortestArcDiff };

// Types
export type {
  Position,
  TrailPoint,
  VehicleSlot,
  VehicleState,
  SweepResult,
  InitialPositionBehavior,
  TrackerOptions,
  TrackerStats,
  TrackerEventMap,
  TrackAdapter,
  InterpolationMode,
  CustomInterpolator,
  InterpolationOptions,
  AdaptiveOptions,
  AdaptiveBehavior,
  TrackerError,
  TrackerErrorCode,
  FadeAnimationOptions,
  PlayoutOptions,
  PlayoutQueueEntry,
};

Performance

Interpolator.compute linear: ~50 ns/call (20M ops/sec). Tracker.tick with 1000 vehicles: ~0.15 ms (about 1% of the 60fps tick budget).

License

MIT