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

package/README.md

@@ -254,14 +254,6 @@ The web uses `navigator.geolocation`. `permission()` reports `inUse` from the
 Permissions API, and the other additions reject with `NotSupportedError`,
 including the event-stream methods. Native support is provided on Apple and Android.
 
-## Platform bindings
-
-`@tokamakdev/plugin-location/apple` is Core Location, and
-`@tokamakdev/plugin-location/android` is `android.location` with the
-`Context`, `CancellationSignal`, `SystemClock`, `Executor` and `Consumer`
-types it uses, for Worker code that needs what this API does not offer.
-`getCurrentPosition` and `watchPosition` are built on them.
-
 ## Errors
 
 Rejections and `onLocationError` events are `DOMException` names:

package/android/LocationPlugin.kt

@@ -45,6 +45,7 @@ class TokamakLocationPlugin(
     private val significantChanges = LocationUpdates(context, LocationUpdates.SIGNIFICANT_CHANGES)
     private val regions = LocationRegions(context)
     private val events = LocationEvents(host)
+    private val positions = LocationPositions(context, manager)
 
     /** Whether the provider was on when last reported, as each request reports its changes. */
     private var providerEnabled = true
@@ -67,6 +68,8 @@ class TokamakLocationPlugin(
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply): (() -> Unit)? {
         when (method) {
             "setup" -> setup(requireObject(arguments), reply)
+            "recentPosition" -> reply(Result.success(recentPosition(requireObject(arguments))))
+            "currentPosition" -> return currentPosition(reply)
             "permission" -> reply(Result.success(permission()))
             "requestPermission" -> requestPermission(requireObject(arguments), reply)
             "servicesEnabled" -> reply(Result.success(manager.isLocationEnabled))
@@ -92,12 +95,30 @@ class TokamakLocationPlugin(
         method: String,
         arguments: Any?,
         reply: TokamakPluginReply,
-    ): () -> Unit = events.listen(method, reply) ?: super.subscribe(method, arguments, reply)
+    ): () -> Unit =
+        when (method) {
+            "watchPosition" -> watchPosition(reply)
+            else -> events.listen(method, reply) ?: super.subscribe(method, arguments, reply)
+        }
+
+    /** The provider's last known position when it is no older than the options' `maximumAge`, or null. */
+    private fun recentPosition(options: JSONObject): JSONObject? =
+        runCatching { positions.recent(options.optDouble("maximumAge", 0.0))?.let(::position) }
+            .getOrElse { throw locationError(it) }
+
+    /** Replies with a new fix, or null when Android finds none, unless the returned cancellation runs first. */
+    private fun currentPosition(reply: TokamakPluginReply): () -> Unit =
+        runCatching { positions.current { reply(Result.success(it?.let(::position))) } }
+            .getOrElse { throw locationError(it) }
+
+    /** Replies with each position as the device moves, until the provider turns off or the returned release runs. */
+    private fun watchPosition(reply: TokamakPluginReply): () -> Unit =
+        runCatching {
+            positions.watch({ reply(Result.success(position(it))) }) {
+                reply(Result.failure(TokamakPluginError("NotReadableError", "Location provider is unavailable")))
+            }
+        }.getOrElse { throw locationError(it) }
 
-    /**
-     * Passes [action] whether the app may read fine or coarse location, asking when it may not.
-     * Throws `NeedsUIError` when asking would show UI while the app is in the background.
-     */
     /**
      * Asks for the foreground [permissions], then passes [action] whether the app has one, first
      * starting what waited for permission.

package/android/LocationPositions.kt

@@ -0,0 +1,52 @@
+package com.tokamak.plugins.location
+
+import android.content.Context
+import android.location.Location
+import android.location.LocationListener
+import android.location.LocationManager
+import android.location.LocationRequest
+import android.os.CancellationSignal
+import android.os.SystemClock
+import com.tokamak.runtime.TokamakPluginError
+
+/**
+ * Positions for `getCurrentPosition` and `watchPosition`, at the provider's highest accuracy, from
+ * the first enabled of the fused provider, which combines GPS with Wi-Fi and cell signals, GPS and
+ * the network, or any other enabled provider. Each throws `SecurityException` without permission.
+ */
+internal class LocationPositions(private val context: Context, private val manager: LocationManager) {
+    /** The provider's last known position when it is no older than [maximumAge] milliseconds. */
+    fun recent(maximumAge: Double): Location? = manager.getLastKnownLocation(provider())?.takeIf { age(it) <= maximumAge }
+
+    /** Passes [found] a new fix, or null when Android finds none, and returns the cancellation. */
+    fun current(found: (Location?) -> Unit): () -> Unit {
+        val signal = CancellationSignal()
+        manager.getCurrentLocation(provider(), highAccuracy(0), signal, context.mainExecutor) { found(it) }
+        return signal::cancel
+    }
+
+    /** Passes [next] each position, and [disabled] the provider turning off, until the returned release runs. */
+    fun watch(next: (Location) -> Unit, disabled: () -> Unit): () -> Unit {
+        val listener = object : LocationListener {
+            override fun onLocationChanged(location: Location) = next(location)
+
+            override fun onProviderDisabled(provider: String) = disabled()
+        }
+        manager.requestLocationUpdates(provider(), highAccuracy(1000), context.mainExecutor, listener)
+        return { manager.removeUpdates(listener) }
+    }
+
+    private fun provider(): String =
+        listOf(LocationManager.FUSED_PROVIDER, LocationManager.GPS_PROVIDER, LocationManager.NETWORK_PROVIDER)
+            .firstOrNull(manager::isProviderEnabled)
+            ?: manager.getProviders(true).firstOrNull()
+            ?: throw TokamakPluginError("NotReadableError", "No location provider is available")
+
+    /** A request for the most accurate fixes the provider gives, every [interval] milliseconds. */
+    private fun highAccuracy(interval: Long): LocationRequest =
+        LocationRequest.Builder(interval).setQuality(LocationRequest.QUALITY_HIGH_ACCURACY).build()
+
+    /** The milliseconds since Android took [location]. */
+    private fun age(location: Location): Double =
+        (SystemClock.elapsedRealtimeNanos() - location.elapsedRealtimeNanos) / 1_000_000.0
+}

package/apple/LocationEvents.swift

@@ -152,4 +152,13 @@ extension TokamakPluginError {
   static func locationUnavailable(_ message: String) -> Self {
     Self(name: "NotReadableError", message: message)
   }
+
+  /// Core Location's `error`: `NotAllowedError` without permission, and
+  /// `NotReadableError` otherwise.
+  static func location(_ error: Error) -> Self {
+    if (error as NSError).code == CLError.Code.denied.rawValue {
+      return Self(name: "NotAllowedError", message: "Location permission was denied")
+    }
+    return .locationUnavailable(error.localizedDescription)
+  }
 }

package/apple/LocationPlugin.swift

@@ -19,10 +19,6 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
 {
   let id = "location"
 
-  private static let permissionDenied = TokamakPluginError(
-    name: "NotAllowedError",
-    message: "Location permission was denied"
-  )
   /// A `requestPermission` waiting for the user to answer a prompt.
   private struct Prompt {
     /// The purpose key of the temporary precise location to ask for next.
@@ -91,6 +87,13 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
         apply(options)
         defaults.set(try? JSONSerialization.data(withJSONObject: options), forKey: setupKey)
         reply(.success(nil))
+      case "recentPosition":
+        reply(.success(recentPosition(maximumAge: (options["maximumAge"] as? Double ?? 0) / 1000)))
+      case "currentPosition":
+        let fix = TokamakLocationPositions(reply: reply)
+        fix.locate()
+        // The cancellation owns the location manager until the call ends.
+        return fix.stop
       case "permission":
         reply(.success(permission()))
       case "requestPermission":
@@ -151,6 +154,12 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     arguments: Any,
     reply: @escaping TokamakPluginReply
   ) throws(TokamakPluginError) -> (() -> Void) {
+    if method == "watchPosition" {
+      let watch = TokamakLocationPositions(reply: reply)
+      watch.watch()
+      // The release owns the location manager until the subscription ends.
+      return watch.stop
+    }
     guard let remove = events.listen(method, reply) else {
       throw .notSupported("\(id).\(method) is not supported")
     }
@@ -185,7 +194,7 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
   ) {
     guard manager === monitoring, (error as NSError).code != CLError.Code.locationUnknown.rawValue
     else { return }
-    events.fail(locationError(error))
+    events.fail(.location(error))
   }
 
   /// Core Location delivers each visit to every manager's delegate.
@@ -195,6 +204,14 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
     }
   }
 
+  /// Core Location's latest position when it is no older than `maximumAge`
+  /// seconds, or nil.
+  private func recentPosition(maximumAge: TimeInterval) -> Any? {
+    guard let recent = authorization.location, -recent.timestamp.timeIntervalSinceNow <= maximumAge
+    else { return nil }
+    return TokamakLocationEvents.position(recent)
+  }
+
   /// Starts the significant changes and visits `config` names, and stops the
   /// others. After a launch for one of their events, starting them again
   /// delivers it.
@@ -381,11 +398,4 @@ final class TokamakLocationPlugin: NSObject, TokamakPlugin,
       reply(opened == true ? .success(nil) : .failure(notOpened))
     #endif
   }
-
-  private func locationError(_ error: Error) -> TokamakPluginError {
-    if (error as NSError).code == CLError.Code.denied.rawValue {
-      return Self.permissionDenied
-    }
-    return .locationUnavailable(error.localizedDescription)
-  }
 }

package/apple/LocationPositions.swift

@@ -0,0 +1,49 @@
+import CoreLocation
+import Foundation
+
+/// Positions from a location manager of its own, for one `getCurrentPosition`
+/// or `watchPosition`. Use it on the main thread.
+final class TokamakLocationPositions: NSObject, CLLocationManagerDelegate {
+  private let manager = CLLocationManager()
+  private let reply: TokamakPluginReply
+  private var watching = false
+
+  /// Passes `reply` the new fix, or each position as the device moves, or a
+  /// failure.
+  init(reply: @escaping TokamakPluginReply) {
+    self.reply = reply
+    super.init()
+    manager.delegate = self
+    manager.desiredAccuracy = kCLLocationAccuracyBest
+  }
+
+  func locate() {
+    manager.requestLocation()
+  }
+
+  func watch() {
+    watching = true
+    manager.startUpdatingLocation()
+  }
+
+  func stop() {
+    manager.stopUpdatingLocation()
+  }
+
+  func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+    for location in watching ? locations : locations.suffix(1) {
+      reply(.success(TokamakLocationEvents.position(location)))
+    }
+  }
+
+  /// Asks again, or keeps watching, while Core Location does not know the
+  /// position yet.
+  func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+    guard (error as NSError).code == CLError.Code.locationUnknown.rawValue else {
+      return reply(.failure(.location(error)))
+    }
+    if !watching {
+      manager.requestLocation()
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-location",
-  "version": "0.1.0-beta.127",
+  "version": "0.1.0-beta.128",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -9,12 +9,10 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./events": "./events/index.ts",
-    "./apple": "./apple/bindings.ts",
-    "./android": "./android/bindings.ts"
+    "./events": "./events/index.ts"
   },
   "peerDependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.127"
+    "@tokamakdev/plugin": "0.1.0-beta.128"
   },
   "files": [
     "android",

package/src/errors.ts

@@ -15,20 +15,3 @@ export function timedOut(): DOMException {
 export function unavailable(message: string): DOMException {
   return new DOMException(message, "NotReadableError");
 }
-
-/**
- * Rejects once `timeout` milliseconds pass without `found` settling, running `stop` either way. An
- * undefined `timeout` waits as long as it takes.
- */
-export async function within<T>(found: Promise<T>, timeout: number | undefined, stop: () => void): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const expired = new Promise<never>((_, reject) => {
-    if (timeout !== undefined) timer = setTimeout(() => { reject(timedOut()); }, timeout);
-  });
-  try {
-    return await Promise.race([found, expired]);
-  } finally {
-    clearTimeout(timer);
-    stop();
-  }
-}

package/src/index.ts

@@ -1,9 +1,6 @@
 import { Plugin, lifecycleStage, type JsonStream, type TokamakContext } from "@tokamakdev/plugin";
-import { valueStream } from "@tokamakdev/plugin/streams";
 
-import * as android from "./android.js";
-import * as apple from "./apple.js";
-import { backgroundDenied, permissionDenied, unavailable } from "./errors.js";
+import { backgroundDenied, permissionDenied, timedOut, unavailable } from "./errors.js";
 import type {
   LocationErrorEvent,
   LocationPermission,
@@ -41,9 +38,15 @@ class Location extends Plugin {
    * when location is unavailable. Asking off screen rejects with `NeedsUIError`, as
    * `requestPermission` does.
    */
-  async getCurrentPosition(options: PositionOptions = {}): Promise<Position> {
+  async getCurrentPosition({ maximumAge = 0, timeout }: PositionOptions = {}): Promise<Position> {
     await this.#authorize();
-    const position = await this.#platform().currentPosition(this.ctx, options);
+    // JSON has no Infinity, which accepts any recent position.
+    const recent = await this.call<Position | null>("recentPosition", { maximumAge: 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 this.call<Position | null>("currentPosition", null, { signal: located.signal })
+      .finally(() => { clearTimeout(timer); });
     if (position) return position;
     // Android finds no position in the background without background permission.
     const background = await lifecycleStage(this.ctx) === "background";
@@ -55,10 +58,7 @@ class Location extends Plugin {
    * 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");
+    return this.stream("watchPosition", this.#authorize().then(() => null), "dropOldest");
   }
 
   /** Requires location services and in-use permission, asking for it where the user has not answered. */
@@ -69,19 +69,6 @@ class Location extends Plugin {
     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");

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",
@@ -62,6 +42,7 @@
       "sources": [
         "apple/LocationEvents.swift",
         "apple/LocationPlugin.swift",
+        "apple/LocationPositions.swift",
         "apple/LocationRegions.swift",
         "apple/LocationUpdates.swift"
       ]
@@ -71,6 +52,7 @@
       "sources": [
         "apple/LocationEvents.swift",
         "apple/LocationPlugin.swift",
+        "apple/LocationPositions.swift",
         "apple/LocationRegions.swift",
         "apple/LocationUpdates.swift"
       ]
@@ -80,6 +62,7 @@
       "sources": [
         "android/LocationEvents.kt",
         "android/LocationPlugin.kt",
+        "android/LocationPositions.kt",
         "android/LocationReceiver.kt",
         "android/LocationRegions.kt",
         "android/LocationService.kt",