@nwutils/packager 0.2.1 → 0.3.0

package/README.md

@@ -4,7 +4,16 @@
 
 Package NW.js applications for Linux, MacOS and Windows.
 
-Currently supported: packaging a Linux application as an [AppImage](https://appimage.org/).
+Supported output formats, selected via `format`:
+
+| Format     | Platform | Status      |
+| ---------- | -------- | ----------- |
+| `AppImage` | Linux    | Implemented |
+| `deb`      | Linux    | Planned     |
+| `rpm`      | Linux    | Planned     |
+| `msix`     | Windows  | Planned     |
+| `nsis`     | Windows  | Planned     |
+| `dmg`      | MacOS    | Planned     |
 
 ## Getting Started
 
@@ -13,11 +22,11 @@ Currently supported: packaging a Linux application as an [AppImage](https://appi
 ## Usage
 
 This composes with `@nwutils/builder`: run it against the `outDir` (and `app.name`)
-that `@nwutils/builder` produced for `platform: "linux"`.
+that `@nwutils/builder` produced.
 
 ```js
 import build from "@nwutils/builder";
-import { appImage } from "@nwutils/packager";
+import packager from "@nwutils/packager";
 
 await build({
   version: "0.115.0",
@@ -33,7 +42,8 @@ await build({
   },
 });
 
-const appImagePath = await appImage({
+const appImagePath = await packager({
+  format: "AppImage",
   appDir: "./out",
   appName: "Demo",
   cacheDir: "./cache",
@@ -43,6 +53,12 @@ const appImagePath = await appImage({
 console.log(`AppImage written to ${appImagePath}`);
 ```
 
+`packager({ format, ...options })` dispatches to the packager for `format` -
+`options` is whatever that packager expects (see `appImage(options)` below).
+Passing a `format` that isn't `"AppImage"` yet throws a clear "not implemented
+yet" error rather than doing nothing. `appImage` is also exported directly, if
+you'd rather skip the dispatch and know you only ever target AppImage.
+
 The first time it runs for a given architecture, `appImage()` downloads
 [`appimagetool`](https://github.com/AppImage/appimagetool) into `cacheDir` and
 reuses it on subsequent calls. `appimagetool` is a native Linux binary, so
@@ -55,6 +71,15 @@ FUSE is typically unavailable.
 
 ## API Reference
 
+### `packager({ format, ...options })`
+
+| Name   | Type                                               | Description                                                                  |
+| ------ | -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| format | `"AppImage" \| "deb" \| "rpm" \| "MSIX" \| "NSIS"` | Which packager to run. Only `"AppImage"` is implemented today.               |
+| ...    | -                                                  | The remaining options are passed through to the packager for `format` as-is. |
+
+Resolves with the path to the resulting packaged artifact.
+
 ### `appImage(options)`
 
 Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwutils/packager",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Package NW.js applications for Linux, MacOS and Windows.",
   "keywords": [
     "NW.js",

package/src/index.js

@@ -1,7 +1,39 @@
 import appImage from "./appImage.js";
 
-export default {
-  appImage,
-};
+/**
+ * Supported packaged output formats.
+ *
+ * `AppImage`, `deb` and `rpm` package a Linux build. `MSIX` and `NSIS`
+ * package a Windows build. Only `"AppImage"` is implemented today - the
+ * others are reserved so this option doesn't need to change shape once they
+ * land.
+ * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
+ */
 
-export { appImage };
+/**
+ * Package a built NW.js application.
+ * @async
+ * @function
+ * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage`) expects.
+ * @returns {Promise<string>}  Path to the resulting packaged artifact.
+ */
+async function packager({ format, ...options }) {
+  switch (format) {
+    case "AppImage":
+      return appImage(/** @type {any} */ (options));
+    case "deb":
+    case "rpm":
+    case "msix":
+    case "nsis":
+    case "dmg":
+      throw new Error(
+        `options.format ${JSON.stringify(format)} is not implemented yet. Currently only "AppImage" is supported.`,
+      );
+    default:
+      throw new Error(
+        `Expected options.format to be one of "AppImage", "deb", "rpm", "msix", "nsis" or "dmg". Got ${JSON.stringify(format)}.`,
+      );
+  }
+}
+
+export default packager;

package/types/index.d.ts

@@ -1,6 +1,21 @@
-import appImage from "./appImage.js";
-declare const _default: {
-    appImage: typeof appImage;
-};
-export default _default;
-export { appImage };
+export type PackageFormat = "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
+/**
+ * Supported packaged output formats.
+ *
+ * `AppImage`, `deb` and `rpm` package a Linux build. `MSIX` and `NSIS`
+ * package a Windows build. Only `"AppImage"` is implemented today - the
+ * others are reserved so this option doesn't need to change shape once they
+ * land.
+ * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
+ */
+/**
+ * Package a built NW.js application.
+ * @async
+ * @function
+ * @param  {{format: PackageFormat} & Record<string, any>}  options  `format`, plus the options the matching packager (eg. `appImage`) expects.
+ * @returns {Promise<string>}  Path to the resulting packaged artifact.
+ */
+declare function packager({ format, ...options }: {
+    format: PackageFormat;
+} & Record<string, any>): Promise<string>;
+export default packager;