@electron/get - npm Package Compare versions

Comparing version 3.0.0 to 3.1.0

dist/cjs/Downloader.d.ts

@@ -0,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>;
 }

dist/cjs/GotDownloader.d.ts

 import { Progress as GotProgress, Options as GotOptions } from 'got';
 import { Downloader } from './Downloader';
 /**
- * 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 & {
+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.
      */
@@ -19,4 +23,8 @@ getProgressCallback?: (progress: GotProgress) => Promise<void>;
 };
+/**
+ * Default {@link Downloader} implemented with {@link https://npmjs.com/package/got | `got`}.
+ * @category Downloader
+ */
 export declare class GotDownloader implements Downloader<GotDownloaderOptions> {
     download(url: string, targetFilePath: string, options?: GotDownloaderOptions): Promise<void>;
 }

dist/cjs/GotDownloader.js

@@ -20,2 +20,6 @@ "use strict";
 const PROGRESS_BAR_DELAY_IN_SECONDS = 30;
+/**
+ * Default {@link Downloader} implemented with {@link https://npmjs.com/package/got | `got`}.
+ * @category Downloader
+ */
 class GotDownloader {
@@ -22,0 +26,0 @@ async download(url, targetFilePath, options) {

dist/cjs/index.d.ts

@@ -1,2 +0,2 @@
-import { ElectronDownloadRequestOptions, ElectronPlatformArtifactDetailsWithDefaults } from './types';
+import { ElectronDownloadRequestOptions, ElectronGenericArtifactDetails, ElectronPlatformArtifactDetailsWithDefaults } from './types';
 export { getHostArch } from './utils';
@@ -9,11 +9,20 @@ export { initializeProxy } from './proxy';
  *
+ * 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 declare function downloadArtifact(_artifactDetails: ElectronPlatformArtifactDetailsWithDefaults): Promise<string>;
+export declare function downloadArtifact(artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails): Promise<string>;
 /**
- * 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 declare function download(version: string, options?: ElectronDownloadRequestOptions): Promise<string>;

dist/cjs/index.js

@@ -24,2 +24,3 @@ "use strict";
 const artifact_utils_1 = require("./artifact-utils");
+const types_1 = require("./types");
 const Cache_1 = require("./Cache");
@@ -63,3 +64,3 @@ const downloader_resolver_1 = require("./downloader-resolver");
                     artifactName: 'SHASUMS256.txt',
-                    force: artifactDetails.force,
+                    force: false,
                     downloadOptions: artifactDetails.downloadOptions,
@@ -69,19 +70,30 @@ cacheRoot: artifactDetails.cacheRoot,
                     mirrorOptions: artifactDetails.mirrorOptions,
+                    // Never use the cache for loading checksums, load
+                    // them fresh every time
+                    cacheMode: types_1.ElectronDownloadCacheMode.Bypass,
                 });
             }
-            // For versions 1.3.2 - 1.3.4, need to overwrite the `defaultTextEncoding` option:
-            // https://github.com/electron/electron/pull/6676#discussion_r75332120
-            if (semver.satisfies(artifactDetails.version, '1.3.2 - 1.3.4')) {
-                const validatorOptions = {};
-                validatorOptions.defaultTextEncoding = 'binary';
-                const checker = new sumchecker.ChecksumValidator('sha256', shasumPath, validatorOptions);
-                await checker.validate(path.dirname(downloadedAssetPath), path.basename(downloadedAssetPath));
+            try {
+                // For versions 1.3.2 - 1.3.4, need to overwrite the `defaultTextEncoding` option:
+                // https://github.com/electron/electron/pull/6676#discussion_r75332120
+                if (semver.satisfies(artifactDetails.version, '1.3.2 - 1.3.4')) {
+                    const validatorOptions = {};
+                    validatorOptions.defaultTextEncoding = 'binary';
+                    const checker = new sumchecker.ChecksumValidator('sha256', shasumPath, validatorOptions);
+                    await checker.validate(path.dirname(downloadedAssetPath), path.basename(downloadedAssetPath));
+                }
+                else {
+                    await sumchecker('sha256', shasumPath, path.dirname(downloadedAssetPath), [
+                        path.basename(downloadedAssetPath),
+                    ]);
+                }
             }
-            else {
-                await sumchecker('sha256', shasumPath, path.dirname(downloadedAssetPath), [
-                    path.basename(downloadedAssetPath),
-                ]);
+            finally {
+                // Once we're done make sure we clean up the shasum temp dir
+                await fs.remove(path.dirname(shasumPath));
             }
         }
-    });
+    }, (0, utils_1.doesCallerOwnTemporaryOutput)((0, utils_1.effectiveCacheMode)(artifactDetails))
+        ? utils_1.TempDirCleanUpMode.ORPHAN
+        : utils_1.TempDirCleanUpMode.CLEAN);
 }
@@ -92,8 +104,14 @@ /**
  *
+ * 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
  */
-async function downloadArtifact(_artifactDetails) {
-    const artifactDetails = Object.assign({}, _artifactDetails);
-    if (!_artifactDetails.isGeneric) {
-        const platformArtifactDetails = artifactDetails;
+async function downloadArtifact(artifactDetails) {
+    const details = Object.assign({}, artifactDetails);
+    if (!artifactDetails.isGeneric) {
+        const platformArtifactDetails = details;
         if (!platformArtifactDetails.platform) {
@@ -111,10 +129,11 @@ d('No platform found, defaulting to the host platform');
     }
-    (0, utils_1.ensureIsTruthyString)(artifactDetails, 'version');
-    artifactDetails.version = (0, artifact_utils_1.getArtifactVersion)(artifactDetails);
-    const fileName = (0, artifact_utils_1.getArtifactFileName)(artifactDetails);
-    const url = await (0, artifact_utils_1.getArtifactRemoteURL)(artifactDetails);
-    const cache = new Cache_1.Cache(artifactDetails.cacheRoot);
+    (0, utils_1.ensureIsTruthyString)(details, 'version');
+    details.version = (0, artifact_utils_1.getArtifactVersion)(details);
+    const fileName = (0, artifact_utils_1.getArtifactFileName)(details);
+    const url = await (0, artifact_utils_1.getArtifactRemoteURL)(details);
+    const cache = new Cache_1.Cache(details.cacheRoot);
+    const cacheMode = (0, utils_1.effectiveCacheMode)(details);
     // 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 ((0, utils_1.shouldTryReadCache)(cacheMode)) {
+        d(`Checking the cache (${details.cacheRoot}) for ${fileName} (${url})`);
         const cachedPath = await cache.getPathForFileInCache(url, fileName);
@@ -126,7 +145,18 @@ if (cachedPath === null) {
             d('Cache hit');
+            let artifactPath = cachedPath;
+            if ((0, utils_1.doesCallerOwnTemporaryOutput)(cacheMode)) {
+                // Copy out of cache into temporary directory if readOnly cache so
+                // that the caller can take ownership of the returned file
+                const tempDir = await (0, utils_1.mkdtemp)(artifactDetails.tempDirectory);
+                artifactPath = path.resolve(tempDir, fileName);
+                await fs.copyFile(cachedPath, artifactPath);
+            }
             try {
-                await validateArtifact(artifactDetails, cachedPath, downloadArtifact);
-                return cachedPath;
+                await validateArtifact(details, artifactPath, downloadArtifact);
+                return artifactPath;
             }
             catch (err) {
+                if ((0, utils_1.doesCallerOwnTemporaryOutput)(cacheMode)) {
+                    await fs.remove(path.dirname(artifactPath));
+                }
                 d("Artifact in cache didn't match checksums", err);
@@ -137,22 +167,30 @@ d('falling back to re-download');
     }
-    if (!artifactDetails.isGeneric &&
-        (0, utils_1.isOfficialLinuxIA32Download)(artifactDetails.platform, artifactDetails.arch, artifactDetails.version, artifactDetails.mirrorOptions)) {
+    if (!details.isGeneric &&
+        (0, utils_1.isOfficialLinuxIA32Download)(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 (0, utils_1.withTempDirectoryIn)(artifactDetails.tempDirectory, async (tempFolder) => {
-        const tempDownloadPath = path.resolve(tempFolder, (0, artifact_utils_1.getArtifactFileName)(artifactDetails));
-        const downloader = artifactDetails.downloader || (await (0, downloader_resolver_1.getDownloaderForSystem)());
-        d(`Downloading ${url} to ${tempDownloadPath} with options: ${JSON.stringify(artifactDetails.downloadOptions)}`);
-        await downloader.download(url, tempDownloadPath, artifactDetails.downloadOptions);
-        await validateArtifact(artifactDetails, tempDownloadPath, downloadArtifact);
-        return await cache.putFileInCache(url, tempDownloadPath, fileName);
-    });
+    return await (0, utils_1.withTempDirectoryIn)(details.tempDirectory, async (tempFolder) => {
+        const tempDownloadPath = path.resolve(tempFolder, (0, artifact_utils_1.getArtifactFileName)(details));
+        const downloader = details.downloader || (await (0, downloader_resolver_1.getDownloaderForSystem)());
+        d(`Downloading ${url} to ${tempDownloadPath} with options: ${JSON.stringify(details.downloadOptions)}`);
+        await downloader.download(url, tempDownloadPath, details.downloadOptions);
+        await validateArtifact(details, tempDownloadPath, downloadArtifact);
+        if ((0, utils_1.doesCallerOwnTemporaryOutput)(cacheMode)) {
+            return tempDownloadPath;
+        }
+        else {
+            return await cache.putFileInCache(url, tempDownloadPath, fileName);
+        }
+    }, (0, utils_1.doesCallerOwnTemporaryOutput)(cacheMode) ? utils_1.TempDirCleanUpMode.ORPHAN : utils_1.TempDirCleanUpMode.CLEAN);
 }
 exports.downloadArtifact = downloadArtifact;
 /**
- * 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
  */
@@ -159,0 +197,0 @@ function download(version, options) {

dist/cjs/proxy.d.ts

 /**
- * 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 declare function initializeProxy(): void;

dist/cjs/proxy.js

@@ -8,3 +8,16 @@ "use strict";
 /**
- * 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"
+ * ```
  */
@@ -11,0 +24,0 @@ function initializeProxy() {

dist/cjs/types.d.ts

 import { Downloader } from './Downloader';
-export { Downloader };
+import { GotDownloader, GotDownloaderOptions } from './GotDownloader';
+export { Downloader, GotDownloader, GotDownloaderOptions };
+/**
+ * Custom downloaders can implement any set of options.
+ * @category Downloader
+ */
 export type DownloadOptions = any;
+/**
+ * Options for specifying an alternative download mirror for Electron.
+ *
+ * @category Utility
+ * @example
+ *
+ * To download the Electron v4.0.4 release for x64 Linux from
+ * https://github.com/electron/electron/releases/download/v4.0.4/electron-v4.0.4-linux-x64.zip
+ *
+ * ```js
+ * const opts = {
+ *  mirror: 'https://github.com/electron/electron/releases/download',
+ *  customDir: 'v4.0.4',
+ *  customFilename: 'electron-v4.0.4-linux-x64.zip',
+ * }
+ * ```
+ */
 export interface MirrorOptions {
     /**
-     * DEPRECATED - see nightlyMirror.
+     * @deprecated
+     * @see {@link MirrorOptions.nightlyMirror}
      */
     nightly_mirror?: string;
     /**
-     * The Electron nightly-specific mirror URL.
+     * The mirror URL for [`electron-nightly`](https://npmjs.com/package/electron-nightly),
+     * which lives in a separate npm package.
      */
     nightlyMirror?: string;
     /**
-     * The base URL of the mirror to download from,
+     * The base URL of the mirror to download from.
      * e.g https://github.com/electron/electron/releases/download
@@ -39,2 +63,6 @@ */
 }
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export interface ElectronDownloadRequest {
@@ -52,2 +80,26 @@ /**
 }
+export declare enum ElectronDownloadCacheMode {
+    /**
+     * Reads from the cache if present
+     * Writes to the cache after fetch if not present
+     */
+    ReadWrite = 0,
+    /**
+     * Reads from the cache if present
+     * Will **not** write back to the cache after fetching missing artifact
+     */
+    ReadOnly = 1,
+    /**
+     * Skips reading from the cache
+     * Will write back into the cache, overwriting anything currently in the cache after fetch
+     */
+    WriteOnly = 2,
+    /**
+     * Bypasses the cache completely, neither reads from nor writes to the cache
+     */
+    Bypass = 3
+}
+/**
+ * @category Download Electron
+ */
 export interface ElectronDownloadRequestOptions {
@@ -57,3 +109,4 @@ /**
      *
-     * Defaults to `false`.
+     * @defaultValue `false`
+     * @deprecated This option is deprecated and directly maps to {@link cacheMode | `cacheMode: ElectronDownloadCacheMode.WriteOnly`}
      */
@@ -65,3 +118,3 @@ force?: boolean;
      *
-     * Defaults to `false`.
+     * @defaultValue `false`
      */
@@ -77,2 +130,9 @@ unsafelyDisableChecksums?: boolean;
      * the values are their respective SHA256 checksums.
+     *
+     * @example
+     * ```json
+     * {
+     *   "electron-v4.0.4-linux-x64.zip": "877617029f4c0f2b24f3805a1c3554ba166fda65c4e88df9480ae7b6ffa26a22"
+     * }
+     * ```
      */
@@ -83,3 +143,3 @@ checksums?: Record<string, string>;
      *
-     * The default value is dependent upon the host platform:
+     * @defaultValue The default value is dependent upon the host platform:
      *
@@ -93,2 +153,4 @@ * * Linux: `$XDG_CACHE_HOME` or `~/.cache/electron/`
      * Options passed to the downloader module.
+     *
+     * @see {@link GotDownloaderOptions} for options for the default {@link GotDownloader}.
      */
@@ -101,3 +163,3 @@ downloadOptions?: DownloadOptions;
     /**
-     * The custom {@link Downloader} class used to download artifacts. Defaults to the
+     * A custom {@link Downloader} class used to download artifacts. Defaults to the
      * built-in {@link GotDownloader}.
@@ -109,5 +171,29 @@ */
      * It is used before artifacts are put into cache.
+     *
+     * @defaultValue the OS default temporary directory via [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir)
      */
     tempDirectory?: string;
+    /**
+     * Controls the cache read and write behavior.
+     *
+     * When set to either {@link ElectronDownloadCacheMode.ReadOnly | ReadOnly} or
+     * {@link ElectronDownloadCacheMode.Bypass | Bypass}, the caller is responsible
+     * for cleaning up the returned file path once they are done using it
+     * (e.g. via `fs.remove(path.dirname(pathFromElectronGet))`).
+     *
+     * When set to either {@link ElectronDownloadCacheMode.WriteOnly | WriteOnly} or
+     * {@link ElectronDownloadCacheMode.ReadWrite | ReadWrite} (the default), the caller
+     * should not move or delete the file path that is returned as the path
+     * points directly to the disk cache.
+     *
+     * This option cannot be used in conjunction with {@link ElectronDownloadRequestOptions.force}.
+     *
+     * @defaultValue {@link ElectronDownloadCacheMode.ReadWrite}
+     */
+    cacheMode?: ElectronDownloadCacheMode;
 }
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export type ElectronPlatformArtifactDetails = {
@@ -119,2 +205,4 @@ /**
      * * `linux`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processplatform | process.platform} docs
      */
@@ -127,2 +215,4 @@ platform: string;
      * * `armv7l`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processarch | process.arch} docs
      */
@@ -133,10 +223,48 @@ arch: string;
 } & ElectronDownloadRequest & ElectronDownloadRequestOptions;
+/**
+ * Options to download a generic (i.e. platform and architecture-agnostic)
+ * Electron artifact. Contains all options from {@link ElectronDownloadRequestOptions},
+ * but specifies a `version` and `artifactName` for the artifact to download.
+ *
+ * @category Download Artifact
+ * @interface
+ */
 export type ElectronGenericArtifactDetails = {
     isGeneric: true;
 } & ElectronDownloadRequest & ElectronDownloadRequestOptions;
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export type ElectronArtifactDetails = ElectronPlatformArtifactDetails | ElectronGenericArtifactDetails;
-export type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
-export type ElectronPlatformArtifactDetailsWithDefaults = (Omit<ElectronPlatformArtifactDetails, 'platform' | 'arch'> & {
+/**
+ * Options to download a platform and architecture-specific Electron artifact.
+ * Contains all options from {@link ElectronDownloadRequestOptions}, but
+ * specifies a `version` and `artifactName` for the artifact to download.
+ *
+ * If `platform` and `arch` are omitted, they will be inferred using the host
+ * system platform and architecture.
+ *
+ * @category Download Artifact
+ * @interface
+ */
+export type ElectronPlatformArtifactDetailsWithDefaults = Omit<ElectronPlatformArtifactDetails, 'platform' | 'arch'> & {
+    /**
+     * The target artifact platform. These are Node-style platform names, for example:
+     * * `win32`
+     * * `darwin`
+     * * `linux`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processplatform | process.platform} docs
+     */
     platform?: string;
+    /**
+     * The target artifact architecture. These are Node-style architecture names, for example:
+     * * `ia32`
+     * * `x64`
+     * * `armv7l`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processarch | process.arch} docs
+     */
     arch?: string;
-}) | ElectronGenericArtifactDetails;
+};

dist/cjs/types.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElectronDownloadCacheMode = exports.GotDownloader = void 0;
+const GotDownloader_1 = require("./GotDownloader");
+Object.defineProperty(exports, "GotDownloader", { enumerable: true, get: function () { return GotDownloader_1.GotDownloader; } });
+var ElectronDownloadCacheMode;
+(function (ElectronDownloadCacheMode) {
+    /**
+     * Reads from the cache if present
+     * Writes to the cache after fetch if not present
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["ReadWrite"] = 0] = "ReadWrite";
+    /**
+     * Reads from the cache if present
+     * Will **not** write back to the cache after fetching missing artifact
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["ReadOnly"] = 1] = "ReadOnly";
+    /**
+     * Skips reading from the cache
+     * Will write back into the cache, overwriting anything currently in the cache after fetch
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["WriteOnly"] = 2] = "WriteOnly";
+    /**
+     * Bypasses the cache completely, neither reads from nor writes to the cache
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["Bypass"] = 3] = "Bypass";
+})(ElectronDownloadCacheMode = exports.ElectronDownloadCacheMode || (exports.ElectronDownloadCacheMode = {}));
 //# sourceMappingURL=types.js.map

dist/cjs/utils.d.ts

@@ -1,3 +0,9 @@
-export declare function withTempDirectoryIn<T>(parentDirectory: string | undefined, fn: (directory: string) => Promise<T>): Promise<T>;
-export declare function withTempDirectory<T>(fn: (directory: string) => Promise<T>): Promise<T>;
+import { ElectronDownloadCacheMode, ElectronGenericArtifactDetails, ElectronPlatformArtifactDetailsWithDefaults } from './types';
+export declare function mkdtemp(parentDirectory?: string): Promise<string>;
+export declare enum TempDirCleanUpMode {
+    CLEAN = 0,
+    ORPHAN = 1
+}
+export declare function withTempDirectoryIn<T>(parentDirectory: string | undefined, fn: (directory: string) => Promise<T>, cleanUp: TempDirCleanUpMode): Promise<T>;
+export declare function withTempDirectory<T>(fn: (directory: string) => Promise<T>, cleanUp: TempDirCleanUpMode): Promise<T>;
 export declare function normalizeVersion(version: string): string;
@@ -15,3 +21,5 @@ /**
  * Generates an architecture name that would be used in an Electron or Node.js
- * download file name, from the `process` module information.
+ * download file name from the `process` module information.
+ *
+ * @category Utility
  */
@@ -27,1 +35,5 @@ export declare function getHostArch(): string;
 export declare function setEnv(key: string, value: string | undefined): void;
+export declare function effectiveCacheMode(artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails): ElectronDownloadCacheMode;
+export declare function shouldTryReadCache(cacheMode: ElectronDownloadCacheMode): boolean;
+export declare function shouldWriteCache(cacheMode: ElectronDownloadCacheMode): boolean;
+export declare function doesCallerOwnTemporaryOutput(cacheMode: ElectronDownloadCacheMode): boolean;

dist/cjs/utils.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setEnv = exports.getEnv = exports.isOfficialLinuxIA32Download = exports.ensureIsTruthyString = exports.getHostArch = exports.getNodeArch = exports.uname = exports.normalizeVersion = exports.withTempDirectory = exports.withTempDirectoryIn = void 0;
+exports.doesCallerOwnTemporaryOutput = exports.shouldWriteCache = exports.shouldTryReadCache = exports.effectiveCacheMode = exports.setEnv = exports.getEnv = exports.isOfficialLinuxIA32Download = exports.ensureIsTruthyString = exports.getHostArch = exports.getNodeArch = exports.uname = exports.normalizeVersion = exports.withTempDirectory = exports.withTempDirectoryIn = exports.TempDirCleanUpMode = exports.mkdtemp = void 0;
 const childProcess = require("child_process");
@@ -8,2 +8,3 @@ const fs = require("fs-extra");
 const path = require("path");
+const types_1 = require("./types");
 async function useAndRemoveDirectory(directory, fn) {
@@ -19,10 +20,24 @@ let result;
 }
-async function withTempDirectoryIn(parentDirectory = os.tmpdir(), fn) {
+async function mkdtemp(parentDirectory = os.tmpdir()) {
     const tempDirectoryPrefix = 'electron-download-';
-    const tempDirectory = await fs.mkdtemp(path.resolve(parentDirectory, tempDirectoryPrefix));
-    return useAndRemoveDirectory(tempDirectory, fn);
+    return await fs.mkdtemp(path.resolve(parentDirectory, tempDirectoryPrefix));
 }
+exports.mkdtemp = mkdtemp;
+var TempDirCleanUpMode;
+(function (TempDirCleanUpMode) {
+    TempDirCleanUpMode[TempDirCleanUpMode["CLEAN"] = 0] = "CLEAN";
+    TempDirCleanUpMode[TempDirCleanUpMode["ORPHAN"] = 1] = "ORPHAN";
+})(TempDirCleanUpMode = exports.TempDirCleanUpMode || (exports.TempDirCleanUpMode = {}));
+async function withTempDirectoryIn(parentDirectory = os.tmpdir(), fn, cleanUp) {
+    const tempDirectory = await mkdtemp(parentDirectory);
+    if (cleanUp === TempDirCleanUpMode.CLEAN) {
+        return useAndRemoveDirectory(tempDirectory, fn);
+    }
+    else {
+        return fn(tempDirectory);
+    }
+}
 exports.withTempDirectoryIn = withTempDirectoryIn;
-async function withTempDirectory(fn) {
-    return withTempDirectoryIn(undefined, fn);
+async function withTempDirectory(fn, cleanUp) {
+    return withTempDirectoryIn(undefined, fn, cleanUp);
 }
@@ -67,3 +82,5 @@ exports.withTempDirectory = withTempDirectory;
  * Generates an architecture name that would be used in an Electron or Node.js
- * download file name, from the `process` module information.
+ * download file name from the `process` module information.
+ *
+ * @category Utility
  */
@@ -111,2 +128,27 @@ function getHostArch() {
 exports.setEnv = setEnv;
+function effectiveCacheMode(artifactDetails) {
+    if (artifactDetails.force) {
+        if (artifactDetails.cacheMode) {
+            throw new Error('Setting both "force" and "cacheMode" is not supported, please exclusively use "cacheMode"');
+        }
+        return types_1.ElectronDownloadCacheMode.WriteOnly;
+    }
+    return artifactDetails.cacheMode || types_1.ElectronDownloadCacheMode.ReadWrite;
+}
+exports.effectiveCacheMode = effectiveCacheMode;
+function shouldTryReadCache(cacheMode) {
+    return (cacheMode === types_1.ElectronDownloadCacheMode.ReadOnly ||
+        cacheMode === types_1.ElectronDownloadCacheMode.ReadWrite);
+}
+exports.shouldTryReadCache = shouldTryReadCache;
+function shouldWriteCache(cacheMode) {
+    return (cacheMode === types_1.ElectronDownloadCacheMode.WriteOnly ||
+        cacheMode === types_1.ElectronDownloadCacheMode.ReadWrite);
+}
+exports.shouldWriteCache = shouldWriteCache;
+function doesCallerOwnTemporaryOutput(cacheMode) {
+    return (cacheMode === types_1.ElectronDownloadCacheMode.Bypass ||
+        cacheMode === types_1.ElectronDownloadCacheMode.ReadOnly);
+}
+exports.doesCallerOwnTemporaryOutput = doesCallerOwnTemporaryOutput;
 //# sourceMappingURL=utils.js.map

dist/esm/Downloader.d.ts

@@ -0,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>;
 }

dist/esm/GotDownloader.d.ts

 import { Progress as GotProgress, Options as GotOptions } from 'got';
 import { Downloader } from './Downloader';
 /**
- * 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 & {
+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.
      */
@@ -19,4 +23,8 @@ getProgressCallback?: (progress: GotProgress) => Promise<void>;
 };
+/**
+ * Default {@link Downloader} implemented with {@link https://npmjs.com/package/got | `got`}.
+ * @category Downloader
+ */
 export declare class GotDownloader implements Downloader<GotDownloaderOptions> {
     download(url: string, targetFilePath: string, options?: GotDownloaderOptions): Promise<void>;
 }

dist/esm/GotDownloader.js

@@ -17,2 +17,6 @@ var __rest = (this && this.__rest) || function (s, e) {
 const PROGRESS_BAR_DELAY_IN_SECONDS = 30;
+/**
+ * Default {@link Downloader} implemented with {@link https://npmjs.com/package/got | `got`}.
+ * @category Downloader
+ */
 export class GotDownloader {
@@ -19,0 +23,0 @@ async download(url, targetFilePath, options) {

dist/esm/index.d.ts

@@ -1,2 +0,2 @@
-import { ElectronDownloadRequestOptions, ElectronPlatformArtifactDetailsWithDefaults } from './types';
+import { ElectronDownloadRequestOptions, ElectronGenericArtifactDetails, ElectronPlatformArtifactDetailsWithDefaults } from './types';
 export { getHostArch } from './utils';
@@ -9,11 +9,20 @@ export { initializeProxy } from './proxy';
  *
+ * 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 declare function downloadArtifact(_artifactDetails: ElectronPlatformArtifactDetailsWithDefaults): Promise<string>;
+export declare function downloadArtifact(artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails): Promise<string>;
 /**
- * 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 declare function download(version: string, options?: ElectronDownloadRequestOptions): Promise<string>;

dist/esm/index.js

@@ -7,6 +7,7 @@ import debug from 'debug';
 import { getArtifactFileName, getArtifactRemoteURL, getArtifactVersion } from './artifact-utils';
+import { ElectronDownloadCacheMode, } from './types';
 import { Cache } from './Cache';
 import { getDownloaderForSystem } from './downloader-resolver';
 import { initializeProxy } from './proxy';
-import { withTempDirectoryIn, getHostArch, getNodeArch, ensureIsTruthyString, isOfficialLinuxIA32Download, } from './utils';
+import { withTempDirectoryIn, getHostArch, getNodeArch, ensureIsTruthyString, isOfficialLinuxIA32Download, mkdtemp, doesCallerOwnTemporaryOutput, effectiveCacheMode, shouldTryReadCache, TempDirCleanUpMode, } from './utils';
 export { getHostArch } from './utils';
@@ -44,3 +45,3 @@ export { initializeProxy } from './proxy';
                     artifactName: 'SHASUMS256.txt',
-                    force: artifactDetails.force,
+                    force: false,
                     downloadOptions: artifactDetails.downloadOptions,
@@ -50,19 +51,30 @@ cacheRoot: artifactDetails.cacheRoot,
                     mirrorOptions: artifactDetails.mirrorOptions,
+                    // Never use the cache for loading checksums, load
+                    // them fresh every time
+                    cacheMode: ElectronDownloadCacheMode.Bypass,
                 });
             }
-            // For versions 1.3.2 - 1.3.4, need to overwrite the `defaultTextEncoding` option:
-            // https://github.com/electron/electron/pull/6676#discussion_r75332120
-            if (semver.satisfies(artifactDetails.version, '1.3.2 - 1.3.4')) {
-                const validatorOptions = {};
-                validatorOptions.defaultTextEncoding = 'binary';
-                const checker = new sumchecker.ChecksumValidator('sha256', shasumPath, validatorOptions);
-                await checker.validate(path.dirname(downloadedAssetPath), path.basename(downloadedAssetPath));
+            try {
+                // For versions 1.3.2 - 1.3.4, need to overwrite the `defaultTextEncoding` option:
+                // https://github.com/electron/electron/pull/6676#discussion_r75332120
+                if (semver.satisfies(artifactDetails.version, '1.3.2 - 1.3.4')) {
+                    const validatorOptions = {};
+                    validatorOptions.defaultTextEncoding = 'binary';
+                    const checker = new sumchecker.ChecksumValidator('sha256', shasumPath, validatorOptions);
+                    await checker.validate(path.dirname(downloadedAssetPath), path.basename(downloadedAssetPath));
+                }
+                else {
+                    await sumchecker('sha256', shasumPath, path.dirname(downloadedAssetPath), [
+                        path.basename(downloadedAssetPath),
+                    ]);
+                }
             }
-            else {
-                await sumchecker('sha256', shasumPath, path.dirname(downloadedAssetPath), [
-                    path.basename(downloadedAssetPath),
-                ]);
+            finally {
+                // Once we're done make sure we clean up the shasum temp dir
+                await fs.remove(path.dirname(shasumPath));
             }
         }
-    });
+    }, doesCallerOwnTemporaryOutput(effectiveCacheMode(artifactDetails))
+        ? TempDirCleanUpMode.ORPHAN
+        : TempDirCleanUpMode.CLEAN);
 }
@@ -73,8 +85,14 @@ /**
  *
+ * 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) {
-    const artifactDetails = Object.assign({}, _artifactDetails);
-    if (!_artifactDetails.isGeneric) {
-        const platformArtifactDetails = artifactDetails;
+export async function downloadArtifact(artifactDetails) {
+    const details = Object.assign({}, artifactDetails);
+    if (!artifactDetails.isGeneric) {
+        const platformArtifactDetails = details;
         if (!platformArtifactDetails.platform) {
@@ -92,10 +110,11 @@ d('No platform found, defaulting to the host platform');
     }
-    ensureIsTruthyString(artifactDetails, 'version');
-    artifactDetails.version = getArtifactVersion(artifactDetails);
-    const fileName = getArtifactFileName(artifactDetails);
-    const url = await getArtifactRemoteURL(artifactDetails);
-    const cache = new Cache(artifactDetails.cacheRoot);
+    ensureIsTruthyString(details, 'version');
+    details.version = getArtifactVersion(details);
+    const fileName = getArtifactFileName(details);
+    const url = await getArtifactRemoteURL(details);
+    const cache = new Cache(details.cacheRoot);
+    const cacheMode = effectiveCacheMode(details);
     // 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 (shouldTryReadCache(cacheMode)) {
+        d(`Checking the cache (${details.cacheRoot}) for ${fileName} (${url})`);
         const cachedPath = await cache.getPathForFileInCache(url, fileName);
@@ -107,7 +126,18 @@ if (cachedPath === null) {
             d('Cache hit');
+            let artifactPath = cachedPath;
+            if (doesCallerOwnTemporaryOutput(cacheMode)) {
+                // Copy out of cache into temporary directory if readOnly cache so
+                // that the caller can take ownership of the returned file
+                const tempDir = await mkdtemp(artifactDetails.tempDirectory);
+                artifactPath = path.resolve(tempDir, fileName);
+                await fs.copyFile(cachedPath, artifactPath);
+            }
             try {
-                await validateArtifact(artifactDetails, cachedPath, downloadArtifact);
-                return cachedPath;
+                await validateArtifact(details, artifactPath, downloadArtifact);
+                return artifactPath;
             }
             catch (err) {
+                if (doesCallerOwnTemporaryOutput(cacheMode)) {
+                    await fs.remove(path.dirname(artifactPath));
+                }
                 d("Artifact in cache didn't match checksums", err);
@@ -118,21 +148,29 @@ d('falling back to re-download');
     }
-    if (!artifactDetails.isGeneric &&
-        isOfficialLinuxIA32Download(artifactDetails.platform, artifactDetails.arch, artifactDetails.version, artifactDetails.mirrorOptions)) {
+    if (!details.isGeneric &&
+        isOfficialLinuxIA32Download(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));
-        const downloader = artifactDetails.downloader || (await getDownloaderForSystem());
-        d(`Downloading ${url} to ${tempDownloadPath} with options: ${JSON.stringify(artifactDetails.downloadOptions)}`);
-        await downloader.download(url, tempDownloadPath, artifactDetails.downloadOptions);
-        await validateArtifact(artifactDetails, tempDownloadPath, downloadArtifact);
-        return await cache.putFileInCache(url, tempDownloadPath, fileName);
-    });
+    return await withTempDirectoryIn(details.tempDirectory, async (tempFolder) => {
+        const tempDownloadPath = path.resolve(tempFolder, getArtifactFileName(details));
+        const downloader = details.downloader || (await getDownloaderForSystem());
+        d(`Downloading ${url} to ${tempDownloadPath} with options: ${JSON.stringify(details.downloadOptions)}`);
+        await downloader.download(url, tempDownloadPath, details.downloadOptions);
+        await validateArtifact(details, tempDownloadPath, downloadArtifact);
+        if (doesCallerOwnTemporaryOutput(cacheMode)) {
+            return tempDownloadPath;
+        }
+        else {
+            return await cache.putFileInCache(url, tempDownloadPath, fileName);
+        }
+    }, doesCallerOwnTemporaryOutput(cacheMode) ? TempDirCleanUpMode.ORPHAN : TempDirCleanUpMode.CLEAN);
 }
 /**
- * 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
  */
@@ -139,0 +177,0 @@ export function download(version, options) {

dist/esm/proxy.d.ts

 /**
- * 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 declare function initializeProxy(): void;

dist/esm/proxy.js

@@ -5,3 +5,16 @@ import * as debug from 'debug';
 /**
- * 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"
+ * ```
  */
@@ -8,0 +21,0 @@ export function initializeProxy() {

dist/esm/types.d.ts

 import { Downloader } from './Downloader';
-export { Downloader };
+import { GotDownloader, GotDownloaderOptions } from './GotDownloader';
+export { Downloader, GotDownloader, GotDownloaderOptions };
+/**
+ * Custom downloaders can implement any set of options.
+ * @category Downloader
+ */
 export type DownloadOptions = any;
+/**
+ * Options for specifying an alternative download mirror for Electron.
+ *
+ * @category Utility
+ * @example
+ *
+ * To download the Electron v4.0.4 release for x64 Linux from
+ * https://github.com/electron/electron/releases/download/v4.0.4/electron-v4.0.4-linux-x64.zip
+ *
+ * ```js
+ * const opts = {
+ *  mirror: 'https://github.com/electron/electron/releases/download',
+ *  customDir: 'v4.0.4',
+ *  customFilename: 'electron-v4.0.4-linux-x64.zip',
+ * }
+ * ```
+ */
 export interface MirrorOptions {
     /**
-     * DEPRECATED - see nightlyMirror.
+     * @deprecated
+     * @see {@link MirrorOptions.nightlyMirror}
      */
     nightly_mirror?: string;
     /**
-     * The Electron nightly-specific mirror URL.
+     * The mirror URL for [`electron-nightly`](https://npmjs.com/package/electron-nightly),
+     * which lives in a separate npm package.
      */
     nightlyMirror?: string;
     /**
-     * The base URL of the mirror to download from,
+     * The base URL of the mirror to download from.
      * e.g https://github.com/electron/electron/releases/download
@@ -39,2 +63,6 @@ */
 }
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export interface ElectronDownloadRequest {
@@ -52,2 +80,26 @@ /**
 }
+export declare enum ElectronDownloadCacheMode {
+    /**
+     * Reads from the cache if present
+     * Writes to the cache after fetch if not present
+     */
+    ReadWrite = 0,
+    /**
+     * Reads from the cache if present
+     * Will **not** write back to the cache after fetching missing artifact
+     */
+    ReadOnly = 1,
+    /**
+     * Skips reading from the cache
+     * Will write back into the cache, overwriting anything currently in the cache after fetch
+     */
+    WriteOnly = 2,
+    /**
+     * Bypasses the cache completely, neither reads from nor writes to the cache
+     */
+    Bypass = 3
+}
+/**
+ * @category Download Electron
+ */
 export interface ElectronDownloadRequestOptions {
@@ -57,3 +109,4 @@ /**
      *
-     * Defaults to `false`.
+     * @defaultValue `false`
+     * @deprecated This option is deprecated and directly maps to {@link cacheMode | `cacheMode: ElectronDownloadCacheMode.WriteOnly`}
      */
@@ -65,3 +118,3 @@ force?: boolean;
      *
-     * Defaults to `false`.
+     * @defaultValue `false`
      */
@@ -77,2 +130,9 @@ unsafelyDisableChecksums?: boolean;
      * the values are their respective SHA256 checksums.
+     *
+     * @example
+     * ```json
+     * {
+     *   "electron-v4.0.4-linux-x64.zip": "877617029f4c0f2b24f3805a1c3554ba166fda65c4e88df9480ae7b6ffa26a22"
+     * }
+     * ```
      */
@@ -83,3 +143,3 @@ checksums?: Record<string, string>;
      *
-     * The default value is dependent upon the host platform:
+     * @defaultValue The default value is dependent upon the host platform:
      *
@@ -93,2 +153,4 @@ * * Linux: `$XDG_CACHE_HOME` or `~/.cache/electron/`
      * Options passed to the downloader module.
+     *
+     * @see {@link GotDownloaderOptions} for options for the default {@link GotDownloader}.
      */
@@ -101,3 +163,3 @@ downloadOptions?: DownloadOptions;
     /**
-     * The custom {@link Downloader} class used to download artifacts. Defaults to the
+     * A custom {@link Downloader} class used to download artifacts. Defaults to the
      * built-in {@link GotDownloader}.
@@ -109,5 +171,29 @@ */
      * It is used before artifacts are put into cache.
+     *
+     * @defaultValue the OS default temporary directory via [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir)
      */
     tempDirectory?: string;
+    /**
+     * Controls the cache read and write behavior.
+     *
+     * When set to either {@link ElectronDownloadCacheMode.ReadOnly | ReadOnly} or
+     * {@link ElectronDownloadCacheMode.Bypass | Bypass}, the caller is responsible
+     * for cleaning up the returned file path once they are done using it
+     * (e.g. via `fs.remove(path.dirname(pathFromElectronGet))`).
+     *
+     * When set to either {@link ElectronDownloadCacheMode.WriteOnly | WriteOnly} or
+     * {@link ElectronDownloadCacheMode.ReadWrite | ReadWrite} (the default), the caller
+     * should not move or delete the file path that is returned as the path
+     * points directly to the disk cache.
+     *
+     * This option cannot be used in conjunction with {@link ElectronDownloadRequestOptions.force}.
+     *
+     * @defaultValue {@link ElectronDownloadCacheMode.ReadWrite}
+     */
+    cacheMode?: ElectronDownloadCacheMode;
 }
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export type ElectronPlatformArtifactDetails = {
@@ -119,2 +205,4 @@ /**
      * * `linux`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processplatform | process.platform} docs
      */
@@ -127,2 +215,4 @@ platform: string;
      * * `armv7l`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processarch | process.arch} docs
      */
@@ -133,10 +223,48 @@ arch: string;
 } & ElectronDownloadRequest & ElectronDownloadRequestOptions;
+/**
+ * Options to download a generic (i.e. platform and architecture-agnostic)
+ * Electron artifact. Contains all options from {@link ElectronDownloadRequestOptions},
+ * but specifies a `version` and `artifactName` for the artifact to download.
+ *
+ * @category Download Artifact
+ * @interface
+ */
 export type ElectronGenericArtifactDetails = {
     isGeneric: true;
 } & ElectronDownloadRequest & ElectronDownloadRequestOptions;
+/**
+ * @category Download Artifact
+ * @internal
+ */
 export type ElectronArtifactDetails = ElectronPlatformArtifactDetails | ElectronGenericArtifactDetails;
-export type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
-export type ElectronPlatformArtifactDetailsWithDefaults = (Omit<ElectronPlatformArtifactDetails, 'platform' | 'arch'> & {
+/**
+ * Options to download a platform and architecture-specific Electron artifact.
+ * Contains all options from {@link ElectronDownloadRequestOptions}, but
+ * specifies a `version` and `artifactName` for the artifact to download.
+ *
+ * If `platform` and `arch` are omitted, they will be inferred using the host
+ * system platform and architecture.
+ *
+ * @category Download Artifact
+ * @interface
+ */
+export type ElectronPlatformArtifactDetailsWithDefaults = Omit<ElectronPlatformArtifactDetails, 'platform' | 'arch'> & {
+    /**
+     * The target artifact platform. These are Node-style platform names, for example:
+     * * `win32`
+     * * `darwin`
+     * * `linux`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processplatform | process.platform} docs
+     */
     platform?: string;
+    /**
+     * The target artifact architecture. These are Node-style architecture names, for example:
+     * * `ia32`
+     * * `x64`
+     * * `armv7l`
+     *
+     * @see Node.js {@link https://nodejs.org/api/process.html#processarch | process.arch} docs
+     */
     arch?: string;
-}) | ElectronGenericArtifactDetails;
+};

dist/esm/types.js

@@ -1,2 +0,25 @@
-export {};
+import { GotDownloader } from './GotDownloader';
+export { GotDownloader };
+export var ElectronDownloadCacheMode;
+(function (ElectronDownloadCacheMode) {
+    /**
+     * Reads from the cache if present
+     * Writes to the cache after fetch if not present
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["ReadWrite"] = 0] = "ReadWrite";
+    /**
+     * Reads from the cache if present
+     * Will **not** write back to the cache after fetching missing artifact
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["ReadOnly"] = 1] = "ReadOnly";
+    /**
+     * Skips reading from the cache
+     * Will write back into the cache, overwriting anything currently in the cache after fetch
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["WriteOnly"] = 2] = "WriteOnly";
+    /**
+     * Bypasses the cache completely, neither reads from nor writes to the cache
+     */
+    ElectronDownloadCacheMode[ElectronDownloadCacheMode["Bypass"] = 3] = "Bypass";
+})(ElectronDownloadCacheMode || (ElectronDownloadCacheMode = {}));
 //# sourceMappingURL=types.js.map

dist/esm/utils.d.ts

@@ -1,3 +0,9 @@
-export declare function withTempDirectoryIn<T>(parentDirectory: string | undefined, fn: (directory: string) => Promise<T>): Promise<T>;
-export declare function withTempDirectory<T>(fn: (directory: string) => Promise<T>): Promise<T>;
+import { ElectronDownloadCacheMode, ElectronGenericArtifactDetails, ElectronPlatformArtifactDetailsWithDefaults } from './types';
+export declare function mkdtemp(parentDirectory?: string): Promise<string>;
+export declare enum TempDirCleanUpMode {
+    CLEAN = 0,
+    ORPHAN = 1
+}
+export declare function withTempDirectoryIn<T>(parentDirectory: string | undefined, fn: (directory: string) => Promise<T>, cleanUp: TempDirCleanUpMode): Promise<T>;
+export declare function withTempDirectory<T>(fn: (directory: string) => Promise<T>, cleanUp: TempDirCleanUpMode): Promise<T>;
 export declare function normalizeVersion(version: string): string;
@@ -15,3 +21,5 @@ /**
  * Generates an architecture name that would be used in an Electron or Node.js
- * download file name, from the `process` module information.
+ * download file name from the `process` module information.
+ *
+ * @category Utility
  */
@@ -27,1 +35,5 @@ export declare function getHostArch(): string;
 export declare function setEnv(key: string, value: string | undefined): void;
+export declare function effectiveCacheMode(artifactDetails: ElectronPlatformArtifactDetailsWithDefaults | ElectronGenericArtifactDetails): ElectronDownloadCacheMode;
+export declare function shouldTryReadCache(cacheMode: ElectronDownloadCacheMode): boolean;
+export declare function shouldWriteCache(cacheMode: ElectronDownloadCacheMode): boolean;
+export declare function doesCallerOwnTemporaryOutput(cacheMode: ElectronDownloadCacheMode): boolean;

dist/esm/utils.js

@@ -5,2 +5,3 @@ import * as childProcess from 'child_process';
 import * as path from 'path';
+import { ElectronDownloadCacheMode, } from './types';
 async function useAndRemoveDirectory(directory, fn) {
@@ -16,10 +17,23 @@ let result;
 }
-export async function withTempDirectoryIn(parentDirectory = os.tmpdir(), fn) {
+export async function mkdtemp(parentDirectory = os.tmpdir()) {
     const tempDirectoryPrefix = 'electron-download-';
-    const tempDirectory = await fs.mkdtemp(path.resolve(parentDirectory, tempDirectoryPrefix));
-    return useAndRemoveDirectory(tempDirectory, fn);
+    return await fs.mkdtemp(path.resolve(parentDirectory, tempDirectoryPrefix));
 }
-export async function withTempDirectory(fn) {
-    return withTempDirectoryIn(undefined, fn);
+export var TempDirCleanUpMode;
+(function (TempDirCleanUpMode) {
+    TempDirCleanUpMode[TempDirCleanUpMode["CLEAN"] = 0] = "CLEAN";
+    TempDirCleanUpMode[TempDirCleanUpMode["ORPHAN"] = 1] = "ORPHAN";
+})(TempDirCleanUpMode || (TempDirCleanUpMode = {}));
+export async function withTempDirectoryIn(parentDirectory = os.tmpdir(), fn, cleanUp) {
+    const tempDirectory = await mkdtemp(parentDirectory);
+    if (cleanUp === TempDirCleanUpMode.CLEAN) {
+        return useAndRemoveDirectory(tempDirectory, fn);
+    }
+    else {
+        return fn(tempDirectory);
+    }
 }
+export async function withTempDirectory(fn, cleanUp) {
+    return withTempDirectoryIn(undefined, fn, cleanUp);
+}
 export function normalizeVersion(version) {
@@ -59,3 +73,5 @@ if (!version.startsWith('v')) {
  * Generates an architecture name that would be used in an Electron or Node.js
- * download file name, from the `process` module information.
+ * download file name from the `process` module information.
+ *
+ * @category Utility
  */
@@ -98,2 +114,23 @@ export function getHostArch() {
 }
+export function effectiveCacheMode(artifactDetails) {
+    if (artifactDetails.force) {
+        if (artifactDetails.cacheMode) {
+            throw new Error('Setting both "force" and "cacheMode" is not supported, please exclusively use "cacheMode"');
+        }
+        return ElectronDownloadCacheMode.WriteOnly;
+    }
+    return artifactDetails.cacheMode || ElectronDownloadCacheMode.ReadWrite;
+}
+export function shouldTryReadCache(cacheMode) {
+    return (cacheMode === ElectronDownloadCacheMode.ReadOnly ||
+        cacheMode === ElectronDownloadCacheMode.ReadWrite);
+}
+export function shouldWriteCache(cacheMode) {
+    return (cacheMode === ElectronDownloadCacheMode.WriteOnly ||
+        cacheMode === ElectronDownloadCacheMode.ReadWrite);
+}
+export function doesCallerOwnTemporaryOutput(cacheMode) {
+    return (cacheMode === ElectronDownloadCacheMode.Bypass ||
+        cacheMode === ElectronDownloadCacheMode.ReadOnly);
+}
 //# sourceMappingURL=utils.js.map

package.json

 {
   "name": "@electron/get",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Utility for downloading artifacts from different versions of Electron",
@@ -12,3 +12,3 @@ "main": "dist/cjs/index.js",
     "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",
@@ -39,3 +39,2 @@ "jest": "jest --coverage",
   "devDependencies": {
-    "@continuous-auth/semantic-release-npm": "^3.0.0",
     "@types/debug": "^4.1.4",
@@ -58,3 +57,3 @@ "@types/fs-extra": "^8.0.0",
     "ts-jest": "^29.0.0",
-    "typedoc": "^0.23.21",
+    "typedoc": "~0.24.8",
     "typescript": "^4.9.3"
@@ -61,0 +60,0 @@ },

README.md

@@ -10,2 +10,4 @@ # @electron/get
 
+For full API details, see the [API documentation](https://electron.github.io/get/).
+
 ### Simple: Downloading an Electron Binary ZIP
@@ -23,3 +25,2 @@
 
-
 ```typescript
@@ -141,1 +142,7 @@ import { downloadArtifact } from '@electron/get';
 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.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

125656

increased by31.52%

Dev dependency count

19

decreased by-5%

Lines of code

1996

increased by43.8%

Number of lines in readme file

145

increased by4.32%

No dependency changes