ember-concurrency-ts

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

ember-concurrency-ts

★ 15 Open GitHub ↗

TypeScript utilities for ember-concurrency.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

ember-concurrency-ts
==============================================================================

TypeScript utilities for [ember-concurrency][e-c].

*NOTE: [ember-concurrency v2.3.0][e-c-2.3-release] introduces a new async arrow function `task()` API (along with codemods to automatically convert your code to the new style) that is TypeScript-friendly and eliminates most or all of the need for this package (as well as [ember-concurrency-async][e-c-async]).*

This is how you would typically write [ember-concurrency][e-c] tasks in Octane:

```ts
import { action } from '@ember/object';
import Component from '@glimmer/component';
import { task, TaskGenerator, timeout } from 'ember-concurrency';

export default class extends Component {
  @task *myTask(ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return 'done!';
  }

@action performTask() {
    if (this.myTask.isRunning) {
      return;
    }

this.myTask.perform(1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

Since we are using native classes in Octane, TypeScript have an easier time
understanding and following our code. Normally, this is a good thing, but in
the case of ember-concurrency, it ends up getting a bit in the way.

ember-concurrency's API was designed with Class Ember in mind, where it could
decorate a property or method and replace it with a different type in the
`.extend()` hook.

This is not allowed using TypeScript's decorators. Since `myTask` is defined
using as the generator method syntax, and since methods do not have a
`.perform()` method on them, calling `this.myTask.perform()` will result in a
type error, even though it will work at runtime.

We could work around this by type casting the method, such as
`(this.myTask as any as Task<string, number>)`, but doing this everywhere is
quite verbose and error-prone.

Instead, this addon provides some TypeScript-specific utility functions to
encapsulate the type cast transparently. See the [Usage](#usage) section for
details.

Compatibility
------------------------------------------------------------------------------

* [ember-concurrency][e-c] 2.0.0 or above
* [ember-concurrency-async][e-c-async] 0.2.0 or above (optional)
* Ember.js v3.12 or above
* Ember CLI v2.13 or above
* Node.js v10 or above
* TypeScript 3.7, 3.9 or 4.*

**NOTE:** if you use [ember-concurrency][e-c] v1.*, you should use v0.2 version
of this package.

Installation
------------------------------------------------------------------------------

```
ember install ember-concurrency-ts
```

Optionally, if using [ember-concurrency-async][e-c-async], add the following to
`types/<app name>/index.d.ts`:

```ts
import 'ember-concurrency-async';
import 'ember-concurrency-ts/async';
```

Usage
------------------------------------------------------------------------------

### `taskFor`

The `taskFor` utility function allows the code example from above to type
check:

```ts
import { action } from '@ember/object';
import Component from '@glimmer/component';
import { task, TaskGenerator, timeout } from 'ember-concurrency';
import { taskFor } from 'ember-concurrency-ts';

export default class extends Component {
  @task *myTask(ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return 'done!';
  }

@action performTask() {
    if (taskFor(this.myTask).isRunning) {
      return;
    }

taskFor(this.myTask).perform(1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

Instead of accessing the task directly, wrapping it in the `taskFor` utility
function will allow TypeScript to understand what we are trying to accomplish.
If this becomes repetitive, you may extract it into a variable or getter, and
the code will still type check:

export default class extends Component {
  @task *myTask(ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return 'done!';
  }

@action performTask() {
    let myTask = taskFor(this.myTask);

if (myTask.isRunning) {
      return;
    }

myTask.perform(1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

Note that everything on the task is type-inferred from the method definition.
Based on the return type of `*myTask`, TypeScript knows that `myTask.value` is
`string | undefined`. Likewise, it knows that `myTask.perform()` takes the same
arguments as `*myTask`. Passing the wrong arguments will be a type error. It
also knows that the `value` promise callback parameter is a `string`.

#### Alternate usage of `taskFor`

The `taskFor` utility function can also be used at assignment:

export default class extends Component {
  @task myTask = taskFor(function*(ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return 'done!';
  });

@action performTask() {
    if (this.myTask.isRunning) {
      return;
    }

this.myTask.perform(1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

This allows you to access the task directly without using `taskFor` and `perform`. The one
caveat here is that the `this` type must be asserted if you are referencing `this` in your task:

export default class MyComponent extends Component {
  returnVal = 'done';

@task myTask = taskFor(function*(this: MyComponent, ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return this.returnVal;
  });

@action performTask() {
    if (this.myTask.isRunning) {
      return;
    }

this.myTask.perform(1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

### `perform`

As a convenience, this addon also provide a `perform` utility function as a
shorthand for `myTask(...).perform(...)`:

```ts
import { action } from '@ember/object';
import Component from '@glimmer/component';
import { task, TaskGenerator, timeout } from 'ember-concurrency';
import { perform } from 'ember-concurrency-ts';

export default class extends Component {
  @task *myTask(ms: number): TaskGenerator<string> {
    yield timeout(ms);
    return 'done!';
  }

@action performTask() {
    perform(this.myTask, 1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

Just like `taskFor`, it infers the type information from `*myTask`, type checks
the arguments as has the right return type, etc.

### `ember-concurrency-async`

This addon can be used together with [ember-concurrency-async][e-c-async], see
the [Installation](#installation) section for additional instructions.

```ts
import { action } from '@ember/object';
import Component from '@glimmer/component';
import { task, timeout } from 'ember-concurrency';
import { taskFor, perform } from 'ember-concurrency-ts';

export default class extends Component {
  @task async myTask(ms: number): Promise<string> {
    await timeout(ms);
    return 'done!';
  }

@action performTask() {
    if (taskFor(this.myTask).isRunning) {
      return;
    }

perform(this.myTask, 1000).then(value => {
      console.log(value.toUpperCase());
    });
  }
}
```

### Type Safety

Under-the-hood, these utility functions are just implemented as [unsafe type
casts](./addon/index.js). For example, the examples will still type check if
the `@task` decorator is omitted (so `this.myTask` is just a regular generator
or async method), but you will get an error at runtime.

Contributing
------------------------------------------------------------------------------

See the [Contributing](CONTRIBUTING.md) guide for details.

License
------------------------------------------------------------------------------

This project is licensed under the [MIT License](LICENSE.md).

[e-c]: https://github.com/machty/ember-concurrency
[e-c-async]: https://github.com/chancancode/ember-concurrency-async
[e-c-2.3-release]: https://github.com/machty/ember-concurrency/releases/tag/2.3.0

ember-concurrency-ts

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README