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.

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

---

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

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

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

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

Returns

Promise<R>

A Promise resolving to the query 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 for the given type.

---

register()

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

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

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

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