🚀 Fetcher

超轻量级 • 模块化 • TypeScript 优先 • 拦截器驱动 • LLM 流式 API 支持

Fetcher v1.2.3 发布：全面支持 Wow 框架 🚀

本次更新带来了多项重磅功能增强和架构优化，重点提升了 JWT 安全处理、事件流查询和快照查询能力，为构建高性能、高安全性的应用提供强大支撑！

✨ 核心亮点

🔒 安全增强

• JWT 解析功能：新增完整的 JWT 载荷解析能力，支持扩展 CoSec 特定属性
• 早期过期周期检查：为 JWT Token 添加安全缓冲期，提升身份验证安全性
• 依赖加固：引入 nanoid 和 reflect-metadata 作为外部依赖，增强安全基础

📊 高级查询功能

• 事件流查询 API：全新推出领域事件流接口和查询服务，支持复杂事件处理
• 快照查询端点：添加完整的快照元数据字段和查询路径，大幅提升数据查询效率
• 排序功能优化：提供直观的 asc/desc 排序方法，简化查询操作

🏗 Wow 框架增强

• 指令客户端升级：CommandHttpClient 重构为 CommandClient，提供更强类型安全
• 快照与事件流客户端：新增 SnapshotQueryClient 和 EventStreamQueryClient，专业化查询处理
• URL 处理工具：新增 interpolateUrl 和 extractPathParams 方法，简化路由管理

🛠 开发者体验

• 错误处理优化：增强事件流错误信息，包含响应内容类型详情
• 类型系统改进：引入 PartialBy 工具类型，替换枚举为静态只读类
• 测试覆盖完善：添加 MongoDB 集成测试环境，确保数据层稳定性
• 代码质量提升：全面应用 ESLint 和 Prettier 代码格式化

📚 文档更新

• 全面重写 Wow 框架集成文档，提供更丰富的示例和用法说明
• 删除重复文档内容，优化阅读体验
• 增强 API 文档的类型定义和说明

🚀 性能与稳定性

• 依赖项更新至最新稳定版本（MongoDB v5.0.31）
• 模块化重构，将功能拆分为独立文件，提升加载效率
• 增强的响应原型处理，提高事件流处理性能

🌟 为什么选择 Fetcher?

import { createLlmFetcher, LlmClient } from './llmClient';

// 使用您的 API 配置初始化 LLM 客户端
const llmFetcher = createLlmFetcher({
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY || 'your-api-key',
  model: 'gpt-3.5-turbo',
});

const llmClient = new LlmClient();

// 流式聊天完成，逐个令牌输出
async function streamChatExample() {
  const stream = await llmClient.streamChat({
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Explain quantum computing in simple terms.' },
    ],
    stream: true,
  });

  for await (const event of stream) {
    if (event.data) {
      const chunk = event.data;
      const content = chunk.choices[0]?.delta?.content || '';
      process.stdout.write(content); // 实时输出
    }
  }
}

# 安装核心包
npm install @ahoo-wang/fetcher

# 或安装所有扩展，包括 LLM 流支持
npm install @ahoo-wang/fetcher @ahoo-wang/fetcher-decorator @ahoo-wang/fetcher-eventstream @ahoo-wang/fetcher-cosec

# 使用 pnpm (推荐)
pnpm add @ahoo-wang/fetcher

# 使用 yarn
yarn add @ahoo-wang/fetcher

import { Fetcher } from '@ahoo-wang/fetcher';

// 创建 fetcher 实例
const fetcher = new Fetcher({
  baseURL: 'https://api.example.com',
  timeout: 5000,
});

// 带路径和查询参数的 GET 请求
const response = await fetcher.get('/users/{id}', {
  urlParams: {
    path: { id: 123 },
    query: { include: 'profile' },
  },
});
const userData = await response.json<User>();

// 自动 JSON 转换的 POST 请求
const createUserResponse = await fetcher.post('/users', {
  body: { name: 'John Doe', email: 'john@example.com' },
});

import { NamedFetcher } from '@ahoo-wang/fetcher';
import {
  api,
  get,
  post,
  path,
  query,
  body,
} from '@ahoo-wang/fetcher-decorator';

// 注册命名 fetcher
const apiFetcher = new NamedFetcher('api', {
  baseURL: 'https://api.example.com',
});

// 使用装饰器定义服务
@api('/users', { fetcher: 'api' })
class UserService {
  @get('/')
  getUsers(@query('limit') limit?: number): Promise<User[]> {
    throw new Error('Auto-generated');
  }

  @post('/')
  createUser(@body() user: User): Promise<User> {
    throw new Error('Auto-generated');
  }

  @get('/{id}')
  getUser(@path('id') id: number): Promise<User> {
    throw new Error('Auto-generated');
  }
}

// 使用服务
const userService = new UserService();
const users = await userService.getUsers(10);

import { Fetcher } from '@ahoo-wang/fetcher';

const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });

// 添加带排序的请求拦截器
fetcher.interceptors.request.use({
  name: 'auth-interceptor',
  order: 100,
  intercept(exchange) {
    exchange.request.headers.Authorization = 'Bearer ' + getAuthToken();
  },
});

// 添加响应拦截器用于日志记录
fetcher.interceptors.response.use({
  name: 'logging-interceptor',
  order: 10,
  intercept(exchange) {
    console.log('Response:', exchange.response.status);
  },
});

import { Fetcher } from '@ahoo-wang/fetcher';
import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';

const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
fetcher.interceptors.response.use(new EventStreamInterceptor());

// 流式实时事件 (通用 SSE)
const response = await fetcher.get('/events');
if (response.eventStream) {
  for await (const event of response.eventStream()) {
    console.log('Real-time event:', event);
  }
}

// 流式 LLM 响应，逐个令牌输出
const llmResponse = await fetcher.post('/chat/completions', {
  body: {
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true,
  },
});

if (llmResponse.jsonEventStream) {
  // 专门用于 LLM API 的 JSON SSE 事件
  for await (const event of llmResponse.jsonEventStream<ChatCompletionChunk>()) {
    const content = event.data.choices[0]?.delta?.content || '';
    process.stdout.write(content); // 实时令牌输出
  }
}

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 运行单元测试和覆盖率
pnpm test:unit

# 格式化代码
pnpm format

# 清理构建产物
pnpm clean

# 运行集成测试
#pnpm test:it

pnpm update-version <new-version>