fs-stream-sync 2.0.21 → 2.0.22

package/read.js

@@ -1,31 +1,72 @@
 "use strict";
+/**
+ * fs-stream-sync - 檔案系統流處理工具
+ *
+ * 這個模組提供了檔案系統的同步和異步流處理功能，包括讀取和寫入流。
+ *
+ * @module fs-stream-sync
+ * @author bluelovers
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadStream = void 0;
 exports.createReadStream = createReadStream;
 const tslib_1 = require("tslib");
 const fs_1 = tslib_1.__importDefault(require("fs"));
 const internal_1 = require("./lib/internal");
+/**
+ * 讀取流類 - 擴展 Node.js 的 ReadStream
+ *
+ * 這個類提供了檔案讀取流的功能，支援同步和異步操作。
+ *
+ * @class ReadStream
+ * @extends fs.ReadStream
+ */
 // @ts-ignore
 class ReadStream extends fs_1.default.ReadStream {
+    /**
+     * 構造函數
+     *
+     * @param {PathLike} path 檔案路徑
+     * @param {string | IFsWriteStreamOptions} [options] 選項
+     */
     constructor(path, options) {
+        // 調用父類構造函數
         // @ts-ignore
         super(path, options);
+        // 初始化流資料
         (0, internal_1.getFsStreamData)(this);
     }
+    /** 創建函數別名 */
     static get create() {
         return createReadStream;
     }
+    /**
+     * 打開流
+     *
+     * 這個函數會打開檔案流，並設置相關狀態。
+     */
     open() {
         if (typeof (0, internal_1.getFsStreamData)(this) !== 'boolean') {
             this[internal_1.SYM_FS_STREAM_DATA].opened = true;
+            // 調用父類的 open 方法
             // @ts-ignore
             fs_1.default.ReadStream.prototype.open.call(this);
         }
     }
 }
 exports.ReadStream = ReadStream;
+/**
+ * 創建讀取流
+ *
+ * 這個函數會創建一個 ReadStream 實例。
+ *
+ * @param {PathLike} path 檔案路徑
+ * @param {string | IFsReadStreamOptions} [options] 選項
+ * @returns {ReadStream} 讀取流實例
+ */
 function createReadStream(path, options) {
     return new ReadStream(path, options);
 }
+/** 預設導出 - ReadStream 類 */
 exports.default = ReadStream;
 //# sourceMappingURL=read.js.map

package/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["read.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAmGH,4CAGC;;AAnGD,oDAAoB;AAEpB,6CAAqE;AAErE;;;;;;;GAOG;AACH,aAAa;AACb,MAAa,UAAW,SAAQ,YAAE,CAAC,UAAU;IAmC5C;;;;;OAKG;IACH,YAAY,IAAc,EAAE,OAAwC;QAEnE,WAAW;QACX,aAAa;QACb,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAEpB,SAAS;QACT,IAAA,0BAAe,EAAC,IAAI,CAAC,CAAA;IACtB,CAAC;IAED,aAAa;IACb,MAAM,KAAK,MAAM;QAEhB,OAAO,gBAAgB,CAAA;IACxB,CAAC;IAED;;;;OAIG;IACH,IAAI;QAEH,IAAI,OAAO,IAAA,0BAAe,EAAC,IAAI,CAAC,KAAK,SAAS,EAC9C,CAAC;YACA,IAAI,CAAC,6BAAkB,CAAC,CAAC,MAAM,GAAG,IAAI,CAAA;YACtC,gBAAgB;YAChB,aAAa;YACb,YAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACxC,CAAC;IACF,CAAC;CACD;AAxED,gCAwEC;AAED;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,IAAc,EAAE,OAAuC;IAEvF,OAAO,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACrC,CAAC;AAED,0BAA0B;AAC1B,kBAAe,UAAU,CAAA","sourcesContent":["/**\n * fs-stream-sync - 檔案系統流處理工具\n * \n * 這個模組提供了檔案系統的同步和異步流處理功能，包括讀取和寫入流。\n * \n * @module fs-stream-sync\n * @author bluelovers\n */\n\nimport { PathLike } from \"fs\";\nimport fs from 'fs';\nimport { IFsReadStreamOptions, IFsStreamData, IFsStreamState, IFsWriteStreamOptions } from './lib/interface';\nimport { getFsStreamData, SYM_FS_STREAM_DATA } from './lib/internal';\n\n/**\n * 讀取流類 - 擴展 Node.js 的 ReadStream\n * \n * 這個類提供了檔案讀取流的功能，支援同步和異步操作。\n * \n * @class ReadStream\n * @extends fs.ReadStream\n */\n// @ts-ignore\nexport class ReadStream extends fs.ReadStream\n{\n\t/** 是否自動關閉 */\n\tprotected autoClose: boolean\n\n\t/** 檔案標誌 */\n\tprotected flags: string\n\n\t/** 檔案描述符 */\n\tfd: number\n\n\t/** 檔案模式 */\n\tprotected mode: number\n\n\t/** 當前位置 */\n\tprotected pos: number\n\n\t/** 是否已關閉 */\n\tprotected override closed: boolean\n\n\t/** 是否已銷毀 */\n\tprotected override destroyed: boolean\n\n\t/** 可寫狀態 */\n\tprotected _writableState: IFsStreamState\n\n\t/** 可讀狀態 */\n\tprotected _readableState: IFsStreamState\n\n\t/** 流資料 */\n\tprotected [SYM_FS_STREAM_DATA]: IFsStreamData\n\n\t/** 結束位置 */\n\tprotected end: number\n\n\t/**\n\t * 構造函數\n\t * \n\t * @param {PathLike} path 檔案路徑\n\t * @param {string | IFsWriteStreamOptions} [options] 選項\n\t */\n\tconstructor(path: PathLike, options?: string | IFsWriteStreamOptions)\n\t{\n\t\t// 調用父類構造函數\n\t\t// @ts-ignore\n\t\tsuper(path, options)\n\n\t\t// 初始化流資料\n\t\tgetFsStreamData(this)\n\t}\n\n\t/** 創建函數別名 */\n\tstatic get create()\n\t{\n\t\treturn createReadStream\n\t}\n\n\t/**\n\t * 打開流\n\t * \n\t * 這個函數會打開檔案流，並設置相關狀態。\n\t */\n\topen()\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\t// 調用父類的 open 方法\n\t\t\t// @ts-ignore\n\t\t\tfs.ReadStream.prototype.open.call(this)\n\t\t}\n\t}\n}\n\n/**\n * 創建讀取流\n * \n * 這個函數會創建一個 ReadStream 實例。\n * \n * @param {PathLike} path 檔案路徑\n * @param {string | IFsReadStreamOptions} [options] 選項\n * @returns {ReadStream} 讀取流實例\n */\nexport function createReadStream(path: PathLike, options?: string | IFsReadStreamOptions)\n{\n\treturn new ReadStream(path, options)\n}\n\n/** 預設導出 - ReadStream 類 */\nexport default ReadStream\n\n"]}

package/write-sync.d.ts

@@ -1,18 +1,118 @@
+/**
+ * 同步寫入流實作
+ * Synchronous Write Stream Implementation
+ *
+ * 提供同步檔案寫入流功能
+ * Provides synchronous file writing stream functionality
+ *
+ * @module fs-stream-sync/write-sync
+ */
 import { PathLike } from "fs";
 import { IFsWriteStreamOptions } from './lib/interface';
 import { WriteStream } from './write';
+/**
+ * 同步寫入流類別
+ * Synchronous Write Stream Class
+ *
+ * 提供同步檔案寫入功能，繼承自 WriteStream
+ * Provides synchronous file writing functionality, extends WriteStream
+ */
 export declare class SyncWriteStream extends WriteStream {
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+     */
     constructor(path: PathLike, options?: string | IFsWriteStreamOptions);
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create(): typeof createSyncWriteStream;
+    /**
+     * 開啟檔案流
+     * Open file stream
+     *
+     * 同步開啟檔案並發送 open 和 ready 事件
+     * Opens file synchronously and emits open and ready events
+     */
     open(): void;
+    /**
+     * 寫入資料
+     * Write data
+     *
+     * 將資料寫入流，檢查流狀態後呼叫父類方法
+     * Writes data to stream, checks stream state before calling parent method
+     *
+     * @param {any} chunk - 要寫入的資料 / Data to write
+     * @param {(error: Error | null | undefined) => void} [cb] - 回調函數 / Callback function
+     * @returns {boolean} 寫入結果 / Write result
+     */
     write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean;
+    /**
+     * 寫入資料（帶編碼）
+     * Write data with encoding
+     *
+     * @param {any} chunk - 要寫入的資料 / Data to write
+     * @param {string} [encoding] - 編碼格式 / Encoding
+     * @param {(error: Error | null | undefined) => void} [cb] - 回調函數 / Callback function
+     * @returns {boolean} 寫入結果 / Write result
+     */
     write(chunk: any, encoding?: string, cb?: (error: Error | null | undefined) => void): boolean;
     /**
-     * @fixme a unknow bug make stream.write only run once
+     * 內部寫入方法
+     * Internal write method
+     *
+     * 同步寫入資料到檔案
+     * Writes data to file synchronously
+     *
+     * @fixme 存在未知錯誤導致 stream.write 只能執行一次
+     * @fixme Unknown bug makes stream.write only run once
+     *
+     * @param {Buffer} chunk - 要寫入的緩衝區 / Buffer to write
+     * @param {string} encoding - 編碼格式（未使用）/ Encoding (unused)
+     * @param {Function} callback - 完成回調 / Completion callback
+     * @returns {boolean | this} 寫入結果 / Write result
      */
     _write(chunk: Buffer, encoding: string, callback: Function): boolean | this;
+    /**
+     * 關閉流
+     * Close stream
+     *
+     * 關閉檔案流並發送 close 事件
+     * Closes file stream and emits close event
+     *
+     * @param {Function} [cb] - 關閉回調 / Close callback
+     */
     close(cb?: Function): void;
+    /**
+     * 銷毀流
+     * 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 write stream
+ *
+ * 工廠函數，建立 SyncWriteStream 實例
+ * Factory function that creates a SyncWriteStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+ * @returns {SyncWriteStream} 同步寫入流實例 / Synchronous write stream instance
+ */
 export declare function createSyncWriteStream(path: PathLike, options?: string | IFsWriteStreamOptions): SyncWriteStream;
+/**
+ * 預設導出 - SyncWriteStream 類別
+ * Default export - SyncWriteStream class
+ */
 export default SyncWriteStream;

package/write-sync.js

@@ -1,3 +1,12 @@
+/**
+ * 同步寫入流實作
+ * Synchronous Write Stream Implementation
+ *
+ * 提供同步檔案寫入流功能
+ * Provides synchronous file writing stream functionality
+ *
+ * @module fs-stream-sync/write-sync
+ */
 'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncWriteStream = void 0;
@@ -8,14 +17,39 @@ const errors_1 = require("./lib/errors");
 const internal_1 = require("./lib/internal");
 const internal_2 = tslib_1.__importDefault(require("./lib/internal"));
 const write_1 = require("./write");
+/**
+ * 同步寫入流類別
+ * Synchronous Write Stream Class
+ *
+ * 提供同步檔案寫入功能，繼承自 WriteStream
+ * Provides synchronous file writing functionality, extends WriteStream
+ */
 class SyncWriteStream extends write_1.WriteStream {
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+     */
     constructor(path, options) {
         // @ts-ignore
         super(path, options);
     }
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create() {
         return createSyncWriteStream;
     }
+    /**
+     * 開啟檔案流
+     * 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;
@@ -34,6 +68,7 @@ class SyncWriteStream extends write_1.WriteStream {
             throw new NodeLikeError(EnumFsStreamErrorCode.ERR_STREAM_WRITE_AFTER_END, `write after end`)
         }
         */
+        // 檢查流是否已銷毀 / Check if stream is destroyed
         if (this._writableState.destroyed) {
             throw new errors_1.NodeLikeError(errors_1.EnumFsStreamErrorCode.ERR_STREAM_DESTROYED, `Cannot call write after a stream was destroyed`);
         }
@@ -41,57 +76,110 @@ class SyncWriteStream extends write_1.WriteStream {
         return super.write(chunk, ...argv);
     }
     /**
-     * @fixme a unknow bug make stream.write only run once
+     * 內部寫入方法
+     * Internal write method
+     *
+     * 同步寫入資料到檔案
+     * Writes data to file synchronously
+     *
+     * @fixme 存在未知錯誤導致 stream.write 只能執行一次
+     * @fixme Unknown bug makes stream.write only run once
+     *
+     * @param {Buffer} chunk - 要寫入的緩衝區 / Buffer to write
+     * @param {string} encoding - 編碼格式（未使用）/ Encoding (unused)
+     * @param {Function} callback - 完成回調 / Completion callback
+     * @returns {boolean | this} 寫入結果 / Write result
      */
     _write(chunk, encoding, callback) {
         let self = this;
         //console.dir({chunk, encoding, callback} );
+        // 驗證資料類型 / Validate data type
         if (!(chunk instanceof Buffer)) {
             return this.emit('error', new Error('Invalid data'));
         }
+        // 等待檔案開啟 / Wait for file to open
         if (typeof this.fd !== 'number') {
             return this.once('open', function () {
                 self._write(chunk, encoding, callback);
             });
         }
         try {
+            // 同步寫入檔案 / Write to file synchronously
             let bytes = fs_1.default.writeSync(this.fd, chunk, 0, chunk.length, this.pos);
             this.bytesWritten += bytes;
         }
         catch (e) {
+            // 發生錯誤時呼叫錯誤回調 / Call error callback on failure
             internal_2.default._error_callback(this, e, callback);
         }
+        // 更新寫入位置 / Update write position
         if (this.pos !== undefined) {
             this.pos += chunk.length;
         }
     }
+    /**
+     * 關閉流
+     * Close stream
+     *
+     * 關閉檔案流並發送 close 事件
+     * Closes file stream and emits close event
+     *
+     * @param {Function} [cb] - 關閉回調 / Close callback
+     */
     close(cb) {
         if (cb) {
             if (this.closed) {
+                // 已關閉，直接執行回調 / Already closed, execute callback directly
                 cb();
                 return;
             }
             else {
+                // 監聽 close 事件 / Listen for close event
                 // @ts-ignore
                 this.on('close', cb);
             }
         }
-        // If we are not autoClosing, we should call
-        // destroy on 'finish'.
+        // 若非自動關閉模式，在 finish 時銷毀
+        // If not auto-closing, destroy on 'finish'
         if (!this.autoClose) {
             this.on('finish', this.destroy.bind(this));
         }
-        // we use end() instead of destroy() because of
-        // https://github.com/nodejs/node/issues/2006
+        // 使用 end() 而非 destroy() 因為 Node.js issue #2006
+        // Use end() instead of destroy() due to https://github.com/nodejs/node/issues/2006
         this.end();
     }
+    /**
+     * 銷毀流
+     * 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.SyncWriteStream = SyncWriteStream;
+/**
+ * 建立同步寫入流
+ * Create synchronous write stream
+ *
+ * 工廠函數，建立 SyncWriteStream 實例
+ * Factory function that creates a SyncWriteStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+ * @returns {SyncWriteStream} 同步寫入流實例 / Synchronous write stream instance
+ */
 function createSyncWriteStream(path, options) {
     return new SyncWriteStream(path, options);
 }
+/**
+ * 預設導出 - SyncWriteStream 類別
+ * Default export - SyncWriteStream class
+ */
 exports.default = SyncWriteStream;
 //# sourceMappingURL=write-sync.js.map

package/write-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-sync.js","sourceRoot":"","sources":["write-sync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 同步寫入流實作\n * Synchronous Write Stream Implementation\n *\n * 提供同步檔案寫入流功能\n * Provides synchronous file writing stream functionality\n *\n * @module fs-stream-sync/write-sync\n */\n\n'use strict';\n\nimport fs from \"fs\";\nimport { PathLike } from \"fs\";\nimport { EnumFsStreamErrorCode, NodeLikeError } from './lib/errors';\nimport {\n\tIFsStream,\n\tIFsStreamState,\n\tIFsStreamOptions,\n\tIFsWriteStreamOptions,\n\tIFsStreamData,\n\tIFsPath,\n} from './lib/interface';\nimport { getFsStreamData, SYM_FS_STREAM_DATA } from './lib/internal';\nimport internal from \"./lib/internal\";\nimport { WriteStream } from './write'\n\n/**\n * 同步寫入流類別\n * Synchronous Write Stream Class\n *\n * 提供同步檔案寫入功能，繼承自 WriteStream\n * Provides synchronous file writing functionality, extends WriteStream\n */\nexport class SyncWriteStream extends WriteStream\n{\n\t/**\n\t * 構造函數\n\t * Constructor\n\t *\n\t * @param {PathLike} path - 檔案路徑 / File path\n\t * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options\n\t */\n\tconstructor(path: PathLike, options?: string | IFsWriteStreamOptions)\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 createSyncWriteStream\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}\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 * Write data\n\t *\n\t * 將資料寫入流，檢查流狀態後呼叫父類方法\n\t * Writes data to stream, checks stream state before calling parent method\n\t *\n\t * @param {any} chunk - 要寫入的資料 / Data to write\n\t * @param {(error: Error | null | undefined) => void} [cb] - 回調函數 / Callback function\n\t * @returns {boolean} 寫入結果 / Write result\n\t */\n\toverride write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean;\n\t/**\n\t * 寫入資料（帶編碼）\n\t * Write data with encoding\n\t *\n\t * @param {any} chunk - 要寫入的資料 / Data to write\n\t * @param {string} [encoding] - 編碼格式 / Encoding\n\t * @param {(error: Error | null | undefined) => void} [cb] - 回調函數 / Callback function\n\t * @returns {boolean} 寫入結果 / Write result\n\t */\n\toverride write(chunk: any, encoding?: string, cb?: (error: Error | null | undefined) => void): boolean;\n\toverride write(chunk: any, ...argv)\n\t{\n\t\t/*\n\t\tif (this.closed)\n\t\t{\n\t\t\tthrow new NodeLikeError(EnumFsStreamErrorCode.ERR_STREAM_WRITE_AFTER_END, `write after end`)\n\t\t}\n\t\t*/\n\t\t// 檢查流是否已銷毀 / Check if stream is destroyed\n\t\tif (this._writableState.destroyed)\n\t\t{\n\t\t\tthrow new NodeLikeError(EnumFsStreamErrorCode.ERR_STREAM_DESTROYED, `Cannot call write after a stream was destroyed`)\n\t\t}\n\n\t\t//console.dir({chunk,argv} );\n\n\t\treturn super.write(chunk, ...argv)\n\t}\n\n\t/**\n\t * 內部寫入方法\n\t * Internal write method\n\t *\n\t * 同步寫入資料到檔案\n\t * Writes data to file synchronously\n\t *\n\t * @fixme 存在未知錯誤導致 stream.write 只能執行一次\n\t * @fixme Unknown bug makes stream.write only run once\n\t *\n\t * @param {Buffer} chunk - 要寫入的緩衝區 / Buffer to write\n\t * @param {string} encoding - 編碼格式（未使用）/ Encoding (unused)\n\t * @param {Function} callback - 完成回調 / Completion callback\n\t * @returns {boolean | this} 寫入結果 / Write result\n\t */\n\toverride _write(chunk: Buffer, encoding: string, callback: Function)\n\t{\n\t\tlet self = this\n\n\t\t//console.dir({chunk, encoding, callback} );\n\n\t\t// 驗證資料類型 / Validate data type\n\t\tif (!(chunk instanceof Buffer))\n\t\t{\n\t\t\treturn this.emit('error', new Error('Invalid data'));\n\t\t}\n\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\tself._write(chunk, encoding, callback);\n\t\t\t});\n\t\t}\n\n\t\ttry\n\t\t{\n\t\t\t// 同步寫入檔案 / Write to file synchronously\n\t\t\tlet bytes = fs.writeSync(this.fd, chunk, 0, chunk.length, this.pos);\n\n\t\t\tthis.bytesWritten += bytes;\n\t\t}\n\t\tcatch (e)\n\t\t{\n\t\t\t// 發生錯誤時呼叫錯誤回調 / Call error callback on failure\n\t\t\tinternal._error_callback(this, e, callback)\n\t\t}\n\n\t\t// 更新寫入位置 / Update write position\n\t\tif (this.pos !== undefined)\n\t\t{\n\t\t\tthis.pos += chunk.length;\n\t\t}\n\t}\n\n\t/**\n\t * 關閉流\n\t * Close stream\n\t *\n\t * 關閉檔案流並發送 close 事件\n\t * Closes file stream and emits close event\n\t *\n\t * @param {Function} [cb] - 關閉回調 / Close callback\n\t */\n\toverride close(cb?: Function)\n\t{\n\t\tif (cb)\n\t\t{\n\t\t\tif (this.closed)\n\t\t\t{\n\t\t\t\t// 已關閉，直接執行回調 / Already closed, execute callback directly\n\t\t\t\tcb();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t// 監聽 close 事件 / Listen for close event\n\t\t\t\t// @ts-ignore\n\t\t\t\tthis.on('close', cb);\n\t\t\t}\n\t\t}\n\n\t\t// 若非自動關閉模式，在 finish 時銷毀\n\t\t// If not auto-closing, destroy on 'finish'\n\t\tif (!this.autoClose)\n\t\t{\n\t\t\tthis.on('finish', this.destroy.bind(this));\n\t\t}\n\n\t\t// 使用 end() 而非 destroy() 因為 Node.js issue #2006\n\t\t// Use end() instead of destroy() due to https://github.com/nodejs/node/issues/2006\n\t\tthis.end();\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 write stream\n *\n * 工廠函數，建立 SyncWriteStream 實例\n * Factory function that creates a SyncWriteStream instance\n *\n * @param {PathLike} path - 檔案路徑 / File path\n * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options\n * @returns {SyncWriteStream} 同步寫入流實例 / Synchronous write stream instance\n */\nexport function createSyncWriteStream(path: PathLike, options?: string | IFsWriteStreamOptions)\n{\n\treturn new SyncWriteStream(path, options)\n}\n\n/**\n * 預設導出 - SyncWriteStream 類別\n * Default export - SyncWriteStream class\n */\nexport default SyncWriteStream\n"]}

package/write.d.ts

@@ -1,29 +1,110 @@
+/**
+ * 寫入流實作
+ * Write Stream Implementation
+ *
+ * 提供非同步檔案寫入流功能，擴展 Node.js fs.WriteStream
+ * Provides asynchronous file writing stream functionality, extends Node.js fs.WriteStream
+ *
+ * @module fs-stream-sync/write
+ */
 import fs from "fs";
 import { PathLike } from 'fs';
 import { IFsPath, IFsStreamData, IFsStreamState, IFsWriteStreamOptions } from './lib/interface';
 import { SYM_FS_STREAM_DATA } from './lib/internal';
+/**
+ * 寫入流類別
+ * Write Stream Class
+ *
+ * 擴展 Node.js fs.WriteStream，提供額外功能
+ * Extends Node.js fs.WriteStream with additional functionality
+ */
 export declare class WriteStream extends fs.WriteStream {
+    /**
+     * 自動關閉標誌 / Auto close flag
+     */
     protected autoClose: boolean;
+    /**
+     * 檔案開啟標誌 / File open flags
+     */
     protected flags: string;
+    /**
+     * 檔案描述符 / File descriptor
+     */
     fd: number;
+    /**
+     * 檔案權限模式 / File permission mode
+     */
     protected mode: number;
+    /**
+     * 當前位置 / Current position
+     */
     protected pos: number;
+    /**
+     * 是否已關閉 / Whether closed
+     */
     protected closed: boolean;
+    /**
+     * 是否已銷毀 / Whether destroyed
+     */
     protected destroyed: boolean;
+    /**
+     * 可寫狀態 / Writable state
+     */
     protected _writableState: IFsStreamState;
+    /**
+     * 可讀狀態 / Readable state
+     */
     protected _readableState: IFsStreamState;
+    /**
+     * 流資料符號屬性 / Stream data symbol property
+     */
     protected [SYM_FS_STREAM_DATA]: IFsStreamData;
     /**
-     * The number of bytes written so far. Does not include data that is still queued for writing.
+     * 已寫入的位元組數（不包含佇列中的資料）
+     * Number of bytes written so far (excludes queued data)
      */
     bytesWritten: number;
     /**
-     * The path to the file the stream is writing to as specified in the first argument to fs.createWriteStream(). If path is passed as a string, then writeStream.path will be a string. If path is passed as a Buffer, then writeStream.path will be a Buffer.
+     * 檔案路徑（字串或 Buffer）
+     * File path (string or Buffer)
      */
     readonly path: IFsPath;
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+     */
     constructor(path: PathLike, options?: string | IFsWriteStreamOptions);
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create(): typeof createWriteStream;
+    /**
+     * 開啟檔案流
+     * Open file stream
+     *
+     * 開啟檔案並發送 open 和 ready 事件
+     * Opens file and emits open and ready events
+     */
     open(): void;
 }
+/**
+ * 建立寫入流
+ * Create write stream
+ *
+ * 工廠函數，建立 WriteStream 實例
+ * Factory function that creates a WriteStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+ * @returns {WriteStream} 寫入流實例 / Write stream instance
+ */
 export declare function createWriteStream(path: PathLike, options?: string | IFsWriteStreamOptions): WriteStream;
+/**
+ * 預設導出 - WriteStream 類別
+ * Default export - WriteStream class
+ */
 export default WriteStream;

package/write.js

@@ -1,24 +1,61 @@
 "use strict";
+/**
+ * 寫入流實作
+ * Write Stream Implementation
+ *
+ * 提供非同步檔案寫入流功能，擴展 Node.js fs.WriteStream
+ * Provides asynchronous file writing stream functionality, extends Node.js fs.WriteStream
+ *
+ * @module fs-stream-sync/write
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WriteStream = void 0;
 exports.createWriteStream = createWriteStream;
 const tslib_1 = require("tslib");
 const fs_1 = tslib_1.__importDefault(require("fs"));
 const internal_1 = require("./lib/internal");
+/**
+ * 寫入流類別
+ * Write Stream Class
+ *
+ * 擴展 Node.js fs.WriteStream，提供額外功能
+ * Extends Node.js fs.WriteStream with additional functionality
+ */
 // @ts-ignore
 class WriteStream extends fs_1.default.WriteStream {
+    /**
+     * 構造函數
+     * Constructor
+     *
+     * @param {PathLike} path - 檔案路徑 / File path
+     * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+     */
     constructor(path, options) {
         // @ts-ignore
         super(path, options);
+        // 初始化流資料 / Initialize stream data
         (0, internal_1.getFsStreamData)(this);
     }
+    /**
+     * 建立函數別名
+     * Factory method alias
+     */
     static get create() {
         return createWriteStream;
     }
+    /**
+     * 開啟檔案流
+     * Open file stream
+     *
+     * 開啟檔案並發送 open 和 ready 事件
+     * Opens file and emits open and ready events
+     */
     open() {
         if (!(0, internal_1.getFsStreamData)(this).opened) {
             const self = this;
             this[internal_1.SYM_FS_STREAM_DATA].opened = true;
+            // 監聽 open 事件並發送 ready 事件
+            // Listen for open event and emit ready event
             this.once('open', function () {
                 process.nextTick(function () {
                     self.emit('ready');
@@ -30,8 +67,23 @@ class WriteStream extends fs_1.default.WriteStream {
     }
 }
 exports.WriteStream = WriteStream;
+/**
+ * 建立寫入流
+ * Create write stream
+ *
+ * 工廠函數，建立 WriteStream 實例
+ * Factory function that creates a WriteStream instance
+ *
+ * @param {PathLike} path - 檔案路徑 / File path
+ * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options
+ * @returns {WriteStream} 寫入流實例 / Write stream instance
+ */
 function createWriteStream(path, options) {
     return new WriteStream(path, options);
 }
+/**
+ * 預設導出 - WriteStream 類別
+ * Default export - WriteStream class
+ */
 exports.default = WriteStream;
 //# sourceMappingURL=write.js.map

package/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["write.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA2IH,8CAGC;;AA5ID,oDAAoB;AAGpB,6CAAqE;AAErE;;;;;;GAMG;AACH,aAAa;AACb,MAAa,WAAY,SAAQ,YAAE,CAAC,WAAW;IAyD9C;;;;;;OAMG;IACH,YAAY,IAAc,EAAE,OAAwC;QAEnE,aAAa;QACb,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAEpB,kCAAkC;QAClC,IAAA,0BAAe,EAAC,IAAI,CAAC,CAAA;IACtB,CAAC;IAED;;;OAGG;IACH,MAAM,KAAK,MAAM;QAEhB,OAAO,iBAAiB,CAAA;IACzB,CAAC;IAED;;;;;;OAMG;IACH,IAAI;QAEH,IAAI,CAAC,IAAA,0BAAe,EAAC,IAAI,CAAC,CAAC,MAAM,EACjC,CAAC;YACA,MAAM,IAAI,GAAG,IAAI,CAAA;YAEjB,IAAI,CAAC,6BAAkB,CAAC,CAAC,MAAM,GAAG,IAAI,CAAA;YAEtC,yBAAyB;YACzB,6CAA6C;YAC7C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;gBAEjB,OAAO,CAAC,QAAQ,CAAC;oBAEhB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBACnB,CAAC,CAAC,CAAA;YACH,CAAC,CAAC,CAAA;YACF,aAAa;YACb,YAAE,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACzC,CAAC;IACF,CAAC;CAED;AA/GD,kCA+GC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAAC,IAAc,EAAE,OAAwC;IAEzF,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACtC,CAAC;AAED;;;GAGG;AACH,kBAAe,WAAW,CAAA","sourcesContent":["/**\n * 寫入流實作\n * Write Stream Implementation\n *\n * 提供非同步檔案寫入流功能，擴展 Node.js fs.WriteStream\n * Provides asynchronous file writing stream functionality, extends Node.js fs.WriteStream\n *\n * @module fs-stream-sync/write\n */\n\nimport fs from \"fs\";\nimport { PathLike } from 'fs';\nimport { IFsPath, IFsStreamData, IFsStreamState, IFsWriteStreamOptions } from './lib/interface';\nimport { getFsStreamData, SYM_FS_STREAM_DATA } from './lib/internal';\n\n/**\n * 寫入流類別\n * Write Stream Class\n *\n * 擴展 Node.js fs.WriteStream，提供額外功能\n * Extends Node.js fs.WriteStream with additional functionality\n */\n// @ts-ignore\nexport class WriteStream extends fs.WriteStream\n{\n\t/**\n\t * 自動關閉標誌 / Auto close flag\n\t */\n\tprotected autoClose: boolean\n\t/**\n\t * 檔案開啟標誌 / File open flags\n\t */\n\tprotected flags: string\n\t/**\n\t * 檔案描述符 / File descriptor\n\t */\n\tfd: number\n\t/**\n\t * 檔案權限模式 / File permission mode\n\t */\n\tprotected mode: number\n\t/**\n\t * 當前位置 / Current position\n\t */\n\tprotected pos: number\n\t/**\n\t * 是否已關閉 / Whether closed\n\t */\n\tprotected override closed: boolean\n\t/**\n\t * 是否已銷毀 / Whether destroyed\n\t */\n\tprotected override destroyed: boolean\n\n\t/**\n\t * 可寫狀態 / Writable state\n\t */\n\tprotected _writableState: IFsStreamState\n\t/**\n\t * 可讀狀態 / Readable state\n\t */\n\tprotected _readableState: IFsStreamState\n\n\t/**\n\t * 流資料符號屬性 / Stream data symbol property\n\t */\n\tprotected [SYM_FS_STREAM_DATA]: IFsStreamData\n\n\t/**\n\t * 已寫入的位元組數（不包含佇列中的資料）\n\t * Number of bytes written so far (excludes queued data)\n\t */\n\tpublic override bytesWritten: number\n\n\t/**\n\t * 檔案路徑（字串或 Buffer）\n\t * File path (string or Buffer)\n\t */\n\tpublic override readonly path: IFsPath\n\n\t/**\n\t * 構造函數\n\t * Constructor\n\t *\n\t * @param {PathLike} path - 檔案路徑 / File path\n\t * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options\n\t */\n\tconstructor(path: PathLike, options?: string | IFsWriteStreamOptions)\n\t{\n\t\t// @ts-ignore\n\t\tsuper(path, options)\n\n\t\t// 初始化流資料 / Initialize stream data\n\t\tgetFsStreamData(this)\n\t}\n\n\t/**\n\t * 建立函數別名\n\t * Factory method alias\n\t */\n\tstatic get create()\n\t{\n\t\treturn createWriteStream\n\t}\n\n\t/**\n\t * 開啟檔案流\n\t * Open file stream\n\t *\n\t * 開啟檔案並發送 open 和 ready 事件\n\t * Opens file and emits open and ready events\n\t */\n\topen()\n\t{\n\t\tif (!getFsStreamData(this).opened)\n\t\t{\n\t\t\tconst self = this\n\n\t\t\tthis[SYM_FS_STREAM_DATA].opened = true\n\n\t\t\t// 監聽 open 事件並發送 ready 事件\n\t\t\t// Listen for open event and emit ready event\n\t\t\tthis.once('open', function ()\n\t\t\t{\n\t\t\t\tprocess.nextTick(function ()\n\t\t\t\t{\n\t\t\t\t\tself.emit('ready')\n\t\t\t\t})\n\t\t\t})\n\t\t\t// @ts-ignore\n\t\t\tfs.WriteStream.prototype.open.call(this)\n\t\t}\n\t}\n\n}\n\n/**\n * 建立寫入流\n * Create write stream\n *\n * 工廠函數，建立 WriteStream 實例\n * Factory function that creates a WriteStream instance\n *\n * @param {PathLike} path - 檔案路徑 / File path\n * @param {string | IFsWriteStreamOptions} [options] - 選項 / Options\n * @returns {WriteStream} 寫入流實例 / Write stream instance\n */\nexport function createWriteStream(path: PathLike, options?: string | IFsWriteStreamOptions)\n{\n\treturn new WriteStream(path, options)\n}\n\n/**\n * 預設導出 - WriteStream 類別\n * Default export - WriteStream class\n */\nexport default WriteStream\n"]}