wow-client

Use Wow clients with a service that implements the Wow command and query protocols. The builders create serializable data locally; creating a query or client does not send HTTP. Generics describe the expected response, not server authorization, schema validation or projection freshness.

Choose an entry

Need	Entry	Check first
Send a write and inspect its stage	CommandClient	URL identity, command body and wait strategy; HTTP success is not business success.
Read current state or snapshots	QueryClientFactory	Choose state-only versus full snapshot result and correct path.
Construct a query without I/O	filter + pagedQuery	filter defaults to filter.matchAll(); listQuery() sends no limit, so the server applies its default list size. Condition queries come from /legacy.
Traverse a changing result set	Cursor queries	Stable sort and cursor rules accepted by your backend.
Compute grouped results	Aggregations	Metric/group expression and server capability; builders do not compute results.
Read an event stream or historical state	Events and history	Event envelopes versus state payloads and stream cleanup.
Handle a failed call or stream	WowError / toWowError	Refused request, error event midway through a stream, or no answer from Wow.

Installation prerequisites

pnpm add @ahoo-wang/fetcher @ahoo-wang/fetcher-decorator @ahoo-wang/fetcher-eventstream @ahoo-wang/wow-client

The package version follows Wow: @ahoo-wang/wow-client x.y.z is released together with Wow x.y.z. The Fetcher peers accept ^5.1 || ^6. The package requires Node >=22.12.0, as does repository development, which also pins pnpm 10.34.5. The command installs every peer the package declares; direct runtime dependencies are installed automatically.

Entry points

Import	Exports
@ahoo-wang/wow-client	Everything but the /legacy API: command and query clients, QueryClientFactory, WowMetadataClient, errors (WowError, toWowError, ErrorCodes), headers and their builders, the stream result extractors, and the whole query DSL.
@ahoo-wang/wow-client/dsl	The query DSL alone: filter, aggregation, sort, projection, pagination, cursorQuery, the query factories and their Filter* types, DeletionState, DynamicDocument, SnapshotMetadataFields, DomainEventStreamMetadataFields.
@ahoo-wang/wow-client/legacy	The deprecated Condition API for Wow 8.10 servers: condition builders, Operator, the Condition-based query types and factories, operator locales. Removed in v10.

/dsl loads no HTTP code — no Fetcher, no decorators, no reflect-metadata, and none of the global stream patches @ahoo-wang/fetcher-eventstream installs — so an application that only builds queries, or sends them through a client of its own, can import it without those side effects. Its exports are the same objects the root entry exports; the peers are still declared by the package. See the /dsl symbol list.

The root entry queries with FilterExpression, which Wow 8.11 and later accept. For a Wow 8.10 server, import the deprecated Condition API, its query types and factories, and the operator locales from @ahoo-wang/wow-client/legacy; the query clients accept both kinds of query. The subpath is removed in v10.

Coming from @ahoo-wang/fetcher-wow? The first @ahoo-wang/wow-client release renames and retypes several APIs — errors, command headers, the cancellation parameter, aggregation builders — and moves the Condition API to /legacy; follow the migration guide.

Core request

Pass a Fetcher configured with your baseURL/authentication. Calling loadUsers issues the request and returns {list,total}; the service must implement the accounts/user Wow snapshot-state paged endpoint. This example does not contact a public service.

import type { Fetcher } from '@ahoo-wang/fetcher';
import { QueryClientFactory, filter, pagedQuery } from '@ahoo-wang/wow-client';

interface User {
  id: string;
  name: string;
}

export async function loadUsers(fetcher: Fetcher) {
  const client = new QueryClientFactory<User>({
    fetcher,
    contextAlias: 'accounts',
    aggregateName: 'user',
  }).createSnapshotQueryClient();
  return client.pagedState(
    pagedQuery({
      filter: filter.matchAll(),
      pagination: { index: 1, size: 20 },
    }),
  );
}

Topics

• Client configuration and metadata
• Commands and wait results
• Snapshot queries
• Filter expressions and legacy conditions
• Projection, sorting and pagination
• Cursor queries
• Aggregation builders
• Events and historical state
• Identity and resource attribution
• Message payloads and state metadata
• Business errors and document utilities
• Legacy operator locales
• Complete symbol index

State and resource ownership · Failure and cancellation boundaries