@simplysm/capacitor-plugin-file-system 14.0.46 → 14.0.48

package/README.md

@@ -0,0 +1,133 @@
+# @simplysm/capacitor-plugin-file-system
+
+Capacitor 플러그인으로 Android 파일 시스템 접근을 제공합니다. 외부 저장소 전체 접근 및 앱 전용 디렉토리 접근을 지원하며, 브라우저 환경에서는 IndexedDB 기반 가상 파일 시스템으로 에뮬레이션합니다.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-file-system
+```
+
+## API Overview
+
+### Core File System Operations
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FileSystem.readdir` | function | 디렉토리의 파일/폴더 목록 조회 |
+| `FileSystem.writeFile` | function | 파일 쓰기 (문자열 또는 Bytes) |
+| `FileSystem.readFile` | function | 파일 읽기 (기본: Bytes, encoding="utf8" 시: string) |
+| `FileSystem.remove` | function | 파일/디렉토리 삭제 (재귀) |
+| `FileSystem.mkdir` | function | 디렉토리 생성 (재귀) |
+| `FileSystem.exists` | function | 파일/디렉토리 존재 여부 확인 |
+
+→ See [docs/file-operations.md](./docs/file-operations.md) for details.
+
+### Storage & Paths
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FileSystem.getStoragePath` | function | 저장소 유형별 경로 조회 (external, externalFiles, appCache 등) |
+| `FileSystem.getUri` | function | 파일 URI 조회 (FileProvider Blob URL) |
+| `StorageType` | type | 저장소 유형 (external, externalFiles, externalCache, externalMedia, appData, appFiles, appCache) |
+
+→ See [docs/storage-paths.md](./docs/storage-paths.md) for details.
+
+### Permissions
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FileSystem.checkPermissions` | function | 파일 시스템 접근 권한 확인 |
+| `FileSystem.requestPermissions` | function | 파일 시스템 접근 권한 요청 |
+
+→ See [docs/permissions.md](./docs/permissions.md) for details.
+
+### Types
+
+| API | Type | Description |
+|-----|------|-------------|
+| `FileInfo` | interface | 파일/디렉토리 정보 (name, isDirectory) |
+
+→ See [docs/types.md](./docs/types.md) for details.
+
+## Usage Examples
+
+### 권한 확인 후 파일 읽기
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+async function readAppFile() {
+  // 권한 확인
+  const hasPermission = await FileSystem.checkPermissions();
+  if (!hasPermission) {
+    await FileSystem.requestPermissions();
+  }
+
+  // 앱 파일 디렉토리 경로 조회
+  const appFilesPath = await FileSystem.getStoragePath("appFiles");
+
+  // 파일 읽기 (문자열)
+  const content = await FileSystem.readFile(appFilesPath + "/config.json", "utf8");
+  console.log(content);
+}
+```
+
+### Bytes 데이터 쓰기
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+import { bytes } from "@simplysm/core-common";
+
+async function writeAppDataAsBytes() {
+  const appCachePath = await FileSystem.getStoragePath("appCache");
+  
+  // Uint8Array로 작성
+  const data = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header
+  await FileSystem.writeFile(appCachePath + "/image.png", data);
+}
+```
+
+### 디렉토리 탐색
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+async function listDirectory(dirPath: string) {
+  const files = await FileSystem.readdir(dirPath);
+  
+  for (const file of files) {
+    console.log(`${file.name} ${file.isDirectory ? "(dir)" : "(file)"}`);
+  }
+  
+  // 삭제 전 존재 여부 확인
+  const exists = await FileSystem.exists(dirPath);
+  if (exists) {
+    await FileSystem.remove(dirPath);
+  }
+}
+```
+
+### 브라우저에서 Blob URL 사용
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+async function showImageInBrowser() {
+  const appFilesPath = await FileSystem.getStoragePath("appFiles");
+  const imagePath = appFilesPath + "/photo.jpg";
+  
+  // Blob URL 획득
+  const uri = await FileSystem.getUri(imagePath);
+  
+  // DOM에서 사용
+  const img = document.createElement("img");
+  img.src = uri;
+  document.body.appendChild(img);
+  
+  // 사용 완료 후 URL 해제 (메모리 누수 방지)
+  img.onload = () => {
+    URL.revokeObjectURL(uri);
+  };
+}
+```

package/docs/file-operations.md

@@ -0,0 +1,154 @@
+# File Operations
+
+## `FileSystem.readdir`
+
+디렉토리의 파일과 폴더 목록을 조회합니다.
+
+```typescript
+static async readdir(dirPath: string): Promise<FileInfo[]>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dirPath` | string | 조회할 디렉토리의 절대 경로 |
+
+**Return**: 디렉토리 내 파일/폴더 목록 (각 항목은 name과 isDirectory 포함)
+
+**Throws**: 디렉토리가 존재하지 않거나 허용되지 않는 경로일 경우 Error
+
+```typescript
+const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+for (const file of files) {
+  console.log(`${file.name} ${file.isDirectory ? "[DIR]" : ""}`);
+}
+```
+
+## `FileSystem.writeFile`
+
+파일을 작성합니다. 문자열 또는 Bytes(Uint8Array) 데이터를 지원합니다.
+
+```typescript
+static async writeFile(filePath: string, data: string | Bytes): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 쓸 파일의 절대 경로 |
+| `data` | string \| Bytes | 파일 내용 (문자열 또는 Uint8Array) |
+
+**Behavior**:
+- 문자열인 경우: UTF-8 인코딩으로 저장 (encoding: "utf8")
+- Bytes인 경우: Base64 인코딩으로 저장 (encoding: "base64")
+- 상위 디렉토리가 없으면 자동 생성 (웹 환경에서만)
+
+**Throws**: 쓰기 권한 없을 경우 Error
+
+```typescript
+// 문자열 쓰기
+await FileSystem.writeFile("/storage/emulated/0/Documents/notes.txt", "Hello, World!");
+
+// Bytes 쓰기 (예: PNG 이미지)
+const pngData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+await FileSystem.writeFile("/storage/emulated/0/Pictures/image.png", pngData);
+```
+
+## `FileSystem.readFile`
+
+파일을 읽습니다. 기본적으로 Bytes를 반환하며, encoding 파라미터로 문자열 반환을 지정할 수 있습니다.
+
+```typescript
+static async readFile(filePath: string): Promise<Bytes>;
+static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 읽을 파일의 절대 경로 |
+| `encoding` | "utf8" (optional) | "utf8"일 경우 string 반환, 생략 시 Bytes 반환 |
+
+**Return**:
+- encoding 생략: `Promise<Bytes>` (Uint8Array)
+- encoding="utf8": `Promise<string>`
+
+**Throws**: 파일이 없거나 읽기 권한이 없을 경우 Error
+
+```typescript
+// Bytes로 읽기 (기본)
+const imageData = await FileSystem.readFile("/storage/emulated/0/Pictures/photo.jpg");
+console.log(imageData instanceof Uint8Array); // true
+
+// 문자열로 읽기
+const config = await FileSystem.readFile("/storage/emulated/0/Documents/config.json", "utf8");
+const obj = JSON.parse(config);
+```
+
+## `FileSystem.remove`
+
+파일 또는 디렉토리를 삭제합니다. 디렉토리인 경우 재귀적으로 삭제됩니다.
+
+```typescript
+static async remove(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 삭제할 파일/디렉토리의 절대 경로 |
+
+**Behavior**:
+- 파일: 즉시 삭제
+- 디렉토리: 하위의 모든 파일/폴더 포함하여 재귀 삭제
+- 웹 환경: 경로 프리픽스로 모든 관련 항목 삭제
+
+**Throws**: 대상이 존재하지 않거나 권한 없을 경우 Error
+
+```typescript
+// 파일 삭제
+await FileSystem.remove("/storage/emulated/0/Documents/temp.txt");
+
+// 디렉토리 재귀 삭제
+await FileSystem.remove("/storage/emulated/0/Documents/old_backup");
+```
+
+## `FileSystem.mkdir`
+
+디렉토리를 생성합니다. 상위 경로가 없는 경우 자동으로 생성됩니다 (재귀 생성).
+
+```typescript
+static async mkdir(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 생성할 디렉토리의 절대 경로 |
+
+**Behavior**:
+- 중간 경로가 없어도 자동 생성
+- 이미 존재하면 아무 동작 없음
+
+**Throws**: 권한 없을 경우 Error
+
+```typescript
+// 중간 경로 자동 생성
+await FileSystem.mkdir("/storage/emulated/0/Documents/projects/2025/Q1");
+```
+
+## `FileSystem.exists`
+
+파일 또는 디렉토리의 존재 여부를 확인합니다.
+
+```typescript
+static async exists(targetPath: string): Promise<boolean>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 확인할 파일/디렉토리의 절대 경로 |
+
+**Return**: true (존재), false (존재하지 않음)
+
+```typescript
+const exists = await FileSystem.exists("/storage/emulated/0/Documents/config.json");
+if (!exists) {
+  await FileSystem.writeFile("/storage/emulated/0/Documents/config.json", "{}");
+}
+```

package/docs/permissions.md

@@ -0,0 +1,84 @@
+# Permissions
+
+## `FileSystem.checkPermissions`
+
+파일 시스템 접근 권한 여부를 확인합니다.
+
+```typescript
+static async checkPermissions(): Promise<boolean>
+```
+
+**Return**: true (권한 허용), false (권한 거부)
+
+**플랫폼별 동작**:
+- **Android**: 현재 권한 상태 확인 (MANAGE_EXTERNAL_STORAGE 또는 READ/WRITE_EXTERNAL_STORAGE)
+- **Web**: 항상 true (권한 개념 없음)
+
+```typescript
+const hasPermission = await FileSystem.checkPermissions();
+if (hasPermission) {
+  // 파일 접근 가능
+  const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+} else {
+  // 권한 요청 필요
+  await FileSystem.requestPermissions();
+}
+```
+
+## `FileSystem.requestPermissions`
+
+파일 시스템 접근 권한을 요청합니다.
+
+```typescript
+static async requestPermissions(): Promise<void>
+```
+
+**플랫폼별 동작**:
+- **Android 11+ (API 30+)**:
+  - `MANAGE_EXTERNAL_STORAGE` 권한 요청
+  - 설정 화면으로 이동하여 사용자가 수동으로 허용
+  - 권한 대화상자가 표시되지 않음
+- **Android 10 이하 (API 29-)**:
+  - `READ_EXTERNAL_STORAGE` + `WRITE_EXTERNAL_STORAGE` 요청
+  - 표준 권한 대화상자 표시
+- **Web**: 아무 동작 없음
+
+```typescript
+async function ensureFileSystemAccess() {
+  const hasPermission = await FileSystem.checkPermissions();
+  
+  if (!hasPermission) {
+    try {
+      await FileSystem.requestPermissions();
+      console.log("Permission granted");
+    } catch (error) {
+      console.error("Permission request failed:", error);
+    }
+  }
+}
+
+// 앱 시작 시 권한 확인
+await ensureFileSystemAccess();
+
+// 외부 저장소 접근
+const externalPath = await FileSystem.getStoragePath("external");
+const files = await FileSystem.readdir(externalPath);
+```
+
+## 권한 관련 주의사항
+
+### Android 11+ (Scoped Storage)
+
+- `MANAGE_EXTERNAL_STORAGE` 권한은 특수 권한이며, 일반 권한 대화상자로 요청할 수 없습니다.
+- 권한 요청 시 설정 앱으로 이동하므로 사용자가 직접 허용/거부를 선택해야 합니다.
+- AndroidManifest.xml에 `android.permission.MANAGE_EXTERNAL_STORAGE`를 선언해야 합니다.
+
+### Android 10 이하
+
+- `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE` 권한이 필요합니다.
+- 이 권한들은 위험한(Dangerous) 권한으로 분류되어 런타임 권한 요청이 필요합니다.
+
+### 웹 환경
+
+- 권한 개념이 없으며, IndexedDB 기반 가상 파일 시스템을 사용합니다.
+- 사용자는 브라우저 저장소 한도에만 제한됩니다.

package/docs/storage-paths.md

@@ -0,0 +1,107 @@
+# Storage & Paths
+
+## `FileSystem.getStoragePath`
+
+저장소 유형별로 기기의 실제 경로(Android) 또는 가상 경로(웹)를 반환합니다.
+
+```typescript
+static async getStoragePath(type: StorageType): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | StorageType | 저장소 유형 |
+
+**Return**: 절대 경로 문자열
+
+**StorageType 종류**:
+
+| Type | Android Path | Web Path | 설명 |
+|------|--------------|----------|------|
+| `external` | `Environment.getExternalStorageDirectory()` | `/webfs/external` | 외부 저장소 루트 (공유 저장소) |
+| `externalFiles` | `getExternalFilesDir(null)` | `/webfs/externalFiles` | 앱 전용 외부 파일 디렉토리 |
+| `externalCache` | `externalCacheDir` | `/webfs/externalCache` | 앱 전용 외부 캐시 디렉토리 |
+| `externalMedia` | `externalMediaDirs[0]` | `/webfs/externalMedia` | 앱 전용 외부 미디어 디렉토리 |
+| `appData` | `applicationInfo.dataDir` | `/webfs/appData` | 앱 데이터 디렉토리 (내부) |
+| `appFiles` | `filesDir` | `/webfs/appFiles` | 앱 파일 디렉토리 (내부) |
+| `appCache` | `cacheDir` | `/webfs/appCache` | 앱 캐시 디렉토리 (내부) |
+
+```typescript
+// 앱 캐시 디렉토리에 임시 파일 작성
+const cachePath = await FileSystem.getStoragePath("appCache");
+await FileSystem.writeFile(cachePath + "/temp.dat", "temporary data");
+
+// 외부 파일 디렉토리에 문서 저장
+const filesPath = await FileSystem.getStoragePath("externalFiles");
+await FileSystem.mkdir(filesPath + "/documents");
+await FileSystem.writeFile(filesPath + "/documents/report.pdf", pdfBytes);
+```
+
+## `FileSystem.getUri`
+
+파일의 URI를 조회합니다. 주로 Blob URL(웹) 또는 FileProvider URI(Android)로 반환됩니다.
+
+```typescript
+static async getUri(filePath: string): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 파일의 절대 경로 |
+
+**Return**: URI 문자열
+- Android: `content://` scheme의 FileProvider URI
+- Web: `blob://` scheme의 Blob URL
+
+**Web 환경 주의사항**:
+반환된 Blob URL은 사용 후 반드시 `URL.revokeObjectURL(uri)`로 해제해야 합니다. 해제하지 않으면 메모리 누수가 발생할 수 있습니다.
+
+```typescript
+// 웹 환경: Blob URL 사용 후 해제
+const imagePath = await FileSystem.getStoragePath("appFiles");
+const imageFile = imagePath + "/photo.jpg";
+
+const uri = await FileSystem.getUri(imageFile);
+
+const img = document.createElement("img");
+img.src = uri;
+img.onload = () => {
+  URL.revokeObjectURL(uri); // 메모리 해제
+};
+
+// Android 환경: FileProvider URI를 다른 앱과 공유
+const documentPath = await FileSystem.getStoragePath("externalFiles");
+const documentFile = documentPath + "/report.pdf";
+const contentUri = await FileSystem.getUri(documentFile);
+
+// contentUri를 Intent의 data로 사용하여 다른 앱 실행
+const intent = new Intent(Intent.ACTION_VIEW);
+intent.setDataAndType(Uri.parse(contentUri), "application/pdf");
+startActivity(intent);
+```
+
+## `StorageType`
+
+저장소 유형을 나타내는 union type입니다.
+
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```
+
+**사용 가이드**:
+- **내부 저장소 (앱 전용)**:
+  - `appData`: 앱 상태 데이터 (자동 백업 대상)
+  - `appFiles`: 일반 파일 저장
+  - `appCache`: 임시 캐시 (시스템이 필요 시 삭제 가능)
+- **외부 저장소 (공유 또는 앱 전용)**:
+  - `external`: 전체 외부 저장소 (권한 필요)
+  - `externalFiles`: 앱 전용 외부 파일 (권한 필요)
+  - `externalCache`: 앱 전용 외부 캐시 (권한 필요)
+  - `externalMedia`: 앱 전용 외부 미디어 (권한 필요)

package/docs/types.md

@@ -0,0 +1,83 @@
+# Types
+
+## `FileInfo`
+
+파일 또는 디렉토리의 정보를 나타내는 인터페이스입니다.
+
+```typescript
+interface FileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | 파일 또는 디렉토리의 이름 (경로 제외, 확장자 포함) |
+| `isDirectory` | boolean | true일 경우 디렉토리, false일 경우 파일 |
+
+```typescript
+// 디렉토리 읽기 결과
+const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+
+// FileInfo 배열 처리
+for (const file of files) {
+  if (file.isDirectory) {
+    console.log(`📁 ${file.name} (directory)`);
+  } else {
+    console.log(`📄 ${file.name} (file)`);
+  }
+}
+```
+
+## `FileSystemPlugin`
+
+Capacitor 플러그인 인터페이스입니다. 일반적으로 `FileSystem` 파사드를 통해 간접적으로 사용됩니다.
+
+```typescript
+interface FileSystemPlugin {
+  checkPermissions(): Promise<{ granted: boolean }>;
+  requestPermissions(): Promise<void>;
+  readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
+  getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
+  getUri(options: { path: string }): Promise<{ uri: string }>;
+  writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
+  readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
+  remove(options: { path: string }): Promise<void>;
+  mkdir(options: { path: string }): Promise<void>;
+  exists(options: { path: string }): Promise<{ exists: boolean }>;
+}
+```
+
+**참고**: 이 인터페이스는 내부 플러그인 구현용이며, 외부 사용자는 `FileSystem` 파사드의 정적 메서드를 사용합니다.
+
+## `Bytes`
+
+이 패키지에서는 `@simplysm/core-common`의 `Bytes` 타입(Uint8Array의 별칭)을 사용합니다.
+
+```typescript
+import type { Bytes } from "@simplysm/core-common";
+import { bytes } from "@simplysm/core-common";
+
+// Bytes = Uint8Array
+const data: Bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+
+// Base64 변환 유틸리티
+const base64Str = bytes.toBase64(data);      // Bytes → Base64 문자열
+const bytesData = bytes.fromBase64(base64Str); // Base64 문자열 → Bytes
+```
+
+## `StorageType`
+
+저장소 유형 union type입니다. 자세한 설명은 [storage-paths.md](./storage-paths.md)를 참조하세요.
+
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "14.0.46",
+  "version": "14.0.48",
   "description": "심플리즘 패키지 - Capacitor 파일 시스템 플러그인",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -15,14 +15,15 @@
   "files": [
     "dist",
     "src",
-    "android"
+    "android",
+    "docs"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "14.0.46",
-    "@simplysm/core-common": "14.0.46"
+    "@simplysm/core-browser": "14.0.48",
+    "@simplysm/core-common": "14.0.48"
   },
   "devDependencies": {
-    "@capacitor/core": "^7.6.1"
+    "@capacitor/core": "^7.6.2"
   },
   "peerDependencies": {
     "@capacitor/core": "^7"