geolocation

Promise-based and observable wrapper around navigator.geolocation.

Module geolocation | Source packages/front/fw/src/dom/sensors/geolocation.js | Deps none | Worker-safe no

Wraps the browser Geolocation API with a simplified interface. current() returns a Promise, watch() returns a stop fn. Normalized payload {lat, lon} (not coords.latitude).

Resolve

const geolocation = runtime.resolve('geolocation');
// Returns: { isSupported, current, watch }

API

Type Position

{
    lat: number,
    lon: number,
    accuracy: number,          // metres
    altitude: number | null,
    altitudeAccuracy: number | null,
    heading: number | null,    // degrees 0-360 from north
    speed: number | null,      // m/s
    timestamp: number,         // ms Unix
}

Options (forwarded to the native API)

{
    enableHighAccuracy: boolean,  // GPS if available (slower, more accurate)
    timeout: number,              // ms before PositionError.TIMEOUT
    maximumAge: number,           // ms — accept cached position
}

Examples

Single position

const geolocation = runtime.resolve('geolocation');

try {
    const pos = await geolocation.current({ enableHighAccuracy: true });
    console.log(`${pos.lat}, ${pos.lon} ± ${pos.accuracy}m`);
} catch (err) {
    if (err.code === 1) console.log('Permission denied');
    if (err.code === 2) console.log('Position unavailable');
    if (err.code === 3) console.log('Timeout');
}

Real-time tracking

const stop = geolocation.watch(pos => {
    updateMap(pos.lat, pos.lon);
}, { enableHighAccuracy: true });

// Later:
stop();

Combined with permissions (plan 29)

const permissions = runtime.resolve('permissions');
const status = await permissions.query('geolocation');
if (status === 'granted') {
    const pos = await geolocation.current();
}

Error codes

Notes

• HTTPS required except localhost — the Geolocation API is blocked on HTTP.
• Explicit user permission required — combine with permissions.query('geolocation') for proactive UX.
• Accuracy depends on the device: GPS (accurate), wifi (medium), IP (low).
• watch returns the stop fn directly (not an object).
• current() throws with err.code accessible to distinguish cases.

See also

• permissions — permission status query before the call
• sensors — inertial sensors (gyro, accelerometer)