Class: QueryBus

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:33

Dispatches queries to the active handler for each query type.

Remarks

Queries represent read-oriented work such as current user, labels, or cached state. Handlers are stacked by type: the newest handler is active until it unregisters. Required queries throw when no handler exists. Optional queries return undefined for a miss.

Example

import { Container, QueriesPlugin, QueryBus } from "@wirestate/core";

const container = new Container({ plugins: [new QueriesPlugin()] });
const bus = container.get(QueryBus);
const unregister = bus.register("CURRENT_USER", () => ({ id: "u1" }));

const user = bus.query<{ id: string }>("CURRENT_USER");
unregister();

Extends

• HandlerStackBus<QueryType>

Constructors

Constructor

new QueryBus(): QueryBus;

Returns

QueryBus

Inherited from

HandlerStackBus<QueryType>.constructor

Methods

createMissingHandlerError()

protected createMissingHandlerError(type: QueryType): WirestateError;

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:40

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

Parameters

Parameter	Type	Description
type	QueryType	Query type that failed to resolve.

Returns

WirestateError

The error to throw.

Overrides

HandlerStackBus.createMissingHandlerError

---

dispatch()

protected dispatch<R, P>(type: QueryType, 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	QueryType	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: QueryType, 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	QueryType	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: QueryType, 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	QueryType	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: QueryType, 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	QueryType	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

---

hasHandler()

hasHandler(type: QueryType): 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	QueryType	Token to inspect.

Returns

boolean

true if a handler is available, false otherwise.

Inherited from

HandlerStackBus.hasHandler

---

query()

Call Signature

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

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:64

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

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query type.
payload	Optional<P>	Optional payload for the handler.
options	QueryDispatchOptions & { optional: true; }	Dispatch options with optional: true.

Returns

Optional<R>

The query 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

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

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:94

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

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query type.
payload?	P	Optional payload for the handler.
options?	QueryDispatchOptions & { optional?: false; }	Dispatch options.

Returns

R

The result of the query execution.

Remarks

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

Throws

WirestateError If no handler is registered for the given type.

Example

const user: User = queryBus.query<User, string>("FIND_USER", "user-id-123");

Call Signature

query<R, P, T>(
   type: T, 
   payload: Optional<P>, 
options: QueryDispatchOptions): Optional<R>;

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:114

Dispatches a query whose optionality is decided at runtime.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

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

Returns

Optional<R>

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

Throws

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

---

queryAsync()

Call Signature

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

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:145

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

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query type.
payload	Optional<P>	Optional payload for the handler.
options	QueryDispatchOptions & { optional: true; }	Dispatch options with optional: true.

Returns

Promise<Optional<R>>

A Promise resolving to the query 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

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

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:170

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

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query type.
payload?	P	Optional payload for the handler.
options?	QueryDispatchOptions & { optional?: false; }	Dispatch options.

Returns

Promise<R>

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

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 query 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

queryAsync<R, P, T>(
   type: T, 
   payload: Optional<P>, 
options: QueryDispatchOptions): Promise<Optional<R>>;

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:189

Dispatches a query 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 QueryType	QueryType	Query type.

Parameters

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

Returns

Promise<Optional<R>>

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

---

register()

register<R, P, T>(type: T, handler: QueryHandler<R, P, T>): QueryUnregister;

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:224

Registers a query handler.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query token.
handler	QueryHandler<R, P, T>	Query handler.

Returns

QueryUnregister

Function that unregisters this handler.

Remarks

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

Example

const unregister: QueryUnregister = queryBus.register("GET_NOW", () => Date.now());

---

registerHandler()

protected registerHandler<R, P>(type: QueryType, 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	QueryType	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: QueryHandler<R, P, T>): void;

Defined in: src/wirestate-core/plugin/queries/query-bus.ts:244

Removes a previously registered query handler.

Type Parameters

Type Parameter	Default type	Description
R	unknown	Result type.
P	unknown	Payload type.
T extends QueryType	QueryType	Query type.

Parameters

Parameter	Type	Description
type	T	Query type.
handler	QueryHandler<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: QueryType, 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	QueryType	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