@simplysm/capacitor-plugin-file-system 13.0.68 → 13.0.70

package/README.md

@@ -1,241 +1,22 @@
 # @simplysm/capacitor-plugin-file-system
 
-A Capacitor-based file system access plugin. On Android, it provides direct access to the native file system, while in web environments it operates as an IndexedDB-based virtual file system.
+Simplysm Package - Capacitor File System Plugin
 
 ## Installation
 
-```bash
-npm install @simplysm/capacitor-plugin-file-system
-npx cap sync
-```
+pnpm add @simplysm/capacitor-plugin-file-system
 
-## Supported Platforms
+**Peer Dependencies:** `@capacitor/core ^7.4.4`
 
-| Platform | Supported | Implementation |
-|--------|----------|----------|
-| Android | Yes | Native Java (API 23+) |
-| Web | Yes | IndexedDB-based virtual file system |
-| iOS | No | - |
+## Source Index
 
-### Android Permissions
+### File System
 
-Different permission models are used depending on the Android version.
-
-| Android Version | Permission | Behavior |
-|-------------|------|------|
-| Android 11+ (API 30+) | `MANAGE_EXTERNAL_STORAGE` | Navigate to settings screen to grant full file access permission |
-| Android 10 and below | `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE` | Display runtime permission dialog |
-
-The plugin automatically declares the necessary permissions in `AndroidManifest.xml`, so you don't need to add them separately in your app's manifest.
-
-## Main Modules
-
-All APIs are provided as static methods of the `FileSystem` class.
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-```
-
-### Method List
-
-| Method | Return Type | Description |
-|--------|----------|------|
-| `hasPermission()` | `Promise<boolean>` | Check if file system access permission is granted |
-| `requestPermission()` | `Promise<void>` | Request file system access permission |
-| `readdir(dirPath)` | `Promise<IFileInfo[]>` | List files/folders in directory |
-| `getStoragePath(type)` | `Promise<string>` | Return absolute path by storage type |
-| `getFileUri(filePath)` | `Promise<string>` | Return FileProvider URI (Android) / Blob URL (Web) |
-| `writeFile(filePath, data)` | `Promise<void>` | Write file (string or binary) |
-| `readFileString(filePath)` | `Promise<string>` | Read file as UTF-8 string |
-| `readFileBytes(filePath)` | `Promise<Bytes>` | Read file as binary (`Uint8Array`) |
-| `remove(targetPath)` | `Promise<void>` | Recursively delete file or directory |
-| `mkdir(targetPath)` | `Promise<void>` | Recursively create directory |
-| `exists(targetPath)` | `Promise<boolean>` | Check if file or directory exists |
-
-### Type Definitions
-
-```typescript
-import type { TStorage, IFileInfo } from "@simplysm/capacitor-plugin-file-system";
-```
-
-#### `TStorage`
-
-A string literal type representing storage types.
-
-| Value | Android Path | Description |
-|----|-------------|------|
-| `"external"` | `Environment.getExternalStorageDirectory()` | External storage root |
-| `"externalFiles"` | `Context.getExternalFilesDir(null)` | App-specific external files directory |
-| `"externalCache"` | `Context.getExternalCacheDir()` | App-specific external cache directory |
-| `"externalMedia"` | `Context.getExternalMediaDirs()[0]` | App-specific external media directory |
-| `"appData"` | `ApplicationInfo.dataDir` | App data directory |
-| `"appFiles"` | `Context.getFilesDir()` | App internal files directory |
-| `"appCache"` | `Context.getCacheDir()` | App internal cache directory |
-
-#### `IFileInfo`
-
-```typescript
-interface IFileInfo {
-  name: string;        // File or directory name
-  isDirectory: boolean; // Whether it's a directory
-}
-```
-
-#### `IFileSystemPlugin`
-
-The low-level Capacitor plugin interface. Not intended for direct use -- use the `FileSystem` static class instead.
-
-```typescript
-import type { IFileSystemPlugin } from "@simplysm/capacitor-plugin-file-system";
-```
-
-## Usage Examples
-
-### Check and Request Permission
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-async function ensurePermission(): Promise<boolean> {
-  const granted = await FileSystem.hasPermission();
-  if (!granted) {
-    await FileSystem.requestPermission();
-    // On Android 11+, it navigates to settings screen,
-    // so you need to check again after returning to the app.
-    return await FileSystem.hasPermission();
-  }
-  return true;
-}
-```
-
-### Read/Write Text Files
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-async function textFileExample(): Promise<void> {
-  const storagePath = await FileSystem.getStoragePath("appFiles");
-  const filePath = storagePath + "/config.json";
-
-  // Write file
-  const config = { theme: "dark", lang: "ko" };
-  await FileSystem.writeFile(filePath, JSON.stringify(config, null, 2));
-
-  // Read file
-  const content = await FileSystem.readFileString(filePath);
-  const parsed = JSON.parse(content);
-  console.log(parsed.theme); // "dark"
-}
-```
-
-### Read/Write Binary Files
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-import type { Bytes } from "@simplysm/core-common";
-
-async function binaryFileExample(): Promise<void> {
-  const storagePath = await FileSystem.getStoragePath("appFiles");
-  const filePath = storagePath + "/data.bin";
-
-  // Write as Uint8Array
-  const bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
-  await FileSystem.writeFile(filePath, bytes);
-
-  // Read as Bytes (Uint8Array alias from @simplysm/core-common)
-  const readBytes: Bytes = await FileSystem.readFileBytes(filePath);
-  console.log(readBytes.length); // 5
-}
-```
-
-### Directory Management
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-async function directoryExample(): Promise<void> {
-  const storagePath = await FileSystem.getStoragePath("appFiles");
-  const dirPath = storagePath + "/logs/2024";
-
-  // Recursively create directory
-  await FileSystem.mkdir(dirPath);
-
-  // Create file
-  await FileSystem.writeFile(dirPath + "/app.log", "Started\n");
-
-  // List directory contents
-  const files = await FileSystem.readdir(dirPath);
-  for (const file of files) {
-    console.log(`${file.name} (directory: ${file.isDirectory})`);
-  }
-
-  // Check existence
-  const dirExists = await FileSystem.exists(dirPath);
-  console.log(dirExists); // true
-
-  // Recursively delete directory
-  await FileSystem.remove(dirPath);
-}
-```
-
-### Get FileProvider URI
-
-On Android, a `content://` URI is needed when sharing files with other apps.
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-async function shareFile(filePath: string): Promise<string> {
-  // Android: returns content:// URI
-  // Web: returns blob: URL (must call URL.revokeObjectURL() after use)
-  const uri = await FileSystem.getFileUri(filePath);
-  return uri;
-}
-```
-
-> **Warning**: In web environments, the Blob URL returned by `getFileUri()` must be released by calling `URL.revokeObjectURL(uri)` after use to free memory.
-
-## Android Configuration
-
-### FileProvider
-
-The plugin includes its own `FileSystemProvider`, and the authority is automatically set in the format `${applicationId}.filesystem.provider`. Shareable paths are:
-
-- External storage (`external-path`)
-- App-specific external files (`external-files-path`)
-- App-specific external cache (`external-cache-path`)
-- App internal files (`files-path`)
-- App internal cache (`cache-path`)
-
-### Minimum SDK Version
-
-- `minSdkVersion`: 23 (Android 6.0)
-- `compileSdkVersion`: 35
-
-## Web Environment Behavior
-
-In web environments, it operates as an IndexedDB-based virtual file system (`VirtualFileSystem`).
-
-- Database name: `capacitor_web_virtual_fs`
-- Permission-related methods (`hasPermission`, `requestPermission`) always succeed.
-- `getStoragePath()` returns virtual paths in the format `/webfs/{type}`.
-- `getFileUri()` returns a Blob URL, which must be released with `URL.revokeObjectURL()` after use.
-- File data is base64-encoded and stored in IndexedDB.
-
-## Dependencies
-
-### Peer Dependencies
-
-| Package | Version |
-|--------|------|
-| `@capacitor/core` | `^7.4.4` |
-
-### Internal Dependencies
-
-| Package | Description |
-|--------|------|
-| `@simplysm/core-common` | Common utilities such as base64 conversion, `Bytes` type |
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/FileSystem.ts` | `FileSystem` | Static class for file read/write, directory, permission, and URI operations | - |
+| `src/IFileSystemPlugin.ts` | `TStorage`, `IFileInfo`, `IFileSystemPlugin` | Types and interface for storage paths, file info, and the native plugin contract | - |
 
 ## License
 
-MIT
+Apache-2.0

package/dist/FileSystem.d.ts

@@ -1,64 +1,64 @@
 import type { IFileInfo, TStorage } from "./IFileSystemPlugin";
 import type { Bytes } from "@simplysm/core-common";
 /**
- * 파일 시스템 접근 플러그인
- * - Android 11+: MANAGE_EXTERNAL_STORAGE 권한으로 전체 파일 시스템 접근
- * - Android 10-: READ/WRITE_EXTERNAL_STORAGE 권한
- * - Browser: IndexedDB 기반 에뮬레이션
+ * File system access plugin
+ * - Android 11+: Full file system access via MANAGE_EXTERNAL_STORAGE permission
+ * - Android 10-: READ/WRITE_EXTERNAL_STORAGE permission
+ * - Browser: IndexedDB-based emulation
  */
 export declare abstract class FileSystem {
     /**
-     * 권한 확인
+     * Check permission
      */
     static hasPermission(): Promise<boolean>;
     /**
-     * 권한 요청
-     * - Android 11+: 설정 화면으로 이동
-     * - Android 10-: 권한 다이얼로그 표시
+     * Request permission
+     * - Android 11+: Navigate to settings
+     * - Android 10-: Show permission dialog
      */
     static requestPermission(): Promise<void>;
     /**
-     * 디렉토리 읽기
+     * Read directory
      */
     static readdir(dirPath: string): Promise<IFileInfo[]>;
     /**
-     * 저장소 경로 얻기
-     * @param type 저장소 타입
-     * - external: 외부 저장소 루트 (Environment.getExternalStorageDirectory)
-     * - externalFiles: 앱 전용 외부 파일 디렉토리
-     * - externalCache: 앱 전용 외부 캐시 디렉토리
-     * - externalMedia: 앱 전용 외부 미디어 디렉토리
-     * - appData: 앱 데이터 디렉토리
-     * - appFiles: 앱 파일 디렉토리
-     * - appCache: 앱 캐시 디렉토리
+     * Get storage path
+     * @param type Storage type
+     * - 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
      */
     static getStoragePath(type: TStorage): Promise<string>;
     /**
-     * 파일 URI 얻기 (FileProvider)
+     * Get file URI (FileProvider)
      */
     static getFileUri(filePath: string): Promise<string>;
     /**
-     * 파일 쓰기
+     * Write file
      */
     static writeFile(filePath: string, data: string | Bytes): Promise<void>;
     /**
-     * 파일 읽기 (UTF-8 문자열)
+     * Read file (UTF-8 string)
      */
     static readFileString(filePath: string): Promise<string>;
     /**
-     * 파일 읽기 (Bytes)
+     * Read file (Bytes)
      */
     static readFileBytes(filePath: string): Promise<Bytes>;
     /**
-     * 파일/디렉토리 삭제 (재귀)
+     * Delete file/directory (recursive)
      */
     static remove(targetPath: string): Promise<void>;
     /**
-     * 디렉토리 생성 (재귀)
+     * Create directory (recursive)
      */
     static mkdir(targetPath: string): Promise<void>;
     /**
-     * 존재 여부 확인
+     * Check existence
      */
     static exists(targetPath: string): Promise<boolean>;
 }

package/dist/FileSystem.js

@@ -8,51 +8,51 @@ const FileSystemPlugin = registerPlugin("FileSystem", {
 });
 class FileSystem {
   /**
-   * 권한 확인
+   * Check permission
    */
   static async hasPermission() {
     const result = await FileSystemPlugin.hasPermission();
     return result.granted;
   }
   /**
-   * 권한 요청
-   * - Android 11+: 설정 화면으로 이동
-   * - Android 10-: 권한 다이얼로그 표시
+   * Request permission
+   * - Android 11+: Navigate to settings
+   * - Android 10-: Show permission dialog
    */
   static async requestPermission() {
     await FileSystemPlugin.requestPermission();
   }
   /**
-   * 디렉토리 읽기
+   * Read directory
    */
   static async readdir(dirPath) {
     const result = await FileSystemPlugin.readdir({ path: dirPath });
     return result.files;
   }
   /**
-   * 저장소 경로 얻기
-   * @param type 저장소 타입
-   * - external: 외부 저장소 루트 (Environment.getExternalStorageDirectory)
-   * - externalFiles: 앱 전용 외부 파일 디렉토리
-   * - externalCache: 앱 전용 외부 캐시 디렉토리
-   * - externalMedia: 앱 전용 외부 미디어 디렉토리
-   * - appData: 앱 데이터 디렉토리
-   * - appFiles: 앱 파일 디렉토리
-   * - appCache: 앱 캐시 디렉토리
+   * Get storage path
+   * @param type Storage type
+   * - 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
    */
   static async getStoragePath(type) {
     const result = await FileSystemPlugin.getStoragePath({ type });
     return result.path;
   }
   /**
-   * 파일 URI 얻기 (FileProvider)
+   * Get file URI (FileProvider)
    */
   static async getFileUri(filePath) {
     const result = await FileSystemPlugin.getFileUri({ path: filePath });
     return result.uri;
   }
   /**
-   * 파일 쓰기
+   * Write file
    */
   static async writeFile(filePath, data) {
     if (typeof data !== "string") {
@@ -70,33 +70,33 @@ class FileSystem {
     }
   }
   /**
-   * 파일 읽기 (UTF-8 문자열)
+   * Read file (UTF-8 string)
    */
   static async readFileString(filePath) {
     const result = await FileSystemPlugin.readFile({ path: filePath, encoding: "utf8" });
     return result.data;
   }
   /**
-   * 파일 읽기 (Bytes)
+   * Read file (Bytes)
    */
   static async readFileBytes(filePath) {
     const result = await FileSystemPlugin.readFile({ path: filePath, encoding: "base64" });
     return bytesFromBase64(result.data);
   }
   /**
-   * 파일/디렉토리 삭제 (재귀)
+   * Delete file/directory (recursive)
    */
   static async remove(targetPath) {
     await FileSystemPlugin.remove({ path: targetPath });
   }
   /**
-   * 디렉토리 생성 (재귀)
+   * Create directory (recursive)
    */
   static async mkdir(targetPath) {
     await FileSystemPlugin.mkdir({ path: targetPath });
   }
   /**
-   * 존재 여부 확인
+   * Check existence
    */
   static async exists(targetPath) {
     const result = await FileSystemPlugin.exists({ path: targetPath });

package/dist/web/FileSystemWeb.d.ts

@@ -19,9 +19,9 @@ export declare class FileSystemWeb extends WebPlugin implements IFileSystemPlugi
         path: string;
     }>;
     /**
-     * 파일의 Blob URL을 반환합니다.
-     * @warning 반환된 URI는 사용 후 반드시 `URL.revokeObjectURL(uri)`를 호출하여 해제해야 합니다.
-     * 해제하지 않으면 메모리 누수가 발생할 수 있습니다.
+     * Return the Blob URL of a file.
+     * @warning The returned URI must be released by calling `URL.revokeObjectURL(uri)` after use.
+     * Failure to release may cause memory leaks.
      */
     getFileUri(options: {
         path: string;

package/dist/web/FileSystemWeb.js

@@ -50,9 +50,9 @@ class FileSystemWeb extends WebPlugin {
     return { path: storagePath };
   }
   /**
-   * 파일의 Blob URL을 반환합니다.
-   * @warning 반환된 URI는 사용 후 반드시 `URL.revokeObjectURL(uri)`를 호출하여 해제해야 합니다.
-   * 해제하지 않으면 메모리 누수가 발생할 수 있습니다.
+   * Return the Blob URL of a file.
+   * @warning The returned URI must be released by calling `URL.revokeObjectURL(uri)` after use.
+   * Failure to release may cause memory leaks.
    */
   async getFileUri(options) {
     const entry = await this._fs.getEntry(options.path);

package/dist/web/VirtualFileSystem.d.ts

@@ -12,12 +12,12 @@ export declare class VirtualFileSystem {
     putEntry(entry: FsEntry): Promise<void>;
     deleteByPrefix(pathPrefix: string): Promise<boolean>;
     /**
-     * 디렉토리의 직접 자식 목록을 반환합니다.
-     * @param dirPath 조회할 디렉토리 경로
-     * @returns 자식 파일/디렉토리 목록
-     * @note 암시적 디렉토리 처리: 파일 경로만 존재하고 디렉토리 엔트리가 없는 경우에도
-     * 중간 경로는 디렉토리로 판정됩니다. 예: "/a/b/c.txt"만 저장된 상태에서
-     * listChildren("/a") 호출 시 "b"는 isDirectory: true로 반환됩니다.
+     * Return the direct children of a directory.
+     * @param dirPath Directory path to query
+     * @returns List of child files/directories
+     * @note Implicit directory handling: Even when only file paths exist without directory entries,
+     * intermediate paths are treated as directories. e.g., With only "/a/b/c.txt" stored,
+     * calling listChildren("/a") returns "b" with isDirectory: true.
      */
     listChildren(dirPath: string): Promise<IFileInfo[]>;
     ensureDir(dirPath: string): Promise<void>;

package/dist/web/VirtualFileSystem.js

@@ -34,12 +34,12 @@ class VirtualFileSystem {
     });
   }
   /**
-   * 디렉토리의 직접 자식 목록을 반환합니다.
-   * @param dirPath 조회할 디렉토리 경로
-   * @returns 자식 파일/디렉토리 목록
-   * @note 암시적 디렉토리 처리: 파일 경로만 존재하고 디렉토리 엔트리가 없는 경우에도
-   * 중간 경로는 디렉토리로 판정됩니다. 예: "/a/b/c.txt"만 저장된 상태에서
-   * listChildren("/a") 호출 시 "b"는 isDirectory: true로 반환됩니다.
+   * Return the direct children of a directory.
+   * @param dirPath Directory path to query
+   * @returns List of child files/directories
+   * @note Implicit directory handling: Even when only file paths exist without directory entries,
+   * intermediate paths are treated as directories. e.g., With only "/a/b/c.txt" stored,
+   * calling listChildren("/a") returns "b" with isDirectory: true.
    */
   async listChildren(dirPath) {
     const prefix = dirPath === "/" ? "/" : dirPath + "/";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/capacitor-plugin-file-system",
-  "version": "13.0.68",
-  "description": "심플리즘 패키지 - Capacitor File System Plugin",
-  "author": "김석래",
+  "version": "13.0.70",
+  "description": "Simplysm Package - Capacitor File System Plugin",
+  "author": "simplysm",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,10 +14,11 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "src",
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-common": "13.0.68"
+    "@simplysm/core-common": "13.0.70"
   },
   "devDependencies": {
     "@capacitor/core": "^7.5.0"

package/src/FileSystem.ts

@@ -0,0 +1,126 @@
+import { registerPlugin } from "@capacitor/core";
+import type { IFileInfo, IFileSystemPlugin, TStorage } from "./IFileSystemPlugin";
+import type { Bytes } from "@simplysm/core-common";
+import { bytesToBase64, bytesFromBase64 } from "@simplysm/core-common";
+
+const FileSystemPlugin = registerPlugin<IFileSystemPlugin>("FileSystem", {
+  web: async () => {
+    const { FileSystemWeb } = await import("./web/FileSystemWeb");
+    return new FileSystemWeb();
+  },
+});
+
+/**
+ * File system access plugin
+ * - Android 11+: Full file system access via MANAGE_EXTERNAL_STORAGE permission
+ * - Android 10-: READ/WRITE_EXTERNAL_STORAGE permission
+ * - Browser: IndexedDB-based emulation
+ */
+export abstract class FileSystem {
+  /**
+   * Check permission
+   */
+  static async hasPermission(): Promise<boolean> {
+    const result = await FileSystemPlugin.hasPermission();
+    return result.granted;
+  }
+
+  /**
+   * Request permission
+   * - Android 11+: Navigate to settings
+   * - Android 10-: Show permission dialog
+   */
+  static async requestPermission(): Promise<void> {
+    await FileSystemPlugin.requestPermission();
+  }
+
+  /**
+   * Read directory
+   */
+  static async readdir(dirPath: string): Promise<IFileInfo[]> {
+    const result = await FileSystemPlugin.readdir({ path: dirPath });
+    return result.files;
+  }
+
+  /**
+   * Get storage path
+   * @param type Storage type
+   * - 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
+   */
+  static async getStoragePath(type: TStorage): Promise<string> {
+    const result = await FileSystemPlugin.getStoragePath({ type });
+    return result.path;
+  }
+
+  /**
+   * Get file URI (FileProvider)
+   */
+  static async getFileUri(filePath: string): Promise<string> {
+    const result = await FileSystemPlugin.getFileUri({ path: filePath });
+    return result.uri;
+  }
+
+  /**
+   * Write file
+   */
+  static async writeFile(filePath: string, data: string | Bytes): Promise<void> {
+    if (typeof data !== "string") {
+      // Bytes (Uint8Array) - works safely in cross-realm environments
+      await FileSystemPlugin.writeFile({
+        path: filePath,
+        data: bytesToBase64(data),
+        encoding: "base64",
+      });
+    } else {
+      await FileSystemPlugin.writeFile({
+        path: filePath,
+        data,
+        encoding: "utf8",
+      });
+    }
+  }
+
+  /**
+   * Read file (UTF-8 string)
+   */
+  static async readFileString(filePath: string): Promise<string> {
+    const result = await FileSystemPlugin.readFile({ path: filePath, encoding: "utf8" });
+    return result.data;
+  }
+
+  /**
+   * Read file (Bytes)
+   */
+  static async readFileBytes(filePath: string): Promise<Bytes> {
+    const result = await FileSystemPlugin.readFile({ path: filePath, encoding: "base64" });
+    return bytesFromBase64(result.data);
+  }
+
+  /**
+   * Delete file/directory (recursive)
+   */
+  static async remove(targetPath: string): Promise<void> {
+    await FileSystemPlugin.remove({ path: targetPath });
+  }
+
+  /**
+   * Create directory (recursive)
+   */
+  static async mkdir(targetPath: string): Promise<void> {
+    await FileSystemPlugin.mkdir({ path: targetPath });
+  }
+
+  /**
+   * Check existence
+   */
+  static async exists(targetPath: string): Promise<boolean> {
+    const result = await FileSystemPlugin.exists({ path: targetPath });
+    return result.exists;
+  }
+}

package/src/IFileSystemPlugin.ts

@@ -0,0 +1,26 @@
+export type TStorage =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+
+export interface IFileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+
+export interface IFileSystemPlugin {
+  hasPermission(): Promise<{ granted: boolean }>;
+  requestPermission(): Promise<void>;
+  readdir(options: { path: string }): Promise<{ files: IFileInfo[] }>;
+  getStoragePath(options: { type: TStorage }): Promise<{ path: string }>;
+  getFileUri(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 }>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+// File System
+export * from "./FileSystem";
+export * from "./IFileSystemPlugin";

package/src/web/FileSystemWeb.ts

@@ -0,0 +1,118 @@
+import { WebPlugin } from "@capacitor/core";
+import type { IFileInfo, IFileSystemPlugin, TStorage } from "../IFileSystemPlugin";
+import { VirtualFileSystem } from "./VirtualFileSystem";
+import { bytesToBase64, bytesFromBase64 } from "@simplysm/core-common";
+
+export class FileSystemWeb extends WebPlugin implements IFileSystemPlugin {
+  private readonly _fs = new VirtualFileSystem("capacitor_web_virtual_fs");
+  private readonly _textEncoder = new TextEncoder();
+  private readonly _textDecoder = new TextDecoder();
+
+  async hasPermission(): Promise<{ granted: boolean }> {
+    return Promise.resolve({ granted: true });
+  }
+
+  async requestPermission(): Promise<void> {}
+
+  async readdir(options: { path: string }): Promise<{ files: IFileInfo[] }> {
+    const entry = await this._fs.getEntry(options.path);
+    if (!entry || entry.kind !== "dir") {
+      throw new Error("Directory does not exist");
+    }
+    const files = await this._fs.listChildren(options.path);
+    return { files };
+  }
+
+  async getStoragePath(options: { type: TStorage }): Promise<{ path: string }> {
+    const base = "/webfs";
+    let storagePath: string;
+    switch (options.type) {
+      case "external":
+        storagePath = base + "/external";
+        break;
+      case "externalFiles":
+        storagePath = base + "/externalFiles";
+        break;
+      case "externalCache":
+        storagePath = base + "/externalCache";
+        break;
+      case "externalMedia":
+        storagePath = base + "/externalMedia";
+        break;
+      case "appData":
+        storagePath = base + "/appData";
+        break;
+      case "appFiles":
+        storagePath = base + "/appFiles";
+        break;
+      case "appCache":
+        storagePath = base + "/appCache";
+        break;
+      default:
+        throw new Error("Unknown storage type: " + options.type);
+    }
+    await this._fs.ensureDir(storagePath);
+    return { path: storagePath };
+  }
+
+  /**
+   * Return the Blob URL of a file.
+   * @warning The returned URI must be released by calling `URL.revokeObjectURL(uri)` after use.
+   * Failure to release may cause memory leaks.
+   */
+  async getFileUri(options: { path: string }): Promise<{ uri: string }> {
+    const entry = await this._fs.getEntry(options.path);
+    if (!entry || entry.kind !== "file" || entry.dataBase64 == null) {
+      throw new Error("File not found: " + options.path);
+    }
+    const bytes = bytesFromBase64(entry.dataBase64);
+    const blob = new Blob([bytes as BlobPart]);
+    return { uri: URL.createObjectURL(blob) };
+  }
+
+  async writeFile(options: {
+    path: string;
+    data: string;
+    encoding?: "utf8" | "base64";
+  }): Promise<void> {
+    const idx = options.path.lastIndexOf("/");
+    const dir = idx === -1 ? "." : options.path.substring(0, idx) || "/";
+    await this._fs.ensureDir(dir);
+    const dataBase64 =
+      options.encoding === "base64"
+        ? options.data
+        : bytesToBase64(this._textEncoder.encode(options.data));
+    await this._fs.putEntry({ path: options.path, kind: "file", dataBase64 });
+  }
+
+  async readFile(options: {
+    path: string;
+    encoding?: "utf8" | "base64";
+  }): Promise<{ data: string }> {
+    const entry = await this._fs.getEntry(options.path);
+    if (!entry || entry.kind !== "file" || entry.dataBase64 == null) {
+      throw new Error("File not found: " + options.path);
+    }
+    const data =
+      options.encoding === "base64"
+        ? entry.dataBase64
+        : this._textDecoder.decode(bytesFromBase64(entry.dataBase64));
+    return { data };
+  }
+
+  async remove(options: { path: string }): Promise<void> {
+    const ok = await this._fs.deleteByPrefix(options.path);
+    if (!ok) {
+      throw new Error("Deletion failed");
+    }
+  }
+
+  async mkdir(options: { path: string }): Promise<void> {
+    await this._fs.ensureDir(options.path);
+  }
+
+  async exists(options: { path: string }): Promise<{ exists: boolean }> {
+    const entry = await this._fs.getEntry(options.path);
+    return { exists: !!entry };
+  }
+}

package/src/web/IndexedDbStore.ts

@@ -0,0 +1,88 @@
+export interface IStoreConfig {
+  name: string;
+  keyPath: string;
+}
+
+export class IndexedDbStore {
+  constructor(
+    private readonly _dbName: string,
+    private readonly _dbVersion: number,
+    private readonly _storeConfigs: IStoreConfig[],
+  ) {}
+
+  async open(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open(this._dbName, this._dbVersion);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        for (const config of this._storeConfigs) {
+          if (!db.objectStoreNames.contains(config.name)) {
+            db.createObjectStore(config.name, { keyPath: config.keyPath });
+          }
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+      req.onblocked = () => reject(new Error("Database blocked by another connection"));
+    });
+  }
+
+  async withStore<T>(
+    storeName: string,
+    mode: IDBTransactionMode,
+    fn: (store: IDBObjectStore) => Promise<T>,
+  ): Promise<T> {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, mode);
+      const store = tx.objectStore(storeName);
+      let result: T;
+      Promise.resolve(fn(store))
+        .then((r) => {
+          result = r;
+        })
+        .catch((err) => {
+          db.close();
+          reject(err);
+        });
+      tx.oncomplete = () => {
+        db.close();
+        resolve(result);
+      };
+      tx.onerror = () => {
+        db.close();
+        reject(tx.error);
+      };
+    });
+  }
+
+  async get<T>(storeName: string, key: IDBValidKey): Promise<T | undefined> {
+    return this.withStore(storeName, "readonly", async (store) => {
+      return new Promise((resolve, reject) => {
+        const req = store.get(key);
+        req.onsuccess = () => resolve(req.result as T | undefined);
+        req.onerror = () => reject(req.error);
+      });
+    });
+  }
+
+  async put(storeName: string, value: unknown): Promise<void> {
+    return this.withStore(storeName, "readwrite", async (store) => {
+      return new Promise((resolve, reject) => {
+        const req = store.put(value);
+        req.onsuccess = () => resolve();
+        req.onerror = () => reject(req.error);
+      });
+    });
+  }
+
+  async getAll<T>(storeName: string): Promise<T[]> {
+    return this.withStore(storeName, "readonly", async (store) => {
+      return new Promise((resolve, reject) => {
+        const req = store.getAll();
+        req.onsuccess = () => resolve(req.result as T[]);
+        req.onerror = () => reject(req.error);
+      });
+    });
+  }
+}

package/src/web/VirtualFileSystem.ts

@@ -0,0 +1,107 @@
+import type { IFileInfo } from "../IFileSystemPlugin";
+import { IndexedDbStore } from "./IndexedDbStore";
+
+interface FsEntry {
+  path: string;
+  kind: "file" | "dir";
+  dataBase64?: string;
+}
+
+export class VirtualFileSystem {
+  private readonly _STORE_NAME = "entries";
+  private readonly _db: IndexedDbStore;
+
+  constructor(dbName: string) {
+    this._db = new IndexedDbStore(dbName, 1, [{ name: this._STORE_NAME, keyPath: "path" }]);
+  }
+
+  async getEntry(filePath: string): Promise<FsEntry | undefined> {
+    return this._db.get<FsEntry>(this._STORE_NAME, filePath);
+  }
+
+  async putEntry(entry: FsEntry): Promise<void> {
+    return this._db.put(this._STORE_NAME, entry);
+  }
+
+  async deleteByPrefix(pathPrefix: string): Promise<boolean> {
+    return this._db.withStore(this._STORE_NAME, "readwrite", async (store) => {
+      return new Promise((resolve, reject) => {
+        const req = store.openCursor();
+        let found = false;
+        req.onsuccess = () => {
+          const cursor = req.result;
+          if (!cursor) {
+            resolve(found);
+            return;
+          }
+          const key = String(cursor.key);
+          if (key === pathPrefix || key.startsWith(pathPrefix + "/")) {
+            found = true;
+            cursor.delete();
+          }
+          cursor.continue();
+        };
+        req.onerror = () => reject(req.error);
+      });
+    });
+  }
+
+  /**
+   * Return the direct children of a directory.
+   * @param dirPath Directory path to query
+   * @returns List of child files/directories
+   * @note Implicit directory handling: Even when only file paths exist without directory entries,
+   * intermediate paths are treated as directories. e.g., With only "/a/b/c.txt" stored,
+   * calling listChildren("/a") returns "b" with isDirectory: true.
+   */
+  async listChildren(dirPath: string): Promise<IFileInfo[]> {
+    const prefix = dirPath === "/" ? "/" : dirPath + "/";
+    return this._db.withStore(this._STORE_NAME, "readonly", async (store) => {
+      return new Promise((resolve, reject) => {
+        const req = store.openCursor();
+        const map = new Map<string, boolean>();
+        req.onsuccess = () => {
+          const cursor = req.result;
+          if (!cursor) {
+            resolve(
+              Array.from(map.entries()).map(([name, isDirectory]) => ({ name, isDirectory })),
+            );
+            return;
+          }
+          const key = String(cursor.key);
+          if (key.startsWith(prefix)) {
+            const rest = key.slice(prefix.length);
+            if (rest) {
+              const segments = rest.split("/").filter(Boolean);
+              if (segments.length > 0) {
+                const firstSeg = segments[0];
+                if (!map.has(firstSeg)) {
+                  const isDir = segments.length > 1 || (cursor.value as FsEntry).kind === "dir";
+                  map.set(firstSeg, isDir);
+                }
+              }
+            }
+          }
+          cursor.continue();
+        };
+        req.onerror = () => reject(req.error);
+      });
+    });
+  }
+
+  async ensureDir(dirPath: string): Promise<void> {
+    if (dirPath === "/") {
+      await this.putEntry({ path: "/", kind: "dir" });
+      return;
+    }
+    const segments = dirPath.split("/").filter(Boolean);
+    let acc = "";
+    for (const seg of segments) {
+      acc += "/" + seg;
+      const existing = await this.getEntry(acc);
+      if (!existing) {
+        await this.putEntry({ path: acc, kind: "dir" });
+      }
+    }
+  }
+}