Package Exports

ember-concurrency-decorators

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ember-concurrency-decorators) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ember-concurrency-decorators

This Ember addon lets you use the decorator syntax for declaring/configuring ember-concurrency tasks.

Installation

This package only works with Ember Octane, which is currently the latest Ember Beta. You'll need at least ember-cli-babel@^7.7.2 and not use @ember-decorators/babel-transforms, so that you get the Ember.js vanilla stage 1 / legacy decorators. Then install as any other addon:

ember install ember-concurrency-decorators@beta

For non-Octane apps, use the latest version:

ember install ember-concurrency-decorators

Usage

Available decorators

@task: turns a generator method into a task
- @restartableTask
- @dropTask
- @keepLatestTask
- @enqueueTask
@taskGroup: creates a task group from a property
- @restartableTaskGroup
- @dropTaskGroup
- @keepLatestTaskGroup
- @enqueueTaskGroup
@lastValue: alias a property to the result of a task with an optional default value

`@task`

import Component from '@ember/component';
import { task } from 'ember-concurrency-decorators';

export default class ExampleComponent extends Component {
  @task
  doStuff = function*() {
    // ...
  };

  // and then elsewhere
  executeTheTask() {
    // `doStuff` is still a `Task` object that can be `.perform()`ed
    this.doStuff.perform();
    console.log(this.doStuff.isRunning);
  }
}

You can also pass further options to the task decorator:

@task({
  maxConcurrency: 3,
  restartable: true
})
doStuff = function*() {
  // ...
}

For your convenience, there are extra decorators for all concurrency modifiers:

Shorthand	Equivalent
`@restartableTask`	`@task({ restartable: true })`
`@dropTask`	`@task({ drop: true })`
`@keepLatestTask`	`@task({ keepLatest: true })`
`@enqueueTask`	`@task({ enqueue: true })`

You can still pass further options to these decorators, like:

@restartableTask({ maxConcurrency: 3 })
doStuff = function*() {
  // ...
}

Encapsulated Tasks

Encapsulated Tasks behave just like regular tasks, but with one crucial difference: the value of this within the task function points to the currently running TaskInstance, rather than the host object that the task lives on (e.g. a Component, Controller, etc). This allows for some nice patterns where all of the state produced/mutated by a task can be contained (encapsulated) within the Task itself, rather than having to live on the host object.

import Component from '@ember/component';
import { task } from 'ember-concurrency-decorators';

export default class ExampleComponent extends Component {
  @task
  doStuff = {
    privateState: 123,
    *perform() {
      // ...
    }
  };

  // and then elsewhere
  executeTheTask() {
    // `doStuff` is still a `Task` object that can be `.perform()`ed
    this.doStuff.perform();
    console.log(this.doStuff.isRunning);
  }
}

Encapsulated Tasks do not work with ember-cli-typescript@1. See the TypeScript section for more details.

`@taskGroup`

import Component from '@ember/component';
import { task, taskGroup } from 'ember-concurrency-decorators';

export default class ExampleComponent extends Component {
  @taskGroup
  someTaskGroup;

  @task({ group: 'someTaskGroup' })
  doStuff = function*() {
    // ...
  };

  @task({ group: 'someTaskGroup' })
  doOtherStuff = function*() {
    // ...
  };

  // and then elsewhere
  executeTheTask() {
    // `doStuff` is still a `Task `object that can be `.perform()`ed
    this.doStuff.perform();

    // `someTaskGroup` is still a `TaskGroup` object
    console.log(this.someTaskGroup.isRunning);
  }
}

You can also pass further options to the task group decorator:

@taskGroup({
  maxConcurrency: 3,
  drop: true
}) someTaskGroup;

As for @task, there are extra decorators for all concurrency modifiers:

Shorthand	Equivalent
`@restartableTaskGroup`	`@taskGroup({ restartable: true })`
`@dropTaskGroup`	`@taskGroup({ drop: true })`
`@keepLatestTaskGroup`	`@taskGroup({ keepLatest: true })`
`@enqueueTaskGroup`	`@taskGroup({ enqueue: true })`

You can still pass further options to these decorators, like:

@dropTaskGroup({ maxConcurrency: 3 }) someTaskGroup;

`@lastValue`

This decorator allows you to alias a property to the result of a task. You can also provide a default value to use before the task has completed.

import Component from '@ember/component';
import { task } from 'ember-concurrency-decorators';
import { lastValue } from 'ember-concurrency-decorators';

export default class ExampleComponent extends Component {
  @task
  someTask = function*() {
    // ...
  };

  @lastValue('someTask')
  someTaskValue;

  @lastValue('someTask')
  someTaskValueWithDefault = 'A default value';
}

License

This project is licensed under the MIT License.