@simplysm/capacitor-plugin-file-system 12.16.31 → 12.16.36

package/README.md

@@ -1,213 +1,30 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor plugin for file system access on Android and web.
-
-- **Android 11+**: Uses `MANAGE_EXTERNAL_STORAGE` permission for full file system access
-- **Android 10 and below**: Uses `READ/WRITE_EXTERNAL_STORAGE` permissions
-- **Web (browser)**: IndexedDB-based virtual file system emulation
+Capacitor File System Plugin -- Full file system access with Android permission management. Supports reading/writing files, directory operations, storage path retrieval, and FileProvider URI generation. Uses `MANAGE_EXTERNAL_STORAGE` on Android 11+ and `READ/WRITE_EXTERNAL_STORAGE` on earlier versions. Falls back to IndexedDB on browser.
 
 ## Installation
 
 ```bash
 npm install @simplysm/capacitor-plugin-file-system
-# or
-yarn add @simplysm/capacitor-plugin-file-system
-```
-
-**Peer dependency**: `@capacitor/core` ^7.4.4
-
-### Android Setup
-
-Register the plugin in your app's `MainActivity`:
-
-```java
-import kr.co.simplysm.capacitor.filesystem.FileSystemPlugin;
-
-public class MainActivity extends BridgeActivity {
-  @Override
-  protected void init(Bundle savedInstanceState) {
-    super.init(savedInstanceState);
-    registerPlugin(FileSystemPlugin.class);
-  }
-}
-```
-
-The plugin's `AndroidManifest.xml` automatically merges the required permissions and `FileProvider` configuration.
-
-## API
-
-All methods are static on the `FileSystem` class. Each returns a `Promise`.
-
-### `FileSystem.checkPermissionAsync()`
-
-Checks whether file system permissions are granted.
-
-```ts
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-const granted = await FileSystem.checkPermissionAsync();
-// granted: boolean
-```
-
-### `FileSystem.requestPermissionAsync()`
-
-Requests file system permissions from the user.
-
-- **Android 11+**: Opens the system settings screen for all-files access
-- **Android 10 and below**: Shows the standard permission dialog
-
-```ts
-await FileSystem.requestPermissionAsync();
-```
-
-### `FileSystem.readdirAsync(dirPath)`
-
-Lists files and directories in the given directory.
-
-| Parameter | Type     | Description              |
-|-----------|----------|--------------------------|
-| `dirPath` | `string` | Absolute path to the directory |
-
-**Returns**: `IFileInfo[]`
-
-```ts
-const files = await FileSystem.readdirAsync("/storage/emulated/0/Documents");
-// files: Array<{ name: string; isDirectory: boolean }>
-```
-
-### `FileSystem.getStoragePathAsync(type)`
-
-Returns the absolute path for a storage location.
-
-| Parameter | Type       | Description    |
-|-----------|------------|----------------|
-| `type`    | `TStorage` | Storage type   |
-
-**`TStorage` values**:
-
-| Value            | Description                                              |
-|------------------|----------------------------------------------------------|
-| `"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                                      |
-
-**Returns**: `string` (absolute path)
-
-```ts
-const extPath = await FileSystem.getStoragePathAsync("external");
-// e.g. "/storage/emulated/0"
-```
-
-### `FileSystem.getFileUriAsync(filePath)`
-
-Returns a content URI for the file via `FileProvider` (Android) or a blob URL (web).
-
-| Parameter  | Type     | Description             |
-|------------|----------|-------------------------|
-| `filePath` | `string` | Absolute path to the file |
-
-**Returns**: `string` (URI)
-
-```ts
-const uri = await FileSystem.getFileUriAsync("/storage/emulated/0/Documents/report.pdf");
-```
-
-### `FileSystem.writeFileAsync(filePath, data)`
-
-Writes data to a file. Creates parent directories automatically.
-
-| Parameter  | Type               | Description                         |
-|------------|--------------------|-------------------------------------|
-| `filePath` | `string`           | Absolute path to the file           |
-| `data`     | `string \| Buffer` | Content to write (UTF-8 string or Buffer) |
-
-When `data` is a `Buffer`, it is encoded as base64 for transfer. When `data` is a `string`, it is written as UTF-8.
-
-```ts
-// Write text
-await FileSystem.writeFileAsync("/path/to/file.txt", "Hello, world!");
-
-// Write binary
-const buf = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-await FileSystem.writeFileAsync("/path/to/file.bin", buf);
-```
-
-### `FileSystem.readFileStringAsync(filePath)`
-
-Reads a file as a UTF-8 string.
-
-| Parameter  | Type     | Description             |
-|------------|----------|-------------------------|
-| `filePath` | `string` | Absolute path to the file |
-
-**Returns**: `string`
-
-```ts
-const content = await FileSystem.readFileStringAsync("/path/to/file.txt");
-```
-
-### `FileSystem.readFileBufferAsync(filePath)`
-
-Reads a file as a `Buffer`.
-
-| Parameter  | Type     | Description             |
-|------------|----------|-------------------------|
-| `filePath` | `string` | Absolute path to the file |
-
-**Returns**: `Buffer`
-
-```ts
-const buf = await FileSystem.readFileBufferAsync("/path/to/file.bin");
-```
-
-### `FileSystem.removeAsync(targetPath)`
-
-Deletes a file or directory recursively.
-
-| Parameter    | Type     | Description                      |
-|--------------|----------|----------------------------------|
-| `targetPath` | `string` | Absolute path to file or directory |
-
-```ts
-await FileSystem.removeAsync("/path/to/dir");
-```
-
-### `FileSystem.mkdirsAsync(targetPath)`
-
-Creates a directory and all parent directories recursively.
-
-| Parameter    | Type     | Description                  |
-|--------------|----------|------------------------------|
-| `targetPath` | `string` | Absolute path to the directory |
-
-```ts
-await FileSystem.mkdirsAsync("/path/to/new/dir");
 ```
 
-### `FileSystem.existsAsync(targetPath)`
+## API Overview
 
-Checks whether a file or directory exists.
+| API | Type | Description |
+|-----|------|-------------|
+| `FileSystem` | Abstract class | Static methods for file system operations with permission management |
+| `TStorage` | Type alias | Union type of storage location identifiers |
+| `IFileInfo` | Interface | File/directory entry information |
+| `IFileSystemPlugin` | Interface | Low-level Capacitor plugin interface for file system operations |
 
-| Parameter    | Type     | Description                      |
-|--------------|----------|----------------------------------|
-| `targetPath` | `string` | Absolute path to file or directory |
-
-**Returns**: `boolean`
-
-```ts
-const exists = await FileSystem.existsAsync("/path/to/file.txt");
-```
-
-## Types
+## API Reference
 
 ### `TStorage`
 
-```ts
-type TStorage =
+Union type representing available storage locations.
+
+```typescript
+export type TStorage =
   | "external"
   | "externalFiles"
   | "externalCache"
@@ -217,21 +34,38 @@ type TStorage =
   | "appCache";
 ```
 
+| Value | Description |
+|-------|-------------|
+| `"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 |
+
 ### `IFileInfo`
 
-```ts
-interface IFileInfo {
+File or directory entry information returned by directory listing.
+
+```typescript
+export interface IFileInfo {
   name: string;
   isDirectory: boolean;
 }
 ```
 
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Name of the file or directory |
+| `isDirectory` | `boolean` | `true` if the entry is a directory, `false` if a file |
+
 ### `IFileSystemPlugin`
 
-Low-level plugin interface registered with Capacitor. Use the `FileSystem` static class instead for a simpler API.
+Low-level Capacitor plugin interface. Use `FileSystem` instead for a simplified API.
 
-```ts
-interface IFileSystemPlugin {
+```typescript
+export interface IFileSystemPlugin {
   checkPermission(): Promise<{ granted: boolean }>;
   requestPermission(): Promise<void>;
   readdir(options: { path: string }): Promise<{ files: IFileInfo[] }>;
@@ -244,3 +78,97 @@ interface IFileSystemPlugin {
   exists(options: { path: string }): Promise<{ exists: boolean }>;
 }
 ```
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `checkPermission` | -- | `Promise<{ granted: boolean }>` | Check file system permission |
+| `requestPermission` | -- | `Promise<void>` | Request file system permission |
+| `readdir` | `options: { path }` | `Promise<{ files: IFileInfo[] }>` | List directory contents |
+| `getStoragePath` | `options: { type: TStorage }` | `Promise<{ path: string }>` | Get absolute path for a storage type |
+| `getFileUri` | `options: { path }` | `Promise<{ uri: string }>` | Get FileProvider content:// URI |
+| `writeFile` | `options: { path, data, encoding? }` | `Promise<void>` | Write file with utf8 or base64 encoding |
+| `readFile` | `options: { path, encoding? }` | `Promise<{ data: string }>` | Read file as utf8 or base64 string |
+| `remove` | `options: { path }` | `Promise<void>` | Remove file or directory recursively |
+| `mkdir` | `options: { path }` | `Promise<void>` | Create directory recursively |
+| `exists` | `options: { path }` | `Promise<{ exists: boolean }>` | Check if file or directory exists |
+
+### `FileSystem`
+
+Abstract class with static methods for full file system access.
+
+- **Android 11+**: `MANAGE_EXTERNAL_STORAGE` permission for full file system access
+- **Android 10-**: `READ/WRITE_EXTERNAL_STORAGE` permissions
+- **Browser**: IndexedDB-based emulation
+
+```typescript
+export abstract class FileSystem {
+  static async checkPermissionAsync(): Promise<boolean>;
+  static async requestPermissionAsync(): Promise<void>;
+  static async readdirAsync(dirPath: string): Promise<IFileInfo[]>;
+  static async getStoragePathAsync(type: TStorage): Promise<string>;
+  static async getFileUriAsync(filePath: string): Promise<string>;
+  static async writeFileAsync(filePath: string, data: string | Buffer): Promise<void>;
+  static async readFileStringAsync(filePath: string): Promise<string>;
+  static async readFileBufferAsync(filePath: string): Promise<Buffer>;
+  static async removeAsync(targetPath: string): Promise<void>;
+  static async mkdirsAsync(targetPath: string): Promise<void>;
+  static async existsAsync(targetPath: string): Promise<boolean>;
+}
+```
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `checkPermissionAsync` | -- | `Promise<boolean>` | Check if file system permission is granted |
+| `requestPermissionAsync` | -- | `Promise<void>` | Request file system permission (Android 11+: opens settings; Android 10-: shows dialog) |
+| `readdirAsync` | `dirPath: string` | `Promise<IFileInfo[]>` | List files and directories in a directory |
+| `getStoragePathAsync` | `type: TStorage` | `Promise<string>` | Get the absolute path for the specified storage type |
+| `getFileUriAsync` | `filePath: string` | `Promise<string>` | Get a FileProvider `content://` URI for a file path |
+| `writeFileAsync` | `filePath: string, data: string \| Buffer` | `Promise<void>` | Write a file; `Buffer` data is base64-encoded, `string` is written as UTF-8 |
+| `readFileStringAsync` | `filePath: string` | `Promise<string>` | Read a file as a UTF-8 string |
+| `readFileBufferAsync` | `filePath: string` | `Promise<Buffer>` | Read a file as a Buffer |
+| `removeAsync` | `targetPath: string` | `Promise<void>` | Delete a file or directory recursively |
+| `mkdirsAsync` | `targetPath: string` | `Promise<void>` | Create a directory and all parent directories |
+| `existsAsync` | `targetPath: string` | `Promise<boolean>` | Check whether a file or directory exists |
+
+## Usage Examples
+
+### Read and write files with permission handling
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+// Ensure permission is granted
+const hasPermission = await FileSystem.checkPermissionAsync();
+if (!hasPermission) {
+  await FileSystem.requestPermissionAsync();
+}
+
+// Get app cache directory
+const cachePath = await FileSystem.getStoragePathAsync("appCache");
+
+// Write a text file
+await FileSystem.writeFileAsync(`${cachePath}/config.json`, '{"key": "value"}');
+
+// Read it back
+const content = await FileSystem.readFileStringAsync(`${cachePath}/config.json`);
+
+// Write binary data
+const buffer = Buffer.from([0x00, 0x01, 0x02]);
+await FileSystem.writeFileAsync(`${cachePath}/data.bin`, buffer);
+
+// Read binary data
+const data = await FileSystem.readFileBufferAsync(`${cachePath}/data.bin`);
+```
+
+### List directory contents
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const externalPath = await FileSystem.getStoragePathAsync("external");
+const files = await FileSystem.readdirAsync(`${externalPath}/Documents`);
+
+for (const file of files) {
+  console.log(`${file.name} (${file.isDirectory ? "directory" : "file"})`);
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "12.16.31",
+  "version": "12.16.36",
   "description": "심플리즘 패키지 - Capacitor File System Plugin",
   "author": "김석래",
   "repository": {
@@ -21,6 +21,6 @@
     "@capacitor/core": "^7.4.4"
   },
   "devDependencies": {
-    "@capacitor/core": "^7.5.0"
+    "@capacitor/core": "^7.6.0"
   }
 }