yeow-api 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.3.5",
+    "version": "0.3.7",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/core.ts

@@ -54,6 +54,8 @@ export { assets, read as assetsRead, readSync as assetsReadSync,
     extract as assetsExtract, extractSync as assetsExtractSync,
     extractDir as assetsExtractDir, extractDirSync as assetsExtractDirSync } from './assets.js';
 export { path } from './path.js';
+export { createReadStream, createWriteStream } from './fs.js';
+export type { ReadStream, WriteStream } from './fs.js';
 export { listen, respond, close, request, requestSync } from './http.js';
 export type { RespondOptions } from './http.js';
 export { logError } from './log-error.js';
@@ -106,6 +108,6 @@ export type { WorkerOptions } from './worker.js';
 export {
     stringToBytes, stringToBytesAsync,
     bytesToString, bytesToStringAsync,
-    gzipCompress, gzipCompressSync,
-    gzipDecompress, gzipDecompressSync,
+    Gzip,
 } from './util.js';
+export type { GzipCompressor, GzipDecompressor } from './util.js';

package/src/fs.ts

@@ -1,5 +1,7 @@
 type FsLevel = 'plugin' | 'server' | 'outer';
 
+import { stringToBytes } from './util.js';
+
 function _sendFs(payload: Record<string, unknown>): unknown {
   const r = $send('fs', payload);
   if (r == null) return undefined;
@@ -114,12 +116,23 @@ function _makeFs(level: FsLevel) {
     return (_sendFs({ t: t('getServerPath') }) as { path: string }).path;
   }
 
+  async function createReadStream(path: string): Promise<ReadStream> {
+    const r = await _sendFsAsync({ t: t('openRead'), p: { path } }) as { id: string };
+    return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
+  }
+
+  async function createWriteStream(path: string): Promise<WriteStream> {
+    const r = await _sendFsAsync({ t: t('openWrite'), p: { path } }) as { id: string };
+    return _makeWriteStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
+  }
+
   return {
     readFile, readFileSync, readFileBase64, readFileBase64Sync,
     writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
     appendFile, appendFileSync,
     exists, existsSync, isDirectory, isDirectorySync,
     deleteFile, deleteFileSync, mkdir, mkdirSync, list, listSync,
+    createReadStream, createWriteStream,
     // outer 专属能力（systemPaths / getServerPath）
     ...(level === 'outer' ? { systemPaths, systemPathsSync, getServerPath, getServerPathSync } : {}),
   };
@@ -154,3 +167,75 @@ export const mkdir = fs.mkdir;
 export const mkdirSync = fs.mkdirSync;
 export const list = fs.list;
 export const listSync = fs.listSync;
+export const createReadStream = fs.createReadStream;
+export const createWriteStream = fs.createWriteStream;
+
+// ── 流式读写（有状态句柄；背压 = 显式响应——每个操作 await 结果后才发起下一块）──
+
+/** 文件读流：read() 一次返回一块（默认 1 MiB），null = EOF；可 for await。 */
+export interface ReadStream {
+  read(maxBytes?: number): Promise<Uint8Array | null>;
+  close(): Promise<void>;
+  [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+
+/** 文件写流：write(chunk) 等到写入完成（显式响应背压），end() 冲刷并关闭。 */
+export interface WriteStream {
+  write(chunk: Uint8Array | string): Promise<void>;
+  /** 冲刷缓冲并关闭（调用后不可再 write）。 */
+  end(): Promise<void>;
+  close(): Promise<void>;
+}
+
+function _makeReadStream(
+  op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
+  id: string,
+): ReadStream {
+  let closed = false;
+  const check = () => { if (closed) throw new Error('read stream closed'); };
+  return {
+    async read(maxBytes?: number) {
+      check();
+      const r = await op('read', { id, maxBytes }) as { data?: string; eof?: boolean };
+      if (r.eof) return null;
+      return Uint8Array.fromBase64(r.data as string);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await op('close', { id });
+    },
+    async *[Symbol.asyncIterator]() {
+      while (true) {
+        const chunk = await this.read();
+        if (chunk === null) break;
+        yield chunk;
+      }
+    },
+  };
+}
+
+function _makeWriteStream(
+  op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
+  id: string,
+): WriteStream {
+  let closed = false;
+  const check = () => { if (closed) throw new Error('write stream closed'); };
+  return {
+    async write(chunk: Uint8Array | string) {
+      check();
+      const data = typeof chunk === 'string' ? stringToBytes(chunk) : chunk;
+      await op('write', { id, data: data.toBase64() });
+    },
+    async end() {
+      check();
+      closed = true;
+      await op('end', { id });
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await op('close', { id });
+    },
+  };
+}

package/src/path.ts

@@ -3,15 +3,20 @@ export function join(...segments: (string | null | undefined)[]): string {
 }
 
 export function basename(p: string): string {
-    const s = p.replace(/\/+$/, '');
-    const i = s.lastIndexOf('/');
+    // 双分隔符：兼容 Windows 反斜杠路径（fs 通道在 Windows 上返回 `\` 路径）
+    const s = p.replace(/[\\/]+$/, '');
+    const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
     return i === -1 ? s : s.substring(i + 1);
 }
 
 export function dirname(p: string): string {
-    const s = p.replace(/\/+$/, '');
-    const i = s.lastIndexOf('/');
-    return i === -1 ? '.' : s.substring(0, i) || '/';
+    const s = p.replace(/[\\/]+$/, '');
+    const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
+    if (i === -1) return '.';
+    const d = s.substring(0, i);
+    // 根：POSIX `/`；Windows 盘符根（`C:\` → `C:\`，`C:\a` → `C:` 兼容）
+    if (d === '') return s.length >= 3 && s[1] === ':' ? s.substring(0, 3) : '/';
+    return d;
 }
 
 export function extname(p: string): string {

package/src/util.ts

@@ -1,8 +1,9 @@
-// util 通道：gzip 压缩/解压 + UTF-8 ↔ 字节转换。
+// util 通道：gzip 压缩/解压（一次性 + 流式分块）+ UTF-8 ↔ 字节转换。
 //
 // 协议层字节数据以 base64 字符串承载（引擎原生 Uint8Array.toBase64()/fromBase64()
 // 负责转换）——本模块输入输出一律 Uint8Array / string，**不暴露 base64**。
-// encode/decode 的语义是 buffer ↔ 字符串；无流式接口（一次性整体处理）。
+// 流式 API：背压基于**显式响应**——每个操作 await 结果后才发起下一块；
+// 块大小由调用方决定（建议 ≥256 KiB，摊销跨线程往返开销）。
 
 /** util 通道同步调用：err → 抛 Error。 */
 function send<T>(t: string, p: Record<string, unknown>): T {
@@ -52,26 +53,90 @@ export function bytesToStringAsync(bytes: Uint8Array): Promise<string> {
   return sendAsync<{ data: string }>('decode.utf8', { data: bytes.toBase64() }).then((r) => r.data);
 }
 
-// ── gzip ──────────────────────────────────────────────────────────
+// ── Gzip 命名空间（一次性 + 流式）────────────────────────────────
 
-/** gzip 压缩（level 0-9，默认引擎默认级别）。输入 string 视为 UTF-8 文本。 */
-export function gzipCompress(data: Uint8Array | string, level?: number): Promise<Uint8Array> {
-  return sendAsync<{ data: string }>('gzip.compress', { data: toB64(data), level })
-    .then((r) => Uint8Array.fromBase64(r.data));
+/** 分块压缩器：write(chunk) → 该块的压缩输出（可能为空）；finish() → 剩余输出（含 GZIP 尾）。 */
+export interface GzipCompressor {
+  /** 压缩一块输入，返回输出块（可能为空）。 */
+  write(chunk: Uint8Array | string): Promise<Uint8Array>;
+  /** 结束压缩，返回剩余输出（含 GZIP 尾）；此后 write 不可再调用。 */
+  finish(): Promise<Uint8Array>;
+  close(): Promise<void>;
 }
 
-/** gzip 压缩（同步版）。 */
-export function gzipCompressSync(data: Uint8Array | string, level?: number): Uint8Array {
-  return Uint8Array.fromBase64(send<{ data: string }>('gzip.compress', { data: toB64(data), level }).data);
+/** 分块解压器：write(chunk) → 该块可解出的输出（可能为空）；finish() → 剩余输出。 */
+export interface GzipDecompressor {
+  /** 喂入一块压缩数据，返回解压输出块（可能为空）。 */
+  write(chunk: Uint8Array | string): Promise<Uint8Array>;
+  /** 标记输入结束，返回剩余解压输出（数据不完整会 reject）。 */
+  finish(): Promise<Uint8Array>;
+  close(): Promise<void>;
 }
 
-/** gzip 解压（输出上限 256 MiB，超限报错——防压缩炸弹）。 */
-export function gzipDecompress(data: Uint8Array | string): Promise<Uint8Array> {
-  return sendAsync<{ data: string }>('gzip.decompress', { data: toB64(data) })
-    .then((r) => Uint8Array.fromBase64(r.data));
-}
+export const Gzip = {
+  /** 一次性 gzip 压缩（level 0-9，默认引擎默认级别）。输入 string 视为 UTF-8 文本。 */
+  compress(data: Uint8Array | string, level?: number): Promise<Uint8Array> {
+    return sendAsync<{ data: string }>('gzip.compress', { data: toB64(data), level })
+      .then((r) => Uint8Array.fromBase64(r.data));
+  },
+  /** 一次性 gzip 压缩（同步版）。 */
+  compressSync(data: Uint8Array | string, level?: number): Uint8Array {
+    return Uint8Array.fromBase64(send<{ data: string }>('gzip.compress', { data: toB64(data), level }).data);
+  },
+  /** 一次性 gzip 解压（输出上限 256 MiB，超限报错——防压缩炸弹；上限可在 config.yml util 段调整）。 */
+  decompress(data: Uint8Array | string): Promise<Uint8Array> {
+    return sendAsync<{ data: string }>('gzip.decompress', { data: toB64(data) })
+      .then((r) => Uint8Array.fromBase64(r.data));
+  },
+  /** 一次性 gzip 解压（同步版）。 */
+  decompressSync(data: Uint8Array | string): Uint8Array {
+    return Uint8Array.fromBase64(send<{ data: string }>('gzip.decompress', { data: toB64(data) }).data);
+  },
+  /** 创建分块压缩器（流式管道）：create → write×n → finish → close。 */
+  async createCompressor(options?: { level?: number }): Promise<GzipCompressor> {
+    const r = await sendAsync<{ id: string }>('gzip.compressor.create', { level: options?.level });
+    let closed = false;
+    const check = () => { if (closed) throw new Error('compressor closed'); };
+    return {
+      write: (chunk) => {
+        check();
+        return sendAsync<{ data: string }>('gzip.compressor.write', { id: r.id, data: toB64(chunk) })
+          .then((x) => Uint8Array.fromBase64(x.data));
+      },
+      finish: () => {
+        check();
+        return sendAsync<{ data: string }>('gzip.compressor.finish', { id: r.id })
+          .then((x) => Uint8Array.fromBase64(x.data));
+      },
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        await sendAsync('gzip.compressor.close', { id: r.id });
+      },
+    };
+  },
+  /** 创建分块解压器（流式管道）：create → write×n → finish → close。 */
+  async createDecompressor(): Promise<GzipDecompressor> {
+    const r = await sendAsync<{ id: string }>('gzip.decompressor.create', {});
+    let closed = false;
+    const check = () => { if (closed) throw new Error('decompressor closed'); };
+    return {
+      write: (chunk) => {
+        check();
+        return sendAsync<{ data: string }>('gzip.decompressor.write', { id: r.id, data: toB64(chunk) })
+          .then((x) => Uint8Array.fromBase64(x.data));
+      },
+      finish: () => {
+        check();
+        return sendAsync<{ data: string }>('gzip.decompressor.finish', { id: r.id })
+          .then((x) => Uint8Array.fromBase64(x.data));
+      },
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        await sendAsync('gzip.decompressor.close', { id: r.id });
+      },
+    };
+  },
+};
 
-/** gzip 解压（同步版）。 */
-export function gzipDecompressSync(data: Uint8Array | string): Uint8Array {
-  return Uint8Array.fromBase64(send<{ data: string }>('gzip.decompress', { data: toB64(data) }).data);
-}