React Native File Gateway

A React Native library making file access easier for developers as first class citizens, without the tears.

⚠️ NOTE: This library is in early development, focusing primarily on Android. ⚠️

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 the encoding key, and the data within the payload 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.
Collection ("audio" | "image" | "video" | "download")
- The collection is to indicate where the file will be stored (ONLY APPLICABLE FOR persistent intentions). Fallsback to download if not specified.

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 following
- size (in bytes)
- mime (e.g application/javascript)
- extension (e.g mp3)
- nameWithoutExtension (e.g bigBuckBunny)
- lastModified (e.g 2021-05-19T21:10:48.197Z- ISO UTC format)
- creationTime (e.g 2021-05-19T21:10:48.197Z- ISO UTC format)
- lastAccessedTime (e.g 2021-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 as true 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