@capacitor/filesystem 7.0.2-nightly-20250526T150552.0 → 7.1.0-dev.1

package/android/src/main/kotlin/com/capacitorjs/plugins/filesystem/LegacyFilesystemImplementation.kt

@@ -0,0 +1,169 @@
+package com.capacitorjs.plugins.filesystem
+
+import android.content.Context
+import android.net.Uri
+import android.os.Environment
+import android.os.Handler
+import android.os.Looper
+import com.getcapacitor.Bridge
+import com.getcapacitor.JSObject
+import com.getcapacitor.PluginCall
+import com.getcapacitor.plugin.util.HttpRequestHandler.HttpURLConnectionBuilder
+import com.getcapacitor.plugin.util.HttpRequestHandler.ProgressEmitter
+import org.json.JSONException
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.net.URISyntaxException
+import java.net.URL
+import kotlin.concurrent.thread
+
+class LegacyFilesystemImplementation internal constructor(private val context: Context) {
+    fun downloadFile(
+        call: PluginCall,
+        bridge: Bridge,
+        emitter: ProgressEmitter?,
+        callback: FilesystemDownloadCallback
+    ) {
+        val urlString = call.getString("url", "")
+        val handler = Handler(Looper.getMainLooper())
+
+        thread {
+            try {
+                val result =
+                    doDownloadInBackground(urlString, call, bridge, emitter)
+                handler.post { callback.onSuccess(result) }
+            } catch (error: Exception) {
+                handler.post { callback.onError(error) }
+            }
+        }
+    }
+
+    /**
+     * True if the given directory string is a public storage directory, which is accessible by the user or other apps.
+     * @param directory the directory string.
+     */
+    fun isPublicDirectory(directory: String?): Boolean {
+        return "DOCUMENTS" == directory || "EXTERNAL_STORAGE" == directory
+    }
+
+    private fun getDirectory(directory: String): File? {
+        val c = this.context
+        when (directory) {
+            "DOCUMENTS" -> return Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOCUMENTS)
+            "DATA", "LIBRARY" -> return c.filesDir
+            "CACHE" -> return c.cacheDir
+            "EXTERNAL" -> return c.getExternalFilesDir(null)
+            "EXTERNAL_STORAGE" -> return Environment.getExternalStorageDirectory()
+        }
+        return null
+    }
+
+    private fun getFileObject(path: String, directory: String?): File? {
+        if (directory == null) {
+            val u = Uri.parse(path)
+            if (u.scheme == null || u.scheme == "file") {
+                return File(u.path)
+            }
+        }
+
+        val androidDirectory = this.getDirectory(directory!!)
+
+        if (androidDirectory == null) {
+            return null
+        } else {
+            if (!androidDirectory.exists()) {
+                androidDirectory.mkdir()
+            }
+        }
+
+        return File(androidDirectory, path)
+    }
+
+    @Throws(IOException::class, URISyntaxException::class, JSONException::class)
+    private fun doDownloadInBackground(
+        urlString: String?,
+        call: PluginCall,
+        bridge: Bridge,
+        emitter: ProgressEmitter?
+    ): JSObject {
+        val headers = call.getObject("headers", JSObject())
+        val params = call.getObject("params", JSObject())
+        val connectTimeout = call.getInt("connectTimeout")
+        val readTimeout = call.getInt("readTimeout")
+        val disableRedirects = call.getBoolean("disableRedirects") ?: false
+        val shouldEncode = call.getBoolean("shouldEncodeUrlParams") ?: true
+        val progress = call.getBoolean("progress") ?: false
+
+        val method = call.getString("method")?.uppercase() ?: "GET"
+        val path = call.getString("path")!!
+        val directory = call.getString("directory", Environment.DIRECTORY_DOWNLOADS)
+
+        val url = URL(urlString)
+        val file = getFileObject(path, directory)
+
+        val connectionBuilder = HttpURLConnectionBuilder()
+            .setUrl(url)
+            .setMethod(method)
+            .setHeaders(headers)
+            .setUrlParams(params, shouldEncode)
+            .setConnectTimeout(connectTimeout)
+            .setReadTimeout(readTimeout)
+            .setDisableRedirects(disableRedirects)
+            .openConnection()
+
+        val connection = connectionBuilder.build()
+
+        connection.setSSLSocketFactory(bridge)
+
+        val connectionInputStream = connection.inputStream
+        val fileOutputStream = FileOutputStream(file, false)
+
+        val contentLength = connection.getHeaderField("content-length")
+        var bytes = 0
+        var maxBytes = 0
+
+        try {
+            maxBytes = contentLength?.toInt() ?: 0
+        } catch (ignored: NumberFormatException) {
+        }
+
+        val buffer = ByteArray(1024)
+        var len: Int
+
+        // Throttle emitter to 100ms so it doesn't slow down app
+        var lastEmitTime = System.currentTimeMillis()
+        val minEmitIntervalMillis: Long = 100
+
+        while ((connectionInputStream.read(buffer).also { len = it }) > 0) {
+            fileOutputStream.write(buffer, 0, len)
+
+            bytes += len
+
+            if (progress!! && null != emitter) {
+                val currentTime = System.currentTimeMillis()
+                if (currentTime - lastEmitTime > minEmitIntervalMillis) {
+                    emitter.emit(bytes, maxBytes)
+                    lastEmitTime = currentTime
+                }
+            }
+        }
+
+        if (progress!! && null != emitter) {
+            emitter.emit(bytes, maxBytes)
+        }
+
+        connectionInputStream.close()
+        fileOutputStream.close()
+
+        val ret = JSObject()
+        ret.put("path", file!!.absolutePath)
+        return ret
+    }
+
+    interface FilesystemDownloadCallback {
+        fun onSuccess(result: JSObject)
+
+        fun onError(error: Exception)
+    }
+}

package/android/src/main/kotlin/com/capacitorjs/plugins/filesystem/PluginResultExtensions.kt

@@ -0,0 +1,25 @@
+package com.capacitorjs.plugins.filesystem
+
+import com.getcapacitor.JSObject
+import com.getcapacitor.PluginCall
+
+/**
+ * Extension function to return a successful plugin result
+ * @param result JSOObject with the JSON content to return
+ * @param keepCallback boolean to determine if callback should be kept for future calls or not
+ */
+internal fun PluginCall.sendSuccess(result: JSObject? = null, keepCallback: Boolean = false) {
+    this.setKeepAlive(keepCallback)
+    if (result != null) {
+        this.resolve(result)
+    } else {
+        this.resolve()
+    }
+}
+
+/**
+ * Extension function to return a unsuccessful plugin result
+ * @param error error class representing the error to return, containing a code and message
+ */
+internal fun PluginCall.sendError(error: FilesystemErrors.ErrorInfo) =
+    this.reject(error.message, error.code)

package/dist/docs.json

@@ -5,6 +5,40 @@
     "docs": "",
     "tags": [],
     "methods": [
+      {
+        "name": "checkPermissions",
+        "signature": "() => Promise<PermissionStatus>",
+        "parameters": [],
+        "returns": "Promise<PermissionStatus>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Check read/write permissions.\nRequired on Android, only when using `Directory.Documents` or\n`Directory.ExternalStorage`.",
+        "complexTypes": [
+          "PermissionStatus"
+        ],
+        "slug": "checkpermissions"
+      },
+      {
+        "name": "requestPermissions",
+        "signature": "() => Promise<PermissionStatus>",
+        "parameters": [],
+        "returns": "Promise<PermissionStatus>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Request read/write permissions.\nRequired on Android, only when using `Directory.Documents` or\n`Directory.ExternalStorage`.",
+        "complexTypes": [
+          "PermissionStatus"
+        ],
+        "slug": "requestpermissions"
+      },
       {
         "name": "readFile",
         "signature": "(options: ReadFileOptions) => Promise<ReadFileResult>",
@@ -29,6 +63,36 @@
         ],
         "slug": "readfile"
       },
+      {
+        "name": "readFileInChunks",
+        "signature": "(options: ReadFileInChunksOptions, callback: ReadFileInChunksCallback) => Promise<CallbackID>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "ReadFileInChunksOptions"
+          },
+          {
+            "name": "callback",
+            "docs": "",
+            "type": "ReadFileInChunksCallback"
+          }
+        ],
+        "returns": "Promise<string>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "7.1.0"
+          }
+        ],
+        "docs": "Read a file from disk, in chunks.\nNative only (not available in web).\nUse the callback to receive each read chunk.\nIf empty chunk is returned, it means file has been completely read.",
+        "complexTypes": [
+          "ReadFileInChunksOptions",
+          "ReadFileInChunksCallback",
+          "CallbackID"
+        ],
+        "slug": "readfileinchunks"
+      },
       {
         "name": "writeFile",
         "signature": "(options: WriteFileOptions) => Promise<WriteFileResult>",
@@ -203,7 +267,7 @@
             "type": "StatOptions"
           }
         ],
-        "returns": "Promise<StatResult>",
+        "returns": "Promise<FileInfo>",
         "tags": [
           {
             "name": "since",
@@ -212,8 +276,9 @@
         ],
         "docs": "Return data about a file",
         "complexTypes": [
-          "StatResult",
-          "StatOptions"
+          "FileInfo",
+          "StatOptions",
+          "StatResult"
         ],
         "slug": "stat"
       },
@@ -264,40 +329,6 @@
         ],
         "slug": "copy"
       },
-      {
-        "name": "checkPermissions",
-        "signature": "() => Promise<PermissionStatus>",
-        "parameters": [],
-        "returns": "Promise<PermissionStatus>",
-        "tags": [
-          {
-            "name": "since",
-            "text": "1.0.0"
-          }
-        ],
-        "docs": "Check read/write permissions.\nRequired on Android, only when using `Directory.Documents` or\n`Directory.ExternalStorage`.",
-        "complexTypes": [
-          "PermissionStatus"
-        ],
-        "slug": "checkpermissions"
-      },
-      {
-        "name": "requestPermissions",
-        "signature": "() => Promise<PermissionStatus>",
-        "parameters": [],
-        "returns": "Promise<PermissionStatus>",
-        "tags": [
-          {
-            "name": "since",
-            "text": "1.0.0"
-          }
-        ],
-        "docs": "Request read/write permissions.\nRequired on Android, only when using `Directory.Documents` or\n`Directory.ExternalStorage`.",
-        "complexTypes": [
-          "PermissionStatus"
-        ],
-        "slug": "requestpermissions"
-      },
       {
         "name": "downloadFile",
         "signature": "(options: DownloadFileOptions) => Promise<DownloadFileResult>",
@@ -313,9 +344,17 @@
           {
             "name": "since",
             "text": "5.1.0"
+          },
+          {
+            "name": "deprecated",
+            "text": "Use the"
+          },
+          {
+            "name": "capacitor",
+            "text": "/file-transfer plugin instead."
           }
         ],
-        "docs": "Perform a http request to a server and download the file to the specified destination.",
+        "docs": "Perform a http request to a server and download the file to the specified destination.\n\nThis method has been deprecated since version 7.1.0.\nWe recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.",
         "complexTypes": [
           "DownloadFileResult",
           "DownloadFileOptions"
@@ -342,9 +381,17 @@
           {
             "name": "since",
             "text": "5.1.0"
+          },
+          {
+            "name": "deprecated",
+            "text": "Use the"
+          },
+          {
+            "name": "capacitor",
+            "text": "/file-transfer plugin instead."
           }
         ],
-        "docs": "Add a listener to file download progress events.",
+        "docs": "Add a listener to file download progress events.\n\nThis method has been deprecated since version 7.1.0.\nWe recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.",
         "complexTypes": [
           "PluginListenerHandle",
           "ProgressListener"
@@ -360,9 +407,17 @@
           {
             "name": "since",
             "text": "5.2.0"
+          },
+          {
+            "name": "deprecated",
+            "text": "Use the"
+          },
+          {
+            "name": "capacitor",
+            "text": "/file-transfer plugin instead."
           }
         ],
-        "docs": "Remove all listeners for this plugin.",
+        "docs": "Remove all listeners for this plugin.\n\nThis method has been deprecated since version 7.1.0.\nWe recommend using the @capacitor/file-transfer plugin instead, in conjunction with this plugin.",
         "complexTypes": [],
         "slug": "removealllisteners"
       }
@@ -370,6 +425,24 @@
     "properties": []
   },
   "interfaces": [
+    {
+      "name": "PermissionStatus",
+      "slug": "permissionstatus",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "publicStorage",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "PermissionState"
+          ],
+          "type": "PermissionState"
+        }
+      ]
+    },
     {
       "name": "ReadFileResult",
       "slug": "readfileresult",
@@ -442,6 +515,27 @@
         }
       ]
     },
+    {
+      "name": "ReadFileInChunksOptions",
+      "slug": "readfileinchunksoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "chunkSize",
+          "tags": [
+            {
+              "text": "7.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Size of the chunks in bytes.",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
+    },
     {
       "name": "WriteFileResult",
       "slug": "writefileresult",
@@ -772,7 +866,12 @@
       "properties": [
         {
           "name": "name",
-          "tags": [],
+          "tags": [
+            {
+              "text": "7.1.0",
+              "name": "since"
+            }
+          ],
           "docs": "Name of the file or directory.",
           "complexTypes": [],
           "type": "string"
@@ -805,7 +904,7 @@
           "name": "ctime",
           "tags": [
             {
-              "text": "4.0.0",
+              "text": "7.1.0",
               "name": "since"
             }
           ],
@@ -817,7 +916,7 @@
           "name": "mtime",
           "tags": [
             {
-              "text": "4.0.0",
+              "text": "7.1.0",
               "name": "since"
             }
           ],
@@ -930,75 +1029,6 @@
         }
       ]
     },
-    {
-      "name": "StatResult",
-      "slug": "statresult",
-      "docs": "",
-      "tags": [],
-      "methods": [],
-      "properties": [
-        {
-          "name": "type",
-          "tags": [
-            {
-              "text": "1.0.0",
-              "name": "since"
-            }
-          ],
-          "docs": "Type of the file.",
-          "complexTypes": [],
-          "type": "'file' | 'directory'"
-        },
-        {
-          "name": "size",
-          "tags": [
-            {
-              "text": "1.0.0",
-              "name": "since"
-            }
-          ],
-          "docs": "Size of the file in bytes.",
-          "complexTypes": [],
-          "type": "number"
-        },
-        {
-          "name": "ctime",
-          "tags": [
-            {
-              "text": "1.0.0",
-              "name": "since"
-            }
-          ],
-          "docs": "Time of creation in milliseconds.\n\nIt's not available on Android 7 and older devices.",
-          "complexTypes": [],
-          "type": "number | undefined"
-        },
-        {
-          "name": "mtime",
-          "tags": [
-            {
-              "text": "1.0.0",
-              "name": "since"
-            }
-          ],
-          "docs": "Time of last modification in milliseconds.",
-          "complexTypes": [],
-          "type": "number"
-        },
-        {
-          "name": "uri",
-          "tags": [
-            {
-              "text": "1.0.0",
-              "name": "since"
-            }
-          ],
-          "docs": "The uri of the file",
-          "complexTypes": [],
-          "type": "string"
-        }
-      ]
-    },
     {
       "name": "StatOptions",
       "slug": "statoptions",
@@ -1116,24 +1146,6 @@
         }
       ]
     },
-    {
-      "name": "PermissionStatus",
-      "slug": "permissionstatus",
-      "docs": "",
-      "tags": [],
-      "methods": [],
-      "properties": [
-        {
-          "name": "publicStorage",
-          "tags": [],
-          "docs": "",
-          "complexTypes": [
-            "PermissionState"
-          ],
-          "type": "PermissionState"
-        }
-      ]
-    },
     {
       "name": "DownloadFileResult",
       "slug": "downloadfileresult",
@@ -1308,7 +1320,7 @@
               "name": "since"
             }
           ],
-          "docs": "The Documents directory.\nOn iOS it's the app's documents directory.\nUse this directory to store user-generated content.\nOn Android it's the Public Documents folder, so it's accessible from other apps.\nIt's not accesible on Android 10 unless the app enables legacy External Storage\nby adding `android:requestLegacyExternalStorage=\"true\"` in the `application` tag\nin the `AndroidManifest.xml`.\nOn Android 11 or newer the app can only access the files/folders the app created."
+          "docs": "The Documents directory.\nOn iOS it's the app's documents directory.\nUse this directory to store user-generated content.\nOn Android it's the Public Documents folder, so it's accessible from other apps.\nIt's not accessible on Android 10 unless the app enables legacy External Storage\nby adding `android:requestLegacyExternalStorage=\"true\"` in the `application` tag\nin the `AndroidManifest.xml`.\nOn Android 11 or newer the app can only access the files/folders the app created."
         },
         {
           "name": "Data",
@@ -1363,7 +1375,40 @@
               "name": "since"
             }
           ],
-          "docs": "The external storage directory.\nOn iOS it will use the Documents directory.\nOn Android it's the primary shared/external storage directory.\nIt's not accesible on Android 10 unless the app enables legacy External Storage\nby adding `android:requestLegacyExternalStorage=\"true\"` in the `application` tag\nin the `AndroidManifest.xml`.\nIt's not accesible on Android 11 or newer."
+          "docs": "The external storage directory.\nOn iOS it will use the Documents directory.\nOn Android it's the primary shared/external storage directory.\nIt's not accessible on Android 10 unless the app enables legacy External Storage\nby adding `android:requestLegacyExternalStorage=\"true\"` in the `application` tag\nin the `AndroidManifest.xml`.\nIt's not accessible on Android 11 or newer."
+        },
+        {
+          "name": "ExternalCache",
+          "value": "'EXTERNAL_CACHE'",
+          "tags": [
+            {
+              "text": "7.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The external cache directory.\nOn iOS it will use the Documents directory.\nOn Android it's the primary shared/external cache."
+        },
+        {
+          "name": "LibraryNoCloud",
+          "value": "'LIBRARY_NO_CLOUD'",
+          "tags": [
+            {
+              "text": "7.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The Library directory without cloud backup. Used in iOS.\nOn Android it's the directory holding application files."
+        },
+        {
+          "name": "Temporary",
+          "value": "'TEMPORARY'",
+          "tags": [
+            {
+              "text": "7.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "A temporary directory for iOS.\nOn Android it's the directory holding the application cache."
         }
       ]
     },
@@ -1408,19 +1453,6 @@
     }
   ],
   "typeAliases": [
-    {
-      "name": "RenameOptions",
-      "slug": "renameoptions",
-      "docs": "",
-      "types": [
-        {
-          "text": "CopyOptions",
-          "complexTypes": [
-            "CopyOptions"
-          ]
-        }
-      ]
-    },
     {
       "name": "PermissionState",
       "slug": "permissionstate",
@@ -1444,6 +1476,56 @@
         }
       ]
     },
+    {
+      "name": "ReadFileInChunksCallback",
+      "slug": "readfileinchunkscallback",
+      "docs": "Callback for receiving chunks read from a file, or error if something went wrong.",
+      "types": [
+        {
+          "text": "(chunkRead: ReadFileResult | null, err?: any): void",
+          "complexTypes": [
+            "ReadFileResult"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "CallbackID",
+      "slug": "callbackid",
+      "docs": "",
+      "types": [
+        {
+          "text": "string",
+          "complexTypes": []
+        }
+      ]
+    },
+    {
+      "name": "StatResult",
+      "slug": "statresult",
+      "docs": "",
+      "types": [
+        {
+          "text": "FileInfo",
+          "complexTypes": [
+            "FileInfo"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "RenameOptions",
+      "slug": "renameoptions",
+      "docs": "",
+      "types": [
+        {
+          "text": "CopyOptions",
+          "complexTypes": [
+            "CopyOptions"
+          ]
+        }
+      ]
+    },
     {
       "name": "ProgressListener",
       "slug": "progresslistener",