electron-incremental-update 0.9.0 → 1.0.0

package/README.md

@@ -1,137 +1,134 @@
-## electron incremental updater
+## Electron Incremental Updater
 
-This project provide a vite plugin, `Updater` class and some useful functions to generate incremental update.
+This project is based on [vite-plugin-electron](https://github.com/electron-vite/vite-plugin-electron), provide a plugin that build on top of `ElectronSimple`, an `Updater` class and some useful utils for Electron.
 
-There will be two asar in production, `app.asar` and `main.asar` (if "main" is your app's name).
+There will be two asar in production, `app.asar` and `${name}.asar` (`electron.app.name`, also as the `name` field in `package.json`).
 
-The `app.asar` is used to load `main.asar` and initialize the `updater`. Also, all the **native modules**, which are set as `dependencies` in `package.json`, will be packaged into `app.asar` by `electron-builder`, [see usage](#use-native-modules).
+The `app.asar` is used to load `${name}.asar` and initialize the `Updater`.
 
-The new `main.asar` downloaded from remote will be verified by presigned RSA + Signature. When pass the check and restart, the old `main.asar` will be replaced by the new one. Hooks like `beforeDoUpdate` are provided.
+The new `${name}.asar`, which can download from remote or load from buffer, will be verified by `Updater` using presigned RSA + Signature. While passing the check and restart, the old `${name}.asar` will be replaced by the new one. Hooks like `beforeDoUpdate` are provided.
 
-- inspired by Obsidian's update strategy
+All **native modules** should be packaged into `app.asar` to reduce `${name}.asar` file size, [see usage](#use-native-modules)
 
-### notice
+no `vite-plugin-electron-renderer` config
 
-- this plugin is developed with [vite-plugin-electron](https://github.com/electron-vite/vite-plugin-electron), and may be effect in other electron vite frameworks
-- **all options are documented in the jsdoc**
+- inspired by [Obsidian](https://obsidian.md/)'s upgrade strategy
 
-## install
+## Install
 
 ### npm
 ```bash
-npm install electron-incremental-update
+npm install -D vite-plugin-electron electron-incremental-update
 ```
 ### yarn
 ```bash
-yarn add electron-incremental-update
+yarn add -D vite-plugin-electron electron-incremental-update
 ```
 ### pnpm
 ```bash
-pnpm add electron-incremental-update
+pnpm add -D vite-plugin-electron electron-incremental-update
 ```
 
-## setup
+## Getting started
+
+### Project structure
 
 base on [electron-vite-vue](https://github.com/electron-vite/electron-vite-vue)
 
 ```
 electron
-├── app.ts // <- add app entry file
-├── electron-env.d.ts
+├── entry.ts // <- entry file
 ├── main
-│   ├── db.ts
-│   ├── index.ts
-└── preload
+│   └── index.ts
+├── preload
+│   └── index.ts
+└── native // possible native modules
     └── index.ts
 src
 └── ...
 ```
 
-### setup app
+### Setup entry
 
 ```ts
-// electron/app.ts
-import { initApp, parseGithubCdnURL } from 'electron-incremental-update'
-import { name, repository } from '../package.json'
+// electron/entry.ts
+import { initApp } from 'electron-incremental-update'
+import { parseGithubCdnURL } from 'electron-incremental-update/utils'
+import { repository } from '../package.json'
 
 const SIGNATURE_CERT = '' // auto generate certificate when start app
 
 initApp({ onStart: console.log })
-  // can be updater option or function that return updater
   .setUpdater({
     SIGNATURE_CERT,
-    productName: name,
-    repository,
-    updateJsonURL: parseGithubCdnURL(repository, '...', 'version.json'),
-    releaseAsarURL: parseGithubCdnURL(repository, '...', `download/latest/${name}.asar.gz`),
-    receiveBeta: true
+    // repository,
+    // updateJsonURL: parseGithubCdnURL(repository, 'https://your.cdn.url/', 'version.json'),
+    // releaseAsarURL: parseGithubCdnURL(repository, 'https://your.cdn.url/', `download/latest/${name}.asar.gz`),
+    // receiveBeta: true
   })
 ```
 
-- [some cdn resources](https://github.com/XIU2/UserScript/blob/master/GithubEnhanced-High-Speed-Download.user.js#L34):
+- [some CDN resources](https://github.com/XIU2/UserScript/blob/master/GithubEnhanced-High-Speed-Download.user.js#L34):
 
-### setup vite.config.ts
+### Setup `vite.config.ts`
 
-make sure the plugin is set in the **last** build task
+All options are documented with JSDoc
 
-- for `vite-plugin-electron`, set it to `preload` (the second object in the plugin option array)
-- cert is read from `process.env.UPDATER_CERT` first, then read config
-- privatekey is read from `process.env.UPDATER_PK` first, then read config
+- cert will read from `process.env.UPDATER_CERT` first, if absend, read config
+- privatekey will read from `process.env.UPDATER_PK` first, if absend, read config
 
 ```ts
-// vite.config.ts
-export default defineConfig(({ command }) => {
-  const isBuild = command === 'build'
-  // ...
+// vite.config.mts
+import { defineConfig } from 'vite'
+import { debugStartup, electronWithUpdater } from 'electron-incremental-update/vite'
+import pkg from './package.json'
 
+export default defineConfig(async ({ command }) => {
+  const isBuild = command === 'build'
   return {
     plugins: [
-      electron([
-        // main
-        {
-          // ...
+      electronWithUpdater({
+        pkg,
+        isBuild,
+        logParsedOptions: true,
+        main: {
+          files: ['./electron/main/index.ts', './electron/main/worker.ts'],
+          // see https://github.com/electron-vite/electron-vite-vue/blob/85ed267c4851bf59f32888d766c0071661d4b94c/vite.config.ts#L22-L28
+          onstart: debugStartup,
         },
-        // preload
-        {
-          // ...
-          vite: {
-            plugins: [
-              updater({
-                productName: pkg.name,
-                version: pkg.version,
-                isBuild,
-              }),
-            ],
-            // ...
-          }
+        preload: {
+          files: './electron/preload/index.ts',
         },
-        // when using vite-plugin-electron-renderer
-        {
-          // ...
+        updater: {
+          // options
         }
-      ]),
-      // ...
+      }),
     ],
-    // ...
+    server: process.env.VSCODE_DEBUG && (() => {
+      const url = new URL(pkg.debug.env.VITE_DEV_SERVER_URL)
+      return {
+        host: url.hostname,
+        port: +url.port,
+      }
+    })(),
   }
 })
 ```
 
-### modify package.json
+### Modify package.json
 
 ```json
 {
-  // ...
-  "main": "app.js" // <- app entry file path
+  "main": "dist-entry/entry.js" // <- entry file path
 }
 ```
 
-### config electron-builder
+### Config electron-builder
 
 ```js
 const { name } = require('./package.json')
 
-const target = `${name}.asar`
+const targetFile = `${name}.asar`
 /**
  * @type {import('electron-builder').Configuration}
  */
@@ -139,26 +136,21 @@ module.exports = {
   appId: 'YourAppID',
   productName: name,
   files: [
-    'app.js', // <- app entry file
-    '!**/{.eslintignore,.eslintrc.cjs,.editorconfig,.prettierignore,.prettierrc.yaml,dev-app-update.yml,LICENSE,.nvmrc,.npmrc}',
-    '!**/{tsconfig.json,tsconfig.node.json,tsconfig.web.json}',
-    '!**/*debug*.*',
-    '!**/*.{md,zip,map}',
-    '!**/*.{c,cpp,h,hpp,cc,hh,cxx,hxx,gypi,gyp,sh}',
-    '!**/.{github,vscode}',
-    '!node_modules/**/better-sqlite3/deps/**',
+    // entry files
+    'dist-entry',
   ],
+  npmRebuild: false,
   asarUnpack: [
-    '**/*.{node,dll}',
+    '**/*.{node,dll,dylib,so}',
   ],
   directories: {
     output: 'release',
   },
   extraResources: [
-    { from: `release/${target}`, to: target }, // <- asar file
+    { from: `release/${targetFile}`, to: targetFile }, // <- asar file
   ],
-  publish: null, // <- disable publish
-  // ...
+  // disable publish
+  publish: null,
 }
 ```
 
@@ -170,21 +162,23 @@ To use electron's `net` module for updating, the `checkUpdate` and `download` fu
 
 However, you have the option to customize the download function when creating the updater.
 
-**NOTE: There can only be one function and should be default export in the entry file**
+**NOTE: There should only one function and should be default export in the entry file**
 
 ```ts
 // electron/main/index.ts
-import type { StartupWithUpdater, Updater } from 'electron-incremental-update'
-import { appInfo, getAppVersion, getElectronVersion, getProductAsarPath } from 'electron-incremental-update/utils'
+import { startupWithUpdater } from 'electron-incremental-update'
+import { getPathFromAppNameAsar, getVersions } from 'electron-incremental-update/utils'
 import { app } from 'electron'
-import { name } from '../../package.json'
 
-const startup: StartupWithUpdater = (updater: Updater) => {
+export default startupWithUpdater((updater) => {
   await app.whenReady()
-  console.log('\ncurrent:')
-  console.log(`\tasar path: ${getProductAsarPath(name)}`)
-  console.log(`\tapp:       ${getAppVersion(name)}`)
-  console.log(`\telectron:  ${getElectronVersion()}`)
+
+  const { appVersion, electronVersion, entryVersion } = getVersions()
+  console.log(`${app.name}.asar path`, getPathFromAppNameAsar())
+  console.log('app version:', appVersion)
+  console.log('entry (installer) version', entryVersion)
+  console.log('electron version', electronVersion)
+
   updater.onDownloading = ({ percent }) => {
     console.log(percent)
   }
@@ -201,41 +195,95 @@ const startup: StartupWithUpdater = (updater: Updater) => {
         buttons: ['Download', 'Later'],
         message: 'Application update available!',
       })
-      response === 0 && console.log(await updater.download())
+      if (response !== 0) {
+        return
+      }
+      const downloadResult = await updater.download()
+      if (downloadResult) {
+        updater.quitAndInstall()
+      }
     }
   })
-}
-export default startup
+})
 ```
 
 ### use native modules
 
-the native modules is packed in `app.asar`, so you cannot directly access it when in production
+All the **native modules** should be set as `dependency` in `package.json`. `electron-rebuild` only check dependencies inside `dependency` field.
 
-to use it, you can prebundle native modules, or use `requireNative` to load.
+If you are using `electron-builder` to build distributions, all the native modules with its **large relavent `node_modiles`** will be packaged into `app.asar` by default. You can setup `nativeModuleEntryMap` option to prebundle all the native modules and skip bundled by `electron-builder`
+
+in `vite.config.ts`
 
 ```ts
-// db.ts
-import { isNoSuchNativeModuleError, requireNative } from 'electron-incremental-update/utils'
+const plugin = electronWithUpdater({
+  // options...
+  updater: {
+    entry: {
+      nativeModuleEntryMap: {
+        db: './electron/native/db.ts',
+      },
+      postBuild: async ({ existsAndCopyToEntryOutputDir }) => {
+        // for better-sqlite3
+        existsAndCopyToEntryOutputDir({
+          from: './node_modules/better-sqlite3/build/Release/better_sqlite3.node',
+          skipIfExist: false,
+        })
+      },
+    },
+  },
+})
+```
 
-const Database = requireNative<typeof import('better-sqlite3')>('better-sqlite3')
-if (isNoSuchNativeModuleError(Database)) {
-  // ...
-}
-const db = new Database(':memory:')
-db.exec(
-  'DROP TABLE IF EXISTS employees; '
+in `electron/native/db.ts`
+
+```ts
+import Database from 'better-sqlite3'
+import { getPaths } from 'electron-incremental-update/utils'
+
+const db = new Database(':memory:', { nativeBinding: getPaths().getPathFromEntryAsar('better_sqlite3.node') })
+
+export function test() {
+  db.exec(
+    'DROP TABLE IF EXISTS employees; '
     + 'CREATE TABLE IF NOT EXISTS employees (name TEXT, salary INTEGER)',
-)
+  )
 
-db.prepare('INSERT INTO employees VALUES (:n, :s)').run({
-  n: 'James',
-  s: 50000,
-})
+  db.prepare('INSERT INTO employees VALUES (:n, :s)').run({
+    n: 'James',
+    s: 5000,
+  })
 
-const r = db.prepare('SELECT * from employees').all()
-console.log(r)
-// [ { name: 'James', salary: 50000 } ]
+  const r = db.prepare('SELECT * from employees').all()
+  console.log(r)
+  // [ { name: 'James', salary: 50000 } ]
 
-db.close()
+  db.close()
+}
 ```
+
+in `electron/main/service.ts`
+
+```ts
+import { loadNativeModuleFromEntry } from 'electron-incremental-update/utils'
+
+const requireNative = loadNativeModuleFromEntry()
+
+requireNative<typeof import('../native/db')>('db').test()
+```
+
+in `electron-builder.config.js`
+
+```js
+module.exports = {
+  files: [
+    'dist-entry',
+    // exclude better-sqlite3 from electron-builder
+    '!node_modules/better-sqlite3/**',
+  ]
+}
+```
+
+## License
+
+MIT

package/dist/{chunk-CMBFI77K.mjs → chunk-GB6VLKJZ.mjs}

@@ -6,32 +6,6 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
-// src/utils/version.ts
-function parseVersion(version) {
-  const semver = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9\.-]+))?/i;
-  const match = semver.exec(version);
-  if (!match) {
-    throw new TypeError(`invalid version: ${version}`);
-  }
-  const [major, minor, patch] = match.slice(1, 4).map(Number);
-  const ret = {
-    major,
-    minor,
-    patch,
-    stage: "",
-    stageVersion: -1
-  };
-  if (match[4]) {
-    let [stage, _v] = match[4].split(".");
-    ret.stage = stage;
-    ret.stageVersion = Number(_v) || -1;
-  }
-  if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch) || Number.isNaN(ret.stageVersion)) {
-    throw new TypeError(`invalid version: ${version}`);
-  }
-  return ret;
-}
-
 // src/utils/zip.ts
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { gunzip, gzip } from "node:zlib";
@@ -67,9 +41,55 @@ async function zipFile(filePath, targetFilePath = `${filePath}.gz`) {
   });
 }
 
+// src/utils/noDep.ts
+function parseGithubCdnURL(originRepoURL, cdnPrefix, relativeFilePath) {
+  if (!originRepoURL.startsWith("https://github.com/")) {
+    throw new Error("origin url must start with https://github.com/");
+  }
+  originRepoURL = originRepoURL.trim().replace(/\/?$/, "/").trim();
+  relativeFilePath = relativeFilePath.trim().replace(/^\/|\/?$/g, "").trim();
+  cdnPrefix = cdnPrefix.trim().replace(/^\/?|\/?$/g, "").trim();
+  return originRepoURL.replace("github.com", cdnPrefix) + relativeFilePath;
+}
+function handleUnexpectedErrors(callback) {
+  process.on("uncaughtException", callback);
+  process.on("unhandledRejection", callback);
+}
+function parseVersion(version) {
+  const semver = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9\.-]+))?/i;
+  const match = semver.exec(version);
+  if (!match) {
+    throw new TypeError(`invalid version: ${version}`);
+  }
+  const [major, minor, patch] = match.slice(1, 4).map(Number);
+  const ret = {
+    major,
+    minor,
+    patch,
+    stage: "",
+    stageVersion: -1
+  };
+  if (match[4]) {
+    let [stage, _v] = match[4].split(".");
+    ret.stage = stage;
+    ret.stageVersion = Number(_v) || -1;
+  }
+  if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch) || Number.isNaN(ret.stageVersion)) {
+    throw new TypeError(`invalid version: ${version}`);
+  }
+  return ret;
+}
+function isUpdateJSON(json) {
+  const is = (j) => !!(j && j.minimumVersion && j.signature && j.size && j.version);
+  return is(json) && is(json?.beta);
+}
+
 export {
   __require,
-  parseVersion,
   unzipFile,
-  zipFile
+  zipFile,
+  parseGithubCdnURL,
+  handleUnexpectedErrors,
+  parseVersion,
+  isUpdateJSON
 };

package/dist/{chunk-5BZLJPHJ.mjs → chunk-GXZSAUBR.mjs}

@@ -30,14 +30,7 @@ var verify = (buffer, signature2, cert) => {
   }
 };
 
-// src/updateJson.ts
-function isUpdateJSON(json) {
-  const is = (j) => "signature" in j && "version" in j && "size" in j && "minimumVersion" in j;
-  return is(json) && "beta" in json && is(json.beta);
-}
-
 export {
   signature,
-  verify,
-  isUpdateJSON
+  verify
 };

package/dist/chunk-OUZLSVQC.mjs

@@ -0,0 +1,148 @@
+import {
+  __require
+} from "./chunk-GB6VLKJZ.mjs";
+
+// src/utils/electron.ts
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { release } from "node:os";
+import { app } from "electron";
+var is = {
+  dev: !app.isPackaged,
+  win: process.platform === "win32",
+  mac: process.platform === "darwin",
+  linux: process.platform === "linux"
+};
+function getPathFromAppNameAsar(...path) {
+  return is.dev ? "DEV.asar" : join(dirname(app.getAppPath()), `${app.name}.asar`, ...path);
+}
+function getVersions() {
+  const platform = is.win ? "Windows" : is.mac ? "MacOS" : process.platform.toUpperCase();
+  return {
+    appVersion: is.dev ? app.getVersion() : readFileSync(getPathFromAppNameAsar("version"), "utf-8"),
+    entryVersion: app.getVersion(),
+    electronVersion: process.versions.electron,
+    nodeVersion: process.versions.node,
+    systemVersion: `${platform} ${release()}`
+  };
+}
+function loadNativeModuleFromEntry(devEntryDirPath = "../../dist-entry", entryDirPath = join(app.getAppPath(), basename(devEntryDirPath))) {
+  const path = is.dev ? devEntryDirPath : entryDirPath;
+  return (moduleName) => {
+    try {
+      return __require(join(path, moduleName));
+    } catch (error) {
+      console.error("fail to load module", error);
+    }
+  };
+}
+function restartApp() {
+  app.relaunch();
+  app.quit();
+}
+function setAppUserModelId(id) {
+  app.setAppUserModelId(is.dev ? process.execPath : id ?? `org.${app.name}`);
+}
+function disableHWAccForWin7() {
+  if (release().startsWith("6.1")) {
+    app.disableHardwareAcceleration();
+  }
+}
+function singleInstance(window) {
+  const result = app.requestSingleInstanceLock();
+  result ? app.on("second-instance", () => {
+    if (window) {
+      window.show();
+      if (window.isMinimized()) {
+        window.restore();
+      }
+      window.focus();
+    }
+  }) : app.quit();
+  return result;
+}
+function setPortableAppDataPath(dirName = "data") {
+  const portablePath = join(dirname(app.getPath("exe")), dirName);
+  if (!existsSync(portablePath)) {
+    mkdirSync(portablePath);
+  }
+  app.setPath("appData", portablePath);
+}
+function waitAppReady(timeout = 1e3) {
+  return app.isReady() ? Promise.resolve() : new Promise((resolve, reject) => {
+    const _ = setTimeout(() => {
+      reject(new Error("app is not ready"));
+    }, timeout);
+    app.whenReady().then(() => {
+      clearTimeout(_);
+      resolve();
+    });
+  });
+}
+function getPaths(entryDirName = "dist-entry") {
+  const root = join(__dirname, "..");
+  const mainDirPath = join(root, "main");
+  const preloadDirPath = join(root, "preload");
+  const rendererDirPath = join(root, "renderer");
+  const devServerURL = process.env.VITE_DEV_SERVER_URL;
+  const indexHTMLPath = join(rendererDirPath, "index.html");
+  const publicDirPath = devServerURL ? join(root, "../public") : rendererDirPath;
+  return {
+    /**
+     * @example
+     * ```ts
+     * devServerURL && win.loadURL(devServerURL)
+     * ```
+     */
+    devServerURL,
+    /**
+     * @example
+     * ```ts
+     * win.loadFile(indexHTMLPath)
+     * ```
+     */
+    indexHTMLPath,
+    /**
+     * get path inside entry asar
+     * @param paths joined path
+     */
+    getPathFromEntryAsar(...paths) {
+      return join(app.getAppPath(), entryDirName, ...paths);
+    },
+    /**
+     * get path inside `${app.name}.asar/main`
+     * @param paths joined path
+     */
+    getPathFromMain(...paths) {
+      return join(mainDirPath, ...paths);
+    },
+    /**
+     * get path inside `${app.name}.asar/preload`
+     * @param paths joined path
+     */
+    getPathFromPreload(...paths) {
+      return join(preloadDirPath, ...paths);
+    },
+    /**
+     * get path inside public dir
+     * @param paths joined path
+     */
+    getPathFromPublic(...paths) {
+      return join(publicDirPath, ...paths);
+    }
+  };
+}
+
+export {
+  is,
+  getPathFromAppNameAsar,
+  getVersions,
+  loadNativeModuleFromEntry,
+  restartApp,
+  setAppUserModelId,
+  disableHWAccForWin7,
+  singleInstance,
+  setPortableAppDataPath,
+  waitAppReady,
+  getPaths
+};