docs: 添加文档

Author: Wyatex

README.md

@@ -1,23 +1,125 @@
-# tsdown-starter
+# @wyatex/event-source-parse
 
-A starter for creating a TypeScript package.
+[简体中文](./README.zh-CN.md)
 
-## Development
+[![NPM Version](https://img.shields.io/npm/v/@wyatex/event-source-parse?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@wyatex/event-source-parse)
+[![License](https://img.shields.io/npm/l/@wyatex/event-source-parse?style=flat-square&color=blue)](https://github.com/wyatex/event-source-parse/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/wyatex/event-source-parse/ci.yml?style=flat-square&label=build)](https://github.com/wyatex/event-source-parse/actions)
+[![Codecov](https://img.shields.io/codecov/c/github/wyatex/event-source-parse?style=flat-square)](https://codecov.io/gh/wyatex/event-source-parse)
 
-- Install dependencies:
+A robust, zero-dependency parser for **Server-Sent Events (SSE)** streams.
+
+This library is designed to consume `ReadableStream` or `AsyncIterable` and parse them into event messages. It is written in TypeScript and optimized for modern runtimes like Node.js, Bun, Deno, and Browsers.
+
+### ✨ Key Features
+
+*   **Universal Support**: Works with standard Web API `ReadableStream` and Node.js streams.
+*   **🧩 Azure OpenAI Compatible**: Includes a specific flush mechanism to handle streams that don't end with a newline (common in Azure OpenAI / LangChain scenarios), ensuring no data is lost.
+*   **TypeScript**: Fully typed with TS sources included.
+*   **Lightweight**: No runtime dependencies.
+
+## 📦 Installation
 
 ```bash
-npm install
+# npm
+npm install @wyatex/event-source-parse
+
+# bun
+bun add @wyatex/event-source-parse
+
+# pnpm
+pnpm add @wyatex/event-source-parse
+
+# yarn
+yarn add @wyatex/event-source-parse
 ```
 
-- Run the unit tests:
+## 🚀 Usage
 
-```bash
-npm run test
+### 1. High-Level Usage (Recommended)
+
+The easiest way to consume a stream is using the helper function `convertEventStreamToIterableReadableDataStream`. This converts a raw SSE stream directly into an async iterable of data strings.
+
+```typescript
+import { convertEventStreamToIterableReadableDataStream } from '@wyatex/event-source-parse'
+
+async function consumeStream() {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    body: JSON.stringify({ stream: true, /* ... */ }),
+  })
+
+  if (!response.body) throw new Error('No body')
+
+  // Convert the raw stream into an iterable of data strings
+  const stream = convertEventStreamToIterableReadableDataStream(response.body)
+
+  for await (const chunk of stream) {
+    console.log('Received chunk:', chunk)
+  }
+}
+```
+
+### 2. Low-Level Control (Pipeline)
+
+If you need full control over the parsing process (e.g., accessing `event` ID, `retry` time, or custom event types), you can compose the parser functions manually.
+
+```typescript
+import { getBytes, getLines, getMessages } from '@wyatex/event-source-parse'
+
+async function parseCustomStream(stream: ReadableStream) {
+  // 1. Create a message handler
+  const onMessage = (msg) => {
+    console.log('Event:', msg.event)
+    console.log('Data:', msg.data)
+    console.log('ID:', msg.id)
+  }
+
+  // 2. Create the pipeline
+  // getMessages -> processes lines into EventSourceMessage objects
+  // getLines    -> processes raw bytes into lines
+  const processLine = getMessages(onMessage)
+  const processChunk = getLines(processLine)
+
+  // 3. Start reading bytes from the stream
+  await getBytes(stream, processChunk)
+}
+```
+
+### 3. Handling Metadata Events
+
+The high-level helpers allow you to hook into specific events like `metadata` without disrupting the main data flow.
+
+```typescript
+const stream = convertEventStreamToIterableReadableDataStream(
+  response.body,
+  (metadata) => {
+    console.log('Received metadata:', metadata)
+  }
+)
 ```
 
-- Build the library:
+## 🛠️ Development
+
+This project uses **Bun** for development.
 
 ```bash
-npm run build
+# Install dependencies
+bun install
+
+# Run tests
+bun run test
+
+# Run tests with coverage
+bun run test:coverage
+
+# Lint code
+bun run lint
+
+# Build library
+bun run build
 ```
+
+## 📄 License
+
+MIT

README.zh-CN.md

@@ -0,0 +1,125 @@
+# @wyatex/event-source-parse
+
+[English](./README.md)
+
+[![NPM Version](https://img.shields.io/npm/v/@wyatex/event-source-parse?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@wyatex/event-source-parse)
+[![License](https://img.shields.io/npm/l/@wyatex/event-source-parse?style=flat-square&color=blue)](https://github.com/wyatex/event-source-parse/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/wyatex/event-source-parse/ci.yml?style=flat-square&label=build)](https://github.com/wyatex/event-source-parse/actions)
+[![Codecov](https://img.shields.io/codecov/c/github/wyatex/event-source-parse?style=flat-square)](https://codecov.io/gh/wyatex/event-source-parse)
+
+一个健壮的、零依赖的 **Server-Sent Events (SSE)** 流解析器。
+
+该库旨在接收 `ReadableStream` 或 `AsyncIterable` 并将其解析为标准事件消息。它完全使用 TypeScript 编写，并针对 Node.js、Bun、Deno 和现代浏览器等运行时进行了优化。
+
+### ✨ 主要特性
+
+*   **通用支持**：同时支持标准 Web API `ReadableStream` 和 Node.js 流。
+*   **🧩 Azure OpenAI 兼容**：内置了特殊的刷新（flush）机制，能够处理不以换行符结尾的流（这在 Azure OpenAI / LangChain 场景中很常见），确保最后一条消息不会丢失。
+*   **TypeScript**：完全类型化，分发包中包含 TS 源码。
+*   **轻量级**：无运行时依赖。
+
+## 📦 安装
+
+```bash
+# npm
+npm install @wyatex/event-source-parse
+
+# bun
+bun add @wyatex/event-source-parse
+
+# pnpm
+pnpm add @wyatex/event-source-parse
+
+# yarn
+yarn add @wyatex/event-source-parse
+```
+
+## 🚀 使用方法
+
+### 1. 高级用法（推荐）
+
+消费流数据最简单的方法是使用辅助函数 `convertEventStreamToIterableReadableDataStream`。它可以直接将原始 SSE 流转换为由 `data` 字符串组成的异步可迭代对象（Async Iterable）。
+
+```typescript
+import { convertEventStreamToIterableReadableDataStream } from '@wyatex/event-source-parse'
+
+async function consumeStream() {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    body: JSON.stringify({ stream: true, /* ... */ }),
+  })
+
+  if (!response.body) throw new Error('No body')
+
+  // 将原始流转换为数据字符串的迭代器
+  const stream = convertEventStreamToIterableReadableDataStream(response.body)
+
+  for await (const chunk of stream) {
+    console.log('收到数据块:', chunk)
+  }
+}
+```
+
+### 2. 低级控制（管道模式）
+
+如果你需要完全控制解析过程（例如获取 `event` ID、`retry` 重试时间或自定义事件类型），可以手动组合解析器函数。
+
+```typescript
+import { getBytes, getLines, getMessages } from '@wyatex/event-source-parse'
+
+async function parseCustomStream(stream: ReadableStream) {
+  // 1. 创建消息处理器
+  const onMessage = (msg) => {
+    console.log('事件类型:', msg.event)
+    console.log('数据内容:', msg.data)
+    console.log('事件ID:', msg.id)
+  }
+
+  // 2. 创建处理管道
+  // getMessages -> 将行数据处理成 EventSourceMessage 对象
+  // getLines    -> 将原始字节处理成行
+  const processLine = getMessages(onMessage)
+  const processChunk = getLines(processLine)
+
+  // 3. 开始从流中读取字节
+  await getBytes(stream, processChunk)
+}
+```
+
+### 3. 处理元数据事件
+
+高级辅助函数允许你在不中断主数据流的情况下，通过回调钩入特定事件（如 `metadata`）。
+
+```typescript
+const stream = convertEventStreamToIterableReadableDataStream(
+  response.body,
+  (metadata) => {
+    console.log('收到元数据:', metadata)
+  }
+)
+```
+
+## 🛠️ 本地开发
+
+本项目使用 **Bun** 进行开发。
+
+```bash
+# 安装依赖
+bun install
+
+# 运行测试
+bun run test
+
+# 运行带覆盖率的测试
+bun run test:coverage
+
+# 代码风格检查 (Lint)
+bun run lint
+
+# 构建库
+bun run build
+```
+
+## 📄 许可证
+
+MIT

package.json

@@ -15,8 +15,8 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -49,6 +49,7 @@
     "vitest": "^4.0.15"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
   }
 }