@tauri-apps/plugin-geolocation 3.0.0-alpha.1 → 3.0.0-alpha.2

package/README.md

@@ -12,7 +12,7 @@ This plugin provides APIs for getting and tracking the device's current position
 
 ## Install
 
-_This plugin requires a Rust version of at least **1.77.2**_
+_This plugin requires a Rust version of at least **1.95**_
 
 There are three general methods of installation that we can recommend.
 

package/dist-js/index.cjs

@@ -5,6 +5,34 @@ var core = require('@tauri-apps/api/core');
 // 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
+ */
+/**
+ * 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
+ */
 async function watchPosition(options, cb) {
     const channel = new core.Channel();
     channel.onmessage = (message) => {
@@ -21,19 +49,69 @@ async function watchPosition(options, cb) {
     });
     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
+ */
 async function getCurrentPosition(options) {
     return await core.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
+ */
 async function clearWatch(channelId) {
     await core.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
+ */
 async function checkPermissions() {
     return await core.checkPermissions('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
+ */
 async function requestPermissions(permissions) {
     return await core.invoke('plugin:geolocation|request_permissions', {
         permissions

package/dist-js/index.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Get and track the device's current position, mirroring the W3C Geolocation API.
+ *
+ * @module
+ */
 import { PermissionState } 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.
@@ -21,12 +29,18 @@ export type Coordinates = {
      * 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.
@@ -47,17 +61,30 @@ export type PermissionStatus = {
      */
     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.
+     * Creation time for these coordinates, in milliseconds since the Unix epoch.
      */
     timestamp: number;
     /**
-     * The GPD coordinates along with the accuracy of the data.
+     * 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)
@@ -77,8 +104,81 @@ export type PositionOptions = {
      */
     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 declare function watchPosition(options: PositionOptions, cb: (location: Position | null, error?: string) => void): Promise<number>;
+/**
+ * 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 declare function getCurrentPosition(options?: PositionOptions): Promise<Position>;
+/**
+ * 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 declare function clearWatch(channelId: number): Promise<void>;
+/**
+ * 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 declare function checkPermissions(): Promise<PermissionStatus>;
+/**
+ * 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 declare function requestPermissions(permissions: PermissionType[] | null): Promise<PermissionStatus>;

package/dist-js/index.js

@@ -3,6 +3,34 @@ import { Channel, invoke, checkPermissions as checkPermissions$1 } from '@tauri-
 // 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
+ */
+/**
+ * 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
+ */
 async function watchPosition(options, cb) {
     const channel = new Channel();
     channel.onmessage = (message) => {
@@ -19,19 +47,69 @@ async function watchPosition(options, cb) {
     });
     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
+ */
 async function getCurrentPosition(options) {
     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
+ */
 async function clearWatch(channelId) {
     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
+ */
 async function checkPermissions() {
     return await checkPermissions$1('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
+ */
 async function requestPermissions(permissions) {
     return await invoke('plugin:geolocation|request_permissions', {
         permissions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-geolocation",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.2",
   "license": "MIT OR Apache-2.0",
   "authors": [
     "Tauri Programme within The Commons Conservancy"