@thingts/execution

Async-friendly debounce, throttle, and serialize function wrappers for modern TypeScript (5.2+)

All are designed for async/await and can be used in either functional or decorator form.

---

Why?

Many existing libraries contain debounce, throttle, and sequencing utilities, but most have legacy designs from the pre-async, pre-TypeScript era.

This package provides modern, ergonomic versions of these utilities that are fully type-safe, designed to work seamlessly with async functions, and support method decorator syntax.

✨ Features

• Fully type-safe — preserves parameter and return types
• Works seamlessly with async functions and Promises
• Supports method decorator syntax (@debounce, @throttle, @serialize)
• Lightweight and dependency-free

---

🚀 Installation

npm install @thingts/execution

---

🧩 Overview

Utility	Purpose	Typical Use
debounce	Coalesce bursts of calls into one execution	UI events
throttle	Limit execution rate to once per interval.	Scroll, resize, polling, APIs
serialize	Queue async calls to run one at a time.	network or file I/O, HTML media controllers

Each utility wraps the original function to provide a new function that enforces the desired behavior, returning a Promise that resolves (or rejects) with the eventual result of the original function.

For debounce and throttle wrappers, multiple calls that yield a single execution all return the exact same promise. Async functions whose executions last longer than the debounce/throttle window are handled naturally, with options to control the subtleties for different use cases.

All utilities can be used in two ways:

1. Functional form: Call the utility with options to get a wrapper factory, which you then call with your target function to get the final wrapped function.

2. Method decorator form: Use the utility as a decorator on a class method definition. When calling the resulting wrapped method on separate instances, they are considered to be independent (i.e., each instance has its own timing/queue state).

---

🔧 Usage Examples

These are a quick overview of how to use the functions. For complete docs and options, see the API Reference.

Debounce

import { debounce } from '@thingts/execution'

// functional form
const save = debounce(200)(async () => {
  console.log('Saving...')
})

// calls in quick succession merge into one
save()
save()
save() // only one save() executes

// decorator form
class Editor {
  @debounce(300)
  async autoSave(): Promise<void> {
    console.log('Auto-saving document...')
  }
}

See the debounce API reference for full options details.

---

Throttle

import { throttle } from '@thingts/execution'

// functional form
const tick = throttle(1000)(async () => {
  console.log('Tick')
})

// called every 250ms → but runs once per second
setInterval(tick, 250)

// decorator form
class Player {
  @throttle(500)
  async move(direction: string): Promise<void> {
    console.log('Moving', direction)
  }
}

See the throttle API reference for full options details.

---

Serialize

import { serialize } from '@thingts/execution'

// individual function
const fetchData = serialize()(async (url: string) => {
  console.log('Fetching', url)
})
await Promise.all([
  fetchData('https://api.example.com/data1'),
  fetchData('https://api.example.com/data2'),
  fetchData('https://api.example.com/data3'),
]) // calls are queued and run one after another

// shared serialization queue via group key
const read  = serialize({ group: 'fileIO' })(async () => readFile('data.json'))
const write = serialize({ group: 'fileIO' })(async () => writeFile('data.json', '...'))
await Promise.all([read(), write()]) // ...: write waits until read completes

// decorator form
class AudioEngine {
  @serialize()
  async playSample(id: string): Promise<void> {
    console.log('Playing', id)
  }
}

See the serialize API reference for full options details.

Contributing

Contributions are welcome!

As usual: fork the repo, create a feature branch, and open a pull request, with tests and docs for any new functionality. Thanks!