@dr.pogodin/react-native-fs
Version:
Native filesystem access for React Native
1,282 lines (1,043 loc) • 60.9 kB
Markdown
# React Native File System
<!-- Collection of hyperlinks. -->
[Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
[New Architecture]: https://reactnative.dev/docs/the-new-architecture/landing-page
[Old Architecture]: https://reactnative.dev/docs/native-modules-intro
[React Native]: https://reactnative.dev/
[react-native-fs]: https://github.com/itinance/react-native-fs
<!-- End of hyperlinks collection. -->
<!-- Status badges section (also double as links to related repos / CICD / etc.). -->
[](https://www.npmjs.com/package/@dr.pogodin/react-native-fs)
[](https://www.npmjs.com/package/@dr.pogodin/react-native-fs)
[](https://app.circleci.com/pipelines/github/birdofpreyru/react-native-fs)
[](https://github.com/birdofpreyru/react-native-fs)
[](https://dr.pogodin.studio/docs/react-native-fs)
<!-- End of status badges section. -->
File system access for [React Native] applications for Android, iOS,
Mac (Catalyst), and Windows platforms. Supports both [new][New Architecture]
and [old][Old Architecture] [RN][React Native] architectures.
[](https://github.com/sponsors/birdofpreyru)
## Table of Contents
- [Getting Started]
- [Project History & Roadmap]
- [Background Downloads Tutorial (iOS)](#background-downloads-tutorial-ios)
- [Examples]
- [API Reference]
- [Constants]
- [CachesDirectoryPath] — The absolute path to the caches directory.
- [DocumentDirectoryPath] — The absolute path to the document directory.
- [DownloadDirectoryPath] — (Android & Windows) The absolute path to
the download directory (on android and Windows only).
- [ExternalCachesDirectoryPath] — (Android) The absolute path to
the external caches directory.
- [ExternalDirectoryPath] — (Android) The absolute path to
the external files, shared directory.
- [ExternalStorageDirectoryPath] — (Android) The absolute path to
the external storage, shared directory.
- [LibraryDirectoryPath] — (iOS) The absolute path to
the NSLibraryDirectory.
- [MainBundlePath] — (non-Android) The absolute path to
the main bundle directory.
- [PicturesDirectoryPath] — The absolute path to the pictures directory.
- [RoamingDirectoryPath] — (Windows) The absolute path to the roaming
directory.
- [TemporaryDirectoryPath] — The absolute path to the temporary
directory.
- [Functions]
- [appendFile()] — Appends content to a file.
- [completeHandlerIOS()] — For use when using background downloads,
tell iOS you are done handling a completed download.
- [copyAssetsFileIOS()] — Reads an image file from Camera Roll and
writes it to the specified location. It also can be used to get video
thumbnails.
- [copyAssetsVideoIOS()] — Copies a video from the assets-library
to the specified destination.
- [copyFile()] — Copies a file to a new destination.
- [copyFileAssets()] — (Android only) Copies Android app's asset(s)
to the specified destination.
- [copyFileRes()] — (Android only) Copies specified resource to
the given destination.
- [copyFolder()] — (Windows only) Copies a folder to a new location
in a Windows-efficient way.
- [downloadFile()] — Downloads a file from network.
- [exists()] — Checks if an item exists at the given path.
- [existsAssets()] — (Android only) Checks if an item exists at
the given path inside
the Android assets folder.
- [existsRes()] — (Android only) Checks if the resource exists.
- [hash()] — Calculates file hash.
- [isResumable()] — (iOS only) Check if the the download job with this
ID is resumable with [resumeDownload()].
- [getAllExternalFilesDirs()] — (Android only) Returns an array with
the absolute paths to application-specific directories on all shared /
external storage devices where the application can place persistent files
it owns.
- [getFSInfo()] — Gets info on the free and total storage space
on the device, and its external storage.
- [mkdir()] — Creates folder(s) at the given path.
- [moveFile()] — Moves a file (or a folder with files) to a new location.
- [pathForGroup()] — (iOS only) Returns the absolute path to
the directory shared for all applications with the same security group
identifier.
- [pickFile()] — Prompts user to select file(s) with help of
a platform-provided file picker UI.
- [read()] — Reads a fragment of file content.
- [readdir()] — Lists the content of a folder (names only).
- [readDir()] — Lists the content of a folder (with item details).
- [readDirAssets()] — (Android only) Lists the content of a folder at
the given path inside the Android assets folder.
- [readFile()] — Reads entire file content.
- [readFileAssets()] — (Android only) Reads the file at a path in
the Android app's assets folder.
- [readFileRes()] — (Android only) Reads specified file in
the Android app's resource folder and return its contents.
- [resumeDownload()] — (iOS only) Resume an interrupted download job.
- [scanFile()] — (Android-only) Scan the file using
[Media Scanner](https://developer.android.com/reference/android/media/MediaScannerConnection).
- [stat()] — Returns info on a file system item.
- [stopDownload()] — Aborts a file download job.
- [stopUpload()] — (iOS only) Aborts file upload job.
- [touch()] — Alters creation and modification timestamps of the given file.
- [unlink()] — Unlinks (removes) a file or directory with files.
and return its contents.
- [uploadFiles()] — Uploads files to a remote location.
- [write()] — Writes content to a file at the given random access
position.
- [writeFile()] — Writes content into a file.
- [Types]
- [DownloadBeginCallbackResultT] — The type of argument passed
to `begin` callback in [DownloadFileOptionsT].
- [DownloadFileOptionsT] — Options for [downloadFile()].
- [DownloadProgressCallbackResultT] — The type of argument passed to
the `progress` callback in [DownloadFileOptionsT].
- [DownloadResultT] — Return type of [downloadFile()].
- [EncodingT] — Union of valid file encoding values.
- [FileOptionsT] — Extra options for [copyFile()].
- [FSInfoResultT] — The type of result resolved by [getFSInfo()].
- [MkdirOptionsT] — Extra options for [mkdir()].
- [PickFileOptionsT] — Optional parameters for [pickFile()].
- [ReadDirResItemT] — Elements returned by [readDir()].
- [ReadDirAssetsResItemT] — Elements returned by [readDirAssets()].
- [ReadFileOptionsT] — The type of extra options argument of
the [readFile()] function.
- [StatResultT] — The type of result resolved by [stat()].
- [StringMapT] — Just a simple **string**-to-**string** mapping.
- [UploadBeginCallbackArgT] — The type of `begin` callback argument in [UploadFileOptionsT].
- [UploadFileItemT] — The type of `files` elements in
[UploadFileOptionsT] objects.
- [UploadFileOptionsT] — Options for [uploadFiles()].
- [UploadProgressCallbackArgT] — The type of `progress` callback
argument in [UploadFileOptionsT], and a few other places.
- [UploadResultT] — The type of resolved [uploadFiles()] promise.
- [WriteFileOptionsT] — The type of extra options argument of
the [writeFile()] function.
## Getting Started
[Getting Started]: #getting-started
Just install & use:
```sh
$ npm install --save @dr.pogodin/react-native-fs
```
**Note**: Windows auto-link command (at least as it was needed for example project to install the lib hosted in the parent folder):
```sh
npx react-native autolink-windows --sln "windows\ReactNativeFsExample.sln" --proj "windows\ReactNativeFsExample\ReactNativeFsExample.vcxproj"
```
## Project History & Roadmap
[Project History & Roadmap]: #project-history--roadmap
This project is a fork of the upstream [react-native-fs] library, which has been
abandoned by its owners and maintainers. This forks aims to keep the library on
par with the latest React Native standards, with support of the [New Architecture],
backward compatibility with the [Old Architecture]; and to further develop
the library according to the best industry practices.
To migrate from the legacy [react-native-fs] install this fork_
```bash
npm install --save @dr.pogodin/react-native-fs
```
then upgrade its imports in the code:
```ts
// The legacy RNFS was imported like this:
import RNFS from 'react-native-fs';
// Instead, this fork should be imported like this:
import * as RNFS from '@dr.pogodin/react-native-fs';
// or (preferrably) you should import separate constants / functions you need
// like:
import {
TemporaryDirectoryPath,
writeFile,
} from '@dr.pogodin/react-native-fs';
```
**ROADMAP:**
- **v2.22.0** of this library is mostly a drop-in replacement for the latest
(**v2.20.0**) release of the original, upstream [react-native-fs]. It requires
to upgrade the host project to the latest RN v0.73+, and to correct the names
of TypeScript types exported from the library, if they are used, by appending
letter `T` to all of them. Beside these, the library has its functionality and
API matching the original library, with just a handful of internal fixes, and
a few added features.
- In further versions, **v2.X.Y**, we'll be taking care of improvements,
and optimizations of existing functionality, as well as adding new APIs,
and deprecating old ones (without yet dropping them out of the codebase),
with the ultimate goal to release **v3** version of the library.
- The aims for **v3** release are the following:
- To unify library APIs for all platforms — the current library has
a lots of platform-dependent APIs, which goes against the purpose and spirit
of React Native — we'll abstract out and unify everything that is
possible, to allow smooth cross-plaform ride.
- To make library API closer to [Node's File System API](https://nodejs.org/dist/latest-v18.x/docs/api/fs.html).
- To ensure that library has no intrinsic limitations (like now it is not efficient
for handling large files, _etc._)
## Background Downloads Tutorial (iOS)
Background downloads in iOS require a bit of a setup.
First, in your `AppDelegate.m` file add the following:
```js
#import <RNFSBackgroundDownloads.h>
...
- (void)application:(UIApplication *)application
handleEventsForBackgroundURLSession:(NSString *)identifier
completionHandler:(void (^)())completionHandler
{
[RNFSBackgroundDownloads
setCompletionHandlerForIdentifier:identifier
completionHandler:completionHandler];
}
```
The `handleEventsForBackgroundURLSession` method is called when a background download is done and your app is not in the foreground.
We need to pass the `completionHandler` to RNFS along with its `identifier`.
The JavaScript will continue to work as usual when the download is done but now you must call `RNFS.completeHandlerIOS(jobId)` when you're done handling the download (show a notification etc.)
**BE AWARE!** iOS will give about 30 sec. to run your code after `handleEventsForBackgroundURLSession` is called and until `completionHandler`
is triggered so don't do anything that might take a long time (like unzipping), you will be able to do it after the user re-launces the app,
otherwide iOS will terminate your app.
## Examples
[Examples]: #examples
_These are legacy examples, and should be revised, there is an Example app in the `/example` folder of the codebase, you probably should rather check it than these examples._
### Basic
```javascript
// require the module
var RNFS = require('react-native-fs');
// get a list of files and directories in the main bundle
RNFS.readDir(RNFS.MainBundlePath) // On Android, use "RNFS.DocumentDirectoryPath" (MainBundlePath is not defined)
.then((result) => {
console.log('GOT RESULT', result);
// stat the first file
return Promise.all([RNFS.stat(result[0].path), result[0].path]);
})
.then((statResult) => {
if (statResult[0].isFile()) {
// if we have a file, read it
return RNFS.readFile(statResult[1], 'utf8');
}
return 'no file';
})
.then((contents) => {
// log the file contents
console.log(contents);
})
.catch((err) => {
console.log(err.message, err.code);
});
```
### File creation
```javascript
// require the module
var RNFS = require('react-native-fs');
// create a path you want to write to
// :warning: on iOS, you cannot write into `RNFS.MainBundlePath`,
// but `RNFS.DocumentDirectoryPath` exists on both platforms and is writable
var path = RNFS.DocumentDirectoryPath + '/test.txt';
// write the file
RNFS.writeFile(path, 'Lorem ipsum dolor sit amet', 'utf8')
.then((success) => {
console.log('FILE WRITTEN!');
})
.catch((err) => {
console.log(err.message);
});
```
### File deletion
```javascript
// create a path you want to delete
var path = RNFS.DocumentDirectoryPath + '/test.txt';
return RNFS.unlink(path)
.then(() => {
console.log('FILE DELETED');
})
// `unlink` will throw an error, if the item to unlink does not exist
.catch((err) => {
console.log(err.message);
});
```
### File upload (Android and IOS only)
```javascript
// require the module
var RNFS = require('react-native-fs');
var uploadUrl = 'http://requestb.in/XXXXXXX'; // For testing purposes, go to http://requestb.in/ and create your own link
// create an array of objects of the files you want to upload
var files = [
{
name: 'test1',
filename: 'test1.w4a',
filepath: RNFS.DocumentDirectoryPath + '/test1.w4a',
filetype: 'audio/x-m4a'
}, {
name: 'test2',
filename: 'test2.w4a',
filepath: RNFS.DocumentDirectoryPath + '/test2.w4a',
filetype: 'audio/x-m4a'
}
];
var upload
= (response) => {
var jobId = response.jobId;
console.log('UPLOAD HAS BEGUN! JobId: ' + jobId);
};
var uploadProgress = (response) => {
var percentage = Math.floor((response.totalBytesSent/response.totalBytesExpectedToSend) * 100);
console.log('UPLOAD IS ' + percentage + '% DONE!');
};
// upload files
RNFS.uploadFiles({
toUrl: uploadUrl,
files: files,
method: 'POST',
headers: {
'Accept': 'application/json',
},
fields: {
'hello': 'world',
},
begin: uploadBegin,
progress: uploadProgress
}).promise.then((response) => {
if (response.statusCode == 200) {
console.log('FILES UPLOADED!'); // response.statusCode, response.headers, response.body
} else {
console.log('SERVER ERROR');
}
})
.catch((err) => {
if(err.description === "cancelled") {
// cancelled by user
}
console.log(err);
});
```
## API Reference
[API Reference]: #api-reference
## Constants
[Constants]: #constants
### CachesDirectoryPath
[CachesDirectoryPath]: #cachesdirectorypath
```ts
const CachesDirectoryPath: string;
```
**VERIFIED:** Android, iOS, macOS, Windows.
The absolute path to the caches directory.
### DocumentDirectoryPath
[DocumentDirectoryPath]: #documentdirectorypath
```ts
const DocumentDirectoryPath: string;
```
**VERIFIED:** Android, iOS, macOS, Windows.
The absolute path to the document directory.
**IMPORTANT**: `DocumentDirectoryPath` (iOS) will include an ID in the path that changes each build e.g `...Application/BCE32988-4C51-483B-892B-16671E3771C2/Documents`.
Use relative paths and resolve the full path at runtime to avoid files not being found on new builds.
### DownloadDirectoryPath
[DownloadDirectoryPath]: #downloaddirectorypath
```ts
const DownloadDirectoryPath: string;
```
**VERIFIED:** Android, Windows. **NOT SUPPORTED:** iOS, macOS.
The absolute path to the download directory (on android and Windows only).
### ExternalCachesDirectoryPath
[ExternalCachesDirectoryPath]: #externalcachesdirectorypath
```ts
const ExternalCachesDirectoryPath: string;
```
**VERIFIED:** Android, Windows (empty?). **NOT SUPPORTED:** iOS, macOS.
The absolute path to the external caches directory (android only).
### ExternalDirectoryPath
[ExternalDirectoryPath]: #externaldirectorypath
```ts
const ExternalDirectoryPath: string;
```
**VERIFIED:** Android, iOS (empty?), macOS (empty?), Windows.
The absolute path to the external files, shared directory (android only).
### ExternalStorageDirectoryPath
[ExternalStorageDirectoryPath]: #externalstoragedirectorypath
```ts
const ExternalStorageDirectoryPath: string;
```
**VERIFIED:** Android, iOS (empty?), macOS (empty?), Windows (empty?).
The absolute path to the external storage, shared directory (android only).
**BEWARE:** When using `ExternalStorageDirectoryPath` it's necessary to request permissions (on Android) to read and write on the external storage, here an example: [React Native Offical Doc](https://facebook.github.io/react-native/docs/permissionsandroid)
### LibraryDirectoryPath
[LibraryDirectoryPath]: #librarydirectorypath
```ts
const LibraryDirectoryPath: string;
```
**VERIFIED:** iOS, macOS, Windows (empty?). **NOT SUPPORTED:** Android.
The absolute path to the NSLibraryDirectory (iOS only).
### MainBundlePath
[MainBundlePath]: #mainbundlepath
```ts
const MainBundlePath: string;
```
**VERIFIED:** iOS, macOS, Windows. **NOT SUPPORTED:** Android.
The absolute path to the main bundle directory (not available on Android).
### PicturesDirectoryPath
[PicturesDirectoryPath]: #picturesdirectorypath
```ts
const PicturesDirectoryPath: string;
```
**VERIFIED:** Android, Windows. **NOT SUPPORTED:** iOS, macOS.
The absolute path to the pictures directory.
### RoamingDirectoryPath
[RoamingDirectoryPath]: #roamingdirectorypath
```ts
const RoamingDirectoryPath: string;
```
**VERIFIED:** Windows. **NOT SUPPORTED:** Android, iOS, macOS.
The absolute path to the roaming directory (Windows only).
### TemporaryDirectoryPath
[TemporaryDirectoryPath]: #temporarydirectorypath
```ts
const TemporaryDirectoryPath: string;
```
**VERIFIED**: Android, iOS, macOS, Windows.
The absolute path to the temporary directory (falls back to Caching-Directory on
Android).
**BEWARE:** The trailing slash might be inconsistent in this path! At the very
least, on Android this constant does not have a slash in the end; but on iOS
(new arch) it has it. It is something to unify in future.
## Functions
[Functions]: #functions
### appendFile()
[appendFile()]: #appendfile
```ts
function appendFile(filepath: string, contents: string, encoding?: string): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Appends content to a file.
- `filepath` — **string** — File path.
- `contents` — **string** — The content to add.
- `encoding` — [EncodingT] — Optional. Encoding.
- Resolves once the operation has been completed.
### completeHandlerIOS()
[completeHandlerIOS()]: #completehandlerios
```ts
function completeHandlerIOS(jobId: number): void;
```
**VERIFIED:** well... not really verified, but is callable on iOS.
iOS only. For use when using background downloads, tell iOS you are done
handling a completed download.
Read more about background downloads in the [Background Downloads Tutorial (iOS)](#background-downloads-tutorial-ios) section.
### copyAssetsFileIOS()
[copyAssetsFileIOS()]: #copyassetsfileios
```ts
function copyAssetsFileIOS(
imageUri: string,
destPath: string,
width: number,
height: number,
scale?: number,
compression?: number,
resizeMode?: string,
): Promise<string>;
```
**BEWARE:** _After ensuring this method gets called correctly on iOS, calling it
just crashes the example app for me. Though, I don't have much interest to dig into
it now (not for free :)_
iOS only.
*Not available on Mac Catalyst.*
Reads an image file from Camera Roll and writes to `destPath`. This method
[assumes the image file to be JPEG file](https://github.com/itinance/react-native-fs/blob/f2f8f4a058cd9acfbcac3b8cf1e08fa1e9b09786/RNFSManager.m#L752-L753).
This method will download the original from iCloud if necessary.
One can use this method also to create a thumbNail from a video in a specific
size. Currently it is impossible to specify a concrete position, the OS will
decide which Thumbnail you'll get then.
To copy a video from assets-library and save it as a mp4-file, refer to
copyAssetsVideoIOS.
Further information: https://developer.apple.com/reference/photos/phimagemanager/1616964-requestimageforasset
The promise will on success return the final destination of the file, as it was defined in the destPath-parameter.
- `imageUri` — **string** — URI of a file in Camera Roll.
Can be [either of the following formats](https://github.com/itinance/react-native-fs/blob/f2f8f4a058cd9acfbcac3b8cf1e08fa1e9b09786/RNFSManager.m#L781-L785):
- `ph://CC95F08C-88C3-4012-9D6D-64A413D254B3/L0/001`
- `assets-library://asset/asset.JPG?id=CC95F08C-88C3-4012-9D6D-64A413D254B3&ext=JPG`
- `destPath` — **string** — Destination to which the copied file
will be saved, e.g. `RNFS.TemporaryDirectoryPath + 'example.jpg'`.
- `width` — **number** — Copied file's image width will be resized
to `width`. [If 0 is provided, width won't be resized.](https://github.com/itinance/react-native-fs/blob/f2f8f4a058cd9acfbcac3b8cf1e08fa1e9b09786/RNFSManager.m#L808)
- `height` — **number** — Copied file's image height will be resized
to `height`. [If 0 is provided, height won't be resized.](https://github.com/itinance/react-native-fs/blob/f2f8f4a058cd9acfbcac3b8cf1e08fa1e9b09786/RNFSManager.m#L808)
- `scale` — **number** | **undefined** — Optional. Copied file's
image will be scaled proportional to `scale` factor from `width` x `height`.
If both `width` and `height` are 0, the image won't scale. Range is [0.0, 1.0]
and default is 1.0.
- `compression` — **number** | **undefined** — Optional. Quality of
copied file's image. The value 0.0 represents the maximum compression
(or lowest quality) while the value 1.0 represents the least compression
(or best quality). Range is [0.0, 1.0] and default is 1.0.
- `resizeMode` — **string** | **undefined** — Optional.
If `resizeMode` is 'contain', copied file's image will be scaled so that its
larger dimension fits `width` x `height`. If `resizeMode` is other value than
'contain', the image will be scaled so that it completely fills
`width` x `height`. Default is 'contain'.
Refer to [PHImageContentMode](https://developer.apple.com/documentation/photokit/phimagecontentmode).
- Resolves to **string** — Copied file's URI.
### copyAssetsVideoIOS()
[copyAssetsVideoIOS()]: #copyassetsvideoios
```ts
function copyAssetsVideoIOS(videoUri: string, destPath: string): Promise<string>;
```
**BEWARE:** _Similarly to [copyAssetsFileIOS()] I believe it gets correctly called
on iOS, but it crashes the example app in my naive test. Perhaps I use it wrong,
or something should be patched in the original implementation._
*Not available on Mac Catalyst.*
Copies a video from assets-library, that is prefixed with
'assets-library://asset/asset.MOV?...' to a specific destination.
- `videoUri` — **string** — Video URI.
- `destPath` — **string** — Destination.
- Resolves to **string** — copied file path?
### copyFile()
[copyFile()]: #copyfile
```ts
function copyFile(from: string, into: string, options?: FileOptionsT): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Copies a file to a new destination. Throws if called on a directory.
**Note:** On Android and Windows [copyFile()] will overwrite `destPath` if it
already exists. On iOS an error will be thrown if the file already exists.
— **beware**, this has not been verified yet.
**BEWARE:** On Android [copyFile()] throws if called on a folder; on other
platforms it does not throw, but it has not been verified yet, if it actually
copies a folder with all its content there.
- `from` — **string** — Source path.
- `into` — **string** — Destination path.
- `options` — [FileOptionsT] | **undefined** — Optional. Additional
settings. **beware**, it has not been verified they work, yet.
- Resolves once done.
### copyFileAssets()
[copyFileAssets()]: #copyfileassets
```ts
function copyFileAssets(from: string, into: string): Promise<void>
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Copies Android app's asset(s) to the specified destination.
If `from` points to a file, this function assumes `into` is a file path as well,
and it copies the asset to that destination, overwriting the existing file at
that destination, if any.
If `from` points to a folder, this function assumes `into` is a folder path
as well, and it recursively copies the content of `from` into that destination,
preserving the folder structure of copied assets, and overwriting existing files
in the destination in case of conflicts. It does not clean the destination prior
to copying into it, and it cannot overwrite files by folders and vice-versa.
If `into` does not exist, it will be created, assuming its parent folder
does exist (_i.e._ it does not attempt to create entire path as [mkdir()] does).
- `from` — **string** — Source path, relative to the root assets
folder. Can be empty to refer the root assets folder itself.
- `into` — **string** — Destination path.
- Resolves once completed.
### copyFileRes()
[copyFileRes()]: #copyfileres
```ts
function copyFileRes(filename: string, destPath: string): Promise<void>
```
**VERIFIED**: Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Copies the file named `filename` in the Android app's res folder
and copies it to the given `destPath` path. `res/drawable` is used as
the source parent folder for image files, `res/raw` for everything else.
**BEWARE:** It will overwrite destPath if it already exists.
- `filename` — **string** — Resource name.
- `destPath` — **string** — Destination.
- Resolves once completed.
### copyFolder()
[copyFolder()]: #copyfolder
```ts
copyFolder(from: string, into: string): Promise<void>;
```
**VERIFIED**: Windows **NOT SUPPORTED**: Android, iOS, macOS
Windows only. Copies content to a new location in a Windows-efficient way,
compared to [copyFile()].
- `from` — **string** — Source location.
- `into` — **string** — Destination location.
### downloadFile()
[downloadFile()]: #downloadfile
```ts
function downloadFile(options: DownloadFileOptionsT): {
jobId: number;
promise: Promise<DownloadResultT>;
};
```
**VERIFIED:** Android, iOS, macOS, Windows \
**BEWARE:** Only basic functionality has been verified.
Downloads a file from `options.fromUrl` to `options.toFile`. It Will overwrite
any previously existing file.
- `options` — [DownloadFileOptionsT] — Download settings.
- Returns an object holding `jobId` **number** (can be used to manage in-progress
download by corresponding functions) and `promise` resolving to [DownloadResultT]
once the download is completed.
### exists()
[exists()]: #exists
```ts
function exists(path: string): Promise<boolean>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Checks if an item exists at the given `path`.
- `path` — **string** — Path.
- Resolves to _true_ if the item exists; to _false_ otherwise.
### existsAssets()
[existsAssets()]: #existsassets
```ts
function existsAssets(path: string): Promise<boolean>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Checks if an item exists at the given path in the Android assets
folder.
- `path` — **string** — Path, relative to the root of the Android
assets folder.
- Resolves _true_ if the item exists; _false_ otherwise.
### existsRes()
[existsRes()]: #existsres
```ts
function existsRes(filename: string): Promise<boolean>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Check if the specified resource exists.
`res/drawable` is used as the parent folder for image files,
`res/raw` for everything else.
- `filename` — **string** — Resource name.
- Resolves to **boolean** — _true_ if the resource exists;
_false_ otherwise.
### getAllExternalFilesDirs()
[getAllExternalFilesDirs()]: #getallexternalfilesdirs
```ts
function getAllExternalFilesDirs(): Promise<string[]>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Returns an array with the absolute paths to application-specific
directories on all shared/external storage devices where the application can
place persistent files it owns.
- Resolves to **string[]** — the array of external paths.
### getFSInfo()
[getFSInfo()]: #getfsinfo
```ts
function getFSInfo(): Promise<FSInfoResultT>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Provides information about free and total file system space.
- Resolves to an [FSInfoResultT] object.
### hash()
[hash()]: #hash
```ts
function hash(path: string, algorithm: string): Promise<string>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Calculates file's hash.
- `path` — **string** — File path.
- `algorithm` — **string** — One of `md5`, `sha1`,
`sha224` (**currently it does not work on Windows!**),
`sha256`, `sha384`, `sha512`.
- Resolves to **string** — file hash.
### isResumable()
[isResumable()]: #isresumable
```ts
function isResumable(jobId: number): Promise<bool>;
```
iOS only. Check if the the download job with this ID is resumable with
[resumeDownload()].
Example:
```js
if (await RNFS.isResumable(jobId) {
RNFS.resumeDownload(jobId)
}
```
- `jobId` — **number** — Download job ID.
- Resolves to **boolean** — the result.
### mkdir()
[mkdir()]: #mkdir
```ts
function mkdir(path: string, options?: MkdirOptionsT): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Creates folder(s) at `path`, and does not throw if already exists (similar to
`mkdir -p` in Linux).
- `path` — **string** — Path to create.
- `options` — **[MkdirOptionsT]** | **undefined** — Optional.
Additional parameters.
- Resolves once completed.
### moveFile()
[moveFile()]: #movefile
```ts
function moveFile(from: string, into: string): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Moves an item (a file, or a folder with files) to a new location. This is more
performant than reading and then re-writing the file data because the move
is done natively and the data doesn't have to be copied or cross the bridge.
**Note:** Overwrites existing file in Windows — To be verified, how does
it behave on other systems, and whether it really overwrites items on Windows?
**BEWARE:** On Windows it currently does not allow moving folders with files,
on other platforms it works fine.
- `from` — **string** — Old path of the item.
- `into` — **string** — New path of the item.
- Resolves once the operation is completed.
### pathForGroup()
[pathForGroup()]: #pathforgroup
```ts
function pathForGroup(groupIdentifier: string): Promise<string>;
```
**VERIFIED:** iOS.
iOS only. Returns the absolute path to the directory shared for all applications
with the same security group identifier. This directory can be used to to share
files between application of the same developer.
Invalid group identifier will cause a rejection.
For more information read the [Adding an App to an App Group](https://developer.apple.com/library/content/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW19) section.
- `groupIdentifier` — **string** — Any value from
the *com.apple.security.application-groups* entitlements list.
- Resolves to **string** — the result path.
### pickFile()
[pickFile()]: #pickfile
```ts
function pickFile(options?: PickFileOptionsT): Promise<string[]>;
```
**SUPPORTED**: Android, iOS, macOS. **NOT YET SUPPORTED**: Windows.
Prompts the user to select file(s) using a platform-provided file picker UI,
which also allows to access files outside the app sandbox.
**BEWARE:** On **macOS (Catalyst)** for this function to work you MUST go to
_Signing & Capabilities_ settings of your project, and inside its _App Sandbox_
section to set _File Access_ > _User Selected Files_ to _Read/Write_ value
(with just _Read_ the file picker on **macOS** opens and seemingly works,
but rather than returning the picked up URL, it signals the operation has been
cancelled).
If it is left at the default _None_ value the call to [pickFile()] will
crash the app.
- `options` — [PickFileOptionsT] — Optional parameters. By default,
this function allows user to select a single file of any kind.
- Resolves to a **string** array — URIs (paths) of user-selected files,
allowing a direct access to them with other methods in this library
(_e.g._ [readFile()]), even if the file is outside the app sandbox.
**NOTE:** On **iOS** & **macOS** it resolve to special values with the format
«`bookmark://<BASE64_ENCODED_STRING>`», rather than normal URIs.
It is necessary for the support of security scopes
(see [Bookmarks and Security Scopes](https://developer.apple.com/documentation/foundation/nsurl#1663783)) in library methods. The «`<BASE64_ENCODED_STRING>`»
in this case is a Base64-encoded binary representation of the URL bookmark,
along with its security scope data. Other methods of the library are expected
to automatically handle such special URIs as needed.
**BEWARE:** It has not been thoroughly verified yet that all library methods
support these «Bookmark URLs» correctly. The expected error in
such case is a failure to access the URLs as non-existing.
### read()
[read()]: #read
```ts
function read(path: string, length = 0, position = 0, encodingOrOptions?: EncodingT | ReadFileOptionsT): Promise<string>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Reads `length` bytes from the given `position` of a file.
**BEWARE:** On Android and Windows [read()] called with zero `length` and `position`
resolves to empty string; however on other platforms it resolves to the entire
file content (same as [readFile()]). This behavior has been inherited from
the legacy RNFS implementation, and is to be corrected in future.
**Note:** To read entire file at once consider to use [readFile()] instead.
**Note:** No matter the encoding, this function will always read the specified
number of bytes from the given position, and then transform that byte chunk
into a string using the given encoding; that is in constrast of, say, reading
the given number of characters, if `utf8` is given.
- `path` — **string** — File path.
- `length` — **number** | **undefined** — Optional. The number of
bytes to read. Defaults 0.
- `position` — **number** | **undefined** — Optional. The starting
read position, in bytes. Defaults 0.
- `encodingOrOptions` — [EncodingT] | [ReadFileOptionsT] | **undefined**
— Optional. The encoding to use, or additional read options (currently,
the encoding is the only option anyway). Defaults `utf8`.
- Resolves to **string** — the content read from file, transformed into
the string according to the specified encoding.
### readdir()
[readdir()]: #readdir-1
```ts
function readdir(path: string): Promise<string[]>;
```
**VERIFIED:** Android, iOS, macOS.
Lists the content of given folder (names only — NodeJS-style). Note the
lowercase `d` in the name, unlike in [readDir()].
**BEWARE:** There is no guarantees about the sort order of resolved listing.
- `path` — **string** — Folder path.
- Resolves to a **string** array — the names of items in the folder.
### readDir()
[readDir()]: #readdir-2
```ts
function readDir(path: string): Promise<ReadDirItem[]>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Lists the content of given absolute path.
**BEWARE:** There is no guarantees about the sort order of resolved listing.
**BEWARE:** On Windows the `isDirectory()` and `isFile()` methods of result
currently return _false_ for all items; also `size` value in the result is
platform dependent for directories.
- `path` — **string** — Path.
- Resolves to an array of [ReadDirResItemT] objects.
### readDirAssets()
[readDirAssets()]: #readdirassets
```ts
function readDirAssets(path: string): Promise<ReadDirItem[]>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
(Android only) Lists the content of a folder at the given `path` inside
the Android assets folder.
- `path` — **string** — Folder path, relative to the root of
the `assets` folder.
- Resolves to an array of [ReadDirAssetsResItemT] objects.
### readFile()
[readFile()]: #readfile
```ts
function readFile(path: string, encodingOrOptions?: EncodingT | ReadFileOptionsT): Promise<string>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Reads the file at `path` and return its content as a string.
**Note:** To read a selected fragment of the file see [read()].
**Note:** For `base64` encoding this function will return file content encoded
into Base64 format; for `ascii` it will fill each character of the result string
with the code of corresponding byte in the file; and for `utf8` (default)
it will assume the source file is UTF8-encoded, and it will decode it into
the result string (thus each result character will be corresponding to a group
of 1-to-4 bytes of the source file).
**BEWARE:** You will take quite a performance hit if you are reading big files.
- `path` — **string** — File path.
- `encoding` — [EncodingT] | [ReadFileOptionsT] — Optional.
File encoding, or extra options.
- Resolves to **string** — the content read from the file, and transformed
according to the given encoding.
### readFileAssets()
[readFileAssets()]: #readfileassets
```ts
function readFileAssets(path: string, encoding?: EncodingT | ReadFileOptionsT): Promise<string>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Reads the file at `path` in the Android app's assets folder
and return its contents. `encoding` can be one of `utf8` (default), `ascii`,
`base64`. Use `base64` for reading binary files.
- `path` — **string** — Asset path.
- `encoding` — [EncodingT] | [ReadFileOptionsT] | **undefined** —
Optional. Encoding, or extra options object, which currently only supports
specifying the encoding.
- Resolves to **string** — the asset content.
### readFileRes
[readFileRes()]: #readfileres
```ts
function readFileRes(filename: string, encoding?: EncodingT): Promise<string>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Reads the file named `filename` in the Android app's `res` folder
and return contents. Only the file name (not folder) needs to be specified.
Original docs say: _The file type will be detected from the extension and
automatically located within `res/drawable` (for image files) or `res/raw`
(for everything else)._ Good luck with it. The test in the example app does not
work if the file extension is not included into the filename... but perhaps
I've overlooked something.
- `filename` — **string** — Resouce file name.
- `encoding` — [EncodingT] — Optional Encdoing.
- Resolves to **string** — the resource content.
### resumeDownload()
[resumeDownload()]: #resumedownload
```ts
function resumeDownload(jobId: number): void;
```
iOS only. Resume the current download job with this ID.
- `jobId` — **number** — Download job ID.
### scanFile()
[scanFile()]: #scanfile
```ts
function scanFile(path: string): Promise<string | null>;
```
**VERIFIED:** Android. **NOT SUPPORTED:** iOS, macOS, Windows.
Android-only. Scan the file using
[Media Scanner](https://developer.android.com/reference/android/media/MediaScannerConnection).
- `path` — **string** — Path of the file to scan.
- Resolve to **string** or **null** — URI of for the file if the scanning
operation succeeded and the file was added to the media database; or _null_
if scanning failed.
### stat()
[stat()]: #stat
```ts
function stat(path: string): Promise<StatResultT>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Stats an item at `path`. If the `path` is linked to a virtual file, for example
Android Content URI, the `originalPath` can be used to find the pointed file
path (**beware** — this has not been verified yet).
**BEWARE:** On Windows a bunch of stuff in the response is currently not compatible
with the specs — `size` is a string rather than number, `isDirectory()` and `isFile()`
do not work (always return _false_), _etc_. Also on Windows, even with those defects
accounted for the test for this function tends to randomly fail on a regular basis.
It thus requires more troubleshooting, but it is not a priority for now.
- `path` — **string** — Item path.
- Resolves to a [StatResultT] object.
### stopDownload()
[stopDownload()]: #stopdownload
```ts
function stopDownload(jobId: number): void;
```
**VERIFIED:** Android, iOS.
Aborts a file download job. The partial file will remain on the filesystem,
and the promise returned from the aborted [downloadFile()] call will reject
with an error.
- `jobId` — **number** — Download job ID (see [downloadFile()]).
### stopUpload()
[stopUpload()]: #stopupload
```ts
function stopUpload(jobId: number): void;
```
**VERIFIED:** iOS.
iOS only. Abort the current upload job with given ID.
**NOTE:** Unlike [stopDownload()] it does not cause the pending upload promise
to reject. Perhaps, we'll change it in future to behave similarly.
- `jobId` — **number** — Upload job ID.
### touch()
[touch()]: #touch
```ts
function touch(filepath: string, mtime?: Date, ctime?: Date): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Alters creation and modification timestamps of the given file.
- `filepath` — **string** — File path.
- `mtime` — **Date** | **undefined** — Optional. Modification
timestamp.
- `ctime` — **Date** | **undefined** — Optional. Creation timestamp.
It is supported on iOS and Windows; Android always sets both timestamps equal
`mtime`.
- Resolves once done.
### unlink()
[unlink()]: #unlink
```ts
function unlink(path: string): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows.
Unlinks (removes) the item at `path`. If the item does not exist, an error will
be thrown. Also recursively deletes directories (works like Linux `rm -rf`).
- `path` — **string** — Item path.
- Resolves once done.
### uploadFiles()
[uploadFiles()]: #uploadfiles
```ts
function uploadFiles(options: UploadFileOptionsT): {
jobId: number;
promise: Promise<UploadResultT>;
}
```
**VERIFIED**: Android, iOS, macOS, Windows
Uploads files to a remote location.
**BEWARE**: Only the most basic upload functionality has been tested so far
in this library fork.
- `options` — [UploadFileOptionsT] — Upload settings.
- Returns an object holding `jobId` **number** (can be used to manage
in-progress download by corresponding functions) and `promise` resolving
to [UploadResultT] once the download is completed.
### write()
[write()]: #write
```ts
function write(filepath: string, contents: string, position?: number, encoding?: EncodingT): Promise<void>;
```
**VERIFIED:** Android, iOS, macOS, Windows \
**BEWARE:** On Windows it seems to work differently from other platforms,
throwing if attempting to write to a non-existing file.
Writes content to a file at the given random access position.
- `filepath` — **string** — File path.
- `contents` — **string** — Content to write.
- `position` — **number** | **undefined** — Write position.
If `undefined` or `-1` the contents is appended to the end of the file.
- `encoding` — [EncodingT] — Write encoding.
- Resolves once the operation has been completed.
### writeFile()
[writeFile()]: #writefile
```ts
function writeFile(path: string, content: string, encodingOrOptions?: EncodingT | WriteFileOptionsT): Promise<void>
```
**VERIFIED:** Android, iOS, macOS, Windows.
Write the `content` to the file at `path`, overwritting it if exists already.
**NOTE:** With `base64` encoding value this function will assume that given
`content` is Base64-encoded already, and it will be decoded into the file;
for `ascii` encoding each character of `content` will be written to one byte
in the file, and the function will fail if any character is outside
the U+0000 to U+00FF range (keep in mind, that regular JS strings have
two-byte characters); and for `utf8` encoding (default) it will encode
`content` characters (which can be from U+0000 to U+FFFF in this case)
into the corresponding UTF8 code (_i.e._ each source character will be
turned into a group of 1-to-4 bytes in the written file).
- `path` — **string** — File path.
- `content` — **string** — Data to write into the file.
- `encodingOrOptions` — [EncodingT] | [WriteFileOptionsT] — Data
encoding, or extra options.
- Resolves once completed.
## Types
[Types]: #types
### DownloadBeginCallbackResultT
[DownloadBeginCallbackResultT]: #downloadbegincallbackresultt
```ts
type DownloadBeginCallbackResultT = {
jobId: number;
statusCode: number;
contentLength: number;
headers: Headers;
};
```
The type of argument passed to `begin` callback in [DownloadFileOptionsT].
- `jobId` — **number** — The download job ID, required if one wishes
to cancel the download. See [stopDownload()].
- `statusCode` — **number** — The HTTP status code.
- `contentLength` — **number** — The total size in bytes of
the download resource.
- `headers` — [StringMapT] — The HTTP response headers from
the server.
### DownloadFileOptionsT
[DownloadFileOptionsT]: #downloadfileoptionst
```ts
type DownloadFileOptions = {
fromUrl: string;
toFile: string;
headers?: StringMapT;
background?: boolean;
discretionary?: boolean;
cacheable?: boolean;
progressInterval?: number;
progressDivider?: number;
begin?: (res: DownloadBeginCallbackResultT) => void;
progress?: (res: DownloadProgressCallbackResultT) => void;
resumable?: () => void;
connectionTimeout?: number;
readTimeout?: number;
backgroundTimeout?: number;
};
```
The type of options argument of [downloadFile()].
- `fromUrl` — **string** — URL to download file from.
- `toFile` — **string** — Local filesystem path to save the file to.
- `headers` — [StringMapT] — Optional. An object of headers to be
passed to the server.
- `background` — **boolean** — Optional. Continue the download in
the background after the app terminates (iOS only).
See [Background Downloads Tutorial (iOS)](#background-downloads-tutorial-ios).
Defaults _false_.
- `discretionary` — **boolean** — Optional. Allow the OS to control
the timing and speed of the download to improve perceived performance. This setting may prevent downloading with mobile internet or when the battery is low. Only works when `background` is activated
(iOS only, defaults to _false_).
- `cacheable` — **boolean** — Optional. Whether the download can be
stored in the shared NSURLCache (iOS only, defaults to _true_).
- `progressInterval` — **number** Optional. If provided, the download
progress events will be emitted with the maximum frequency of `progressInterval`.
For example, if `progressInterval` = 100, you will not receive callbacks more
often than every 100th millisecond.
- `progressDivider` — **number** Optional. If provided, the download
progress events are emitted at `progressDivider` number of steps.
For example, if `progressDivider` = 10, you will receive only ten callbacks
for this values of progress: 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100.
Use it for performance issues.
If `progressDivider` = 0, you will receive all `progressCallback` calls,
default value is 0.
- `begin` — **(res: [DownloadBeginCallbackResultT]) => void** —
Optional; required if `progress` prop provided. If provided, it is invoked
when download starts, once headers have been received, and it is passed
a single argument of [DownloadBeginCallbackResultT] type.
- `progress` — **(res: [DownloadProgressCallbackResultT]) => void** —
Optional. If provided, it is being invoked continuously and passed in a single
argument of [DownloadProgressCallbackResultT] type.
- `resumable` — **() => void** — Optional. iOS-only. If provided,
it is invoked when the download has stopped