Nature's Powerful Meme

    ember-web-workers

    1.0.0 • Public • Published

    ember-web-workers

    Build Status GitHub version NPM version Dependency Status codecov Greenkeeper badge Ember Observer Score

    Information

    NPM

    Service to communicate your application with browser web workers.

    • Ember.js v3.12 or above
    • Ember CLI v2.13 or above
    • Node.js v10 or above

    This addon can be installed with ember-cli:

    • ember install ember-web-workers

    ember-web-workers

    Usage

    • Create the web worker file in public (follow this blueprint):
    // public/assets/web-workers/test.js
     
    // Wait for the initial message event.
    self.addEventListener('message', function(e) {
      var data = e.data;
      var port = e.ports[0];
     
      // Do your stuff here.
      if (port) {
        // Message sended throught a worker created with 'open' method.
        port.postMessage({ foo: 'foo' });
      } else {
        // Message sended throught a worker created with 'send' or 'on' method.
        postMessage({ bar: 'bar' });
      }
    }, false);
     
    // Ping the Ember service to say that everything is ok.
    postMessage(true);
    • Import the service in your application:
    // Some Ember context.
    {
      worker: Ember.inject.service()
    }
    • Use the methods to communicate with the web worker:

    postMessage

    Method used to make a request and wait for a response. This method returns a promise that will be resolved after the worker responses.

    When promise resolves the worker will be terminated.

    Arguments:

    • worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).
    • data: transferable object (true will be ignored, def. for ping).
    // Some Ember context.
    {
      foo() {
        return this.get('worker').postMessage('test', { foo: 'bar' }).then((response) => {
            // response => { bar: 'bar' }
          }, (error) => {
            // error contains the message thrown by the worker.
          });
      }
    }

    terminate

    Using this method a pending promise can be cancelled, this will terminate the worker associated and the promise will be rejected.

    If promise is not provided, it will kill all the active workers.

    Arguments:

    • promise: the promise returned by the send function (optional).
    // Some Ember context.
    {
      foo() {
        const worker = this.get('worker');
        const promise = worker.postMessage('test', { foo: 'bar' });
     
        worker.terminate(promise);
      }
    }

    on/off

    Methods used to subscribe to a worker events. The worker will be alive until the event is detached.

    Arguments:

    • worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).
    • callback: callback to be executed each time worker sends a message (postMessage). callback is optional for off method.
      • If callback is not passed for off method, then all the instantiated worker with the passed name will be terminated
      • If callback is passed, then the corresponding worker associated with the callback will only be terminated.
    // Some Ember context.
     
    function callback(data) {
      console.log(data.foo, data.bar); // 'foo bar'
    }
     
    {
      foo() {
        const worker = this.get('worker');
     
        return worker.on('test', callback).then(() => {
            // Worker has been created.
            // Terminate it after 5 seconds.
            setTimeout(() => {
              worker.off('test', callback);
            }, 5000);
          }, (error) => {
            // Worker error, it has been terminated.
          });
      }
    }

    open

    This method creates a new worker and stablish a communication allowing to keep it alive to send 1..n messages until terminates.

    Arguments:

    • worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).

    Promise argument (object):

    • postMessage: Alias to send a message to the worker.
    • terminate: Close the connection and terminate the worker
    // Some Ember context.
     
    {
      foo() {
        const worker = this.get('worker');
     
        return worker.open('test').then((stream) => {
            const data1 = stream.send({ foo: 'foo' });
            const data2 = stream.send({ bar: 'bar' });
     
            // Wait responses.
            return Ember.RSVP.all([data1, data2]).then(() => {
              // Kill the worker.
              stream.terminate();
     
              // Do something with the worker responses.
              return data1.foo + data2.bar;
            });
          }, (error) => {
            // Worker error, it has been terminated.
          });
      }
    }

    Handling errors

    To reject the promise an error must be thrown inside the worker:

    // Worker context.
     
    throw new Error('foo');
     
     
    // Some Ember context.
     
    {
      foo() {
        return this.get('worker').postMessage('test').catch((error) => {
            console.error(error); // Unhandled error: foo
          });
      }
    }

    Contribute

    If you want to contribute to this addon, please read the CONTRIBUTING.md.

    Versioning

    We use SemVer for versioning. For the versions available, see the tags on this repository.

    Authors

    See the list of contributors who participated in this project.

    Contributing

    See the Contributing guide for details.

    License

    This project is licensed under the MIT License - see the LICENSE.md file for details

    Install

    npm i ember-web-workers

    DownloadsWeekly Downloads

    83

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    18.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • bbvaengineer
    • josex2r