@appium/support 7.0.4 → 7.0.6

package/lib/{zip.js → zip.ts}

@@ -1,199 +1,60 @@
 import _ from 'lodash';
-import B from 'bluebird';
+import {promisify} from 'node:util';
 import * as yauzl from 'yauzl';
 import archiver from 'archiver';
-import {createWriteStream} from 'fs';
-import path from 'path';
-import stream from 'stream';
+import {createWriteStream} from 'node:fs';
+import path from 'node:path';
+import stream from 'node:stream';
+import {pipeline} from 'node:stream/promises';
 import {fs} from './fs';
 import {isWindows} from './system';
 import {Base64Encode} from 'base64-stream';
-import {toReadableSizeString, GiB} from './util';
+import {isSubPath, toReadableSizeString, GiB} from './util';
 import {Timer} from './timing';
 import log from './logger';
 import getStream from 'get-stream';
 import {exec} from 'teen_process';
 
-/**
- * @type {(path: string, options?: yauzl.Options) => Promise<yauzl.ZipFile>}
- */
-const openZip = B.promisify(yauzl.open);
-/**
- * @type {(source: NodeJS.ReadableStream, destination: NodeJS.WritableStream) => Promise<NodeJS.WritableStream>}
- */
-const pipeline = B.promisify(stream.pipeline);
-const ZIP_MAGIC = 'PK';
-const IFMT = 61440;
-const IFDIR = 16384;
-const IFLNK = 40960;
-
-// This class is mostly copied from https://github.com/maxogden/extract-zip/blob/master/index.js
-class ZipExtractor {
-  /** @type {yauzl.ZipFile} */
-  zipfile;
-
-  constructor(sourcePath, opts = {}) {
-    this.zipPath = sourcePath;
-    this.opts = opts;
-    this.canceled = false;
-  }
-
-  extractFileName(entry) {
-    return _.isBuffer(entry.fileName)
-      ? entry.fileName.toString(this.opts.fileNamesEncoding)
-      : entry.fileName;
-  }
-
-  async extract() {
-    const {dir, fileNamesEncoding} = this.opts;
-    this.zipfile = await openZip(this.zipPath, {
-      lazyEntries: true,
-      // https://github.com/thejoshwolfe/yauzl/commit/cc7455ac789ba84973184e5ebde0581cdc4c3b39#diff-04c6e90faac2675aa89e2176d2eec7d8R95
-      decodeStrings: !fileNamesEncoding,
-    });
-    this.canceled = false;
+const openZip = promisify(yauzl.open) as (
+  zipPath: string,
+  options?: yauzl.Options
+) => Promise<yauzl.ZipFile>;
 
-    return new B((resolve, reject) => {
-      this.zipfile.on('error', (err) => {
-        this.canceled = true;
-        reject(err);
-      });
-      this.zipfile.readEntry();
-
-      this.zipfile.on('close', () => {
-        if (!this.canceled) {
-          resolve();
-        }
-      });
-
-      this.zipfile.on('entry', async (entry) => {
-        if (this.canceled) {
-          return;
-        }
-
-        const fileName = this.extractFileName(entry);
-        if (fileName.startsWith('__MACOSX/')) {
-          this.zipfile.readEntry();
-          return;
-        }
-
-        const destDir = path.dirname(path.join(dir, fileName));
-        try {
-          await fs.mkdir(destDir, {recursive: true});
-
-          const canonicalDestDir = await fs.realpath(destDir);
-          const relativeDestDir = path.relative(dir, canonicalDestDir);
-
-          if (relativeDestDir.split(path.sep).includes('..')) {
-            new Error(
-              `Out of bound path "${canonicalDestDir}" found while processing file ${fileName}`
-            );
-          }
-
-          await this.extractEntry(entry);
-          this.zipfile.readEntry();
-        } catch (err) {
-          this.canceled = true;
-          this.zipfile.close();
-          reject(err);
-        }
-      });
-    });
-  }
-
-  async extractEntry(entry) {
-    if (this.canceled) {
-      return;
-    }
-
-    const {dir} = this.opts;
-
-    const fileName = this.extractFileName(entry);
-    const dest = path.join(dir, fileName);
-
-    // convert external file attr int into a fs stat mode int
-    const mode = (entry.externalFileAttributes >> 16) & 0xffff;
-    // check if it's a symlink or dir (using stat mode constants)
-    const isSymlink = (mode & IFMT) === IFLNK;
-    const isDir =
-      (mode & IFMT) === IFDIR ||
-      // Failsafe, borrowed from jsZip
-      fileName.endsWith('/') ||
-      // check for windows weird way of specifying a directory
-      // https://github.com/maxogden/extract-zip/issues/13#issuecomment-154494566
-      (entry.versionMadeBy >> 8 === 0 && entry.externalFileAttributes === 16);
-    const procMode = this.getExtractedMode(mode, isDir) & 0o777;
-    // always ensure folders are created
-    const destDir = isDir ? dest : path.dirname(dest);
-    const mkdirOptions = {recursive: true};
-    if (isDir) {
-      mkdirOptions.mode = procMode;
-    }
-    await fs.mkdir(destDir, mkdirOptions);
-    if (isDir) {
-      return;
-    }
-
-    /** @type {(entry: yauzl.Entry) => Promise<NodeJS.ReadableStream>} */
-    const openReadStream = B.promisify(this.zipfile.openReadStream.bind(this.zipfile));
-    const readStream = await openReadStream(entry);
-    if (isSymlink) {
-      // @ts-ignore This typecast is ok
-      const link = await getStream(readStream);
-      await fs.symlink(link, dest);
-    } else {
-      await pipeline(readStream, fs.createWriteStream(dest, {mode: procMode}));
-    }
-  }
-
-  getExtractedMode(entryMode, isDir) {
-    const {defaultDirMode, defaultFileMode} = this.opts;
-
-    let mode = entryMode;
-    // Set defaults, if necessary
-    if (mode === 0) {
-      if (isDir) {
-        if (defaultDirMode) {
-          mode = parseInt(defaultDirMode, 10);
-        }
-
-        if (!mode) {
-          mode = 0o755;
-        }
-      } else {
-        if (defaultFileMode) {
-          mode = parseInt(defaultFileMode, 10);
-        }
+const ZIP_MAGIC = 'PK';
+const IFMT = 0b1111000000000000;
+const IFDIR = 0b0100000000000000;
+const IFLNK = 0b1010000000000000;
 
-        if (!mode) {
-          mode = 0o644;
-        }
-      }
-    }
+// Internal extraction helpers are defined near the end of the file.
 
-    return mode;
-  }
+export interface ExtractAllOptions {
+  /**
+   * The encoding to use for extracted file names.
+   * For ZIP archives created on MacOS it is usually expected to be `utf8`.
+   * By default it is autodetected based on the entry metadata and is only needed to be set explicitly
+   * if the particular archive does not comply to the standards, which leads to corrupted file names
+   * after extraction. Only applicable if system unzip binary is NOT being used.
+   */
+  fileNamesEncoding?: BufferEncoding;
+  /**
+   * If true, attempt to use system unzip; if this fails,
+   * fallback to the JS unzip implementation.
+   */
+  useSystemUnzip?: boolean;
 }
 
-/**
- * @typedef ExtractAllOptions
- * @property {string} [fileNamesEncoding] The encoding to use for extracted file names.
- * For ZIP archives created on MacOS it is usually expected to be `utf8`.
- * By default it is autodetected based on the entry metadata and is only needed to be set explicitly
- * if the particular archive does not comply to the standards, which leads to corrupted file names
- * after extraction. Only applicable if system unzip binary is NOT being used.
- * @property {boolean} [useSystemUnzip] If true, attempt to use system unzip; if this fails,
- * fallback to the JS unzip implementation.
- */
-
 /**
  * Extract zipfile to a directory
  *
- * @param {string} zipFilePath The full path to the source ZIP file
- * @param {string} destDir The full path to the destination folder
- * @param {ExtractAllOptions} [opts]
+ * @param zipFilePath The full path to the source ZIP file
+ * @param destDir The full path to the destination folder
+ * @param opts Extraction options
  */
-async function extractAllTo(zipFilePath, destDir, opts = /** @type {ExtractAllOptions} */ ({})) {
+export async function extractAllTo(
+  zipFilePath: string,
+  destDir: string,
+  opts: ExtractAllOptions = {}
+): Promise<void> {
   if (!path.isAbsolute(destDir)) {
     throw new Error(`Target path '${destDir}' is expected to be absolute`);
   }
@@ -204,63 +65,36 @@ async function extractAllTo(zipFilePath, destDir, opts = /** @type {ExtractAllOp
     try {
       await extractWithSystemUnzip(zipFilePath, dir);
       return;
-    } catch (err) {
+    } catch (err: any) {
       log.warn('unzip failed; falling back to JS: %s', err.stderr || err.message);
     }
   }
   const extractor = new ZipExtractor(zipFilePath, {
-    ...opts,
+    ...(opts as ExtractAllOptions & Partial<ZipExtractorOptions>),
     dir,
   });
   await extractor.extract();
 }
 
-/**
- * Executes system unzip (e.g., `/usr/bin/unzip`). If available, it is
- * significantly faster than the JS implementation.
- * By default all files in the destDir get overridden if already exist.
- *
- * @param {string} zipFilePath The full path to the source ZIP file
- * @param {string} destDir The full path to the destination folder.
- * This folder is expected to already exist before extracting the archive.
- */
-async function extractWithSystemUnzip(zipFilePath, destDir) {
-  const isWindowsHost = isWindows();
-  let executablePath;
-  try {
-    executablePath = await getExecutablePath(isWindowsHost ? 'powershell.exe' : 'unzip');
-  } catch {
-    throw new Error('Could not find system unzip');
-  }
-
-  if (isWindowsHost) {
-    // on Windows we use PowerShell to unzip files
-    await exec(executablePath, [
-      '-command',
-      'Expand-Archive',
-      '-LiteralPath',
-      zipFilePath,
-      '-DestinationPath',
-      destDir,
-      '-Force',
-    ]);
-  } else {
-    // -q means quiet (no stdout)
-    // -o means overwrite
-    // -d is the dest dir
-    await exec(executablePath, ['-q', '-o', zipFilePath, '-d', destDir]);
-  }
-}
-
 /**
  * Extract a single zip entry to a directory
  *
- * @param {yauzl.ZipFile} zipFile The source ZIP stream
- * @param {yauzl.Entry} entry The entry instance
- * @param {string} destDir The full path to the destination folder
+ * @private
+ * @param zipFile The source ZIP stream
+ * @param entry The entry instance
+ * @param destDir The full path to the destination folder
  */
-async function _extractEntryTo(zipFile, entry, destDir) {
+export async function _extractEntryTo(
+  zipFile: yauzl.ZipFile,
+  entry: yauzl.Entry,
+  destDir: string
+): Promise<void> {
   const dstPath = path.resolve(destDir, entry.fileName);
+  if (!isSubPath(dstPath, destDir)) {
+    throw new Error(
+      `Out of bound path "${dstPath}" found while processing file ${entry.fileName}`
+    );
+  }
 
   // Create dest directory if doesn't exist already
   if (entry.fileName.endsWith('/')) {
@@ -274,54 +108,59 @@ async function _extractEntryTo(zipFile, entry, destDir) {
 
   // Create a write stream
   const writeStream = createWriteStream(dstPath, {flags: 'w'});
-  const writeStreamPromise = new B((resolve, reject) => {
+  const writeStreamPromise = new Promise<void>((resolve, reject) => {
     writeStream.once('finish', resolve);
     writeStream.once('error', reject);
   });
 
-  // Create zipReadStream and pipe data to the write stream
-  // (for some odd reason B.promisify doesn't work on zipfile.openReadStream, it causes an error 'closed')
-  const zipReadStream = await new B((resolve, reject) => {
-    zipFile.openReadStream(entry, (err, readStream) => (err ? reject(err) : resolve(readStream)));
-  });
-  const zipReadStreamPromise = new B((resolve, reject) => {
+  const openReadStream = promisify(zipFile.openReadStream.bind(zipFile)) as (
+    entry: yauzl.Entry
+  ) => Promise<NodeJS.ReadableStream>;
+  const zipReadStream = await openReadStream(entry);
+  const zipReadStreamPromise = new Promise<void>((resolve, reject) => {
     zipReadStream.once('end', resolve);
     zipReadStream.once('error', reject);
   });
   zipReadStream.pipe(writeStream);
 
   // Wait for the zipReadStream and writeStream to end before returning
-  return await B.all([zipReadStreamPromise, writeStreamPromise]);
+  await Promise.all([zipReadStreamPromise, writeStreamPromise]);
 }
 
-/**
- * @typedef ZipEntry
- * @property {yauzl.Entry} entry The actual entry instance
- * @property {function} extractEntryTo An async function, which accepts one parameter.
- * This parameter contains the destination folder path to which this function is going to extract the entry.
- */
+export interface ZipEntry {
+  /** The actual entry instance */
+  entry: yauzl.Entry;
+  /**
+   * Async function which accepts the destination folder path
+   * and extracts this entry into it.
+   */
+  extractEntryTo: (destDir: string) => Promise<void>;
+}
 
 /**
  * Get entries for a zip folder
  *
- * @param {string} zipFilePath The full path to the source ZIP file
- * @param {function} onEntry Callback when entry is read.
+ * @param zipFilePath The full path to the source ZIP file
+ * @param onEntry Callback when entry is read.
  * The callback is expected to accept one argument of ZipEntry type.
- * The iteration through the source zip file will bi terminated as soon as
+ * The iteration through the source zip file will be terminated as soon as
  * the result of this function equals to `false`.
  */
-async function readEntries(zipFilePath, onEntry) {
+export async function readEntries(
+  zipFilePath: string,
+  onEntry: (entry: ZipEntry) => boolean | void | Promise<boolean | void>
+): Promise<void> {
   // Open a zip file and start reading entries
   const zipfile = await openZip(zipFilePath, {lazyEntries: true});
-  const zipReadStreamPromise = new B((resolve, reject) => {
+  const zipReadStreamPromise = new Promise<void>((resolve, reject) => {
     zipfile.once('end', resolve);
     zipfile.once('error', reject);
 
     // On each entry, call 'onEntry' and then read the next entry
-    zipfile.on('entry', async (entry) => {
+    zipfile.on('entry', async (entry: yauzl.Entry) => {
       const res = await onEntry({
         entry,
-        extractEntryTo: async (destDir) => await _extractEntryTo(zipfile, entry, destDir),
+        extractEntryTo: async (destDir: string) => await _extractEntryTo(zipfile, entry, destDir),
       });
       if (res === false) {
         return zipfile.emit('end');
@@ -332,46 +171,53 @@ async function readEntries(zipFilePath, onEntry) {
   zipfile.readEntry();
 
   // Wait for the entries to finish being iterated through
-  return await zipReadStreamPromise;
+  await zipReadStreamPromise;
 }
 
-/**
- * @typedef ZipOptions
- * @property {boolean} [encodeToBase64=false] Whether to encode
- * the resulting archive to a base64-encoded string
- * @property {boolean} [isMetered=true] Whether to log the actual
- * archiver performance
- * @property {number} [maxSize=1073741824] The maximum size of
- * the resulting archive in bytes. This is set to 1GB by default, because
- * Appium limits the maximum HTTP body size to 1GB. Also, the NodeJS heap
- * size must be enough to keep the resulting object (usually this size is
- * limited to 1.4 GB)
- * @property {number} [level=9] The compression level. The maximum
- * level is 9 (the best compression, worst performance). The minimum
- * compression level is 0 (no compression).
- */
+export interface ZipOptions {
+  /** Whether to encode the resulting archive to a base64-encoded string */
+  encodeToBase64?: boolean;
+  /** Whether to log the actual archiver performance */
+  isMetered?: boolean;
+  /**
+   * The maximum size of the resulting archive in bytes.
+   * This is set to 1GB by default, because Appium limits the maximum HTTP body size to 1GB.
+   * Also, the NodeJS heap size must be enough to keep the resulting object
+   * (usually this size is limited to 1.4 GB)
+   */
+  maxSize?: number;
+  /**
+   * The compression level.
+   * The maximum level is 9 (the best compression, worst performance).
+   * The minimum compression level is 0 (no compression).
+   */
+  level?: number;
+}
 
 /**
  * Converts contents of local directory to an in-memory .zip buffer
  *
- * @param {string} srcPath The full path to the folder or file being zipped
- * @param {ZipOptions} opts Zipping options
- * @returns {Promise<Buffer>} Zipped (and encoded if `encodeToBase64` is truthy)
+ * @param srcPath The full path to the folder or file being zipped
+ * @param opts Zipping options
+ * @returns Zipped (and encoded if `encodeToBase64` is truthy)
  * content of the source path as memory buffer
  * @throws {Error} if there was an error while reading the source
  * or the source is too big
  */
-async function toInMemoryZip(srcPath, opts = /** @type {ZipOptions} */ ({})) {
+export async function toInMemoryZip(
+  srcPath: string,
+  opts: ZipOptions = {}
+): Promise<Buffer> {
   if (!(await fs.exists(srcPath))) {
     throw new Error(`No such file or folder: ${srcPath}`);
   }
 
   const {isMetered = true, encodeToBase64 = false, maxSize = 1 * GiB, level = 9} = opts;
-  const resultBuffers = [];
+  const resultBuffers: Buffer[] = [];
   let resultBuffersSize = 0;
   // Create a writable stream that zip buffers will be streamed to
   const resultWriteStream = new stream.Writable({
-    write: (buffer, encoding, next) => {
+    write(buffer: Buffer, _encoding: string, next: (err?: Error) => void) {
       resultBuffers.push(buffer);
       resultBuffersSize += buffer.length;
       if (maxSize > 0 && resultBuffersSize > maxSize) {
@@ -391,10 +237,10 @@ async function toInMemoryZip(srcPath, opts = /** @type {ZipOptions} */ ({})) {
   const archive = archiver('zip', {
     zlib: {level},
   });
-  let srcSize = null;
+  let srcSize: number | null = null;
   const base64EncoderStream = encodeToBase64 ? new Base64Encode() : null;
-  const resultWriteStreamPromise = new B((resolve, reject) => {
-    resultWriteStream.once('error', (e) => {
+  const resultWriteStreamPromise = new Promise<void>((resolve, reject) => {
+    resultWriteStream.once('error', (e: Error) => {
       if (base64EncoderStream) {
         archive.unpipe(base64EncoderStream);
         base64EncoderStream.unpipe(resultWriteStream);
@@ -410,9 +256,11 @@ async function toInMemoryZip(srcPath, opts = /** @type {ZipOptions} */ ({})) {
       resolve();
     });
   });
-  const archiveStreamPromise = new B((resolve, reject) => {
+  const archiveStreamPromise = new Promise<void>((resolve, reject) => {
     archive.once('finish', resolve);
-    archive.once('error', (e) => reject(new Error(`Failed to archive '${srcPath}': ${e.message}`)));
+    archive.once('error', (e: Error) =>
+      reject(new Error(`Failed to archive '${srcPath}': ${e.message}`))
+    );
   });
   const timer = isMetered ? new Timer().start() : null;
   if ((await fs.stat(srcPath)).isDirectory()) {
@@ -431,7 +279,7 @@ async function toInMemoryZip(srcPath, opts = /** @type {ZipOptions} */ ({})) {
   archive.finalize();
 
   // Wait for the streams to finish
-  await B.all([archiveStreamPromise, resultWriteStreamPromise]);
+  await Promise.all([archiveStreamPromise, resultWriteStreamPromise]);
 
   if (timer) {
     log.debug(
@@ -449,10 +297,10 @@ async function toInMemoryZip(srcPath, opts = /** @type {ZipOptions} */ ({})) {
 /**
  * Verifies whether the given file is a valid ZIP archive
  *
- * @param {string} filePath - Full path to the file
+ * @param filePath - Full path to the file
  * @throws {Error} If the file does not exist or is not a valid ZIP archive
  */
-async function assertValidZip(filePath) {
+export async function assertValidZip(filePath: string): Promise<boolean> {
   if (!(await fs.exists(filePath))) {
     throw new Error(`The file at '${filePath}' does not exist`);
   }
@@ -478,48 +326,51 @@ async function assertValidZip(filePath) {
   }
 }
 
-/**
- * @typedef ZipCompressionOptions
- * @property {number} level [9] - Compression level in range 0..9
- * (greater numbers mean better compression, but longer processing time)
- */
+export interface ZipCompressionOptions {
+  /**
+   * Compression level in range 0..9
+   * (greater numbers mean better compression, but longer processing time)
+   */
+  level?: number;
+}
 
-/**
- * @typedef ZipSourceOptions
- * @property {string} [pattern='**\/*'] - GLOB pattern for compression
- * @property {string} [cwd] - The source root folder (the parent folder of
- * the destination file by default)
- * @property {string[]} [ignore] - The list of ignored patterns
- */
+export interface ZipSourceOptions {
+  /** GLOB pattern for compression */
+  pattern?: string;
+  /** The source root folder (the parent folder of the destination file by default) */
+  cwd?: string;
+  /** The list of ignored patterns */
+  ignore?: string[];
+}
 
 /**
  * Creates an archive based on the given glob pattern
  *
- * @param {string} dstPath - The resulting archive path
- * @param {ZipSourceOptions} src - Source options
- * @param {ZipCompressionOptions} opts - Compression options
+ * @param dstPath - The resulting archive path
+ * @param src - Source options
+ * @param opts - Compression options
  * @throws {Error} If there was an error while creating the archive
  */
-async function toArchive(
-  dstPath,
-  src = /** @type {ZipSourceOptions} */ ({}),
-  opts = /** @type {ZipCompressionOptions} */ ({})
-) {
+export async function toArchive(
+  dstPath: string,
+  src: ZipSourceOptions = {},
+  opts: ZipCompressionOptions = {}
+): Promise<void> {
   const {level = 9} = opts;
   const {pattern = '**/*', cwd = path.dirname(dstPath), ignore = []} = src;
   const archive = archiver('zip', {zlib: {level}});
-  const stream = fs.createWriteStream(dstPath);
-  return await new B((resolve, reject) => {
+  const outStream = fs.createWriteStream(dstPath);
+  await new Promise<void>((resolve, reject) => {
     archive
       .glob(pattern, {
         cwd,
         ignore,
       })
       .on('error', reject)
-      .pipe(stream);
-    stream
-      .on('error', (e) => {
-        archive.unpipe(stream);
+      .pipe(outStream);
+    outStream
+      .on('error', (e: Error) => {
+        archive.unpipe(outStream);
         archive.abort();
         archive.destroy();
         reject(e);
@@ -529,22 +380,215 @@ async function toArchive(
   });
 }
 
+interface ZipExtractorOptions {
+  dir: string;
+  fileNamesEncoding?: BufferEncoding;
+  defaultDirMode?: string;
+  defaultFileMode?: string;
+}
+
+// This class is mostly copied from https://github.com/maxogden/extract-zip/blob/master/index.js
+class ZipExtractor {
+  zipfile!: yauzl.ZipFile;
+  private readonly zipPath: string;
+  private readonly opts: ZipExtractorOptions;
+  private canceled = false;
+
+  constructor(sourcePath: string, opts: ZipExtractorOptions) {
+    this.zipPath = sourcePath;
+    this.opts = opts;
+  }
+
+  private extractFileName(entry: yauzl.Entry): string {
+    if (Buffer.isBuffer(entry.fileName)) {
+      return entry.fileName.toString(this.opts.fileNamesEncoding);
+    }
+    return entry.fileName;
+  }
+
+  async extract(): Promise<void> {
+    const {dir, fileNamesEncoding} = this.opts;
+    this.zipfile = await openZip(this.zipPath, {
+      lazyEntries: true,
+      // https://github.com/thejoshwolfe/yauzl/commit/cc7455ac789ba84973184e5ebde0581cdc4c3b39#diff-04c6e90faac2675aa89e2176d2eec7d8R95
+      decodeStrings: !fileNamesEncoding,
+    });
+    this.canceled = false;
+
+    return new Promise<void>((resolve, reject) => {
+      this.zipfile.on('error', (err: Error) => {
+        this.canceled = true;
+        reject(err);
+      });
+      this.zipfile.readEntry();
+
+      this.zipfile.on('close', () => {
+        if (!this.canceled) {
+          resolve();
+        }
+      });
+
+      this.zipfile.on('entry', async (entry: yauzl.Entry) => {
+        if (this.canceled) {
+          return;
+        }
+
+        const fileName = this.extractFileName(entry);
+        if (fileName.startsWith('__MACOSX/')) {
+          this.zipfile.readEntry();
+          return;
+        }
+
+        const destDir = path.dirname(path.join(dir, fileName));
+        try {
+          await fs.mkdir(destDir, {recursive: true});
+
+          const canonicalDestDir = await fs.realpath(destDir);
+          const relativeDestDir = path.relative(dir, canonicalDestDir);
+
+          if (relativeDestDir.split(path.sep).includes('..')) {
+            throw new Error(
+              `Out of bound path "${canonicalDestDir}" found while processing file ${fileName}`
+            );
+          }
+
+          await this.extractEntry(entry);
+          this.zipfile.readEntry();
+        } catch (err) {
+          this.canceled = true;
+          this.zipfile.close();
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private async extractEntry(entry: yauzl.Entry): Promise<void> {
+    if (this.canceled) {
+      return;
+    }
+
+    const {dir} = this.opts;
+
+    const fileName = this.extractFileName(entry);
+    const dest = path.join(dir, fileName);
+
+    // convert external file attr int into a fs stat mode int
+    const mode = (entry.externalFileAttributes >> 16) & 0xffff;
+    // check if it's a symlink or dir (using stat mode constants)
+    const isSymlink = (mode & IFMT) === IFLNK;
+    const isDir =
+      (mode & IFMT) === IFDIR ||
+      // Failsafe, borrowed from jsZip
+      fileName.endsWith('/') ||
+      // check for windows weird way of specifying a directory
+      // https://github.com/maxogden/extract-zip/issues/13#issuecomment-154494566
+      (entry.versionMadeBy >> 8 === 0 && entry.externalFileAttributes === 16);
+    const procMode = this.getExtractedMode(mode, isDir) & 0o777;
+    // always ensure folders are created
+    const destDir = isDir ? dest : path.dirname(dest);
+    const mkdirOptions: Parameters<typeof fs.mkdir>[1] = {recursive: true};
+    if (isDir) {
+      mkdirOptions.mode = procMode;
+    }
+    await fs.mkdir(destDir, mkdirOptions);
+    if (isDir) {
+      return;
+    }
+
+    const openReadStream = promisify(
+      this.zipfile.openReadStream.bind(this.zipfile)
+    ) as (entry: yauzl.Entry) => Promise<NodeJS.ReadableStream>;
+    const readStream = await openReadStream(entry);
+    if (isSymlink) {
+      const link = await getStream(readStream);
+      await fs.symlink(link, dest);
+    } else {
+      await pipeline(readStream, fs.createWriteStream(dest, {mode: procMode}));
+    }
+  }
+
+  private getExtractedMode(entryMode: number, isDir: boolean): number {
+    const {defaultDirMode, defaultFileMode} = this.opts;
+
+    let mode = entryMode;
+    // Set defaults, if necessary
+    if (mode === 0) {
+      if (isDir) {
+        if (defaultDirMode) {
+          mode = parseInt(defaultDirMode, 10);
+        }
+
+        if (!mode) {
+          mode = 0o755;
+        }
+      } else {
+        if (defaultFileMode) {
+          mode = parseInt(defaultFileMode, 10);
+        }
+
+        if (!mode) {
+          mode = 0o644;
+        }
+      }
+    }
+
+    return mode;
+  }
+}
+
+/**
+ * Executes system unzip (e.g., `/usr/bin/unzip`). If available, it is
+ * significantly faster than the JS implementation.
+ * By default all files in the destDir get overridden if already exist.
+ *
+ * @param zipFilePath The full path to the source ZIP file
+ * @param destDir The full path to the destination folder.
+ * This folder is expected to already exist before extracting the archive.
+ */
+async function extractWithSystemUnzip(zipFilePath: string, destDir: string): Promise<void> {
+  const isWindowsHost = isWindows();
+  let executablePath: string;
+  try {
+    executablePath = await getExecutablePath(isWindowsHost ? 'powershell.exe' : 'unzip');
+  } catch {
+    throw new Error('Could not find system unzip');
+  }
+
+  if (isWindowsHost) {
+    // on Windows we use PowerShell to unzip files
+    await exec(executablePath, [
+      '-command',
+      'Expand-Archive',
+      '-LiteralPath',
+      zipFilePath,
+      '-DestinationPath',
+      destDir,
+      '-Force',
+    ]);
+  } else {
+    // -q means quiet (no stdout)
+    // -o means overwrite
+    // -d is the dest dir
+    await exec(executablePath, ['-q', '-o', zipFilePath, '-d', destDir]);
+  }
+}
+
 /**
  * Finds and memoizes the full path to the given executable.
  * Rejects if it is not found.
  */
 const getExecutablePath = _.memoize(
   /**
-   * @returns {Promise<string>} Full Path to the executable
+   * @returns Full Path to the executable
    */
-  async function getExecutablePath(binaryName) {
+  async function getExecutablePath(binaryName: string): Promise<string> {
     const fullPath = await fs.which(binaryName);
     log.debug(`Found '${binaryName}' at '${fullPath}'`);
     return fullPath;
   }
 );
 
-export {extractAllTo, readEntries, toInMemoryZip, _extractEntryTo, assertValidZip, toArchive};
 export default {
   extractAllTo,
   readEntries,
@@ -552,3 +596,4 @@ export default {
   assertValidZip,
   toArchive,
 };
+