@simplysm/storage 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,8 @@
 # @simplysm/storage
 
-Simplysm Package - Storage Module (node). Provides FTP, FTPS, and SFTP storage client implementations with a factory for managed connections.
+Storage client library for FTP, FTPS, and SFTP file operations.
+
+Platform: Node.js.
 
 ## Installation
 
@@ -12,131 +14,121 @@ npm install @simplysm/storage
 
 ### Types
 
-| API | Type | Description |
-|-----|------|-------------|
-| `StorageConnConfig` | interface | Storage connection configuration |
-| `FileInfo` | interface | File/directory entry information |
-| `StorageClient` | interface | Storage client interface |
-| `StorageProtocol` | type | Protocol type (`"ftp" \| "ftps" \| "sftp"`) |
+#### StorageConnConfig
 
-### Clients
+Connection configuration for storage clients.
 
-| API | Type | Description |
-|-----|------|-------------|
-| `FtpStorageClient` | class | FTP/FTPS storage client (uses basic-ftp) |
-| `SftpStorageClient` | class | SFTP storage client (uses ssh2-sftp-client) |
+| Field | Type | Description |
+|---|---|---|
+| `host` | `string` | Server hostname or IP address |
+| `port?` | `number` | Server port (protocol default if omitted) |
+| `user?` | `string` | Username |
+| `password?` | `string` | Password |
 
-### Factory
+#### FileInfo
 
-| API | Type | Description |
-|-----|------|-------------|
-| `StorageFactory` | class | Storage client factory with managed connections |
+File/directory entry returned by `list()`.
 
----
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | File or directory name |
+| `isFile` | `boolean` | `true` if this entry is a file, `false` if it is a directory |
 
-### `StorageProtocol`
+#### StorageProtocol
 
 ```typescript
-type StorageProtocol = "ftp" | "ftps" | "sftp"
+type StorageProtocol = "ftp" | "ftps" | "sftp";
 ```
 
-### `StorageConnConfig`
+#### StorageClient (interface)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `host` | `string` | Server hostname |
-| `port` | `number?` | Server port |
-| `user` | `string?` | Username |
-| `password` | `string?` | Password (SFTP: if omitted, uses SSH agent + key file) |
+Common interface implemented by all storage clients.
 
-### `FileInfo`
+| Method | Signature | Description |
+|---|---|---|
+| `connect` | `(config: StorageConnConfig) => Promise<void>` | Connect to the server |
+| `mkdir` | `(dirPath: string) => Promise<void>` | Create directory (recursive) |
+| `rename` | `(fromPath: string, toPath: string) => Promise<void>` | Rename a file or directory |
+| `list` | `(dirPath: string) => Promise<FileInfo[]>` | List directory contents |
+| `readFile` | `(filePath: string) => Promise<Bytes>` | Read file contents |
+| `exists` | `(filePath: string) => Promise<boolean>` | Check if file or directory exists |
+| `put` | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | Upload a local file path or byte data to remote path |
+| `uploadDir` | `(fromPath: string, toPath: string) => Promise<void>` | Upload entire local directory to remote path |
+| `remove` | `(filePath: string) => Promise<void>` | Remove a file |
+| `close` | `() => Promise<void>` | Close the connection. Safe to call multiple times. |
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | File or directory name |
-| `isFile` | `boolean` | Whether the entry is a file |
+### Clients
 
-### `StorageClient`
+#### FtpStorageClient
 
-Interface implemented by both `FtpStorageClient` and `SftpStorageClient`.
+FTP/FTPS client. Implements `StorageClient`. Uses `basic-ftp` internally.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `connect` | `(config: StorageConnConfig) => Promise<void>` | Connect to server |
-| `mkdir` | `(dirPath: string) => Promise<void>` | Create directory (recursive) |
-| `rename` | `(fromPath: string, toPath: string) => Promise<void>` | Rename file/directory |
-| `list` | `(dirPath: string) => Promise<FileInfo[]>` | List directory contents |
-| `readFile` | `(filePath: string) => Promise<Bytes>` | Read file |
-| `exists` | `(filePath: string) => Promise<boolean>` | Check existence |
-| `put` | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | Upload file (local path or byte data) |
-| `uploadDir` | `(fromPath: string, toPath: string) => Promise<void>` | Upload entire directory |
-| `remove` | `(filePath: string) => Promise<void>` | Delete file |
-| `close` | `() => Promise<void>` | Close connection |
+```typescript
+constructor(secure?: boolean)
+```
 
-### `FtpStorageClient`
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `secure` | `boolean` | `false` | Set `true` for FTPS |
 
-Implements `StorageClient` using FTP/FTPS protocol via the `basic-ftp` library.
+All methods from `StorageClient` are implemented. Prefer using `StorageFactory.connect` over direct instantiation.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `constructor` | `(secure?: boolean)` | Create client (`true` for FTPS, `false` for FTP) |
+#### SftpStorageClient
 
-All `StorageClient` methods are implemented. Using `StorageFactory.connect` is recommended over direct usage.
+SFTP client. Implements `StorageClient`. Uses `ssh2-sftp-client` internally.
 
-### `SftpStorageClient`
+```typescript
+constructor()
+```
 
-Implements `StorageClient` using SFTP protocol via the `ssh2-sftp-client` library. Supports password authentication and SSH agent + key file authentication.
+Authentication priority when `password` is not provided:
+1. SSH private key (`~/.ssh/id_ed25519`) + SSH agent
+2. SSH agent only (fallback when key parsing fails)
 
-All `StorageClient` methods are implemented. Using `StorageFactory.connect` is recommended over direct usage.
+All methods from `StorageClient` are implemented. Prefer using `StorageFactory.connect` over direct instantiation.
 
-### `StorageFactory`
+### Factory
+
+#### StorageFactory
+
+Static factory class for creating and managing storage connections.
+
+##### Static Methods
 
 | Method | Signature | Description |
-|--------|-----------|-------------|
-| `connect` | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | Connect, execute callback, auto-close |
+|---|---|---|
+| `connect` | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | Connect to storage, execute callback, and automatically close the connection. The connection is closed even if the callback throws. |
 
-## Usage Examples
+## Usage
 
-### Using StorageFactory (recommended)
+### Recommended: StorageFactory (auto-managed connection)
 
 ```typescript
 import { StorageFactory } from "@simplysm/storage";
 
-await StorageFactory.connect("sftp", {
+const files = await StorageFactory.connect("sftp", {
   host: "example.com",
   user: "deploy",
-  password: "secret",
-}, async (storage) => {
-  await storage.uploadDir("./dist", "/var/www/app");
-  const files = await storage.list("/var/www/app");
+}, async (client) => {
+  await client.mkdir("/remote/path");
+  await client.put("/local/file.txt", "/remote/file.txt");
+  return client.list("/remote/path");
 });
 ```
 
-### Using client directly
+### Direct client usage
 
 ```typescript
-import { FtpStorageClient } from "@simplysm/storage";
+import { SftpStorageClient } from "@simplysm/storage";
 
-const client = new FtpStorageClient(true); // FTPS
-await client.connect({ host: "ftp.example.com", user: "admin", password: "pass" });
+const client = new SftpStorageClient();
+await client.connect({ host: "example.com", user: "deploy" });
 try {
-  await client.put("./build.zip", "/releases/build.zip");
-  const exists = await client.exists("/releases/build.zip");
+  const exists = await client.exists("/remote/file.txt");
+  if (exists) {
+    const data = await client.readFile("/remote/file.txt");
+  }
 } finally {
   await client.close();
 }
 ```
-
-### SFTP with SSH key authentication
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-// Omit password to use SSH agent + ~/.ssh/id_ed25519
-await StorageFactory.connect("sftp", {
-  host: "example.com",
-  user: "deploy",
-}, async (storage) => {
-  await storage.put(fileBytes, "/data/upload.bin");
-});
-```

package/dist/clients/ftp-storage-client.d.ts

@@ -2,54 +2,54 @@ import type { Bytes } from "@simplysm/core-common";
 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 declare class FtpStorageClient implements StorageClient {
     private readonly _secure;
     private _client;
     constructor(_secure?: boolean);
     /**
-     * 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} 사용을 권장합니다.
      */
     connect(config: StorageConnConfig): Promise<void>;
     private _requireClient;
-    /** Create a directory. Creates parent directories if they do not exist. */
+    /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
     mkdir(dirPath: string): Promise<void>;
     rename(fromPath: string, toPath: string): Promise<void>;
     list(dirPath: string): Promise<FileInfo[]>;
     readFile(filePath: string): Promise<Bytes>;
     /**
-     * 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를 반환합니다.
      */
     exists(filePath: string): Promise<boolean>;
     remove(filePath: string): Promise<void>;
-    /** Upload a local file path or byte data to the remote path. */
+    /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
     put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
     uploadDir(fromPath: string, toPath: string): Promise<void>;
     /**
-     * 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>;
 }

package/dist/clients/ftp-storage-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\ftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAInD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IAGxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,OAAO,CAAyB;gBAEX,OAAO,GAAE,OAAe;IAErD;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvD,OAAO,CAAC,cAAc;IAOtB,2EAA2E;IACrE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAWhD;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,gEAAgE;IAC1D,GAAG,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CASvB"}
+{"version":3,"file":"ftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\ftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAInD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IAGxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,OAAO,CAAyB;gBAEX,OAAO,GAAE,OAAe;IAErD;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvD,OAAO,CAAC,cAAc;IAOtB,0CAA0C;IACpC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAWhD;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,0CAA0C;IACpC,GAAG,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CASvB"}

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

@@ -1,126 +1,137 @@
 import { bytes, SdError } from "@simplysm/core-common";
 import ftp from "basic-ftp";
 import { PassThrough, Readable } from "stream";
-class FtpStorageClient {
-  constructor(_secure = false) {
-    this._secure = _secure;
-  }
-  _client;
-  /**
-   * Connect to the FTP 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("FTP server is already connected. Please call close() first.");
+/**
+ * FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트.
+ *
+ * @remarks
+ * `secure` 생성자 매개변수로 FTPS 사용 여부를 설정합니다.
+ * 직접 사용하기보다 {@link StorageFactory.connect} 사용을 권장합니다.
+ */
+export class FtpStorageClient {
+    _secure;
+    _client;
+    constructor(_secure = false) {
+        this._secure = _secure;
     }
-    const client = new ftp.Client();
-    try {
-      await client.access({
-        host: config.host,
-        port: config.port,
-        user: config.user,
-        password: config.password,
-        secure: this._secure
-      });
-      this._client = client;
-    } catch (err) {
-      client.close();
-      throw err;
+    /**
+     * FTP 서버에 연결합니다.
+     *
+     * @remarks
+     * - 사용 후 {@link close}로 연결을 종료해야 합니다.
+     * - 동일 인스턴스에서 여러 번 호출하지 마세요 (연결 누수).
+     * - 자동 연결/종료 관리를 위해 {@link StorageFactory.connect} 사용을 권장합니다.
+     */
+    async connect(config) {
+        if (this._client !== undefined) {
+            throw new SdError("FTP 서버에 이미 연결되어 있습니다. 먼저 close()를 호출해 주세요.");
+        }
+        const client = new ftp.Client();
+        try {
+            await client.access({
+                host: config.host,
+                port: config.port,
+                user: config.user,
+                password: config.password,
+                secure: this._secure,
+            });
+            this._client = client;
+        }
+        catch (err) {
+            client.close();
+            throw err;
+        }
     }
-  }
-  _requireClient() {
-    if (this._client === void 0) {
-      throw new SdError("Not connected to FTP server.");
+    _requireClient() {
+        if (this._client === undefined) {
+            throw new SdError("FTP 서버에 연결되어 있지 않습니다.");
+        }
+        return this._client;
     }
-    return this._client;
-  }
-  /** Create a directory. Creates parent directories if they do not exist. */
-  async mkdir(dirPath) {
-    await this._requireClient().ensureDir(dirPath);
-  }
-  async rename(fromPath, toPath) {
-    await this._requireClient().rename(fromPath, toPath);
-  }
-  async list(dirPath) {
-    const fileInfos = await this._requireClient().list(dirPath);
-    return fileInfos.map((item) => ({ name: item.name, isFile: item.isFile }));
-  }
-  async readFile(filePath) {
-    const client = this._requireClient();
-    const chunks = [];
-    const writable = new PassThrough();
-    writable.on("data", (chunk) => {
-      chunks.push(chunk);
-    });
-    await client.downloadTo(writable, filePath);
-    return bytes.concat(chunks);
-  }
-  /**
-   * 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.
-   *
-   * Paths without slashes (e.g. `file.txt`) are searched in the root directory (`/`).
-   *
-   * 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 {
-      await this._requireClient().size(filePath);
-      return true;
-    } catch {
-      try {
-        const lastSlash = filePath.lastIndexOf("/");
-        const dirPath = lastSlash > 0 ? filePath.substring(0, lastSlash) : "/";
-        const fileName = filePath.substring(lastSlash + 1);
-        const list = await this._requireClient().list(dirPath);
-        return list.some((item) => item.name === fileName);
-      } catch {
-        return false;
-      }
+    /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
+    async mkdir(dirPath) {
+        await this._requireClient().ensureDir(dirPath);
     }
-  }
-  async remove(filePath) {
-    await this._requireClient().remove(filePath);
-  }
-  /** Upload a local file path or byte data to the remote path. */
-  async put(localPathOrBuffer, storageFilePath) {
-    let param;
-    if (typeof localPathOrBuffer === "string") {
-      param = localPathOrBuffer;
-    } else {
-      param = Readable.from(localPathOrBuffer);
+    async rename(fromPath, toPath) {
+        await this._requireClient().rename(fromPath, toPath);
     }
-    await this._requireClient().uploadFrom(param, storageFilePath);
-  }
-  async uploadDir(fromPath, toPath) {
-    await this._requireClient().uploadFromDir(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.
-   */
-  close() {
-    if (this._client === void 0) {
-      return Promise.resolve();
+    async list(dirPath) {
+        const fileInfos = await this._requireClient().list(dirPath);
+        return fileInfos.map((item) => ({ name: item.name, isFile: item.isFile }));
+    }
+    async readFile(filePath) {
+        const client = this._requireClient();
+        const chunks = [];
+        const writable = new PassThrough();
+        writable.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        await client.downloadTo(writable, filePath);
+        return bytes.concat(chunks);
+    }
+    /**
+     * 파일 또는 디렉토리의 존재 여부를 확인합니다.
+     *
+     * @remarks
+     * 파일의 경우 size() 명령으로 O(1) 성능을 제공합니다.
+     * 디렉토리의 경우 부모 디렉토리 목록을 조회하므로 항목이 많으면 성능이 저하될 수 있습니다.
+     *
+     * 슬래시가 없는 경로(예: `file.txt`)는 루트 디렉토리(`/`)에서 검색합니다.
+     *
+     * 부모 디렉토리가 존재하지 않아도 false를 반환합니다.
+     * 네트워크 오류, 권한 오류 등 모든 예외에 대해 false를 반환합니다.
+     */
+    async exists(filePath) {
+        try {
+            // size()로 파일 존재 여부 빠른 확인 (O(1))
+            await this._requireClient().size(filePath);
+            return true;
+        }
+        catch {
+            // size() 실패 시 디렉토리일 수 있으므로 list()로 확인
+            try {
+                const lastSlash = filePath.lastIndexOf("/");
+                const dirPath = lastSlash > 0 ? filePath.substring(0, lastSlash) : "/";
+                const fileName = filePath.substring(lastSlash + 1);
+                const list = await this._requireClient().list(dirPath);
+                return list.some((item) => item.name === fileName);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    async remove(filePath) {
+        await this._requireClient().remove(filePath);
+    }
+    /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
+    async put(localPathOrBuffer, storageFilePath) {
+        let param;
+        if (typeof localPathOrBuffer === "string") {
+            param = localPathOrBuffer;
+        }
+        else {
+            param = Readable.from(localPathOrBuffer);
+        }
+        await this._requireClient().uploadFrom(param, storageFilePath);
+    }
+    async uploadDir(fromPath, toPath) {
+        await this._requireClient().uploadFromDir(fromPath, toPath);
+    }
+    /**
+     * 연결을 종료합니다.
+     *
+     * @remarks
+     * 이미 종료된 상태에서 호출해도 안전합니다 (오류 미발생).
+     * 종료 후 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
+     */
+    close() {
+        if (this._client === undefined) {
+            return Promise.resolve();
+        }
+        this._client.close();
+        this._client = undefined;
+        return Promise.resolve();
     }
-    this._client.close();
-    this._client = void 0;
-    return Promise.resolve();
-  }
 }
-export {
-  FtpStorageClient
-};
-//# sourceMappingURL=ftp-storage-client.js.map
+//# sourceMappingURL=ftp-storage-client.js.map

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

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

package/dist/clients/sftp-storage-client.d.ts

@@ -2,46 +2,46 @@ import type { Bytes } from "@simplysm/core-common";
 import type { StorageClient, FileInfo } from "../types/storage";
 import type { StorageConnConfig } from "../types/storage-conn-config";
 /**
- * Storage client using SFTP protocol.
+ * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
  *
  * @remarks
- * Using {@link StorageFactory.connect} is recommended over direct usage.
+ * 직접 사용하기보다 {@link StorageFactory.connect} 사용을 권장합니다.
  */
 export declare class SftpStorageClient implements StorageClient {
     private _client;
     /**
-     * Connect to the SFTP server.
+     * SFTP 서버에 연결합니다.
      *
      * @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} 사용을 권장합니다.
      */
     connect(config: StorageConnConfig): Promise<void>;
     private _requireClient;
-    /** Create a directory. Creates parent directories if they do not exist. */
+    /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
     mkdir(dirPath: string): Promise<void>;
     rename(fromPath: string, toPath: string): Promise<void>;
     /**
-     * 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.
+     * 부모 디렉토리가 존재하지 않아도 false를 반환합니다.
+     * 네트워크 오류, 권한 오류 등 모든 예외에 대해 false를 반환합니다.
      */
     exists(filePath: string): Promise<boolean>;
     list(dirPath: string): Promise<FileInfo[]>;
     readFile(filePath: string): Promise<Bytes>;
     remove(filePath: string): Promise<void>;
-    /** Upload a local file path or byte data to the remote path. */
+    /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
     put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
     uploadDir(fromPath: string, toPath: string): Promise<void>;
     /**
-     * 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>;
 }

package/dist/clients/sftp-storage-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CvD,OAAO,CAAC,cAAc;IAOtB,2EAA2E;IACrE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAc1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,gEAAgE;IAC1D,GAAG,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}
+{"version":3,"file":"sftp-storage-client.d.ts","sourceRoot":"","sources":["..\\..\\src\\clients\\sftp-storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CvD,OAAO,CAAC,cAAc;IAOtB,0CAA0C;IACpC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAc1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,0CAA0C;IACpC,GAAG,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}