@simplysm/storage 13.0.69 → 13.0.71

package/README.md

@@ -1,292 +1,33 @@
 # @simplysm/storage
 
-A storage client package that supports FTP, FTPS, and SFTP protocols. Through the unified `Storage` interface, you can perform file upload, download, directory manipulation and other operations with the same API regardless of protocol.
-
-Using `StorageFactory`, you can automatically manage connection/disconnection, and you can also directly instantiate `FtpStorageClient` or `SftpStorageClient` if needed.
+Simplysm Package - Storage Module (node)
 
 ## Installation
 
-```bash
-npm install @simplysm/storage
-# or
 pnpm add @simplysm/storage
-```
-
-## Main Modules
-
-### Export List
-
-| Module | Type | Description |
-|------|------|------|
-| `StorageFactory` | Class | Creates clients based on storage type and automatically manages connection/disconnection |
-| `FtpStorageClient` | Class | FTP/FTPS protocol client (based on `basic-ftp`) |
-| `SftpStorageClient` | Class | SFTP protocol client (based on `ssh2-sftp-client`) |
-| `Storage` | Interface | Common interface implemented by all storage clients |
-| `StorageConnConfig` | Interface | Connection configuration |
-| `FileInfo` | Interface | Directory entry information |
-| `StorageType` | Type | Storage protocol types (`"ftp" \| "ftps" \| "sftp"`) |
-
-## Type Definitions
-
-### StorageConnConfig
-
-Configuration required for server connection.
-
-```typescript
-interface StorageConnConfig {
-  host: string;   // Server host
-  port?: number;  // Port (FTP default: 21, SFTP default: 22)
-  user?: string;  // Username
-  pass?: string;  // Password (required for FTP/FTPS; optional for SFTP)
-}
-```
-
-**SFTP SSH Key Authentication:**
-- If `pass` is omitted for SFTP connections, the client automatically attempts authentication using:
-  1. SSH key file at `~/.ssh/id_ed25519`
-  2. SSH agent (if `SSH_AUTH_SOCK` environment variable is set)
-  - Both methods are tried in order; if the key file authentication fails (e.g., encrypted keys), the client falls back to agent-only authentication.
-
-### FileInfo
-
-File/directory information returned by `readdir()`.
-
-```typescript
-interface FileInfo {
-  name: string;    // File or directory name
-  isFile: boolean; // true if file, false if directory
-}
-```
-
-### StorageType
-
-Supported storage protocol types.
-
-```typescript
-type StorageType = "ftp" | "ftps" | "sftp";
-```
-
-| Value | Protocol | Default Port | Description |
-|-----|---------|----------|------|
-| `"ftp"` | FTP | 21 | Unencrypted FTP |
-| `"ftps"` | FTPS | 21 | TLS-encrypted FTP |
-| `"sftp"` | SFTP | 22 | SSH-based file transfer |
-
-### Storage Interface
-
-Common interface implemented by all storage clients (`FtpStorageClient`, `SftpStorageClient`). `Bytes` is a `Uint8Array` type alias defined in `@simplysm/core-common`.
-
-| Method | Signature | Description |
-|--------|---------|------|
-| `connect` | `(config: StorageConnConfig) => Promise<void>` | Connect to server |
-| `close` | `() => Promise<void>` | Close connection |
-| `put` | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | Upload file (local path or byte data) |
-| `readFile` | `(filePath: string) => Promise<Bytes>` | Download file (returns `Bytes`) |
-| `readdir` | `(dirPath: string) => Promise<FileInfo[]>` | List directory contents |
-| `remove` | `(filePath: string) => Promise<void>` | Delete file |
-| `exists` | `(filePath: string) => Promise<boolean>` | Check if file/directory exists |
-| `mkdir` | `(dirPath: string) => Promise<void>` | Create directory (recursive) |
-| `rename` | `(fromPath: string, toPath: string) => Promise<void>` | Rename file/directory |
-| `uploadDir` | `(fromPath: string, toPath: string) => Promise<void>` | Upload entire local directory to remote |
-
-## Usage
-
-### StorageFactory (Recommended)
-
-`StorageFactory.connect()` automatically manages connection and disconnection with a callback pattern. The connection is always closed even if an exception occurs in the callback, so it's recommended over using clients directly.
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-// FTP connection
-const result = await StorageFactory.connect("ftp", {
-  host: "ftp.example.com",
-  port: 21,
-  user: "username",
-  pass: "password",
-}, async (client) => {
-  // Upload local file to remote server
-  await client.put("/local/path/file.txt", "/remote/path/file.txt");
-
-  // Upload byte data directly
-  const data = new TextEncoder().encode("hello world");
-  await client.put(data, "/remote/path/hello.txt");
-
-  // Download remote file
-  const content = await client.readFile("/remote/path/file.txt");
-
-  // The callback's return value becomes the return value of StorageFactory.connect()
-  return content;
-});
-```
-
-```typescript
-// FTPS connection (TLS encryption)
-await StorageFactory.connect("ftps", {
-  host: "ftps.example.com",
-  user: "username",
-  pass: "password",
-}, async (client) => {
-  await client.put("/local/file.txt", "/remote/file.txt");
-});
-```
-
-```typescript
-// SFTP connection with password
-await StorageFactory.connect("sftp", {
-  host: "sftp.example.com",
-  port: 22,
-  user: "username",
-  pass: "password",
-}, async (client) => {
-  // List directory contents
-  const files = await client.readdir("/remote/path");
-  for (const file of files) {
-    console.log(`${file.name} - ${file.isFile ? "File" : "Directory"}`);
-  }
-
-  // Upload entire directory
-  await client.uploadDir("/local/dir", "/remote/dir");
-});
-```
-
-```typescript
-// SFTP connection with SSH key (if pass is omitted, uses ~/.ssh/id_ed25519 or SSH agent)
-await StorageFactory.connect("sftp", {
-  host: "sftp.example.com",
-  port: 22,
-  user: "username",
-  // No password provided - uses SSH key authentication
-}, async (client) => {
-  const files = await client.readdir("/remote/path");
-  await client.uploadDir("/local/dir", "/remote/dir");
-});
-```
-
-### FtpStorageClient (Direct Usage)
-
-Client that uses FTP or FTPS protocol. The `secure` parameter in the constructor determines whether to use FTPS.
-
-```typescript
-import { FtpStorageClient } from "@simplysm/storage";
-
-// FTP client (secure: false is default)
-const client = new FtpStorageClient();
-
-// FTPS client
-const secureClient = new FtpStorageClient(true);
-
-await client.connect({
-  host: "ftp.example.com",
-  port: 21,
-  user: "username",
-  pass: "password",
-});
-
-try {
-  // Upload file - from local file path
-  await client.put("/local/path/file.txt", "/remote/path/file.txt");
-
-  // Upload file - from Uint8Array byte data
-  const bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
-  await client.put(bytes, "/remote/path/hello.bin");
-
-  // Download file (returns Bytes, i.e. Uint8Array)
-  const data = await client.readFile("/remote/path/file.txt");
-  const text = new TextDecoder().decode(data);
-
-  // List directory contents
-  const files = await client.readdir("/remote/path");
-
-  // Check if file/directory exists
-  const exists = await client.exists("/remote/path/file.txt");
-
-  // Create directory (creates parent directories too)
-  await client.mkdir("/remote/new/nested/path");
-
-  // Rename file
-  await client.rename("/remote/old-name.txt", "/remote/new-name.txt");
-
-  // Delete file
-  await client.remove("/remote/path/file.txt");
-
-  // Upload entire local directory to remote
-  await client.uploadDir("/local/dir", "/remote/dir");
-} finally {
-  // Connection must be closed
-  await client.close();
-}
-```
-
-### SftpStorageClient (Direct Usage)
-
-Client that uses SFTP protocol. It implements the same `Storage` interface as `FtpStorageClient`, so the API is identical.
-
-```typescript
-import { SftpStorageClient } from "@simplysm/storage";
-
-const client = new SftpStorageClient();
-
-// Connection with password
-await client.connect({
-  host: "sftp.example.com",
-  port: 22,
-  user: "username",
-  pass: "password",
-});
-
-try {
-  // All methods of the Storage interface can be used identically
-  await client.put("/local/path/file.txt", "/remote/path/file.txt");
-  const data = await client.readFile("/remote/path/file.txt");
-  const files = await client.readdir("/remote/path");
-  const exists = await client.exists("/remote/path/file.txt");
-  await client.mkdir("/remote/new/path");
-  await client.rename("/remote/old.txt", "/remote/new.txt");
-  await client.remove("/remote/path/file.txt");
-  await client.uploadDir("/local/dir", "/remote/dir");
-} finally {
-  await client.close();
-}
-```
-
-```typescript
-// Connection with SSH key (password omitted)
-const client = new SftpStorageClient();
-
-await client.connect({
-  host: "sftp.example.com",
-  port: 22,
-  user: "username",
-  // Uses ~/.ssh/id_ed25519 or SSH agent for authentication
-});
-
-try {
-  await client.put("/local/path/file.txt", "/remote/path/file.txt");
-  // ... other operations
-} finally {
-  await client.close();
-}
-```
 
-## Caveats
+## Source Index
 
-### Connection Management
+### Types
 
-- Using `StorageFactory.connect()` is recommended. The connection is automatically closed when the callback ends, and closure is guaranteed in the `finally` block even if an exception occurs.
-- When using clients directly, you must call `close()` with a `try/finally` pattern. Otherwise, connections may leak.
-- Calling `connect()` again on an already connected instance will cause an error. If reconnection is needed, call `close()` first.
-- Calling `close()` when already closed does not cause an error.
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/types/storage-conn-config.ts` | `StorageConnConfig` | Connection config interface (host, port, user, pass) | - |
+| `src/types/storage.ts` | `FileInfo`, `Storage` | Storage interface and file entry type | - |
+| `src/types/storage-type.ts` | `StorageType` | Union type for supported protocols: ftp, ftps, sftp | - |
 
-### exists() Behavior
+### Clients
 
-- FTP: Checks files with the `SIZE` command (O(1)), and on failure, lists the parent directory to check if a directory exists. Performance may degrade in directories with many entries.
-- SFTP: Uses `ssh2-sftp-client`'s `exists()` method, returns `true` for files (`"-"`), directories (`"d"`), and symbolic links (`"l"`).
-- Both implementations return `false` instead of throwing exceptions when the parent directory doesn't exist or on network/permission errors.
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/clients/ftp-storage-client.ts` | `FtpStorageClient` | Storage client for FTP/FTPS protocol | `ftp-storage-client.spec.ts` |
+| `src/clients/sftp-storage-client.ts` | `SftpStorageClient` | Storage client for SFTP protocol with SSH key support | `sftp-storage-client.spec.ts` |
 
-### Byte Data Type
+### Factory
 
-- `Bytes` used in the return type of `readFile()` and input type of `put()` is a `Uint8Array` type alias defined in `@simplysm/core-common`.
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/storage-factory.ts` | `StorageFactory` | Factory that creates and auto-closes storage connections | `storage-factory.spec.ts` |
 
 ## License
 

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

@@ -2,54 +2,54 @@ import type { Bytes } from "@simplysm/core-common";
 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 declare class FtpStorageClient implements Storage {
     private readonly _secure;
     private _client;
     constructor(_secure?: boolean);
     /**
-     * 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).
      */
     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>;
     readdir(dirPath: string): Promise<FileInfo[]>;
     readFile(filePath: string): Promise<Bytes>;
     /**
-     * 파일 또는 디렉토리 존재 여부를 확인합니다.
+     * 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.
      */
     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
-     * 이미 종료된 상태에서 호출해도 에러가 발생하지 않습니다.
-     * 종료 후에는 동일 인스턴스에서 {@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>;
 }

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,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAGlC,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,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK7C,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"}
+{"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,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAGlC,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,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK7C,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"}

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

@@ -7,16 +7,16 @@ class FtpStorageClient {
   }
   _client;
   /**
-   * 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) {
     if (this._client !== void 0) {
-      throw new SdError("\uC774\uBBF8 FTP \uC11C\uBC84\uC5D0 \uC5F0\uACB0\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 close()\uB97C \uD638\uCD9C\uD558\uC138\uC694.");
+      throw new SdError("FTP server is already connected. Please call close() first.");
     }
     const client = new ftp.Client();
     try {
@@ -35,11 +35,11 @@ class FtpStorageClient {
   }
   _requireClient() {
     if (this._client === void 0) {
-      throw new SdError("FTP \uC11C\uBC84\uC5D0 \uC5F0\uACB0\uB418\uC5B4\uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+      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) {
     await this._requireClient().ensureDir(dirPath);
   }
@@ -61,16 +61,16 @@ class FtpStorageClient {
     return bytesConcat(chunks);
   }
   /**
-   * 파일 또는 디렉토리 존재 여부를 확인합니다.
+   * 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) {
     try {
@@ -91,7 +91,7 @@ class FtpStorageClient {
   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") {
@@ -105,11 +105,11 @@ class FtpStorageClient {
     await this._requireClient().uploadFromDir(fromPath, toPath);
   }
   /**
-   * 연결을 종료합니다.
+   * 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() {
     if (this._client === void 0) {

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

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

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

@@ -2,46 +2,46 @@ import type { Bytes } from "@simplysm/core-common";
 import type { Storage, FileInfo } from "../types/storage";
 import type { StorageConnConfig } from "../types/storage-conn-config";
 /**
- * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
+ * Storage client using SFTP protocol.
  *
  * @remarks
- * 직접 사용보다 {@link StorageFactory.connect}를 통한 사용을 권장합니다.
+ * Using {@link StorageFactory.connect} is recommended over direct usage.
  */
 export declare class SftpStorageClient implements Storage {
     private _client;
     /**
-     * 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).
      */
     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
-     * 상위 디렉토리가 존재하지 않는 경우에도 false를 반환합니다.
-     * 네트워크 오류, 권한 오류 등 모든 예외도 false를 반환합니다.
+     * Returns false even if the parent directory does not exist.
+     * Returns false for all exceptions including network errors and permission errors.
      */
     exists(filePath: string): Promise<boolean>;
     readdir(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
-     * 이미 종료된 상태에서 호출해도 에러가 발생하지 않습니다.
-     * 종료 후에는 동일 인스턴스에서 {@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>;
 }

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,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CvD,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,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ7C,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"}
+{"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,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAKtE;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,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,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAQ7C,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"}

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

@@ -3,16 +3,16 @@ import SftpClient from "ssh2-sftp-client";
 class SftpStorageClient {
   _client;
   /**
-   * 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) {
     if (this._client !== void 0) {
-      throw new SdError("\uC774\uBBF8 SFTP \uC11C\uBC84\uC5D0 \uC5F0\uACB0\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 close()\uB97C \uD638\uCD9C\uD558\uC138\uC694.");
+      throw new SdError("SFTP server is already connected. Please call close() first.");
     }
     const client = new SftpClient();
     try {
@@ -51,11 +51,11 @@ class SftpStorageClient {
   }
   _requireClient() {
     if (this._client === void 0) {
-      throw new SdError("SFTP \uC11C\uBC84\uC5D0 \uC5F0\uACB0\uB418\uC5B4\uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+      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) {
     await this._requireClient().mkdir(dirPath, true);
   }
@@ -63,11 +63,11 @@ class SftpStorageClient {
     await this._requireClient().rename(fromPath, toPath);
   }
   /**
-   * 파일 또는 디렉토리 존재 여부를 확인합니다.
+   * 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) {
     try {
@@ -92,12 +92,12 @@ class SftpStorageClient {
     if (typeof result === "string") {
       return new TextEncoder().encode(result);
     }
-    throw new SdError("\uC608\uC0C1\uCE58 \uBABB\uD55C \uC751\uB2F5 \uD0C0\uC785\uC785\uB2C8\uB2E4.");
+    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);
@@ -109,11 +109,11 @@ class SftpStorageClient {
     await this._requireClient().uploadDir(fromPath, toPath);
   }
   /**
-   * 연결을 종료합니다.
+   * 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() {
     if (this._client === void 0) {