electron-incremental-update 3.0.0-beta.6 → 3.0.0

package/README.md

@@ -16,25 +16,15 @@ Lightweight incremental update tools for Electron applications built with Vite.
     - [Plugin Options](#plugin-options)
   - [Electron Builder](#electron-builder)
   - [Runtime Usage](#runtime-usage)
-    - [Create The App](#create-the-app)
-    - [Updater API](#updater-api)
   - [Providers](#providers)
-    - [GitHub](#github)
-      - [Default](#default)
-      - [Atom](#atom)
-      - [Api](#api)
-      - [URL Handling](#url-handling)
-    - [Local](#local)
-      - [Recommended Setup](#recommended-setup)
-      - [Custom Options](#custom-options)
-      - [Manual Provider](#manual-provider)
-      - [Testing The Local Flow](#testing-the-local-flow)
+    - [Testing The Local Flow](#testing-the-local-flow)
   - [Update Artifacts](#update-artifacts)
   - [Native Modules](#native-modules)
     - [Result in app.asar](#result-in-appasar)
   - [Bytecode Protection](#bytecode-protection)
   - [Development Bundling](#development-bundling)
   - [Utilities](#utilities)
+  - [API Reference](#api-reference)
   - [Credits](#credits)
   - [License](#license)
 
@@ -83,6 +73,8 @@ pnpm add -D electron-incremental-update @electron/asar @babel/core
 yarn add -D electron-incremental-update @electron/asar @babel/core
 ```
 
+> Upgrading from `3.0.0-beta.x`? See [MIGRATION.md](./MIGRATION.md).
+
 ## Quick Start
 
 Recommended project layout:
@@ -202,7 +194,7 @@ export default defineElectronConfig({
     minimumVersion: '0.0.0',
     paths: {
       asarOutputPath: 'release/my-app.asar',
-      gzipPath: 'release/my-app-1.0.0.asar.gz',
+      compressedPath: 'release/my-app-1.0.0.asar.br',
       versionPath: 'release/version.json',
     },
   },
@@ -242,7 +234,7 @@ export default defineConfig({
 
 ### Plugin Options
 
-Common options:
+Common options overview:
 
 - `entry.files`: entry process input. Required.
 - `main.files`: main process input. Required.
@@ -254,26 +246,10 @@ Common options:
 - `external`: additional Vite/Rolldown externals. Use `true` to externalize `dependencies`.
 - `buildVersionJson`: generates update JSON. Defaults to CI only.
 - `localDevUpdate`: generates and serves a local update package during dev startup. Use `true`
-  for defaults, or pass `{ baseDir, packageJsonPath, chunkSize, chunkDelay }`. See [Local Development](#local-development) for details.
+  for defaults, or pass `{ baseDir, packageJsonPath, chunkSize, chunkDelay }`. See [Testing The Local Flow](#testing-the-local-flow) for details.
 - `updater.minimumVersion`: minimum supported entry asar version. Defaults to `0.0.0`.
 
-Default output paths:
-
-- `updater.paths.asarOutputPath`: `release/${app.name}.asar`
-- `updater.paths.gzipPath`: `release/${app.name}-${version}.asar.gz`
-- `updater.paths.versionPath`: `release/version.json`
-- `updater.paths.entryOutDir`: `dist-entry`
-- `updater.paths.electronDistPath`: `dist-electron`
-- `updater.paths.rendererDistPath`: `dist`
-
-Signing keys:
-
-- `updater.keys.privateKeyPath`: defaults to `keys/private.pem`
-- `updater.keys.certPath`: defaults to `keys/cert.pem`
-- `UPDATER_PK`: overrides `privateKeyPath`
-- `UPDATER_CERT`: overrides `certPath`
-
-The plugin creates a simple self-signed certificate when the key files are missing.
+> 📖 See [API.md → Plugin Options](./API.md#plugin-options) for the complete reference including all types, defaults, paths, keys, and generator overrides.
 
 ## Electron Builder
 
@@ -316,231 +292,44 @@ module.exports = {
 
 ## Runtime Usage
 
-### Create The App
-
 ```ts
 import { createElectronApp } from 'electron-incremental-update'
+import { GitHubProvider } from 'electron-incremental-update/provider'
 
 createElectronApp({
   updater: {
-    provider,
-    receiveBeta: false,
-    logger: console,
-  },
-  onInstall(install, tempAsarPath, appNameAsarPath, logger) {
-    logger?.info(`Installing ${tempAsarPath} to ${appNameAsarPath}`)
-    install()
-  },
-  onStartError(error, logger) {
-    logger?.error('Failed to start app', error)
+    provider: new GitHubProvider({
+      user: 'your-github-user',
+      repo: 'your-repo',
+    }),
   },
-})
-```
-
-`updater` can also be an async factory:
-
-```ts
-createElectronApp({
-  updater: async () => {
-    const { Updater } = await import('electron-incremental-update')
-    return new Updater({ provider })
+  beforeStart(mainFilePath, logger) {
+    logger?.debug(`Starting app from ${mainFilePath}`)
   },
 })
 ```
 
-### Updater API
-
-```ts
-updater.provider = provider
-updater.receiveBeta = true
-updater.logger = console
-
-await updater.checkForUpdates()
-await updater.downloadUpdate()
-updater.cancel()
-updater.quitAndInstall()
-```
-
-Events:
+The full `Updater` API, `createElectronApp` options, `AppOption`, events, and error codes are documented in the API reference.
 
-- `update-available`: emitted with update info and current app/entry versions.
-- `update-not-available`: emitted with a code, message, and optional update info.
-- `download-progress`: emitted while downloading.
-- `update-downloaded`: emitted after the temporary asar is ready.
-- `update-cancelled`: emitted after cancellation.
-- `error`: emitted with `UpdaterError`.
+> 📖 See [API.md → Entry API](./API.md#entry-api) for the complete reference.
 
 ## Providers
 
-### GitHub
-
-GitHub providers read update metadata from a repository or release and download the generated
-`{name}-{version}.asar.gz` artifact from GitHub Releases.
-
-#### Default
-
-Reads `version.json` from the repository branch and downloads the asar from GitHub Releases.
-
-```ts
-import { GitHubProvider } from 'electron-incremental-update/provider'
-
-const provider = new GitHubProvider({
-  user: 'your-github-user',
-  repo: 'your-repo',
-  branch: 'HEAD',
-})
-```
-
-Default URLs:
-
-- update JSON: `https://github.com/{user}/{repo}/raw/{branch}/{versionPath}`
-- asar: `https://github.com/{user}/{repo}/releases/download/v{version}/{name}-{version}.asar.gz`
-
-#### Atom
-
-Reads the latest release tag from `releases.atom`, then downloads the update JSON and asar from that release.
-
-```ts
-import { GitHubAtomProvider } from 'electron-incremental-update/provider'
-
-const provider = new GitHubAtomProvider({
-  user: 'your-github-user',
-  repo: 'your-repo',
-})
-```
-
-#### Api
-
-Uses the GitHub Releases API and can use a token for private repositories or higher rate limits.
-
-```ts
-import { GitHubApiProvider } from 'electron-incremental-update/provider'
-
-const provider = new GitHubApiProvider({
-  user: 'your-github-user',
-  repo: 'your-repo',
-  token: process.env.GITHUB_TOKEN,
-})
-```
-
-#### URL Handling
-
-GitHub providers support `urlHandler` for mirrors, custom gateways, or request rewriting.
-
-```ts
-const provider = new GitHubProvider({
-  user: 'your-github-user',
-  repo: 'your-repo',
-  urlHandler(url) {
-    url.hostname = 'mirror.example.com'
-    url.pathname = `https://github.com${url.pathname}`
-    return url
-  },
-})
-```
+The package includes GitHub-based providers (file, atom, API) and a local development provider.
 
-### Local
+- **GitHubProvider** — reads `version.json` from a repository branch, downloads asar from Releases.
+- **GitHubAtomProvider** — reads the latest release from `releases.atom`.
+- **GitHubApiProvider** — uses the GitHub Releases API (supports tokens for private repos).
+- **LocalDevProvider** — reads update artifacts from the local filesystem for dev testing.
 
-Local updates are for development and manual update-flow testing. They let you test
-`checkForUpdates()`, download progress, `update-downloaded`, and restart/install behavior without
-publishing a GitHub release.
+All GitHub providers support a `urlHandler` for mirrors and custom gateways.
 
-Most projects should use the Vite `localDevUpdate` option instead of manually creating a
-`LocalDevProvider`.
+See the [API reference](./API.md#providers) for the complete provider constructor options and method signatures.
 
-#### Recommended Setup
+### Testing The Local Flow
 
-Enable local update generation in `vite.config.ts`:
-
-```ts
-import { electronWithUpdater } from 'electron-incremental-update/vite'
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  plugins: [
-    electronWithUpdater({
-      entry: {
-        files: './electron/entry.ts',
-      },
-      main: {
-        files: './electron/main/index.ts',
-      },
-      preload: {
-        files: './electron/preload/index.ts',
-      },
-      localDevUpdate: true,
-    }),
-  ],
-})
-```
-
-When `localDevUpdate` is enabled in development:
-
-- the Vite plugin creates a local update package before Electron starts
-- `createElectronApp()` auto-configures `LocalDevProvider` when no explicit `updater.provider` is set
-- dev-only `forceUpdate` is enabled so update checks are not skipped in development
-- production builds keep the normal provider and signature behavior
-
-The default generated files are:
-
-- `release/local-update/release/version.json`
-- `release/local-update/{name}-{version}.asar.gz`
-- `DEV.asar`
-- `DEV.asar.tmp` after `downloadUpdate()`
-
-The generated update version is the next patch version from the installed local dev asar. For
-example, if `DEV.asar` contains version `1.2.3`, the generated update is `1.2.4`.
-
-#### Custom Options
-
-```ts
-export default defineConfig({
-  plugins: [
-    electronWithUpdater({
-      // ...
-      localDevUpdate: {
-        baseDir: 'release/local-update',
-        packageJsonPath: 'playground/package.json',
-        chunkSize: 32 * 1024,
-        chunkDelay: 50,
-      },
-    }),
-  ],
-})
-```
-
-Options:
-
-- `baseDir`: directory for generated local update resources. Defaults to `release/local-update`.
-- `packageJsonPath`: package metadata used for update name/version. Defaults to the project
-  `package.json`.
-- `chunkSize`: bytes per simulated download progress chunk. Defaults to `64 * 1024`.
-- `chunkDelay`: delay between progress chunks in milliseconds. Defaults to `30`.
-
-`chunkSize` must be greater than `0`, and `chunkDelay` must be greater than or equal to `0`.
-
-#### Manual Provider
-
-Use `LocalDevProvider` directly only when you need to wire local artifacts yourself.
-
-```ts
-import { LocalDevProvider } from 'electron-incremental-update/provider'
-
-const provider = new LocalDevProvider({
-  baseDir: 'release/local-update',
-  chunkSize: 32 * 1024,
-  chunkDelay: 50,
-})
-```
-
-It reads:
-
-- `{baseDir}/{versionPath}`
-- `{baseDir}/{name}-{version}.asar.gz`
-
-#### Testing The Local Flow
-
-Use the [playground](./playground) as a complete local update test:
+Prefer `localDevUpdate: true` in the Vite plugin over constructing `LocalDevProvider` manually.
+See [playground](./playground) as a complete local update test:
 
 ```sh
 bun run play
@@ -567,7 +356,7 @@ local provider setup is skipped.
 The Vite plugin can generate:
 
 - `${app.name}.asar`
-- `${app.name}-${version}.asar.gz`
+- `${app.name}-${version}.asar.br`
 - `version.json`
 
 Default `version.json` shape:
@@ -589,6 +378,15 @@ Stable releases update both the top-level fields and `beta`. Prerelease versions
 
 Set `buildVersionJson: true` if you need metadata during non-CI builds.
 
+> [!NOTE]
+> The **default** version parser supports `major.minor.patch[-prerelease[.number]]` (e.g. `1.0.0-beta.1`).
+> Build metadata (`+build`) and complex semver prerelease identifiers (e.g. `1.0.0-beta.1.2`)
+> are not supported by default.
+>
+> To use full semver or a custom version scheme, override
+> [`provider.isLowerVersion`](#providers) with your own comparator
+> (e.g. `semver.lt` from the `semver` package).
+
 ## Native Modules
 
 To keep update packages small, put native modules and their native binaries in `app.asar`, then load them from the main process with `requireNative()` or `importNative()`.
@@ -676,7 +474,7 @@ module.exports = {
 }
 ```
 
-#### Result in app.asar
+### Result in app.asar
 
 Before: Redundant 🤮
 
@@ -785,56 +583,15 @@ electronWithUpdater({
 
 ## Utilities
 
-Import from `electron-incremental-update/utils`:
+Import from `electron-incremental-update/utils` for path helpers, platform checks, native module loading, crypto, compression, download, and version parsing utilities.
 
-```ts
-import {
-  aesDecrypt,
-  aesEncrypt,
-  beautifyDevTools,
-  defaultIsLowerVersion,
-  defaultSignature,
-  defaultUnzipFile,
-  defaultVerifySignature,
-  defaultZipFile,
-  getAppVersion,
-  getEntryVersion,
-  getPathFromAppNameAsar,
-  getPathFromEntryAsar,
-  getPathFromMain,
-  getPathFromPreload,
-  getPathFromPublic,
-  handleUnexpectedErrors,
-  hashBuffer,
-  importNative,
-  isDev,
-  isLinux,
-  isMac,
-  isWin,
-  loadPage,
-  parseVersion,
-  requireNative,
-  restartApp,
-  setAppUserModelId,
-  setPortableDataPath,
-  singleInstance,
-} from 'electron-incremental-update/utils'
-```
+> 📖 See [API.md → Utilities API](./API.md#utilities-api) for the complete function list with signatures and descriptions.
+
+## API Reference
+
+For the full API documentation including all types, options tables, provider constructors, and plugin configuration, see the standalone reference:
 
-Common helpers:
-
-- `getPathFromAppNameAsar(...paths)`: path inside `${app.name}.asar`.
-- `getPathFromEntryAsar(...paths)`: path inside `app.asar`.
-- `getPathFromMain(...paths)`: path inside the built main directory.
-- `getPathFromPreload(...paths)`: path inside the built preload directory.
-- `getPathFromPublic(...paths)`: path inside `public` in dev or renderer output in production.
-- `getAppVersion()`: current app version. In dev, returns the entry version.
-- `getEntryVersion()`: version from Electron app metadata.
-- `loadPage(win, htmlFilePath)`: loads `VITE_DEV_SERVER_URL` in dev or renderer HTML in production.
-- `singleInstance(window)`: restores and focuses the window on `second-instance`.
-- `setPortableDataPath(dirName, create)`: stores user data beside the executable for portable apps.
-- `requireNative(moduleName)`: loads a CommonJS native helper from entry asar.
-- `importNative(moduleName)`: imports an ES module native helper from entry asar.
+> 📖 **[API.md](./API.md)** — Auto-generated JSDoc extraction + manual reference sections.
 
 ## Credits
 

package/dist/{zip-D1dbBzw4.cjs → crypto-BSky88mL.cjs}

@@ -20,14 +20,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-let node_crypto = require("node:crypto");
-node_crypto = __toESM(node_crypto, 1);
 let node_zlib = require("node:zlib");
 node_zlib = __toESM(node_zlib, 1);
+let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto, 1);
 //#region src/utils/version.ts
 const REG_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([a-z0-9]+)(?:\.(\d+))?)?$/i;
 /**
 * Parse version string to {@link Version}, like `0.2.0-beta.1`
+*
+* **Supported format**: `major.minor.patch[-stage[.stageVersion]]`
+*
+* Build metadata (`+build`) and complex semver prerelease identifiers
+* (e.g. `1.0.0-beta.1.2`) are not supported yet.
 * @param version version string
 */
 function parseVersion(version) {
@@ -119,6 +124,26 @@ function defaultVersionJsonGenerator(existingJson, signature, version, minimumVe
 	return existingJson;
 }
 //#endregion
+//#region src/utils/compress.ts
+/**
+* Default function to compress file using brotli
+* @param buffer uncompressed file buffer
+*/
+async function defaultCompressFile(buffer) {
+	return new Promise((resolve, reject) => {
+		node_zlib.default.brotliCompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
+	});
+}
+/**
+* Default function to decompress file using brotli
+* @param buffer compressed file buffer
+*/
+async function defaultDecompressFile(buffer) {
+	return new Promise((resolve, reject) => {
+		node_zlib.default.brotliDecompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
+	});
+}
+//#endregion
 //#region src/utils/crypto.ts
 function hashBuffer(data, length) {
 	const hash = node_crypto.default.createHash("SHA256").update(data).digest("binary");
@@ -160,26 +185,6 @@ function defaultVerifySignature(buffer, version, signature, cert) {
 	}
 }
 //#endregion
-//#region src/utils/zip.ts
-/**
-* Default function to compress file using brotli
-* @param buffer uncompressed file buffer
-*/
-async function defaultZipFile(buffer) {
-	return new Promise((resolve, reject) => {
-		node_zlib.default.brotliCompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
-	});
-}
-/**
-* Default function to decompress file using brotli
-* @param buffer compressed file buffer
-*/
-async function defaultUnzipFile(buffer) {
-	return new Promise((resolve, reject) => {
-		node_zlib.default.brotliDecompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
-	});
-}
-//#endregion
 Object.defineProperty(exports, "__toESM", {
 	enumerable: true,
 	get: function() {
@@ -198,40 +203,40 @@ Object.defineProperty(exports, "aesEncrypt", {
 		return aesEncrypt;
 	}
 });
-Object.defineProperty(exports, "defaultIsLowerVersion", {
+Object.defineProperty(exports, "defaultCompressFile", {
 	enumerable: true,
 	get: function() {
-		return defaultIsLowerVersion;
+		return defaultCompressFile;
 	}
 });
-Object.defineProperty(exports, "defaultSignature", {
+Object.defineProperty(exports, "defaultDecompressFile", {
 	enumerable: true,
 	get: function() {
-		return defaultSignature;
+		return defaultDecompressFile;
 	}
 });
-Object.defineProperty(exports, "defaultUnzipFile", {
+Object.defineProperty(exports, "defaultIsLowerVersion", {
 	enumerable: true,
 	get: function() {
-		return defaultUnzipFile;
+		return defaultIsLowerVersion;
 	}
 });
-Object.defineProperty(exports, "defaultVerifySignature", {
+Object.defineProperty(exports, "defaultSignature", {
 	enumerable: true,
 	get: function() {
-		return defaultVerifySignature;
+		return defaultSignature;
 	}
 });
-Object.defineProperty(exports, "defaultVersionJsonGenerator", {
+Object.defineProperty(exports, "defaultVerifySignature", {
 	enumerable: true,
 	get: function() {
-		return defaultVersionJsonGenerator;
+		return defaultVerifySignature;
 	}
 });
-Object.defineProperty(exports, "defaultZipFile", {
+Object.defineProperty(exports, "defaultVersionJsonGenerator", {
 	enumerable: true,
 	get: function() {
-		return defaultZipFile;
+		return defaultVersionJsonGenerator;
 	}
 });
 Object.defineProperty(exports, "hashBuffer", {

package/dist/{zip-DUK3opmV.mjs → crypto-DZzMmoz2.mjs}

@@ -1,9 +1,14 @@
-import crypto from "node:crypto";
 import zlib from "node:zlib";
+import crypto from "node:crypto";
 //#region src/utils/version.ts
 const REG_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([a-z0-9]+)(?:\.(\d+))?)?$/i;
 /**
 * Parse version string to {@link Version}, like `0.2.0-beta.1`
+*
+* **Supported format**: `major.minor.patch[-stage[.stageVersion]]`
+*
+* Build metadata (`+build`) and complex semver prerelease identifiers
+* (e.g. `1.0.0-beta.1.2`) are not supported yet.
 * @param version version string
 */
 function parseVersion(version) {
@@ -95,6 +100,26 @@ function defaultVersionJsonGenerator(existingJson, signature, version, minimumVe
 	return existingJson;
 }
 //#endregion
+//#region src/utils/compress.ts
+/**
+* Default function to compress file using brotli
+* @param buffer uncompressed file buffer
+*/
+async function defaultCompressFile(buffer) {
+	return new Promise((resolve, reject) => {
+		zlib.brotliCompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
+	});
+}
+/**
+* Default function to decompress file using brotli
+* @param buffer compressed file buffer
+*/
+async function defaultDecompressFile(buffer) {
+	return new Promise((resolve, reject) => {
+		zlib.brotliDecompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
+	});
+}
+//#endregion
 //#region src/utils/crypto.ts
 function hashBuffer(data, length) {
 	const hash = crypto.createHash("SHA256").update(data).digest("binary");
@@ -136,24 +161,4 @@ function defaultVerifySignature(buffer, version, signature, cert) {
 	}
 }
 //#endregion
-//#region src/utils/zip.ts
-/**
-* Default function to compress file using brotli
-* @param buffer uncompressed file buffer
-*/
-async function defaultZipFile(buffer) {
-	return new Promise((resolve, reject) => {
-		zlib.brotliCompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
-	});
-}
-/**
-* Default function to decompress file using brotli
-* @param buffer compressed file buffer
-*/
-async function defaultUnzipFile(buffer) {
-	return new Promise((resolve, reject) => {
-		zlib.brotliDecompress(buffer, (err, buffer) => err ? reject(err) : resolve(buffer));
-	});
-}
-//#endregion
-export { defaultSignature as a, defaultIsLowerVersion as c, parseVersion as d, aesEncrypt as i, defaultVersionJsonGenerator as l, defaultZipFile as n, defaultVerifySignature as o, aesDecrypt as r, hashBuffer as s, defaultUnzipFile as t, isUpdateJSON as u };
+export { hashBuffer as a, defaultIsLowerVersion as c, parseVersion as d, defaultVerifySignature as i, defaultVersionJsonGenerator as l, aesEncrypt as n, defaultCompressFile as o, defaultSignature as r, defaultDecompressFile as s, aesDecrypt as t, isUpdateJSON as u };

package/dist/{download-BjWmHHAu.d.cts → download-BVmLiAvB.d.cts}

@@ -1,4 +1,4 @@
-import { p as Arrayable, s as UpdateJSON, t as DownloadingInfo } from "./types-BOqQ_r5Q.cjs";
+import { p as Arrayable, s as UpdateJSON, t as DownloadingInfo } from "./types-q78spjKB.cjs";
 import { ClientRequest, IncomingMessage } from "electron";
 
 //#region src/utils/download.d.ts
@@ -8,7 +8,7 @@ import { ClientRequest, IncomingMessage } from "electron";
 * @param key target header key
 */
 declare function getHeader(headers: Record<string, Arrayable<string>>, key: any): any;
-declare function downloadUtil<T>(url: string, headers: Record<string, any>, onResponse: (req: ClientRequest, resp: IncomingMessage, resolve: (data: T) => void, reject: (e: any) => void) => void): Promise<T>;
+declare function downloadUtil<T>(url: string, headers: Record<string, any>, onResponse: (req: ClientRequest, resp: IncomingMessage, resolve: (data: T) => void, reject: (e: any) => void) => void, signal?: AbortSignal): Promise<T>;
 type ResolveDataFn = (data: string, resolve: (data: any) => void, reject: (e: any) => void) => void;
 declare const resolveJson: ResolveDataFn;
 /**