react-native-file-gateway v1.5.1
React Native File Gateway
A React Native library making file access easier for developers as first class citizens, without the tears.
:warning: NOTE: This library is in early development, focusing primarily on Android. :warning:
About
This library is focused around making the developer's life simpler when it comes to interacting with the native file system for React Native. This library has 3 main goals:
- Being simple, and easy to understand
* This may mean some things are abstracted/opinionated (see
writeFile()
as one example of this) - Being performant * Handling large/many files is a must. Any file interopability is always handled at the native level
- Being well tested * Where tests are needed, they will be there. Native or at the JS level, a test will accompany said code
Supported platforms
- Android (In development)
Upcoming platforms
- iOS
- Windows
- MacOS
Roadmap
- File system interoperability (In progress)
- Downloading/uploading files
- Cryptography
- Unit/integration/E2E testing (TO:DO)
Installation
npm install react-native-file-gateway
Usage
import FileGateway from "react-native-file-gateway";
// Scenario 1: Writing an MP4 file to the secure application store.
// This file will be deleted on uninstall.
const path = await FileGateway.writeFile(
"bigBuckBunny.mp4", // Name of the file
"010101", // Data to be written as a string (UTF-8 encoding is default)
"application" // Intention of the file's lifetime. Can be application, ephemeral, or persistent (see more in documentation below)
)
// Scenario 2: Writing an image file to the cache.
// This file will be deleted on uninstall.
const path = await FileGateway.writeFile(
"bigBuckBunny.mp4",
"010101",
"ephemeral" // Ephemeral will store this file into the system's cache
)
// Scenario 3: Writing an image file to the cache using base64 encoding.
const path = await FileGateway.writeFile(
"bigBuckBunny.mp4",
{
data: "010101",
encoding: "base64" // Specifying this will encode the written file as base64 (UTF-8 as the charset)
},
"ephemeral"
)
Functions
writeFile(fileName: string, data: string | DataWithEncoding, intention: Intention, collection?: Collection): Promise<string>
- Writes to a file and returns it's path as a Promise<string>
- DataWithEncoding - explicitly define the encoding
("utf-8", "utf-16", "utf-32", "base64")
within theencoding
key, and the data within thepayload
key -{ data: string; encoding: Encoding }
- Intention: Intention
("application" | "ephemeral" | "persistent")
- The intention is to indicate how the file will be stored.
-
application
intention will allocate the file into the application's own storage, but other applications won't be able to access it. The file will be lost on uninstall. -ephemeral
intention will allocate the file into the cache storage. The file will be lost on uninstall -persistent
intention will allocate the file into external storage. The file will persist on uninstall. Useful for media content.
- The intention is to indicate how the file will be stored.
-
- Collection
("audio" | "image" | "video" | "download")
- The collection is to indicate where the file will be stored (ONLY APPLICABLE FOR
persistent
intentions). Fallsback todownload
if not specified.
- The collection is to indicate where the file will be stored (ONLY APPLICABLE FOR
readFile(path: string, encoding?: Encoding): Promise<string>
- Reads a given file, given it's path and returns the data as a Promise<string>
- Encoding
("utf-8", "utf-16", "utf-32", "base64")
* Sets the encoding when reading the file
deleteFile(path: string): Promise<string>
- Deletes a file, given it's path and returns the path if successful as a Promise<string>
status(path: string): Promise<RawStatus>
- Returns back the Promise<RawStatus>
of a file, given it's path
RawStatus
includes the followingsize
(in bytes)mime
(e.gapplication/javascript
)extension
(e.gmp3
)nameWithoutExtension
(e.gbigBuckBunny
)lastModified
(e.g2021-05-19T21:10:48.197Z
- ISO UTC format)creationTime
(e.g2021-05-19T21:10:48.197Z
- ISO UTC format)lastAccessedTime
(e.g2021-05-19T21:10:48.197Z
- ISO UTC format)
listFiles(path: string, recursive?: boolean): Promise<string[]>
- List all the files, given it's path and returns all the file names as a Promise<string[]>
- Specifying
recursive
astrue
will recursively search through every directory for the given path
exists(path: string): Promise<boolean>
- Checks if a file or directory exists. Returns true
or false
if a file exists, or doesn't, respectively as a Promise<boolean>
isDirectory(path: string): Promise<boolean>
- Checks if the given path is a directory exists. Returns true
or false
if it's a directory, or not, respectively as a Promise<boolean>
moveDirectory(path: string, targetPath: string): Promise<string>
- Moves a directory from the path
to the targetPath
(the destination). Any files at the destination will be overridden by default. Returns back the targetPath
as a Promise<string>
deleteDirectory(path: string): Promise<string>
- Deletes a directory, given it's path and returns the path if successful as a Promise<string>
Contributing
See the contributing guide to learn how to contribute to the repository and the development workflow.
License
MIT