# promise-worker-transferable

> Communicate with a Web Worker using Promises, allowing transferList

Latest version **1.0.4** (published 2016-09-23) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install promise-worker-transferable
pnpm add promise-worker-transferable
yarn add promise-worker-transferable
bun add promise-worker-transferable
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2016-09-23 |
| First published | 2016-09-22 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Roman Viskin |
| Maintainers | terikon |
| Keywords | web worker, promise, webworker, worker |

## Links

- npm: https://www.npmjs.com/package/promise-worker-transferable
- Repository: https://github.com/terikon/promise-worker-transferable
- Homepage: https://github.com/terikon/promise-worker-transferable#readme
- Issues: https://github.com/terikon/promise-worker-transferable/issues
- npm.io page: https://npm.io/package/promise-worker-transferable

## Dependencies (2)

- [lie](https://npm.io/package/lie.md) ^3.0.2
- [is-promise](https://npm.io/package/is-promise.md) ^2.1.0

## Alternatives

- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads

## Recent versions

- 1.0.4 (latest) — 2016-09-23
- 1.0.3 — 2016-09-23
- 1.0.2 — 2016-09-22

## README

promise-worker-transferable [![Build Status](https://travis-ci.org/terikon/promise-worker-transferable.svg?branch=master)](https://travis-ci.org/terikon/promise-worker-transferable)
====

Modified version of [promise-worker](https://github.com/nolanlawson/promise-worker) library that supports object transferring. Possibly works slower than original for not transferable messages.

As mentioned [here](https://github.com/nolanlawson/promise-worker/issues/13), promise-worker library will not get support for blobs and transferables. So here promise-worker-transferable goes.

**Goals:**

 * Tiny footprint (~2.5kB min+gz)
 * Assumes you have a separate `worker.js` file (easier to debug, better browser support)
 * Removed from promise-worker and no longer true: `JSON.stringify`s messages [for performance](http://nolanlawson.com/2016/02/29/high-performance-web-worker-messages/)
 * Instead, it's now possbile to transfer blobs, as well as attach transferList array to transfer objects, which works much faster for larger objects. 

**Live examples:**

* [Web Workers](https://bl.ocks.org/nolanlawson/05e74a8408a099635c9a38f839b5ae9f)
* [Service Workers](https://bl.ocks.org/nolanlawson/91a7f5809f2e17a2e6a753a3cb8d2eec)

Usage
---

Install:

    npm install promise-worker-transferable

Inside your main bundle:

```js
// main.js
var PromiseWorker = require('promise-worker-transferable');
var worker = new Worker('worker.js');
var promiseWorker = new PromiseWorker(worker);

promiseWorker.postMessage('ping').then(function (response) {
  // handle response
}).catch(function (error) {
  // handle error
});

// With transferList
promiseWorker.postMessage(pingImageData, [pingImageData.data.buffer]) // pongImageData transferred from main to worker
.then(function (response) {
  // handle response
}).catch(function (error) {
  // handle error
});
```

Inside your `worker.js` bundle:

```js
// worker.js
var registerPromiseWorker = require('promise-worker-transferable/register');

registerPromiseWorker(function (message) {
  return 'pong';
});

// With transferList
registerPromiseWorker(function (message, withTransferList) {
  return withTransferList(pongImageData, [pongImageData.data.buffer]); // pongImageData transferred from worker to main 
});
```

Note that you `require()` two separate APIs, so the library is split
between the `worker.js` and main file. This keeps the total bundle size smaller.


### Message format

The message you send can be any object, array, string, number, etc.:

```js
// main.js
promiseWorker.postMessage({
  hello: 'world',
  answer: 42,
  "this is fun": true
}).then(/* ... */);
```

```js
// worker.js
registerPromiseWorker(function (message) {
  console.log(message); // { hello: 'world', answer: 42, 'this is fun': true }
});
```

### Promises

Inside of the worker, the registered handler can return either a Promise or a normal value:

```js
// worker.js
registerPromiseWorker(function () {
  return Promise.resolve().then(function () {
    return 'much async, very promise';
  });
});
```

```js
// main.js
promiseWorker.postMessage(null).then(function (message) {
  console.log(message): // 'much async, very promise'
});
```

Promise can return withTransferList as well:

```js
// worker.js
registerPromiseWorker(function (_, withTransferList) {
  return Promise.resolve().then(function () {
    return withTransferList(pongImageData, [pongImageData.data.buffer]); // pongImageData transferred to webworker
  });
});
```

```js
// main.js
promiseWorker.postMessage(null).then(function (message) {
  // message contains pongImageData
});
```

### Error handling

Any thrown errors or asynchronous rejections from the worker will
be propagated to the main thread as a rejected Promise. For instance:

```js
// worker.js
registerPromiseWorker(function (message) {
  throw new Error('naughty!');
});
```

```js
// main.js
promiseWorker.postMessage('whoops').catch(function (err) {
  console.log(err.message); // 'naughty!'
});
```

Note that stacktraces cannot be sent from the worker to the main thread, so you
will have to debug those errors yourself. This library does however, print
messages to `console.error()`, so you should see them there.

### Multi-type messages

If you need to send messages of multiple types to the worker, just add
some type information to the message you send:

```js
// main.js
promiseWorker.postMessage({
  type: 'en'
}).then(/* ... */);

promiseWorker.postMessage({
  type: 'fr'
}).then(/* ... */);
```

```js
// worker.js
registerPromiseWorker(function (message) {
  if (message.type === 'en') {
    return 'Hello!';
  } else if (message.type === 'fr') {
    return 'Bonjour!';
  }
});
```

### Service Workers

Communicating with a Service Worker is the same as with a Web Worker.
However, you have to wait for the Service Worker to install and start controlling the page. Here's an example:

```js
navigator.serviceWorker.register('sw.js', {
  scope: './'
}).then(function () {
  if (navigator.serviceWorker.controller) {
    // already active and controlling this page
    return navigator.serviceWorker;
  }
  // wait for a new service worker to control this page
  return new Promise(function (resolve) {
    function onControllerChange() {
      navigator.serviceWorker.removeEventListener('controllerchange', onControllerChange);
      resolve(navigator.serviceWorker);
    }
    navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
  });
}).then(function (worker) { // the worker is ready
  var promiseWorker = new PromiseWorker(worker);
  return promiseWorker.postMessage('hello worker!');
}).catch(console.log.bind(console));
```

Then inside your Service Worker:

```js
var registerPromiseWorker = require('../register');

registerPromiseWorker(function (msg) {
  return 'hello main thread!';
});

self.addEventListener('activate', function(event) {
  event.waitUntil(self.clients.claim()); // activate right now
});
```

Browser support
----

* Chrome
* Firefox
* Safari 8+
* IE 10+
* Edge
* iOS 8+
* Android 4.4+

If a browser [doesn't support Web Workers](http://caniuse.com/webworker) but you still want to use this library,
then you can use [pseudo-worker](https://github.com/nolanlawson/pseudo-worker).

For Service Worker support, Chrome 40 and 41 are known to be buggy (see [#9](https://github.com/nolanlawson/promise-worker/pull/9)), but 42+ are supported.

This library is not designed to run in Node.js.

API
---

### Main bundle

#### `new PromiseWorker(worker)`

Create a new `PromiseWorker`, using the given worker.

* `worker` - the `Worker` or [PseudoWorker](https://github.com/nolanlawson/pseudo-worker) to use.

#### `PromiseWorker.postMessage(message, optionalTransferList)`

Send a message to the worker and return a Promise.

* `message` - object - required
  * The message to send.
* `optionalTransferList` - array of objects to transfer, just as in usual Worker.postMessage.
* returns a Promise

### Worker bundle

Register a message handler inside of the worker. Your handler consumes a message
and returns a Promise or value.

#### `registerPromiseWorker(function)`

* `function`
  * Takes a message and withTransferList function, returns a Promise or a value.
  Value can be wrapped with withTransferList. withTransferList gets value and transferList. 


Testing the library
---

First:

    npm install

Then to test in Node (using an XHR/PseudoWorker shim):

    npm test

Or to test manually in your browser of choice:

    npm run test-local

Or to test in a browser using SauceLabs:

    npm run test-browser

Or to test in PhantomJS:

    npm run test-phantom

Or to test with coverage reports:

    npm run coverage

---
_Source: https://npm.io/package/promise-worker-transferable · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._