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.

Remarks

Sync values are wrapped. Async values are passed through.

Throws

WirestateError If no handler is registered.

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): 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	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);

---

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:129

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): Promise<R>;

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

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	Dispatch options.

Returns

Promise<R>

A Promise resolving to the command result.

Remarks

Throws when no handler is registered. Synchronous handler results are wrapped. Promises returned by handlers are passed through.

Throws

WirestateError If no handler is registered.

---

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:190

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:210

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