Function task

Wrap an argument-taking function so it will run in (and returns) a new Job when called.

This lets you avoid the common pattern of needing to write your functions or methods like this:

function outer(arg1, arg2) {
    return start(function*() {
        // ...
    })
}
Copy

and instead write them like this:

const outer = task(function *(arg1, arg2) {
    // ...
});
Copy

or this:

class Something {
    ⁣⁣@task  // auto-detects TC39 or legacy decorators
    *someMethod(arg1): Yielding<SomeResultType> {
        // ...
    }
}
Copy

Important: if the wrapped function or method has overloads, the resulting function type will be based on the last overload, because TypeScript (at least as of 5.x) is still not very good at dealing with higher order generics, especially if overloads are involved.

Also note that TypeScript doesn't allow decorators to change the calling signature or return type of a method, so even though the above method will return a Job, TypeScript will only see it as a Yielding.

This is fine if all you're going to do is yield * it to wait for the result, but if you need to use any job-specific methods on it, you'll have to pass it through start to have TypeScript treat it as an actual job. (Luckily, start() has a fast path to return the original job if it's passed a job, so you won't actually create a new job by doing this.)