@simplysm/storage 13.0.69 → 13.0.70

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

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

package/dist/storage-factory.d.ts

@@ -2,17 +2,17 @@ import type { StorageConnConfig } from "./types/storage-conn-config";
 import type { Storage } from "./types/storage";
 import type { StorageType } from "./types/storage-type";
 /**
- * 스토리지 클라이언트 팩토리
+ * Storage client factory
  *
- * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리한다.
+ * Creates and manages FTP, FTPS, and SFTP storage connections.
  */
 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: StorageType, config: StorageConnConfig, fn: (storage: Storage) => R | Promise<R>): Promise<R>;
     private static _createClient;

package/dist/storage-factory.js

@@ -2,11 +2,11 @@ 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);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/storage",
-  "version": "13.0.69",
-  "description": "심플리즘 패키지 - 스토리지 모듈 (node)",
-  "author": "김석래",
+  "version": "13.0.70",
+  "description": "Simplysm Package - Storage Module (node)",
+  "author": "simplysm",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,13 +14,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "tests"
   ],
   "sideEffects": false,
   "dependencies": {
     "basic-ftp": "^5.2.0",
     "ssh2-sftp-client": "^12.0.1",
-    "@simplysm/core-common": "13.0.69"
+    "@simplysm/core-common": "13.0.70"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"

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

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

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

@@ -4,29 +4,29 @@ import SftpClient from "ssh2-sftp-client";
 import type { Storage, FileInfo } from "../types/storage";
 import type { StorageConnConfig } from "../types/storage-conn-config";
 
-// ssh2-sftp-client 라이브러리 타입 정의에서 Buffer 사용
+// Buffer usage from ssh2-sftp-client library type definitions
 type SftpGetResult = string | NodeJS.WritableStream | Bytes;
 
 /**
- * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
+ * Storage client using SFTP protocol.
  *
  * @remarks
- * 직접 사용보다 {@link StorageFactory.connect}를 통한 사용을 권장합니다.
+ * Using {@link StorageFactory.connect} is recommended over direct usage.
  */
 export class SftpStorageClient implements Storage {
   private _client: SftpClient | undefined;
 
   /**
-   * SFTP 서버에 연결합니다.
+   * Connect to the SFTP server.
    *
    * @remarks
-   * - 연결 후 반드시 {@link close}로 연결을 종료해야 합니다.
-   * - 동일 인스턴스에서 여러 번 호출하지 마세요. (연결 누수 발생)
-   * - 자동 연결/종료 관리가 필요하면 {@link StorageFactory.connect}를 사용하세요. (권장)
+   * - 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: StorageConnConfig): Promise<void> {
     if (this._client !== undefined) {
-      throw new SdError("이미 SFTP 서버에 연결되어 있습니다. 먼저 close()를 호출하세요.");
+      throw new SdError("SFTP server is already connected. Please call close() first.");
     }
 
     const client = new SftpClient();
@@ -39,7 +39,7 @@ export class SftpStorageClient implements Storage {
           password: config.pass,
         });
       } else {
-        // SSH agent + 키 파일로 인증 시도
+        // Authenticate with SSH agent + key file
         const fsP = await import("fs/promises");
         const os = await import("os");
         const pathMod = await import("path");
@@ -58,7 +58,7 @@ export class SftpStorageClient implements Storage {
             privateKey: await fsP.readFile(keyPath),
           });
         } catch {
-          // privateKey 파싱 실패 (암호화된 키 등) → agent만으로 재시도
+          // privateKey parsing failed (encrypted key, etc.) -> retry with agent only
           await client.connect(baseOptions);
         }
       }
@@ -71,12 +71,12 @@ export class SftpStorageClient implements Storage {
 
   private _requireClient(): SftpClient {
     if (this._client === undefined) {
-      throw new SdError("SFTP 서버에 연결되어있지 않습니다.");
+      throw new SdError("Not connected to SFTP server.");
     }
     return this._client;
   }
 
-  /** 디렉토리를 생성합니다. 상위 디렉토리가 없으면 함께 생성합니다. */
+  /** Create a directory. Creates parent directories if they do not exist. */
   async mkdir(dirPath: string): Promise<void> {
     await this._requireClient().mkdir(dirPath, true);
   }
@@ -86,16 +86,16 @@ export class SftpStorageClient implements Storage {
   }
 
   /**
-   * 파일 또는 디렉토리 존재 여부를 확인합니다.
+   * Check whether a file or directory exists.
    *
    * @remarks
-   * 상위 디렉토리가 존재하지 않는 경우에도 false를 반환합니다.
-   * 네트워크 오류, 권한 오류 등 모든 예외도 false를 반환합니다.
+   * Returns false even if the parent directory does not exist.
+   * Returns false for all exceptions including network errors and permission errors.
    */
   async exists(filePath: string): Promise<boolean> {
     try {
-      // ssh2-sftp-client의 exists()는 false | 'd' | '-' | 'l' 를 반환한다.
-      // false: 존재하지 않음, 'd': 디렉토리, '-': 파일, 'l': 심볼릭 링크
+      // ssh2-sftp-client's exists() returns false | 'd' | '-' | 'l'.
+      // false: does not exist, 'd': directory, '-': file, 'l': symbolic link
       const result = await this._requireClient().exists(filePath);
       return typeof result === "string";
     } catch {
@@ -112,29 +112,29 @@ export class SftpStorageClient implements Storage {
   }
 
   async readFile(filePath: string): Promise<Bytes> {
-    // ssh2-sftp-client의 get()은 dst 미전달 시 Buffer를 반환한다.
-    // 타입 정의(string | WritableStream | Buffer)와 달리 실제로는 Buffer만 반환된다.
+    // ssh2-sftp-client's get() returns Buffer when dst is not provided.
+    // Despite the type definition (string | WritableStream | Buffer), only Buffer is actually returned.
     const result = (await this._requireClient().get(filePath)) as SftpGetResult;
     if (result instanceof Uint8Array) {
       return result;
     }
-    // 타입 정의상 string도 가능하므로 방어 코드
+    // Defensive code since string is possible per type definition
     if (typeof result === "string") {
       return new TextEncoder().encode(result);
     }
-    throw new SdError("예상치 못한 응답 타입입니다.");
+    throw new SdError("Unexpected response type.");
   }
 
   async remove(filePath: string): Promise<void> {
     await this._requireClient().delete(filePath);
   }
 
-  /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
+  /** Upload a local file path or byte data to the remote path. */
   async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void> {
     if (typeof localPathOrBuffer === "string") {
       await this._requireClient().fastPut(localPathOrBuffer, storageFilePath);
     } else {
-      // eslint-disable-next-line no-restricted-globals -- ssh2-sftp-client 라이브러리 요구사항
+      // eslint-disable-next-line no-restricted-globals -- ssh2-sftp-client library requirement
       await this._requireClient().put(Buffer.from(localPathOrBuffer), storageFilePath);
     }
   }
@@ -144,11 +144,11 @@ export class SftpStorageClient implements Storage {
   }
 
   /**
-   * 연결을 종료합니다.
+   * Close the connection.
    *
    * @remarks
-   * 이미 종료된 상태에서 호출해도 에러가 발생하지 않습니다.
-   * 종료 후에는 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
+   * 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(): Promise<void> {
     if (this._client === undefined) {

package/src/storage-factory.ts

@@ -5,17 +5,17 @@ import { FtpStorageClient } from "./clients/ftp-storage-client";
 import { SftpStorageClient } from "./clients/sftp-storage-client";
 
 /**
- * 스토리지 클라이언트 팩토리
+ * Storage client factory
  *
- * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리한다.
+ * Creates and manages FTP, FTPS, and SFTP storage connections.
  */
 export 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<R>(
     type: StorageType,
@@ -29,7 +29,7 @@ export class StorageFactory {
       return await fn(client);
     } finally {
       await client.close().catch(() => {
-        // 이미 닫힌 경우 무시
+        // Ignore if already closed
       });
     }
   }

package/tests/ftp-storage-client.spec.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { FtpStorageClient } from "../src/clients/ftp-storage-client";
+
+// Mock basic-ftp module
+const mockAccess = vi.fn().mockResolvedValue(undefined);
+const mockEnsureDir = vi.fn().mockResolvedValue(undefined);
+const mockRename = vi.fn().mockResolvedValue(undefined);
+const mockSize = vi.fn().mockResolvedValue(100);
+const mockList = vi.fn().mockResolvedValue([
+  { name: "file.txt", isFile: true },
+  { name: "dir", isFile: false },
+]);
+const mockDownloadTo = vi.fn().mockImplementation((writable) => {
+  writable.emit("data", new TextEncoder().encode("test content"));
+  return Promise.resolve();
+});
+const mockRemove = vi.fn().mockResolvedValue(undefined);
+const mockUploadFrom = vi.fn().mockResolvedValue(undefined);
+const mockUploadFromDir = vi.fn().mockResolvedValue(undefined);
+const mockClose = vi.fn();
+
+vi.mock("basic-ftp", () => {
+  return {
+    default: {
+      Client: class MockClient {
+        access = mockAccess;
+        ensureDir = mockEnsureDir;
+        rename = mockRename;
+        size = mockSize;
+        list = mockList;
+        downloadTo = mockDownloadTo;
+        remove = mockRemove;
+        uploadFrom = mockUploadFrom;
+        uploadFromDir = mockUploadFromDir;
+        close = mockClose;
+      },
+    },
+  };
+});
+
+describe("FtpStorageClient", () => {
+  let client: FtpStorageClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new FtpStorageClient();
+  });
+
+  describe("connect", () => {
+    it("Should connect with connection settings", async () => {
+      await client.connect({
+        host: "ftp.example.com",
+        port: 21,
+        user: "user",
+        pass: "pass",
+      });
+
+      expect(mockAccess).toHaveBeenCalledWith({
+        host: "ftp.example.com",
+        port: 21,
+        user: "user",
+        password: "pass",
+        secure: false,
+      });
+    });
+
+    it("Should connect in secure mode", async () => {
+      const secureClient = new FtpStorageClient(true);
+      await secureClient.connect({ host: "ftp.example.com" });
+
+      expect(mockAccess).toHaveBeenCalledWith(expect.objectContaining({ secure: true }));
+    });
+
+    it("Should throw error when connect is called on already connected client", async () => {
+      await client.connect({ host: "test" });
+      await expect(client.connect({ host: "test" })).rejects.toThrow(
+        "FTP server is already connected. Please call close() first.",
+      );
+    });
+
+    it("Should clean up client on connection failure", async () => {
+      mockAccess.mockRejectedValueOnce(new Error("Auth failed"));
+      await expect(client.connect({ host: "test" })).rejects.toThrow("Auth failed");
+      expect(mockClose).toHaveBeenCalled();
+    });
+  });
+
+  describe("Method calls before connection", () => {
+    it("Should throw error when mkdir is called before connection", async () => {
+      await expect(client.mkdir("/test")).rejects.toThrow("Not connected to FTP server.");
+    });
+
+    it("Should throw error when rename is called before connection", async () => {
+      await expect(client.rename("/from", "/to")).rejects.toThrow(
+        "Not connected to FTP server.",
+      );
+    });
+
+    it("Should throw error when readdir is called before connection", async () => {
+      await expect(client.readdir("/")).rejects.toThrow("Not connected to FTP server.");
+    });
+  });
+
+  describe("mkdir", () => {
+    it("Should create directory", async () => {
+      await client.connect({ host: "test" });
+      await client.mkdir("/test/dir");
+
+      expect(mockEnsureDir).toHaveBeenCalledWith("/test/dir");
+    });
+  });
+
+  describe("rename", () => {
+    it("Should rename file/directory", async () => {
+      await client.connect({ host: "test" });
+      await client.rename("/from", "/to");
+
+      expect(mockRename).toHaveBeenCalledWith("/from", "/to");
+    });
+  });
+
+  describe("readdir", () => {
+    it("Should return directory list as FileInfo array", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.readdir("/");
+
+      expect(result).toEqual([
+        { name: "file.txt", isFile: true },
+        { name: "dir", isFile: false },
+      ]);
+    });
+  });
+
+  describe("readFile", () => {
+    it("Should return file content as Uint8Array", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.readFile("/file.txt");
+
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(new TextDecoder().decode(result)).toBe("test content");
+    });
+  });
+
+  describe("exists", () => {
+    it("Should return true if file exists (checked via size)", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/file.txt");
+
+      expect(mockSize).toHaveBeenCalledWith("/path/file.txt");
+      expect(result).toBe(true);
+    });
+
+    it("Should return true if directory exists (checked via list)", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/dir");
+
+      expect(mockList).toHaveBeenCalledWith("/path");
+      expect(result).toBe(true);
+    });
+
+    it("Should return false if file does not exist", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      mockList.mockResolvedValueOnce([]);
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/nonexistent.txt");
+
+      expect(result).toBe(false);
+    });
+
+    it("Should return false on error", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      mockList.mockRejectedValueOnce(new Error("Not found"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/error.txt");
+
+      expect(result).toBe(false);
+    });
+
+    it("Should check file existence in root directory", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/file.txt");
+
+      expect(mockList).toHaveBeenCalledWith("/");
+      expect(result).toBe(true);
+    });
+
+    it("Should check file existence for paths without slashes", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("file.txt");
+
+      expect(mockList).toHaveBeenCalledWith("/");
+      expect(result).toBe(true);
+    });
+  });
+
+  describe("remove", () => {
+    it("Should delete file", async () => {
+      await client.connect({ host: "test" });
+      await client.remove("/file.txt");
+
+      expect(mockRemove).toHaveBeenCalledWith("/file.txt");
+    });
+  });
+
+  describe("put", () => {
+    it("Should upload from local path", async () => {
+      await client.connect({ host: "test" });
+      await client.put("/local/file.txt", "/remote/file.txt");
+
+      expect(mockUploadFrom).toHaveBeenCalledWith("/local/file.txt", "/remote/file.txt");
+    });
+
+    it("Should upload from Uint8Array", async () => {
+      await client.connect({ host: "test" });
+      const bytes = new TextEncoder().encode("content");
+      await client.put(bytes, "/remote/file.txt");
+
+      expect(mockUploadFrom).toHaveBeenCalled();
+    });
+  });
+
+  describe("uploadDir", () => {
+    it("Should upload directory", async () => {
+      await client.connect({ host: "test" });
+      await client.uploadDir("/local/dir", "/remote/dir");
+
+      expect(mockUploadFromDir).toHaveBeenCalledWith("/local/dir", "/remote/dir");
+    });
+  });
+
+  describe("close", () => {
+    it("Should exit without error when close is called before connection", async () => {
+      await expect(client.close()).resolves.toBeUndefined();
+    });
+
+    it("Should close connection", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+
+      expect(mockClose).toHaveBeenCalled();
+    });
+
+    it("Should throw error when calling method after close", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+
+      await expect(client.mkdir("/test")).rejects.toThrow("Not connected to FTP server.");
+    });
+
+    it("Should allow reconnection after close", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+      await client.connect({ host: "test" });
+
+      expect(mockAccess).toHaveBeenCalledTimes(2);
+    });
+  });
+});