@tokamakdev/plugin-location 0.1.0-beta.127 → 0.1.0-beta.129

package/src/index.ts

@@ -1,9 +1,8 @@
-import { Plugin, lifecycleStage, type JsonStream, type TokamakContext } from "@tokamakdev/plugin";
-import { valueStream } from "@tokamakdev/plugin/streams";
+import { capabilitiesOf, lifecycleStage, platformApi, type JsonStream, type TokamakContext } from "@tokamakdev/plugin";
 
-import * as android from "./android.js";
-import * as apple from "./apple.js";
-import { backgroundDenied, permissionDenied, unavailable } from "./errors.js";
+import { android } from "./android.generated.js";
+import { apple } from "./apple.generated.js";
+import { backgroundDenied, permissionDenied, timedOut, unavailable } from "./errors.js";
 import type {
   LocationErrorEvent,
   LocationPermission,
@@ -21,157 +20,120 @@ import type {
 
 export type * from "./types.js";
 
-class Location extends Plugin {
-  constructor(ctx: TokamakContext) {
-    super(ctx, "location");
-  }
-
-  /**
-   * Applies long-term location awareness, replacing the previous configuration, which the plugin keeps
-   * and applies again at each start. Rejects on Apple platforms with `NotSupportedError` where the
-   * device cannot monitor significant changes.
-   */
-  setup(config: SetupConfig): Promise<void> {
-    return this.call("setup", config);
-  }
-
-  /**
-   * The device's position, asking for in-use permission where the user has not answered. Rejects
-   * with `NotAllowedError` without it, `TimeoutError` after `timeout`, and `NotReadableError`
-   * when location is unavailable. Asking off screen rejects with `NeedsUIError`, as
-   * `requestPermission` does.
-   */
-  async getCurrentPosition(options: PositionOptions = {}): Promise<Position> {
-    await this.#authorize();
-    const position = await this.#platform().currentPosition(this.ctx, options);
-    if (position) return position;
-    // Android finds no position in the background without background permission.
-    const background = await lifecycleStage(this.ctx) === "background";
-    throw background && (await this.permission()).background !== "granted" ? backgroundDenied() : unavailable("Location is unavailable");
-  }
-
-  /**
-   * Positions as the device moves, after `getCurrentPosition`'s permission checks, which can reject
-   * with `NeedsUIError` off screen. A slow reader receives the newest.
-   */
-  watchPosition(): JsonStream<Position> {
-    return valueStream<Position>(async (next, error) => {
-      await this.#authorize();
-      return this.#platform().watchPositions(this.ctx, next, error);
-    }, "dropOldest");
-  }
+export function location(ctx: TokamakContext) {
+  const native = platformApi(ctx, { apple, android });
 
   /** Requires location services and in-use permission, asking for it where the user has not answered. */
-  async #authorize(): Promise<void> {
-    if (!await this.servicesEnabled()) throw unavailable("Location services are disabled");
-    let { inUse } = await this.permission();
-    if (inUse === "prompt") ({ inUse } = await this.requestPermission());
+  async function authorize(): Promise<void> {
+    if (!await native.servicesEnabled()) throw unavailable("Location services are disabled");
+    let { inUse } = await native.permission();
+    if (inUse === "prompt") ({ inUse } = await native.requestPermission());
     if (inUse !== "granted") throw permissionDenied();
   }
 
-  /** The platform's composition of its location SDK. */
-  #platform(): typeof apple | typeof android {
-    switch (this.ctx.platform) {
-      case "ios":
-      case "macos":
-        return apple;
-      case "android":
-        return android;
-      default:
-        throw new DOMException("Location is not supported on this platform", "NotSupportedError");
-    }
-  }
-
-  /** The app's in-use and background permission, and the precision it gets. Never asks. */
-  permission(): Promise<LocationPermission> {
-    return this.call("permission");
-  }
-
-  /**
-   * Asks for in-use permission, and for what `options` names, where the user has not answered.
-   * Android asks for background permission once in-use permission is granted. Rejects with
-   * `NeedsUIError` when a prompt would show off screen.
-   */
-  requestPermission(options: PermissionRequest = {}): Promise<LocationPermission> {
-    return this.call("requestPermission", options);
-  }
-
-  /** Whether location services are on for the device. While they are off, nothing locates. */
-  servicesEnabled(): Promise<boolean> {
-    return this.call("servicesEnabled");
-  }
-
-  /**
-   * Opens the app's page in the system settings, where the user changes its location permission.
-   * Rejects with `NeedsUIError` off screen on iOS and Android.
-   */
-  openSettings(): Promise<void> {
-    return this.call("openSettings");
-  }
-
-  /**
-   * Starts continuous tracking, replacing any running, until `stopUpdates`; `setup` gives long-term
-   * awareness instead. The updates' positions reach `onLocationUpdate`, including after the system
-   * ended the app. Rejects with `NotAllowedError` without in-use permission, and on iOS with
-   * `NeedsUIError` off screen. Android's `foregroundService` rejects with `NotSupportedError`
-   * without the `background-updates` build setting, and with `NeedsUIError` when Android does not
-   * allow the service to start off screen.
-   */
-  startUpdates(options: UpdateOptions = {}): Promise<void> {
-    return this.call("startUpdates", options);
-  }
-
-  stopUpdates(): Promise<void> {
-    return this.call("stopUpdates");
-  }
-
-  /** The options of the running updates, or null when none are running. */
-  getUpdates(): Promise<UpdateOptions | null> {
-    return this.call("getUpdates");
-  }
-
-  /**
-   * Monitors a circular region, replacing one with the same `id`, until `removeRegion`. Its entries
-   * and exits reach `onRegionTransition`, including when the system launches the app for one. A
-   * region starts outside, so a device already inside reports an entry. Rejects with
-   * `NotAllowedError` without precise location, and with `QuotaExceededError` beyond Apple's 20.
-   */
-  addRegion(region: Region): Promise<void> {
-    return this.call("addRegion", region);
-  }
-
-  /** The monitored regions. */
-  getRegions(): Promise<MonitoredRegion[]> {
-    return this.call("getRegions");
-  }
-
-  removeRegion(id: string): Promise<void> {
-    return this.call("removeRegion", { id });
-  }
-
-  /** Receives the updates the Worker's `onLocationUpdate` receives, while the listening page or Worker runs. */
-  onLocationUpdate(): JsonStream<LocationUpdate> {
-    return this.stream("onLocationUpdate", null, "dropOldest");
-  }
-
-  /** Receives the transitions the Worker's `onRegionTransition` receives, while the listening page or Worker runs. */
-  onRegionTransition(): JsonStream<RegionTransition> {
-    return this.stream("onRegionTransition");
-  }
-
-  /**
-   * Receives the visits the Worker's `onVisit` receives, while the listening page or Worker runs.
-   * @platforms ios macos
-   */
-  onVisit(): JsonStream<Visit> {
-    return this.stream("onVisit");
-  }
-
-  /** Receives the failures the Worker's `onLocationError` receives, while the listening page or Worker runs. */
-  onLocationError(): JsonStream<LocationErrorEvent> {
-    return this.stream("onLocationError");
-  }
+  return {
+    /** Whether each operation is implemented where the app runs, without calling it. Permission is not reported. */
+    get capabilities(): Readonly<Record<string, boolean>> {
+      return capabilitiesOf(ctx, "location");
+    },
+
+    /**
+     * Applies long-term location awareness, replacing the previous configuration, which the plugin
+     * keeps and applies again at each start. Rejects on Apple platforms with `NotSupportedError` where
+     * the device cannot monitor significant changes.
+     */
+    setup: (config: SetupConfig): Promise<void> => native.setup(config),
+
+    /**
+     * The device's position, asking for in-use permission where the user has not answered. Rejects
+     * with `NotAllowedError` without it, `TimeoutError` after `timeout`, and `NotReadableError`
+     * when location is unavailable. Asking off screen rejects with `NeedsUIError`, as
+     * `requestPermission` does.
+     */
+    async getCurrentPosition({ maximumAge = 0, timeout }: PositionOptions = {}): Promise<Position> {
+      await authorize();
+      // JSON has no Infinity, which accepts any recent position.
+      const recent = await native.recentPosition(Math.min(maximumAge, Number.MAX_VALUE));
+      if (recent) return recent;
+      const located = new AbortController();
+      const timer = timeout === undefined ? undefined : setTimeout(() => { located.abort(timedOut()); }, timeout);
+      const position = await platformApi(ctx, { apple, android }, located.signal).currentPosition()
+        .finally(() => { clearTimeout(timer); });
+      if (position) return position;
+      // Android finds no position in the background without background permission.
+      const background = await lifecycleStage(ctx) === "background";
+      throw background && (await native.permission()).background !== "granted" ? backgroundDenied() : unavailable("Location is unavailable");
+    },
+
+    /**
+     * Positions as the device moves, after `getCurrentPosition`'s permission checks, which can reject
+     * with `NeedsUIError` off screen. A slow reader receives the newest.
+     */
+    async watchPosition(): Promise<JsonStream<Position>> {
+      await authorize();
+      return native.watchPosition();
+    },
+
+    /** The app's in-use and background permission, and the precision it gets. Never asks. */
+    permission: (): Promise<LocationPermission> => native.permission(),
+
+    /**
+     * Asks for in-use permission, and for what `options` names, where the user has not answered.
+     * Android asks for background permission once in-use permission is granted. Rejects with
+     * `NeedsUIError` when a prompt would show off screen.
+     */
+    requestPermission: (options?: PermissionRequest): Promise<LocationPermission> => native.requestPermission(options),
+
+    /** Whether location services are on for the device. While they are off, nothing locates. */
+    servicesEnabled: (): Promise<boolean> => native.servicesEnabled(),
+
+    /**
+     * Opens the app's page in the system settings, where the user changes its location permission.
+     * Rejects with `NeedsUIError` off screen on iOS and Android.
+     */
+    openSettings: (): Promise<void> => native.openSettings(),
+
+    /**
+     * Starts continuous tracking, replacing any running, until `stopUpdates`; `setup` gives long-term
+     * awareness instead. The updates' positions reach `onLocationUpdate`, including after the system
+     * ended the app. Rejects with `NotAllowedError` without in-use permission, and on iOS with
+     * `NeedsUIError` off screen. Android's `foregroundService` rejects with `NotSupportedError`
+     * without the `background-updates` build setting, and with `NeedsUIError` when Android does not
+     * allow the service to start off screen.
+     */
+    startUpdates: (options?: UpdateOptions): Promise<void> => native.startUpdates(options),
+
+    stopUpdates: (): Promise<void> => native.stopUpdates(),
+
+    /** The options of the running updates, or null when none are running. */
+    getUpdates: (): Promise<UpdateOptions | null> => native.getUpdates(),
+
+    /**
+     * Monitors a circular region, replacing one with the same `id`, until `removeRegion`. Its entries
+     * and exits reach `onRegionTransition`, including when the system launches the app for one. A
+     * region starts outside, so a device already inside reports an entry. Rejects with
+     * `NotAllowedError` without precise location, and with `QuotaExceededError` beyond Apple's 20.
+     */
+    addRegion: (region: Region): Promise<void> => native.addRegion(region),
+
+    /** The monitored regions. */
+    getRegions: (): Promise<MonitoredRegion[]> => native.getRegions(),
+
+    removeRegion: (id: string): Promise<void> => native.removeRegion(id),
+
+    /** Receives the updates the Worker's `onLocationUpdate` receives, while the listening page or Worker runs. */
+    onLocationUpdate: (): JsonStream<LocationUpdate> => native.onLocationUpdate(),
+
+    /** Receives the transitions the Worker's `onRegionTransition` receives, while the listening page or Worker runs. */
+    onRegionTransition: (): JsonStream<RegionTransition> => native.onRegionTransition(),
+
+    /**
+     * Receives the visits the Worker's `onVisit` receives, while the listening page or Worker runs.
+     * @platforms ios macos
+     */
+    onVisit: (): JsonStream<Visit> => apple(ctx).onVisit(),
+
+    /** Receives the failures the Worker's `onLocationError` receives, while the listening page or Worker runs. */
+    onLocationError: (): JsonStream<LocationErrorEvent> => native.onLocationError(),
+  };
 }
-
-
-export function location(ctx: TokamakContext): Location { return new Location(ctx); }

package/src/types.ts

@@ -1,11 +1,12 @@
+/** A position's coordinates, without those the device does not report. */
 export interface Coordinates {
   readonly latitude: number;
   readonly longitude: number;
   readonly accuracy: number;
-  readonly altitude: number | null;
-  readonly altitudeAccuracy: number | null;
-  readonly heading: number | null;
-  readonly speed: number | null;
+  readonly altitude?: number;
+  readonly altitudeAccuracy?: number;
+  readonly heading?: number;
+  readonly speed?: number;
 }
 
 export interface Position {
@@ -157,10 +158,10 @@ export interface Visit {
   readonly longitude: number;
   /** In metres. */
   readonly accuracy: number;
-  /** Milliseconds since the epoch, or null when unknown. */
-  readonly arrival: number | null;
-  /** Milliseconds since the epoch, or null before the user leaves. */
-  readonly departure: number | null;
+  /** Milliseconds since the epoch, absent when unknown. */
+  readonly arrival?: number;
+  /** Milliseconds since the epoch, absent before the user leaves. */
+  readonly departure?: number;
 }
 
 /** A failure of a background location service. */
@@ -174,15 +175,3 @@ export interface LocationErrorEvent {
 
 export type Listener<T> = (event: T) => void;
 export type ErrorListener = (error: DOMException) => void;
-
-declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace -- events are declared by merging into Tokamak.Events.
-  namespace Tokamak {
-    interface Events {
-      "location.update": LocationUpdate;
-      "location.region": RegionTransition;
-      "location.visit": Visit;
-      "location.error": LocationErrorEvent;
-    }
-  }
-}

package/tokamak-plugin.json

@@ -1,26 +1,6 @@
 {
   "schemaVersion": 2,
   "id": "location",
-  "bindings": {
-    "apple": {
-      "sdk": "26.2",
-      "modules": [
-        "CoreLocation",
-        "_LocationEssentials"
-      ]
-    },
-    "android": {
-      "sdk": 35,
-      "modules": [
-        "android.location",
-        "android.content.Context",
-        "android.os.CancellationSignal",
-        "android.os.SystemClock",
-        "java.util.concurrent.Executor",
-        "java.util.function.Consumer"
-      ]
-    }
-  },
   "settings": {
     "background": {
       "kind": "boolean",
@@ -58,33 +38,13 @@
   "build": "build/index.mjs",
   "platforms": {
     "macos": {
-      "class": "TokamakLocationPlugin",
-      "sources": [
-        "apple/LocationEvents.swift",
-        "apple/LocationPlugin.swift",
-        "apple/LocationRegions.swift",
-        "apple/LocationUpdates.swift"
-      ]
+      "class": "TokamakLocationPlugin"
     },
     "ios": {
-      "class": "TokamakLocationPlugin",
-      "sources": [
-        "apple/LocationEvents.swift",
-        "apple/LocationPlugin.swift",
-        "apple/LocationRegions.swift",
-        "apple/LocationUpdates.swift"
-      ]
+      "class": "TokamakLocationPlugin"
     },
     "android": {
-      "class": "com.tokamak.plugins.location.TokamakLocationPlugin",
-      "sources": [
-        "android/LocationEvents.kt",
-        "android/LocationPlugin.kt",
-        "android/LocationReceiver.kt",
-        "android/LocationRegions.kt",
-        "android/LocationService.kt",
-        "android/LocationUpdates.kt"
-      ]
+      "class": "com.tokamak.plugins.location.TokamakLocationPlugin"
     }
   },
   "api": {

package/web/index.ts

@@ -59,19 +59,20 @@ function browserLocationApi(): Geolocation {
   throw new DOMException("Location is unavailable", "NotSupportedError");
 }
 
-function copyPosition(position: GeolocationPosition): Position {
-  const { coords } = position;
+/** `position` as native platforms give it: without the coordinates the device does not report. */
+function copyPosition({ coords, timestamp }: GeolocationPosition): Position {
+  const { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed } = coords;
   return {
     coords: {
-      latitude: coords.latitude,
-      longitude: coords.longitude,
-      accuracy: coords.accuracy,
-      altitude: coords.altitude,
-      altitudeAccuracy: coords.altitudeAccuracy,
-      heading: coords.heading,
-      speed: coords.speed,
+      latitude,
+      longitude,
+      accuracy,
+      ...(altitude === null ? {} : { altitude }),
+      ...(altitudeAccuracy === null ? {} : { altitudeAccuracy }),
+      ...(heading === null ? {} : { heading }),
+      ...(speed === null ? {} : { speed }),
     },
-    timestamp: position.timestamp,
+    timestamp,
   };
 }