@simplysm/storage 13.0.96 → 13.0.98

package/README.md

@@ -1,223 +1,179 @@
 # @simplysm/storage
 
-FTP, FTPS, SFTP 원격 스토리지 통합 라이브러리. 팩토리 패턴으로 프로토콜에 독립적인 파일 전송을 제공한다.
+Storage Module (node) -- FTP, FTPS, and SFTP storage client with a unified interface and factory pattern.
 
-## 설치
+## Installation
 
 ```bash
 npm install @simplysm/storage
 ```
 
-**의존성:** `basic-ftp` (FTP/FTPS), `ssh2-sftp-client` (SFTP), `@simplysm/core-common`
+## API Overview
 
-## 빠른 시작
+### Types
 
-```typescript
-import { StorageFactory } from "@simplysm/storage";
+| API | Type | Description |
+|-----|------|-------------|
+| `StorageProtocol` | type | Protocol type: `"ftp"`, `"ftps"`, `"sftp"` |
+| `StorageConnConfig` | interface | Connection configuration (host, port, user, password) |
+| `FileInfo` | interface | File entry info (`name`, `isFile`) |
+| `StorageClient` | interface | Unified storage client interface |
 
-// 팩토리 패턴: 연결 → 작업 → 자동 종료
-await StorageFactory.connect("sftp", {
-  host: "example.com",
-  port: 22,
-  user: "deploy",
-  password: "secret",
-}, async (storage) => {
-  await storage.put("/local/file.zip", "/remote/file.zip");
-  await storage.uploadDir("/local/dist", "/remote/www");
-  const files = await storage.list("/remote/www");
-  const exists = await storage.exists("/remote/file.zip");
-});
-// 콜백 종료 시 연결 자동 해제 (예외 발생해도 보장)
-```
+### Factory
+
+| API | Type | Description |
+|-----|------|-------------|
+| `StorageFactory` | class | Factory that creates and manages storage connections |
+
+### Clients
 
-## 타입 정의
+| API | Type | Description |
+|-----|------|-------------|
+| `FtpStorageClient` | class | FTP/FTPS storage client (basic-ftp) |
+| `SftpStorageClient` | class | SFTP storage client (ssh2-sftp-client) |
 
-### StorageProtocol
+## `StorageProtocol`
 
 ```typescript
 type StorageProtocol = "ftp" | "ftps" | "sftp";
 ```
 
-| 값 | 설명 | 내부 클라이언트 |
-|-----|------|----------------|
-| `"ftp"` | File Transfer Protocol | `FtpStorageClient(secure=false)` |
-| `"ftps"` | FTP over SSL/TLS | `FtpStorageClient(secure=true)` |
-| `"sftp"` | SSH File Transfer Protocol | `SftpStorageClient` |
-
-### StorageConnConfig
+## `StorageConnConfig`
 
 ```typescript
 interface StorageConnConfig {
   host: string;
-  port?: number;   // 미지정 시 프로토콜 기본값 사용
+  port?: number;
   user?: string;
   password?: string;
 }
 ```
 
-- **SFTP에서 `password` 미지정 시**: SSH 키 인증으로 전환
-  1. `~/.ssh/id_ed25519` 키 파일 자동 탐색
-  2. 키 파싱 실패 시 `SSH_AUTH_SOCK` 환경변수의 SSH 에이전트로 재시도
-
-### FileInfo
+## `FileInfo`
 
 ```typescript
 interface FileInfo {
-  name: string;     // 파일/디렉토리 이름
-  isFile: boolean;  // true: 파일, false: 디렉토리
+  name: string;
+  isFile: boolean;
 }
 ```
 
-### Bytes
-
-`@simplysm/core-common`에서 정의한 바이트 배열 타입 (`Uint8Array` 기반).
-
-## API 레퍼런스
-
-### StorageFactory
-
-프로토콜에 독립적으로 스토리지 클라이언트를 생성하고 연결을 관리하는 팩토리 클래스.
-
-#### `StorageFactory.connect<R>(type, config, fn): Promise<R>`
+## `StorageClient`
 
 ```typescript
-static async connect<R>(
-  type: StorageProtocol,
-  config: StorageConnConfig,
-  fn: (storage: StorageClient) => R | Promise<R>,
-): Promise<R>
+interface StorageClient {
+  connect(config: StorageConnConfig): Promise<void>;
+  mkdir(dirPath: string): Promise<void>;
+  rename(fromPath: string, toPath: string): Promise<void>;
+  list(dirPath: string): Promise<FileInfo[]>;
+  readFile(filePath: string): Promise<Bytes>;
+  exists(filePath: string): Promise<boolean>;
+  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  uploadDir(fromPath: string, toPath: string): Promise<void>;
+  remove(filePath: string): Promise<void>;
+  close(): Promise<void>;
+}
 ```
 
-- 연결 수립 → 콜백 실행 → 연결 종료를 자동 관리
-- 콜백에서 예외가 발생해도 `finally`에서 연결이 안전하게 종료됨
-- 콜백의 반환값을 그대로 반환 (제네릭 `R`)
+## `StorageFactory`
 
 ```typescript
-// 반환값 활용 예시
-const fileList = await StorageFactory.connect("ftp", config, async (storage) => {
-  return await storage.list("/data");
-});
-// fileList: FileInfo[]
+class StorageFactory {
+  static async connect<R>(
+    type: StorageProtocol,
+    config: StorageConnConfig,
+    fn: (storage: StorageClient) => R | Promise<R>,
+  ): Promise<R>;
+}
 ```
 
-### StorageClient (공통 인터페이스)
-
-`FtpStorageClient`와 `SftpStorageClient`가 구현하는 공통 인터페이스. `StorageFactory.connect` 콜백의 `storage` 파라미터 타입이다.
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `connect` | `(config: StorageConnConfig) => Promise<void>` | 서버 연결. 이미 연결된 인스턴스에서 호출하면 에러 발생 |
-| `close` | `() => Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전함 |
-| `mkdir` | `(dirPath: string) => Promise<void>` | 디렉토리 생성 (부모 디렉토리 자동 생성) |
-| `rename` | `(fromPath: string, toPath: string) => Promise<void>` | 파일/디렉토리 이름 변경 |
-| `list` | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 내 항목 목록 조회 |
-| `readFile` | `(filePath: string) => Promise<Bytes>` | 원격 파일을 바이트 배열로 읽기 |
-| `exists` | `(filePath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인 |
-| `put` | `(localPathOrBuffer: string \| Bytes, remotePath: string) => Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
-| `uploadDir` | `(fromPath: string, toPath: string) => Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
-| `remove` | `(filePath: string) => Promise<void>` | 원격 파일 삭제 |
-
-#### 메서드별 주의사항
-
-**`exists`**: 부모 디렉토리가 존재하지 않아도 `false` 반환. 네트워크 오류/권한 오류 등 모든 예외에 대해서도 `false` 반환.
-- FTP: `size()` 명령으로 파일 확인 (O(1)), 실패 시 부모 디렉토리 `list()`로 폴백
-- SFTP: `exists()` 내장 메서드 사용 (반환값 `false | 'd' | '-' | 'l'`)
-
-**`mkdir`**: 부모 디렉토리가 없으면 재귀적으로 생성한다.
-
-**`put`**: 첫 번째 인자로 로컬 파일 경로(string) 또는 바이트 데이터(Bytes)를 받는다.
-- SFTP는 파일 경로 전달 시 `fastPut` 사용 (병렬 전송으로 더 빠름)
-
-**`connect`**: 이미 연결된 인스턴스에서 중복 호출하면 `SdError` 발생. 반드시 `close()` 후 재연결해야 한다.
+Creates a storage connection, executes the callback, and automatically closes the connection. The connection is closed even if the callback throws an exception. This is the recommended way to use storage clients.
 
-### FtpStorageClient
-
-FTP/FTPS 프로토콜 클라이언트. 내부적으로 `basic-ftp` 라이브러리를 사용한다.
+## `FtpStorageClient`
 
 ```typescript
-import { FtpStorageClient } from "@simplysm/storage";
-
-const client = new FtpStorageClient(secure?: boolean);
-// secure=false: FTP (기본값)
-// secure=true: FTPS
+class FtpStorageClient implements StorageClient {
+  constructor(secure?: boolean);
+  async connect(config: StorageConnConfig): Promise<void>;
+  async mkdir(dirPath: string): Promise<void>;
+  async rename(fromPath: string, toPath: string): Promise<void>;
+  async list(dirPath: string): Promise<FileInfo[]>;
+  async readFile(filePath: string): Promise<Bytes>;
+  async exists(filePath: string): Promise<boolean>;
+  async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  async uploadDir(fromPath: string, toPath: string): Promise<void>;
+  async remove(filePath: string): Promise<void>;
+  close(): Promise<void>;
+}
 ```
 
-직접 사용 시 반드시 `connect` → 작업 → `close` 순서를 지켜야 한다. `StorageFactory.connect` 사용을 권장한다.
-
-### SftpStorageClient
+FTP/FTPS storage client. The `secure` constructor parameter controls FTPS mode. Use `StorageFactory.connect` instead of direct usage for automatic connection lifecycle management.
 
-SFTP 프로토콜 클라이언트. 내부적으로 `ssh2-sftp-client` 라이브러리를 사용한다.
+## `SftpStorageClient`
 
 ```typescript
-import { SftpStorageClient } from "@simplysm/storage";
-
-const client = new SftpStorageClient();
+class SftpStorageClient implements StorageClient {
+  async connect(config: StorageConnConfig): Promise<void>;
+  async mkdir(dirPath: string): Promise<void>;
+  async rename(fromPath: string, toPath: string): Promise<void>;
+  async list(dirPath: string): Promise<FileInfo[]>;
+  async readFile(filePath: string): Promise<Bytes>;
+  async exists(filePath: string): Promise<boolean>;
+  async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  async uploadDir(fromPath: string, toPath: string): Promise<void>;
+  async remove(filePath: string): Promise<void>;
+  async close(): Promise<void>;
+}
 ```
 
-**인증 방식 (자동 선택):**
-1. `password`가 있으면 비밀번호 인증
-2. `password`가 없으면 키 기반 인증:
-   - `~/.ssh/id_ed25519` 키 파일 + SSH 에이전트(`SSH_AUTH_SOCK`) 시도
-   - 키 파싱 실패 시 SSH 에이전트만으로 재시도
+SFTP storage client. Supports password authentication and SSH key/agent authentication. Use `StorageFactory.connect` instead of direct usage for automatic connection lifecycle management.
 
-## 사용 예제
+## Usage Examples
 
-### 파일 업로드/다운로드
+### Upload files via StorageFactory (recommended)
 
 ```typescript
-await StorageFactory.connect("sftp", config, async (storage) => {
-  // 로컬 파일 업로드
-  await storage.put("/local/path/file.txt", "/remote/path/file.txt");
-
-  // 바이트 데이터 직접 업로드
-  const data = new TextEncoder().encode("hello");
-  await storage.put(data, "/remote/path/hello.txt");
-
-  // 파일 읽기
-  const content = await storage.readFile("/remote/path/file.txt");
-});
-```
-
-### 디렉토리 관리
+import { StorageFactory } from "@simplysm/storage";
 
-```typescript
-await StorageFactory.connect("ftp", config, async (storage) => {
-  // 디렉토리 생성 (중첩 경로 자동 생성)
-  await storage.mkdir("/remote/a/b/c");
-
-  // 디렉토리 전체 업로드
-  await storage.uploadDir("/local/dist", "/remote/www");
-
-  // 디렉토리 목록 조회
-  const items = await storage.list("/remote/www");
-  for (const item of items) {
-    // item.name: 이름, item.isFile: 파일 여부
-  }
+await StorageFactory.connect("sftp", {
+  host: "example.com",
+  user: "deploy",
+  password: "secret",
+}, async (storage) => {
+  await storage.mkdir("/var/www/app");
+  await storage.put("/local/dist/bundle.js", "/var/www/app/bundle.js");
 });
+// Connection is automatically closed
 ```
 
-### 파일 존재 확인 및 삭제
+### List remote directory
 
 ```typescript
-await StorageFactory.connect("ftps", config, async (storage) => {
-  if (await storage.exists("/remote/old-file.txt")) {
-    await storage.remove("/remote/old-file.txt");
-  }
+import { StorageFactory } from "@simplysm/storage";
 
-  await storage.rename("/remote/temp.txt", "/remote/final.txt");
+const files = await StorageFactory.connect("ftp", {
+  host: "files.example.com",
+  user: "admin",
+  password: "pass",
+}, async (storage) => {
+  return await storage.list("/uploads");
 });
+
+for (const file of files) {
+  // file.name, file.isFile
+}
 ```
 
-### SSH 키 인증 (SFTP)
+### Upload entire directory via FTPS
 
 ```typescript
-// password 미지정 시 자동으로 키 기반 인증
-await StorageFactory.connect("sftp", {
-  host: "example.com",
-  port: 22,
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect("ftps", {
+  host: "secure.example.com",
   user: "deploy",
-  // password 생략 → ~/.ssh/id_ed25519 + SSH_AUTH_SOCK 사용
+  password: "secret",
 }, async (storage) => {
-  await storage.uploadDir("/local/build", "/var/www/html");
+  await storage.uploadDir("/local/dist", "/remote/app");
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/storage",
-  "version": "13.0.96",
+  "version": "13.0.98",
   "description": "Simplysm Package - Storage Module (node)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -21,7 +21,7 @@
   "dependencies": {
     "basic-ftp": "^5.2.0",
     "ssh2-sftp-client": "^12.1.0",
-    "@simplysm/core-common": "13.0.96"
+    "@simplysm/core-common": "13.0.98"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"