fs-stream-sync 2.0.21 → 2.0.22

package/lib/internal.js

@@ -1,4 +1,11 @@
 "use strict";
+/**
+ * 檔案系統流內部工具函數
+ * File System Stream Internal Utility Functions
+ *
+ * 提供開啟、關閉、銷毀流等核心功能
+ * Provides core functions for opening, closing, and destroying streams
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYM_FS_STREAM_DATA = void 0;
 exports.open = open;
@@ -9,40 +16,100 @@ exports.closeFsStreamSync = closeFsStreamSync;
 exports._destroy = _destroy;
 exports.getFsStreamData = getFsStreamData;
 const fs_1 = require("fs");
+/**
+ * 流資料符號鍵 / Stream data symbol key
+ * 用於存取流的內部資料 / Used to access stream's internal data
+ */
 exports.SYM_FS_STREAM_DATA = Symbol('FsStreamData');
+/**
+ * 開啟檔案流
+ * Open file stream
+ *
+ * 使用同步方式開啟檔案並發送相關事件
+ * Opens file synchronously and emits relevant events
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ * @param {any[]} [argv] - 額外參數 / Additional arguments
+ */
 function open(thisArgv, argv) {
     if (typeof thisArgv.fd !== 'number') {
         let fd;
         try {
+            // 使用同步方式開啟檔案 / Open file synchronously
             // @ts-ignore
             fd = (0, fs_1.openSync)(thisArgv.path, thisArgv.flags, thisArgv.mode);
         }
         catch (er) {
+            // 發生錯誤時發射錯誤事件 / Emit error on failure
             _error_emit(thisArgv, er);
             return;
         }
         thisArgv.fd = fd;
     }
+    // 發送開啟和就緒事件 / Emit open and ready events
     thisArgv.emit('open', thisArgv.fd);
     thisArgv.emit('ready');
 }
+/**
+ * 發射錯誤事件
+ * Emit error event
+ *
+ * 關閉流並發射錯誤事件
+ * Closes stream and emits error event
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ * @param {T} e - 錯誤物件 / Error object
+ */
 function _error_emit(thisArgv, e) {
     __close(thisArgv);
     thisArgv.emit('error', e);
 }
+/**
+ * 內部關閉函數
+ * Internal close function
+ *
+ * 根據 autoClose 設定決定是否銷毀流
+ * Destroys stream based on autoClose setting
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ */
 function __close(thisArgv) {
+    // 如果啟用自動關閉，則銷毀流 / Destroy stream if autoClose is enabled
     // @ts-ignore
     if (thisArgv.autoClose) {
         thisArgv.destroy();
     }
 }
+/**
+ * 錯誤回調處理
+ * Error callback handler
+ *
+ * 關閉流並執行錯誤回調
+ * Closes stream and executes error callback
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ * @param {T} e - 錯誤物件 / Error object
+ * @param {Function} callback - 回調函數 / Callback function
+ */
 function _error_callback(thisArgv, e, callback) {
     __close(thisArgv);
     callback(e);
 }
+/**
+ * 同步關閉檔案流
+ * Close file stream synchronously
+ *
+ * 同步關閉檔案描述符並發送關閉事件
+ * Closes file descriptor synchronously and emits close event
+ *
+ * @param {fs.WriteStream | fs.ReadStream | SyncWriteStream | SyncReadStream} stream - 流實例 / Stream instance
+ * @param {Function} cb - 回調函數 / Callback function
+ * @param {any} [err] - 錯誤物件 / Error object
+ */
 function closeFsStreamSync(stream, cb, err) {
     let er;
     try {
+        // 同步關閉檔案描述符 / Close file descriptor synchronously
         // @ts-ignore
         (0, fs_1.closeSync)(stream.fd);
     }
@@ -50,28 +117,52 @@ function closeFsStreamSync(stream, cb, err) {
         er = e || err;
     }
     cb(er);
+    // 標記流為已關閉 / Mark stream as closed
     // @ts-ignore
     stream.closed = true;
     if (!er) {
+        // 無錯誤時發送關閉事件 / Emit close event on success
         stream.emit('close');
     }
 }
+/**
+ * 銷毀流
+ * Destroy stream
+ *
+ * 處理流的銷毀邏輯，包括關閉檔案描述符
+ * Handles stream destruction logic including closing file descriptor
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ * @param {Error | null} error - 錯誤物件或 null / Error object or null
+ * @param {(error: Error | null) => void} callback - 完成回調 / Completion callback
+ */
 function _destroy(thisArgv, error, callback) {
+    // 檢查檔案是否已開啟 / Check if file is open
     // @ts-ignore
     const isOpen = typeof thisArgv.fd !== 'number';
     if (isOpen) {
+        // 等待開啟事件後再關閉 / Wait for open event before closing
         // @ts-ignore
         thisArgv.once('open', closeFsStreamSync.bind(null, thisArgv, callback, error));
         return;
     }
     closeFsStreamSync(thisArgv, callback);
+    // 清除檔案描述符 / Clear file descriptor
     // @ts-ignore
     thisArgv.fd = null;
 }
+/**
+ * 發射錯誤和關閉事件（下一個 tick）
+ * Emit error and close events (next tick)
+ */
 function emitErrorAndCloseNT(self, err) {
     emitErrorNT(self, err);
     emitCloseNT(self);
 }
+/**
+ * 發射關閉事件（下一個 tick）
+ * Emit close event (next tick)
+ */
 function emitCloseNT(self) {
     if (self._writableState && !self._writableState.emitClose) {
         return;
@@ -81,11 +172,29 @@ function emitCloseNT(self) {
     }
     self.emit('close');
 }
+/**
+ * 發射錯誤事件（下一個 tick）
+ * Emit error event (next tick)
+ */
 function emitErrorNT(self, err) {
     self.emit('error', err);
 }
+/**
+ * 取得流資料
+ * Get stream data
+ *
+ * 取得或初始化流的內部資料物件
+ * Gets or initializes stream's internal data object
+ *
+ * @param {IThisFsStream} thisArgv - 流實例 / Stream instance
+ * @returns {IFsStreamData} 流資料物件 / Stream data object
+ */
 function getFsStreamData(thisArgv) {
     return thisArgv[exports.SYM_FS_STREAM_DATA] = thisArgv[exports.SYM_FS_STREAM_DATA] || {};
 }
+/**
+ * 預設導出 - 內部模組
+ * Default export - internal module
+ */
 exports.default = exports;
 //# sourceMappingURL=internal.js.map

package/lib/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["internal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 檔案系統流內部工具函數\n * File System Stream Internal Utility Functions\n *\n * 提供開啟、關閉、銷毀流等核心功能\n * Provides core functions for opening, closing, and destroying streams\n */\n\nimport { ReadStream } from '../read';\nimport { WriteStream } from '../write';\nimport { SyncReadStream } from '../read-sync';\nimport { SyncWriteStream } from '../write-sync';\nimport { IFsStreamData } from './interface';\nimport fs, { openSync, closeSync } from 'fs';\n\n/**\n * 流資料符號鍵 / Stream data symbol key\n * 用於存取流的內部資料 / Used to access stream's internal data\n */\nexport const SYM_FS_STREAM_DATA = Symbol('FsStreamData')\n\n/**\n * 檔案流類型聯合 / File stream type union\n */\nexport type IThisFsStream = WriteStream | ReadStream | SyncWriteStream | SyncReadStream\n\n/**\n * 開啟檔案流\n * Open file stream\n *\n * 使用同步方式開啟檔案並發送相關事件\n * Opens file synchronously and emits relevant events\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n * @param {any[]} [argv] - 額外參數 / Additional arguments\n */\nexport function open(thisArgv: IThisFsStream, argv?: any[])\n{\n\tif (typeof thisArgv.fd !== 'number')\n\t{\n\t\tlet fd: number\n\t\ttry\n\t\t{\n\t\t\t// 使用同步方式開啟檔案 / Open file synchronously\n\t\t\t// @ts-ignore\n\t\t\tfd = openSync(thisArgv.path, thisArgv.flags, thisArgv.mode)\n\t\t}\n\t\tcatch (er)\n\t\t{\n\t\t\t// 發生錯誤時發射錯誤事件 / Emit error on failure\n\t\t\t_error_emit(thisArgv, er)\n\t\t\treturn;\n\t\t}\n\n\t\tthisArgv.fd = fd;\n\t}\n\n\t// 發送開啟和就緒事件 / Emit open and ready events\n\tthisArgv.emit('open', thisArgv.fd);\n\tthisArgv.emit('ready');\n}\n\n/**\n * 發射錯誤事件\n * Emit error event\n *\n * 關閉流並發射錯誤事件\n * Closes stream and emits error event\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n * @param {T} e - 錯誤物件 / Error object\n */\nexport function _error_emit<T extends Error>(thisArgv: IThisFsStream, e: T): void\n{\n\t__close(thisArgv)\n\tthisArgv.emit('error', e);\n}\n\n/**\n * 內部關閉函數\n * Internal close function\n *\n * 根據 autoClose 設定決定是否銷毀流\n * Destroys stream based on autoClose setting\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n */\nexport function __close(thisArgv: IThisFsStream): void\n{\n\t// 如果啟用自動關閉，則銷毀流 / Destroy stream if autoClose is enabled\n\t// @ts-ignore\n\tif (thisArgv.autoClose)\n\t{\n\t\tthisArgv.destroy();\n\t}\n}\n\n/**\n * 錯誤回調處理\n * Error callback handler\n *\n * 關閉流並執行錯誤回調\n * Closes stream and executes error callback\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n * @param {T} e - 錯誤物件 / Error object\n * @param {Function} callback - 回調函數 / Callback function\n */\nexport function _error_callback<T extends Error>(thisArgv: IThisFsStream, e: T, callback: Function): void\n{\n\t__close(thisArgv)\n\tcallback(e);\n}\n\n/**\n * 同步關閉檔案流\n * Close file stream synchronously\n *\n * 同步關閉檔案描述符並發送關閉事件\n * Closes file descriptor synchronously and emits close event\n *\n * @param {fs.WriteStream | fs.ReadStream | SyncWriteStream | SyncReadStream} stream - 流實例 / Stream instance\n * @param {Function} cb - 回調函數 / Callback function\n * @param {any} [err] - 錯誤物件 / Error object\n */\nexport function closeFsStreamSync(stream: fs.WriteStream | fs.ReadStream | SyncWriteStream | SyncReadStream,\n\tcb: Function,\n\terr?,\n)\n{\n\tlet er\n\ttry\n\t{\n\t\t// 同步關閉檔案描述符 / Close file descriptor synchronously\n\t\t// @ts-ignore\n\t\tcloseSync(stream.fd)\n\t}\n\tcatch (e)\n\t{\n\t\ter = e || err;\n\t}\n\n\tcb(er)\n\t// 標記流為已關閉 / Mark stream as closed\n\t// @ts-ignore\n\tstream.closed = true;\n\tif (!er)\n\t{\n\t\t// 無錯誤時發送關閉事件 / Emit close event on success\n\t\tstream.emit('close');\n\t}\n}\n\n/**\n * 銷毀流\n * Destroy stream\n *\n * 處理流的銷毀邏輯，包括關閉檔案描述符\n * Handles stream destruction logic including closing file descriptor\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n * @param {Error | null} error - 錯誤物件或 null / Error object or null\n * @param {(error: Error | null) => void} callback - 完成回調 / Completion callback\n */\nexport function _destroy(thisArgv: IThisFsStream, error: Error | null, callback: (error: Error | null) => void): void\n{\n\t// 檢查檔案是否已開啟 / Check if file is open\n\t// @ts-ignore\n\tconst isOpen = typeof thisArgv.fd !== 'number';\n\n\tif (isOpen)\n\t{\n\t\t// 等待開啟事件後再關閉 / Wait for open event before closing\n\t\t// @ts-ignore\n\t\tthisArgv.once('open', closeFsStreamSync.bind(null, thisArgv, callback, error));\n\t\treturn;\n\t}\n\n\tcloseFsStreamSync(thisArgv as any, callback)\n\t// 清除檔案描述符 / Clear file descriptor\n\t// @ts-ignore\n\tthisArgv.fd = null;\n}\n\n/**\n * 發射錯誤和關閉事件（下一個 tick）\n * Emit error and close events (next tick)\n */\nfunction emitErrorAndCloseNT(self, err)\n{\n\temitErrorNT(self, err);\n\temitCloseNT(self);\n}\n\n/**\n * 發射關閉事件（下一個 tick）\n * Emit close event (next tick)\n */\nfunction emitCloseNT(self)\n{\n\tif (self._writableState && !self._writableState.emitClose)\n\t{\n\t\treturn;\n\t}\n\tif (self._readableState && !self._readableState.emitClose)\n\t{\n\t\treturn;\n\t}\n\tself.emit('close');\n}\n\n/**\n * 發射錯誤事件（下一個 tick）\n * Emit error event (next tick)\n */\nfunction emitErrorNT(self, err)\n{\n\tself.emit('error', err);\n}\n\n/**\n * 取得流資料\n * Get stream data\n *\n * 取得或初始化流的內部資料物件\n * Gets or initializes stream's internal data object\n *\n * @param {IThisFsStream} thisArgv - 流實例 / Stream instance\n * @returns {IFsStreamData} 流資料物件 / Stream data object\n */\nexport function getFsStreamData(thisArgv: IThisFsStream): IFsStreamData\n{\n\treturn thisArgv[SYM_FS_STREAM_DATA] = thisArgv[SYM_FS_STREAM_DATA] || {}\n}\n\n/**\n * 預設導出 - 內部模組\n * Default export - internal module\n */\nexport default exports as typeof import('./internal');\n"]}

package/lib/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["util.ts"],"names":[],"mappings":"","sourcesContent":[""]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-stream-sync",
-  "version": "2.0.21",
+  "version": "2.0.22",
   "description": "檔案系統同步讀寫流實作，相容於 Node.js Core fs 模組 (File System synchronous read/write stream implementation, compatible with Node.js Core fs module)",
   "keywords": [
     "File System",
@@ -50,5 +50,5 @@
     "@types/node": "*",
     "tslib": "^2"
   },
-  "gitHead": "6bcfe6a585ad7e5657a40a5b0727c6281b564b60"
+  "gitHead": "6c690c4123ff9db0f807fbc9a05f509a832aee69"
 }

package/read-sync.d.ts

@@ -1,13 +1,86 @@
+/**
+ * 同步讀取流實作
+ * Synchronous Read Stream Implementation
+ *
+ * 提供同步檔案讀取流功能
+ * Provides synchronous file reading stream functionality
+ *
+ * @module fs-stream-sync/read-sync
+ */
 import { PathLike } from "fs";
 import { IFsReadStreamOptions } from './lib/interface';
 import { ReadStream } from './read';
+/**
+ * 最小緩衝池空間（位元組）
+ * Minimum pool space in bytes
+ */
 export declare const kMinPoolSpace = 128;
+/**
+ * 同步讀取流類別
+ * Synchronous Read Stream Class
+ *
+ * 提供同步檔案讀取功能，繼承自 ReadStream
+ * Provides synchronous file reading functionality, extends ReadStream
+ */
 export declare class SyncReadStream extends ReadStream {
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsReadStreamOptions} [options] - 選項 / Options
+     */
     constructor(path: PathLike, options?: string | IFsReadStreamOptions);
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create(): typeof createSyncReadStream;
+    /**
+     * 開啟檔案流
+     * Open file stream
+     *
+     * 同步開啟檔案並發送 open 和 ready 事件
+     * Opens file synchronously and emits open and ready events
+     */
     open(): void;
+    /**
+     * 內部讀取方法
+     * Internal read method
+     *
+     * 從檔案同步讀取資料到緩衝池
+     * Reads data from file synchronously into buffer pool
+     *
+     * @param {number} n - 要讀取的位元組數 / Number of bytes to read
+     * @returns {boolean | this} 讀取結果 / Read result
+     */
     _read(n: number): boolean | this;
+    /**
+     * 銷毀流
+     * Destroy stream
+     *
+     * 清理資源並關閉檔案描述符
+     * Cleans up resources and closes file descriptor
+     *
+     * @param {Error | null} error - 錯誤物件或 null / Error object or null
+     * @param {(error: Error | null) => void} callback - 完成回調 / Completion callback
+     */
     _destroy(error: Error | null, callback: (error: Error | null) => void): void;
 }
+/**
+ * 建立同步讀取流
+ * Create synchronous read stream
+ *
+ * 工廠函數，建立 SyncReadStream 實例
+ * Factory function that creates a SyncReadStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsReadStreamOptions} [options] - 選項 / Options
+ * @returns {SyncReadStream} 同步讀取流實例 / Synchronous read stream instance
+ */
 export declare function createSyncReadStream(path: PathLike, options?: string | IFsReadStreamOptions): SyncReadStream;
+/**
+ * 預設導出 - SyncReadStream 類別
+ * Default export - SyncReadStream class
+ */
 export default SyncReadStream;

package/read-sync.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * 同步讀取流實作
+ * Synchronous Read Stream Implementation
+ *
+ * 提供同步檔案讀取流功能
+ * Provides synchronous file reading stream functionality
+ *
+ * @module fs-stream-sync/read-sync
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncReadStream = exports.kMinPoolSpace = void 0;
 exports.createSyncReadStream = createSyncReadStream;
@@ -7,26 +16,74 @@ const fs_1 = tslib_1.__importDefault(require("fs"));
 const internal_1 = require("./lib/internal");
 const internal_2 = tslib_1.__importDefault(require("./lib/internal"));
 const read_1 = require("./read");
+/**
+ * 最小緩衝池空間（位元組）
+ * Minimum pool space in bytes
+ */
 exports.kMinPoolSpace = 128;
+/**
+ * 共享緩衝池 - 用於減少記憶體分配
+ * Shared buffer pool - used to reduce memory allocations
+ */
 let pool;
+/**
+ * 緩衝池碎片陣列 - 儲存可回收的緩衝區
+ * Pool fragments array - stores recyclable buffers
+ */
 const poolFragments = [];
+/**
+ * 分配新的緩衝池
+ * Allocate new buffer pool
+ *
+ * 嘗試從碎片陣列重用緩衝區，否則建立新緩衝區
+ * Tries to reuse buffer from fragments array, otherwise creates new buffer
+ *
+ * @param {number} poolSize - 緩衝池大小 / Pool size in bytes
+ */
 function allocNewPool(poolSize) {
     if (poolFragments.length > 0) {
+        // 重用現有的緩衝區碎片 / Reuse existing buffer fragment
         pool = poolFragments.pop();
     }
     else {
+        // 建立新的不安全緩衝區 / Create new unsafe buffer
         pool = Buffer.allocUnsafe(poolSize);
     }
     pool.used = 0;
 }
+/**
+ * 同步讀取流類別
+ * Synchronous Read Stream Class
+ *
+ * 提供同步檔案讀取功能，繼承自 ReadStream
+ * Provides synchronous file reading functionality, extends ReadStream
+ */
 class SyncReadStream extends read_1.ReadStream {
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsReadStreamOptions} [options] - 選項 / Options
+     */
     constructor(path, options) {
         // @ts-ignore
         super(path, options);
     }
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create() {
         return createSyncReadStream;
     }
+    /**
+     * 開啟檔案流
+     * Open file stream
+     *
+     * 同步開啟檔案並發送 open 和 ready 事件
+     * Opens file synchronously and emits open and ready events
+     */
     open() {
         if (typeof (0, internal_1.getFsStreamData)(this) !== 'boolean') {
             this[internal_1.SYM_FS_STREAM_DATA].opened = true;
@@ -39,47 +96,60 @@ class SyncReadStream extends read_1.ReadStream {
             this.emit('ready');
         }
     }
+    /**
+     * 內部讀取方法
+     * Internal read method
+     *
+     * 從檔案同步讀取資料到緩衝池
+     * Reads data from file synchronously into buffer pool
+     *
+     * @param {number} n - 要讀取的位元組數 / Number of bytes to read
+     * @returns {boolean | this} 讀取結果 / Read result
+     */
     _read(n) {
+        // 等待檔案開啟 / Wait for file to open
         if (typeof this.fd !== 'number') {
             return this.once('open', function () {
                 // @ts-ignore
                 this._read(n);
             });
         }
+        // 檢查流是否已銷毀 / Check if stream is destroyed
         if (this.destroyed) {
             return;
         }
+        // 檢查緩衝池空間是否足夠 / Check if pool has enough space
         if (!pool || pool.length - pool.used < exports.kMinPoolSpace) {
-            // discard the old pool.
+            // 丟棄舊緩衝池並建立新的 / Discard old pool and allocate new one
             allocNewPool(this.readableHighWaterMark);
         }
         const thisPool = pool;
         let toRead = Math.min(pool.length - pool.used, n);
         const start = pool.used;
+        // 計算實際可讀取位元組數 / Calculate actual readable bytes
         if (this.pos !== undefined) {
             toRead = Math.min(this.end - this.pos + 1, toRead);
         }
         else {
             toRead = Math.min(this.end - this.bytesRead + 1, toRead);
         }
-        // already read everything we were supposed to read!
-        // treat as EOF.
+        // 已讀取完所有資料，視為 EOF / Already read everything, treat as EOF
         if (toRead <= 0) {
             return this.push(null);
         }
         try {
-            // the actual read.
+            // 實際讀取操作 / The actual read operation
             let bytesRead = fs_1.default.readSync(this.fd, pool, pool.used, toRead, this.pos);
             let b = null;
-            // Now that we know how much data we have actually read, re-wind the
-            // 'used' field if we can, and otherwise allow the remainder of our
-            // reservation to be used as a new pool later.
+            // 調整緩衝池已使用標記或回收剩餘空間
+            // Adjust pool used marker or recycle remaining space
             if (start + toRead === thisPool.used && thisPool === pool) {
                 thisPool.used += bytesRead - toRead;
             }
             else if (toRead - bytesRead > exports.kMinPoolSpace) {
                 poolFragments.push(thisPool.slice(start + bytesRead, start + toRead));
             }
+            // 建立結果緩衝區 / Create result buffer
             if (bytesRead > 0) {
                 this.bytesRead += bytesRead;
                 b = thisPool.slice(start, start + bytesRead);
@@ -87,24 +157,50 @@ class SyncReadStream extends read_1.ReadStream {
             this.push(b);
         }
         catch (er) {
+            // 發生錯誤時自動關閉流 / Auto-close stream on error
             if (this.autoClose) {
                 this.destroy();
             }
             this.emit('error', er);
         }
-        // move the pool positions, and internal position for reading.
+        // 更新位置和緩衝池標記 / Update position and pool markers
         if (this.pos !== undefined) {
             this.pos += toRead;
         }
         pool.used += toRead;
     }
+    /**
+     * 銷毀流
+     * Destroy stream
+     *
+     * 清理資源並關閉檔案描述符
+     * Cleans up resources and closes file descriptor
+     *
+     * @param {Error | null} error - 錯誤物件或 null / Error object or null
+     * @param {(error: Error | null) => void} callback - 完成回調 / Completion callback
+     */
     _destroy(error, callback) {
         internal_2.default._destroy(this, error, callback);
     }
 }
 exports.SyncReadStream = SyncReadStream;
+/**
+ * 建立同步讀取流
+ * Create synchronous read stream
+ *
+ * 工廠函數，建立 SyncReadStream 實例
+ * Factory function that creates a SyncReadStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsReadStreamOptions} [options] - 選項 / Options
+ * @returns {SyncReadStream} 同步讀取流實例 / Synchronous read stream instance
+ */
 function createSyncReadStream(path, options) {
     return new SyncReadStream(path, options);
 }
+/**
+ * 預設導出 - SyncReadStream 類別
+ * Default export - SyncReadStream class
+ */
 exports.default = SyncReadStream;
 //# sourceMappingURL=read-sync.js.map

package/read-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-sync.js","sourceRoot":"","sources":["read-sync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 同步讀取流實作\n * Synchronous Read Stream Implementation\n *\n * 提供同步檔案讀取流功能\n * Provides synchronous file reading stream functionality\n *\n * @module fs-stream-sync/read-sync\n */\n\nimport fs from 'fs';\nimport { PathLike } from \"fs\";\nimport { IFsReadStreamOptions } from './lib/interface';\nimport { getFsStreamData, SYM_FS_STREAM_DATA } from './lib/internal';\nimport internal from \"./lib/internal\";\nimport { ReadStream } from './read'\n\n/**\n * 最小緩衝池空間（位元組）\n * Minimum pool space in bytes\n */\nexport const kMinPoolSpace = 128;\n\n/**\n * 共享緩衝池 - 用於減少記憶體分配\n * Shared buffer pool - used to reduce memory allocations\n */\nlet pool;\n\n/**\n * 緩衝池碎片陣列 - 儲存可回收的緩衝區\n * Pool fragments array - stores recyclable buffers\n */\nconst poolFragments = [];\n\n/**\n * 分配新的緩衝池\n * Allocate new buffer pool\n *\n * 嘗試從碎片陣列重用緩衝區，否則建立新緩衝區\n * Tries to reuse buffer from fragments array, otherwise creates new buffer\n *\n * @param {number} poolSize - 緩衝池大小 / Pool size in bytes\n */\nfunction allocNewPool(poolSize: number)\n{\n\tif (poolFragments.length > 0)\n\t{\n\t\t// 重用現有的緩衝區碎片 / Reuse existing buffer fragment\n\t\tpool = poolFragments.pop();\n\t}\n\telse\n\t{\n\t\t// 建立新的不安全緩衝區 / Create new unsafe buffer\n\t\tpool = Buffer.allocUnsafe(poolSize);\n\t}\n\tpool.used = 0;\n}\n\n/**\n * 同步讀取流類別\n * Synchronous Read Stream Class\n *\n * 提供同步檔案讀取功能，繼承自 ReadStream\n * Provides synchronous file reading functionality, extends ReadStream\n */\nexport class SyncReadStream extends ReadStream\n{\n\t/**\n\t * 構造函數\n\t * Constructor\n\t *\n\t * @param {PathLike} path - 檔案路徑 / File path\n\t * @param {string | IFsReadStreamOptions} [options] - 選項 / Options\n\t */\n\tconstructor(path: PathLike, options?: string | IFsReadStreamOptions)\n\t{\n\t\t// @ts-ignore\n\t\tsuper(path, options)\n\t}\n\n\t/**\n\t * 建立函數別名\n\t * Factory method alias\n\t */\n\tstatic override get create()\n\t{\n\t\treturn createSyncReadStream\n\t}\n\n\t/**\n\t * 開啟檔案流\n\t * Open file stream\n\t *\n\t * 同步開啟檔案並發送 open 和 ready 事件\n\t * Opens file synchronously and emits open and ready events\n\t */\n\toverride open(): void\n\t{\n\t\tif (typeof getFsStreamData(this) !== 'boolean')\n\t\t{\n\t\t\tthis[SYM_FS_STREAM_DATA].opened = true\n\t\t\tinternal.open(this)\n\t\t\tthis.read();\n\t\t}\n\t\telse if (this[SYM_FS_STREAM_DATA].opened === true)\n\t\t{\n\t\t\tthis[SYM_FS_STREAM_DATA].opened = false\n\t\t\tthis.emit('open', this.fd);\n\t\t\tthis.emit('ready');\n\t\t}\n\t}\n\n\t/**\n\t * 內部讀取方法\n\t * Internal read method\n\t *\n\t * 從檔案同步讀取資料到緩衝池\n\t * Reads data from file synchronously into buffer pool\n\t *\n\t * @param {number} n - 要讀取的位元組數 / Number of bytes to read\n\t * @returns {boolean | this} 讀取結果 / Read result\n\t */\n\toverride _read(n: number)\n\t{\n\t\t// 等待檔案開啟 / Wait for file to open\n\t\tif (typeof this.fd !== 'number')\n\t\t{\n\t\t\treturn this.once('open', function ()\n\t\t\t{\n\t\t\t\t// @ts-ignore\n\t\t\t\tthis._read(n);\n\t\t\t});\n\t\t}\n\n\t\t// 檢查流是否已銷毀 / Check if stream is destroyed\n\t\tif (this.destroyed)\n\t\t{\n\t\t\treturn;\n\t\t}\n\n\t\t// 檢查緩衝池空間是否足夠 / Check if pool has enough space\n\t\tif (!pool || pool.length - pool.used < kMinPoolSpace)\n\t\t{\n\t\t\t// 丟棄舊緩衝池並建立新的 / Discard old pool and allocate new one\n\t\t\tallocNewPool(this.readableHighWaterMark);\n\t\t}\n\n\t\tconst thisPool = pool;\n\t\tlet toRead = Math.min(pool.length - pool.used, n);\n\t\tconst start = pool.used;\n\n\t\t// 計算實際可讀取位元組數 / Calculate actual readable bytes\n\t\tif (this.pos !== undefined)\n\t\t{\n\t\t\ttoRead = Math.min(this.end - this.pos + 1, toRead);\n\t\t}\n\t\telse\n\t\t{\n\t\t\ttoRead = Math.min(this.end - this.bytesRead + 1, toRead);\n\t\t}\n\n\t\t// 已讀取完所有資料，視為 EOF / Already read everything, treat as EOF\n\t\tif (toRead <= 0)\n\t\t{\n\t\t\treturn this.push(null);\n\t\t}\n\n\t\ttry\n\t\t{\n\t\t\t// 實際讀取操作 / The actual read operation\n\t\t\tlet bytesRead = fs.readSync(this.fd, pool, pool.used, toRead, this.pos);\n\n\t\t\tlet b = null;\n\t\t\t// 調整緩衝池已使用標記或回收剩餘空間\n\t\t\t// Adjust pool used marker or recycle remaining space\n\t\t\tif (start + toRead === thisPool.used && thisPool === pool)\n\t\t\t{\n\t\t\t\tthisPool.used += bytesRead - toRead;\n\t\t\t}\n\t\t\telse if (toRead - bytesRead > kMinPoolSpace)\n\t\t\t{\n\t\t\t\tpoolFragments.push(thisPool.slice(start + bytesRead, start + toRead));\n\t\t\t}\n\n\t\t\t// 建立結果緩衝區 / Create result buffer\n\t\t\tif (bytesRead > 0)\n\t\t\t{\n\t\t\t\tthis.bytesRead += bytesRead;\n\t\t\t\tb = thisPool.slice(start, start + bytesRead);\n\t\t\t}\n\n\t\t\tthis.push(b);\n\t\t}\n\t\tcatch (er)\n\t\t{\n\t\t\t// 發生錯誤時自動關閉流 / Auto-close stream on error\n\t\t\tif (this.autoClose)\n\t\t\t{\n\t\t\t\tthis.destroy();\n\t\t\t}\n\t\t\tthis.emit('error', er);\n\t\t}\n\n\t\t// 更新位置和緩衝池標記 / Update position and pool markers\n\t\tif (this.pos !== undefined)\n\t\t{\n\t\t\tthis.pos += toRead;\n\t\t}\n\t\tpool.used += toRead;\n\t}\n\n\t/**\n\t * 銷毀流\n\t * Destroy stream\n\t *\n\t * 清理資源並關閉檔案描述符\n\t * Cleans up resources and closes file descriptor\n\t *\n\t * @param {Error | null} error - 錯誤物件或 null / Error object or null\n\t * @param {(error: Error | null) => void} callback - 完成回調 / Completion callback\n\t */\n\toverride _destroy(error: Error | null, callback: (error: Error | null) => void): void\n\t{\n\t\tinternal._destroy(this, error, callback)\n\t}\n}\n\n/**\n * 建立同步讀取流\n * Create synchronous read stream\n *\n * 工廠函數，建立 SyncReadStream 實例\n * Factory function that creates a SyncReadStream instance\n *\n * @param {PathLike} path - 檔案路徑 / File path\n * @param {string | IFsReadStreamOptions} [options] - 選項 / Options\n * @returns {SyncReadStream} 同步讀取流實例 / Synchronous read stream instance\n */\nexport function createSyncReadStream(path: PathLike, options?: string | IFsReadStreamOptions)\n{\n\treturn new SyncReadStream(path, options)\n}\n\n/**\n * 預設導出 - SyncReadStream 類別\n * Default export - SyncReadStream class\n */\nexport default SyncReadStream\n"]}

package/read.d.ts

@@ -1,22 +1,71 @@
+/**
+ * fs-stream-sync - 檔案系統流處理工具
+ *
+ * 這個模組提供了檔案系統的同步和異步流處理功能，包括讀取和寫入流。
+ *
+ * @module fs-stream-sync
+ * @author bluelovers
+ */
 import { PathLike } from "fs";
 import fs from 'fs';
 import { IFsReadStreamOptions, IFsStreamData, IFsStreamState, IFsWriteStreamOptions } from './lib/interface';
 import { SYM_FS_STREAM_DATA } from './lib/internal';
+/**
+ * 讀取流類 - 擴展 Node.js 的 ReadStream
+ *
+ * 這個類提供了檔案讀取流的功能，支援同步和異步操作。
+ *
+ * @class ReadStream
+ * @extends fs.ReadStream
+ */
 export declare class ReadStream extends fs.ReadStream {
+    /** 是否自動關閉 */
     protected autoClose: boolean;
+    /** 檔案標誌 */
     protected flags: string;
+    /** 檔案描述符 */
     fd: number;
+    /** 檔案模式 */
     protected mode: number;
+    /** 當前位置 */
     protected pos: number;
+    /** 是否已關閉 */
     protected closed: boolean;
+    /** 是否已銷毀 */
     protected destroyed: boolean;
+    /** 可寫狀態 */
     protected _writableState: IFsStreamState;
+    /** 可讀狀態 */
     protected _readableState: IFsStreamState;
+    /** 流資料 */
     protected [SYM_FS_STREAM_DATA]: IFsStreamData;
+    /** 結束位置 */
     protected end: number;
+    /**
+     * 構造函數
+     *
+     * @param {PathLike} path 檔案路徑
+     * @param {string | IFsWriteStreamOptions} [options] 選項
+     */
     constructor(path: PathLike, options?: string | IFsWriteStreamOptions);
+    /** 創建函數別名 */
     static get create(): typeof createReadStream;
+    /**
+     * 打開流
+     *
+     * 這個函數會打開檔案流，並設置相關狀態。
+     */
     open(): void;
 }
+/**
+ * 創建讀取流
+ *
+ * 這個函數會創建一個 ReadStream 實例。
+ *
+ * @param {PathLike} path 檔案路徑
+ * @param {string | IFsReadStreamOptions} [options] 選項
+ * @returns {ReadStream} 讀取流實例
+ */
 export declare function createReadStream(path: PathLike, options?: string | IFsReadStreamOptions): ReadStream;
+/** 預設導出 - ReadStream 類 */
 export default ReadStream;