https://github.com/dokmic/ts-async-decorators
TypeScript Async Method Decorators
https://github.com/dokmic/ts-async-decorators
async cancelable debounce decorator decorators mutex promise retry semaphore throttle timeout typescript
Last synced: 5 months ago
JSON representation
TypeScript Async Method Decorators
- Host: GitHub
- URL: https://github.com/dokmic/ts-async-decorators
- Owner: dokmic
- Created: 2021-01-09T20:18:54.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-10-31T09:11:07.000Z (about 4 years ago)
- Last Synced: 2025-08-12T01:55:08.316Z (5 months ago)
- Topics: async, cancelable, debounce, decorator, decorators, mutex, promise, retry, semaphore, throttle, timeout, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ts-async-decorators
- Size: 45.9 KB
- Stars: 20
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TypeScript Async Method Decorators 🧰
[](https://www.npmjs.com/package/ts-async-decorators)
[](https://www.npmjs.com/package/ts-async-decorators)
[](https://github.com/dokmic/ts-async-decorators/actions/workflows/tests.yaml)
[](https://codecov.io/gh/dokmic/ts-async-decorators?branch=master)
[](https://opensource.org/licenses/MIT)
This package provides a collection of asynchronous method decorators with an elegant declarative API.
## What's Inside?
- `after` - post action.
- `before` - pre action.
- `cancelable` - canceling execution.
- `debounce` - delaying execution by timeout since the last call.
- `retry` - retrying on fail.
- `semaphore` - limiting the number of simultaneous calls.
- `throttle` - limiting the number of calls per time range.
- `timeout` - limiting the execution time.
## Get Started
```bash
npm install --save ts-async-decorators
```
## API
### `after`
Calls an action after a decorated method.
```typescript
after({ action, wait = false }): Decorator
```
- `action: (instance) => unknown` - The action to call after the decorated method.
- `wait: boolean` - The flag to wait with promise resolution until the action completes.
#### Example
```typescript
import { after } from 'ts-async-decorators';
class SomeClass {
@after({ action() { console.log('called fetch!'); } })
fetch() {
// ...
}
}
```
### `before`
Calls an action before a decorated method.
```typescript
before({ action, wait = false }): Decorator
```
- `action: (instance) => unknown` - The action to call before the decorated method.
- `wait: boolean` - The flag to wait with the decorated method call until the action completes.
#### Example
```typescript
import { before } from 'ts-async-decorators';
class SomeClass {
@before({ action() { console.log('calling fetch!'); } })
fetch() {
// ...
}
}
```
### `cancelable`
Wraps a call inside a cancelable promise.
```typescript
cancelable({ onCancel = undefined }): Decorator
```
- `onCancel: (instance) => void` - The action to call on canceling the returned promise.
There is also an option to set the cancelation callback from within the decorated method.
```typescript
onCancel(callback): void
```
- `callback: (instance) => void` - The callback that will be called on promise cancelation.
#### Example using parameters
```typescript
import { cancelable } from 'ts-async-decorators';
class SomeClass {
@cancelable({ onCancel() { this.stop(); } })
start() {
// ...
}
stop() {
// ...
}
}
```
#### Example using `onCancel`
```typescript
import { cancelable, onCancel } from 'ts-async-decorators';
class SomeClass {
@cancelable()
fetch() {
const controller = new AbortController();
const { signal } = controller;
onCancel(() => controller.abort());
return fetch('http://example.com', { signal });
}
}
```
### `debounce`
Delays execution by timeout since the last call.
```typescript
debounce({ immediate = false, timeout }): Decorator
```
- `immediate: boolean` - The flag to call the decorated method on the leading edge.
- `timeout: number | ((instance) => number)` - The decorated method will be called only once after `timeout` milliseconds since the last call.
#### Example
```typescript
import { debounce } from 'ts-async-decorators';
class SomeClass {
@debounce({ timeout: 2000 })
handleChange() {
// ...
}
}
```
### `retry`
Retries failed method calls.
```typescript
retry({ retries }): Decorator
```
- `retries: number | ((instance) => number)` - The retries number.
#### Example
```typescript
import { retry } from 'ts-async-decorators';
class SomeClass {
@retry({ retries: 3 })
fetch() {
// ...
}
}
```
### `semaphore`
Limits the number of simultaneous calls.
```typescript
semaphore({ limit }): Decorator
```
- `limit: number` - The max number of simultaneous calls.
#### Example
```typescript
import { semaphore } from 'ts-async-decorators';
const mutex = () => semaphore({ limit: 1 });
class SomeClass {
@mutex()
connect() {
// ...
}
@semaphore({ limit: 2 })
read() {
// ...
}
}
```
### `throttle`
Limits the number of calls per time range.
```typescript
throttle({ immediate = false, timeout }): Decorator
```
- `immediate: boolean` - The flag to call the decorated method on the leading edge.
- `timeout: number | ((instance) => number)` - The decorated method will be called only once within `timeout` milliseconds.
#### Example
```typescript
import { throttle } from 'ts-async-decorators';
class SomeClass {
@throttle({ timeout: 1000 })
handleResize() {
// ...
}
}
```
### `timeout`
Limits method execution time.
```typescript
timeout({ timeout, reason = 'Operation timeout.' }): Decorator
```
- `timeout: number | ((instance) => number)` - The execution timeout in milliseconds.
- `reason: string` - The timeout reason.
#### Example
```typescript
import { cancelable, timeout, onCancel } from 'ts-async-decorators';
class SomeClass {
@timeout({ timeout: 10000, reason = 'Fetch timeout.' })
@cancelable()
fetch() {
const controller = new AbortController();
const { signal } = controller;
onCancel(() => controller.abort());
return fetch('http://example.com', { signal });
}
}
```
## Examples
- [Bluetooth Low-Energy Peripheral Device](https://github.com/dokmic/bluetooth-device).