This Ember addon lets you use the decorator syntax for declaring/configuring ember-concurrency tasks.
All of the decorators provided by this repo were merged into Ember Concurrency v2; if you running Ember Concurrency 2.0.0+, you can remove this addon, and convert all of your import {...} from 'ember-concurrency-decorators'
to import {...} from 'ember-concurrency'
.
⚠️👉 Check the FAQ, if something isn't working or you're not sure what to do.
Requirements:
ember-cli-babel@^7.7.2
@babel/core@^7.5.0
(as a transitive dependency via ember-cli-babel
)ember-cli-typescript@^2.0.0
, if you want to use it with TypeScript@ember-decorators/babel-transforms
is not installed@ember-decorators
, if present, is ^6.0.0
ember-decorators-polyfill
Then install the latest
release:
ember install ember-concurrency-decorators
If you are still using stage 2 decorators, I recommend that you refactor away from them as soon as possible.
Requirements:
ember-cli-babel@^7.7.2
@ember-decorators/babel-transforms
is installed@ember-decorators
, if present, is ^5.0.0
(below 6.0.0
)Then install the legacy
version:
ember install ember-concurrency-decorators@legacy
The following documentation will not be accurate. Instead refer to the docs for stage 2 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() {
// ...
}
// 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() {
// ...
}
You can also use task lifecycle event hooks in your tasks:
@task({ on: 'didInsertElement' })
*doStuff() {
// ...
}
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() {
// ...
}
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);
}
}
Unfortunately, encapsulated Tasks do not currently work well with TypeScript. 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() {
// ...
}
@task({ group: 'someTaskGroup' })
*doOtherStuff() {
// ...
}
// 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() {
// ...
}
@lastValue('someTask')
someTaskValue;
@lastValue('someTask')
someTaskValueWithDefault = 'A default value';
}
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.
You can use this package with TypeScript, but unfortunately decorators cannot yet change the type signature of the decorated element. This is why you may get type errors like:
import { task } from 'ember-concurrency-decorators';
export default class Foo {
@task
*doStuff(this: Foo) {
// ...
}
executeTheTask() {
this.doStuff.perform();
}
}
TS2339: Property 'perform' does not exist on type '() => IterableIterator<any>'.
See ember-concurrency's documentation on TypeScript for more details and workarounds.
See also issue #30 and PR #56 for more historical context and alternative design ideas.
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:
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.
This project is licensed under the MIT License.