@tauri-apps/plugin-updater 3.0.0-alpha.1 → 3.0.0-alpha.3

package/README.md

@@ -12,7 +12,7 @@ In-app updates for Tauri applications.
 
 ## 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,19 +5,66 @@ 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
+/**
+ * In-app updates for Tauri applications: check the configured endpoints for a new release,
+ * download it and install it.
+ *
+ * @module
+ */
+/**
+ * An update announced by the update server, as returned by {@linkcode check}.
+ *
+ * It holds a resource on the Rust side, so call {@linkcode Update.close} when you are done with it
+ * without installing it.
+ *
+ * @since 2.0.0
+ */
 class Update extends core.Resource {
+    /**
+     * Creates an update from the metadata returned by the backend.
+     * You should not need to call this yourself, use {@linkcode check} instead.
+     *
+     * @param metadata The update information returned by the backend, including the resource identifier of the update.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     * // the update instance is created for you by `check`
+     * const update = await check();
+     * ```
+     */
     constructor(metadata) {
         super(metadata.rid);
-        this.available = true;
         this.currentVersion = metadata.currentVersion;
         this.version = metadata.version;
         this.date = metadata.date;
         this.body = metadata.body;
         this.rawJson = metadata.rawJson;
     }
-    /** Download the updater package. Call {@linkcode install} later to install it */
+    /**
+     * Downloads the updater package. Call {@linkcode install} later to install it.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   let downloaded = 0;
+     *   await update.download((event) => {
+     *     if (event.event === 'Progress') {
+     *       downloaded += event.data.chunkLength;
+     *       console.log(`downloaded ${downloaded} bytes`);
+     *     }
+     *   });
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request.
+     */
     async download(onEvent, options) {
-        convertToRustHeaders(options);
         const channel = new core.Channel();
         if (onEvent) {
             channel.onmessage = onEvent;
@@ -25,8 +72,12 @@ class Update extends core.Resource {
         const downloadedBytesRid = await core.invoke('plugin:updater|download', {
             onEvent: channel,
             rid: this.rid,
-            ...options
+            ...options,
+            headers: toRustHeaders(options?.headers)
         });
+        // release the bytes of a previous download, which would otherwise be kept
+        // in memory until the webview is destroyed
+        await this.downloadedBytes?.close().catch(() => { });
         this.downloadedBytes = new core.Resource(downloadedBytesRid);
     }
     /**
@@ -36,6 +87,19 @@ class Update extends core.Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.download();
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param options Options for the installation, such as whether the Windows installer should restart the app afterwards.
      */
     async install(options) {
         if (!this.downloadedBytes) {
@@ -56,9 +120,23 @@ class Update extends core.Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.downloadAndInstall((event) => {
+     *     console.log(event.event);
+     *   });
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request, and the installation options.
      */
     async downloadAndInstall(onEvent, options) {
-        convertToRustHeaders(options);
         const channel = new core.Channel();
         if (onEvent) {
             channel.onmessage = onEvent;
@@ -66,29 +144,61 @@ class Update extends core.Resource {
         await core.invoke('plugin:updater|download_and_install', {
             onEvent: channel,
             rid: this.rid,
-            ...options
+            ...options,
+            headers: toRustHeaders(options?.headers)
         });
     }
+    /**
+     * Releases the update resource and the downloaded bytes held by the backend.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.close();
+     * }
+     * ```
+     */
     async close() {
         await this.downloadedBytes?.close();
         await super.close();
     }
 }
-/** Check for updates, resolves to `null` if no updates are available */
+/**
+ * Checks the configured endpoints for an available update.
+ *
+ * @example
+ * ```typescript
+ * import { check } from '@tauri-apps/plugin-updater';
+ *
+ * const update = await check();
+ * if (update) {
+ *   console.log(`update ${update.version} is available`);
+ *   await update.downloadAndInstall();
+ * }
+ * ```
+ *
+ * @param options The headers, timeout, proxy and target to use for the update check request.
+ *
+ * @returns A promise resolving to the available {@linkcode Update}, or `null` when no update is available.
+ *
+ * @since 2.0.0
+ */
 async function check(options) {
-    convertToRustHeaders(options);
     const metadata = await core.invoke('plugin:updater|check', {
-        ...options
+        ...options,
+        headers: toRustHeaders(options?.headers)
     });
     return metadata ? new Update(metadata) : null;
 }
 /**
- * Converts the headers in options to be an {@linkcode Array<[string, string]>} which is what the Rust side expects
+ * Converts headers to an {@linkcode Array<[string, string]>}, which is what the Rust side expects,
+ * without modifying the caller's options.
  */
-function convertToRustHeaders(options) {
-    if (options?.headers) {
-        options.headers = Array.from(new Headers(options.headers).entries());
-    }
+function toRustHeaders(headers) {
+    return headers ? Array.from(new Headers(headers).entries()) : undefined;
 }
 
 exports.Update = Update;

package/dist-js/index.d.ts

@@ -1,8 +1,14 @@
+/**
+ * In-app updates for Tauri applications: check the configured endpoints for a new release,
+ * download it and install it.
+ *
+ * @module
+ */
 import { Resource } from '@tauri-apps/api/core';
 /** Options used when checking for updates */
 interface CheckOptions {
     /**
-     * Request headers
+     * The headers to send along with the update check request.
      */
     headers?: HeadersInit;
     /**
@@ -21,7 +27,7 @@ interface CheckOptions {
 /** Options used when downloading an update */
 interface DownloadOptions {
     /**
-     * Request headers
+     * The headers to send along with the update download request.
      */
     headers?: HeadersInit;
     /**
@@ -58,17 +64,71 @@ type DownloadEvent = {
 } | {
     event: 'Finished';
 };
+/**
+ * An update announced by the update server, as returned by {@linkcode check}.
+ *
+ * It holds a resource on the Rust side, so call {@linkcode Update.close} when you are done with it
+ * without installing it.
+ *
+ * @since 2.0.0
+ */
 declare class Update extends Resource {
-    /** @deprecated This is always true, check if the return value is `null` instead when using {@linkcode check} */
-    available: boolean;
     currentVersion: string;
+    /**
+     * The version announced by the update server.
+     */
     version: string;
+    /**
+     * The publish date of the update as an RFC 3339 string, when the server provided one.
+     */
     date?: string;
+    /**
+     * The release notes of the update, when the server provided them.
+     */
     body?: string;
+    /**
+     * The raw update manifest returned by the server, useful when it contains
+     * additional fields that the updater itself does not handle.
+     */
     rawJson: Record<string, unknown>;
     private downloadedBytes?;
+    /**
+     * Creates an update from the metadata returned by the backend.
+     * You should not need to call this yourself, use {@linkcode check} instead.
+     *
+     * @param metadata The update information returned by the backend, including the resource identifier of the update.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     * // the update instance is created for you by `check`
+     * const update = await check();
+     * ```
+     */
     constructor(metadata: UpdateMetadata);
-    /** Download the updater package. Call {@linkcode install} later to install it */
+    /**
+     * Downloads the updater package. Call {@linkcode install} later to install it.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   let downloaded = 0;
+     *   await update.download((event) => {
+     *     if (event.event === 'Progress') {
+     *       downloaded += event.data.chunkLength;
+     *       console.log(`downloaded ${downloaded} bytes`);
+     *     }
+     *   });
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request.
+     */
     download(onEvent?: (progress: DownloadEvent) => void, options?: DownloadOptions): Promise<void>;
     /**
      * Install downloaded updater package. Must be called after {@linkcode download}.
@@ -77,6 +137,19 @@ declare class Update extends Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.download();
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param options Options for the installation, such as whether the Windows installer should restart the app afterwards.
      */
     install(options?: InstallOptions): Promise<void>;
     /**
@@ -86,11 +159,58 @@ declare class Update extends Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.downloadAndInstall((event) => {
+     *     console.log(event.event);
+     *   });
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request, and the installation options.
      */
     downloadAndInstall(onEvent?: (progress: DownloadEvent) => void, options?: DownloadOptions & InstallOptions): Promise<void>;
+    /**
+     * Releases the update resource and the downloaded bytes held by the backend.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.close();
+     * }
+     * ```
+     */
     close(): Promise<void>;
 }
-/** Check for updates, resolves to `null` if no updates are available */
+/**
+ * Checks the configured endpoints for an available update.
+ *
+ * @example
+ * ```typescript
+ * import { check } from '@tauri-apps/plugin-updater';
+ *
+ * const update = await check();
+ * if (update) {
+ *   console.log(`update ${update.version} is available`);
+ *   await update.downloadAndInstall();
+ * }
+ * ```
+ *
+ * @param options The headers, timeout, proxy and target to use for the update check request.
+ *
+ * @returns A promise resolving to the available {@linkcode Update}, or `null` when no update is available.
+ *
+ * @since 2.0.0
+ */
 declare function check(options?: CheckOptions): Promise<Update | null>;
 export type { CheckOptions, DownloadOptions, DownloadEvent };
 export { check, Update };

package/dist-js/index.js

@@ -3,19 +3,66 @@ import { Resource, Channel, invoke } from '@tauri-apps/api/core';
 // Copyright 2019-2023 Tauri Programme within The Commons Conservancy
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
+/**
+ * In-app updates for Tauri applications: check the configured endpoints for a new release,
+ * download it and install it.
+ *
+ * @module
+ */
+/**
+ * An update announced by the update server, as returned by {@linkcode check}.
+ *
+ * It holds a resource on the Rust side, so call {@linkcode Update.close} when you are done with it
+ * without installing it.
+ *
+ * @since 2.0.0
+ */
 class Update extends Resource {
+    /**
+     * Creates an update from the metadata returned by the backend.
+     * You should not need to call this yourself, use {@linkcode check} instead.
+     *
+     * @param metadata The update information returned by the backend, including the resource identifier of the update.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     * // the update instance is created for you by `check`
+     * const update = await check();
+     * ```
+     */
     constructor(metadata) {
         super(metadata.rid);
-        this.available = true;
         this.currentVersion = metadata.currentVersion;
         this.version = metadata.version;
         this.date = metadata.date;
         this.body = metadata.body;
         this.rawJson = metadata.rawJson;
     }
-    /** Download the updater package. Call {@linkcode install} later to install it */
+    /**
+     * Downloads the updater package. Call {@linkcode install} later to install it.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   let downloaded = 0;
+     *   await update.download((event) => {
+     *     if (event.event === 'Progress') {
+     *       downloaded += event.data.chunkLength;
+     *       console.log(`downloaded ${downloaded} bytes`);
+     *     }
+     *   });
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request.
+     */
     async download(onEvent, options) {
-        convertToRustHeaders(options);
         const channel = new Channel();
         if (onEvent) {
             channel.onmessage = onEvent;
@@ -23,8 +70,12 @@ class Update extends Resource {
         const downloadedBytesRid = await invoke('plugin:updater|download', {
             onEvent: channel,
             rid: this.rid,
-            ...options
+            ...options,
+            headers: toRustHeaders(options?.headers)
         });
+        // release the bytes of a previous download, which would otherwise be kept
+        // in memory until the webview is destroyed
+        await this.downloadedBytes?.close().catch(() => { });
         this.downloadedBytes = new Resource(downloadedBytesRid);
     }
     /**
@@ -34,6 +85,19 @@ class Update extends Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.download();
+     *   await update.install();
+     * }
+     * ```
+     *
+     * @param options Options for the installation, such as whether the Windows installer should restart the app afterwards.
      */
     async install(options) {
         if (!this.downloadedBytes) {
@@ -54,9 +118,23 @@ class Update extends Resource {
      *
      * - **Windows:** This function exits the app after launching the updater installer successfully
      * - **macOS / Linux:** You need to relaunch the app to run the newly install version
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.downloadAndInstall((event) => {
+     *     console.log(event.event);
+     *   });
+     * }
+     * ```
+     *
+     * @param onEvent Callback invoked with a `Started` event when the first chunk is received, a `Progress` event for every downloaded chunk and a `Finished` event when the download completes.
+     * @param options The headers and the timeout to use for the download request, and the installation options.
      */
     async downloadAndInstall(onEvent, options) {
-        convertToRustHeaders(options);
         const channel = new Channel();
         if (onEvent) {
             channel.onmessage = onEvent;
@@ -64,29 +142,61 @@ class Update extends Resource {
         await invoke('plugin:updater|download_and_install', {
             onEvent: channel,
             rid: this.rid,
-            ...options
+            ...options,
+            headers: toRustHeaders(options?.headers)
         });
     }
+    /**
+     * Releases the update resource and the downloaded bytes held by the backend.
+     *
+     * @example
+     * ```typescript
+     * import { check } from '@tauri-apps/plugin-updater';
+     *
+     * const update = await check();
+     * if (update) {
+     *   await update.close();
+     * }
+     * ```
+     */
     async close() {
         await this.downloadedBytes?.close();
         await super.close();
     }
 }
-/** Check for updates, resolves to `null` if no updates are available */
+/**
+ * Checks the configured endpoints for an available update.
+ *
+ * @example
+ * ```typescript
+ * import { check } from '@tauri-apps/plugin-updater';
+ *
+ * const update = await check();
+ * if (update) {
+ *   console.log(`update ${update.version} is available`);
+ *   await update.downloadAndInstall();
+ * }
+ * ```
+ *
+ * @param options The headers, timeout, proxy and target to use for the update check request.
+ *
+ * @returns A promise resolving to the available {@linkcode Update}, or `null` when no update is available.
+ *
+ * @since 2.0.0
+ */
 async function check(options) {
-    convertToRustHeaders(options);
     const metadata = await invoke('plugin:updater|check', {
-        ...options
+        ...options,
+        headers: toRustHeaders(options?.headers)
     });
     return metadata ? new Update(metadata) : null;
 }
 /**
- * Converts the headers in options to be an {@linkcode Array<[string, string]>} which is what the Rust side expects
+ * Converts headers to an {@linkcode Array<[string, string]>}, which is what the Rust side expects,
+ * without modifying the caller's options.
  */
-function convertToRustHeaders(options) {
-    if (options?.headers) {
-        options.headers = Array.from(new Headers(options.headers).entries());
-    }
+function toRustHeaders(headers) {
+    return headers ? Array.from(new Headers(headers).entries()) : undefined;
 }
 
 export { Update, check };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-updater",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.3",
   "license": "MIT OR Apache-2.0",
   "authors": [
     "Tauri Programme within The Commons Conservancy"
@@ -24,6 +24,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tauri-apps/api": "^3.0.0-alpha.1"
+    "@tauri-apps/api": "^3.0.0-alpha.2"
   }
 }