docs: improve types (#288)

.circleci/config.yml

@@ -10,6 +10,12 @@ workflows:
     jobs:
       - node/test:
           name: test-<< matrix.executor >>-<< matrix.node-version >>
+          override-ci-command: |
+            if [ << matrix.node-version >> = '14.16' ]; then
+              yarn install --frozen-lockfile --ignore-engines
+            else
+              yarn install --frozen-lockfile
+            fi
           pre-steps:
             - run: git config --global core.autocrlf input
             - when:

.gitignore

@@ -3,3 +3,4 @@ dist
 docs
 node_modules
 .idea
+.vscode

.prettierrc.json

@@ -3,5 +3,13 @@
   "tabWidth": 2,
   "singleQuote": true,
   "printWidth": 100,
-  "parser": "typescript"
+  "parser": "typescript",
+  "overrides": [
+    {
+      "files": ["*.json", "*.jsonc", "*.json5"],
+      "options": {
+        "parser": "json"
+      }
+    }
+  ]
 }

README.md

@@ -21,7 +21,6 @@ const zipFilePath = await download('4.0.4');
 
 ### Advanced: Downloading a macOS Electron Symbol File
 
-
 ```typescript
 import { downloadArtifact } from '@electron/get';
 
@@ -138,3 +137,9 @@ disable, set the `ELECTRON_GET_NO_PROGRESS` environment variable to any non-empt
 
 Downstream packages should utilize the `initializeProxy` function to add HTTP(S) proxy support. If
 the environment variable `ELECTRON_GET_USE_PROXY` is set, it is called automatically.
+
+### Debug
+
+[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages.
+Set the `DEBUG=@electron/get*` environment variable to log additional
+debug information from this module.

package.json

@@ -9,7 +9,7 @@
   "license": "MIT",
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "build:docs": "typedoc --out docs src/index.ts",
+    "build:docs": "npx typedoc",
     "eslint": "eslint --ext .ts src test",
     "jest": "jest --coverage",
     "lint": "npm run prettier && npm run eslint",
@@ -52,7 +52,7 @@
     "lint-staged": "^13.0.4",
     "prettier": "^1.17.1",
     "ts-jest": "^29.0.0",
-    "typedoc": "^0.23.21",
+    "typedoc": "~0.24.8",
     "typescript": "^4.9.3"
   },
   "eslintConfig": {

src/Downloader.ts

@@ -1,3 +1,18 @@
+/**
+ * Generic interface for the artifact downloader library.
+ * The default implementation is {@link GotDownloader},
+ * but any custom downloader can be passed to `@electron/get` via
+ * the {@link ElectronDownloadRequestOptions.downloader} option.
+ *
+ * @typeParam T - Options to pass to the downloader
+ * @category Downloader
+ */
 export interface Downloader<T> {
+  /**
+   * Download an artifact from an arbitrary URL to a file path on system
+   * @param url URL of the file to download
+   * @param targetFilePath Filesystem path to download the artifact to (including the file name)
+   * @param options Options to pass to the downloader
+   */
   download(url: string, targetFilePath: string, options: T): Promise<void>;
 }

src/GotDownloader.ts

@@ -8,11 +8,15 @@ import { Downloader } from './Downloader';
 const PROGRESS_BAR_DELAY_IN_SECONDS = 30;
 
 /**
- * See [`got#options`](https://github.com/sindresorhus/got#options) for possible keys/values.
+ * Options for the default [`got`](https://github.com/sindresorhus/got) Downloader implementation.
+ *
+ * @category Downloader
+ * @see {@link https://github.com/sindresorhus/got/tree/v11.8.5?tab=readme-ov-file#options | `got#options`} for possible keys/values.
  */
-export type GotDownloaderOptions = (GotOptions & { isStream?: true }) & {
+export type GotDownloaderOptions = (GotOptions) & { isStream?: true } & {
   /**
-   * if defined, triggers every time `got`'s `downloadProgress` event callback is triggered.
+   * if defined, triggers every time `got`'s
+   * {@link https://github.com/sindresorhus/got/tree/v11.8.5?tab=readme-ov-file#downloadprogress | `downloadProgress``} event callback is triggered.
    */
   getProgressCallback?: (progress: GotProgress) => Promise<void>;
   /**
@@ -22,6 +26,10 @@ export type GotDownloaderOptions = (GotOptions & { isStream?: true }) & {
   quiet?: boolean;
 };
 
+/**
+ * Default {@link Downloader} implemented with {@link https://npmjs.com/package/got | `got`}.
+ * @category Downloader
+ */
 export class GotDownloader implements Downloader<GotDownloaderOptions> {
   async download(
     url: string,

src/index.ts

@@ -8,6 +8,7 @@ import { getArtifactFileName, getArtifactRemoteURL, getArtifactVersion } from '.
 import {
   ElectronArtifactDetails,
   ElectronDownloadRequestOptions,
+  ElectronGenericArtifactDetails,
   ElectronPlatformArtifactDetails,
   ElectronPlatformArtifactDetailsWithDefaults,
 } from './types';
@@ -33,7 +34,7 @@ if (process.env.ELECTRON_GET_USE_PROXY) {
 }
 
 type ArtifactDownloader = (
-  _artifactDetails: ElectronPlatformArtifactDetailsWithDefaults,
+  _artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails,
 ) => Promise<string>;
 
 async function validateArtifact(
@@ -99,16 +100,22 @@ async function validateArtifact(
  * Downloads an artifact from an Electron release and returns an absolute path
  * to the downloaded file.
  *
+ * Each release of Electron comes with artifacts, many of which are
+ * platform/arch-specific (e.g. `ffmpeg-v31.0.0-darwin-arm64.zip`) and others that
+ * are generic (e.g. `SHASUMS256.txt`).
+ *
+ *
  * @param artifactDetails - The information required to download the artifact
+ * @category Download Artifact
  */
 export async function downloadArtifact(
-  _artifactDetails: ElectronPlatformArtifactDetailsWithDefaults,
+  artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails,
 ): Promise<string> {
-  const artifactDetails: ElectronArtifactDetails = {
-    ...(_artifactDetails as ElectronArtifactDetails),
+  const details: ElectronArtifactDetails = {
+    ...(artifactDetails as ElectronArtifactDetails),
   };
-  if (!_artifactDetails.isGeneric) {
-    const platformArtifactDetails = artifactDetails as ElectronPlatformArtifactDetails;
+  if (!artifactDetails.isGeneric) {
+    const platformArtifactDetails = details as ElectronPlatformArtifactDetails;
     if (!platformArtifactDetails.platform) {
       d('No platform found, defaulting to the host platform');
       platformArtifactDetails.platform = process.platform;
@@ -120,24 +127,24 @@ export async function downloadArtifact(
       platformArtifactDetails.arch = getHostArch();
     }
   }
-  ensureIsTruthyString(artifactDetails, 'version');
+  ensureIsTruthyString(details, 'version');
 
-  artifactDetails.version = getArtifactVersion(artifactDetails);
-  const fileName = getArtifactFileName(artifactDetails);
-  const url = await getArtifactRemoteURL(artifactDetails);
-  const cache = new Cache(artifactDetails.cacheRoot);
+  details.version = getArtifactVersion(details);
+  const fileName = getArtifactFileName(details);
+  const url = await getArtifactRemoteURL(details);
+  const cache = new Cache(details.cacheRoot);
 
   // Do not check if the file exists in the cache when force === true
-  if (!artifactDetails.force) {
-    d(`Checking the cache (${artifactDetails.cacheRoot}) for ${fileName} (${url})`);
+  if (!details.force) {
+    d(`Checking the cache (${details.cacheRoot}) for ${fileName} (${url})`);
     const cachedPath = await cache.getPathForFileInCache(url, fileName);
 
     if (cachedPath === null) {
       d('Cache miss');
     } else {
       d('Cache hit');
       try {
-        await validateArtifact(artifactDetails, cachedPath, downloadArtifact);
+        await validateArtifact(details, cachedPath, downloadArtifact);
 
         return cachedPath;
       } catch (err) {
@@ -148,40 +155,43 @@ export async function downloadArtifact(
   }
 
   if (
-    !artifactDetails.isGeneric &&
+    !details.isGeneric &&
     isOfficialLinuxIA32Download(
-      artifactDetails.platform,
-      artifactDetails.arch,
-      artifactDetails.version,
-      artifactDetails.mirrorOptions,
+      details.platform,
+      details.arch,
+      details.version,
+      details.mirrorOptions,
     )
   ) {
     console.warn('Official Linux/ia32 support is deprecated.');
     console.warn('For more info: https://electronjs.org/blog/linux-32bit-support');
   }
 
-  return await withTempDirectoryIn(artifactDetails.tempDirectory, async tempFolder => {
-    const tempDownloadPath = path.resolve(tempFolder, getArtifactFileName(artifactDetails));
+  return await withTempDirectoryIn(details.tempDirectory, async tempFolder => {
+    const tempDownloadPath = path.resolve(tempFolder, getArtifactFileName(details));
 
-    const downloader = artifactDetails.downloader || (await getDownloaderForSystem());
+    const downloader = details.downloader || (await getDownloaderForSystem());
     d(
       `Downloading ${url} to ${tempDownloadPath} with options: ${JSON.stringify(
-        artifactDetails.downloadOptions,
+        details.downloadOptions,
       )}`,
     );
-    await downloader.download(url, tempDownloadPath, artifactDetails.downloadOptions);
+    await downloader.download(url, tempDownloadPath, details.downloadOptions);
 
-    await validateArtifact(artifactDetails, tempDownloadPath, downloadArtifact);
+    await validateArtifact(details, tempDownloadPath, downloadArtifact);
 
     return await cache.putFileInCache(url, tempDownloadPath, fileName);
   });
 }
 
 /**
- * Downloads a specific version of Electron and returns an absolute path to a
+ * Downloads the Electron binary for a specific version and returns an absolute path to a
  * ZIP file.
  *
- * @param version - The version of Electron you want to download
+ * @param version - The version of Electron you want to download (e.g. `31.0.0`)
+ * @param options - Options to customize the download behavior
+ * @returns An absolute path to the downloaded ZIP file
+ * @category Download Electron
  */
 export function download(
   version: string,

src/proxy.ts

@@ -4,7 +4,20 @@ import { getEnv, setEnv } from './utils';
 const d = debug('@electron/get:proxy');
 
 /**
- * Initializes a third-party proxy module for HTTP(S) requests.
+ * Initializes a third-party proxy module for HTTP(S) requests. Call this function before
+ * using the {@link download} and {@link downloadArtifact} APIs if you need proxy support.
+ *
+ * If the `ELECTRON_GET_USE_PROXY` environment variable is set to `true`, this function will be
+ * called automatically for `@electron/get` requests.
+ *
+ * @category Utility
+ * @see {@link https://github.com/gajus/global-agent?tab=readme-ov-file#environment-variables | `global-agent`}
+ * documentation for available environment variables.
+ *
+ * @example
+ * ```sh
+ * export GLOBAL_AGENT_HTTPS_PROXY="$HTTPS_PROXY"
+ * ```
  */
 export function initializeProxy(): void {
   try {