@molecule/app-geolocation

Geolocation interface for molecule.dev.

Provides a unified API for GPS/location services that works across different platforms (web, native containers, etc.): one-off reads (getCurrentPosition), continuous watches (watchPosition / clearWatch), a permission flow (checkPermission / requestPermission), and a pure calculateDistance helper.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import {
  checkPermission,
  clearWatch,
  getCurrentPosition,
  requestPermission,
  watchPosition,
} from '@molecule/app-geolocation'

async function showNearby(): Promise<void> {
  if ((await checkPermission()) !== 'granted') {
    const p = await requestPermission() // from a user gesture
    if (p !== 'granted') return // offer manual address entry instead
  }
  const { coords } = await getCurrentPosition({ enableHighAccuracy: false })
  console.log(coords.latitude, coords.longitude)
}

function trackRun(onPoint: (lat: number, lng: number) => void): () => void {
  const watchId = watchPosition((pos) => onPoint(pos.coords.latitude, pos.coords.longitude))
  return () => clearWatch(watchId) // ALWAYS clear on unmount
}

Type

native

Installation

npm install @molecule/app-geolocation @molecule/app-bond

API

Interfaces

`Coordinates`

Geographic coordinates (latitude, longitude, accuracy, altitude, heading, speed).

interface Coordinates {
  /**
   * Latitude in decimal degrees.
   */
  latitude: number

  /**
   * Longitude in decimal degrees.
   */
  longitude: number

  /**
   * Accuracy in meters.
   */
  accuracy: number

  /**
   * Altitude in meters (if available).
   */
  altitude?: number

  /**
   * Altitude accuracy in meters (if available).
   */
  altitudeAccuracy?: number

  /**
   * Heading in degrees (0-360, if available).
   */
  heading?: number

  /**
   * Speed in m/s (if available).
   */
  speed?: number
}

`Position`

Geolocation position containing coordinates and a timestamp.

interface Position {
  /**
   * Geographic coordinates.
   */
  coords: Coordinates

  /**
   * Timestamp of the position.
   */
  timestamp: number
}

`PositionOptions`

Options for position queries (high accuracy mode, max cached age, timeout).

interface PositionOptions {
  /**
   * Enable high accuracy mode.
   */
  enableHighAccuracy?: boolean

  /**
   * Maximum age of cached position in ms.
   */
  maximumAge?: number

  /**
   * Timeout in ms.
   */
  timeout?: number
}

`WatchOptions`

Watch options (extends position options).

interface WatchOptions extends PositionOptions {
  /**
   * Minimum distance change in meters before triggering update.
   */
  distanceFilter?: number
}

`GeolocationError`

Geolocation error with code (permission_denied, position_unavailable, timeout) and message.

interface GeolocationError {
  /**
   * Error code.
   */
  code: 'permission_denied' | 'position_unavailable' | 'timeout' | 'unknown'

  /**
   * Error message.
   */
  message: string
}

`GeolocationProvider`

Geolocation provider interface.

All geolocation providers must implement this interface.

interface GeolocationProvider {
  /**
   * Checks the current permission status.
   * @returns The current location permission state.
   */
  checkPermission(): Promise<LocationPermission>

  /**
   * Requests location permission.
   */
  requestPermission(): Promise<LocationPermission>

  /**
   * Gets the current position.
   */
  getCurrentPosition(options?: PositionOptions): Promise<Position>

  /**
   * Watches position changes.
   * Returns an ID that can be used to stop watching.
   */
  watchPosition(
    onSuccess: PositionCallback,
    onError?: ErrorCallback,
    options?: WatchOptions,
  ): string

  /**
   * Stops watching position changes.
   */
  clearWatch(watchId: string): void

  /**
   * Calculates distance between two coordinates in meters.
   * @returns The distance in meters between the two coordinates.
   */
  calculateDistance(
    from: { latitude: number; longitude: number },
    to: { latitude: number; longitude: number },
  ): number
}

`CreateWebGeolocationProviderOptions`

Options for creating a web geolocation provider.

interface CreateWebGeolocationProviderOptions {
  /**
   * Optional translation function for i18n support.
   * When provided, error messages will be passed through this function.
   */
  t?: TranslateFn
}

Types

`LocationPermission`

Location permission state: granted, denied, or prompt (not yet requested).

type LocationPermission = 'granted' | 'denied' | 'prompt'

`PositionCallback`

Callback invoked with a resolved geographic position.

type PositionCallback = (position: Position) => void

position — The resolved geographic position data.

`ErrorCallback`

Callback invoked when a geolocation error occurs.

type ErrorCallback = (error: GeolocationError) => void

Functions

`checkPermission()`

Checks the current location permission status.

function checkPermission(): Promise<LocationPermission>

Returns: The current location permission state.

`requestPermission()`

Requests location permission from the user.

function requestPermission(): Promise<LocationPermission>

Returns: The resulting permission state after the request.

`getCurrentPosition(options)`

Gets the device's current geographic position.

function getCurrentPosition(options?: PositionOptions): Promise<Position>

options — Configuration for accuracy, timeout, and caching behavior.

Returns: The current position with coordinates and timestamp.

`watchPosition(onSuccess, onError, options)`

Watches for continuous position changes.

function watchPosition(
  onSuccess: PositionCallback,
  onError?: ErrorCallback,
  options?: WatchOptions,
): string

onSuccess — Callback invoked with each new position update.
onError — Callback invoked when a geolocation error occurs.
options — Configuration for accuracy, distance filter, and timing.

Returns: A watch identifier that can be passed to clearWatch to stop watching.

`clearWatch(watchId)`

Stops watching position changes for the given watch.

function clearWatch(watchId: string): void

watchId — The identifier returned by watchPosition.

Returns: void

`calculateDistance(from, to)`

Calculates the distance between two geographic coordinates.

function calculateDistance(
  from: { latitude: number; longitude: number },
  to: { latitude: number; longitude: number },
): number

from — The starting coordinate.
from.latitude — The starting latitude in decimal degrees.
from.longitude — The starting longitude in decimal degrees.
to — The destination coordinate.
to.latitude — The destination latitude in decimal degrees.
to.longitude — The destination longitude in decimal degrees.

Returns: The distance in meters between the two coordinates.

`setProvider(provider)`

Sets the geolocation provider implementation.

function setProvider(provider: GeolocationProvider): void

provider — The provider implementation.

`getProvider()`

Gets the current geolocation provider, falling back to the web implementation.

function getProvider(): GeolocationProvider

Returns: The active geolocation provider instance.

`hasProvider()`

Checks if a geolocation provider has been bonded.

function hasProvider(): boolean

Returns: Whether a geolocation provider is currently registered.

`toRadians(degrees)`

Converts degrees to radians.

function toRadians(degrees: number): number

degrees — The angle in degrees to convert.

Returns: The angle in radians.

`haversineDistance(from, to)`

Calculates the distance between two coordinates using the Haversine formula.

function haversineDistance(
  from: { latitude: number; longitude: number },
  to: { latitude: number; longitude: number },
): number

from — The starting coordinate.
from.latitude — The starting latitude in decimal degrees.
from.longitude — The starting longitude in decimal degrees.
to — The destination coordinate.
to.latitude — The destination latitude in decimal degrees.
to.longitude — The destination longitude in decimal degrees.