Class: CommandBus

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:37

Dispatches commands to the active handler for each command type.

Remarks

Commands represent write-oriented work such as save, login, reset, or send. Handlers are stacked by type: the newest handler is active until it unregisters. Required execution throws when no handler exists. Optional execution returns undefined for a miss.

Example

import { CommandBus, CommandsPlugin, Container } from "@wirestate/core";

const container = new Container({ plugins: [new CommandsPlugin()] });
const bus = container.get(CommandBus);
const unregister = bus.register<void, User>("SAVE_USER", async (user: User) => {
  // persist the user
});

await bus.executeAsync<void, User>("SAVE_USER", { id: "u1" });

unregister();

Extends

• HandlerStackBus<CommandType>

Constructors

Constructor

new CommandBus(): CommandBus;

Returns

CommandBus

Inherited from

HandlerStackBus<CommandType>.constructor

Methods

createMissingHandlerError()

protected createMissingHandlerError(type: CommandType): WirestateError;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:44

Builds the error thrown when a required command dispatch finds no handler.

Parameters

Parameter	Type	Description
type	CommandType	Command type that failed to resolve.

Returns

WirestateError

The error to throw.

Overrides

HandlerStackBus.createMissingHandlerError

---

dispatch()

protected dispatch<R, P>(type: CommandType, payload?: P): R;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:76

Dispatches to the active handler and returns its result as-is.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token to dispatch.
payload?	P	Payload passed to the handler.

Returns

R

The handler result.

Remarks

If a handler returns a Promise, that Promise is returned untouched.

Throws

WirestateError If no handler is registered.

Inherited from

HandlerStackBus.dispatch

---

dispatchAsync()

protected dispatchAsync<R, P>(type: CommandType, payload?: P): Promise<R>;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:101

Dispatches to the active handler and Promise-wraps the result.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token to dispatch.
payload?	P	Payload passed to the handler.

Returns

Promise<R>

A Promise resolving to the handler result, rejected with a WirestateError when no handler is registered.

Remarks

Sync values are wrapped. Async values are passed through. The method is async, so a missing handler rejects the returned promise rather than throwing at the call site.

Inherited from

HandlerStackBus.dispatchAsync

---

dispatchOptional()

protected dispatchOptional<R, P>(type: CommandType, payload?: P): Optional<R>;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:121

Dispatches to the active handler if one exists, otherwise returns undefined.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token to dispatch.
payload?	P	Payload passed to the handler.

Returns

Optional<R>

The handler result, or undefined when no handler exists.

Inherited from

HandlerStackBus.dispatchOptional

---

dispatchOptionalAsync()

protected dispatchOptionalAsync<R, P>(type: CommandType, payload?: P): Promise<Optional<R>>;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:138

Dispatches to the active handler if one exists and Promise-wraps the result, otherwise resolves to undefined.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token to dispatch.
payload?	P	Payload passed to the handler.

Returns

Promise<Optional<R>>

A Promise resolving to the handler result, or undefined when no handler exists.

Inherited from

HandlerStackBus.dispatchOptionalAsync

---

execute()

Call Signature

execute<R, P, T>(
   type: T, 
   payload: Optional<P>, 
   options: CommandDispatchOptions & {
  optional: true;
}): Optional<R>;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:68

Dispatches an optional command and returns the handler result as-is.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload	Optional<P>	Command payload.
options	CommandDispatchOptions & { optional: true; }	Dispatch options with optional: true.

Returns

Optional<R>

The command result, or undefined when no handler exists.

Remarks

Returns undefined when no handler exists. If a handler returns a Promise, this returns that Promise. Pass a literal { optional: true } so the result narrows to Optional<R>.

Call Signature

execute<R, P, T>(
   type: T, 
   payload?: P, 
   options?: CommandDispatchOptions & {
  optional?: false;
}): R;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:98

Dispatches a required command and returns the handler result as-is.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload?	P	Command payload.
options?	CommandDispatchOptions & { optional?: false; }	Dispatch options.

Returns

R

The command handler result.

Remarks

Throws when no handler is registered. If a handler returns a Promise, this returns that Promise. Use executeAsync when the caller should always receive a Promise.

Throws

WirestateError If no handler is registered.

Example

const saved: SaveResult = commandBus.execute<SaveResult, Draft>("SAVE_DRAFT", draft);

Call Signature

execute<R, P, T>(
   type: T, 
   payload: Optional<P>, 
options: CommandDispatchOptions): Optional<R>;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:118

Dispatches a command whose optionality is decided at runtime.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload	Optional<P>	Command payload.
options	CommandDispatchOptions	Dispatch options with a runtime-decided optional flag.

Returns

Optional<R>

The command result, or undefined when the dispatch is optional and no handler exists.

Throws

WirestateError If the dispatch is required and no handler is registered.

---

executeAsync()

Call Signature

executeAsync<R, P, T>(
   type: T, 
   payload: Optional<P>, 
   options: CommandDispatchOptions & {
  optional: true;
}): Promise<Optional<R>>;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:149

Dispatches an optional command and returns a Promise for the result.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload	Optional<P>	Command payload.
options	CommandDispatchOptions & { optional: true; }	Dispatch options with optional: true.

Returns

Promise<Optional<R>>

A Promise resolving to the command result, or undefined when no handler exists.

Remarks

Synchronous handler results are wrapped. Resolves to undefined when no handler exists. Pass a literal { optional: true } so the result narrows to Optional<R>.

Call Signature

executeAsync<R, P, T>(
   type: T, 
   payload?: P, 
   options?: CommandDispatchOptions & {
  optional?: false;
}): Promise<R>;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:174

Dispatches a required command and returns a Promise for the result.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload?	P	Command payload.
options?	CommandDispatchOptions & { optional?: false; }	Dispatch options.

Returns

Promise<R>

A Promise resolving to the command result, rejected with a WirestateError when no handler is registered.

Remarks

Rejects when no handler is registered - it never throws synchronously, so the miss has to be caught by awaiting or by a .catch, not by a try around the call. Use execute when a missing handler should surface at the call site instead. Synchronous handler results are wrapped. Promises returned by handlers are passed through.

Call Signature

executeAsync<R, P, T>(
   type: T, 
   payload: Optional<P>, 
options: CommandDispatchOptions): Promise<Optional<R>>;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:198

Dispatches a command whose optionality is decided at runtime and returns a Promise.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command token.
payload	Optional<P>	Command payload.
options	CommandDispatchOptions	Dispatch options with a runtime-decided optional flag.

Returns

Promise<Optional<R>>

A Promise resolving to the command result, or undefined when the dispatch is optional and no handler exists, rejected with a WirestateError when it is required and no handler exists.

Remarks

Selected when optional is a plain boolean, as with an options object built elsewhere. The result is Optional<R> because the call may resolve to undefined for a miss. Pass a literal { optional: true } or omit the option to select a narrower overload.

---

hasHandler()

hasHandler(type: CommandType): boolean;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:45

Checks if at least one handler is registered for the given type.

Parameters

Parameter	Type	Description
type	CommandType	Token to inspect.

Returns

boolean

true if a handler is available, false otherwise.

Inherited from

HandlerStackBus.hasHandler

---

register()

register<R, P, T>(type: T, handler: CommandHandler<R, P, T>): CommandUnregister;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:235

Registers a command handler.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command type.
handler	CommandHandler<R, P, T>	Function to execute when the command is dispatched.

Returns

CommandUnregister

A function to unregister the handler.

Remarks

Registering another handler for the same type shadows the previous one. Unregistering the newest restores it.

Example

const unregister: CommandUnregister = commandBus.register("LOG_MESSAGE", (message: string) => {
  console.log(message);
});

---

registerHandler()

protected registerHandler<R, P>(type: CommandType, handler: (payload: P) => MaybePromise<R>): () => void;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:157

Pushes a handler onto the stack for a type.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token the handler answers.
handler	(payload: P) => MaybePromise<R>	Handler function.

Returns

A callback that removes this exact registration.

() => void

Remarks

Multiple handlers for one type form a stack. The newest handler is active.

Inherited from

HandlerStackBus.registerHandler

---

unregister()

unregister<R, P, T>(type: T, handler: CommandHandler<R, P, T>): void;

Defined in: src/wirestate-core/plugin/commands/command-bus.ts:255

Removes a previously registered command handler.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends CommandType	CommandType	Command type.

Parameters

Parameter	Type	Description
type	T	Command type.
handler	CommandHandler<R, P, T>	The handler function instance to remove.

Returns

void

Remarks

If the handler was not registered for the given type, this operation does nothing.

---

unregisterHandler()

protected unregisterHandler<R, P>(type: CommandType, handler: (payload: P) => MaybePromise<R>): void;

Defined in: src/wirestate-core/plugin/bus/handler-stack-bus.ts:184

Removes the newest registration whose handler matches by reference.

Type Parameters

Type Parameter	Description
R	Type of the handler result.
P	Type of the payload.

Parameters

Parameter	Type	Description
type	CommandType	Token whose stack to update.
handler	(payload: P) => MaybePromise<R>	The handler function instance to remove.

Returns

void

Remarks

If the handler was not registered for the given type, this does nothing.

Inherited from

HandlerStackBus.unregisterHandler