ember-api-docs icon indicating copy to clipboard operation
ember-api-docs copied to clipboard

Document nullish timer argument for cancel()

Open andreyfel opened this issue 3 years ago • 1 comments

Current documentation doesn't mention that the timer argument can be undefined/null: https://api.emberjs.com/ember/4.1/functions/@ember%2Frunloop/cancel

However, the implementation allows that: https://github.com/BackburnerJS/backburner.js/blob/af77b18f37ec24e89f65bef0ce16bc3c8d1f4bfb/lib/index.ts#L551

In fact, in our code, we were leveraging the fact that you can pass undefined as the timer argument. It may be useful if you have a local var where you save the timer, so, the type f this var is EmberRunTimer | undefined because the timer is not initialized in the constructor. In willDestroy hook we call cancel(this.timer).

In fact, we should understand if we can keep doing that or we cave to wrap such calls with if (this.timer) check.

@ember/runloop types do not allow undefined, this is where this issue came from. https://github.com/DefinitelyTyped/DefinitelyTyped/pull/58893

andreyfel avatar Feb 24 '22 08:02 andreyfel

Personally, I think the app code should write the conditional for clarity, but I think the intention here is to match the DOM apis for clearTimeout etc, and since TS also marks that as ? it seems fine to do the same.

chancancode avatar Apr 12 '22 21:04 chancancode