@ahoo-wang/fetcher-wow 3.18.0 → 4.0.0

package/README.zh-CN.md

@@ -1,745 +1,56 @@
-# @ahoo-wang/fetcher-wow
+# `@ahoo-wang/fetcher-wow`
 
-[![npm version](https://img.shields.io/npm/v/@ahoo-wang/fetcher-wow.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-wow)
-[![Build Status](https://github.com/Ahoo-Wang/fetcher/actions/workflows/ci.yml/badge.svg)](https://github.com/Ahoo-Wang/fetcher/actions)
-[![codecov](https://codecov.io/gh/Ahoo-Wang/fetcher/graph/badge.svg?token=JGiWZ52CvJ)](https://codecov.io/gh/Ahoo-Wang/fetcher)
-[![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-wow.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
-[![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-wow.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-wow)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher-wow)](https://www.npmjs.com/package/@ahoo-wang/fetcher-wow)
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
-[![Storybook](https://img.shields.io/badge/Storybook-交互式文档-FF4785)](https://fetcher.ahoo.me/?path=/docs/wow-introduction--docs)
+面向 Wow 命令、快照、领域事件、过滤、分页与聚合的类型化 Fetcher 客户端和契约。只在
+对接 Wow HTTP 端点时使用。
 
-为 [Wow](https://github.com/Ahoo-Wang/Wow) 框架提供支持。提供用于与 Wow CQRS/DDD 框架配合使用的 TypeScript 类型和工具。
-
-## 🌟 特性
-
-- **📦 完整的 TypeScript 支持**：为所有 Wow 框架实体提供完整的类型定义，包括命令、事件和查询
-- **🚀 命令客户端**：用于向 Wow 服务发送命令的高级客户端，支持同步和流式响应
-- **🔍 强大的查询 DSL**：类型安全的 `FilterExpression` 构建器，支持完整的查询操作符
-- **📊 快照聚合**：使用类型安全的查询对快照数据进行分组和聚合
-- **📡 实时事件流**：内置对服务器发送事件的支持，用于接收实时命令结果和数据更新
-- **🔄 CQRS 模式实现**：对命令查询责任分离架构模式的一流支持
-- **🧱 DDD 基础构件**：基本的领域驱动设计构建块，包括聚合、事件和值对象
-- **🔍 查询客户端**：专门用于查询快照和事件流数据的客户端，支持全面的查询操作：
-  - 资源计数
-  - 资源列表查询
-  - 以服务器发送事件形式流式传输资源
-  - 资源分页
-  - 单个资源检索
-
-## 🚀 快速开始
-
-### 安装
+## 安装
 
 ```bash
-# 使用 npm
-npm install @ahoo-wang/fetcher-wow
-
-# 使用 pnpm
-pnpm add @ahoo-wang/fetcher-wow
-
-# 使用 yarn
-yarn add @ahoo-wang/fetcher-wow
-```
-
-## 📚 API 参考
-
-### 命令模块
-
-#### CommandResult
-
-表示命令执行结果的接口：
-
-```typescript
-import { CommandResult, CommandStage } from '@ahoo-wang/fetcher-wow';
-```
-
-#### CommandClient
-
-用于向 Wow 框架发送命令的 HTTP 客户端。该客户端提供了同步或流式接收命令结果的方法。
-
-```typescript
-import {
-  Fetcher,
-  FetchExchange,
-  HttpMethod,
-  RequestInterceptor,
-  URL_RESOLVE_INTERCEPTOR_ORDER,
-} from '@ahoo-wang/fetcher';
-import '@ahoo-wang/fetcher-eventstream';
-import {
-  CommandClient,
-  CommandRequest,
-  CommandHeaders,
-  CommandStage,
-} from '@ahoo-wang/fetcher-wow';
-import { idGenerator } from '@ahoo-wang/fetcher-cosec';
-
-// 使用基础配置创建 fetcher 实例
-const exampleFetcher = new Fetcher({
-  baseURL: 'http://localhost:8080/',
-});
-
-// 定义当前用户 ID
-const currentUserId = idGenerator.generateId();
-
-// 创建处理 URL 参数的拦截器
-class AppendOwnerId implements RequestInterceptor {
-  readonly name: string = 'AppendOwnerId';
-  readonly order: number = URL_RESOLVE_INTERCEPTOR_ORDER - 1;
-
-  intercept(exchange: FetchExchange) {
-    const urlParams = exchange.ensureRequestUrlParams();
-    urlParams.path['ownerId'] = currentUserId;
-  }
-}
-
-// 注册拦截器
-exampleFetcher.interceptors.request.use(new AppendOwnerId());
-
-// 创建命令客户端
-const cartCommandClient = new CommandClient({
-  fetcher: exampleFetcher,
-  basePath: 'owner/{ownerId}/cart',
-});
-
-// 定义命令端点
-class CartCommandEndpoints {
-  static readonly addCartItem = 'add_cart_item';
-}
-
-// 定义命令接口
-interface AddCartItem {
-  productId: string;
-  quantity: number;
-}
-
-type AddCartItemCommand = CommandRequest<AddCartItem>;
-
-// 创建命令请求
-const addCartItemCommand: AddCartItemCommand = {
-  method: HttpMethod.POST,
-  headers: {
-    [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
-  },
-  body: {
-    productId: 'productId',
-    quantity: 1,
-  },
-};
-
-// 发送命令并等待结果
-const commandResult = await cartCommandClient.send(
-  CartCommandEndpoints.addCartItem,
-  addCartItemCommand,
-);
-
-// 发送命令并接收流式结果
-const commandResultStream = await cartCommandClient.sendAndWaitStream(
-  CartCommandEndpoints.addCartItem,
-  addCartItemCommand,
-);
-for await (const commandResultEvent of commandResultStream) {
-  console.log('收到命令结果:', commandResultEvent.data);
-}
-```
-
-##### 方法
-
-- `send(path: string, commandRequest: CommandRequest): Promise<CommandResult>` - 发送命令并等待结果。
-- `sendAndWaitStream(path: string, commandRequest: CommandRequest): Promise<CommandResultEventStream>` -
-  发送命令并以服务器发送事件的形式返回结果流。
-
-### 查询模块
-
-#### FilterExpression 构建器
-
-Wow 8.11+ 查询使用 `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,
-  }),
-]);
-```
-
-所有构建器集中在 `filter`：`matchAll`、`matchNone`、`and`、`or`、`nor`、
-比较、字符串/集合谓词、存在性检查、`elementMatch`、`search`、删除范围和相对时间过滤器。
-`and`、`or`、`nor`、`ids`、`aggregateIds`、`isIn`、`notIn` 和
-`containsAll` 接收一个非空 `readonly` 数组；传入空数组时抛出 `TypeError`。
-
-#### 条件构建器（已弃用）
-
-旧 Condition API 仅为兼容旧版 Wow 服务保留。新代码应使用
-`FilterExpression` 和 `filter.*`。
-
-```typescript
-import {
-  and,
-  or,
-  eq,
-  ne,
-  gt,
-  lt,
-  gte,
-  lte,
-  contains,
-  isIn,
-  notIn,
-  between,
-  allIn,
-  startsWith,
-  endsWith,
-  match,
-  elemMatch,
-  isNull,
-  notNull,
-  isTrue,
-  isFalse,
-  exists,
-  raw,
-  today,
-  beforeToday,
-  tomorrow,
-  thisWeek,
-  nextWeek,
-  lastWeek,
-  thisMonth,
-  lastMonth,
-  recentDays,
-  earlierDays,
-  active,
-  all,
-  id,
-  ids,
-  aggregateId,
-  aggregateIds,
-  tenantId,
-  ownerId,
-} from '@ahoo-wang/fetcher-wow';
-
-// 简单条件
-const simpleConditions = [
-  eq('name', 'John'),
-  ne('status', 'inactive'),
-  gt('age', 18),
-  lt('score', 100),
-  gte('rating', 4.0),
-  lte('price', 100),
-];
-
-// 字符串条件
-const stringConditions = [
-  contains('email', '@company.com'),
-  startsWith('username', 'j'),
-  endsWith('domain', '.com'),
-  isIn('status', 'active', 'pending'),
-  notIn('role', 'guest', 'banned'),
-  match('description', 'search keywords'),
-];
-
-// 空值检查
-const nullConditions = [
-  isNull('deletedAt'),
-  notNull('email'),
-  isTrue('isActive'),
-  isFalse('isDeleted'),
-  exists('phoneNumber'),
-];
-
-// 数组条件
-const arrayConditions = [
-  allIn('tags', 'react', 'typescript'),
-  elemMatch('items', eq('quantity', 0)),
-];
-
-// 日期条件
-const dateConditions = [
-  today('createdAt'),
-  beforeToday('lastLogin', '09:30'),
-  tomorrow('scheduledDate'),
-  thisWeek('updatedAt'),
-  nextWeek('startDate'),
-  lastWeek('endDate'),
-  thisMonth('createdDate'),
-  lastMonth('expirationDate'),
-  recentDays('createdAt', 5), // 最近5天，包括今天
-  earlierDays('createdAt', 3), // 3天之前
-];
-
-// 复杂条件
-const complexCondition = and(
-  eq('tenantId', 'tenant-123'),
-  or(
-    contains('email', '@company.com'),
-    isIn('department', 'engineering', 'marketing'),
-  ),
-  between('salary', 50000, 100000),
-  today('createdAt'),
-  active(),
-);
-
-// 高级用法的原始条件
-const rawCondition = raw({ $text: { $search: 'keywords' } });
-```
-
-**操作符参考：**
-
-| 类别      | 操作符                                                                                                                                          |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| 逻辑      | `and`, `or`, `nor`                                                                                                                              |
-| 比较      | `eq`, `ne`, `gt`, `lt`, `gte`, `lte`                                                                                                            |
-| 字符串    | `contains`, `startsWith`, `endsWith`, `match`                                                                                                   |
-| 集合      | `isIn`, `notIn`, `allIn`, `elemMatch`                                                                                                           |
-| 空值/布尔 | `isNull`, `notNull`, `isTrue`, `isFalse`, `exists`                                                                                              |
-| 日期      | `today`, `beforeToday(time)`, `tomorrow`, `thisWeek`, `nextWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `recentDays(days)`, `earlierDays(days)` |
-| ID        | `id`, `ids`, `aggregateId`, `aggregateIds`, `tenantId`, `ownerId`                                                                               |
-| 状态      | `active`, `all`, `deleted`                                                                                                                      |
-| 特殊      | `raw`（用于高级数据库特定查询）                                                                                                                 |
-
-#### SnapshotQueryClient
-
-用于查询物化快照的客户端，支持全面的查询操作：
-
-```typescript
-import {
-  Fetcher,
-  FetchExchange,
-  RequestInterceptor,
-  URL_RESOLVE_INTERCEPTOR_ORDER,
-} from '@ahoo-wang/fetcher';
-import '@ahoo-wang/fetcher-eventstream';
-import {
-  aggregation,
-  SnapshotQueryClient,
-  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[];
-}
-
-// 使用基础配置创建 fetcher 实例
-const exampleFetcher = new Fetcher({
-  baseURL: 'http://localhost:8080/',
-});
-
-// 定义当前用户 ID
-const currentUserId = idGenerator.generateId();
-
-// 创建处理 URL 参数的拦截器
-class AppendOwnerId implements RequestInterceptor {
-  readonly name: string = 'AppendOwnerId';
-  readonly order: number = URL_RESOLVE_INTERCEPTOR_ORDER - 1;
-
-  intercept(exchange: FetchExchange) {
-    const urlParams = exchange.ensureRequestUrlParams();
-    urlParams.path['ownerId'] = currentUserId;
-  }
-}
-
-// 注册拦截器
-exampleFetcher.interceptors.request.use(new AppendOwnerId());
-
-// 创建快照查询客户端
-const cartSnapshotQueryClient = new SnapshotQueryClient<CartState>({
-  fetcher: exampleFetcher,
-  basePath: 'owner/{ownerId}/cart',
-});
-
-// 统计快照数量
-const count = await cartSnapshotQueryClient.count(filter.matchAll());
-
-// 列出快照
-const listQuery: FilterListQuery = {
-  filter: filter.matchAll(),
-};
-const list = await cartSnapshotQueryClient.list(listQuery);
-
-// 以流的形式列出快照
-const listStream = await cartSnapshotQueryClient.listStream(listQuery);
-for await (const event of listStream) {
-  const snapshot = event.data;
-  console.log('收到快照:', snapshot);
-}
-
-// 列出快照状态
-const stateList = await cartSnapshotQueryClient.listState(listQuery);
-
-// 以流的形式列出快照状态
-const stateStream = await cartSnapshotQueryClient.listStateStream(listQuery);
-for await (const event of stateStream) {
-  const state = event.data;
-  console.log('收到状态:', state);
-}
-
-// 分页查询快照
-const pagedQuery: FilterPagedQuery = {
-  filter: filter.matchAll(),
-};
-const paged = await cartSnapshotQueryClient.paged(pagedQuery);
-
-// 分页查询快照状态
-const pagedState = await cartSnapshotQueryClient.pagedState(pagedQuery);
-
-// 查询单个快照
-const singleQuery: FilterSingleQuery = {
-  filter: filter.matchAll(),
-};
-const single = await cartSnapshotQueryClient.single(singleQuery);
-
-// 查询单个快照状态
-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);
-}
+pnpm add @ahoo-wang/fetcher @ahoo-wang/fetcher-decorator \
+  @ahoo-wang/fetcher-eventstream @ahoo-wang/fetcher-wow
 ```
 
-`aggregation.any(field, alias)` 增加的是指标，不是新的分组。它从当前分组返回一个
-非空标量；没有值时返回 `null`。具体选择哪个值不属于契约，可能随后端或执行变化；
-只有候选值可互换时才应使用。字段相对最内层 Element，集合字段或不具备 terms 聚合
-能力的字段由 Wow 在运行时拒绝。按 `ANY` alias 排序属于昂贵的指标排序。
-
-##### 方法
+Peer 依赖：`fetcher`、`fetcher-decorator` 和 `fetcher-eventstream`。
 
-- `count(filter: FilterExpression): Promise<number>` - 统计匹配过滤表达式的快照数量。
-- `list(listQuery: FilterListQuery): Promise<Partial<MaterializedSnapshot<S>>[]>` - 检索物化快照列表。
-- `listStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<MaterializedSnapshot<S>>>>>` -
-  以服务器发送事件的形式检索物化快照流。
-- `listState(listQuery: FilterListQuery): Promise<Partial<S>[]>` - 检索快照状态列表。
-- `listStateStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<S>>>>` -
-  以服务器发送事件的形式检索快照状态流。
-- `paged(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<MaterializedSnapshot<S>>>>` - 检索物化快照的分页列表。
-- `pagedState(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<S>>>` - 检索快照状态的分页列表。
-- `single(singleQuery: FilterSingleQuery): Promise<Partial<MaterializedSnapshot<S>>>` - 检索单个物化快照。
-- `singleState(singleQuery: FilterSingleQuery): Promise<Partial<S>>` - 检索单个快照状态。
-- `aggregate<Row extends DynamicDocument = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>): Promise<Row[]>` - 执行快照聚合并请求 `snapshot/aggregation`。
-- `aggregateStream<Row extends DynamicDocument = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>): Promise<ReadableStream<JsonServerSentEvent<Row>>>` - 执行快照聚合并通过服务器发送事件（SSE）请求 `snapshot/aggregation`。
-
-#### QueryClientFactory
-
-用于创建预配置查询客户端的工厂。当您需要具有共享配置的多个客户端时，这非常有用。
-
-```typescript
-import {
-  filter,
-  QueryClientFactory,
-  ResourceAttributionPathSpec,
-} from '@ahoo-wang/fetcher-wow';
-import { idGenerator } from '@ahoo-wang/fetcher-cosec';
-
-// 使用默认选项创建工厂
-const factory = new QueryClientFactory({
-  contextAlias: 'example',
-  aggregateName: 'cart',
-  resourceAttribution: ResourceAttributionPathSpec.OWNER,
-  fetcher: exampleFetcher,
-});
+## 示例
 
-// 创建快照查询客户端
-const snapshotClient = factory.createSnapshotQueryClient({
-  aggregateName: 'cart',
-});
-const carts = await snapshotClient.listState({ filter: filter.matchAll() });
-
-// 创建状态聚合客户端
-const stateClient = factory.createLoadStateAggregateClient({
-  aggregateName: 'cart',
-});
-const cart = await stateClient.load('cart-123');
-
-// 创建事件流查询客户端
-const eventClient = factory.createEventStreamQueryClient({
-  aggregateName: 'cart',
-});
-const events = await eventClient.list({ filter: filter.matchAll() });
-```
-
-**方法：**
-
-- `createSnapshotQueryClient(options?: QueryClientOptions): SnapshotQueryClient` - 创建用于查询快照的客户端。
-- `createLoadStateAggregateClient(options?: QueryClientOptions): LoadStateAggregateClient` - 创建用于按 ID 加载聚合状态的客户端。
-- `createOwnerLoadStateAggregateClient(options?: QueryClientOptions): LoadOwnerStateAggregateClient` - 创建用于加载当前所有者聚合状态的客户端。
-- `createEventStreamQueryClient(options?: QueryClientOptions): EventStreamQueryClient` - 创建用于查询事件流的客户端。
-
-#### EventStreamQueryClient
-
-用于查询领域事件流的客户端，支持全面的查询操作：
-
-```typescript
-import {
-  Fetcher,
-  FetchExchange,
-  RequestInterceptor,
-  URL_RESOLVE_INTERCEPTOR_ORDER,
-} from '@ahoo-wang/fetcher';
-import '@ahoo-wang/fetcher-eventstream';
-import {
-  EventStreamQueryClient,
-  filter,
-  FilterListQuery,
-  FilterPagedQuery,
-} from '@ahoo-wang/fetcher-wow';
-import { idGenerator } from '@ahoo-wang/fetcher-cosec';
-
-// 使用基础配置创建 fetcher 实例
-const exampleFetcher = new Fetcher({
-  baseURL: 'http://localhost:8080/',
-});
-
-// 定义当前用户 ID
-const currentUserId = idGenerator.generateId();
-
-// 创建处理 URL 参数的拦截器
-class AppendOwnerId implements RequestInterceptor {
-  readonly name: string = 'AppendOwnerId';
-  readonly order: number = URL_RESOLVE_INTERCEPTOR_ORDER - 1;
-
-  intercept(exchange: FetchExchange) {
-    const urlParams = exchange.ensureRequestUrlParams();
-    urlParams.path['ownerId'] = currentUserId;
-  }
-}
-
-// 注册拦截器
-exampleFetcher.interceptors.request.use(new AppendOwnerId());
-
-// 创建事件流查询客户端
-const cartEventStreamQueryClient = new EventStreamQueryClient({
-  fetcher: exampleFetcher,
-  basePath: 'owner/{ownerId}/cart',
-});
-
-// 统计事件流数量
-const count = await cartEventStreamQueryClient.count(filter.matchAll());
-
-// 列出事件流
-const listQuery: FilterListQuery = {
-  filter: filter.matchAll(),
-};
-const list = await cartEventStreamQueryClient.list(listQuery);
-
-// 以流的形式列出事件流
-const listStream = await cartEventStreamQueryClient.listStream(listQuery);
-for await (const event of listStream) {
-  const domainEventStream = event.data;
-  console.log('收到事件流:', domainEventStream);
-}
-
-// 分页查询事件流
-const pagedQuery: FilterPagedQuery = {
-  filter: filter.matchAll(),
-};
-const paged = await cartEventStreamQueryClient.paged(pagedQuery);
-```
-
-##### 方法
-
-- `count(filter: FilterExpression): Promise<number>` - 统计匹配过滤表达式的领域事件流数量。
-- `list(listQuery: FilterListQuery): Promise<Partial<DomainEventStream>[]>` - 检索领域事件流列表。
-- `listStream(listQuery: FilterListQuery): Promise<ReadableStream<JsonServerSentEvent<Partial<DomainEventStream>>>>` -
-  以服务器发送事件的形式检索领域事件流。
-- `paged(pagedQuery: FilterPagedQuery): Promise<PagedList<Partial<DomainEventStream>>>` - 检索领域事件流的分页列表。
-
-## 🛠️ 高级用法
-
-### 完整的命令和查询流程示例
-
-```typescript
-import {
-  Fetcher,
-  FetchExchange,
-  HttpMethod,
-  RequestInterceptor,
-  URL_RESOLVE_INTERCEPTOR_ORDER,
-} from '@ahoo-wang/fetcher';
-import '@ahoo-wang/fetcher-eventstream';
-import {
-  CommandClient,
-  CommandRequest,
-  CommandHeaders,
-  CommandStage,
-  SnapshotQueryClient,
-  filter,
-  FilterListQuery,
-} from '@ahoo-wang/fetcher-wow';
-import { idGenerator } from '@ahoo-wang/fetcher-cosec';
-
-interface CartItem {
-  productId: string;
-  quantity: number;
-}
+```ts
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { SnapshotQueryClient, filter, listQuery } from '@ahoo-wang/fetcher-wow';
 
 interface CartState {
-  id: string;
-  items: CartItem[];
-}
-
-// 创建 fetcher 实例
-const exampleFetcher = new Fetcher({
-  baseURL: 'http://localhost:8080/',
-});
-
-// 定义当前用户 ID
-const currentUserId = idGenerator.generateId();
-
-// 创建处理 URL 参数的拦截器
-class AppendOwnerId implements RequestInterceptor {
-  readonly name: string = 'AppendOwnerId';
-  readonly order: number = URL_RESOLVE_INTERCEPTOR_ORDER - 1;
-
-  intercept(exchange: FetchExchange) {
-    const urlParams = exchange.ensureRequestUrlParams();
-    urlParams.path['ownerId'] = currentUserId;
-  }
+  status: 'ACTIVE' | 'CHECKED_OUT';
 }
 
-// 注册拦截器
-exampleFetcher.interceptors.request.use(new AppendOwnerId());
-
-// 创建客户端
-const cartCommandClient = new CommandClient({
-  fetcher: exampleFetcher,
-  basePath: 'owner/{ownerId}/cart',
+const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
+const snapshots = new SnapshotQueryClient<CartState>({
+  fetcher,
+  basePath: 'cart',
 });
 
-const cartSnapshotQueryClient = new SnapshotQueryClient<CartState>({
-  fetcher: exampleFetcher,
-  basePath: 'owner/{ownerId}/cart',
-});
-
-// 定义命令端点
-class CartCommandEndpoints {
-  static readonly addCartItem = 'add_cart_item';
-}
-
-// 定义命令接口
-interface AddCartItem {
-  productId: string;
-  quantity: number;
-}
-
-type AddCartItemCommand = CommandRequest<AddCartItem>;
-
-// 1. 发送命令添加商品到购物车
-const addItemCommand: AddCartItemCommand = {
-  method: HttpMethod.POST,
-  headers: {
-    [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
-  },
-  body: {
-    productId: 'product-123',
-    quantity: 2,
-  },
-};
-
-const commandResult = await cartCommandClient.send(
-  CartCommandEndpoints.addCartItem,
-  addItemCommand,
+const carts = await snapshots.listState(
+  listQuery({
+    filter: filter.and([
+      filter.ownerId('u-42'),
+      filter.eq('state.status', 'ACTIVE'),
+    ]),
+    limit: 50,
+  }),
 );
-console.log('命令执行完成:', commandResult);
-
-// 2. 查询更新后的购物车
-const listQuery: FilterListQuery = {
-  filter: filter.matchAll(),
-};
-const carts = await cartSnapshotQueryClient.list(listQuery);
-
-for (const cart of carts) {
-  console.log('购物车:', cart.state);
-}
-
-// 3. 流式监听购物车更新
-const listStream = await cartSnapshotQueryClient.listStream(listQuery);
-for await (const event of listStream) {
-  const cart = event.data;
-  console.log('购物车更新:', cart.state);
-}
-```
-
-## 🧪 测试
-
-```bash
-# 运行测试
-pnpm test
-
-# 运行带覆盖率的测试
-pnpm test --coverage
 ```
 
-## 🤝 贡献
-
-欢迎贡献！请查看
-[贡献指南](https://github.com/Ahoo-Wang/fetcher/blob/main/wiki/guide/contributing.md) 获取更多详情。
+## 核心能力
 
-## 📄 许可证
+- 命令结果与流式等待阶段。
+- 快照、领域事件、状态加载与所有者状态客户端。
+- 提前校验的数组优先 `FilterExpression` 构建器。
+- 单条、列表、分页、游标、计数与流查询契约。
+- 投影、排序、嵌套聚合、建模、ABAC 与元数据类型。
 
-Apache-2.0
+## 文档
 
----
+- [Wow CQRS 实战](https://fetcher.ahoo.me/zh/recipes/wow-cqrs)
+- [Wow 参考](https://fetcher.ahoo.me/zh/reference/wow)
+- [交互式查询 Story](https://fetcher.ahoo.me/storybook/)
 
-<p align="center">
-  <a href="https://github.com/Ahoo-Wang/fetcher">Fetcher</a> 生态系统的一部分
-</p>
+[English](./README.md) · [许可证](../../LICENSE)