@simplysm/capacitor-plugin-file-system 13.0.85 → 13.0.87

package/README.md

@@ -1,200 +1,172 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor plugin for file system access across Android and web platforms.
+Capacitor 파일시스템 플러그인. Android 네이티브 파일시스템 접근과 Web IndexedDB 기반 가상 파일시스템을 제공한다.
 
-- **Android 11+**: Full file system access via `MANAGE_EXTERNAL_STORAGE` permission
-- **Android 10 and below**: `READ_EXTERNAL_STORAGE` / `WRITE_EXTERNAL_STORAGE` permissions
-- **Browser**: IndexedDB-based virtual file system emulation
-
-## Installation
+## 설치
 
 ```bash
 npm install @simplysm/capacitor-plugin-file-system
 ```
 
-### Peer Dependencies
-
-- `@capacitor/core` ^7.4.4
-
-## API
+**의존성:** `@simplysm/core-common` (Bytes, bytes 유틸), `@simplysm/core-browser` (IndexedDbStore, IndexedDbVirtualFs)
+**Peer:** `@capacitor/core` ^7.4.4
 
-### `FileSystem`
-
-Abstract static class providing all file system operations.
+## Export 목록
 
 ```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+// index.ts
+export { FileSystem } from "./FileSystem";
+export type { FileSystemPlugin, FileInfo, StorageType } from "./FileSystemPlugin";
 ```
 
-#### `FileSystem.checkPermissions()`
-
-Check whether file system permissions are granted.
-
-```typescript
-static async checkPermissions(): Promise<boolean>
-```
-
-**Returns**: `true` if permissions are granted, `false` otherwise. On the web platform, always returns `true`.
-
-#### `FileSystem.requestPermissions()`
+## 주요 사용법
 
-Request file system permissions from the user.
+### 권한 관리
 
 ```typescript
-static async requestPermissions(): Promise<void>
-```
-
-- Android 11+: Navigates to the system settings page for the user to grant access.
-- Android 10 and below: Shows the standard permission dialog.
-
-#### `FileSystem.readdir(dirPath)`
-
-Read the contents of a directory.
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-```typescript
-static async readdir(dirPath: string): Promise<FileInfo[]>
+const granted = await FileSystem.checkPermissions(); // boolean
+if (!granted) {
+  await FileSystem.requestPermissions();
+  // Android 11+: MANAGE_EXTERNAL_STORAGE 설정 화면 이동
+  // Android 10-: READ/WRITE_EXTERNAL_STORAGE 권한 다이얼로그
+}
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `dirPath` | `string` | Absolute path to the directory |
-
-**Returns**: Array of `FileInfo` objects.
-
-#### `FileSystem.getStoragePath(type)`
-
-Get the absolute path for a specific storage location.
+### 파일 읽기/쓰기
 
 ```typescript
-static async getStoragePath(type: StorageType): Promise<string>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | `StorageType` | The storage location type |
+import type { Bytes } from "@simplysm/core-common";
 
-**Returns**: Absolute path string for the requested storage location.
+// 텍스트 파일 쓰기
+await FileSystem.writeFile("/storage/emulated/0/test.txt", "Hello World");
 
-#### `FileSystem.getUri(filePath)`
+// 바이너리 파일 쓰기 (Bytes = Uint8Array)
+const data: Bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+await FileSystem.writeFile("/storage/emulated/0/data.bin", data);
 
-Get a content URI for a file (via Android FileProvider). On the web platform, returns a Blob URL that must be released with `URL.revokeObjectURL()` after use.
+// 텍스트 읽기
+const text: string = await FileSystem.readFile("/path/to/file.txt", "utf8");
 
-```typescript
-static async getUri(filePath: string): Promise<string>
+// 바이너리 읽기 (기본값, Bytes 반환)
+const bytes: Bytes = await FileSystem.readFile("/path/to/file.bin");
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | `string` | Absolute path to the file |
+`writeFile`은 내부적으로 string이면 utf8, Bytes이면 base64로 인코딩하여 네이티브에 전달한다.
 
-**Returns**: URI string.
-
-#### `FileSystem.writeFile(filePath, data)`
-
-Write data to a file. Parent directories are created automatically.
+### 디렉토리 조작
 
 ```typescript
-static async writeFile(filePath: string, data: string | Bytes): Promise<void>
-```
+// 디렉토리 생성 (재귀)
+await FileSystem.mkdir("/storage/emulated/0/myapp/data");
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | `string` | Absolute path to the file |
-| `data` | `string \| Bytes` | Content to write. Strings are written as UTF-8; `Bytes` (`Uint8Array`) is encoded as base64 for transfer. |
+// 디렉토리 목록 조회
+const files = await FileSystem.readdir("/storage/emulated/0/myapp");
+// FileInfo[] = [{ name: "data", isDirectory: true }, { name: "config.json", isDirectory: false }]
 
-#### `FileSystem.readFile(filePath, encoding?)`
+// 파일/디렉토리 삭제 (재귀)
+await FileSystem.remove("/storage/emulated/0/myapp/temp");
 
-Read a file. Returns binary data by default, or a UTF-8 string when the encoding parameter is provided.
-
-```typescript
-static async readFile(filePath: string): Promise<Bytes>
-static async readFile(filePath: string, encoding: "utf8"): Promise<string>
+// 존재 여부 확인
+const exists = await FileSystem.exists("/storage/emulated/0/myapp"); // boolean
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filePath` | `string` | Absolute path to the file |
-| `encoding` | `"utf8"` (optional) | If provided, returns a UTF-8 decoded string |
-
-**Returns**: `Bytes` (binary) or `string` depending on the encoding parameter.
-
-#### `FileSystem.remove(targetPath)`
-
-Delete a file or directory. Directories are removed recursively.
+### 스토리지 경로 조회
 
 ```typescript
-static async remove(targetPath: string): Promise<void>
+const path = await FileSystem.getStoragePath("external"); // string
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | `string` | Absolute path to the file or directory |
+| 타입 | Android 경로 | 설명 |
+|------|-------------|------|
+| `"external"` | `Environment.getExternalStorageDirectory()` | 외부 스토리지 루트 |
+| `"externalFiles"` | `getExternalFilesDir(null)` | 앱 전용 외부 파일 |
+| `"externalCache"` | `getExternalCacheDir()` | 앱 전용 외부 캐시 |
+| `"externalMedia"` | `getExternalMediaDirs()[0]` | 앱 전용 미디어 |
+| `"appData"` | `getApplicationInfo().dataDir` | 앱 데이터 디렉토리 |
+| `"appFiles"` | `getFilesDir()` | 앱 파일 디렉토리 |
+| `"appCache"` | `getCacheDir()` | 앱 캐시 디렉토리 |
 
-#### `FileSystem.mkdir(targetPath)`
+Web 환경에서는 `/webfs/{type}` 가상 경로를 반환한다.
 
-Create a directory. Missing parent directories are created recursively.
+### FileProvider URI
 
-```typescript
-static async mkdir(targetPath: string): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | `string` | Absolute path to the directory |
-
-#### `FileSystem.exists(targetPath)`
-
-Check whether a file or directory exists.
+파일의 `content://` URI를 얻는다. APK 설치 등 인텐트에 파일을 전달할 때 사용한다.
 
 ```typescript
-static async exists(targetPath: string): Promise<boolean>
+const uri = await FileSystem.getUri("/path/to/file.apk");
+// content://{applicationId}.filesystem.provider/...
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetPath` | `string` | Absolute path to check |
+## API 레퍼런스
 
-**Returns**: `true` if the path exists, `false` otherwise.
+### `FileSystem` (abstract class, static 메서드)
 
-## Types
+| 메서드 | 시그니처 | 설명 |
+|--------|----------|------|
+| `checkPermissions` | `() => Promise<boolean>` | 파일시스템 권한 확인 |
+| `requestPermissions` | `() => Promise<void>` | 권한 요청 |
+| `readdir` | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 목록 |
+| `getStoragePath` | `(type: StorageType) => Promise<string>` | 스토리지 경로 조회 |
+| `getUri` | `(filePath: string) => Promise<string>` | FileProvider URI |
+| `writeFile` | `(filePath: string, data: string \| Bytes) => Promise<void>` | 파일 쓰기 |
+| `readFile` | `(filePath: string) => Promise<Bytes>` | 바이너리 읽기 |
+| `readFile` | `(filePath: string, encoding: "utf8") => Promise<string>` | 텍스트 읽기 |
+| `remove` | `(targetPath: string) => Promise<void>` | 재귀 삭제 |
+| `mkdir` | `(targetPath: string) => Promise<void>` | 재귀 생성 |
+| `exists` | `(targetPath: string) => Promise<boolean>` | 존재 여부 확인 |
 
-### `StorageType`
+### `StorageType` (type alias)
 
 ```typescript
 type StorageType =
-  | "external"        // External storage root (Environment.getExternalStorageDirectory)
-  | "externalFiles"   // App-specific external files directory
-  | "externalCache"   // App-specific external cache directory
-  | "externalMedia"   // App-specific external media directory
-  | "appData"         // App data directory
-  | "appFiles"        // App files directory
-  | "appCache";       // App cache directory
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
 ```
 
-### `FileInfo`
+### `FileInfo` (interface)
 
 ```typescript
 interface FileInfo {
-  name: string;        // File or directory name
-  isDirectory: boolean; // true if the entry is a directory
+  name: string;        // 파일/디렉토리 이름
+  isDirectory: boolean;
 }
 ```
 
-### `FileSystemPlugin`
-
-Low-level Capacitor plugin interface. Use the `FileSystem` class instead for a simpler API.
-
-```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 }>;
-}
-```
+## 플랫폼 지원
+
+| 기능 | Android | Web |
+|------|---------|-----|
+| 파일 읽기/쓰기 | 네이티브 파일시스템 (base64/utf8) | IndexedDB 가상 파일시스템 |
+| 디렉토리 | `java.io.File` API | IndexedDB 기반 가상 경로 |
+| 스토리지 경로 | Android 스토리지 API | `/webfs/{type}` 가상 경로 |
+| FileProvider | `content://` URI 생성 | Blob URL (`URL.createObjectURL`) |
+| 권한 | MANAGE_EXTERNAL_STORAGE / READ+WRITE | 항상 granted |
+
+## Android 네이티브 구현
+
+- **패키지:** `kr.co.simplysm.capacitor.filesystem`
+- **플러그인명:** `FileSystem`
+- **FileProvider authority:** `${applicationId}.filesystem.provider`
+- **FileProvider paths:** external, external_files, external_cache, files, cache (모두 root `.`)
+- **AndroidManifest 권한:**
+  - `READ_EXTERNAL_STORAGE` (maxSdkVersion=32)
+  - `WRITE_EXTERNAL_STORAGE` (maxSdkVersion=29)
+  - `MANAGE_EXTERNAL_STORAGE`
+- `writeFile`: 부모 디렉토리 자동 생성 (`mkdirs`), BufferedOutputStream 사용
+- `readFile`: BufferedInputStream + ByteArrayOutputStream (8KB 버퍼)
+
+## Web 구현 상세
+
+`FileSystemWeb`은 `VirtualFileSystem` 클래스를 사용하며, 내부적으로 `IndexedDbStore`와 `IndexedDbVirtualFs`(`@simplysm/core-browser`)를 활용한다.
+
+- **IndexedDB 이름:** `capacitor_web_virtual_fs`
+- **스토어:** `entries` (keyPath: `path`)
+- `getUri`: Blob URL 반환. 사용 후 `URL.revokeObjectURL(uri)` 호출 필요 (메모리 누수 방지)
+- 암묵적 디렉토리 처리: 파일 경로만 저장되어 있어도 중간 경로를 디렉토리로 인식

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "13.0.85",
+  "version": "13.0.87",
   "description": "Simplysm Package - Capacitor File System Plugin",
   "author": "simplysm",
   "license": "MIT",
@@ -18,8 +18,8 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-common": "13.0.85",
-    "@simplysm/core-browser": "13.0.85"
+    "@simplysm/core-browser": "13.0.87",
+    "@simplysm/core-common": "13.0.87"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.0"