For Issue #44, introduce a @typedef for UnarchiverOptions

archive/decompress-internal.js

@@ -17,6 +17,12 @@ import { findMimeType } from '../file/sniffer.js';
  * @property {Uint8Array} fileData
  */
 
+/**
+ * @typedef DecompressorOptions
+ * @property {string} pathToBitJS The path to the bitjs folder.
+ * @property {boolean=} debug Set to true for verbose decompressor logging.
+ */
+
 /**
  * The UnarchiveEvent types.
  */
@@ -188,18 +194,16 @@ export class UnarchiveExtractEvent extends UnarchiveEvent {
    *     to the decompress implementation.
    * @param {Function(string, MessagePort):Promise<*>} connectPortFn A function that takes a path
    *     to a JS decompression implementation (unzip.js) and connects it to a MessagePort.
-   * @param {Object|string} options An optional object of options, or a string representing where
-   *     the BitJS files are located.  The string version of this argument is deprecated.
-   *     Available options:
-   *       'pathToBitJS': A string indicating where the BitJS files are located.
-   *       'debug': A boolean where true indicates that the archivers should log debug output.
+   * @param {DecompressorOptions|string} options An optional object of options, or a string
+   *     representing where the BitJS files are located.  The string version of this argument is
+   *     deprecated.
    */
   constructor(arrayBuffer, connectPortFn, options = {}) {
     super();
 
     if (typeof options === 'string') {
       console.warn(`Deprecated: Don't send a raw string to Unarchiver()`);
-      console.warn(`            send {'pathToBitJS':'${options}'} instead`);
+      console.warn(`            send DecompressorOptions instead.`);
       options = { 'pathToBitJS': options };
     }
 

archive/decompress.js

@@ -38,6 +38,10 @@ export {
  * @property {Uint8Array} fileData
  */
 
+/**
+ * @typedef {import('./decompress-internal.js').DecompressorOptions} DecompressorOptions
+ */
+
 /**
  * Creates a WebWorker with the given decompressor implementation (i.e. unzip.js)
  * and transfers a MessagePort for communication. Returns a Promise to the Worker.
@@ -78,9 +82,10 @@ export class Untarrer extends UntarrerInternal {
 * in the ArrayBuffer.
 * @param {ArrayBuffer} ab The ArrayBuffer to unarchive. Note that this ArrayBuffer
 *     must not be referenced after calling this method, as the ArrayBuffer may be
-*     tranferred to a different JS context once start() is called.
-* @param {Object|string} options An optional object of options, or a string
-*     representing where the path to the unarchiver script files.
+*     transferred to a different JS context once start() is called.
+* @param {DecompressorOptions|string} options An optional object of options, or a
+*     string representing where the path to the unarchiver script files. The latter
+*     is now deprecated (use DecompressorOptions).
 * @returns {Unarchiver}
 */
 export function getUnarchiver(ab, options = {}) {

types/archive/decompress-internal.d.ts

@@ -2,12 +2,12 @@
  * Factory method that creates an unarchiver based on the byte signature found
  * in the arrayBuffer.
  * @param {ArrayBuffer} ab
- * @param {Function(string):Worker} createWorkerFn A function that creates a Worker from a script file.
+ * @param {Function(string):Promise<*>} connectPortFn A function that connects the impl port.
  * @param {Object|string} options An optional object of options, or a string representing where
  *     the path to the unarchiver script files.
  * @returns {Unarchiver}
  */
-export function getUnarchiverInternal(ab: ArrayBuffer, createWorkerFn: any, options?: any | string): Unarchiver;
+export function getUnarchiverInternal(ab: ArrayBuffer, connectPortFn: any, options?: any | string): Unarchiver;
 export namespace UnarchiveEventType {
     const START: string;
     const APPEND: string;
@@ -118,27 +118,39 @@ export class Unarchiver extends EventTarget {
     /**
      * @param {ArrayBuffer} arrayBuffer The Array Buffer. Note that this ArrayBuffer must not be
      *     referenced once it is sent to the Unarchiver, since it is marked as Transferable and sent
-     *     to the Worker.
-     * @param {Function(string):Worker} createWorkerFn A function that creates a Worker from a script file.
-     * @param {Object|string} options An optional object of options, or a string representing where
-     *     the BitJS files are located.  The string version of this argument is deprecated.
-     *     Available options:
-     *       'pathToBitJS': A string indicating where the BitJS files are located.
-     *       'debug': A boolean where true indicates that the archivers should log debug output.
+     *     to the decompress implementation.
+     * @param {Function(string, MessagePort):Promise<*>} connectPortFn A function that takes a path
+     *     to a JS decompression implementation (unzip.js) and connects it to a MessagePort.
+     * @param {UnarchiverOptions|string} options An optional object of options, or a string
+     *     representing where the BitJS files are located.  The string version of this argument is
+     *     deprecated.
      */
-    constructor(arrayBuffer: ArrayBuffer, createWorkerFn: any, options?: any | string);
+    constructor(arrayBuffer: ArrayBuffer, connectPortFn: any, options?: UnarchiverOptions | string);
+    /**
+     * A handle to the decompressor implementation context.
+     * @type {Worker|*}
+     * @private
+     */
+    private implRef_;
+    /**
+     * The client-side port that sends messages to, and receives messages from the
+     * decompressor implementation.
+     * @type {MessagePort}
+     * @private
+     */
+    private port_;
     /**
      * The ArrayBuffer object.
      * @type {ArrayBuffer}
      * @protected
      */
     protected ab: ArrayBuffer;
     /**
-     * A factory method that creates a Worker that does the unarchive work.
-     * @type {Function(string): Worker}
+     * A factory method that connects a port to the decompress implementation.
+     * @type {Function(MessagePort): Promise<*>}
      * @private
      */
-    private createWorkerFn_;
+    private connectPortFn_;
     /**
      * The path to the BitJS files.
      * @type {string}
@@ -150,12 +162,6 @@ export class Unarchiver extends EventTarget {
      * @type {boolean}
      */
     debugMode_: boolean;
-    /**
-     * Private web worker initialized during start().
-     * @private
-     * @type {Worker}
-     */
-    private worker_;
     /**
      * This method must be overridden by the subclass to return the script filename.
      * @returns {string} The MIME type of the archive.
@@ -169,7 +175,7 @@ export class Unarchiver extends EventTarget {
      */
     protected getScriptFileName(): string;
     /**
-     * Create an UnarchiveEvent out of the object sent back from the Worker.
+     * Create an UnarchiveEvent out of the object sent back from the implementation.
      * @param {Object} obj
      * @returns {UnarchiveEvent}
      * @private
@@ -181,37 +187,47 @@ export class Unarchiver extends EventTarget {
      * @param {Object} obj
      * @private
      */
-    private handleWorkerEvent_;
+    private handlePortEvent_;
     /**
-     * Starts the unarchive in a separate Web Worker thread and returns immediately.
+     * Starts the unarchive by connecting the ports and sending the first ArrayBuffer.
      */
     start(): void;
     /**
-     * Adds more bytes to the unarchiver's Worker thread.
+     * Adds more bytes to the unarchiver.
      * @param {ArrayBuffer} ab The ArrayBuffer with more bytes in it. If opt_transferable is
      *     set to true, this ArrayBuffer must not be referenced after calling update(), since it
-     *     is marked as Transferable and sent to the Worker.
+     *     is marked as Transferable and sent to the implementation.
      * @param {boolean=} opt_transferable Optional boolean whether to mark this ArrayBuffer
      *     as a Tranferable object, which means it can no longer be referenced outside of
-     *     the Worker thread.
+     *     the implementation context.
      */
     update(ab: ArrayBuffer, opt_transferable?: boolean | undefined): void;
     /**
-     * Terminates the Web Worker for this Unarchiver and returns immediately.
+     * Closes the port to the decompressor implementation and terminates it.
      */
     stop(): void;
 }
 export class UnzipperInternal extends Unarchiver {
-    constructor(arrayBuffer: any, createWorkerFn: any, options: any);
+    constructor(arrayBuffer: any, connectPortFn: any, options: any);
 }
 export class UnrarrerInternal extends Unarchiver {
-    constructor(arrayBuffer: any, createWorkerFn: any, options: any);
+    constructor(arrayBuffer: any, connectPortFn: any, options: any);
 }
 export class UntarrerInternal extends Unarchiver {
-    constructor(arrayBuffer: any, createWorkerFn: any, options: any);
+    constructor(arrayBuffer: any, connectPortFn: any, options: any);
 }
 export type UnarchivedFile = {
     filename: string;
     fileData: Uint8Array;
 };
+export type UnarchiverOptions = {
+    /**
+     * The path to the bitjs folder.
+     */
+    pathToBitJS: string;
+    /**
+     * Set to true for verbose unarchiver logging.
+     */
+    debug?: boolean | undefined;
+};
 //# sourceMappingURL=decompress-internal.d.ts.map

types/archive/decompress.d.ts

@@ -1,14 +1,15 @@
 /**
 * Factory method that creates an unarchiver based on the byte signature found
-* in the arrayBuffer.
+* in the ArrayBuffer.
 * @param {ArrayBuffer} ab The ArrayBuffer to unarchive. Note that this ArrayBuffer
-*     must not be referenced after calling this method, as the ArrayBuffer is marked
-*     as Transferable and sent to a Worker thread once start() is called.
-* @param {Object|string} options An optional object of options, or a string
-*     representing where the path to the unarchiver script files.
+*     must not be referenced after calling this method, as the ArrayBuffer may be
+*     transferred to a different JS context once start() is called.
+* @param {UnarchiverOptions|string} options An optional object of options, or a
+*     string representing where the path to the unarchiver script files. The latter
+*     is now deprecated (use UnarchiverOptions).
 * @returns {Unarchiver}
 */
-export function getUnarchiver(ab: ArrayBuffer, options?: any | string): Unarchiver;
+export function getUnarchiver(ab: ArrayBuffer, options?: UnarchiverOptions | string): Unarchiver;
 export class Unzipper extends UnzipperInternal {
     constructor(ab: any, options: any);
 }
@@ -22,6 +23,7 @@ export type UnarchivedFile = {
     filename: string;
     fileData: Uint8Array;
 };
+export type UnarchiverOptions = import('./decompress-internal.js').UnarchiverOptions;
 import { Unarchiver } from "./decompress-internal.js";
 import { UnarchiveAppendEvent } from "./decompress-internal.js";
 import { UnarchiveErrorEvent } from "./decompress-internal.js";