Merge pull request #398 from machty/mf-v2_release_finalization

v2 release finalization

Author: maxfierke

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
   push:
     branches:
       - master
+      - v1
       - v2
       # npm version tags
       - /^v\d+.\d+.\d+(?:-(?:alpha|beta|rc)\.\d+)?/

API.md

@@ -6,15 +6,24 @@ most of the time, you'll only be using the `task` and `timeout`
 imports, e.g.:
 
 ```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
 import { task, timeout } from 'ember-concurrency';
 
-export default Component.extend({
-  loopingTask: task(function * () {
+export default class MyCompontent extends Component {
+  @tracked num;
+
+  constructor() {
+    super(...arguments);
+    this.loopingTask.perform();
+  }
+
+  @task *loopingTask() {
     while (true) {
-      this.set('num', Math.random());
+      this.num = Math.random();
       yield timeout(100);
     }
-  }).on('init')
+  }
 });
 ```
 
@@ -44,6 +53,9 @@ used in conjunction with Tasks / TaskInstances.
 
 ## Misc
 
+- [animationFrame](global.html#animationFrame)
+- [didCancel](global.html#didCancel)
+- [forever](global.html#forever)
+- [rawTimeout](global.html#rawTimeout)
 - [waitForEvent](global.html#waitForEvent)
 - [waitForQueue](global.html#waitForQueue)
-

README.md

@@ -1,8 +1,3 @@
-# v2 Development Branch
-
-This here is the work-in-progress branch for ember-concurrency v2. This will be
-merged into master when v2 is ready for release.
-
 # ember-concurrency
 
 [![Build Status][build-status-img]][build-status-link]

UPGRADING-2.x.md

@@ -10,6 +10,20 @@ semantic changes to the operation of the addon.
 
 ## Changes
 
+### Drops support for Ember < 3.8 and Node 8
+
+ember-concurrency 2.0.0 drops support for many older Ember and Node versions.
+Usage with 3.8 LTS and up ensures ember-concurrency can depend on the same Ember
+runloop semantics (e.g. running on the microtask queue), while still providing a
+broad level of compatibility with existing apps.
+
+In some cases, polyfills will be needed for Ember 3.8, for example when using
+decorators. See [config/ember-try.js](config/ember-try.js) for the `ember-lts-3.8`
+scenario.
+
+ember-concurrency 1.x is still available for those apps needing support back to
+Ember 2.4 LTS.
+
 ### Decorators from `ember-concurrency-decorators` are built-in
 
 This provides built-in support for the "nice" decorator syntax based on the
@@ -82,6 +96,10 @@ depend on cancelation to finish by awaiting the value of the promise returned by
 the cancelation methods on `Task` and `TaskInstance`, `cancelAll` and `cancel`,
 respectively.
 
+It should be noted that when calling `cancelAll` with `{ resetState: true }`, the
+state reset does not take effect immediately, as it did in e-c 1.x, but happens
+on cancelation finalization, making it important to `await` calls to `cancelAll`.
+
 For example,
 
 ```javascript
@@ -282,3 +300,21 @@ jobs:
     - env: EMBER_TRY_SCENARIO=ember-concurrency-1.x
     - env: EMBER_TRY_SCENARIO=ember-concurrency-2.x
 ```
+
+## FAQ
+
+### Something is broken even though I made sure to do the above updates!
+
+First, make sure that ember-concurrency 2.0.0 or higher is the version that is
+being loaded and used by your application. It's often the case that an addon
+might be pinned to an older version and is pulling that in and it's being used
+instead. Check `yarn why ember-concurrency` to see how the versions are being
+resolved, if you're a `yarn` user. For npm, use whatever available equivalents.
+
+You may need to contact the maintainer of another addon to get them to release
+a version with support for ember-concurrency 2.0.0 (point them to this guide!)
+or you might be able to workaround it with Yarn resolutions, as the APIs are
+largely compatible between the two versions.
+
+If you've verified the proper version of ember-concurrency is being loaded and
+you still are seeing the issue, please reach out on Discord or open an issue here.

addon/-private/external/yieldables.js

@@ -107,8 +107,8 @@ class RawTimeoutYieldable extends Yieldable {
  * for every animation frame.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     let lastNow = performance.now();
  *     while (true) {
  *       yield animationFrame();
@@ -119,8 +119,8 @@ class RawTimeoutYieldable extends Yieldable {
  *
  *       console.log(dt);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  */
 export function animationFrame() {
@@ -148,14 +148,13 @@ export function animationFrame() {
  *
  * ```js
  * import { task, forever } from 'ember-concurrency';
- *
- * export default Component.extend({
- *   myService: service(),
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @service myService;
+ *   @task *myTask() {
  *     yield this.myService.doSomethingThatCausesATransition();
  *     yield forever;
- *   })
- * });
+ *   }
+ * }
  * ```
  */
 export const forever = new ForeverYieldable();
@@ -183,14 +182,14 @@ export function raw(value) {
  * console every second.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     while (true) {
  *       console.log("Hello!");
  *       yield rawTimeout(1000);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param {number} ms - the amount of time to sleep before resuming

addon/-private/task-instance.js

@@ -154,7 +154,7 @@ export class TaskInstance extends BaseTaskInstance {
    * `on` from `@ember/object/evented` may be used to create a binding on the host object to the event.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   doSomething: task(function * () {
    *     // ... does something
    *   }),
@@ -175,7 +175,7 @@ export class TaskInstance extends BaseTaskInstance {
    * `on` from `@ember/object/evented` may be used to create a binding on the host object to the event.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   doSomething: task(function * () {
    *     // ... does something
    *   }),
@@ -197,7 +197,7 @@ export class TaskInstance extends BaseTaskInstance {
    * `on` from `@ember/object/evented` may be used to create a binding on the host object to the event.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   doSomething: task(function * () {
    *     // ... does something
    *   }),
@@ -219,7 +219,7 @@ export class TaskInstance extends BaseTaskInstance {
    * `on` from `@ember/object/evented` may be used to create a binding on the host object to the event.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   doSomething: task(function * () {
    *     // ... does something
    *   }),

addon/-private/task-properties.js

@@ -132,7 +132,7 @@ Object.assign(TaskProperty.prototype, propertyModifiers, {
    * when the host object is initialized.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   pollForUpdates: task(function * () {
    *     // ... this runs when the Component is first created
    *     // because we specified .on('init')

addon/-private/utils.js

@@ -59,14 +59,14 @@ class TimeoutYieldable extends EmberYieldable {
  * console every second.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     while (true) {
  *       console.log("Hello!");
  *       yield timeout(1000);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param {number} ms - the amount of time to sleep before resuming

addon/-private/wait-for.js

@@ -124,12 +124,12 @@ class WaitForPropertyYieldable extends EmberYieldable {
  *
  * ```js
  * import { task, waitForQueue } from 'ember-concurrency';
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     yield waitForQueue('afterRender');
  *     console.log("now we're in the afterRender queue");
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param {string} queueName the name of the Ember run loop queue
@@ -145,8 +145,8 @@ export function waitForQueue(queueName) {
  *
  * ```js
  * import { task, waitForEvent } from 'ember-concurrency';
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     console.log("Please click anywhere..");
  *     let clickEvent = yield waitForEvent($('body'), 'click');
  *     console.log("Got event", clickEvent);
@@ -155,8 +155,8 @@ export function waitForQueue(queueName) {
  *     console.log("Got foo event", emberEvent);
  *
  *     // somewhere else: component.trigger('foo', { value: 123 });
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param {object} object the Ember Object, jQuery element, or other object with .on() and .off() APIs
@@ -187,24 +187,24 @@ export function waitForEvent(object, eventName) {
  *
  * ```js
  * import { task, waitForProperty } from 'ember-concurrency';
- * export default Component.extend({
- *   foo: 0,
+ * export default class MyComponent extends Component {
+ *   @tracked foo = 0;
  *
- *   myTask: task(function * () {
+ *   @task *myTask() {
  *     console.log("Waiting for `foo` to become 5");
  *
  *     yield waitForProperty(this, 'foo', v => v === 5);
  *     // alternatively: yield waitForProperty(this, 'foo', 5);
  *
- *     // somewhere else: this.set('foo', 5)
+ *     // somewhere else: this.foo = 5;
  *
  *     console.log("`foo` is 5!");
  *
  *     // wait for another task to be idle before running:
  *     yield waitForProperty(this, 'otherTask.isIdle');
  *     console.log("otherTask is idle!");
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param {object} object an object (most likely an Ember Object)

addon/index.d.ts

@@ -393,7 +393,7 @@ interface AbstractTaskProperty<T extends Task<any, any[]>> extends ComputedPrope
    * when the host object is initialized.
    *
    * ```js
-   * export default Ember.Component.extend({
+   * export default Component.extend({
    *   pollForUpdates: task(function * () {
    *     // ... this runs when the Component is first created
    *     // because we specified .on('init')
@@ -1122,8 +1122,8 @@ export function allSettled<T>(values: Iterable<T>): Promise<Array<Settled<T>>>;
  * for every animation frame.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     let lastNow = performance.now();
  *     while (true) {
  *       yield animationFrame();
@@ -1134,8 +1134,8 @@ export function allSettled<T>(values: Iterable<T>): Promise<Array<Settled<T>>>;
  *
  *       console.log(dt);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  */
 export function animationFrame(): Yieldable;
@@ -1219,14 +1219,14 @@ export function race<T>(values: Iterable<T>): Promise<Resolved<T>>;
  * console every second.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     while (true) {
  *       console.log("Hello!");
  *       yield timeout(1000);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param ms The amount of time to sleep before resuming
@@ -1246,14 +1246,14 @@ export function timeout(ms: number): Yieldable;
  * console every second.
  *
  * ```js
- * export default Component.extend({
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @task *myTask() {
  *     while (true) {
  *       console.log("Hello!");
  *       yield rawTimeout(1000);
  *     }
- *   })
- * });
+ *   }
+ * }
  * ```
  *
  * @param ms The amount of time to sleep before resuming
@@ -1380,13 +1380,14 @@ export function waitForProperty<O extends object, K extends keyof O>(
  * ```js
  * import { task, forever } from 'ember-concurrency';
  *
- * export default Component.extend({
- *   myService: service(),
- *   myTask: task(function * () {
+ * export default class MyComponent extends Component {
+ *   @service myService;
+ *
+ *   @task *myTask() {
  *     yield this.myService.doSomethingThatCausesATransition();
  *     yield forever;
- *   })
- * });
+ *   }
+ * }
  * ```
  */
 export function forever(): Yieldable<never>;