ember-concurrency-decorators

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

Installation

⚠️👉 Check the FAQ, if something isn't working or you're not sure what to do.

Stage 1 Decorators

Requirements:

• At least ember-cli-babel@^7.7.2
• At least ember-cli-typescript@^2.0.0, if you want to use it with TypeScript
• @ember-decorators/babel-transforms is not installed
• The rest of @ember-decorators, if present, is ^6.0.0
• Below Ember v3.10: ember-decorators-polyfill

Then install the latest beta:

ember install ember-concurrency-decorators@beta

Stage 2 Decorators

If you are still using stage 2 decorators, I recommend that refactor away from them as soon as possible.

Requirements:

• at least ember-cli-babel@^7.7.2
• @ember-decorators/babel-transforms is installed
• The rest of @ember-decorators, if present, is ^5.0.0 (below 6.0.0)

Then install the current latest version:

ember install ember-concurrency-decorators@latest

The following documentation will not be accurate. Instead refer to the docs for stage 2 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:

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:

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';
}

FAQ

Compatibility and Weird Errors

The specification for decorators in broader JavaScript has been in flux. Unfortunately, that means if you have been an early adopter of decorators in your Ember application, you may need to deal with some API churn.

(You can read an excellent discussion on decorators here.)

Check the above requirements to see what version you need to install.

If you are sure, that you fulfilled the requirements correctly, but are still experiencing weird errors, install ember-cli-dependency-lint to ensure that you are not accidentally including outdated versions of ember-decorators as transitive dependencies.

If it's still not working after that, please create an issue.

TypeScript Support

You can use this package with ember-cli-typescript@2. But unfortunately decorators cannot yet change the type signature of the decorated element. This is why you are getting type errors like:

import { task } from 'ember-concurrency-decorators';

export default class Foo {
  @task
  doStuff = function*(this: Foo) {
    // ...
  };

  executeTheTask() {
    this.doStuff.perform();
  }
}

TS2339: Property 'perform' does not exist on type '() => IterableIterator<any>'.

Check issue #30 for more details.

Very soon, you will be able to use the following syntax instead with TypeScript:

import { task } from 'ember-concurrency-decorators';

export default class Foo {
  doStuff = task(function*(this: Foo) {
    // ...
  });

  executeTheTask() {
    this.doStuff.perform();
  }
}

This might not be using a fancy decorator, but it is 💯 type-safe! 🎉

What happened to the fancy generator method syntax?

With the pre-1.0.0 version of ember-concurrency-decorators, you used to be able to use the following sleek syntax:

import { task } from 'ember-concurrency-decorators';

export default class Foo {
  @task
  *doStuff() {
    // ...
  }

  executeTheTask() {
    this.doStuff.perform();
  }
}

This only worked with stage 2 decorators, which are not supported any more. Decorating generator methods with stage 1 decorators, is currently not possible, because of a bug in the stage 1 Babel parser.

There already is a PR that will fix this and make the above syntax available for stage 1 decorators. The fix is expected to be shipped with the next minor release of Babel (v7.5.0).

You can find more information about this bug in issue #48.

If you don't want to wait until the fix is merged and released upstream, you can use patch-package or a similar technique to apply the patch yourself. You can find an example of that in PR #54.

Please note that if you are using TypeScript, you likely still would not want to use this syntax, since it would lead to (false) type errors. See TypeScript Support for more details.

Do I need this addon?

No! If you are using Ember v3.10.0 or above, you can use ember-concurrency directly, like this:

import { task } from 'ember-concurrency';

class Foo {
  @(task(function*() {
    // ...
  }).restartable())
  doStuff;

  executeTheTask() {
    this.doStuff.perform();
  }
}

However:

• This syntax will not continue to work with the new "static decorators" proposal that is set to replace the stage 1 decorators eventually.
• This does not properly type-check with TypeScript. See TypeScript Support for more details.
• I think this looks hideous, but that is just an opinion.

Eventually, all work in ember-concurrency-decorators will likely flow back into ember-concurrency at some point. Until then, we want to mature and test-drive the API here first.

License

This project is licensed under the MIT License.