@magmacomputing/tempo-plugin-spatial

A comprehensive Community plugin for the Tempo ecosystem providing GIS spatial geometry, Great-Circle navigation, transit velocity and impossible travel anomaly detection, spatial geofencing, and natural solar time offset calculations.

By decoupling geographic mathematics from network lookup into a dedicated plugin, @magmacomputing/tempo core remains zero-network, lightweight, and purely deterministic.

---

Key Features

• Great-Circle Navigation: Haversine distance (Tempo.spatial.distance), compass bearing (Tempo.spatial.bearing), and geographic midpoint (Tempo.spatial.midpoint) between any two coordinates.
• Impossible Travel Detection: Tempo.spatial.isImpossibleTravel(from, to) flags sessions with transit speeds exceeding commercial aviation feasibility (default: > 900 km/h).
• Transit Velocity: Tempo.spatial.velocity(from, to) computes speed of travel between two timestamped Tempo instances.
• Spatial Geofencing: Radial proximity check (isWithin) and rectangular bounding box containment (inBoundingBox) with antimeridian crossing support.
• Natural Solar Time Offset: Tempo.spatial.solarOffset(coords) derives meridian offset in minutes (4 min/degree) for circadian rhythm alignment.
• Immutable Namespace: Tempo.spatial is recursively frozen and mounted tamper-proof onto Tempo.

---

Installation

npm install @magmacomputing/tempo-plugin-spatial

---

Quickstart

Interactive Demo (@magmacomputing/tempo-plugin-spatial)

Open in Full REPL↗

// 🧭 Great-Circle Navigation & Spatial Geofencing (@magmacomputing/tempo-plugin-spatial)
const { SpatialPlugin } = await import('@magmacomputing/tempo-plugin-spatial');
Tempo.use(SpatialPlugin);

const sydney = { lat: -33.8688, lng: 151.2093 };
const london = { lat: 51.5074, lng: -0.1278 };

// 1. Haversine Distance & Initial Bearing
const distKm = Tempo.spatial.distance(sydney, london, 'km');
const heading = Tempo.spatial.bearing(sydney, london);
console.log('Distance Sydney -> London:', distKm.toFixed(1), 'km');
console.log('Compass Heading:', heading.toFixed(1) + '°');

// 2. Geographic Midpoint
const mid = Tempo.spatial.midpoint(sydney, london);
console.log('Great-Circle Midpoint:', `${mid.latitude.toFixed(2)}°, ${mid.longitude.toFixed(2)}° (${mid.sphere})`);

// 3. Impossible Travel Anomaly Detection
const loginSydney = new Tempo('2026-03-31T08:00:00Z', { geo: sydney });
const loginLondon = new Tempo('2026-03-31T09:30:00Z', { geo: london }); // 1.5h later
const speed = loginSydney.spatialVelocity(loginLondon);
const isAnomaly = Tempo.spatial.isImpossibleTravel(loginSydney, loginLondon);

console.log('Transit Velocity:', speed.toFixed(1), 'km/h');
console.log('Impossible Travel Alert?', isAnomaly);

return `Sydney -> London: ${distKm.toFixed(0)} km (Midpoint: ${mid.latitude.toFixed(1)}°, ${mid.longitude.toFixed(1)}°)`;

Executes 100% in browser via native ESM sandbox

import { Tempo } from '@magmacomputing/tempo';
import { SpatialPlugin } from '@magmacomputing/tempo-plugin-spatial';

Tempo.use(SpatialPlugin);

const sydney = { lat: -33.8688, lng: 151.2093 };
const london = { lat: 51.5074, lng: -0.1278 };

const distKm = Tempo.spatial.distance(sydney, london, 'km');
console.log('Distance:', distKm.toFixed(1), 'km'); // ~16988.0 km

const heading = Tempo.spatial.bearing(sydney, london);
console.log('Compass Bearing:', heading.toFixed(1) + '°'); // ~319.2° (NW)

const mid = Tempo.spatial.midpoint(sydney, london);
console.log('Midpoint:', mid.latitude, mid.longitude);

Auto-Installation (Side-Effect Import)

import { Tempo } from '@magmacomputing/tempo';
import '@magmacomputing/tempo-plugin-spatial/install';

Impossible Travel Anomaly Detection

const login1 = new Tempo('2026-06-21T10:00:00Z', {
  geo: { lat: 51.5074, lng: -0.1278 }, // London
});

const login2 = new Tempo('2026-06-21T11:00:00Z', {
  geo: { lat: 40.7128, lng: -74.0060 }, // New York (1 hour later)
});

const speed = Tempo.spatial.velocity(login1, login2);
console.log('Velocity:', speed.toFixed(1), 'km/h'); // ~5570.2 km/h

const alert = Tempo.spatial.isImpossibleTravel(login1, login2);
console.log('Impossible Travel Alert?', alert); // true

---

API Reference

Comprehensive Tempo.spatial API Surface

Method / Property	Category	Description
Tempo.spatial.distance(from, to, unit?)	Navigation	Great-Circle Haversine distance between two coordinates ('km', 'miles', or 'm').
Tempo.spatial.bearing(from, to, opts?)	Navigation	Initial forward compass azimuth bearing (0°..360°) from origin to destination.
Tempo.spatial.midpoint(from, to)	Navigation	Exact geographic midpoint along the Great-Circle path between two coordinates with hemisphere inference.
Tempo.spatial.velocity(from, to, opts?)	Security / Transit	Speed of travel between two timestamped instances ('km', 'miles', or 'm'; time unit 'hh', 'ss', 'mi').
Tempo.spatial.isImpossibleTravel(from, to, opts?)	Security / Transit	Evaluates whether travel between timestamped instances exceeds physical commercial aviation feasibility (default: > 900 km/h).
Tempo.spatial.isWithin(from, to, maxDist, unit?)	Geofencing	Checks whether two points fall within a maximum radial distance threshold.
Tempo.spatial.inBoundingBox(coords, bbox)	Geofencing	Checks whether a coordinate point falls inside a geographic bounding box with antimeridian crossing support.
Tempo.spatial.solarOffset(coords, opts?)	Solar Timing	Computes natural solar time offset (in minutes, seconds, or hours) derived from meridian offset (4 min/deg).

Fluent Instance Methods

Instance Method	Description
t.spatialDistance(to, unit?)	Calculates Great-Circle distance from this instance's coordinates to target coordinates.
t.spatialBearing(to, opts?)	Computes initial forward compass bearing from this instance to target coordinates.
t.spatialVelocity(to, opts?)	Calculates travel velocity between this instance and target timestamped instance.
t.spatialSolarOffset(opts?)	Computes natural solar time offset for this instance's coordinates.
t.isWithin(to, maxDist, unit?)	Checks if this instance is within a specified proximity radius of target coordinates.
t.inBoundingBox(bbox)	Checks if this instance falls inside a rectangular bounding box.

---

Topic Guides

Explore detailed guides on specific capabilities:

• Transit & Navigation: Great-Circle distance, compass bearing, geographic midpoint, transit velocity, and impossible travel anomaly detection.
• Spatial Geofencing: Proximity checking (isWithin), rectangular bounding boxes (inBoundingBox), and antimeridian crossing resolution.
• Natural Solar Time Offset: Longitude delta calculations (solarOffset), meridian drift, and circadian rhythm alignment.
• Production Use Cases & Architectural Patterns: Zero-trust impossible travel detection, depot geofencing, flight sector planning, and physical solar noon alignment.

---

License

This is a Community plugin. It is completely free and open-source for personal and commercial use under the MIT license.