easy-web-worker 1.0.5 → 1.0.7

package/README.md

@@ -1,11 +1,12 @@
 # easy-web-worker
+
 This is a package to easily create and handle Workers, both run time and static .js workers files
 
 ## Creating a simple Web Worker
 
 Creating a new worker is as simple as
 
-```
+```TS
 const backgroundWorker = new EasyWebWorker<string, string>((easyWorker) => {
   easyWorker.onMessage((message) => {
     const { payload } = message;
@@ -17,15 +18,16 @@ const backgroundWorker = new EasyWebWorker<string, string>((easyWorker) => {
 const messsageResult = await backgroundWorker.send('hello!');
 ```
 
-### Important notes: 
+### Important notes:
 
 EasyWebWorker<IPayload, IResult> has two generic parameters... They will affect the typing of the send() and response() methods.
-* If IResult is null, the *resolve* method will not require parameters
-* If IPayload is null, the *send* method will not require parameters
 
-Take into consideration that the *workerBody* is a template to create a worker in run time, so you'll not be able to use anything outside of the Worker-Scope
+- If IResult is null, the _resolve_ method will not require parameters
+- If IPayload is null, the _send_ method will not require parameters
 
-```
+Take into consideration that the _workerBody_ is a template to create a worker in run time, so you'll not be able to use anything outside of the Worker-Scope
+
+```TS
 const message = 'Hello';
 
 await new EasyWebWorker<null, string>((easyWorker) => {
@@ -38,12 +40,14 @@ await new EasyWebWorker<null, string>((easyWorker) => {
 ```
 
 Take a look at Workers API if you don't know yet how they work: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API,
-If you need t to send data to the worker, please define IPayload while creating a worker. *new EasyWebWorker<IPayload>(*
+If you need t to send data to the worker, please define IPayload while creating a worker. _new EasyWebWorker<IPayload>(_
 You are just allowed to send information to Workers by messages, and vice versa
 
 ## IEasyWebWorkerMessage<IPayload = null, IResult = void>
-When you defined an onMessage callback in your *Worker*, this will receive all messages from the *send* method: 
-```
+
+When you defined an onMessage callback in your _Worker_, this will receive all messages from the _send_ method:
+
+```TS
 easyWorker.onMessage((message) => {
   // the *message* will be strongly typed with TS
 
@@ -59,21 +63,22 @@ easyWorker.onMessage((message) => {
 ```
 
 ## onProgress
+
 Let say you are performing some heavy process in your worker, but you still wanted to implement some kind of progress bar in the main thread... you could add an onProgress callback.
 
-```
+```TS
 await worker.send().onProgress((progress: number) => {
   // change some progress bar percentage
 }).then(doSomething);
 ```
 
-onProgress Is gonna be executed every time you call  *message.reportProgress* inside the worker... the cool part here is that the *reportProgress* is not gonna finish the main promise returned by the *send* method.
+onProgress Is gonna be executed every time you call _message.reportProgress_ inside the worker... the cool part here is that the _reportProgress_ is not gonna finish the main promise returned by the _send_ method.
 
 ## Having multiple Worker-Templates
 
-As *WorkerBody* are just templates, you could reuse them on other *Workers*, or use them as plugins for your *Workers*. Let's see:
+As _WorkerBody_ are just templates, you could reuse them on other _Workers_, or use them as plugins for your _Workers_. Let's see:
 
-```
+```TS
 const WorkerPluggin: EasyWebWorkerBody = (_easyWorker, context) => {
   context.doSomething = () => Promise.resolve('This is a plugin example');
 };
@@ -89,17 +94,18 @@ const plugginMessage = await new EasyWebWorker([WorkerPluggin, (easyWorker, cont
 
 In this way, you could avoid having to create more than once the same template for your worker.
 
-## Importing scripts into your *Workers*
+## Importing scripts into your _Workers_
 
 Web Workers has this amazing method called importScripts, are you passed an array of strings in the EeasyWorker extra configuration, all those files are gonna be imported into your worker.
 
 // test.js
-```
+
+```TS
 self.message = 'Hello coders!';
 selft.doSomething = () => console.log(self.message);
 ```
 
-```
+```TS
 await new EasyWebWorker((easyWorker, context) => {
   easyWorker.onMessage((message) => context.doSomething());
 }, {
@@ -108,22 +114,23 @@ await new EasyWebWorker((easyWorker, context) => {
 
 ```
 
-This is a very simple example, but you could import a whole library into your worker, as *JQUERY*, *Bluebird* for example
+This is a very simple example, but you could import a whole library into your worker, as _JQUERY_, _Bluebird_ for example
 
 ## StaticEasyWebWorker
 
-If you want to create a *Worker* with a static .js file and don't want to lose the structure of messages and promises and the onProgress callback from the library... you could use *StaticEasyWebWorker<IPayload = null, IResult = void>* directly in your Worker.
+If you want to create a _Worker_ with a static .js file and don't want to lose the structure of messages and promises and the onProgress callback from the library... you could use _StaticEasyWebWorker<IPayload = null, IResult = void>_ directly in your Worker.
 
-trust me, talking about performance it's going to be the same. but may if you are trying to create something very complex and huge into a *Worker*... OK, a static js file could be a good option.
+trust me, talking about performance it's going to be the same. but may if you are trying to create something very complex and huge into a _Worker_... OK, a static js file could be a good option.
 
 Workers are gonna work just as the javascript you have in your main thread, but into another thread, so, the user experience could improve!!
 
-let's see how to use it: 
+let's see how to use it:
 
 // worker.js
 // This is gonna be the content of your worker
-// onMessage Callback is gonna receive all *send* method calls.
-```
+// onMessage Callback is gonna receive all _send_ method calls.
+
+```TS
 const onMessageCallback = (message: IEasyWebWorkerMessage<null, number>) => {
   setTimeout(() => {
     message.resolve(200);
@@ -135,18 +142,19 @@ new StaticEasyWebWorker<null, number>(onMessageCallback);
 ```
 
 and in your main thread:
-```
+
+```TS
 const worker = new EasyWebWorker<null,number>('http://localhost:3000/worker.js');
 await worker.send();
 ```
 
-Super easy right? 
+Super easy right?
 
-## Want to see more? 
+## Want to see more?
 
 Here is an example of how you could easily create data filter into a Worker, to avoid performing loops process into the main thread that could end affecting user experience.
 
-```
+```TS
 interface FilterSource {
   filter: string,
   collection: any[],
@@ -195,9 +203,9 @@ const worker = new EasyWebWorker<FilterSource, any[]>((easyWorker) => {
 });
 ```
 
-And how to use this? 
+And how to use this?
 
-```
+```TS
 worker.send({
   collection: [{ name: 'julio perez' }, { name: 'carol starling' }, { name: 'goku' }, { name: { firstname: 'johnny' } }],
   filter: 'johnny',
@@ -215,4 +223,4 @@ the output should be:
 
 Of course this is a very tiny array, but is just to give you and idea, actually you also could make fetch requests into workers... give it a try.
 
-*Thanks for reading, hope this help someone*
+_Thanks for reading, hope this help someone_

package/lib/EasyWebWorker.d.ts

@@ -1,57 +1,95 @@
-import * as IEasyWebWorker from './EasyWebWorkerTypes';
+import { EasyWebWorkerBody, IWorkerConfig } from './EasyWebWorkerTypes';
+import { CancelablePromise } from 'cancelable-promise-jq';
 /**
-* This is a class to create global-store objects
-* @template IPayload - Indicates if your WORKERS messages requires a parameter to be provided, NULL indicates they doesn't
-* @template IResult - Indicates if your WORKERS messages has a result... NULL indicates all you messages are Promise<void>
-* @param {IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult> | IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult>[]} workerBody -
-* this parameter should be a function or set of functions that will become the body of your Web-Worker
-* IMPORTANT!! all WORKERS content is gonna be transpiled on run time, so you can not use any variable, method of resource that weren't included into the WORKER.
-* the above the reason of why we are injecting all worker context into the MessageBody Callbacks, so,
-* you could easily identify what is on the context of your Worker.
-* @param {Partial<IEasyWebWorker.IWorkerConfig>} WorkerConfig - You could add extra configuration to your worker,
-* consult IWorkerConfig description to have more information
-* */
-declare class EasyWebWorker<IPayload = null, IResult = void> implements IEasyWebWorker.IEasyWebWorker<IPayload, IResult> {
-    protected workerBody: IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult> | IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult>[] | string;
+ * This is a class to create global-store objects
+ * @template IPayload - Indicates if your WORKERS messages requires a parameter to be provided, NULL indicates they doesn't
+ * @template IResult - Indicates if your WORKERS messages has a result... NULL indicates all you messages are Promise<void>
+ * @param {EasyWebWorkerBody<IPayload, IResult> | EasyWebWorkerBody<IPayload, IResult>[]} workerBody -
+ * this parameter should be a function or set of functions that will become the body of your Web-Worker
+ * IMPORTANT!! all WORKERS content is gonna be transpiled on run time, so you can not use any variable, method of resource that weren't included into the WORKER.
+ * the above the reason of why we are injecting all worker context into the MessageBody Callbacks, so,
+ * you could easily identify what is on the context of your Worker.
+ * @param {Partial<IWorkerConfig>} WorkerConfig - You could add extra configuration to your worker,
+ * consult IWorkerConfig description to have more information
+ * */
+export declare class EasyWebWorker<IPayload = null, IResult = void> {
+    /**
+     * this parameter should be a function or set of functions that will become the body of your Web-Worker
+     * IMPORTANT!! all WORKERS content is gonna be transpiled on run time, so you can not use any variable, method of resource that weren't included into the WORKER.
+     * the above the reason of why we are injecting all worker context into the MessageBody Callbacks, so,
+     * you could easily identify what is on the context of your Worker.
+     */
+    protected workerBody: EasyWebWorkerBody<IPayload, IResult> | EasyWebWorkerBody<IPayload, IResult>[] | string;
     name: string;
-    private worker;
+    /**
+     * @deprecated Directly modifying the worker may lead to unexpected behavior. Use it only if you know what you are doing.
+     */
+    worker: Worker;
+    /**
+     * These where send to the worker but not yet resolved
+     */
     private messagesQueue;
+    /**
+     * This is the URL of the worker file
+     */
     workerUrl: string;
-    protected scripts: string[];
+    /**
+     * This is the list of scripts that will be imported into the worker
+     */
+    scripts: string[];
+    /**
+     * This is the callback that will be executed when the worker throws an error
+     */
+    onWorkerError: (error: ErrorEvent) => void;
     protected get isExternalWorkerFile(): boolean;
-    constructor(workerBody: IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult> | IEasyWebWorker.EasyWebWorkerBody<IPayload, IResult>[] | string, { scripts, name, }?: Partial<IEasyWebWorker.IWorkerConfig>);
+    constructor(
+    /**
+     * this parameter should be a function or set of functions that will become the body of your Web-Worker
+     * IMPORTANT!! all WORKERS content is gonna be transpiled on run time, so you can not use any variable, method of resource that weren't included into the WORKER.
+     * the above the reason of why we are injecting all worker context into the MessageBody Callbacks, so,
+     * you could easily identify what is on the context of your Worker.
+     */
+    workerBody: EasyWebWorkerBody<IPayload, IResult> | EasyWebWorkerBody<IPayload, IResult>[] | string, 
+    /**
+     * You could import scripts into your worker, this is useful if you want to use external libraries
+     */
+    { scripts, name, onWorkerError }?: Partial<IWorkerConfig>);
     private RemoveMessageFromQueue;
+    /**
+     * Categorizes the worker response and executes the corresponding callback
+     */
     private executeMessageCallback;
     protected getWorkerUrl(): string;
     protected createWorker(): Worker;
     /**
-    * Disable the resolve of all current WebWorkers messages, no any of the current messages gonna call onProgress callback, neither promise.resolve
-    */
-    cancelAll(): void;
-    /**
-    * Send a message to the worker queue
-    * @param {IPayload} payload - whatever json data you want to send to the worker
-    * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
-    */
-    send(...payload: IPayload extends null ? [null?] : [IPayload]): IEasyWebWorker.IMessagePromise<IResult>;
-    /**
-    * Web Workers works as a QUEUE, sometimes a new message actually would be the only message that you'll want to resolve...
-    * you could use OVERRIDE to that purpose.
-    * @param {IPayload} payload - whatever json data you want to send to the worker
-    * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
-    */
-    override(...payload: IPayload extends null ? [null?] : [IPayload]): IEasyWebWorker.IMessagePromise<IResult>;
-    /**
-    * Web Workers works as a QUEUE, sometimes a new message actually would be the only message that you'll want to resolve...
-    * you could use OVERRIDE to that purpose.
-    * @param {IPayload} payload - whatever json data you want to send to the worker
-    * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
-    */
-    overrideAfterCurrent(...payload: IPayload extends null ? [null?] : [IPayload]): IEasyWebWorker.IMessagePromise<IResult>;
-    /**
-    * This method will remove the WebWorker and the BlobUrl
-    */
+     * Terminates the worker and remove all messages from the queue
+     * Execute the cancel callback of each message in the queue if provided
+     * @param {unknown} reason - reason why the worker was terminated
+     */
+    cancelAll(reason?: unknown): void;
+    /**
+     * Send a message to the worker queue
+     * @param {IPayload} payload - whatever json data you want to send to the worker
+     * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
+     */
+    send: IPayload extends null ? () => CancelablePromise<IResult> : (payload: IPayload) => CancelablePromise<IResult>;
+    /**
+     * This method terminate all current messages and send a new one to the worker queue
+     * @param {IPayload} payload - whatever json data you want to send to the worker, should be serializable
+     * @param {unknown} reason - reason why the worker was terminated
+     * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
+     */
+    override: IPayload extends null ? (reason?: unknown) => CancelablePromise<IResult> : (payload: IPayload, reason?: unknown) => CancelablePromise<IResult>;
+    /**
+     * This method will alow the current message to be completed and send a new one to the worker queue after it, all the messages after the current one will be canceled
+     * @param {IPayload} payload - whatever json data you want to send to the worker should be serializable
+     * @param {unknown} reason - reason why the worker was terminated
+     * @returns {IMessagePromise<IResult>} generated defer that will be resolved when the message completed
+     */
+    overrideAfterCurrent: IPayload extends null ? (reason?: unknown) => CancelablePromise<IResult> : (payload: IPayload, reason?: unknown) => CancelablePromise<IResult>;
+    /**
+     * This method will remove the WebWorker and the BlobUrl
+     */
     dispose(): void;
 }
 export default EasyWebWorker;
-//# sourceMappingURL=EasyWebWorker.d.ts.map

package/lib/EasyWebWorker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EasyWebWorker.d.ts","sourceRoot":"","sources":["../src/EasyWebWorker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,sBAAsB,CAAC;AAKvD;;;;;;;;;;;IAWI;AACJ,cAAM,aAAa,CAAE,QAAQ,GAAG,IAAI,EAAE,OAAO,GAAG,IAAI,CAAE,YAAW,cAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC;IAiB3G,SAAS,CAAC,UAAU,EAAE,cAAc,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM;IAfrI,IAAI,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,MAAM,CAAgB;IAE9B,OAAO,CAAC,aAAa,CAAiD;IAE/D,SAAS,EAAE,MAAM,CAAM;IAE9B,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAM;IAEjC,SAAS,KAAK,oBAAoB,IAAK,OAAO,CAE7C;gBAGW,UAAU,EAAE,cAAc,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,EAC1I,EACE,OAAY,EACZ,IAAI,GACL,GAAE,OAAO,CAAC,cAAc,CAAC,aAAa,CAAM;IAO/C,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,sBAAsB;IAmC9B,SAAS,CAAC,YAAY,IAAI,MAAM;IAShC,SAAS,CAAC,YAAY,IAAI,MAAM;IAahC;;MAEE;IACK,SAAS,IAAI,IAAI;IAKxB;;;;MAIE;IACK,IAAI,CAAC,GAAG,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC;IAqB9G;;;;;MAKE;IACK,QAAQ,CAAC,GAAG,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC;IAKlH;;;;;MAKE;IACK,oBAAoB,CAAC,GAAG,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC;IAY9H;;MAEE;IACK,OAAO,IAAI,IAAI;CAOzB;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"EasyWebWorker.d.ts","sourceRoot":"","sources":["../src/EasyWebWorker.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,iBAAiB,EAEjB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;KAWK;AAEL,qBAAa,aAAa,CAAC,QAAQ,GAAG,IAAI,EAAE,OAAO,GAAG,IAAI;IAkCtD;;;;;OAKG;IACH,SAAS,CAAC,UAAU,EAChB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACpC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,GACtC,MAAM;IA1CL,IAAI,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACI,MAAM,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,aAAa,CACT;IAEZ;;OAEG;IACI,SAAS,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACI,OAAO,EAAE,MAAM,EAAE,CAAM;IAE9B;;OAEG;IACI,aAAa,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAElD,SAAS,KAAK,oBAAoB,IAAI,OAAO,CAE5C;;IAGC;;;;;OAKG;IACO,UAAU,EAChB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACpC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,GACtC,MAAM;IAEV;;OAEG;IACH,EAAE,OAAY,EAAE,IAAI,EAAE,aAAoB,EAAE,GAAE,OAAO,CAAC,aAAa,CAAM;IAQ3E,OAAO,CAAC,sBAAsB;IAI9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkD9B,SAAS,CAAC,YAAY,IAAI,MAAM;IAahC,SAAS,CAAC,YAAY,IAAI,MAAM;IAuBhC;;;;OAIG;IACI,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAUxC;;;;OAIG;IACI,IAAI,gCAeD,kBAAkB,OAAO,CAAC,aACtB,QAAQ,KAAK,kBAAkB,OAAO,CAAC,CAAC;IAEtD;;;;;OAKG;IACI,QAAQ,oCASD,OAAO,KAAK,kBAAkB,OAAO,CAAC,aACtC,QAAQ,WAAW,OAAO,KAAK,kBAAkB,OAAO,CAAC,CAAC;IAExE;;;;;OAKG;IACI,oBAAoB,oCAkBb,OAAO,KAAK,kBAAkB,OAAO,CAAC,aACtC,QAAQ,WAAW,OAAO,KAAK,kBAAkB,OAAO,CAAC,CAAC;IAExE;;OAEG;IACI,OAAO,IAAI,IAAI;CAOvB;AAED,eAAe,aAAa,CAAC"}