@simplysm/capacitor-plugin-file-system 13.0.98 → 13.0.99

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +63 -97
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @simplysm/capacitor-plugin-file-system
2
2
 
3
- Capacitor File System Plugin -- full file system access for Android with IndexedDB fallback for browser.
3
+ Simplysm Package - Capacitor File System Plugin. Provides file system access for Android (MANAGE_EXTERNAL_STORAGE on Android 11+) with IndexedDB-based browser emulation.
4
4
 
5
5
  ## Installation
6
6
 
@@ -10,88 +10,69 @@ npm install @simplysm/capacitor-plugin-file-system
10
10
 
11
11
  ## API Overview
12
12
 
13
- ### Types
13
+ ### File System
14
14
 
15
15
  | API | Type | Description |
16
16
  |-----|------|-------------|
17
- | `StorageType` | type | Storage location type (`"external"`, `"externalFiles"`, `"externalCache"`, `"externalMedia"`, `"appData"`, `"appFiles"`, `"appCache"`) |
18
- | `FileInfo` | interface | File entry info (`name`, `isDirectory`) |
17
+ | `FileSystem` | class | File system access plugin (static methods) |
18
+ | `FileSystemPlugin` | interface | Low-level Capacitor plugin interface for file system |
19
+ | `StorageType` | type | Storage location type |
20
+ | `FileInfo` | interface | File/directory entry information |
19
21
 
20
- ### Interfaces
22
+ ---
21
23
 
22
- | API | Type | Description |
23
- |-----|------|-------------|
24
- | `FileSystemPlugin` | interface | Low-level Capacitor plugin interface for file system operations |
25
-
26
- ### Classes
27
-
28
- | API | Type | Description |
29
- |-----|------|-------------|
30
- | `FileSystem` | abstract class | File system access with permission management |
31
-
32
- ## `StorageType`
24
+ ### `StorageType`
33
25
 
34
26
  ```typescript
35
27
  type StorageType =
36
- | "external"
37
- | "externalFiles"
38
- | "externalCache"
39
- | "externalMedia"
40
- | "appData"
41
- | "appFiles"
42
- | "appCache";
43
- ```
44
-
45
- ## `FileInfo`
46
-
47
- ```typescript
48
- interface FileInfo {
49
- name: string;
50
- isDirectory: boolean;
51
- }
52
- ```
53
-
54
- ## `FileSystemPlugin`
55
-
56
- ```typescript
57
- interface FileSystemPlugin {
58
- checkPermissions(): Promise<{ granted: boolean }>;
59
- requestPermissions(): Promise<void>;
60
- readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
61
- getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
62
- getUri(options: { path: string }): Promise<{ uri: string }>;
63
- writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
64
- readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
65
- remove(options: { path: string }): Promise<void>;
66
- mkdir(options: { path: string }): Promise<void>;
67
- exists(options: { path: string }): Promise<{ exists: boolean }>;
68
- }
69
- ```
70
-
71
- Low-level Capacitor plugin interface. Use `FileSystem` static methods instead of calling this directly.
72
-
73
- ## `FileSystem`
74
-
75
- ```typescript
76
- abstract class FileSystem {
77
- static async checkPermissions(): Promise<boolean>;
78
- static async requestPermissions(): Promise<void>;
79
- static async readdir(dirPath: string): Promise<FileInfo[]>;
80
- static async getStoragePath(type: StorageType): Promise<string>;
81
- static async getUri(filePath: string): Promise<string>;
82
- static async writeFile(filePath: string, data: string | Bytes): Promise<void>;
83
- static async readFile(filePath: string): Promise<Bytes>;
84
- static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
85
- static async remove(targetPath: string): Promise<void>;
86
- static async mkdir(targetPath: string): Promise<void>;
87
- static async exists(targetPath: string): Promise<boolean>;
88
- }
28
+ | "external" // External storage root (Environment.getExternalStorageDirectory)
29
+ | "externalFiles" // App-specific external files directory
30
+ | "externalCache" // App-specific external cache directory
31
+ | "externalMedia" // App-specific external media directory
32
+ | "appData" // App data directory
33
+ | "appFiles" // App files directory
34
+ | "appCache"; // App cache directory
89
35
  ```
90
36
 
91
- File system access plugin.
92
- - Android 11+: Full file system access via `MANAGE_EXTERNAL_STORAGE` permission.
93
- - Android 10-: `READ/WRITE_EXTERNAL_STORAGE` permission.
94
- - Browser: IndexedDB-based emulation.
37
+ ### `FileInfo`
38
+
39
+ | Field | Type | Description |
40
+ |-------|------|-------------|
41
+ | `name` | `string` | File or directory name |
42
+ | `isDirectory` | `boolean` | Whether the entry is a directory |
43
+
44
+ ### `FileSystemPlugin`
45
+
46
+ | Method | Signature | Description |
47
+ |--------|-----------|-------------|
48
+ | `checkPermissions` | `() => Promise<{ granted: boolean }>` | Check file system permission |
49
+ | `requestPermissions` | `() => Promise<void>` | Request file system permission |
50
+ | `readdir` | `(options: { path: string }) => Promise<{ files: FileInfo[] }>` | Read directory contents |
51
+ | `getStoragePath` | `(options: { type: StorageType }) => Promise<{ path: string }>` | Get storage path by type |
52
+ | `getUri` | `(options: { path: string }) => Promise<{ uri: string }>` | Get FileProvider URI |
53
+ | `writeFile` | `(options: { path: string; data: string; encoding?: "utf8" \| "base64" }) => Promise<void>` | Write file |
54
+ | `readFile` | `(options: { path: string; encoding?: "utf8" \| "base64" }) => Promise<{ data: string }>` | Read file |
55
+ | `remove` | `(options: { path: string }) => Promise<void>` | Delete file/directory |
56
+ | `mkdir` | `(options: { path: string }) => Promise<void>` | Create directory |
57
+ | `exists` | `(options: { path: string }) => Promise<{ exists: boolean }>` | Check existence |
58
+
59
+ ### `FileSystem`
60
+
61
+ Abstract class with static methods for file system access. Android 11+ uses MANAGE_EXTERNAL_STORAGE; Android 10- uses READ/WRITE_EXTERNAL_STORAGE; browser uses IndexedDB emulation.
62
+
63
+ | Method | Signature | Description |
64
+ |--------|-----------|-------------|
65
+ | `checkPermissions` | `() => Promise<boolean>` | Check permission |
66
+ | `requestPermissions` | `() => Promise<void>` | Request permission (Android 11+: settings, Android 10-: dialog) |
67
+ | `readdir` | `(dirPath: string) => Promise<FileInfo[]>` | Read directory |
68
+ | `getStoragePath` | `(type: StorageType) => Promise<string>` | Get storage path |
69
+ | `getUri` | `(filePath: string) => Promise<string>` | Get FileProvider URI |
70
+ | `writeFile` | `(filePath: string, data: string \| Bytes) => Promise<void>` | Write file (string or Uint8Array) |
71
+ | `readFile` | `(filePath: string) => Promise<Bytes>` | Read file as Bytes |
72
+ | `readFile` | `(filePath: string, encoding: "utf8") => Promise<string>` | Read file as UTF-8 string |
73
+ | `remove` | `(targetPath: string) => Promise<void>` | Delete file/directory (recursive) |
74
+ | `mkdir` | `(targetPath: string) => Promise<void>` | Create directory (recursive) |
75
+ | `exists` | `(targetPath: string) => Promise<boolean>` | Check existence |
95
76
 
96
77
  ## Usage Examples
97
78
 
@@ -100,33 +81,18 @@ File system access plugin.
100
81
  ```typescript
101
82
  import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
102
83
 
103
- const storagePath = await FileSystem.getStoragePath("appFiles");
104
- const filePath = storagePath + "/data.txt";
105
-
106
- await FileSystem.writeFile(filePath, "Hello, World!");
107
- const content = await FileSystem.readFile(filePath, "utf8");
108
- ```
109
-
110
- ### List directory contents
111
-
112
- ```typescript
113
- import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
114
-
115
- const granted = await FileSystem.checkPermissions();
116
- if (!granted) {
84
+ // Check and request permissions
85
+ if (!(await FileSystem.checkPermissions())) {
117
86
  await FileSystem.requestPermissions();
118
87
  }
119
88
 
120
- const externalPath = await FileSystem.getStoragePath("external");
121
- const files = await FileSystem.readdir(externalPath + "/Documents");
122
- ```
123
-
124
- ### Write binary data
89
+ // Get storage path and write a file
90
+ const storagePath = await FileSystem.getStoragePath("appFiles");
91
+ await FileSystem.writeFile(`${storagePath}/data.txt`, "Hello, world!");
125
92
 
126
- ```typescript
127
- import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
93
+ // Read it back
94
+ const content = await FileSystem.readFile(`${storagePath}/data.txt`, "utf8");
128
95
 
129
- const storagePath = await FileSystem.getStoragePath("appCache");
130
- await FileSystem.writeFile(storagePath + "/image.bin", myUint8Array);
131
- const data = await FileSystem.readFile(storagePath + "/image.bin");
96
+ // List directory contents
97
+ const files = await FileSystem.readdir(storagePath);
132
98
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simplysm/capacitor-plugin-file-system",
3
- "version": "13.0.98",
3
+ "version": "13.0.99",
4
4
  "description": "Simplysm Package - Capacitor File System Plugin",
5
5
  "author": "simplysm",
6
6
  "license": "MIT",
@@ -18,8 +18,8 @@
18
18
  "android"
19
19
  ],
20
20
  "dependencies": {
21
- "@simplysm/core-browser": "13.0.98",
22
- "@simplysm/core-common": "13.0.98"
21
+ "@simplysm/core-common": "13.0.99",
22
+ "@simplysm/core-browser": "13.0.99"
23
23
  },
24
24
  "devDependencies": {
25
25
  "@capacitor/core": "^7.6.0"