@simplysm/storage 14.0.50 → 14.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/storage",
-  "version": "14.0.50",
+  "version": "14.0.52",
   "description": "심플리즘 패키지 - 저장소 (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,14 +14,13 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": false,
   "dependencies": {
     "basic-ftp": "^5.3.0",
     "ssh2-sftp-client": "^12.1.1",
-    "@simplysm/core-common": "14.0.50"
+    "@simplysm/core-common": "14.0.52"
   },
   "devDependencies": {
     "@types/ssh2-sftp-client": "^9.0.6"

package/README.md

@@ -1,84 +0,0 @@
-# @simplysm/storage
-
-FTP/FTPS/SFTP 파일 저장소 클라이언트 라이브러리 (Node.js 전용). `StorageClient` 인터페이스로 프로토콜을 통일하고, `StorageFactory`로 연결 생명주기를 관리한다.
-
-## Installation
-
-```bash
-npm install @simplysm/storage
-```
-
-## API Overview
-
-### Types
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`StorageConnConfig`](./docs/types/storage-conn-config.md) | interface | 스토리지 서버 연결 설정 |
-| [`FileInfo`](./docs/types/file-info.md) | interface | 파일/디렉토리 정보 |
-| [`StorageClient`](./docs/types/storage-client.md) | interface | 스토리지 클라이언트 공통 인터페이스 (포함: `StorageProtocol`) |
-
-### Clients
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`FtpStorageClient`](./docs/clients/ftp-storage-client.md) | class | FTP/FTPS 프로토콜 스토리지 클라이언트 (`basic-ftp` 기반) |
-| [`SftpStorageClient`](./docs/clients/sftp-storage-client.md) | class | SFTP 프로토콜 스토리지 클라이언트 (`ssh2-sftp-client` 기반) |
-
-### Factory
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`StorageFactory`](./docs/factory/storage-factory.md) | class | 프로토콜별 클라이언트 생성 및 연결 생명주기 자동 관리 (포함: `StorageProtocol`) |
-
-## Usage Examples
-
-### SFTP로 파일 업로드 (StorageFactory 사용 권장)
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    await storage.mkdir("/remote/dir");
-    await storage.put("/local/file.txt", "/remote/dir/file.txt");
-  },
-);
-```
-
-콜백이 완료되거나 예외가 발생하면 자동으로 연결이 종료된다.
-
-### FTP로 파일 목록 조회 및 다운로드
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-const files = await StorageFactory.connect(
-  "ftp",
-  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
-  async (storage) => {
-    const list = await storage.list("/data");
-    for (const file of list.filter((f) => f.isFile)) {
-      const content = await storage.readFile(`/data/${file.name}`);
-      // content는 Bytes (Uint8Array)
-    }
-    return list;
-  },
-);
-```
-
-### SSH 키 인증으로 SFTP 연결 (비밀번호 생략)
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user" }, // password 생략 → SSH agent/키 파일 인증
-  async (storage) => {
-    const list = await storage.list("/home/user");
-  },
-);
-```

package/docs/clients/ftp-storage-client.md

@@ -1,47 +0,0 @@
-# FtpStorageClient
-
-FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트. `basic-ftp` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
-
-직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
-
-```typescript
-class FtpStorageClient implements StorageClient {
-  constructor(private readonly _secure: boolean = false);
-}
-```
-
-## Constructor
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `_secure` | `boolean` | `false` | `true`이면 FTPS (TLS/SSL 암호화), `false`이면 FTP |
-
-## Members
-
-[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
-
-| Member | Kind | Description |
-|--------|------|-------------|
-| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. 연결 실패 시 내부 `ftp.Client`를 즉시 닫고 예외를 전파 |
-| `mkdir` | method | `basic-ftp`의 `ensureDir()`을 사용하여 부모 디렉토리 포함 재귀 생성 |
-| `exists` | method | 먼저 `size()` 명령으로 파일을 O(1) 성능으로 확인. 실패 시 부모 디렉토리 `list()`로 디렉토리 존재 여부 확인. 슬래시 없는 경로(예: `file.txt`)는 루트(`/`)에서 검색. 모든 예외는 `false` 반환 |
-| `put` | method | `string`이면 파일 경로로, `Bytes`이면 `Readable` 스트림으로 변환하여 `uploadFrom()` 호출 |
-| `close` | method | 동기적으로 내부 클라이언트를 정리하고 `Promise.resolve()` 반환. 이미 종료된 상태에서 호출해도 안전 |
-
-## Usage
-
-```typescript
-import { FtpStorageClient } from "@simplysm/storage";
-
-// FTPS 사용
-const client = new FtpStorageClient(true);
-try {
-  await client.connect({ host: "ftps.example.com", user: "user", password: "pass" });
-  const exists = await client.exists("/remote/file.txt");
-  if (exists) {
-    await client.rename("/remote/file.txt", "/remote/backup.txt");
-  }
-} finally {
-  await client.close();
-}
-```

package/docs/clients/sftp-storage-client.md

@@ -1,58 +0,0 @@
-# SftpStorageClient
-
-SFTP 프로토콜을 사용하는 스토리지 클라이언트. `ssh2-sftp-client` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
-
-직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
-
-```typescript
-class SftpStorageClient implements StorageClient {
-  constructor();
-}
-```
-
-## Members
-
-[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
-
-| Member | Kind | Description |
-|--------|------|-------------|
-| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. `password` 유무에 따라 인증 방식이 달라짐 (아래 인증 메커니즘 참조). 연결 실패 시 `client.end()`를 호출하고 예외를 전파 |
-| `mkdir` | method | `ssh2-sftp-client`의 `mkdir(path, true)`를 호출하여 부모 디렉토리 포함 재귀 생성 |
-| `list` | method | `item.type === "-"`이면 파일(`isFile: true`), 아니면 디렉토리(`isFile: false`)로 변환 |
-| `exists` | method | `ssh2-sftp-client`의 `exists()` 반환값(`false \| 'd' \| '-' \| 'l'`)을 검사. 문자열이면 존재. 모든 예외는 `false` 반환 |
-| `readFile` | method | `ssh2-sftp-client`의 `get()` 반환값(`Buffer` 또는 `string`)을 `Bytes`(`Uint8Array`)로 변환 |
-| `put` | method | `string`이면 `fastPut()`으로, `Bytes`이면 `Buffer.from()` 변환 후 `put()`으로 업로드 (`ssh2-sftp-client` 라이브러리 요구사항) |
-| `close` | method | `client.end()`를 호출하여 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
-
-## Authentication
-
-`connect()` 호출 시 [`StorageConnConfig`](../types/storage-conn-config.md)의 `password` 유무에 따라 인증 방식이 결정된다:
-
-**`password`가 있는 경우**: 패스워드 인증
-
-**`password`가 없는 경우**: 다음 순서로 시도
-1. SSH agent (`SSH_AUTH_SOCK` 환경변수가 설정된 경우 `agent` 옵션 추가)
-2. `~/.ssh/id_ed25519` 개인키 파일 읽어 `privateKey` 옵션으로 인증 시도
-3. `privateKey` 파싱 실패 시 (암호화된 키 등) SSH agent만으로 재시도
-
-## Usage
-
-```typescript
-import { SftpStorageClient } from "@simplysm/storage";
-
-// 패스워드 인증
-const client = new SftpStorageClient();
-try {
-  await client.connect({ host: "sftp.example.com", user: "user", password: "pass" });
-  await client.mkdir("/remote/dir");
-  await client.put("/local/file.txt", "/remote/dir/file.txt");
-} finally {
-  await client.close();
-}
-```
-
-SSH 키 인증 사용 시 `password` 필드를 생략한다:
-
-```typescript
-await client.connect({ host: "sftp.example.com", user: "user" }); // password 생략
-```

package/docs/factory/storage-factory.md

@@ -1,82 +0,0 @@
-# StorageFactory
-
-스토리지 클라이언트 팩토리. 콜백 패턴으로 연결/종료를 자동 관리한다.
-
-```typescript
-class StorageFactory {
-  static async connect<R>(
-    type: StorageProtocol,
-    config: StorageConnConfig,
-    fn: (storage: StorageClient) => R | Promise<R>,
-  ): Promise<R>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `connect` | static | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | 프로토콜에 맞는 클라이언트를 생성하고, 연결 후 콜백을 실행하며, 완료/예외 시 자동으로 연결을 종료 |
-
-### `connect<R>()` 파라미터
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | `StorageProtocol` | 프로토콜 타입 |
-| `config` | [`StorageConnConfig`](../types/storage-conn-config.md) | 연결 설정 |
-| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트로 작업을 수행하는 콜백 |
-
-**반환**: `Promise<R>` — 콜백의 반환값
-
-**동작**:
-- `type`에 따라 [`FtpStorageClient`](../clients/ftp-storage-client.md) 또는 [`SftpStorageClient`](../clients/sftp-storage-client.md)를 생성
-- `client.connect(config)` 후 `fn(client)` 실행
-- `fn` 완료 또는 예외 발생 여부와 무관하게 `finally`에서 `client.close()` 호출
-- `fn`에서 발생한 예외는 그대로 전파
-
-## Related Types
-
-### `StorageProtocol`
-
-`StorageFactory.connect()`의 `type` 파라미터 타입.
-
-```typescript
-type StorageProtocol = "ftp" | "ftps" | "sftp";
-```
-
-| Variant | Description |
-|---------|-------------|
-| `"ftp"` | 일반 FTP. `FtpStorageClient(false)` 생성 |
-| `"ftps"` | TLS/SSL 암호화 FTP. `FtpStorageClient(true)` 생성 |
-| `"sftp"` | SSH 기반 SFTP. `SftpStorageClient()` 생성 |
-
-## Usage
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-// 파일 업로드
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    await storage.mkdir("/remote/dir");
-    await storage.put("/local/file.txt", "/remote/dir/file.txt");
-  },
-);
-
-// 파일 목록 조회 후 반환
-const list = await StorageFactory.connect(
-  "ftp",
-  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
-  (storage) => storage.list("/data"),
-);
-
-// 바이트 데이터로 업로드
-const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
-await StorageFactory.connect(
-  "ftps",
-  { host: "ftps.example.com", user: "user", password: "pass" },
-  (storage) => storage.put(data, "/remote/file.bin"),
-);
-```

package/docs/types/file-info.md

@@ -1,32 +0,0 @@
-# FileInfo
-
-파일 또는 디렉토리 정보를 담는 인터페이스. [`StorageClient.list()`](./storage-client.md)의 반환 타입이다.
-
-```typescript
-interface FileInfo {
-  name: string;
-  isFile: boolean;
-}
-```
-
-## Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | 파일 또는 디렉토리의 이름 (경로 아님, 이름만) |
-| `isFile` | `boolean` | `true`이면 파일, `false`이면 디렉토리 |
-
-## Usage
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-const items = await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user", password: "pass" },
-  async (storage) => storage.list("/remote/dir"),
-);
-
-const files = items.filter((item) => item.isFile);
-const dirs = items.filter((item) => !item.isFile);
-```

package/docs/types/storage-client.md

@@ -1,50 +0,0 @@
-# StorageClient
-
-스토리지 클라이언트 공통 인터페이스. [`FtpStorageClient`](../clients/ftp-storage-client.md)와 [`SftpStorageClient`](../clients/sftp-storage-client.md)가 구현한다.
-
-직접 사용하기보다 [`StorageFactory.connect()`](../factory/storage-factory.md)를 통해 콜백 패턴으로 사용하는 것을 권장한다.
-
-```typescript
-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>;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `connect` | method | `(config: StorageConnConfig) => Promise<void>` | 스토리지 서버에 연결. 이미 연결된 상태에서 호출하면 `SdError` 발생 |
-| `mkdir` | method | `(dirPath: string) => Promise<void>` | 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성 |
-| `rename` | method | `(fromPath: string, toPath: string) => Promise<void>` | 파일/디렉토리 이름 변경 또는 이동 |
-| `list` | method | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 내 파일/디렉토리 목록 조회 |
-| `readFile` | method | `(filePath: string) => Promise<Bytes>` | 파일 내용을 `Bytes`(`Uint8Array`)로 읽기 |
-| `exists` | method | `(filePath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인. 모든 예외는 `false` 반환 |
-| `put` | method | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
-| `uploadDir` | method | `(fromPath: string, toPath: string) => Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
-| `remove` | method | `(filePath: string) => Promise<void>` | 파일 삭제 |
-| `close` | method | `() => Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
-
-## Usage
-
-```typescript
-import type { StorageClient } from "@simplysm/storage";
-import { StorageFactory } from "@simplysm/storage";
-
-// StorageClient 타입을 직접 사용하는 경우 (예: 함수 파라미터 타입)
-async function doWork(storage: StorageClient): Promise<void> {
-  await storage.mkdir("/remote/dir");
-  await storage.put("/local/file.txt", "/remote/dir/file.txt");
-}
-
-await StorageFactory.connect("sftp", { host: "sftp.example.com", user: "user", password: "pass" }, doWork);
-```

package/docs/types/storage-conn-config.md

@@ -1,34 +0,0 @@
-# StorageConnConfig
-
-스토리지 서버 연결 설정 인터페이스.
-
-```typescript
-interface StorageConnConfig {
-  host: string;
-  port?: number;
-  user?: string;
-  password?: string;
-}
-```
-
-## Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `host` | `string` | 서버 호스트 주소 |
-| `port` | `number \| undefined` | 포트 번호. 생략 시 프로토콜 기본값 사용 (FTP/FTPS: 21, SFTP: 22) |
-| `user` | `string \| undefined` | 사용자 이름 |
-| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도 |
-
-## Usage
-
-```typescript
-import type { StorageConnConfig } from "@simplysm/storage";
-
-const config: StorageConnConfig = {
-  host: "sftp.example.com",
-  port: 22,
-  user: "user",
-  password: "pass",
-};
-```