From 37534d971c219706660bf0aad9c0686c99857350 Mon Sep 17 00:00:00 2001 From: Chace Daniels Date: Mon, 5 May 2025 09:59:33 -0500 Subject: [PATCH 1/2] deprecate(filesystem): deprecate downloadFile and add migration steps for file transfer plugin --- filesystem/README.md | 58 +++++++++++++++++++++++++++++++++++ filesystem/src/definitions.ts | 39 +++++++++++++++-------- 2 files changed, 84 insertions(+), 13 deletions(-) diff --git a/filesystem/README.md b/filesystem/README.md index 32c7ba2d9..1965276c0 100644 --- a/filesystem/README.md +++ b/filesystem/README.md @@ -42,6 +42,64 @@ For detailed steps on how to do this, please see the [Capacitor Docs](https://ca ``` +## Migrating from downloadFile to File Transfer plugin + +As of version 7.1.0, the `downloadFile` functionality in the Filesystem plugin has been deprecated in favor of the new [@capacitor/file-transfer](https://capacitorjs.com/docs/apis/file-transfer) plugin. + +### Installing the File Transfer plugin + +```bash +npm install @capacitor/file-transfer +npx cap sync +``` + +### Migration example + +Before (using Filesystem plugin): + +```typescript +import { Filesystem, Directory } from '@capacitor/filesystem'; + +await Filesystem.downloadFile({ + url: 'https://example.com/file.pdf', + path: 'downloaded-file.pdf', + directory: Directory.Documents, + progress: true +}); + +// Progress events +Filesystem.addListener('progress', (progress) => { + console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`); +}); +``` + +After (using File Transfer plugin): + +```typescript +import { FileTransfer } from '@capacitor/file-transfer'; +import { Filesystem, Directory } from '@capacitor/filesystem'; + +// First get the full file path using Filesystem +const fileInfo = await Filesystem.getUri({ + directory: Directory.Documents, + path: 'downloaded-file.pdf' +}); + +// Then use the FileTransfer plugin to download +await FileTransfer.downloadFile({ + url: 'https://example.com/file.pdf', + path: fileInfo.uri, + progress: true +}); + +// Progress events +FileTransfer.addListener('progress', (progress) => { + console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`); +}); +``` + +The File Transfer plugin offers improved reliability, better error handling with specific error codes, and also adds upload functionality. + ## iOS To have files appear in the Files app, you must also set the following keys to `YES` in `Info.plist`: diff --git a/filesystem/src/definitions.ts b/filesystem/src/definitions.ts index 5d0bce164..d9c880c7b 100644 --- a/filesystem/src/definitions.ts +++ b/filesystem/src/definitions.ts @@ -485,7 +485,8 @@ export interface CopyResult { export interface DownloadFileOptions extends HttpOptions { /** * The path the downloaded file should be moved to. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ path: string; @@ -493,7 +494,8 @@ export interface DownloadFileOptions extends HttpOptions { * The directory to write the file to. * If this option is used, filePath can be a relative path rather than absolute. * The default is the `DATA` directory. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ directory?: Directory; @@ -501,14 +503,16 @@ export interface DownloadFileOptions extends HttpOptions { * An optional listener function to receive downloaded progress events. * If this option is used, progress event should be dispatched on every chunk received. * Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ progress?: boolean; /** * Whether to create any missing parent directories. - * + * * @default false + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.2 */ recursive?: boolean; @@ -517,14 +521,16 @@ export interface DownloadFileOptions extends HttpOptions { export interface DownloadFileResult { /** * The path the file was downloaded to. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ path?: string; /** * The blob data of the downloaded file. * This is only available on web. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ blob?: Blob; @@ -532,19 +538,22 @@ export interface DownloadFileResult { export interface ProgressStatus { /** * The url of the file being downloaded. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ url: string; /** * The number of bytes downloaded so far. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ bytes: number; /** * The total number of bytes to download for this file. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ contentLength: number; @@ -552,7 +561,8 @@ export interface ProgressStatus { /** * A listener function that receives progress events. - * + * + * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ export type ProgressListener = (progress: ProgressStatus) => void; @@ -655,14 +665,16 @@ export interface FilesystemPlugin { /** * Perform a http request to a server and download the file to the specified destination. - * + * + * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.1.0 */ downloadFile(options: DownloadFileOptions): Promise; /** * Add a listener to file download progress events. - * + * + * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.1.0 */ addListener( @@ -671,7 +683,8 @@ export interface FilesystemPlugin { ): Promise; /** * Remove all listeners for this plugin. - * + * + * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.2.0 */ removeAllListeners(): Promise; From ed59dd009a099be28939e49597e79d4dbe87db16 Mon Sep 17 00:00:00 2001 From: Chace Daniels Date: Wed, 7 May 2025 20:40:53 -0500 Subject: [PATCH 2/2] chore: run fmt --- filesystem/src/definitions.ts | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/filesystem/src/definitions.ts b/filesystem/src/definitions.ts index d9c880c7b..ca0c114ed 100644 --- a/filesystem/src/definitions.ts +++ b/filesystem/src/definitions.ts @@ -485,7 +485,7 @@ export interface CopyResult { export interface DownloadFileOptions extends HttpOptions { /** * The path the downloaded file should be moved to. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -494,7 +494,7 @@ export interface DownloadFileOptions extends HttpOptions { * The directory to write the file to. * If this option is used, filePath can be a relative path rather than absolute. * The default is the `DATA` directory. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -503,14 +503,14 @@ export interface DownloadFileOptions extends HttpOptions { * An optional listener function to receive downloaded progress events. * If this option is used, progress event should be dispatched on every chunk received. * Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ progress?: boolean; /** * Whether to create any missing parent directories. - * + * * @default false * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.2 @@ -521,7 +521,7 @@ export interface DownloadFileOptions extends HttpOptions { export interface DownloadFileResult { /** * The path the file was downloaded to. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -529,7 +529,7 @@ export interface DownloadFileResult { /** * The blob data of the downloaded file. * This is only available on web. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -538,21 +538,21 @@ export interface DownloadFileResult { export interface ProgressStatus { /** * The url of the file being downloaded. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ url: string; /** * The number of bytes downloaded so far. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ bytes: number; /** * The total number of bytes to download for this file. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -561,7 +561,7 @@ export interface ProgressStatus { /** * A listener function that receives progress events. - * + * * @deprecated Use @capacitor/file-transfer instead. * @since 5.1.0 */ @@ -665,7 +665,7 @@ export interface FilesystemPlugin { /** * Perform a http request to a server and download the file to the specified destination. - * + * * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.1.0 */ @@ -673,7 +673,7 @@ export interface FilesystemPlugin { /** * Add a listener to file download progress events. - * + * * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.1.0 */ @@ -683,7 +683,7 @@ export interface FilesystemPlugin { ): Promise; /** * Remove all listeners for this plugin. - * + * * @deprecated Use @capacitor/file-transfer plugin instead. * @since 5.2.0 */