snapshot of https://github.com/tauri-apps/plugins-workspace.git (v2, 2026-09-23; blobs > 131072B omitted)

plugins/geolocation/guest-js/index.ts

@@ -0,0 +1,239 @@
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+/**
+ * Get and track the device's current position, mirroring the W3C Geolocation API.
+ *
+ * @module
+ */
+
+import {
+  Channel,
+  invoke,
+  PermissionState,
+  checkPermissions as checkPluginPermissions
+} from '@tauri-apps/api/core'
+
+/**
+ * The GPS coordinates of a {@link Position}, along with the accuracy of each reading.
+ */
+export type Coordinates = {
+  /**
+   * Latitude in decimal degrees.
+   */
+  latitude: number
+  /**
+   * Longitude in decimal degrees.
+   */
+  longitude: number
+  /**
+   * Accuracy level of the latitude and longitude coordinates in meters.
+   */
+  accuracy: number
+  /**
+   * Accuracy level of the altitude coordinate in meters, if available.
+   * Available on all iOS versions and on Android 8 and above.
+   */
+  altitudeAccuracy: number | null
+  /**
+   * The altitude the user is at, if available.
+   */
+  altitude: number | null
+  /**
+   * The speed the user is traveling, in meters per second, if available.
+   */
+  speed: number | null
+  /**
+   * The heading the user is facing, if available.
+   */
+  heading: number | null
+}
+
+/**
+ * The current permission state for the geolocation APIs.
+ */
+export type PermissionStatus = {
+  /**
+   * Permission state for the location alias.
+   *
+   * On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions.
+   *
+   * On iOS it requests/checks location permissions.
+   */
+  location: PermissionState
+  /**
+   * Permissions state for the coarseLoaction alias.
+   *
+   * On Android it requests/checks ACCESS_COARSE_LOCATION.
+   *
+   * On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) and Precise location (ACCESS_FINE_LOCATION).
+   *
+   * On iOS it will have the same value as the `location` alias.
+   */
+  coarseLocation: PermissionState
+}
+
+/**
+ * The individual permission aliases that can be requested with {@link requestPermissions}.
+ *
+ * `location` maps to both the coarse and fine location permissions on Android and to the standard
+ * location permission on iOS. `coarseLocation` maps to the coarse location permission only on
+ * Android, and behaves the same as `location` on iOS.
+ */
+export type PermissionType = 'location' | 'coarseLocation'
+
+/**
+ * A geolocation reading, as returned by {@link getCurrentPosition} and passed to the callback of {@link watchPosition}.
+ */
+export type Position = {
+  /**
+   * Creation time for these coordinates, in milliseconds since the Unix epoch.
+   */
+  timestamp: number
+  /**
+   * The GPS coordinates along with the accuracy of the data.
+   */
+  coords: Coordinates
+}
+
+/**
+ * Options used to configure a {@link getCurrentPosition} or {@link watchPosition} request.
+ */
+export type PositionOptions = {
+  /**
+   * High accuracy mode (such as GPS, if available)
+   * Will be ignored on Android 12+ if users didn't grant the ACCESS_FINE_LOCATION permission (`coarseLocation` permission).
+   */
+  enableHighAccuracy: boolean
+  /**
+   * The maximum wait time in milliseconds for location updates.
+   * On Android the timeout gets ignored for getCurrentPosition.
+   * Ignored on iOS
+   */
+  timeout: number
+  /**
+   * The maximum age in milliseconds of a possible cached position that is acceptable to return.
+   * Default: 0
+   * Ignored on iOS
+   */
+  maximumAge: number
+}
+
+/**
+ * Registers a callback that is invoked with the device's position whenever it changes, similar to the W3C `navigator.geolocation.watchPosition` API. Pass the returned id to {@link clearWatch} to stop watching.
+ *
+ * @example
+ * ```typescript
+ * import { watchPosition } from '@tauri-apps/plugin-geolocation';
+ * const watchId = await watchPosition(
+ *   { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 },
+ *   (position, error) => {
+ *     if (error) {
+ *       console.error(error)
+ *     } else {
+ *       console.log(position)
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @param options Configuration for the position watcher.
+ * @param cb Callback invoked with the new {@link Position} on success, or `null` and an error message when a read fails.
+ * @returns A promise resolving to the id of the registered watcher.
+ * @since 2.0.0
+ */
+export async function watchPosition(
+  options: PositionOptions,
+  cb: (location: Position | null, error?: string) => void
+): Promise<number> {
+  const channel = new Channel<Position | string>()
+  channel.onmessage = (message) => {
+    if (typeof message === 'string') {
+      cb(null, message)
+    } else {
+      cb(message)
+    }
+  }
+  await invoke('plugin:geolocation|watch_position', {
+    options,
+    channel
+  })
+  return channel.id
+}
+
+/**
+ * Returns the device's current position, similar to the W3C `navigator.geolocation.getCurrentPosition` API.
+ *
+ * @example
+ * ```typescript
+ * import { getCurrentPosition } from '@tauri-apps/plugin-geolocation';
+ * const position = await getCurrentPosition();
+ * ```
+ *
+ * @param options Configuration for the position request.
+ * @returns A promise resolving to the current {@link Position}.
+ * @since 2.0.0
+ */
+export async function getCurrentPosition(
+  options?: PositionOptions
+): Promise<Position> {
+  return await invoke('plugin:geolocation|get_current_position', {
+    options
+  })
+}
+
+/**
+ * Stops the position watcher registered with {@link watchPosition}.
+ *
+ * @example
+ * ```typescript
+ * import { clearWatch } from '@tauri-apps/plugin-geolocation';
+ * await clearWatch(watchId);
+ * ```
+ *
+ * @param channelId The id returned by {@link watchPosition}.
+ * @since 2.0.0
+ */
+export async function clearWatch(channelId: number): Promise<void> {
+  await invoke('plugin:geolocation|clear_watch', {
+    channelId
+  })
+}
+
+/**
+ * Returns the current state of the geolocation permissions. Rejects if location services are disabled on the device.
+ *
+ * @example
+ * ```typescript
+ * import { checkPermissions } from '@tauri-apps/plugin-geolocation';
+ * const permission = await checkPermissions();
+ * ```
+ *
+ * @returns A promise resolving to the current {@link PermissionStatus}.
+ * @since 2.0.0
+ */
+export async function checkPermissions(): Promise<PermissionStatus> {
+  return await checkPluginPermissions('geolocation')
+}
+
+/**
+ * Requests the given geolocation permissions, prompting the user if needed. Rejects if location services are disabled on the device.
+ *
+ * @example
+ * ```typescript
+ * import { requestPermissions } from '@tauri-apps/plugin-geolocation';
+ * const permission = await requestPermissions(['location']);
+ * ```
+ *
+ * @param permissions The permissions to request, or `null` to request all of them.
+ * @returns A promise resolving to the resulting {@link PermissionStatus}.
+ * @since 2.0.0
+ */
+export async function requestPermissions(
+  permissions: PermissionType[] | null
+): Promise<PermissionStatus> {
+  return await invoke('plugin:geolocation|request_permissions', {
+    permissions
+  })
+}