@luxisjs/requester

函数式协议无关请求框架

纯函数式架构，不可变数据，函数组合。

安装

npm install @luxisjs/requester

快速开始

方式一：使用默认实现

使用预设的 HTTP/Stream/WebSocket 实现，开箱即用：

import { createDefaultRequester } from '@luxisjs/requester'

const requester = createDefaultRequester()

// HTTP 请求
const data = await requester.request({ url: '/api/data' })

// SSE 流式请求
for await (const chunk of requester.stream({ url: '/api/stream' })) {
  console.log(chunk)
}

// WebSocket 连接
const ws = await requester.connect({ url: 'wss://api.example.com' })
ws.onMessage((data) => console.log(data))
ws.send({ hello: 'world' })

方式二：自定义实现

完全掌控中间件和能力注册：

import {
  createRequester,
  createRuntime,
  createCapabilityRegistry,
  tap,
  catchError,
  createHttpCapability,
  createAuthHttpCapability,
} from '@luxisjs/requester'

// 1. 创建能力注册表
const registry = createCapabilityRegistry()

// 2. 注册自定义能力
registry.register('http', createHttpCapability(async ({ url, method = 'GET', body }) => {
  const res = await fetch(url, { method, body: JSON.stringify(body) })
  return res.json()
}))

// 3. 创建运行时
const runtime = createRuntime(registry, [
  tap((ctx) => console.log('Request:', ctx.config.url)),
  catchError((ctx, err) => console.error('Error:', err)),
])

// 4. 创建请求器
const { request } = createRequester(runtime)

// 5. 使用
const data = await request({ url: '/api/data' })

中间件

compose

组合多个中间件为一个管道：

import { compose, tap, catchError } from '@luxisjs/requester'

const pipeline = compose([
  tap((ctx) => console.log('Before')),
  tap((ctx) => console.log('After')),
])

tap

在请求前后执行副作用：

import { tap } from '@luxisjs/requester'

const logMiddleware = tap(
  (ctx) => console.log('Request:', ctx.config.url),
  (ctx) => console.log('Response:', ctx.response)
)

catchError

捕获中间件链中的错误：

import { catchError } from '@luxisjs/requester'

const errorHandler = catchError((ctx, err) => {
  console.error('Error:', err)
  ctx.error = err
})

pipe

组合两个中间件：

import { pipe, tap } from '@luxisjs/requester'

const combined = pipe(
  tap((ctx) => console.log('Step 1')),
  tap((ctx) => console.log('Step 2'))
)

merge

合并多个中间件为单个：

import { merge, tap } from '@luxisjs/requester'

const merged = merge(
  tap((ctx) => console.log('A')),
  tap((ctx) => console.log('B'))
)

能力注册

手动注册

import {
  createCapabilityRegistry,
  createHttpCapability,
  fetchStreamCapability,
  webSocketCapability,
} from '@luxisjs/requester'

const registry = createCapabilityRegistry()

// 注册 HTTP 能力
registry.register('http', fetchHttpCapability)

// 或使用工厂函数创建
registry.register('http', createHttpCapability(async (config) => {
  // 自定义实现
  return fetch(config.url).then(r => r.json())
}))

// 注册 Stream 能力
registry.register('stream', fetchStreamCapability)

// 注册 WebSocket 能力
registry.register('socket', webSocketCapability)

运行时辅助函数

import { createRuntime, registerHttp, registerStream, registerSocket } from '@luxisjs/requester'

const runtime = createRuntime()

// 注册能力并返回新运行时（保持不可变性）
const withHttp = registerHttp(runtime, fetchHttpCapability)
const withStream = registerStream(withHttp, fetchStreamCapability)
const withSocket = registerStream(withStream, webSocketCapability)

带认证的 HTTP 能力

import { createAuthHttpCapability } from '@luxisjs/requester'

const authHttp = createAuthHttpCapability(() => {
  const token = localStorage.getItem('token')
  return `Bearer ${token}`
})

registry.register('http', authHttp)

类型系统

// 协议类型
type Protocol = 'http' | 'sse' | 'websocket'

// HTTP 配置
interface HttpConfig {
  url: string
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
  headers?: Record<string, string>
  body?: unknown
  timeout?: number
}

// Stream 配置
interface StreamConfig {
  url: string
  method?: 'GET' | 'POST' | 'PUT'
  headers?: Record<string, string>
  body?: unknown
}

// Socket 配置
interface SocketConfig {
  url: string
}

// 连接接口
interface Connection {
  send(data: unknown): void
  close(): void
  onOpen(handler: () => void): void
  onMessage(handler: (data: unknown) => void): void
  onClose(handler: () => void): void
  onError(handler: (error: unknown) => void): void
}

// 运行时上下文
interface RuntimeContext<C = unknown> {
  protocol: Protocol
  config: C
  response?: unknown
  stream?: AsyncIterable<unknown>
  connection?: Connection
  metadata: Map<string, unknown>
  error?: unknown
}

// 中间件类型
type Middleware<C = unknown> = (
  ctx: RuntimeContext<C>,
  next: () => Promise<void>
) => Promise<void>

架构

业务代码
    │
    ▼
createRequester(runtime)
    │
    ▼
dispatch(runtime, ctx)
    │
    ▼
compose([...middlewares, execute])
    │
    ▼
registry.resolve(type)
    │
    ▼
注册的 capability 实现

导出摘要

| 导出 | 说明 | |------|------| | createRequester | 创建请求器实例 | | createDefaultRequester | 创建带默认实现的请求器 | | createRuntime | 创建运行时 | | createCapabilityRegistry | 创建能力注册表 | | compose | 组合中间件 | | tap | 前后钩子中间件 | | catchError | 错误处理中间件 | | pipe | 组合两个中间件 | | merge | 合并多个中间件 | | fetchHttpCapability | Fetch HTTP 实现 | | createAuthHttpCapability | 带认证的 HTTP 实现 | | fetchStreamCapability | Fetch Stream 实现 | | webSocketCapability | WebSocket 实现 |

License

MIT