@ahoo-wang/fetcher-wow 1.0.2 → 1.0.5

package/README.md

@@ -53,7 +53,7 @@ const request = {
     [CommandHeaders.AGGREGATE_ID]: 'aggregate-456',
     [CommandHeaders.REQUEST_ID]: 'request-789',
   },
-  body: JSON.stringify(command),
+  body: command
 };
 ```
 
@@ -92,35 +92,124 @@ const commandRequest: CommandRequest = {
   stream: false,
 };
 ```
-
 #### CommandResult
 
 Interface representing the result of command execution:
 
 ```typescript
 import { CommandResult, CommandStage } from '@ahoo-wang/fetcher-wow';
+```
 
-const commandResult: CommandResult = {
-  id: 'result-123',
-  commandId: 'cmd-456',
-  requestId: 'req-789',
-  stage: CommandStage.PROCESSED,
-  contextName: 'user-context',
-  aggregateName: 'User',
-  aggregateId: 'user-456',
-  aggregateVersion: 1,
-  errorCode: 'Ok',
-  errorMsg: '',
-  function: {
-    functionKind: 'COMMAND',
-    contextName: 'user-context',
-    processorName: 'UserProcessor',
-    name: 'CreateUser',
+#### CommandHttpClient
+
+HTTP client for sending commands to the Wow framework. This client provides methods to send commands and receive results
+either synchronously or as a stream of events.
+
+##### Usage
+
+First, create a fetcher instance with base configuration and add the EventStreamInterceptor:
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const wowFetcher = new Fetcher({
+  baseURL: 'http://localhost:8080/',
+});
+
+// Add EventStreamInterceptor to handle Server-Sent Events
+wowFetcher.interceptors.response.use(new EventStreamInterceptor());
+```
+
+Then create a CommandHttpClient instance:
+
+```typescript
+import { CommandHttpClient } from '@ahoo-wang/fetcher-wow';
+
+const commandHttpClient = new CommandHttpClient(wowFetcher);
+```
+
+##### Sending a Command
+
+To send a command and wait for the result:
+
+```typescript
+import { CommandHeaders, CommandStage, HttpMethod } from '@ahoo-wang/fetcher-wow';
+
+const command = {
+  path: 'owner/{ownerId}/cart/add_cart_item',
+  method: HttpMethod.POST,
+  headers: {
+    [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+  },
+  urlParams: {
+    path: {
+      ownerId: 'ownerId',
+    },
+  },
+  body: {
+    productId: 'productId',
+    quantity: 1,
   },
-  signalTime: Date.now(),
 };
+
+const result = await commandHttpClient.send(command);
+console.log('Command result:', result);
 ```
 
+##### Sending a Command and Receiving Stream Results
+
+For long-running commands, you can receive results as a stream of events:
+
+```typescript
+const commandResultStream = await commandHttpClient.sendAndWaitStream(command);
+for await (const commandResultEvent of commandResultStream) {
+  console.log('Received:', commandResultEvent.data);
+}
+```
+
+##### API
+
+**Constructor**
+
+```typescript
+new CommandHttpClient(fetcher
+:
+Fetcher
+)
+```
+
+Creates a new CommandHttpClient instance.
+
+- `fetcher` - The Fetcher instance to use for HTTP requests
+
+**send**
+
+```typescript
+send(commandHttpRequest
+:
+CommandHttpRequest
+):
+Promise<CommandResult>
+```
+
+Sends a command and waits for the result. This method sends a command to the Wow framework and waits for the processing
+to complete before returning the result.
+
+**sendAndWaitStream**
+
+```typescript
+sendAndWaitStream(commandHttpRequest
+:
+CommandHttpRequest
+):
+Promise<CommandResultEventStream>
+```
+
+Sends a command and returns a stream of results as events. This method sets the Accept header to text/event-stream to
+receive Server-Sent Events, and uses a JSON event stream result extractor to parse the response. It's useful for
+long-running commands where you want to receive progress updates or multiple results.
+
 #### CommandResultEventStream
 
 Type alias for a readable stream of CommandResult events:
@@ -133,8 +222,6 @@ import { JsonServerSentEventStream } from '@ahoo-wang/fetcher-eventstream';
 type CommandResultEventStream = JsonServerSentEventStream<CommandResult>;
 ```
 
-````
-
 ### Query Module
 
 #### Condition Builder
@@ -351,81 +438,6 @@ const functionInfo: FunctionInfo = {
 
 ## 🛠️ Advanced Usage
 
-### Complete Command Flow Example
-
-```typescript
-import {
-  CommandRequest,
-  CommandHeaders,
-  CommandResult,
-  CommandStage,
-} from '@ahoo-wang/fetcher-wow';
-import { fetchEventStream } from '@ahoo-wang/fetcher-eventstream';
-
-// 1. Create command request
-const commandRequest: CommandRequest = {
-  path: '/commands/user/CreateUser',
-  method: 'POST',
-  headers: {
-    [CommandHeaders.TENANT_ID]: 'tenant-123',
-    [CommandHeaders.REQUEST_ID]: 'req-' + Date.now(),
-  },
-  body: {
-    name: 'John Doe',
-    email: 'john@example.com',
-  },
-  timeout: 10000,
-  localFirst: true,
-};
-
-// 2. Execute command and wait for result
-async function executeCommand(request: CommandRequest): Promise<CommandResult> {
-  // Implementation depends on your HTTP client
-  // This is just an example structure
-  const response = await fetch('/api' + request.path, {
-    method: request.method,
-    headers: request.headers,
-    body: JSON.stringify(request.body),
-  });
-
-  return response.json();
-}
-
-// 3. Stream command results in real-time
-async function streamCommandResults() {
-  const eventStream = fetchEventStream('/commands/stream');
-  const commandResultStream = eventStream as CommandResultEventStream;
-
-  const reader = commandResultStream.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      const result: CommandResult = value.data;
-
-      // Handle different stages
-      switch (result.stage) {
-        case CommandStage.SENT:
-          console.log('Command sent to bus');
-          break;
-        case CommandStage.PROCESSED:
-          console.log('Command processed by aggregate');
-          break;
-        case CommandStage.SNAPSHOT:
-          console.log('Snapshot generated');
-          break;
-        case CommandStage.PROJECTED:
-          console.log('Events projected to read model');
-          break;
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-```
-
 ### Complex Query Building
 
 ```typescript

package/README.zh-CN.md

@@ -131,16 +131,6 @@ import { JsonServerSentEventStream } from '@ahoo-wang/fetcher-eventstream';
 
 // CommandResultEventStream 是 CommandResult 的 JsonServerSentEventStream
 type CommandResultEventStream = JsonServerSentEventStream<CommandResult>;
-```
-
-while (true) {
-const { done, value } = await reader.read();
-if (done) break;
-
-const commandResult: CommandResult = value.data;
-console.log('命令结果:', commandResult);
-}
-
 ````
 
 ### 查询模块
@@ -359,81 +349,6 @@ const functionInfo: FunctionInfo = {
 
 ## 🛠️ 高级用法
 
-### 完整命令流程示例
-
-```typescript
-import {
-  CommandRequest,
-  CommandHeaders,
-  CommandResult,
-  CommandStage,
-} from '@ahoo-wang/fetcher-wow';
-import { fetchEventStream } from '@ahoo-wang/fetcher-eventstream';
-
-// 1. 创建命令请求
-const commandRequest: CommandRequest = {
-  path: '/commands/user/CreateUser',
-  method: 'POST',
-  headers: {
-    [CommandHeaders.TENANT_ID]: 'tenant-123',
-    [CommandHeaders.REQUEST_ID]: 'req-' + Date.now(),
-  },
-  body: {
-    name: 'John Doe',
-    email: 'john@example.com',
-  },
-  timeout: 10000,
-  localFirst: true,
-};
-
-// 2. 执行命令并等待结果
-async function executeCommand(request: CommandRequest): Promise<CommandResult> {
-  // 实现依赖于您的 HTTP 客户端
-  // 这只是一个示例结构
-  const response = await fetch('/api' + request.path, {
-    method: request.method,
-    headers: request.headers,
-    body: JSON.stringify(request.body),
-  });
-
-  return response.json();
-}
-
-// 3. 实时流式处理命令结果
-async function streamCommandResults() {
-  const eventStream = fetchEventStream('/commands/stream');
-  const commandResultStream = eventStream as CommandResultEventStream;
-
-  const reader = commandResultStream.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      const result: CommandResult = value.data;
-
-      // 处理不同阶段
-      switch (result.stage) {
-        case CommandStage.SENT:
-          console.log('命令已发送到总线');
-          break;
-        case CommandStage.PROCESSED:
-          console.log('命令已被聚合根处理');
-          break;
-        case CommandStage.SNAPSHOT:
-          console.log('已生成快照');
-          break;
-        case CommandStage.PROJECTED:
-          console.log('事件已投影到读模型');
-          break;
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-```
-
 ### 复杂查询构建
 
 ```typescript

package/dist/command/commandHttpClient.d.ts

@@ -0,0 +1,133 @@
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { CommandResult, CommandResultEventStream } from './commandResult';
+import { CommandHttpRequest } from './commandHttpRequest';
+/**
+ * HTTP client for sending commands to the Wow framework.
+ *
+ * This client provides methods to send commands and receive results either
+ * synchronously or as a stream of events. It uses the fetcher-decorator
+ * library to handle HTTP communication with appropriate headers and
+ * result extraction.
+ *
+ * @example
+ * ```typescript
+ * // Create a fetcher instance with base configuration
+ * const wowFetcher = new Fetcher({
+ *   baseURL: 'http://localhost:8080/',
+ * });
+ *
+ * // Add EventStreamInterceptor to handle Server-Sent Events
+ * wowFetcher.interceptors.response.use(new EventStreamInterceptor());
+ *
+ * // Create CommandHttpClient instance
+ * const commandHttpClient = new CommandHttpClient(wowFetcher);
+ *
+ * // Define a command
+ * const command: CommandHttpRequest = {
+ *   path: 'owner/{ownerId}/cart/add_cart_item',
+ *   method: HttpMethod.POST,
+ *   headers: {
+ *     [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+ *   },
+ *   urlParams: {
+ *     path: {
+ *       ownerId: 'ownerId',
+ *     },
+ *   },
+ *   body: {
+ *     productId: 'productId',
+ *     quantity: 1,
+ *   },
+ * };
+ *
+ * // Send command and wait for result
+ * const commandResult = await commandHttpClient.send(command);
+ *
+ * // Send command and receive result as stream
+ * const commandResultStream = await commandHttpClient.sendAndWaitStream(command);
+ * for await (const commandResultEvent of commandResultStream) {
+ *   console.log('Received:', commandResultEvent.data);
+ * }
+ * ```
+ */
+export declare class CommandHttpClient {
+    readonly fetcher: Fetcher;
+    /**
+     * Creates a new CommandHttpClient instance.
+     *
+     * @param fetcher - The Fetcher instance to use for HTTP requests
+     */
+    constructor(fetcher: Fetcher);
+    /**
+     * Sends a command and waits for the result.
+     *
+     * This method sends a command to the Wow framework and waits for the processing
+     * to complete before returning the result. The command is sent as an HTTP request
+     * with the specified path, method, headers, and body.
+     *
+     * @param commandHttpRequest - The command HTTP request to send
+     * @returns A promise that resolves to the command result
+     *
+     * @example
+     * ```typescript
+     * const command: CommandHttpRequest = {
+     *   path: 'owner/{ownerId}/cart/add_cart_item',
+     *   method: HttpMethod.POST,
+     *   headers: {
+     *     [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+     *   },
+     *   urlParams: {
+     *     path: {
+     *       ownerId: 'ownerId',
+     *     },
+     *   },
+     *   body: {
+     *     productId: 'productId',
+     *     quantity: 1,
+     *   },
+     * };
+     *
+     * const result = await commandHttpClient.send(command);
+     * console.log('Command result:', result);
+     * ```
+     */
+    send(commandHttpRequest: CommandHttpRequest): Promise<CommandResult>;
+    /**
+     * Sends a command and returns a stream of results as events.
+     *
+     * This method sets the Accept header to text/event-stream to receive
+     * Server-Sent Events, and uses a JSON event stream result extractor
+     * to parse the response. It's useful for long-running commands where
+     * you want to receive progress updates or multiple results.
+     *
+     * @param commandHttpRequest - The command HTTP request to send
+     * @returns A promise that resolves to a stream of command results
+     *
+     * @example
+     * ```typescript
+     * const command: CommandHttpRequest = {
+     *   path: 'owner/{ownerId}/cart/add_cart_item',
+     *   method: HttpMethod.POST,
+     *   headers: {
+     *     [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+     *   },
+     *   urlParams: {
+     *     path: {
+     *       ownerId: 'ownerId',
+     *     },
+     *   },
+     *   body: {
+     *     productId: 'productId',
+     *     quantity: 1,
+     *   },
+     * };
+     *
+     * const stream = await commandHttpClient.sendAndWaitStream(command);
+     * for await (const event of stream) {
+     *   console.log('Command result event:', event.data);
+     * }
+     * ```
+     */
+    sendAndWaitStream(commandHttpRequest: CommandHttpRequest): Promise<CommandResultEventStream>;
+}
+//# sourceMappingURL=commandHttpClient.d.ts.map

package/dist/command/commandHttpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandHttpClient.d.ts","sourceRoot":"","sources":["../../src/command/commandHttpClient.ts"],"names":[],"mappings":"AAaA,OAAO,EAAqB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,iBAAiB;aAMA,OAAO,EAAE,OAAO;IAL5C;;;;OAIG;gBACyB,OAAO,EAAE,OAAO;IAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IAEH,IAAI,CAAY,kBAAkB,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAI/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IAOG,iBAAiB,CAAY,kBAAkB,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAG9G"}

package/dist/command/commandHttpRequest.d.ts

@@ -0,0 +1,48 @@
+import { RequestHeaders, UrlParams } from '@ahoo-wang/fetcher';
+import { ParameterRequest } from '@ahoo-wang/fetcher-decorator';
+/**
+ * Command HTTP Headers Interface
+ *
+ * Defines the HTTP header fields used in command processing within the Wow framework.
+ * This interface extends RequestHeaders to provide type-safe access to all command-related headers.
+ *
+ * @example
+ * ```typescript
+ * // Using CommandHttpHeaders in a request
+ * const headers: CommandHttpHeaders = {
+ *   [CommandHeaders.TENANT_ID]: 'tenant-123',
+ *   [CommandHeaders.AGGREGATE_ID]: 'aggregate-456',
+ *   [CommandHeaders.REQUEST_ID]: 'request-789'
+ * };
+ * ```
+ */
+export interface CommandHttpHeaders extends RequestHeaders {
+}
+export interface CommandPathParams {
+    tenantId?: string;
+    ownerId?: string;
+    id?: string;
+    [key: string]: string | undefined;
+}
+export interface CommandUrlParams extends Omit<UrlParams, 'path' | 'query'> {
+    path?: CommandPathParams;
+}
+/**
+ * Command HTTP Request Interface
+ *
+ * Extends RequestHeaders to provide type-safe access to command-related HTTP headers.
+ * This interface includes only the essential command headers commonly used in HTTP requests.
+ */
+export interface CommandHttpRequest extends ParameterRequest {
+    /**
+     * Path for the command endpoint (relative to class base path).
+     */
+    path: string;
+    urlParams?: CommandUrlParams;
+    headers?: CommandHttpHeaders;
+    /**
+     * The body of the command request.
+     */
+    body: any;
+}
+//# sourceMappingURL=commandHttpRequest.d.ts.map

package/dist/command/commandHttpRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandHttpRequest.d.ts","sourceRoot":"","sources":["../../src/command/commandHttpRequest.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;CA4GzD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACzE,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;OAEG;IACH,IAAI,EAAE,GAAG,CAAC;CACX"}

package/dist/command/index.d.ts

@@ -1,4 +1,6 @@
 export * from './commandHeaders';
+export * from './commandHttpClient';
+export * from './commandHttpRequest';
 export * from './commandRequest';
 export * from './commandResult';
 export * from './types';

package/dist/command/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAaA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/command/index.ts"],"names":[],"mappings":"AAaA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC"}