Typing Command Pattern Implementations in TypeScript
Introduction
The Command Pattern is a behavioral design pattern that encapsulates a request as an object, allowing you to parameterize clients with queues, logs, undo/redo operations, and more. In TypeScript, the pattern becomes more powerful: types help ensure commands are used correctly, payloads are validated, and composed systems remain maintainable. For intermediate developers, adding robust typing to the Command Pattern often raises questions: How do I type a generic command interface? How can I ensure payload types align with handlers? How to support undo, serialization, or middleware without losing type-safety?
In this tutorial you'll learn how to model the Command Pattern in TypeScript end-to-end. We'll cover typed command interfaces and implementations, a typed command bus, middlewares, undo/redo mechanics, serialization, and advanced strategies like variadic command arguments or async commands. We include practical code examples, step-by-step instructions, and safety checks using TypeScript's type system. By the end, you'll be able to build a production-ready typed command system that scales across services and UIs.
This guide also links to related TypeScript topics that pair well with command implementations, such as typed factory patterns, typed caches, higher-order functions, and assertion functions. These references provide deeper dives on adjacent concerns you'll likely encounter while building real-world command systems.
Background & Context
The Command Pattern decouples the invoker of an operation from the object that performs it. It's useful in CQRS, event-sourcing, task scheduling, GUI actions, and any system where requests need to be queued, retried, or composed. TypeScript adds compile-time guarantees: you can ensure commands carry the right payload, handlers accept matching types, and composition doesn't break contracts.
Typed commands reduce runtime errors and improve maintainability, especially in large codebases where commands cross module boundaries. We'll treat commands as value objects with a discriminant (type or name), a payload, and optional metadata. We'll also explore typed command buses, middlewares, and patterns for undo/redo and serialization.
Key design goals for this tutorial:
- Maintain strong typing across commands and handlers
- Support async commands and middleware pipelines
- Allow composition and serialization without losing types
- Provide patterns that integrate with other typed utilities
Key Takeaways
- How to define strongly typed command interfaces and discriminated unions
- Building a typed CommandBus with compile-time safety
- Implementing middleware and higher-order handler composition without losing types
- Strategies for undo/redo and serialization with typed commands
- Integration tips with caches, memoization, and assertion patterns
Prerequisites & Setup
- Knowledge of TypeScript basics: interfaces, generics, conditional types, and mapped types
- Node.js + TypeScript environment (tsc >= 4.x preferred for newer typing features)
- Optional: familiarity with design patterns like Factory and Observer (see linked resources below)
To follow along, create a new project and initialize TypeScript:
mkdir typed-commands && cd typed-commands npm init -y npm install typescript --save-dev npx tsc --init
Create a src/ folder and save examples as .ts files. We keep examples simple and focused on types; adapt them to your runtime framework as needed.
Main Tutorial Sections
1) Defining a Strongly Typed Command Interface
Start by modeling a minimal command. Use a discriminant plus payload and optional meta to allow pattern matching.
type CommandType = string
interface Command<T extends CommandType, P = undefined> {
readonly type: T
readonly payload: P
readonly meta?: Record<string, unknown>
}
// Example
type CreateUserCmd = Command<'CREATE_USER', { name: string; email: string }>
const cmd: CreateUserCmd = { type: 'CREATE_USER', payload: { name: 'Ana', email: 'a@x' } }This basic shape enables discriminated unions and compiler-assisted narrowing in handler logic.
(See also typed factory patterns for constructing commands safely: Typing Factory Pattern Implementations in TypeScript).
2) Modeling Command Handlers with Generics
Handlers should accept only the payloads that correspond to their command type. Use generic interfaces to tie a handler to its command type.
interface Handler<C extends Command<any, any>, R = void> {
(command: C): Promise<R> | R
}
const createUserHandler: Handler<CreateUserCmd, { id: string }> = async cmd => {
// payload typed as { name: string; email: string }
return { id: 'user_1' }
}This ensures handlers can't be accidentally assigned to incompatible command types.
3) Building a Typed Command Registry / Bus
A command bus routes commands to handlers. For compile-time safety, represent the supported commands as a mapping from type to payload and result types.
type CommandMap = {
CREATE_USER: { payload: { name: string; email: string }; result: { id: string } }
DELETE_USER: { payload: { id: string }; result: boolean }
}
type CommandOf<K extends keyof CommandMap> = Command<K, CommandMap[K]['payload']>
class CommandBus<M extends Record<string, { payload: any; result: any }>> {
private handlers = new Map<string, Handler<any, any>>()
register<K extends keyof M>(type: K, handler: Handler<Command<K, M[K]['payload']>, M[K]['result']>) {
this.handlers.set(String(type), handler)
}
async execute<K extends keyof M>(cmd: Command<K, M[K]['payload']>): Promise<M[K]['result']> {
const h = this.handlers.get(cmd.type as string) as Handler<typeof cmd, M[K]['result']> | undefined
if (!h) throw new Error('Handler not found')
return await h(cmd)
}
}
const bus = new CommandBus<CommandMap>()
bus.register('CREATE_USER', createUserHandler)This design preserves payload and result types through the bus boundary, reducing casting and runtime checks.
4) Using Discriminated Unions for Flexible Command Sets
For dynamic scenarios, define a union of commands so switch statements and exhaustive checks are typed.
type Commands =
| Command<'CREATE_USER', { name: string; email: string }>
| Command<'DELETE_USER', { id: string }>
function handle(cmd: Commands) {
switch (cmd.type) {
case 'CREATE_USER':
// cmd.payload typed correctly
break
case 'DELETE_USER':
break
default:
const _exhaustive: never = cmd
return _exhaustive
}
}Discriminated unions pair nicely with pattern-based dispatchers and can be used when the set of commands is known ahead of time.
(If you're manipulating arrays of commands or filtering them, explore type predicates for safer filters: Using Type Predicates for Filtering Arrays in TypeScript).
5) Middleware: Composable Handler Pipelines
Middleware is a higher-order handler wrapper that can add logging, validation, retries, or caching. Use typed higher-order functions to preserve types across the pipeline.
type Middleware<M, K extends keyof M> = (
next: Handler<Command<K, M[K]['payload']>, M[K]['result']>
) => Handler<Command<K, M[K]['payload']>, M[K]['result']>
function logger<M, K extends keyof M>() : Middleware<M, K> {
return next => async cmd => {
console.log('dispatch', cmd.type)
const res = await next(cmd)
console.log('result', res)
return res
}
}
// apply by wrapping when registering on the busMiddleware composition leverages patterns from typed higher-order functions; see advanced typing strategies in our guide: Typing Higher-Order Functions in TypeScript — Advanced Scenarios.
6) Async Commands, Queues, and Typed Iterables
Commands often need async execution and batching. Use async handlers and typed async iterables for consumer-based architectures.
async function processQueue<T extends Command<any, any>>(queue: AsyncIterable<T>, bus: CommandBus<any>) {
for await (const cmd of queue) {
await bus.execute(cmd as any)
}
}If you stream commands from a source, typed async iterables ensure consumers process the right shapes. If you need a primer on typing async iterables and iterators, review: Typing Async Iterators and Async Iterables in TypeScript — Practical Guide and Typing Iterators and Iterables in TypeScript.
7) Undo/Redo: Capturing Reverse Operations Safely
Add an optional inverse handler in your command schema for undo. Type both forward and inverse results to ensure safety.
type CommandSchema<P, R, U = void> = { payload: P; result: R; undoResult?: U }
type AppCommands = {
CREATE_USER: CommandSchema<{ name: string }, { id: string }, { success: boolean }>
}
// store history as typed entries
interface HistoryEntry<K extends keyof AppCommands> {
type: K
payload: AppCommands[K]['payload']
undo?: (entry: HistoryEntry<K>) => Promise<AppCommands[K]['undoResult']>
}An undo stack keeps typed entries and calls the undo handler defined when the command was executed. This reduces runtime surprises when rolling back operations.
8) Serialization and Transport of Commands
Command objects are often serialized for transport. Use explicit DTO shapes and avoid sending functions or class instances. Create small DTO types for serialization.
type SerializableCommand = { type: string; payload: unknown; meta?: Record<string, unknown> }
function serialize(cmd: Command<any, any>): string { return JSON.stringify(cmd as SerializableCommand) }
function deserialize<T extends SerializableCommand>(s: string): T { return JSON.parse(s) as T }Keep a registry to convert deserialized payloads back into typed commands at the application boundary, using assertion functions to validate shapes. See: Using Assertion Functions in TypeScript (TS 3.7+).
9) Advanced Payload Patterns: Tuples, Variadic Args, and 'this'
Some commands act like function calls with variadic parameters. To type these, model payloads as tuples and leverage variadic/labelled tuple typing.
type FuncCmd<T extends any[], R> = Command<'CALL', { args: T; fnId: string }>
// an executor that preserves tuple types
function callExecutor<T extends any[], R>(c: Command<'CALL', { args: T; fnId: string }>, fn: (...args: T) => R): R {
return fn(...c.payload.args)
}If your handlers need to preserve or modify this, study patterns for typing functions that modify this: Typing Functions That Modify this (ThisParameterType, OmitThisParameter).
10) Composition with Other Typed Patterns
Commands often interact with factories, caches, memoization, and debouncing. For example, if a command triggers expensive computations, combine it with a typed cache or memoizer to reduce repeated work. See: Typing Cache Mechanisms: A Practical TypeScript Guide and Typing Memoization Functions in TypeScript. If commands relate to GUI actions, debouncing or throttling handlers can help: Typing Debounce and Throttling Functions in TypeScript.
Advanced Techniques
When pushing types to their limits, consider these expert approaches:
- Use mapped types to derive handler maps from a central command schema so adding a new command updates all derived types automatically.
- Leverage branded types or nominal typing for IDs (e.g., UserId) to prevent accidental string reassignments.
- For large systems, split command registration into feature modules and compose the global CommandMap via intersection types or utility merge functions.
- Use runtime validation (zod, io-ts) with assertion helpers to convert deserialized payloads into typed values. This combines runtime safety and compile-time typing.
Performance tip: minimize the amount of runtime metadata stored on commands (keep payloads lean) to reduce serialization cost and GC pressure. When using middleware chains, avoid creating heavy closures per call in hot paths; reuse composed pipelines when possible.
(For patterns that complement composition such as builder patterns, see: Typing Builder Pattern Implementations in TypeScript).
Best Practices & Common Pitfalls
Dos:
- Do keep command payloads serializable and free of functions or class instances.
- Do prefer discriminated unions or a central CommandMap to gain exhaustive check benefits.
- Do type the CommandBus generically so handlers and callers get compile-time feedback.
- Do use assertion functions on deserialization boundaries to prevent malformed input from propagating.
Don'ts:
- Don't rely on ad-hoc stringly-typed commands across boundaries without a registry — it causes brittle code.
- Don't mutate command payloads in place; treat them as immutable value objects for predictable undo/redo.
- Avoid over-engineering micro-typing for small apps; heavy typing pays off more in large teams and codebases.
Common troubleshooting:
- If TypeScript refuses to infer a handler type, check that your generics are not widened to any; use explicit generic parameters when needed.
- When serializing, check for circular references or non-serializable fields. Keep payloads plain objects and primitives.
Real-World Applications
- CQRS & Event Sourcing: Commands as intent messages that generate events and update read models.
- UI Command Patterns: Button clicks or menu actions as commands with undo stacks for user-facing apps.
- Microservices: Commands serialized over message buses (e.g., Kafka, RabbitMQ) with typed DTOs and validators.
- Task Runners: Scheduling and retry strategies for heavy background jobs executed through a typed CommandBus.
Integrate typed command systems with caches and observers to build resilient apps; for example, use typed observers to watch command outcomes (see: Typing Observer Pattern Implementations in TypeScript).
Conclusion & Next Steps
Typed Command Pattern implementations unlock robust, maintainable, and scalable designs for many application domains. Start by modeling a central command schema, implement a typed CommandBus, and expand with middleware, undo stacks, and serialization boundaries. To deepen your skills, explore adjacent topics: typed factories, builders, and higher-order functions — the links throughout this guide will help.
Next steps: implement a small feature using the patterns here, add runtime validation at the transport boundary, and iterate on your command schema as your domain evolves.
Enhanced FAQ
Q1: How should I choose between discriminated unions and a central CommandMap? A1: Use discriminated unions when the full set of commands is known and relatively static — unions give you exhaustive checks. Choose a central CommandMap when you need a single source of truth that can be extended and used to generate derived types (handlers, DTOs). CommandMap is more modular and preferable for larger systems where commands are added across modules.
Q2: How can I ensure commands remain serializable across services? A2: Keep payloads to primitives and plain POJOs. Avoid functions, class instances, Symbols, or BigInt without a well-defined serializer. Introduce small DTO types for transport and perform validation on deserialize using assertion functions or schema validators. Our article on assertion functions provides patterns for this: Using Assertion Functions in TypeScript (TS 3.7+).
Q3: Are constructors or factories better for creating commands? A3: Factories provide better flexibility for validation or generation of defaults; constructors (classes) are convenient but may carry methods that make serialization harder. Prefer lightweight factory functions when you need pure DTOs that serialize well. If using builders for complex commands, typed builder patterns can help: Typing Builder Pattern Implementations in TypeScript.
Q4: How do I type middleware that works for all command types? A4: Define middleware as a generic higher-order function parameterized by the CommandMap and the command key. Use the same generic constraints in both the middleware signature and when applying it to handlers so the payload/result types are preserved. See the middleware examples above and the advanced HOF typing guide: Typing Higher-Order Functions in TypeScript — Advanced Scenarios.
Q5: How do I implement undo safely for async commands? A5: Store a typed history entry with enough context to perform the inverse operation, including payload and any returned identifiers. The undo handler should be typed to accept the history entry and return a typed undo result. For async operations, ensure the undo handler is idempotent when possible and add retries with exponential backoff in middleware. Keep history entries immutable and small.
Q6: Can I use variadic tuples for commands that map to function calls?
A6: Yes. Model the payload as a tuple of args and type your executor to accept the same tuple via spread. This preserves tuple types and allows safe calling of the underlying function. If your function needs to preserve this, consult patterns for typing functions that modify this: Typing Functions That Modify this (ThisParameterType, OmitThisParameter).
Q7: How should I combine commands with caches and memoization? A7: Commands that are idempotent or read-only are good candidates for caching or memoization. Use typed cache wrappers to ensure payload->result mapping is maintained. See guides on cache mechanisms and memoization for typed examples: Typing Cache Mechanisms: A Practical TypeScript Guide and Typing Memoization Functions in TypeScript.
Q8: What patterns help when commands are evolved over time (schema changes)? A8: Version your command types via a version field or namespacing (e.g., 'user.CREATE_v2'). Maintain deserializers that can handle multiple versions and migrate payloads to the latest shape on read. Use feature flags to roll out new handlers, and prefer additive changes where possible. Keep migrations explicit and tested.
Q9: How do I debug type errors when registering handlers in a big app? A9: Extract the CommandMap into a central declaration and make sure modules import the shared type. Use explicit generic parameters on register/execute calls when inference fails. Create small helper types that narrow the generic space (e.g., RegisterHandler<M, K>) so the TS compiler surfaces a focused error. Also check for any widening to any caused by const assertions or implicit any in payloads.
Q10: Should Command objects be classes or plain objects? A10: Prefer plain objects (POJOs) to keep serialization and equality simple. Use classes only if you need methods or behavior on the command itself, and ensure you provide a proper serialization path. POJOs tend to be more interoperable and testable across services.
For additional reading on surrounding TypeScript topics mentioned in this article (builders, observers, factories, memoization, debounce/throttle, HOFs, etc.), see the referenced tutorials throughout the guide to deepen your typing toolkit. For example, when designing handler composition or middleware you may find our work on higher-order functions and typed iterables particularly useful.
Thanks for reading — implement a small typed command system today and iterate toward the shape that fits your domain and team.