{"id":20837468,"url":"https://github.com/jd1378/react-native-saf-x","last_synced_at":"2025-07-06T13:40:21.695Z","repository":{"id":57688662,"uuid":"480109479","full_name":"jd1378/react-native-saf-x","owner":"jd1378","description":null,"archived":false,"fork":false,"pushed_at":"2023-10-03T18:22:06.000Z","size":644,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-07T18:01:53.168Z","etag":null,"topics":["android","library","react-native","saf","storage-access-framework","storage-access-helper"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/react-native-saf-x","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jd1378.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-10T18:47:15.000Z","updated_at":"2024-11-01T20:30:43.000Z","dependencies_parsed_at":"2023-09-27T14:24:50.065Z","dependency_job_id":null,"html_url":"https://github.com/jd1378/react-native-saf-x","commit_stats":{"total_commits":71,"total_committers":1,"mean_commits":71.0,"dds":0.0,"last_synced_commit":"d941e8e600653d4b11d55e4144cfea0d3b75ec44"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jd1378%2Freact-native-saf-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jd1378%2Freact-native-saf-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jd1378%2Freact-native-saf-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jd1378%2Freact-native-saf-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jd1378","download_url":"https://codeload.github.com/jd1378/react-native-saf-x/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225110574,"owners_count":17422411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","library","react-native","saf","storage-access-framework","storage-access-helper"],"created_at":"2024-11-18T01:07:38.632Z","updated_at":"2024-11-18T01:07:40.352Z","avatar_url":"https://github.com/jd1378.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-native-saf-x\n\n\u003ca href=\"https://www.npmjs.com/package/react-native-saf-x\" target=\"_blank\"\u003e\n\u003cimg src=\"https://img.shields.io/npm/v/react-native-saf-x?color=green\"/\u003e\n\u003c/a\u003e\n\nA module to help simplify usage of scoped storages on android.\n\nintended to use when targeting Android API level 30+\n\nMinimum supported API level is 24\n\n## Installation\n\n```sh\nnpm install react-native-saf-x\n```\n\nor\n\n```sh\nyarn add react-native-saf-x\n```\n\n## Usage\n\nAfter receiving a content uri using `openDocumentTree` function,\n you can use this as if like it's a normal path like we are used to.\n  This is the intended behaviour,\n   if you find any problems or if something does not behave as intended,\n    please create an issue.\n\nNote that each method can reject when there's an unexpected error or when the permission is revoked.\n\nExample:\n\n```js\nimport { openDocumentTree, mkdir } from \"react-native-saf-x\";\n\n// somewhere in the app .....\n\nasync function testIt() {\n  const doc = await openDocumentTree(true);\n  if (doc \u0026\u0026 doc.uri) {\n    // user has selected a directory and uri is available\n    // you can save this uri as base directory in your app and reuse it anywhere you want\n    await mkdir(doc.uri + '/foo/bar'); // creates foo/bar folder and subfolder at selected directory\n  }\n}\n\n```\n\nFor more examples look at example folder in the source.\n\n## Table of contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Type aliases](#type-aliases)\n- [Functions](#functions)\n- [Caveats](#caveats)\n- [Thanks to](#thanks-to)\n- [Contributing](#contributing)\n- [License](#license)\n\n### Type aliases\n\n- [CreateDocumentOptions](#createdocumentoptions)\n- [DocumentFileDetail](#documentfiledetail)\n- [Encoding](#encoding)\n- [FileOperationOptions](#fileoperationoptions)\n- [OpenDocumentOptions](#opendocumentoptions)\n\n### Variables\n\n- [default](#default)\n\n### Functions\n\n- [copyFile](#copyfile)\n- [createDocument](#createdocument)\n- [createFile](#createfile)\n- [exists](#exists)\n- [getPersistedUriPermissions](#getpersisteduripermissions)\n- [hasPermission](#haspermission)\n- [listFiles](#listfiles)\n- [mkdir](#mkdir)\n- [moveFile](#movefile)\n- [openDocument](#opendocument)\n- [openDocumentTree](#opendocumenttree)\n- [readFile](#readfile)\n- [releasePersistableUriPermission](#releasepersistableuripermission)\n- [rename](#rename)\n- [stat](#stat)\n- [unlink](#unlink)\n- [writeFile](#writefile)\n\n## Type aliases\n\n### CreateDocumentOptions\n\nƬ **CreateDocumentOptions**: [`FileOperationOptions`](#fileoperationoptions) \u0026 { `initialName?`: `string`  }\n\n#### Defined in\n\n[index.tsx:90](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L90)\n\n___\n\n### DocumentFileDetail\n\nƬ **DocumentFileDetail**: `Object`\n\n#### Type declaration\n\n| Name | Type |\n| :------ | :------ |\n| `lastModified` | `number` |\n| `mime` | `string` |\n| `name` | `string` |\n| `size` | `number` |\n| `type` | ``\"directory\"`` \\| ``\"file\"`` |\n| `uri` | `string` |\n\n#### Defined in\n\n[index.tsx:70](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L70)\n\n___\n\n### Encoding\n\nƬ **Encoding**: ``\"utf8\"`` \\| ``\"base64\"`` \\| ``\"ascii\"``\n\n#### Defined in\n\n[index.tsx:29](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L29)\n\n___\n\n### FileOperationOptions\n\nƬ **FileOperationOptions**: `Object`\n\n#### Type declaration\n\n| Name | Type | Description |\n| :------ | :------ | :------ |\n| `append?` | `boolean` | Append data to the file. If not set file content will be overwritten. |\n| `encoding?` | [`Encoding`](#encoding) | Defaults to `'utf8'` |\n| `mimeType?` | `string` | mime type of the file being saved. Defaults to '\\*\\/\\*' |\n\n#### Defined in\n\n[index.tsx:79](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L79)\n\n___\n\n### OpenDocumentOptions\n\nƬ **OpenDocumentOptions**: `Object`\n\n#### Type declaration\n\n| Name | Type | Description |\n| :------ | :------ | :------ |\n| `multiple?` | `boolean` | should the file picker allow multiple documents ? |\n| `persist?` | `boolean` | should the permission of returned document(s) be persisted ? |\n\n#### Defined in\n\n[index.tsx:103](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L103)\n\n## Variables\n\n### default\n\n• **default**: `Object`\n\n#### Type declaration\n\n| Name | Type |\n| :------ | :------ |\n| `copyFile` | (`srcUri`: `string`, `destUri`: `string`, `options?`: `FileTransferOptions`) =\u003e `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `createDocument` | (`data`: `string`, `options?`: [`CreateDocumentOptions`](#createdocumentoptions)) =\u003e `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `createFile` | (`uriString`: `string`, `options?`: `Pick`\u003c[`FileOperationOptions`](#fileoperationoptions), ``\"mimeType\"``\\\u003e) =\u003e `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `exists` | (`uriString`: `string`) =\u003e `Promise`\u003c`boolean`\\\u003e |\n| `getPersistedUriPermissions` | () =\u003e `Promise`\u003c`string`[]\\\u003e |\n| `hasPermission` | (`uriString`: `string`) =\u003e `Promise`\u003c`boolean`\\\u003e |\n| `listFiles` | (`uriString`: `string`) =\u003e `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)[]\\\u003e |\n| `mkdir` | (`uriString`: `string`) =\u003e `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `moveFile` | (`srcUri`: `string`, `destUri`: `string`, `options?`: `FileTransferOptions`) =\u003e `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `openDocument` | (`options`: [`OpenDocumentOptions`](#opendocumentoptions)) =\u003e `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)[]\\\u003e |\n| `openDocumentTree` | (`persist`: `boolean`) =\u003e `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `readFile` | (`uriString`: `string`, `options?`: `Pick`\u003c[`FileOperationOptions`](#fileoperationoptions), ``\"encoding\"``\\\u003e) =\u003e `Promise`\u003c`string`\\\u003e |\n| `releasePersistableUriPermission` | (`uriString`: `string`) =\u003e `Promise`\u003c`void`\\\u003e |\n| `rename` | (`uriString`: `string`, `newName`: `string`) =\u003e `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `stat` | (`uriString`: `string`) =\u003e `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e |\n| `unlink` | (`uriString`: `string`) =\u003e `Promise`\u003c`boolean`\\\u003e |\n| `writeFile` | (`uriString`: `string`, `data`: `string`, `options?`: [`FileOperationOptions`](#fileoperationoptions)) =\u003e `Promise`\u003c`void`\\\u003e |\n\n#### Defined in\n\n[index.tsx:259](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L259)\n\n## Functions\n\n### copyFile\n\n▸ **copyFile**(`srcUri`, `destUri`, `options?`): `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nCopy file from source uri to destination uri.\npromise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.\nDoes not support moving directories.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `srcUri` | `string` |\n| `destUri` | `string` |\n| `options?` | `FileTransferOptions` |\n\n#### Returns\n\n`Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:234](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L234)\n\n___\n\n### createDocument\n\n▸ **createDocument**(`data`, `options?`): `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nOpen the Document Picker to save a file.\nReturns an object of type `DocumentFileDetail` or `null` if user did not select a file.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `data` | `string` |\n| `options?` | [`CreateDocumentOptions`](#createdocumentoptions) |\n\n#### Returns\n\n`Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:124](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L124)\n\n___\n\n### createFile\n\n▸ **createFile**(`uriString`, `options?`): `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nCreates an empty file at given uri.\nRejects if a file or directory exist at given uri.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n| `options?` | `Pick`\u003c[`FileOperationOptions`](#fileoperationoptions), ``\"mimeType\"``\\\u003e |\n\n#### Returns\n\n`Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:169](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L169)\n\n___\n\n### exists\n\n▸ **exists**(`uriString`): `Promise`\u003c`boolean`\\\u003e\n\nCheck if there's a document located at the given uri.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c`boolean`\\\u003e\n\n#### Defined in\n\n[index.tsx:136](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L136)\n\n___\n\n### getPersistedUriPermissions\n\n▸ **getPersistedUriPermissions**(): `Promise`\u003c`string`[]\\\u003e\n\nReturns a list of all the persisted uri permissions.\n\n#### Returns\n\n`Promise`\u003c`string`[]\\\u003e\n\n#### Defined in\n\n[index.tsx:206](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L206)\n\n___\n\n### hasPermission\n\n▸ **hasPermission**(`uriString`): `Promise`\u003c`boolean`\\\u003e\n\nCheck if you have permission to access the uri.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c`boolean`\\\u003e\n\n#### Defined in\n\n[index.tsx:131](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L131)\n\n___\n\n### listFiles\n\n▸ **listFiles**(`uriString`): `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)[]\\\u003e\n\nList all files and folders in a directory uri.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)[]\\\u003e\n\n#### Defined in\n\n[index.tsx:216](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L216)\n\n___\n\n### mkdir\n\n▸ **mkdir**(`uriString`): `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nCreate a directory at given uri.\nAutomatically creates folders in path if needed.\nYou can use it to create nested directories easily.\nRejects if it fails.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:192](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L192)\n\n___\n\n### moveFile\n\n▸ **moveFile**(`srcUri`, `destUri`, `options?`): `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nMove file from source uri to destination uri.\npromise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.\nDoes not support moving directories.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `srcUri` | `string` |\n| `destUri` | `string` |\n| `options?` | `FileTransferOptions` |\n\n#### Returns\n\n`Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:249](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L249)\n\n___\n\n### openDocument\n\n▸ **openDocument**(`options`): `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)[]\\\u003e\n\nOpen the Document Picker to select a file.\nDocumentFileDetail is always an array.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `options` | [`OpenDocumentOptions`](#opendocumentoptions) |\n\n#### Returns\n\n`Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)[]\\\u003e\n\n`DocumentFileDetail[]` or `null` if user did not select a file.\n\n#### Defined in\n\n[index.tsx:115](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L115)\n\n___\n\n### openDocumentTree\n\n▸ **openDocumentTree**(`persist`): `Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nOpen the Document Picker to select a folder. Read/Write Permission will be granted to the selected folder.\nReturns an object of type `DocumentFileDetail` or `null` if user did not select a folder.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `persist` | `boolean` |\n\n#### Returns\n\n`Promise`\u003c``null`` \\| [`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:99](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L99)\n\n___\n\n### readFile\n\n▸ **readFile**(`uriString`, `options?`): `Promise`\u003c`string`\\\u003e\n\nRead contents of the given uri. uri must point to a file.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n| `options?` | `Pick`\u003c[`FileOperationOptions`](#fileoperationoptions), ``\"encoding\"``\\\u003e |\n\n#### Returns\n\n`Promise`\u003c`string`\\\u003e\n\n#### Defined in\n\n[index.tsx:141](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L141)\n\n___\n\n### releasePersistableUriPermission\n\n▸ **releasePersistableUriPermission**(`uriString`): `Promise`\u003c`void`\\\u003e\n\nRemove a uri from persisted uri permissions list.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c`void`\\\u003e\n\n#### Defined in\n\n[index.tsx:211](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L211)\n\n___\n\n### rename\n\n▸ **rename**(`uriString`, `newName`): `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nRenames the document at given uri.\nuri can be file or folder.\nResolves with `true` if successful and `false` otherwise.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n| `newName` | `string` |\n\n#### Returns\n\n`Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:201](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L201)\n\n___\n\n### stat\n\n▸ **stat**(`uriString`): `Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\nGet details for a file/directory at given uri.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c[`DocumentFileDetail`](#documentfiledetail)\\\u003e\n\n#### Defined in\n\n[index.tsx:221](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L221)\n\n___\n\n### unlink\n\n▸ **unlink**(`uriString`): `Promise`\u003c`boolean`\\\u003e\n\nRemoves the file or directory at given uri.\nResolves with `true` if delete is successful, throws otherwise.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n\n#### Returns\n\n`Promise`\u003c`boolean`\\\u003e\n\n#### Defined in\n\n[index.tsx:182](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L182)\n\n___\n\n### writeFile\n\n▸ **writeFile**(`uriString`, `data`, `options?`): `Promise`\u003c`void`\\\u003e\n\nWrites the given data to the file at given uri.\nTries to create the file if does not already exist before writing to it.\nResolves with given uriString if successful.\n\n#### Parameters\n\n| Name | Type |\n| :------ | :------ |\n| `uriString` | `string` |\n| `data` | `string` |\n| `options?` | [`FileOperationOptions`](#fileoperationoptions) |\n\n#### Returns\n\n`Promise`\u003c`void`\\\u003e\n\n#### Defined in\n\n[index.tsx:155](https://github.com/jd1378/react-native-saf-x/blob/de1efc0/src/index.tsx#L155)\n\n## Caveats\n\nDue to simplyifing the uri structure usage, file and directories should not have the same name at a given uri.\ndoing so can cause unexpected results.\nfor example in a folder named \"foo\", do not create \"bar\" file and \"bar\" directory making the uri being \"foo/bar\" for both cases.\n\n___\n\n## Thanks to\n\n- [ammarahm-ed](https://github.com/ammarahm-ed) for his work on [react-native-scoped-storage](https://github.com/ammarahm-ed/react-native-scoped-storage)\n which helped me jump start this module.\n\n## Contributing\n\nSee the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjd1378%2Freact-native-saf-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjd1378%2Freact-native-saf-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjd1378%2Freact-native-saf-x/lists"}