{"ava":{"files":["./test/*.test.ts"],"require":["ts-node/register"],"extensions":["ts"],"compileEnhancements":false},"bugs":{"url":"https://github.com/andywer/threads/issues"},"dist":{"shasum":"16d568a671b8d75f0ef38f3579167ce31ef12d67","tarball":"https://registry.npmjs.org/threads/-/threads-1.0.0-alpha.tgz","fileCount":45,"integrity":"sha512-nyC+oLC3LctnPNqpDC9BZctOnt1X6+LzZnS1+W0jwt6OCgHR7cZkM4YM1i64wuoYu0gMeQ4wGYYQTylYEwzO0w==","signatures":[{"sig":"MEYCIQCiCbp+ED4+WLgrfH6xQT8eSRvuzeG/pGHxF7nApeJwiAIhAJIucGOiyk6IAde/uRHpx/bOtKmAbSY3iYP+rp14MWd5","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":53869,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc1bfUCRA9TVsSAnZWagAAeO4P/2Cu4hD1oPAzZ3fz4AD/\nQZ5tLmcqAhb/6W5nkSfC2zpxZOzbrQrsjC9LkbJ8HPq/+YC1V/pXVlMRNArx\n7UUdFcbM36Z9WbN2smAqXU0YjBchIwxuuv0+h36+pBfrWD6CAWhi3stHJHXY\nXaUQ296qCMgkUMBWFLY9Euxg8N++rxlZAH4l3fNxumYjljsAGBXGB5vCEr35\nfDOTgrl9Q0v0KErdMHFFDv0khbnSM4CitVaTjfPWLv22U19L5Gx46YGMzz8e\ng08F2fiWRug/I2pKGKLbBbe16UkjwsAp/b/8WXCr3v/Y1/xy/PnDSOW6DT3U\nZ6bp8W9GNPpsg+mxiSNgur8pV+3krqsFRYmjdhxH8zo5oRted/iCy9wDcUE+\nVe5WPZj6vwd2oMnVNtX47YzuQyDmEDSWEKunHTkqvKoJYASdzui8KvvMkMnj\nGfVtnytuX2vuiOOrOipj2aZl2SL3xv60aQMDK2a6uCsLWcBDW585KuYsHjJJ\nRdCTjdFet/e5nq+LRpBAUEma32uXysQOanH5TaNt9Cd2UY4BoiA/juJBVhSK\n6ltnI4iHt6QDMih1cl4ybSOV0g/cZygFz2H9wCe03hdRyfhz+EaexErsMwpb\n07d2dqDP6h2rphubDWGZN82UKK+zUWzO2Jl76AaIcEnLsNoru5S8X+T5OOlA\nUhmz\r\n=CSyw\r\n-----END PGP SIGNATURE-----\r\n"},"main":"dist/index.js","name":"threads","author":{"url":"https://github.com/andywer","name":"Andy Wermke"},"readme":"

threads

\n\nVersion 1.0 - Work in progress 🛠\n\nComplete rewrite of the library with a new robust API, all functional, and all statically typed. It's still fully isomorphic – run the same code in the browser, in node.js or an electron app!\n\nDevelopment progress is tracked in 👉 [#100](https://github.com/andywer/threads.js/issues/100). Feel free to leave feedback there!\n\n## Installation\n\nNot yet published to npm.\n\n## Compatibility\n\n#### Platform: Web (browsers)\n\nUses [web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).\n\n#### Platform: Node.js 12+\n\nUses native [worker threads](https://nodejs.org/api/worker_threads.html).\n\n#### Platform: Node.js < 12\n\nUses [`tiny-worker`](https://github.com/avoidwork/tiny-worker) as fallback if native worker threads are not available.\n\n## New Paradigm\n\nWe dropped inline functions support and instead focus on worker code residing in their own files.\nRunning inlined functions in a worker was nice for concise code samples, but offered limited value in real-world applications. Those inlined functions also had some built-in limitations that could not be overcome and that frequently got users confused.\n\nFocussing on worker code in distinct source modules also means we are focussing on using `threads` with bundlers like Webpack or Parcel in the front-end. In a node.js context you should be able to use a bundler as well, but you probably won't need to.\n\nThese changes also mean that we shall have worker code with `import`/`require()` that works in node.js just as well as bundled in browsers.\n\n## Usage\n\n### Concept\n\n```js\n// master.js\nimport { spawn, Thread, Worker } from \"threads\"\n\nconst add = await spawn(new Worker(\"./workers/add\"))\nconst sum = await add(2, 3)\n\nconsole.log(`2 + 3 = ${sum}`)\n\nawait Thread.terminate(sum)\n```\n\n```js\n// workers/add.js\nimport { expose } from \"threads/worker\"\n\nexpose(function add(a, b) {\n return a + b\n})\n```\n\n#### spawn()\n\nThe return value of `add()` in the master code depends on the `add()` return value in the worker:\nIf the function returns a promise or an observable then you can just use the return value as such in the master code. If the function returns a primitive value, expect the master function to return a promise resolving to that value.\n\n#### expose()\n\nYou can `expose()` either a function or an object. In case of exposing an object, `spawn()` will asynchronously return an object exposing all the object's functions, following the same rules as functions directly `expose()`-ed.\n\n### Code Samples\n\n
\nBasics - Function thread\n\n```js\n// master.js\nimport { spawn, Thread, Worker } from \"threads\"\n\nconst fetchGithubProfile = await spawn(new Worker(\"./workers/fetch-github-profile\"))\nconst andywer = await fetchGithubProfile(\"andywer\")\n\nconsole.log(`User \"andywer\" has signed up on ${new Date(andywer.created_at).toLocaleString()}`)\n\nawait Thread.terminate(fetchGithubProfile)\n```\n\n```js\n// workers/fetch-github-profile.js\nimport fetch from \"isomorphic-fetch\"\nimport { expose } from \"threads/worker\"\n\nexpose(async function fetchGithubProfile(username) {\n const response = await fetch(`https://api.github.com/users/${username}`)\n return response.json()\n})\n```\n
\n\n
\nBasics - Module thread\n\n```js\n// master.js\nimport { spawn, Thread, Worker } from \"threads\"\n\nconst counter = await spawn(new Worker(\"./workers/counter\"))\nawait counter.increment()\nawait counter.increment()\nawait counter.decrement()\n\nconsole.log(`Counter is now at ${await counter.getCount()}`)\n\nawait Thread.terminate(counter)\n```\n\n```js\n// workers/counter.js\nimport { expose } from \"threads/worker\"\n\nlet currentCount = 0\n\nconst counter = {\n getCount() {\n return currentCount\n },\n increment() {\n return ++currentCount\n },\n decrement() {\n return --currentCount\n }\n}\n\nexpose(counter)\n```\n
\n\n
\nTODO: Basics - Returning observables\n\nJust return an observable in your worker, subscribe to it in the master code. Fully transparent.\n
\n\n
\nTODO: Basics - Error handling\n\nFully transparent. The promise in the master code's call will be rejected with the error thrown in the worker, also yielding the worker error's stack trace.\n
\n\n
\nTODO: Cancelling a thread job\n
\n\n
\nTODO: Thread pool & Task queue\n
\n\n
\nTransferable objects\nUse `Transfer()` to mark [`transferable objects`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#Passing_data_by_transferring_ownership_(transferable_objects)) like ArrayBuffers to be transferred to the receiving thread. It can speed up your code a lot if you are working with big chunks of binary data.\n\n`Transfer()` comes in two flavors:\n* `Transfer(myBuffer: Transferable)`\n* `Transfer(someObjectOrArrayContainingMyBuffers: any, [myBuffer, /* ... */]: Transferable[])`\n\nUse it when calling a thread function or returning from a thread function:\n\n```js\n// master.js\nimport { spawn, Transfer, Worker } from \"threads\"\n\nconst xorBuffer = await spawn(new Worker(\"./workers/arraybuffer-xor\"))\nconst resultBuffer = await xorBuffer(Transfer(testData), 127)\n```\n\n```js\n// workers/arraybuffer-xor.js\nimport { expose, Transfer } from \"threads/worker\"\n\nexpose(function xorBuffer(username) {\n const view = new Uint8Array(buffer)\n view.forEach((byte, offset) => view.set([byte ^ value], offset))\n return Transfer(buffer)\n})\n```\n\nWithout `Transfer()` the buffers would be copied on every call and every return. Using `Transfer()` only their ownership is transferred to the other thread instead to make sure it is accessible in a thread-safe way. This is a much faster operation.\n
\n\n
\nTODO: Subscribe to thread debugging events\n
\n\n
\nTests\n\nCheck out the [integration tests](./test) and [their workers](./test/workers) to see it in action.\n
\n\n### Usage with node.js\n\nWorks out of the box. Note that we wrap the native `Worker`, so `new Worker(\"./foo/bar\")` will resolve the path relative to the module that calls it, not relative to the current working directory.\n\nThat aligns it with the behavior when bundling the code with webpack or parcel.\n\n### Usage with Webpack\n\nUse with the [`worker-plugin`](https://github.com/GoogleChromeLabs/worker-plugin), so all `new Worker(\"./unbundled-path\")` expressions are detected and properly transformed transparently, so you don't need to explicitly use the `worker-loader` or define extra entry points.\n\nTODO\n\n### Usage with Parcel\n\nShould work out of the box without any extra plugins.\n\nTODO\n\n## API\n\nTODO\n\n## Debug\n\nWe are using the [`debug`](https://github.com/visionmedia/debug) package to provide opt-in debug logging. All the package's debug messages have a scope starting with `threads:`, with different sub-scopes.\n\nSet it to `DEBUG=threads:*` to enable all the library's debug logging. To run its tests with full debug logging, for instance:\n\n```\nDEBUG=threads:* npm test\n```\n\n## License\n\nMIT\n","browser":{"./dist/master/implementation":"./dist/master/implementation.browser.js","./dist/worker/implementation":"./dist/worker/implementation.browser.js","./dist/master/implementation.node.js":false,"./dist/worker/implementation.tiny-worker.js":false,"./dist/worker/implementation.worker_threads.js":false},"gitHead":"67e18291a1dea00a122c1e7d2ff1d5a066459fcb","license":"MIT","scripts":{"test":"TS_NODE_FILES=true ava","build":"tsc","prepare":"run-s build","pretest":"babel --plugins @babel/plugin-transform-typescript --plugins @babel/plugin-transform-modules-commonjs ./test/workers -d ./test/workers -x .ts","posttest":"tslint --project .","prebuild":"rimraf dist/"},"_npmUser":{"name":"andywer","email":"andy.dev@next-step-software.com"},"homepage":"https://github.com/andywer/threads#readme","keywords":["thread","web worker","pool","spawn","isomorphic","parallel","observable"],"repository":{"url":"git+https://github.com/andywer/threads.git","type":"git"},"_npmVersion":"6.9.0","description":"Easy to use, yet powerful multi-threading library for node.js and the browser!","directories":{},"maintainers":[{"name":"andywer","email":"andy@dev.next-step-software.com"}],"_nodeVersion":"12.0.0","dependencies":{"debug":"^4.1.1","callsites":"^3.1.0","is-observable":"^1.1.0","zen-observable":"^0.8.14","@types/zen-observable":"^0.8.0"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"ava":"^1.4.1","rimraf":"^2.6.3","tslint":"^5.16.0","ts-node":"^8.1.0","@babel/cli":"^7.4.4","typescript":"^3.4.5","@types/node":"^11.13.8","npm-run-all":"^4.1.5","tiny-worker":"^2.2.0","@types/debug":"^4.1.4","@types/callsites":"^3.0.0","tslint-config-prettier":"^1.18.0","@babel/plugin-transform-typescript":"^7.4.4","@babel/plugin-transform-modules-commonjs":"^7.4.4"},"optionalDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/threads_1.0.0-alpha_1557510099997_0.9321875242757587","host":"s3://npm-registry-packages"},"_id":"threads@1.0.0-alpha","version":"1.0.0-alpha"}