{"id":20886061,"url":"https://github.com/srowhani/ember-artisans","last_synced_at":"2025-05-12T19:32:00.469Z","repository":{"id":39838666,"uuid":"159077246","full_name":"srowhani/ember-artisans","owner":"srowhani","description":"An abstraction layer around using web-workers in Ember.js","archived":false,"fork":false,"pushed_at":"2022-12-10T01:46:19.000Z","size":2727,"stargazers_count":25,"open_issues_count":23,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-16T03:08:06.902Z","etag":null,"topics":["ember","typescript","web-worker"],"latest_commit_sha":null,"homepage":"https://srowhani.github.io/ember-artisans","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srowhani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-25T21:40:06.000Z","updated_at":"2024-08-30T00:08:16.000Z","dependencies_parsed_at":"2023-01-26T01:32:35.230Z","dependency_job_id":null,"html_url":"https://github.com/srowhani/ember-artisans","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srowhani%2Fember-artisans","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srowhani%2Fember-artisans/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srowhani%2Fember-artisans/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srowhani%2Fember-artisans/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srowhani","download_url":"https://codeload.github.com/srowhani/ember-artisans/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253808280,"owners_count":21967521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ember","typescript","web-worker"],"created_at":"2024-11-18T08:15:38.707Z","updated_at":"2025-05-12T19:31:59.964Z","avatar_url":"https://github.com/srowhani.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# \u003cimg src='https://raw.githubusercontent.com/srowhani/files/master/leader.png' width=100 height=100/\u003e ember-artisans \n\n[![NPM Version](https://badge.fury.io/js/ember-artisans.svg?style=flat)](https://npmjs.org/package/ember-artisans)\n[![Build Status](https://travis-ci.org/srowhani/ember-artisans.svg?branch=master)](https://travis-ci.org/srowhani/ember-artisans/)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\nArtisans 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.\n\nHere's an example of how it might look in your application!\n\n```js\n// app/controllers/application.js\nimport Controller from '@ember/controller'\nimport { action } from '@ember/object';\nimport { createWorker } from 'ember-artisans';\n\nexport default class ApplicationController extends Controller {\n  worker = createWorker('/assets/workers/foo.js');\n\n  @action\n  async onFooBar() {\n    const result = await this.worker.foo('bar');\n    // ...\n  }\n}\n```\n\n```js\n// workers/foo.js\nexport default class FooBarWorker {\n  foo (bar) {\n    return `foo${bar}`;\n  }\n}\n```\n\nThat's it! In the above example we're instantiating a worker using the `createWorker` utility. This returns a proxied [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker), that allows for any method you invoke will be delegated to it's corresponding worker.\n\n\n## Migration Guide (1.x -\u003e 2.x)\n\nStarting from version 2, the interface has changed so that the result will no longer have to be unwrapped from the worker response.\n\n### Before 🕸\n```js\nexport default class ApplicationController extends Controller {\n  worker = createWorker('/assets/workers/foo.js');\n\n  @action\n  async onFooBar() {\n    const { result }  = await this.worker.foo('bar');\n    // ...\n  }\n}\n```\n\n\n### After ✨\n\n```js\nexport default class ApplicationController extends Controller {\n  worker = createWorker('/assets/workers/foo.js');\n\n  @action\n  async onFooBar() {\n    const result = await this.worker.foo('bar');\n  }\n}\n```\n\nThis 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!\n\n## Getting Started \n\n### Installation 🎉\nThe 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.\n\n```sh\nyarn add -D ember-artisans\n```\n\n### Creating workers 🛠\n\nOnce this has completed, you'll be able to start writing your workers! Running `ember g artisan \u003cname\u003e` will create your web worker for you in the root of your project inside `\u003croot\u003e/workers`\nAll changes made to the files in this directory will be automatically picked up by the live reload server, and updated inside your app!\n\nHere's some example input, and the corresponding output:\n\n`ember g artisan foo-bar`\n\n```js\n/**\n * Add your worker description here.\n */\nexport default class FooBarWorker {\n  // Add your worker methods here.\n\n  /**\n   * @returns Promise\u003cvoid\u003e\n   */\n  async fooBar() {\n    \n  }\n}\n```\n\n## API 👩‍💻\n\nThere 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.\n\n### `createWorker`\n\n```js\nimport { createWorker } from 'ember-artisans';\n\ncreateWorker(\n  workerPath: string,\n  options = {\n    timeout: 5000,\n  },\n) =\u003e Proxy\u003cWorker\u003e\n```\n\nSpecifying 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/\u003cname\u003e.js` This means that you would consume them by referencing their public location.\n\n```js\nconst 🐹 = createWorker('/assets/workers/tomster.js')\n```\n\n### `createWorkerPool`\n\n```js\n\nimport { createWorkerPool } from 'ember-artisans';\n\nexport function createWorkerPool(\n  workerPath: string,\n  poolSize: number,\n)\n```\n\n`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.\n\nUsing it would look something like this:\n\n```js\n// app/controllers/foo.js\nimport { createWorkerPool } from 'ember-artisans';\n\nconst taskPool = createWorkerPool('/assets/workers/task-pool.js', 5);\nawait taskPool.doSomething();\n...\n```\n\n```js\n// workers/worker-pool.js\nexport default class TaskPoolWorker {\n  async doSomething () {\n    return await something();\n  }\n}\n```\n\n### `service('artisans')`\n\nThis addon also provides a service that lets you instantiate a worker pool to be shared across different parts\nof your application.\n\n```js\n// app/controllers/foo.js\nimport Controller from '@ember/controller';\n\nimport { inject as service } from '@ember/service';\nimport { task } from 'ember-concurrency';\n\nexport default class FooController extends Controller {\n  @service('artisans')\n  artisanService;\n\n  @(task(function* () {\n    const workerPool = this.artisanService.poolFor('/assets/workers/pool.js', 2);\n    return workerPool.doSomething();\n  }))\n  poolTask;\n}\n```\n\n## Handling Responses\n\nMethods on your Worker will return as such, on successful completion.\n\n```js\nimport { createWorker } from 'ember-artisans';\n\nconst tomsterWorker = createWorker('/assets/workers/tomster.js');\n\nconst {\n  result, // optional, present if the worker ran successfully!\n  error, // optional, present if there was an error encountered by the worker, or in the event of a timeout\n  id,   // identifier corresponding to the request instance, used internally to map postMessage to responses\n} = await tomsterWorker.runOnWheel();\n```\n\n## Notes 📓\n\n### Worker Syntax\n\nCurrently 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.\n\n```js\n// esm\nexport default class FoobarWorker {\n  async foo() {\n    const response = await bar();\n    return baz(response);\n  }\n  ...\n}\n```\n\n```js\n// cjs\nmodule.exports = {\n  async foo() {\n    const response = await bar();\n    return baz(response);\n  }\n}\n```\n\n### ESM Imports in Workers ✨\n\nYou're able to import any of your node_modules/ into your worker, as long as they're able to run in browser context!\n\nHere's a sample worker using the [uuid](https://www.npmjs.com/package/uuid) package on npm.\n\n```js\nimport { v4 as uuidV4 } from 'uuid';\n\nexport default class UUIDWorker {\n  generateUuid() {\n    return uuidV4();\n  }\n}\n```\n\n### Naming Worker Methods\n\nTo preserve the native methods present on a worker, avoid naming your Artisan worker methods the same as the native [Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) methods.\n\n### My Worker Isn't Being Detected 🕵️‍♂️\n\nIf 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrowhani%2Fember-artisans","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrowhani%2Fember-artisans","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrowhani%2Fember-artisans/lists"}