Decorators

Concurrency Decorators

Define TypeScript concurrency limits, locks, deduplication, throttling, debouncing, and idempotency semantics with AxilJS.

5 min readUpdated DocumentationEdit this page
On this page7

AxilJS concurrency decorators describe how operations behave when multiple executions occur at the same time.

They express concurrency requirements as semantic metadata so a runtime or infrastructure consumer can implement locking, execution limits, request deduplication, throttling, debouncing, and idempotency without embedding those mechanics into business logic.

@tConcurrency

Defines a concurrency limit for an operation.

TypeScript
TS
1import { tConcurrency } from '@axiljs/decorator'
2
3@tConcurrency({ limit: 10 })
4async processOrders() {}

A key scopes the limit (for example per customer), and strategy says what happens when the limit is reached:

TypeScript
TS
1@tConcurrency({
2  limit: 20,
3  key: (orderId: string) => `order:${orderId}`,
4  strategy: 'queue', // 'queue' | 'reject' | 'drop-oldest'
5})
6async processOrder(orderId: string) {}

The consumer can use this metadata to control how many instances of the operation may execute concurrently.

@tLock

Declares that an operation requires a lock before execution.

TypeScript
TS
1import { tLock } from '@axiljs/decorator'
2
3@tLock({ key: 'account:{accountId}' })
4async updateBalance(accountId: string, amount: number) {}

The lock key can represent the resource whose concurrent modification must be coordinated.

For example:

TypeScript
TS
1@tLock({
2  key: 'inventory:{productId}',
3})
4async reserveInventory(productId: string, quantity: number) {}

tLock also accepts ttl (lock lifetime) and wait (how long to wait for the lock), both in milliseconds, and key may be a function of the method arguments.

A lock-aware consumer can resolve the key and coordinate concurrent executions against the same resource.

@tMutex

Declares mutually exclusive execution for an operation or resource.

TypeScript
TS
1import { tMutex } from '@axiljs/decorator'
2
3@tMutex({ key: 'account-update' })
4async updateAccount(accountId: string) {}

Only one execution associated with the mutex can proceed at a time. key is optional; without it the mutex applies to the method itself.

This is useful when concurrent execution could produce inconsistent state or violate an application invariant.

@tDedupe

Declares that equivalent concurrent requests should be deduplicated.

TypeScript
TS
1import { tDedupe } from '@axiljs/decorator'
2
3@tDedupe({
4  key: 'user:{userId}',
5  window: 1000, // optional, ms
6})
7async loadUser(userId: string) {}

When multiple requests resolve to the same deduplication key, a concurrency-aware consumer can coalesce them instead of executing the same operation repeatedly.

This is particularly useful for high-frequency reads, expensive computations, and cache-miss protection.

@tThrottle

Limits how frequently an operation can execute.

TypeScript
TS
1import { tThrottle } from '@axiljs/decorator'
2
3@tThrottle(100, 60_000) // (calls, periodMs)
4async sendNotification() {}

The example allows up to 100 executions within a 60-second period.

Throttling is useful for protecting external APIs, shared resources, and internal services from excessive execution rates.

@tDebounce

Delays execution until activity has stopped for a configured period.

TypeScript
TS
1import { tDebounce } from '@axiljs/decorator'
2
3@tDebounce(500)
4async updateSearchIndex(query: string) {}

A debounce policy is useful when many events can arrive in rapid succession and only the latest execution is relevant.

Typical use cases include search indexing, event aggregation, and rapid state updates.

@tIdempotent

Declares that repeated execution with the same semantic request should produce an equivalent result rather than applying the operation multiple times.

TypeScript
TS
1import { tIdempotent } from '@axiljs/decorator'
2
3@tIdempotent({
4  key: 'payment:{paymentId}',
5  ttl: 86_400_000, // optional, ms
6})
7async processPayment(paymentId: string) {}

Idempotency is particularly important for distributed systems where a request may be retried because of network failures, timeouts, or message redelivery.

The decorator describes the requirement; an infrastructure consumer can implement mechanisms such as idempotency keys or persisted execution records.

Composing Concurrency Semantics

Concurrency decorators can be combined when an operation has multiple execution constraints.

TypeScript
TS
1import {
2  tConcurrency,
3  tLock,
4  tIdempotent,
5  tThrottle,
6} from '@axiljs/decorator'
7
8@tConcurrency({
9  limit: 20,
10})
11@tLock({
12  key: 'payment:{paymentId}',
13})
14@tIdempotent({
15  key: 'payment:{paymentId}',
16})
17@tThrottle(100, 60_000)
18async processPayment(paymentId: string) {
19  return this.paymentService.process(paymentId)
20}

The metadata describes several independent requirements:

  • Limit the number of concurrent executions.
  • Coordinate access to the same payment resource.
  • Prevent duplicate processing.
  • Limit the overall execution rate.

The runtime can interpret each semantic requirement through the appropriate concurrency infrastructure.

Concurrency and Distributed Systems

Concurrency control becomes more important when an operation can execute across multiple application instances.

A local in-memory lock may only coordinate executions inside one process. A distributed consumer may instead implement the same semantic requirement using infrastructure such as a distributed lock, shared state store, or coordination service.

For example:

TypeScript
TS
1@tLock({
2  key: 'inventory:{productId}',
3})
4async reserveInventory(
5  productId: string,
6  quantity: number,
7) {
8  // Business operation
9}

The business operation does not need to know whether the lock is implemented locally, through Redis, or through another coordination mechanism.

The decorator declares the invariant; the infrastructure layer determines how that invariant is enforced.

Concurrency Decorator Reference

DecoratorPurpose
@tConcurrencyLimits concurrent executions
@tLockDeclares a resource-level locking requirement
@tMutexDeclares mutually exclusive execution
@tDedupeCoalesces equivalent concurrent executions
@tThrottleLimits execution frequency
@tDebounceDelays execution until activity settles
@tIdempotentDeclares safe repeated execution semantics

Design Principle

Concurrency decorators should describe execution semantics rather than contain concurrency implementation.

For example:

TypeScript
TS
1@tIdempotent({
2  key: 'payment:{paymentId}',
3})
4async processPayment(paymentId: string) {}

The method remains focused on the payment operation. The decorator communicates an important distributed-system requirement to the infrastructure consumer.

This keeps locking, deduplication, rate control, and idempotency mechanisms outside the business logic while keeping their policies visible at the operation boundary.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY