feat: async debounce

[frodi-karlsson]

I recommend we have async versions of these to match asyncMemo

I ran into this with runInBackground as follows, in a way that broke at runtime:

class SomeService {
  @_Throttle(1000)
  async flush(): Promise<void> {
    // ...
  }
}

  // elsewhere:
 runInBackground(this.someService.flush())
  
  // runInBackground immediately does undefined.catch(...)

There's still a small quirk with this implementation:

const save = _asyncThrottle(..., 1000, { trailing: false })

const a = save('a')
const b = save('b') // Promise<undefined>

which is fine for the function variant, but for decorated variants it means

@_AsyncThrottle(1000, { trailing: false })
async someMethod(): Promise<number> { ... }

actually can return Promise<number | undefined> which is still better than returning a sync undefined

[Copilot]

Pull request overview

Adds async-safe debounce/throttle utilities and method decorators so async functions always return Promises (aligning semantics with async memoization), plus a small refactor to centralize the MethodDecorator type.

Changes:

• Add _asyncDebounce / _asyncThrottle to provide Promise-based coalescing semantics for async functions.
• Add @_AsyncDebounce / @_AsyncThrottle decorators for async methods and extend test coverage for the new APIs.
• Move the generic MethodDecorator<T> helper type to decorator.util.ts and update imports accordingly.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/js-lib/src/decorators/memo.util.ts	Removes the MethodDecorator type from memo utilities (relocated).
packages/js-lib/src/decorators/memo.decorator.ts	Switches MethodDecorator import to decorator.util.ts.
packages/js-lib/src/decorators/decorator.util.ts	Adds the shared generic MethodDecorator<T> type definition.
packages/js-lib/src/decorators/debounce.ts	Refactors debounce timing state and introduces _asyncDebounce / _asyncThrottle.
packages/js-lib/src/decorators/debounce.test.ts	Adds tests for _asyncDebounce / _asyncThrottle.
packages/js-lib/src/decorators/debounce.decorator.ts	Adds @_AsyncDebounce / @_AsyncThrottle decorators for async methods.
packages/js-lib/src/decorators/debounce.decorator.test.ts	Adds tests for the new async decorators.
packages/js-lib/src/decorators/asyncMemo.decorator.ts	Switches MethodDecorator import to decorator.util.ts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kirillgroshkov]

Ok, I trust you that it works.

[github-actions]

🎉 This PR is included in @naturalcycles/js-lib-v15.84.0 🎉