@simplysm/storage 13.0.100 → 14.0.4

package/dist/clients/sftp-storage-client.js

@@ -1,129 +1,145 @@
 import { SdError } from "@simplysm/core-common";
 import SftpClient from "ssh2-sftp-client";
-class SftpStorageClient {
-  _client;
-  /**
-   * Connect to the SFTP server.
-   *
-   * @remarks
-   * - Must close the connection with {@link close} after use.
-   * - Do not call multiple times on the same instance (connection leak).
-   * - Use {@link StorageFactory.connect} for automatic connection/close management (recommended).
-   */
-  async connect(config) {
-    if (this._client !== void 0) {
-      throw new SdError("SFTP server is already connected. Please call close() first.");
+import fsP from "fs/promises";
+import os from "os";
+import pathMod from "path";
+/**
+ * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
+ *
+ * @remarks
+ * 직접 사용하기보다 {@link StorageFactory.connect} 사용을 권장합니다.
+ */
+export class SftpStorageClient {
+    _client;
+    /**
+     * SFTP 서버에 연결합니다.
+     *
+     * @remarks
+     * - 사용 후 {@link close}로 연결을 종료해야 합니다.
+     * - 동일 인스턴스에서 여러 번 호출하지 마세요 (연결 누수).
+     * - 자동 연결/종료 관리를 위해 {@link StorageFactory.connect} 사용을 권장합니다.
+     */
+    async connect(config) {
+        if (this._client !== undefined) {
+            throw new SdError("SFTP 서버에 이미 연결되어 있습니다. 먼저 close()를 호출해 주세요.");
+        }
+        const client = new SftpClient();
+        try {
+            if (config.password != null) {
+                await client.connect({
+                    host: config.host,
+                    port: config.port,
+                    username: config.user,
+                    password: config.password,
+                });
+            }
+            else {
+                // SSH agent + 키 파일로 인증
+                const keyPath = pathMod.join(os.homedir(), ".ssh", "id_ed25519");
+                const baseOptions = {
+                    host: config.host,
+                    port: config.port,
+                    username: config.user,
+                    ...(process.env["SSH_AUTH_SOCK"] != null ? { agent: process.env["SSH_AUTH_SOCK"] } : {}),
+                };
+                try {
+                    await client.connect({
+                        ...baseOptions,
+                        privateKey: await fsP.readFile(keyPath),
+                    });
+                }
+                catch {
+                    // privateKey 파싱 실패 (암호화된 키 등) -> agent만으로 재시도
+                    await client.connect(baseOptions);
+                }
+            }
+            this._client = client;
+        }
+        catch (err) {
+            await client.end();
+            throw err;
+        }
+    }
+    _requireClient() {
+        if (this._client === undefined) {
+            throw new SdError("SFTP 서버에 연결되어 있지 않습니다.");
+        }
+        return this._client;
+    }
+    /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
+    async mkdir(dirPath) {
+        await this._requireClient().mkdir(dirPath, true);
     }
-    const client = new SftpClient();
-    try {
-      if (config.password != null) {
-        await client.connect({
-          host: config.host,
-          port: config.port,
-          username: config.user,
-          password: config.password
-        });
-      } else {
-        const fsP = await import("fs/promises");
-        const os = await import("os");
-        const pathMod = await import("path");
-        const keyPath = pathMod.join(os.homedir(), ".ssh", "id_ed25519");
-        const baseOptions = {
-          host: config.host,
-          port: config.port,
-          username: config.user,
-          ...process.env["SSH_AUTH_SOCK"] != null ? { agent: process.env["SSH_AUTH_SOCK"] } : {}
-        };
+    async rename(fromPath, toPath) {
+        await this._requireClient().rename(fromPath, toPath);
+    }
+    /**
+     * 파일 또는 디렉토리의 존재 여부를 확인합니다.
+     *
+     * @remarks
+     * 부모 디렉토리가 존재하지 않아도 false를 반환합니다.
+     * 네트워크 오류, 권한 오류 등 모든 예외에 대해 false를 반환합니다.
+     */
+    async exists(filePath) {
         try {
-          await client.connect({
-            ...baseOptions,
-            privateKey: await fsP.readFile(keyPath)
-          });
-        } catch {
-          await client.connect(baseOptions);
+            // ssh2-sftp-client의 exists()는 false | 'd' | '-' | 'l'을 반환합니다.
+            // false: 존재하지 않음, 'd': 디렉토리, '-': 파일, 'l': 심볼릭 링크
+            const result = await this._requireClient().exists(filePath);
+            return typeof result === "string";
+        }
+        catch {
+            return false;
         }
-      }
-      this._client = client;
-    } catch (err) {
-      await client.end();
-      throw err;
     }
-  }
-  _requireClient() {
-    if (this._client === void 0) {
-      throw new SdError("Not connected to SFTP server.");
+    async list(dirPath) {
+        const list = await this._requireClient().list(dirPath);
+        return list.map((item) => ({
+            name: item.name,
+            isFile: item.type === "-",
+        }));
     }
-    return this._client;
-  }
-  /** Create a directory. Creates parent directories if they do not exist. */
-  async mkdir(dirPath) {
-    await this._requireClient().mkdir(dirPath, true);
-  }
-  async rename(fromPath, toPath) {
-    await this._requireClient().rename(fromPath, toPath);
-  }
-  /**
-   * Check whether a file or directory exists.
-   *
-   * @remarks
-   * Returns false even if the parent directory does not exist.
-   * Returns false for all exceptions including network errors and permission errors.
-   */
-  async exists(filePath) {
-    try {
-      const result = await this._requireClient().exists(filePath);
-      return typeof result === "string";
-    } catch {
-      return false;
+    async readFile(filePath) {
+        // ssh2-sftp-client의 get()은 dst가 제공되지 않으면 Buffer를 반환합니다.
+        // 타입 정의(string | WritableStream | Buffer)와 달리 실제로는 Buffer만 반환됩니다.
+        const result = (await this._requireClient().get(filePath));
+        if (result instanceof Uint8Array) {
+            return result;
+        }
+        // 타입 정의상 string도 가능하므로 방어 코드
+        if (typeof result === "string") {
+            return new TextEncoder().encode(result);
+        }
+        throw new SdError("예상하지 못한 응답 타입입니다.");
     }
-  }
-  async list(dirPath) {
-    const list = await this._requireClient().list(dirPath);
-    return list.map((item) => ({
-      name: item.name,
-      isFile: item.type === "-"
-    }));
-  }
-  async readFile(filePath) {
-    const result = await this._requireClient().get(filePath);
-    if (result instanceof Uint8Array) {
-      return result;
+    async remove(filePath) {
+        await this._requireClient().delete(filePath);
     }
-    if (typeof result === "string") {
-      return new TextEncoder().encode(result);
+    /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
+    async put(localPathOrBuffer, storageFilePath) {
+        if (typeof localPathOrBuffer === "string") {
+            await this._requireClient().fastPut(localPathOrBuffer, storageFilePath);
+        }
+        else {
+            // eslint-disable-next-line no-restricted-globals -- ssh2-sftp-client library requirement
+            await this._requireClient().put(Buffer.from(localPathOrBuffer), storageFilePath);
+        }
     }
-    throw new SdError("Unexpected response type.");
-  }
-  async remove(filePath) {
-    await this._requireClient().delete(filePath);
-  }
-  /** Upload a local file path or byte data to the remote path. */
-  async put(localPathOrBuffer, storageFilePath) {
-    if (typeof localPathOrBuffer === "string") {
-      await this._requireClient().fastPut(localPathOrBuffer, storageFilePath);
-    } else {
-      await this._requireClient().put(Buffer.from(localPathOrBuffer), storageFilePath);
+    async uploadDir(fromPath, toPath) {
+        await this._requireClient().uploadDir(fromPath, toPath);
     }
-  }
-  async uploadDir(fromPath, toPath) {
-    await this._requireClient().uploadDir(fromPath, toPath);
-  }
-  /**
-   * Close the connection.
-   *
-   * @remarks
-   * Safe to call when already closed (no error thrown).
-   * After closing, you can reconnect by calling {@link connect} again on the same instance.
-   */
-  async close() {
-    if (this._client === void 0) {
-      return;
+    /**
+     * 연결을 종료합니다.
+     *
+     * @remarks
+     * 이미 종료된 상태에서 호출해도 안전합니다 (오류 미발생).
+     * 종료 후 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
+     */
+    async close() {
+        if (this._client === undefined) {
+            return;
+        }
+        await this._client.end();
+        this._client = undefined;
     }
-    await this._client.end();
-    this._client = void 0;
-  }
 }
-export {
-  SftpStorageClient
-};
-//# sourceMappingURL=sftp-storage-client.js.map
+//# sourceMappingURL=sftp-storage-client.js.map

package/dist/clients/sftp-storage-client.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../../src/clients/sftp-storage-client.ts"],
-  "mappings": "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",
-  "names": []
-}
+{"version":3,"file":"sftp-storage-client.js","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,10 @@
+// 타입
 export * from "./types/storage-conn-config.js";
 export * from "./types/storage.js";
 export * from "./types/storage-type.js";
+// 클라이언트
 export * from "./clients/ftp-storage-client.js";
 export * from "./clients/sftp-storage-client.js";
+// 팩토리
 export * from "./storage-factory.js";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/index.ts"],
-  "mappings": "AACA,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;",
-  "names": []
-}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["..\\src\\index.ts"],"names":[],"mappings":"AAAA,KAAK;AACL,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAErC,QAAQ;AACR,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAE9C,MAAM;AACN,cAAc,mBAAmB,CAAC"}

package/dist/storage-factory.d.ts

@@ -2,17 +2,17 @@ import type { StorageConnConfig } from "./types/storage-conn-config";
 import type { StorageClient } from "./types/storage";
 import type { StorageProtocol } from "./types/storage-type";
 /**
- * Storage client factory
+ * 스토리지 클라이언트 팩토리
  *
- * Creates and manages FTP, FTPS, and SFTP storage connections.
+ * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리합니다.
  */
 export declare class StorageFactory {
     /**
-     * Connect to storage, execute the callback, and automatically close the connection.
+     * 스토리지에 연결하고, 콜백을 실행한 후, 자동으로 연결을 종료합니다.
      *
      * @remarks
-     * The callback pattern auto-manages connection/close, so this is preferred over direct client usage.
-     * The connection is automatically closed even if the callback throws an exception.
+     * 콜백 패턴으로 연결/종료를 자동 관리하므로 직접 클라이언트를 사용하는 것보다 권장됩니다.
+     * 콜백에서 예외가 발생해도 연결은 자동으로 종료됩니다.
      */
     static connect<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R | Promise<R>): Promise<R>;
     private static _createClient;

package/dist/storage-factory.js

@@ -1,35 +1,39 @@
 import { FtpStorageClient } from "./clients/ftp-storage-client.js";
 import { SftpStorageClient } from "./clients/sftp-storage-client.js";
-class StorageFactory {
-  /**
-   * Connect to storage, execute the callback, and automatically close the connection.
-   *
-   * @remarks
-   * The callback pattern auto-manages connection/close, so this is preferred over direct client usage.
-   * The connection is automatically closed even if the callback throws an exception.
-   */
-  static async connect(type, config, fn) {
-    const client = StorageFactory._createClient(type);
-    await client.connect(config);
-    try {
-      return await fn(client);
-    } finally {
-      await client.close().catch(() => {
-      });
+/**
+ * 스토리지 클라이언트 팩토리
+ *
+ * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리합니다.
+ */
+export class StorageFactory {
+    /**
+     * 스토리지에 연결하고, 콜백을 실행한 후, 자동으로 연결을 종료합니다.
+     *
+     * @remarks
+     * 콜백 패턴으로 연결/종료를 자동 관리하므로 직접 클라이언트를 사용하는 것보다 권장됩니다.
+     * 콜백에서 예외가 발생해도 연결은 자동으로 종료됩니다.
+     */
+    static async connect(type, config, fn) {
+        const client = StorageFactory._createClient(type);
+        await client.connect(config);
+        try {
+            return await fn(client);
+        }
+        finally {
+            await client.close().catch(() => {
+                // 이미 종료된 경우 무시
+            });
+        }
     }
-  }
-  static _createClient(type) {
-    switch (type) {
-      case "sftp":
-        return new SftpStorageClient();
-      case "ftps":
-        return new FtpStorageClient(true);
-      case "ftp":
-        return new FtpStorageClient(false);
+    static _createClient(type) {
+        switch (type) {
+            case "sftp":
+                return new SftpStorageClient();
+            case "ftps":
+                return new FtpStorageClient(true);
+            case "ftp":
+                return new FtpStorageClient(false);
+        }
     }
-  }
 }
-export {
-  StorageFactory
-};
-//# sourceMappingURL=storage-factory.js.map
+//# sourceMappingURL=storage-factory.js.map

package/dist/storage-factory.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/storage-factory.ts"],
-  "mappings": "AAGA,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AAO3B,MAAM,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ1B,aAAa,QACX,MACA,QACA,IACY;AACZ,UAAM,SAAS,eAAe,cAAc,IAAI;AAEhD,UAAM,OAAO,QAAQ,MAAM;AAC3B,QAAI;AACF,aAAO,MAAM,GAAG,MAAM;AAAA,IACxB,UAAE;AACA,YAAM,OAAO,MAAM,EAAE,MAAM,MAAM;AAAA,MAEjC,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEA,OAAe,cAAc,MAAsC;AACjE,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,eAAO,IAAI,kBAAkB;AAAA,MAC/B,KAAK;AACH,eAAO,IAAI,iBAAiB,IAAI;AAAA,MAClC,KAAK;AACH,eAAO,IAAI,iBAAiB,KAAK;AAAA,IACrC;AAAA,EACF;AACF;",
-  "names": []
-}
+{"version":3,"file":"storage-factory.js","sourceRoot":"","sources":["..\\src\\storage-factory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,CAClB,IAAqB,EACrB,MAAyB,EACzB,EAA8C;QAE9C,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAElD,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC9B,eAAe;YACjB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,IAAqB;QAChD,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,MAAM;gBACT,OAAO,IAAI,iBAAiB,EAAE,CAAC;YACjC,KAAK,MAAM;gBACT,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACpC,KAAK,KAAK;gBACR,OAAO,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;CACF"}

package/dist/types/storage-conn-config.js

@@ -1 +1,2 @@
-//# sourceMappingURL=storage-conn-config.js.map
+export {};
+//# sourceMappingURL=storage-conn-config.js.map

package/dist/types/storage-conn-config.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": [],
-  "mappings": "",
-  "names": []
-}
+{"version":3,"file":"storage-conn-config.js","sourceRoot":"","sources":["..\\..\\src\\types\\storage-conn-config.ts"],"names":[],"mappings":""}

package/dist/types/storage-type.js

@@ -1 +1,2 @@
-//# sourceMappingURL=storage-type.js.map
+export {};
+//# sourceMappingURL=storage-type.js.map

package/dist/types/storage-type.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": [],
-  "mappings": "",
-  "names": []
-}
+{"version":3,"file":"storage-type.js","sourceRoot":"","sources":["..\\..\\src\\types\\storage-type.ts"],"names":[],"mappings":""}

package/dist/types/storage.js

@@ -1 +1,2 @@
-//# sourceMappingURL=storage.js.map
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/types/storage.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": [],
-  "mappings": "",
-  "names": []
-}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["..\\..\\src\\types\\storage.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/storage",
-  "version": "13.0.100",
-  "description": "Simplysm Package - Storage Module (node)",
-  "author": "simplysm",
+  "version": "14.0.4",
+  "description": "심플리즘 패키지 - 저장소 (node)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,14 +14,13 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "tests"
+    "src"
   ],
   "sideEffects": false,
   "dependencies": {
     "basic-ftp": "^5.2.0",
-    "ssh2-sftp-client": "^12.1.0",
-    "@simplysm/core-common": "13.0.100"
+    "ssh2-sftp-client": "^12.1.1",
+    "@simplysm/core-common": "14.0.4"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"

package/src/clients/ftp-storage-client.ts

@@ -6,11 +6,11 @@ import type { StorageClient, FileInfo } from "../types/storage";
 import type { StorageConnConfig } from "../types/storage-conn-config";
 
 /**
- * Storage client using FTP/FTPS protocol.
+ * FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트.
  *
  * @remarks
- * The `secure` constructor parameter configures whether to use FTPS.
- * Using {@link StorageFactory.connect} is recommended over direct usage.
+ * `secure` 생성자 매개변수로 FTPS 사용 여부를 설정합니다.
+ * 직접 사용하기보다 {@link StorageFactory.connect} 사용을 권장합니다.
  */
 export class FtpStorageClient implements StorageClient {
   private _client: ftp.Client | undefined;
@@ -18,16 +18,16 @@ export class FtpStorageClient implements StorageClient {
   constructor(private readonly _secure: boolean = false) {}
 
   /**
-   * Connect to the FTP server.
+   * FTP 서버에 연결합니다.
    *
    * @remarks
-   * - Must close the connection with {@link close} after use.
-   * - Do not call multiple times on the same instance (connection leak).
-   * - Use {@link StorageFactory.connect} for automatic connection/close management (recommended).
+   * - 사용 후 {@link close}로 연결을 종료해야 합니다.
+   * - 동일 인스턴스에서 여러 번 호출하지 마세요 (연결 누수).
+   * - 자동 연결/종료 관리를 위해 {@link StorageFactory.connect} 사용을 권장합니다.
    */
   async connect(config: StorageConnConfig): Promise<void> {
     if (this._client !== undefined) {
-      throw new SdError("FTP server is already connected. Please call close() first.");
+      throw new SdError("FTP 서버에 이미 연결되어 있습니다. 먼저 close()를 호출해 주세요.");
     }
     const client = new ftp.Client();
     try {
@@ -47,12 +47,12 @@ export class FtpStorageClient implements StorageClient {
 
   private _requireClient(): ftp.Client {
     if (this._client === undefined) {
-      throw new SdError("Not connected to FTP server.");
+      throw new SdError("FTP 서버에 연결되어 있지 않습니다.");
     }
     return this._client;
   }
 
-  /** Create a directory. Creates parent directories if they do not exist. */
+  /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
   async mkdir(dirPath: string): Promise<void> {
     await this._requireClient().ensureDir(dirPath);
   }
@@ -78,24 +78,24 @@ export class FtpStorageClient implements StorageClient {
   }
 
   /**
-   * Check whether a file or directory exists.
+   * 파일 또는 디렉토리의 존재 여부를 확인합니다.
    *
    * @remarks
-   * For files, uses the size() command for O(1) performance.
-   * For directories, queries the parent directory listing, so performance may degrade with many entries.
+   * 파일의 경우 size() 명령으로 O(1) 성능을 제공합니다.
+   * 디렉토리의 경우 부모 디렉토리 목록을 조회하므로 항목이 많으면 성능이 저하될 수 있습니다.
    *
-   * Paths without slashes (e.g. `file.txt`) are searched in the root directory (`/`).
+   * 슬래시가 없는 경로(예: `file.txt`)는 루트 디렉토리(`/`)에서 검색합니다.
    *
-   * Returns false even if the parent directory does not exist.
-   * Returns false for all exceptions including network errors and permission errors.
+   * 부모 디렉토리가 존재하지 않아도 false를 반환합니다.
+   * 네트워크 오류, 권한 오류 등 모든 예외에 대해 false를 반환합니다.
    */
   async exists(filePath: string): Promise<boolean> {
     try {
-      // Quick check for files via size() (O(1))
+      // size()로 파일 존재 여부 빠른 확인 (O(1))
       await this._requireClient().size(filePath);
       return true;
     } catch {
-      // If size() fails, it may be a directory, so check via list()
+      // size() 실패 시 디렉토리일 수 있으므로 list()로 확인
       try {
         const lastSlash = filePath.lastIndexOf("/");
         const dirPath = lastSlash > 0 ? filePath.substring(0, lastSlash) : "/";
@@ -112,7 +112,7 @@ export class FtpStorageClient implements StorageClient {
     await this._requireClient().remove(filePath);
   }
 
-  /** Upload a local file path or byte data to the remote path. */
+  /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
   async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void> {
     let param: string | Readable;
     if (typeof localPathOrBuffer === "string") {
@@ -128,11 +128,11 @@ export class FtpStorageClient implements StorageClient {
   }
 
   /**
-   * Close the connection.
+   * 연결을 종료합니다.
    *
    * @remarks
-   * Safe to call when already closed (no error thrown).
-   * After closing, you can reconnect by calling {@link connect} again on the same instance.
+   * 이미 종료된 상태에서 호출해도 안전합니다 (오류 미발생).
+   * 종료 후 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
    */
   close(): Promise<void> {
     if (this._client === undefined) {