@nwutils/packager 0.5.0 → 0.7.0

package/types/util.d.ts

@@ -1,3 +1,45 @@
+declare namespace _default {
+    export { APPIMAGE_ARCH_KV };
+    export { appUpdateYaml };
+    export { desktopExecArg };
+    export { fileExists };
+    export { isWindowsFileName };
+    export { nsisEscape };
+    export { nsisPath };
+    export { parseDesktopEntry };
+    export { sha512 };
+    export { shellQuote };
+    export { stringifyDesktopEntry };
+    export { stringifyYaml };
+    export { updateInfoFileName };
+    export { validatePublish };
+    export { windowsVersion };
+    export { writeUpdateInfo };
+}
+export default _default;
+/**
+ * Map nw-builder's architecture identifiers to the identifiers used in
+ * `appimagetool` release asset names and its `ARCH` environment variable.
+ * @type {Record<"ia32" | "x64" | "arm64", string>}
+ */
+declare const APPIMAGE_ARCH_KV: Record<"ia32" | "x64" | "arm64", string>;
+/**
+ * Contents of the `app-update.yml` file `@nwutils/updater` reads to find out
+ * where releases are published. It is shipped next to the NW.js executable.
+ * @param {import("./appImage.js").PublishOptions} publish
+ * @returns {string}
+ */
+declare function appUpdateYaml(publish: import("./appImage.js").PublishOptions): string;
+/**
+ * Quote `value` as a single argument of a desktop entry's `Exec` key, per the
+ * Desktop Entry Specification: `%` is doubled so it isn't read as a field
+ * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
+ * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
+ * required for every string value.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function desktopExecArg(value: string): string;
 /**
  * Check if a file or directory exists.
  * @async
@@ -6,6 +48,35 @@
  * @returns {Promise<boolean>}
  */
 declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Check that `value` can be used as a single Windows file name: no path
+ * separators, characters Windows forbids in file names, control characters,
+ * trailing dots or spaces, or reserved device names.
+ * @param {string} value
+ * @returns {boolean}
+ */
+declare function isWindowsFileName(value: string): boolean;
+/**
+ * Escape `value` for use inside a double quoted NSIS string. NSIS expands `$`
+ * variables and `$\` escapes there, so `$` is doubled and `"` is escaped.
+ * Line breaks are rejected rather than escaped: a raw one would end the
+ * command and let the value inject further script lines. The result is not
+ * quoted, so it can be joined with NSIS variables, eg. `"$INSTDIR\<value>"`.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function nsisEscape(value: string): string;
+/**
+ * Check a path on the host for use inside a double quoted NSIS string that
+ * `makensis` reads at compile time, eg. a `File` source or `OutFile`. Unlike
+ * runtime strings, those keep `$` literally, so nothing is escaped. Instead,
+ * the sequences `makensis` would still interpret are rejected: `${define}`
+ * expansions and `$\` escapes, and `"` - an escaped `$\"` doesn't survive
+ * being passed through a `!define`, as the icon and license paths are.
+ * @param {string} value
+ * @returns {string}  `value`, unchanged.
+ */
+declare function nsisPath(value: string): string;
 /**
  * Parse a freedesktop.org desktop entry file's `[Desktop Entry]` group into
  * a key/value map. Other groups (eg. `[Desktop Action ...]`) are ignored.
@@ -14,11 +85,14 @@ declare function fileExists(filePath: string): Promise<boolean>;
  */
 declare function parseDesktopEntry(contents: string): Record<string, string>;
 /**
- * Serialise a `[Desktop Entry]` key/value map back into a desktop entry file.
- * @param {Record<string, string | undefined>} entries
- * @returns {string}
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
+ * same encoding electron-builder writes into its update info files.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<string>}
  */
-declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
+declare function sha512(filePath: string): Promise<string>;
 /**
  * Quote `value` as a single POSIX shell word. Inside single quotes nothing is
  * expanded, so only single quotes themselves need escaping.
@@ -27,23 +101,11 @@ declare function stringifyDesktopEntry(entries: Record<string, string | undefine
  */
 declare function shellQuote(value: string): string;
 /**
- * Quote `value` as a single argument of a desktop entry's `Exec` key, per the
- * Desktop Entry Specification: `%` is doubled so it isn't read as a field
- * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
- * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
- * required for every string value.
- * @param {string} value
- * @returns {string}
- */
-declare function desktopExecArg(value: string): string;
-/**
- * Name of the update info file `@nwutils/updater` downloads to find the
- * latest release, following electron-builder's naming: `x64` gets the bare
- * `latest-linux.yml`, every other architecture gets an `-<arch>` suffix.
- * @param {"ia32" | "x64" | "arm64"} arch
+ * Serialise a `[Desktop Entry]` key/value map back into a desktop entry file.
+ * @param {Record<string, string | undefined>} entries
  * @returns {string}
  */
-declare function updateInfoFileName(arch: "ia32" | "x64" | "arm64"): string;
+declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
 /**
  * Serialise a map of scalars, and lists of maps of scalars, as YAML. This is
  * the only shape the update info and `app-update.yml` files use, so it avoids
@@ -53,23 +115,44 @@ declare function updateInfoFileName(arch: "ia32" | "x64" | "arm64"): string;
  */
 declare function stringifyYaml(entries: Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>): string;
 /**
- * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
- * same encoding electron-builder writes into its update info files.
+ * Name of the update info file `@nwutils/updater` downloads for `arch` on
+ * `platform`, matching electron-builder: `x64` gets the bare
+ * `latest-linux.yml` (Linux) or `latest.yml` (Windows), every other
+ * architecture gets an `-<arch>` suffix.
+ * @param {string}           arch
+ * @param {"linux" | "win"}  [platform="linux"]
+ * @returns {string}
+ */
+declare function updateInfoFileName(arch: string, platform?: "linux" | "win"): string;
+/**
+ * Throw if `publish` isn't a valid `PublishOptions` object.
+ * @param {unknown} publish
+ * @returns {void}
+ */
+declare function validatePublish(publish: unknown): void;
+/**
+ * Convert a version such as `"1.2.3"` or `"1.2.3-beta.1"` into the
+ * `X.X.X.X` form Windows version resources (and NSIS' `VIProductVersion`)
+ * require. Up to four leading numeric parts are kept, missing ones are
+ * filled with `0`, and any prerelease or build suffix is dropped.
+ * @param {string} version
+ * @returns {string}
+ */
+declare function windowsVersion(version: string): string;
+/**
+ * Write the update info file `@nwutils/updater` compares the running version
+ * against, describing the packaged artifact at `filePath`. It must be uploaded
+ * to every release next to the artifact.
  * @async
  * @function
- * @param {string} filePath
- * @returns {Promise<string>}
+ * @param  {object}  options
+ * @param  {string}  options.filePath        Path to the packaged artifact, eg. the AppImage or installer.
+ * @param  {string}  options.updateInfoPath  Path the update info file is written to.
+ * @param  {string}  options.version         Version of the application.
+ * @returns {Promise<void>}
  */
-declare function sha512(filePath: string): Promise<string>;
-declare const _default: {
-    APPIMAGE_ARCH_KV: Record<"arm64" | "ia32" | "x64", string>;
-    desktopExecArg: typeof desktopExecArg;
-    fileExists: typeof fileExists;
-    parseDesktopEntry: typeof parseDesktopEntry;
-    sha512: typeof sha512;
-    shellQuote: typeof shellQuote;
-    stringifyDesktopEntry: typeof stringifyDesktopEntry;
-    stringifyYaml: typeof stringifyYaml;
-    updateInfoFileName: typeof updateInfoFileName;
-};
-export default _default;
+declare function writeUpdateInfo({ filePath, updateInfoPath, version }: {
+    filePath: string;
+    updateInfoPath: string;
+    version: string;
+}): Promise<void>;