Designing Typed CallbackParams in TypeScriptTypeScript’s type system is one of its greatest strengths for building reliable, maintainable code — especially when working with asynchronous patterns and callbacks. “CallbackParams” often refers to the argument(s) a callback receives. Designing clear, precise, and reusable types for those parameters reduces bugs, improves editor tooling (autocomplete and refactoring), and makes APIs easier to understand. This article walks through patterns and practical techniques for designing typed CallbackParams in TypeScript, from simple callbacks to advanced, generic, and composable designs.
Why type CallbackParams?
Strongly typing callback parameters provides immediate benefits:
- Better developer experience: autocomplete, jump-to-definition, and inline documentation.
- Safer refactors: TypeScript catches mismatched parameter shapes across call sites.
- Clearer API contracts: Consumers know exactly what to expect and provide.
- Reduced runtime errors: Compile-time checks catch many issues before execution.
Basic callbacks: simple types
Start with the simplest case — a callback that receives a single value:
type CallbackParams = (result: string) => void; function fetchName(cb: CallbackParams) { setTimeout(() => cb("Alice"), 100); } fetchName((name) => { // `name` inferred as string console.log(name.toUpperCase()); }); This is explicit and readable for straightforward scenarios.
Multiple parameters and tuple types
When callbacks accept multiple values, use tuples in the function type:
type CallbackParams = (err: Error | null, data?: string) => void; function fetchData(cb: CallbackParams) { setTimeout(() => cb(null, "payload"), 100); } fetchData((err, data) => { if (err) return; console.log(data?.length); }); Tuple-based typing mirrors Node.js conventions. If the order matters (as it usually does), this approach is clear.
Named parameter objects for clarity
When a callback takes many parameters or some are optional, prefer an object for clarity and future extensibility:
type CallbackParams = (params: { status: number; body?: string; headers?: Record<string,string> }) => void; function handleResponse(cb: CallbackParams) { cb({ status: 200, body: "OK", headers: { "content-type": "text/plain" } }); } handleResponse(({ status, body }) => { console.log(status, body); }); Object parameters allow consumers to use destructuring and ignore unused fields.
Using interfaces and aliases
For complex parameter shapes, define interfaces or type aliases:
interface ResponseParams { status: number; body?: string; headers?: Record<string, string>; } type CallbackParams = (params: ResponseParams) => void; Interfaces make it easy to extend or implement the parameter shape across modules.
Generics: make callbacks reusable
Generics unlock powerful reusability. For APIs that return different shapes, a generic callback captures that variability:
type CallbackParams<T> = (result: T, meta?: Record<string, unknown>) => void; function doWork<T>(cb: CallbackParams<T>, value: T) { cb(value, { timestamp: Date.now() }); } // usage doWork<number>((n) => console.log(n * 2), 21); doWork<{ id: string }>((obj) => console.log(obj.id), { id: "x" }); Generics preserve correct types for each usage while keeping a single callback type definition.
Optional and overloaded callbacks
When callbacks can be omitted, mark them optional:
type CallbackParams<T> = ((value: T) => void) | undefined; function compute<T>(value: T, cb?: (v: T) => void) { if (cb) cb(value); } For APIs with different callback signatures depending on inputs, use function overloads:
function subscribe(event: "data", cb: (payload: string) => void): void; function subscribe(event: "error", cb: (err: Error) => void): void; function subscribe(event: string, cb: (arg: any) => void) { // runtime implementation } Overloads give precise type safety at call sites though implementation uses broader types.
Conditional types for advanced shapes
Conditional types let you compute callback parameter types based on other types:
type PayloadFor<T> = T extends "user" ? { id: string; name: string } : { value: number }; type CallbackParams<T extends string> = (p: PayloadFor<T>) => void; function dispatch<T extends string>(type: T, cb: CallbackParams<T>) { // ... } dispatch("user", (p) => console.log(p.id)); // p inferred as user payload dispatch("score", (p) => console.log(p.value)); // p inferred as score payload This pattern is powerful for event systems or message buses.
Tuple utility: Infer parameters from function types
You may want to extract parameter types from an existing function type. Use TypeScript’s utility types:
type Params<T> = T extends (...args: infer P) => any ? P : never; type MyCb = (a: number, b: string) => void; type MyCbParams = Params<MyCb>; // [number, string] This helps when adapting callback types to other APIs or composing higher-order functions.
Strongly-typed event emitter pattern
Event emitters are a common use-case for typed CallbackParams. Define an event map and use it to type listeners:
interface EventMap { connect: { id: string }; disconnect: { id: string; reason?: string }; message: { from: string; text: string }; } type Listener<K extends keyof EventMap> = (payload: EventMap[K]) => void; class TypedEmitter { private listeners: { [K in keyof EventMap]?: Listener<K>[] } = {}; on<K extends keyof EventMap>(event: K, cb: Listener<K>) { (this.listeners[event] ||= []).push(cb as Listener<any>); } emit<K extends keyof EventMap>(event: K, payload: EventMap[K]) { (this.listeners[event] || []).forEach((cb) => cb(payload)); } } This design gives exhaustive typing for listeners and payloads and prevents mismatched emit/on usages.
Interoperation with Promises: callback-to-promise adapters
To support both callback and promise styles, design types that map callback parameters to resolve/reject signatures:
type NodeStyleCallback<T> = (err: Error | null, res?: T) => void; function promisify<T>(fn: (cb: NodeStyleCallback<T>) => void): Promise<T> { return new Promise((resolve, reject) => { fn((err, res) => (err ? reject(err) : resolve(res))); }); } Type-safe promisify utilities require correct generic wiring to preserve result types.
Error-first vs. result-only callbacks
Decide on a convention: Node-style error-first callbacks or result-only callbacks. Consistency matters:
- Error-first: (err: Error | null, data?: T) => void
- Result-only: (data: T) => void
If using error-first, consider creating a reusable alias:
type NodeCallback<T> = (err: Error | null, data?: T) => void; Documentation, naming, and ergonomics
- Use clear names: ResponseParams, UserResult, NodeCallback, Listener.
- Prefer objects for many fields to support named destructuring.
- Keep callbacks simple; if the parameter shape grows, consider returning a Promise or an observable instead.
- Provide JSDoc comments for complex generic types to aid IDE hints.
Practical examples and patterns
- Event-driven UI: “`ts type UIEventPayload = { x: number; y: number }; type UIEventCb = (payload: UIEventPayload) => void;
function onClick(cb: UIEventCb) { /* … */ }
2. Library API with generics: ```ts type ApiCallback<T> = (data: T, meta?: { fromCache: boolean }) => void; function fetchFromApi<T>(url: string, cb: ApiCallback<T>) { /* ... */ } - Progressive enhancement:
- Start with result-only callbacks.
- Add optional error parameter if operations can fail.
- When complexity increases, introduce types that represent states (loading, success, error).
Testing and type assertions
Use type-level tests (with dtslint or TypeScript’s expect-type packages) to ensure API invariants:
// pseudo type test = Expect<Equal<Params<MyCb>[0], number>>; Compile-time checks prevent regressions when changing CallbackParams.
Summary
Designing typed CallbackParams in TypeScript is about clarity, reusability, and safety. Start simple, prefer object parameters for multi-field payloads, use generics for reusable patterns, and leverage TypeScript’s advanced types (conditional, infer, tuple utilities) for flexible APIs. For event-heavy systems, define an event map and type listeners against it. When in doubt, document and keep the callback surface minimal — move complexity into return types (Promises or streams) where appropriate.
Leave a Reply