ngx-rs-simple-worker

An injectable service framework that provides a streamlined way of dispatching web worker tasks and handling their callbacks.

Packaged for Angular ^16.2.0

How to use:

First:

• Create your Worker the angular way, with the Angular Cli
• This automatically extends your tsconfig with a tsconfig.worker.json, and creates a worker file with the necessary /// reference lib="webworker" heading
• For example, we will make a worker file called services/workerthread.worker.ts:

ng generate web-worker services/workerthread.worker.ts

Then:

• Inject the NgxSimpleWorkerService into your application
• Instantiate your worker on the dtWorker:Worker property of the NgxSimpleWorkerService, preferably in your application's root component ( app.component.ts )
• Initialize it with the 'bootstrapWebWorker' method
• Make requests to the worker wherever your NgxSimpleWorkerService is injected with the 'makeWorkerRequest' method
• Bind calback functions with the 'onWorkerReturn' : Record<string, IWorkerReturn>

//import these
import { NgxSimpleWorkerService } from 'ngx-rs-simple-worker';
import { WorkerReturn } from 'ngx-rs-simple-worker/shared';
...

constructor( _workerSvc: NgxSimpleWorkerService) {
	//set things up
	_workerSvc.dtWorker = new Worker(new URL('./services/workerthread.worker.ts', import.meta.url), { type: 'module' });
	_workerSvc.bootstrapWebWorker();
	
	//run a worker task called "TESTME"
	_workerSvc.makeWorkerRequest({data:"HELLO", directive:"TESTME"});

	//handle the response from "TESTME"
	_workerSvc.onWorkerReturn["TESTME"] = {
		ProcessReturn: (returnData: WorkerReturn) => { 
			console.log("got return from :" + returnData.directive);
			console.log("data is :" + returnData.value)
			console.log( "error is: "+ returnData.err)
		}
	};
}

And, In your Worker file,

• Instantiate a SimpleWorker instance using the workers 'self'
• Attach your worker tasks to the SharedNGWorker's 'workerDirectives' : Record<string, IWorkerDirective>

//import these
import { SimpleWorker, WorkerRequest, WorkerReturn } from 'ngx-rs-simple-worker/shared';

var WC = new SimpleWorker(self);

//your "TESTME" task function goes here!
WC.workerDirectives["TESTME"] = { ProcessRequest: (req: WorkerRequest)=>{
		let responseMessage = req.data+" NASTY";
		let retr : WorkerReturn = {directive:"TESTME", value: responseMessage, err: null }
		postMessage(retr);
	}
}

And thats it!

The data exchange intefaces look like this:

/**
 * interface WorkerReturn
 *	- directive: {string} key for the onWorkerReturn {IWorkerReturn} callback function 
 *	- vaule: object of {any} type, returned from worker thread 
 *	- error: object of {error|null} type, returned from worker thread in case of error,	to be checked upon callback return
 */
 export interface WorkerReturn {
	/**  directive: {string} key for the onWorkerReturn {IWorkerReturn} callback function */
	directive: string
	/**  vaule: object of {any} type, returned from worker thread */
	value: any
	/**  error: object of {error|null} type, returned from worker thread in case of error, to be checked upon callback return */
	err: Error | null
}

/**
 * interface IWorkerReturn
 *	- @param {function(WorkerReturn):void} ProcessReturn - function signature for onWorkerReturn callback
 */
export interface IWorkerReturn {
	ProcessReturn(returner: WorkerReturn): void
}

/**
 * interface IWorkerDirective 
 *	- @param {function(WorkerRequest):void} ProcessReturn - function signature for IWorkerDirective handler endpoint. 
 * Maps to, and executes, a handler at workerDirectives[[WorkerRequest.directive]] with the parameter arguments WorkerRequest.data
 * 	- @returns ProcessRequest has no return but must execute postMessage with a {WorkerReturn} object.
 *  I.E. postMessage({directive:"SOME_DIRECTIVE@Caller's_onWorkerReturn", value:"SOME_VALUE", err: null })
 */
 export interface IWorkerDirective {
	ProcessRequest(req: WorkerRequest): void
}


/**
 * interface WorkerRequest
 *	- @param {string} directive - lookup key for callbakc function in worker thread's workerDirectives list of {IWorkerDirective} endpoints
 *	- @param {any} data - data to be supplied by copy to {IWorkerDirective} endpoints. 
 *	Warnging, any in memory references to other data in the UI thread within this data object will be lost.
 */
export interface WorkerRequest {
	directive: string
	data: any
}