ember-artisans
Artisans is a tool that makes using web workers in your application a lot more accessible. It offers an easy to use, Promise based API, that lets you break up your business logic to run on other threads, so that client side logic doesn't bog down your application's user experience.
Here's an example of how it might look in your application!
// app/controllers/application.js;; worker = ; @action async { const result = await thisworker; // ... }
// workers/foo.js { return `foo`; }
That's it! In the above example we're instantiating a worker using the createWorker
utility. This returns a proxied Web Worker, that allows for any method you invoke will be delegated to it's corresponding worker.
Migration Guide (1.x -> 2.x)
Starting from version 2, the interface has changed so that the result will no longer have to be unwrapped from the worker response.
Before 🕸
worker = ; @action async { const result = await thisworker; // ... }
After ✨
worker = ; @action async { const result = await thisworker; }
This also means if that the worker will no longer silently fail if an exception is thrown. Be sure to properly handle errors if they are present!
Getting Started
Installation 🎉
The first step is installing ember-artisans
. This will provide you with the templates for generating your workers, as well as the necessary build steps along the way.
yarn add -D ember-artisans
Creating workers 🛠
Once this has completed, you'll be able to start writing your workers! Running ember g artisan <name>
will create your web worker for you in the root of your project inside <root>/workers
All changes made to the files in this directory will be automatically picked up by the live reload server, and updated inside your app!
Here's some example input, and the corresponding output:
ember g artisan foo-bar
/** * Add your worker description here. */ // Add your worker methods here. /** * @returns Promise<void> */ async { }
API 👩💻
There are a couple ways to pull the worker in, and make use of them. I'll walk over each of the available methods of interacting with your workers.
createWorker
; Proxy<Worker>
Specifying a worker path is done by providing the url that the workers are built at. By default - workers are place inside of dist/assets/workers/<name>.js
This means that you would consume them by referencing their public location.
const 🐹 =
createWorkerPool
;
createWorkerPool
will work the same as createWorker
, except that when a method is invoked on a worker pool, it will instead look for the first non-busy worker to delegate your task to.
Using it would look something like this:
// app/controllers/foo.js; const taskPool = ;await taskPool;...
// workers/worker-pool.js async { return await ; }
service('artisans')
This addon also provides a service that lets you instantiate a worker pool to be shared across different parts of your application.
// app/controllers/foo.js; ;; @ artisanService; @ poolTask;
Handling Responses
Methods on your Worker will return as such, on successful completion.
; const tomsterWorker = ; const result // optional, present if the worker ran successfully! error // optional, present if there was an error encountered by the worker, or in the event of a timeout id // identifier corresponding to the request instance, used internally to map postMessage to responses} = await tomsterWorker;
Notes 📓
Worker Syntax
Currently worker's can be specified as the default export (ESM), or as the module.export (CJS). That means that each of the following is an acceptable way of declaring your workers.
// esm async { const response = await ; return ; } ...
// cjsmoduleexports = async { const response = await ; return ; }
ESM Imports in Workers ✨
You're able to import any of your node_modules/ into your worker, as long as they're able to run in browser context!
Here's a sample worker using the uuid package on npm.
; { return ; }
Naming Worker Methods
To preserve the native methods present on a worker, avoid naming your Artisan worker methods the same as the native Worker methods.
My Worker Isn't Being Detected 🕵️♂️
If you create a new worker after the development server is already running, you might need to restart it for the worker to be properly be built into the public assets directory.