react-native-saf-x

A module to help simplify usage of scoped storages on android.

intended to use when targeting Android API level 30+

Minimum supported API level is 24

Installation

npm install react-native-saf-x

yarn add react-native-saf-x

After receiving a content uri using openDocumentTree function, you can use this as if like it's a normal path like we are used to. This is the intended behaviour, if you find any problems or if something does not behave as intended, please create an issue.

Note that each method can reject when there's an unexpected error or when the permission is revoked.

Example:

import { openDocumentTree, mkdir } from "react-native-saf-x";

// somewhere in the app .....

async function testIt() {
  const doc = await openDocumentTree(true);
  if (doc && doc.uri) {
    // user has selected a directory and uri is available
    // you can save this uri as base directory in your app and reuse it anywhere you want
    await mkdir(doc.uri + '/foo/bar'); // creates foo/bar folder and subfolder at selected directory
  }
}

For more examples look at example folder in the source.

Installation
Usage
Type aliases
Functions
Caveats
Thanks to
Contributing
License

Type aliases

CreateDocumentOptions

Ƭ CreateDocumentOptions: FileOperationOptions & { initialName?: string }

Defined in

index.tsx:90

DocumentFileDetail

Ƭ DocumentFileDetail: Object

Type declaration

Name	Type
`lastModified`	`number`
`mime`	`string`
`name`	`string`
`size`	`number`
`type`	`"directory"` \| `"file"`
`uri`	`string`

Defined in

index.tsx:70

Encoding

Ƭ Encoding: "utf8" | "base64" | "ascii"

Defined in

index.tsx:29

FileOperationOptions

Ƭ FileOperationOptions: Object

Type declaration

Name	Type	Description
`append?`	`boolean`	Append data to the file. If not set file content will be overwritten.
`encoding?`	`Encoding`	Defaults to `'utf8'`
`mimeType?`	`string`	mime type of the file being saved. Defaults to '/'

Defined in

index.tsx:79

OpenDocumentOptions

Ƭ OpenDocumentOptions: Object

Type declaration

Name	Type	Description
`multiple?`	`boolean`	should the file picker allow multiple documents ?
`persist?`	`boolean`	should the permission of returned document(s) be persisted ?

Defined in

index.tsx:103

Variables

default

• default: Object

Type declaration

Name	Type
`copyFile`	(`srcUri`: `string`, `destUri`: `string`, `options?`: `FileTransferOptions`) => `Promise`<`null` \| `DocumentFileDetail`>
`createDocument`	(`data`: `string`, `options?`: `CreateDocumentOptions`) => `Promise`<`null` \| `DocumentFileDetail`>
`createFile`	(`uriString`: `string`, `options?`: `Pick`<`FileOperationOptions`, `"mimeType"`>) => `Promise`<`DocumentFileDetail`>
`exists`	(`uriString`: `string`) => `Promise`<`boolean`>
`getPersistedUriPermissions`	() => `Promise`<`string`[]>
`hasPermission`	(`uriString`: `string`) => `Promise`<`boolean`>
`listFiles`	(`uriString`: `string`) => `Promise`<`DocumentFileDetail`[]>
`mkdir`	(`uriString`: `string`) => `Promise`<`DocumentFileDetail`>
`moveFile`	(`srcUri`: `string`, `destUri`: `string`, `options?`: `FileTransferOptions`) => `Promise`<`null` \| `DocumentFileDetail`>
`openDocument`	(`options`: `OpenDocumentOptions`) => `Promise`<`null` \| `DocumentFileDetail`[]>
`openDocumentTree`	(`persist`: `boolean`) => `Promise`<`null` \| `DocumentFileDetail`>
`readFile`	(`uriString`: `string`, `options?`: `Pick`<`FileOperationOptions`, `"encoding"`>) => `Promise`<`string`>
`releasePersistableUriPermission`	(`uriString`: `string`) => `Promise`<`void`>
`rename`	(`uriString`: `string`, `newName`: `string`) => `Promise`<`DocumentFileDetail`>
`stat`	(`uriString`: `string`) => `Promise`<`DocumentFileDetail`>
`unlink`	(`uriString`: `string`) => `Promise`<`boolean`>
`writeFile`	(`uriString`: `string`, `data`: `string`, `options?`: `FileOperationOptions`) => `Promise`<`void`>

Defined in

index.tsx:259

Functions

copyFile

▸ copyFile(srcUri, destUri, options?): Promise<null | DocumentFileDetail>

Copy file from source uri to destination uri. promise Rejects if destination already exists and replaceIfDestinationExists option is not set to true. Does not support moving directories.

Parameters

Name	Type
`srcUri`	`string`
`destUri`	`string`
`options?`	`FileTransferOptions`

Returns

Promise<null | DocumentFileDetail>

Defined in

index.tsx:234

createDocument

▸ createDocument(data, options?): Promise<null | DocumentFileDetail>

Open the Document Picker to save a file. Returns an object of type DocumentFileDetail or null if user did not select a file.

Parameters

Name	Type
`data`	`string`
`options?`	`CreateDocumentOptions`

Returns

Promise<null | DocumentFileDetail>

Defined in

index.tsx:124

createFile

▸ createFile(uriString, options?): Promise<DocumentFileDetail>

Creates an empty file at given uri. Rejects if a file or directory exist at given uri.

Parameters

Name	Type
`uriString`	`string`
`options?`	`Pick`<`FileOperationOptions`, `"mimeType"`>

Returns

Promise<DocumentFileDetail>

Defined in

index.tsx:169

exists

▸ exists(uriString): Promise<boolean>

Check if there's a document located at the given uri.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<boolean>

Defined in

index.tsx:136

getPersistedUriPermissions

▸ getPersistedUriPermissions(): Promise<string[]>

Returns a list of all the persisted uri permissions.

Returns

Promise<string[]>

Defined in

index.tsx:206

hasPermission

▸ hasPermission(uriString): Promise<boolean>

Check if you have permission to access the uri.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<boolean>

Defined in

index.tsx:131

listFiles

▸ listFiles(uriString): Promise<DocumentFileDetail[]>

List all files and folders in a directory uri.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<DocumentFileDetail[]>

Defined in

index.tsx:216

mkdir

▸ mkdir(uriString): Promise<DocumentFileDetail>

Create a directory at given uri. Automatically creates folders in path if needed. You can use it to create nested directories easily. Rejects if it fails.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<DocumentFileDetail>

Defined in

index.tsx:192

moveFile

▸ moveFile(srcUri, destUri, options?): Promise<null | DocumentFileDetail>

Move file from source uri to destination uri. promise Rejects if destination already exists and replaceIfDestinationExists option is not set to true. Does not support moving directories.

Parameters

Name	Type
`srcUri`	`string`
`destUri`	`string`
`options?`	`FileTransferOptions`

Returns

Promise<null | DocumentFileDetail>

Defined in

index.tsx:249

openDocument

▸ openDocument(options): Promise<null | DocumentFileDetail[]>

Open the Document Picker to select a file. DocumentFileDetail is always an array.

Parameters

Name	Type
`options`	`OpenDocumentOptions`

Returns

Promise<null | DocumentFileDetail[]>

DocumentFileDetail[] or null if user did not select a file.

Defined in

index.tsx:115

openDocumentTree

▸ openDocumentTree(persist): Promise<null | DocumentFileDetail>

Open the Document Picker to select a folder. Read/Write Permission will be granted to the selected folder. Returns an object of type DocumentFileDetail or null if user did not select a folder.

Parameters

Name	Type
`persist`	`boolean`

Returns

Promise<null | DocumentFileDetail>

Defined in

index.tsx:99

readFile

▸ readFile(uriString, options?): Promise<string>

Read contents of the given uri. uri must point to a file.

Parameters

Name	Type
`uriString`	`string`
`options?`	`Pick`<`FileOperationOptions`, `"encoding"`>

Returns

Promise<string>

Defined in

index.tsx:141

releasePersistableUriPermission

▸ releasePersistableUriPermission(uriString): Promise<void>

Remove a uri from persisted uri permissions list.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<void>

Defined in

index.tsx:211

rename

▸ rename(uriString, newName): Promise<DocumentFileDetail>

Renames the document at given uri. uri can be file or folder. Resolves with true if successful and false otherwise.

Parameters

Name	Type
`uriString`	`string`
`newName`	`string`

Returns

Promise<DocumentFileDetail>

Defined in

index.tsx:201

stat

▸ stat(uriString): Promise<DocumentFileDetail>

Get details for a file/directory at given uri.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<DocumentFileDetail>

Defined in

index.tsx:221

unlink

▸ unlink(uriString): Promise<boolean>

Removes the file or directory at given uri. Resolves with true if delete is successful, throws otherwise.

Parameters

Name	Type
`uriString`	`string`

Returns

Promise<boolean>

Defined in

index.tsx:182

writeFile

▸ writeFile(uriString, data, options?): Promise<void>

Writes the given data to the file at given uri. Tries to create the file if does not already exist before writing to it. Resolves with given uriString if successful.

Parameters

Name	Type
`uriString`	`string`
`data`	`string`
`options?`	`FileOperationOptions`

Returns

Promise<void>

Defined in

index.tsx:155

Caveats

Due to simplyifing the uri structure usage, file and directories should not have the same name at a given uri. doing so can cause unexpected results. for example in a folder named "foo", do not create "bar" file and "bar" directory making the uri being "foo/bar" for both cases.

Thanks to

ammarahm-ed for his work on react-native-scoped-storage which helped me jump start this module.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

react-native-saf-x

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads