@ahoo-wang/fetcher-generator 2.9.0 → 2.9.1

package/README.md

@@ -340,8 +340,7 @@ import {
 export class CartApiClient implements ApiMetadataCapable {
   constructor(
     public readonly apiMetadata: ApiMetadata = { basePath: 'example' },
-  ) {
-  }
+  ) {}
 
   /** Custom command sending */
   @post('/cart/{userId}/customize-send-cmd')
@@ -397,7 +396,9 @@ const fetcher = new Fetcher({
 });
 
 // Use the generated query client factory
-const snapshotClient = cartQueryClientFactory.createSnapshotQueryClient({ fetcher: fetcher });
+const snapshotClient = cartQueryClientFactory.createSnapshotQueryClient({
+  fetcher: fetcher,
+});
 const cartState = await snapshotClient.singleState({ condition: all() });
 
 // Use the generated command client
@@ -419,6 +420,209 @@ const apiClient = new CartApiClient({ fetcher: fetcher });
 const cartData = await apiClient.me();
 ```
 
+## 🚀 Advanced Usage Examples
+
+### Custom Configuration
+
+Create a `.fetcherrc.json` configuration file for advanced generation options:
+
+```json
+{
+  "generator": {
+    "targetFramework": "wow",
+    "outputFormat": "typescript",
+    "basePath": "api/v1",
+    "generateIndexFiles": true,
+    "verbose": true,
+    "typeMappings": {
+      "string": "string",
+      "integer": "number",
+      "boolean": "boolean",
+      "number": "number"
+    },
+    "schemaTransformers": [
+      {
+        "pattern": "^wow\\.",
+        "transform": "removePrefix"
+      }
+    ]
+  }
+}
+```
+
+### Multi-Context Generation
+
+Generate code for multiple bounded contexts from a single OpenAPI spec:
+
+```bash
+# Generate all contexts
+fetcher-generator generate -i ./multi-context-api.json -o ./src/generated
+
+# Generated structure:
+# src/generated/
+# ├── ecommerce/
+# │   ├── index.ts
+# │   ├── boundedContext.ts
+# │   ├── cart/
+# │   ├── order/
+# │   └── product/
+# └── inventory/
+#     ├── index.ts
+#     ├── boundedContext.ts
+#     └── stock/
+```
+
+### Event-Driven Architecture
+
+Generated code supports event streaming for real-time updates:
+
+```typescript
+import { cartQueryClientFactory } from './generated/ecommerce/cart/queryClient';
+import { CartStreamCommandClient } from './generated/ecommerce/cart/commandClient';
+
+// Create streaming query client
+const eventClient = cartQueryClientFactory.createEventQueryClient({
+  fetcher: fetcher,
+  onEvent: event => {
+    console.log('Cart event:', event);
+    // Handle real-time cart updates
+  },
+});
+
+// Use streaming command client
+const streamCommandClient = new CartStreamCommandClient({ fetcher });
+
+const eventStream = await streamCommandClient.addCartItem(
+  {
+    command: { productId: 'item-123', quantity: 1 },
+  },
+  { ownerId: 'user-456' },
+);
+
+// Process streaming events
+for await (const event of eventStream) {
+  console.log('Command event:', event);
+}
+```
+
+### Custom Type Guards and Validation
+
+Generated code includes runtime type validation:
+
+```typescript
+import { CartState, isCartState } from './generated/ecommerce/cart/types';
+
+// Runtime type checking
+function processCartData(data: unknown) {
+  if (isCartState(data)) {
+    // TypeScript knows data is CartState here
+    console.log('Valid cart state:', data.items.length);
+  } else {
+    throw new Error('Invalid cart data');
+  }
+}
+```
+
+### Integration with State Management
+
+Use generated clients with popular state management libraries:
+
+```typescript
+// Redux Toolkit integration
+import { createAsyncThunk, createSlice } from '@reduxjs/toolkit';
+import { cartQueryClientFactory } from './generated/ecommerce/cart/queryClient';
+
+const fetchCartState = createAsyncThunk(
+  'cart/fetchState',
+  async (ownerId: string) => {
+    const snapshotClient = cartQueryClientFactory.createSnapshotQueryClient({
+      fetcher: fetcher,
+    });
+    return await snapshotClient.singleState({ condition: { ownerId } });
+  },
+);
+
+const cartSlice = createSlice({
+  name: 'cart',
+  initialState: { items: [], loading: false },
+  reducers: {},
+  extraReducers: builder => {
+    builder.addCase(fetchCartState.pending, state => {
+      state.loading = true;
+    });
+    builder.addCase(fetchCartState.fulfilled, (state, action) => {
+      state.items = action.payload.items;
+      state.loading = false;
+    });
+  },
+});
+```
+
+### Error Handling and Retry Logic
+
+Generated clients work seamlessly with retry mechanisms:
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { CartCommandClient } from './generated/ecommerce/cart/commandClient';
+
+// Configure fetcher with retry logic
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+  retryConfig: {
+    maxRetries: 3,
+    retryDelay: 1000,
+    retryCondition: error => error.status >= 500,
+  },
+});
+
+const commandClient = new CartCommandClient({ fetcher });
+
+// Commands automatically retry on server errors
+try {
+  const result = await commandClient.addCartItem(
+    {
+      command: { productId: 'item-123', quantity: 1 },
+    },
+    { ownerId: 'user-456' },
+  );
+} catch (error) {
+  console.error('Failed to add item after retries:', error);
+}
+```
+
+### Testing Generated Code
+
+Write unit tests for generated clients:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { CartCommandClient } from './generated/ecommerce/cart/commandClient';
+
+describe('CartCommandClient', () => {
+  it('should add item to cart', async () => {
+    const mockFetcher = {
+      request: vi.fn().mockResolvedValue({ success: true }),
+    };
+
+    const client = new CartCommandClient({
+      fetcher: mockFetcher as any,
+    });
+
+    // This will throw autoGeneratedError in generated code
+    // In real usage, you'd use a decorator interceptor
+    expect(() =>
+      client.addCartItem(
+        {
+          command: { productId: 'test', quantity: 1 },
+        },
+        { ownerId: 'user' },
+      ),
+    ).toThrow();
+  });
+});
+```
+
 ## 📋 OpenAPI Specification Requirements
 
 The generator expects OpenAPI 3.0+ specifications with specific patterns for WOW domain-driven design framework:

package/dist/cli.cjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("commander"),a=require("./index.cjs");require("@ahoo-wang/fetcher");require("yaml");require("fs");require("path");class f{getTimestamp(){return new Date().toISOString().slice(11,19)}info(e,...t){const o=this.getTimestamp();t.length>0?console.log(`[${o}] ℹ️  ${e}`,...t):console.log(`[${o}] ℹ️  ${e}`)}success(e,...t){const o=this.getTimestamp();t.length>0?console.log(`[${o}] ✅ ${e}`,...t):console.log(`[${o}] ✅ ${e}`)}error(e,...t){const o=this.getTimestamp();t.length>0?console.error(`[${o}] ❌ ${e}`,...t):console.error(`[${o}] ❌ ${e}`)}progress(e,t=0,...o){const i=this.getTimestamp(),r="  ".repeat(t);o.length>0?console.log(`[${i}] 🔄 ${r}${e}`,...o):console.log(`[${i}] 🔄 ${r}${e}`)}progressWithCount(e,t,o,i=0,...r){const s=this.getTimestamp(),p="  ".repeat(i),l=`[${e}/${t}]`;r.length>0?console.log(`[${s}] 🔄 ${p}${l} ${o}`,...r):console.log(`[${s}] 🔄 ${p}${l} ${o}`)}}function h(n){if(!n)return!1;try{const e=new URL(n);return e.protocol==="http:"||e.protocol==="https:"}catch{return n.length>0}}async function d(n){const e=new f;process.on("SIGINT",()=>{e.error("Generation interrupted by user"),process.exit(130)}),h(n.input)||(e.error("Invalid input: must be a valid file path or HTTP/HTTPS URL"),process.exit(2));try{e.info("Starting code generation...");const t={inputPath:n.input,outputDir:n.output,configPath:n.config,tsConfigFilePath:n.tsConfigFilePath,logger:e};await new a.CodeGenerator(t).generate(),e.success(`Code generation completed successfully! Files generated in: ${n.output}`)}catch(t){e.error(`Error during code generation: ${t}`),process.exit(1)}}const $="2.9.0",m={version:$};function u(){return c.program.name("fetcher-generator").description("OpenAPI Specification TypeScript code generator for Wow").version(m.version),c.program.command("generate").description("Generate TypeScript code from OpenAPI specification").requiredOption("-i, --input <file>","Input OpenAPI specification file path or URL (http/https)").option("-o, --output <path>","Output directory path","src/generated").option("-c, --config <file>","Configuration file path",a.DEFAULT_CONFIG_PATH).option("-t, --ts-config-file-path <file>","TypeScript configuration file path").option("-v, --verbose","Enable verbose logging").option("--dry-run","Show what would be generated without writing files").action(d),c.program}function g(){u().parse()}g();exports.runCLI=g;exports.setupCLI=u;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("commander"),a=require("./index.cjs");require("@ahoo-wang/fetcher");require("yaml");require("fs");require("path");class f{getTimestamp(){return new Date().toISOString().slice(11,19)}info(e,...t){const o=this.getTimestamp();t.length>0?console.log(`[${o}] ℹ️  ${e}`,...t):console.log(`[${o}] ℹ️  ${e}`)}success(e,...t){const o=this.getTimestamp();t.length>0?console.log(`[${o}] ✅ ${e}`,...t):console.log(`[${o}] ✅ ${e}`)}error(e,...t){const o=this.getTimestamp();t.length>0?console.error(`[${o}] ❌ ${e}`,...t):console.error(`[${o}] ❌ ${e}`)}progress(e,t=0,...o){const i=this.getTimestamp(),r="  ".repeat(t);o.length>0?console.log(`[${i}] 🔄 ${r}${e}`,...o):console.log(`[${i}] 🔄 ${r}${e}`)}progressWithCount(e,t,o,i=0,...r){const s=this.getTimestamp(),p="  ".repeat(i),l=`[${e}/${t}]`;r.length>0?console.log(`[${s}] 🔄 ${p}${l} ${o}`,...r):console.log(`[${s}] 🔄 ${p}${l} ${o}`)}}function h(n){if(!n)return!1;try{const e=new URL(n);return e.protocol==="http:"||e.protocol==="https:"}catch{return n.length>0}}async function d(n){const e=new f;process.on("SIGINT",()=>{e.error("Generation interrupted by user"),process.exit(130)}),h(n.input)||(e.error("Invalid input: must be a valid file path or HTTP/HTTPS URL"),process.exit(2));try{e.info("Starting code generation...");const t={inputPath:n.input,outputDir:n.output,configPath:n.config,tsConfigFilePath:n.tsConfigFilePath,logger:e};await new a.CodeGenerator(t).generate(),e.success(`Code generation completed successfully! Files generated in: ${n.output}`)}catch(t){e.error(`Error during code generation: ${t}`),process.exit(1)}}const $="2.9.1",m={version:$};function u(){return c.program.name("fetcher-generator").description("OpenAPI Specification TypeScript code generator for Wow").version(m.version),c.program.command("generate").description("Generate TypeScript code from OpenAPI specification").requiredOption("-i, --input <file>","Input OpenAPI specification file path or URL (http/https)").option("-o, --output <path>","Output directory path","src/generated").option("-c, --config <file>","Configuration file path",a.DEFAULT_CONFIG_PATH).option("-t, --ts-config-file-path <file>","TypeScript configuration file path").option("-v, --verbose","Enable verbose logging").option("--dry-run","Show what would be generated without writing files").action(d),c.program}function g(){u().parse()}g();exports.runCLI=g;exports.setupCLI=u;
 //# sourceMappingURL=cli.cjs.map

package/dist/cli.js

@@ -63,7 +63,7 @@ async function h(n) {
     e.error(`Error during code generation: ${t}`), process.exit(1);
   }
 }
-const $ = "2.9.0", d = {
+const $ = "2.9.1", d = {
   version: $
 };
 function m() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-generator",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "TypeScript code generator from OpenAPI specs for Wow domain-driven design framework. ",
   "keywords": [
     "fetch",