@ahoo-wang/fetcher-wow 3.17.0 → 3.18.0

package/README.md

@@ -23,7 +23,8 @@ working with the Wow CQRS/DDD framework.
   updates
 - **🚀 Command Client**: High-level client for sending commands to Wow services with both synchronous and streaming
   responses
-- **🔍 Powerful Query DSL**: Rich query condition builder with comprehensive operator support for complex querying
+- **🔍 Powerful Query DSL**: Typed `FilterExpression` builders with comprehensive operator support
+- **📊 Snapshot Aggregation**: Group and aggregate snapshot data with typed queries
 - **🔍 Query Clients**: Specialized clients for querying snapshot and event stream data with comprehensive query
   operations:
   - Counting resources
@@ -68,6 +69,7 @@ either synchronously or as a stream of events.
 import {
   Fetcher,
   FetchExchange,
+  HttpMethod,
   RequestInterceptor,
   URL_RESOLVE_INTERCEPTOR_ORDER,
 } from '@ahoo-wang/fetcher';
@@ -75,8 +77,7 @@ import '@ahoo-wang/fetcher-eventstream';
 import {
   CommandClient,
   CommandRequest,
-  HttpMethod,
-  CommandHttpHeaders,
+  CommandHeaders,
   CommandStage,
 } from '@ahoo-wang/fetcher-wow';
 import { idGenerator } from '@ahoo-wang/fetcher-cosec';
@@ -126,7 +127,7 @@ type AddCartItemCommand = CommandRequest<AddCartItem>;
 const addCartItemCommand: AddCartItemCommand = {
   method: HttpMethod.POST,
   headers: {
-    [CommandHttpHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+    [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
   },
   body: {
     productId: 'productId',
@@ -159,9 +160,44 @@ for await (const commandResultEvent of commandResultStream) {
 
 ### Query Module
 
-#### Condition Builder
+#### Filter Expression Builder
 
-Comprehensive query condition builder with operator support:
+Wow 8.11+ queries use `FilterExpression`:
+
+```typescript
+import {
+  DeletionState,
+  filter,
+  SearchMode,
+  TimeUnit,
+} from '@ahoo-wang/fetcher-wow';
+
+const expression = filter.and([
+  filter.deletion(DeletionState.ACTIVE),
+  filter.eq('state.status', 'PAID'),
+  filter.elementMatch('state.items', filter.gt('quantity', 0)),
+  filter.search('event sourcing', {
+    mode: SearchMode.PHRASE,
+    fields: ['state.title', 'state.description'],
+  }),
+  filter.yesterday('state.createdAt', {
+    zoneId: 'Asia/Shanghai',
+    timeUnit: TimeUnit.MILLISECONDS,
+  }),
+]);
+```
+
+Builders are grouped under `filter`: `matchAll`, `matchNone`, `and`, `or`,
+`nor`, comparisons, string/collection predicates, presence checks,
+`elementMatch`, `search`, deletion scope, and relative-time filters.
+`and`, `or`, `nor`, `ids`, `aggregateIds`, `isIn`, `notIn`, and
+`containsAll` accept one non-empty `readonly` array and throw `TypeError` for
+an empty array.
+
+#### Condition Builder (Deprecated)
+
+The legacy Condition API remains available for compatibility with older Wow
+servers. New code should use `FilterExpression` and `filter.*`.
 
 ```typescript
 import {
@@ -246,7 +282,7 @@ const arrayConditions = [
 // Date conditions
 const dateConditions = [
   today('createdAt'),
-  beforeToday('lastLogin', 7), // 7 days before today (i.e., within last 7 days)
+  beforeToday('lastLogin', '09:30'),
   tomorrow('scheduledDate'),
   thisWeek('updatedAt'),
   nextWeek('startDate'),
@@ -282,7 +318,7 @@ const rawCondition = raw({ $text: { $search: 'keywords' } });
 | String       | `contains`, `startsWith`, `endsWith`, `match`                                                                                                   |
 | Collection   | `isIn`, `notIn`, `allIn`, `elemMatch`                                                                                                           |
 | Null/Boolean | `isNull`, `notNull`, `isTrue`, `isFalse`, `exists`                                                                                              |
-| Date         | `today`, `beforeToday(days)`, `tomorrow`, `thisWeek`, `nextWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `recentDays(days)`, `earlierDays(days)` |
+| Date         | `today`, `beforeToday(time)`, `tomorrow`, `thisWeek`, `nextWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `recentDays(days)`, `earlierDays(days)` |
 | ID           | `id`, `ids`, `aggregateId`, `aggregateIds`, `tenantId`, `ownerId`                                                                               |
 | State        | `active`, `all`, `deleted`                                                                                                                      |
 | Special      | `raw` (for advanced database-specific queries)                                                                                                  |
@@ -300,20 +336,25 @@ import {
 } from '@ahoo-wang/fetcher';
 import '@ahoo-wang/fetcher-eventstream';
 import {
+  aggregation,
   SnapshotQueryClient,
-  all,
-  ListQuery,
-  PagedQuery,
-  SingleQuery,
+  filter,
+  FilterListQuery,
+  FilterPagedQuery,
+  FilterSingleQuery,
+  type AggregationQuery,
+  Identifier,
 } from '@ahoo-wang/fetcher-wow';
 import { idGenerator } from '@ahoo-wang/fetcher-cosec';
 
 interface CartItem {
   productId: string;
+  price: number;
   quantity: number;
 }
 
 interface CartState extends Identifier {
+  status: string;
   items: CartItem[];
 }
 
@@ -346,11 +387,11 @@ const cartSnapshotQueryClient = new SnapshotQueryClient<CartState>({
 });
 
 // Count snapshots
-const count = await cartSnapshotQueryClient.count(all());
+const count = await cartSnapshotQueryClient.count(filter.matchAll());
 
 // List snapshots
-const listQuery: ListQuery = {
-  condition: all(),
+const listQuery: FilterListQuery = {
+  filter: filter.matchAll(),
 };
 const list = await cartSnapshotQueryClient.list(listQuery);
 
@@ -372,8 +413,8 @@ for await (const event of stateStream) {
 }
 
 // Paged snapshots
-const pagedQuery: PagedQuery = {
-  condition: all(),
+const pagedQuery: FilterPagedQuery = {
+  filter: filter.matchAll(),
 };
 const paged = await cartSnapshotQueryClient.paged(pagedQuery);
 
@@ -381,31 +422,77 @@ const paged = await cartSnapshotQueryClient.paged(pagedQuery);
 const pagedState = await cartSnapshotQueryClient.pagedState(pagedQuery);
 
 // Single snapshot
-const singleQuery: SingleQuery = {
-  condition: all(),
+const singleQuery: FilterSingleQuery = {
+  filter: filter.matchAll(),
 };
 const single = await cartSnapshotQueryClient.single(singleQuery);
 
 // Single snapshot state
 const singleState = await cartSnapshotQueryClient.singleState(singleQuery);
+
+type CartFields = 'state.status' | 'state.items';
+type ItemFields = 'productId' | 'price' | 'quantity';
+
+type ProductSummary = {
+  product: string;
+  representativeProduct: string | null;
+  itemCount: number;
+  revenue: number;
+};
+
+const revenue = aggregation.multiply(
+  aggregation.field<ItemFields>('price'),
+  aggregation.field<ItemFields>('quantity'),
+);
+
+const aggregationQuery: AggregationQuery<CartFields, ItemFields> = {
+  filter: filter.eq('state.status', 'COMPLETED'),
+  elements: [aggregation.element('state.items', filter.gt('quantity', 0))],
+  groupBy: [aggregation.terms('productId', 'product')],
+  metrics: [
+    aggregation.any('productId', 'representativeProduct'),
+    aggregation.count('itemCount'),
+    aggregation.sum(revenue, 'revenue'),
+  ],
+};
+
+const summaries =
+  await cartSnapshotQueryClient.aggregate<ProductSummary>(aggregationQuery);
+const summaryStream =
+  await cartSnapshotQueryClient.aggregateStream<ProductSummary>(
+    aggregationQuery,
+  );
+for await (const event of summaryStream) {
+  console.log(event.data);
+}
 ```
 
+`aggregation.any(field, alias)` adds a metric, not another group. It returns one
+non-null scalar from the current group, or `null` when no value exists. The
+selected value is intentionally unspecified and may differ across backends or
+executions; use it only when every candidate is interchangeable. Its field is
+relative to the innermost element, and Wow rejects collection or non-terms-capable
+fields at runtime. Sorting by an `ANY` alias is an expensive metric sort.
+
 ##### Methods
 
-- `count(condition: Condition): Promise<number>` - Counts the number of snapshots that match the given condition.
-- `list(listQuery: ListQuery): Promise<Partial<MaterializedSnapshot<S>>[]>` - Retrieves a list of materialized
+- `count(filter: FilterExpression): Promise<number>` - Counts snapshots matching the filter expression.
+- `list(listQuery: FilterListQuery): Promise<Partial<MaterializedSnapshot<S>>[]>` - Retrieves a list of materialized
   snapshots.
-- `listStream(listQuery: ListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<MaterializedSnapshot<S>>>>>` -
+- `listStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<MaterializedSnapshot<S>>>>>` -
   Retrieves a stream of materialized snapshots as Server-Sent Events.
-- `listState(listQuery: ListQuery): Promise<Partial<S>[]>` - Retrieves a list of snapshot states.
-- `listStateStream(listQuery: ListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<S>>>>` - Retrieves a stream
+- `listState(listQuery: FilterListQuery): Promise<Partial<S>[]>` - Retrieves a list of snapshot states.
+- `listStateStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<S>>>>` - Retrieves a stream
   of snapshot states as Server-Sent Events.
-- `paged(pagedQuery: PagedQuery): Promise<PagedList<Partial<MaterializedSnapshot<S>>>>` - Retrieves a paged list of
+- `paged(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<MaterializedSnapshot<S>>>>` - Retrieves a paged list of
   materialized snapshots.
-- `pagedState(pagedQuery: PagedQuery): Promise<PagedList<Partial<S>>>` - Retrieves a paged list of snapshot states.
-- `single(singleQuery: SingleQuery): Promise<Partial<MaterializedSnapshot<S>>>` - Retrieves a single materialized
+- `pagedState(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<S>>>` - Retrieves a paged list of snapshot states.
+- `single(singleQuery: FilterSingleQuery): Promise<Partial<MaterializedSnapshot<S>>>` - Retrieves a single materialized
   snapshot.
-- `singleState(singleQuery: SingleQuery): Promise<Partial<S>>` - Retrieves a single snapshot state.
+- `singleState(singleQuery: FilterSingleQuery): Promise<Partial<S>>` - Retrieves a single snapshot state.
+- `aggregate<Row extends DynamicDocument = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>): Promise<Row[]>` - Runs a
+  snapshot aggregation and requests `snapshot/aggregation`.
+- `aggregateStream<Row extends DynamicDocument = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>): Promise<ReadableStream<JsonServerSentEvent<Row>>>` - Runs a snapshot aggregation and requests `snapshot/aggregation` using Server-Sent Events (SSE).
 
 #### QueryClientFactory
 
@@ -413,9 +500,9 @@ Factory for creating pre-configured query clients. Useful when you need multiple
 
 ```typescript
 import {
+  filter,
   QueryClientFactory,
   ResourceAttributionPathSpec,
-  all,
 } from '@ahoo-wang/fetcher-wow';
 import { idGenerator } from '@ahoo-wang/fetcher-cosec';
 
@@ -431,7 +518,7 @@ const factory = new QueryClientFactory({
 const snapshotClient = factory.createSnapshotQueryClient({
   aggregateName: 'cart',
 });
-const carts = await snapshotClient.listState({ condition: all() });
+const carts = await snapshotClient.listState({ filter: filter.matchAll() });
 
 // Create a state aggregate client
 const stateClient = factory.createLoadStateAggregateClient({
@@ -443,7 +530,7 @@ const cart = await stateClient.load('cart-123');
 const eventClient = factory.createEventStreamQueryClient({
   aggregateName: 'cart',
 });
-const events = await eventClient.list({ condition: all() });
+const events = await eventClient.list({ filter: filter.matchAll() });
 ```
 
 **Methods:**
@@ -467,9 +554,9 @@ import {
 import '@ahoo-wang/fetcher-eventstream';
 import {
   EventStreamQueryClient,
-  all,
-  ListQuery,
-  PagedQuery,
+  filter,
+  FilterListQuery,
+  FilterPagedQuery,
 } from '@ahoo-wang/fetcher-wow';
 import { idGenerator } from '@ahoo-wang/fetcher-cosec';
 
@@ -502,11 +589,11 @@ const cartEventStreamQueryClient = new EventStreamQueryClient({
 });
 
 // Count event streams
-const count = await cartEventStreamQueryClient.count(all());
+const count = await cartEventStreamQueryClient.count(filter.matchAll());
 
 // List event streams
-const listQuery: ListQuery = {
-  condition: all(),
+const listQuery: FilterListQuery = {
+  filter: filter.matchAll(),
 };
 const list = await cartEventStreamQueryClient.list(listQuery);
 
@@ -518,20 +605,19 @@ for await (const event of listStream) {
 }
 
 // Paged event streams
-const pagedQuery: PagedQuery = {
-  condition: all(),
+const pagedQuery: FilterPagedQuery = {
+  filter: filter.matchAll(),
 };
 const paged = await cartEventStreamQueryClient.paged(pagedQuery);
 ```
 
 ##### Methods
 
-- `count(condition: Condition): Promise<number>` - Counts the number of domain event streams that match the given
-  condition.
-- `list(listQuery: ListQuery): Promise<Partial<DomainEventStream>[]>` - Retrieves a list of domain event streams.
-- `listStream(listQuery: ListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<DomainEventStream>>>>` -
+- `count(filter: FilterExpression): Promise<number>` - Counts domain event streams matching the filter expression.
+- `list(listQuery: FilterListQuery): Promise<Partial<DomainEventStream>[]>` - Retrieves a list of domain event streams.
+- `listStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<DomainEventStream>>>>` -
   Retrieves a stream of domain event streams as Server-Sent Events.
-- `paged(pagedQuery: PagedQuery): Promise<PagedList<Partial<DomainEventStream>>>` - Retrieves a paged list of domain
+- `paged(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<DomainEventStream>>>` - Retrieves a paged list of domain
   event streams.
 
 ## 🚀 Advanced Usage Examples
@@ -673,8 +759,9 @@ Create complex queries with reactive real-time updates:
 
 ```typescript
 import {
-  SnapshotQueryClient,
   EventStreamQueryClient,
+  filter,
+  SnapshotQueryClient,
 } from '@ahoo-wang/fetcher-wow';
 
 // Advanced query manager with reactive updates
@@ -725,17 +812,16 @@ class ReactiveQueryManager {
   async getUserDashboardStats(userId: string) {
     const [userProfile, recentActivity, stats] = await Promise.all([
       this.snapshotClient.single({
-        condition: { id: userId },
-        projection: { name: 1, email: 1, createdAt: 1 },
+        filter: filter.eq('aggregateId', userId),
       }),
       this.snapshotClient.list({
-        condition: { userId, type: 'activity' },
-        sort: [{ field: 'timestamp', order: 'desc' }],
+        filter: filter.and([
+          filter.eq('state.userId', userId),
+          filter.eq('state.type', 'activity'),
+        ]),
         limit: 10,
       }),
-      this.snapshotClient.count({
-        condition: { userId },
-      }),
+      this.snapshotClient.count(filter.eq('state.userId', userId)),
     ]);
 
     return {
@@ -758,8 +844,10 @@ console.log('Dashboard:', dashboard);
 queryManager.subscribeToQuery(
   'user-activity',
   {
-    condition: { userId: 'user-123', type: 'activity' },
-    sort: [{ field: 'timestamp', order: 'desc' }],
+    filter: filter.and([
+      filter.eq('state.userId', 'user-123'),
+      filter.eq('state.type', 'activity'),
+    ]),
   },
   update => {
     console.log('New activity:', update);
@@ -774,6 +862,7 @@ queryManager.subscribeToQuery(
 import {
   Fetcher,
   FetchExchange,
+  HttpMethod,
   RequestInterceptor,
   URL_RESOLVE_INTERCEPTOR_ORDER,
 } from '@ahoo-wang/fetcher';
@@ -781,12 +870,11 @@ import '@ahoo-wang/fetcher-eventstream';
 import {
   CommandClient,
   CommandRequest,
-  CommandHttpHeaders,
+  CommandHeaders,
   CommandStage,
-  HttpMethod,
   SnapshotQueryClient,
-  all,
-  ListQuery,
+  filter,
+  FilterListQuery,
 } from '@ahoo-wang/fetcher-wow';
 import { idGenerator } from '@ahoo-wang/fetcher-cosec';
 
@@ -850,7 +938,7 @@ type AddCartItemCommand = CommandRequest<AddCartItem>;
 const addItemCommand: AddCartItemCommand = {
   method: HttpMethod.POST,
   headers: {
-    [CommandHttpHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+    [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
   },
   body: {
     productId: 'product-123',
@@ -865,8 +953,8 @@ const commandResult = await cartCommandClient.send(
 console.log('Command executed:', commandResult);
 
 // 2. Query the updated cart
-const listQuery: ListQuery = {
-  condition: all(),
+const listQuery: FilterListQuery = {
+  filter: filter.matchAll(),
 };
 const carts = await cartSnapshotQueryClient.list(listQuery);
 
@@ -895,7 +983,7 @@ pnpm test --coverage
 ## 🤝 Contributing
 
 Contributions are welcome! Please see
-the [contributing guide](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) for more details.
+the [contributing guide](https://github.com/Ahoo-Wang/fetcher/blob/main/wiki/guide/contributing.md) for more details.
 
 ## 📄 License