@simplysm/capacitor-plugin-file-system 14.0.4 → 14.0.5

package/README.md

@@ -1,6 +1,10 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor file system plugin with full storage access on Android 11+.
+Capacitor plugin for file system access on Android with an IndexedDB-based fallback for browsers.
+
+- **Android 11+**: Full file system access via `MANAGE_EXTERNAL_STORAGE` permission
+- **Android 10-**: `READ/WRITE_EXTERNAL_STORAGE` permissions
+- **Browser**: IndexedDB-based emulation
 
 ## Installation
 
@@ -10,26 +14,43 @@ npm install @simplysm/capacitor-plugin-file-system
 
 ## API Overview
 
-### File System
+### Types
 
 | API | Type | Description |
 |-----|------|-------------|
 | `StorageType` | Type | Union of supported Android storage location identifiers |
+
+### Interfaces
+
+| API | Type | Description |
+|-----|------|-------------|
 | `FileInfo` | Interface | File entry metadata returned by directory listing |
 | `FileSystemPlugin` | Interface | Native plugin interface for file system operations |
+
+### Classes
+
+| API | Type | Description |
+|-----|------|-------------|
 | `FileSystem` | Class | Static API for file system access with permission management |
 
-## Types
+## `StorageType`
 
-### StorageType
+Union type representing available storage location types.
 
-```ts
-type StorageType = "external" | "externalFiles" | "externalCache" | "externalMedia" | "appData" | "appFiles" | "appCache";
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
 ```
 
 | Value | Description |
 |-------|-------------|
-| `"external"` | Shared external storage root |
+| `"external"` | Shared external storage root (`Environment.getExternalStorageDirectory`) |
 | `"externalFiles"` | App-specific external files directory |
 | `"externalCache"` | App-specific external cache directory |
 | `"externalMedia"` | App-specific external media directory |
@@ -37,20 +58,40 @@ type StorageType = "external" | "externalFiles" | "externalCache" | "externalMed
 | `"appFiles"` | Internal app files directory |
 | `"appCache"` | Internal app cache directory |
 
-## Interfaces
-
-### FileInfo
+## `FileInfo`
 
 Metadata for a single file or directory entry.
 
+```typescript
+interface FileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `name` | `string` | Name of the file or directory |
 | `isDirectory` | `boolean` | `true` if the entry is a directory |
 
-### FileSystemPlugin
-
-Native plugin interface for file system operations.
+## `FileSystemPlugin`
+
+Native plugin interface for file system operations. Use the `FileSystem` class for a simplified 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 }>;
+}
+```
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
@@ -58,28 +99,40 @@ Native plugin interface for file system operations.
 | `requestPermissions` | `() => Promise<void>` | Request storage permissions |
 | `readdir` | `(options: { path: string }) => Promise<{ files: FileInfo[] }>` | List files in a directory |
 | `getStoragePath` | `(options: { type: StorageType }) => Promise<{ path: string }>` | Get the absolute path for a storage type |
-| `getUri` | `(options: { path: string }) => Promise<{ uri: string }>` | Get a FileProvider content URI for a file path |
+| `getUri` | `(options: { path: string }) => Promise<{ uri: string }>` | Get a FileProvider `content://` URI for a file path |
 | `writeFile` | `(options: { path: string; data: string; encoding?: "utf8" \| "base64" }) => Promise<void>` | Write data to a file |
 | `readFile` | `(options: { path: string; encoding?: "utf8" \| "base64" }) => Promise<{ data: string }>` | Read data from a file |
 | `remove` | `(options: { path: string }) => Promise<void>` | Remove a file or directory |
 | `mkdir` | `(options: { path: string }) => Promise<void>` | Create a directory |
 | `exists` | `(options: { path: string }) => Promise<{ exists: boolean }>` | Check if a path exists |
 
-## Classes
-
-### FileSystem
-
-File system access plugin. On Android 11+ it uses `MANAGE_EXTERNAL_STORAGE`. On Android 10 and below it uses `READ_EXTERNAL_STORAGE` / `WRITE_EXTERNAL_STORAGE`. On the browser it falls back to IndexedDB emulation.
-
-All methods are static.
+## `FileSystem`
+
+Abstract class with static methods for file system operations. On Android 11+ it uses `MANAGE_EXTERNAL_STORAGE`. On Android 10 and below it uses `READ_EXTERNAL_STORAGE` / `WRITE_EXTERNAL_STORAGE`. On the browser it falls back to IndexedDB emulation.
+
+```typescript
+abstract class FileSystem {
+  static async checkPermissions(): Promise<boolean>;
+  static async requestPermissions(): Promise<void>;
+  static async readdir(dirPath: string): Promise<FileInfo[]>;
+  static async getStoragePath(type: StorageType): Promise<string>;
+  static async getUri(filePath: string): Promise<string>;
+  static async writeFile(filePath: string, data: string | Bytes): Promise<void>;
+  static async readFile(filePath: string): Promise<Bytes>;
+  static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
+  static async remove(targetPath: string): Promise<void>;
+  static async mkdir(targetPath: string): Promise<void>;
+  static async exists(targetPath: string): Promise<boolean>;
+}
+```
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | `checkPermissions` | `static async checkPermissions(): Promise<boolean>` | Check whether storage permissions are granted |
 | `requestPermissions` | `static async requestPermissions(): Promise<void>` | Request storage permissions from the user |
 | `readdir` | `static async readdir(dirPath: string): Promise<FileInfo[]>` | List files and directories at the given path |
-| `getStoragePath` | `static async getStoragePath(type: StorageType): Promise<string>` | Get the absolute path for a storage type (`external`, `externalFiles`, `externalCache`, `externalMedia`, `appData`, `appFiles`, `appCache`) |
-| `getUri` | `static async getUri(filePath: string): Promise<string>` | Get a FileProvider content URI for the given file path |
+| `getStoragePath` | `static async getStoragePath(type: StorageType): Promise<string>` | Get the absolute path for a storage type |
+| `getUri` | `static async getUri(filePath: string): Promise<string>` | Get a FileProvider `content://` URI for the given file path |
 | `writeFile` | `static async writeFile(filePath: string, data: string \| Bytes): Promise<void>` | Write string or binary data to a file. Binary data (`Bytes`) is automatically base64-encoded. |
 | `readFile` | `static async readFile(filePath: string): Promise<Bytes>` | Read a file as binary data |
 | `readFile` (overload) | `static async readFile(filePath: string, encoding: "utf8"): Promise<string>` | Read a file as a UTF-8 string |
@@ -91,7 +144,7 @@ All methods are static.
 
 ### Read and write files
 
-```ts
+```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
 // Ensure permissions
@@ -100,34 +153,32 @@ if (!granted) {
   await FileSystem.requestPermissions();
 }
 
-// Get external files directory
-const basePath = await FileSystem.getStoragePath("externalFiles");
+// Get app cache path and write a file
+const cachePath = await FileSystem.getStoragePath("appCache");
+await FileSystem.writeFile(`${cachePath}/data.json`, JSON.stringify({ key: "value" }));
 
-// Write a text file
-await FileSystem.writeFile(`${basePath}/config.json`, '{"key": "value"}');
-
-// Read it back as a string
-const content = await FileSystem.readFile(`${basePath}/config.json`, "utf8");
+// Read the file back as a string
+const content = await FileSystem.readFile(`${cachePath}/data.json`, "utf8");
 ```
 
-### List directory contents
+### List directory contents and check existence
 
-```ts
+```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-const files = await FileSystem.readdir("/storage/emulated/0/Download");
+const externalPath = await FileSystem.getStoragePath("external");
+const files = await FileSystem.readdir(`${externalPath}/Documents`);
+
 for (const file of files) {
-  console.log(`${file.name} (${file.isDirectory ? "dir" : "file"})`);
+  if (file.isDirectory) {
+    // handle directory
+  } else {
+    // handle file
+  }
 }
-```
-
-### Create directories and check existence
-
-```ts
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-const dirPath = "/storage/emulated/0/MyApp/data/logs";
 
+// Create a directory if it does not exist
+const dirPath = `${externalPath}/MyApp/data/logs`;
 if (!(await FileSystem.exists(dirPath))) {
   await FileSystem.mkdir(dirPath);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "14.0.4",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - Capacitor 파일 시스템 플러그인",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -18,8 +18,8 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "14.0.4",
-    "@simplysm/core-common": "14.0.4"
+    "@simplysm/core-browser": "14.0.5",
+    "@simplysm/core-common": "14.0.5"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.1"