Skip to content

Commit d28f20b

Browse files
author
Preben Ludviksen
committed
Split out API reference from README.
1 parent b86ce58 commit d28f20b

File tree

2 files changed

+116
-42
lines changed

2 files changed

+116
-42
lines changed

‎README.md

Lines changed: 12 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# react-native-filesystem
1+
# react-native-filesystem [![npm version](https://img.shields.io/npm/v/react-native-filesystem.svg?style=flat)](https://www.npmjs.com/package/react-native-filesystem)
22
Simple file system API for iOS & Android, for dealing with text-files.
33

44
All interaction is promise-based, and all content is
@@ -10,12 +10,15 @@ written and read as UTF-8.
1010
react-native link react-native-filesystem
1111

1212
## Usage
13+
14+
For a full list of available methods, see the [API Reference](docs/reference.md)
15+
1316
### Write to files
1417

1518
```javascript
1619
import FileSystem from 'react-native-filesystem';
1720

18-
async function writeFile() {
21+
async function writeToFile() {
1922
const fileContents = 'This is a my content.';
2023
await FileSystem.writeToFile('my-directory/my-file.txt', fileContents);
2124
console.log('file is written');
@@ -67,47 +70,14 @@ FileSystem.writeToFile('my-file.txt', 'My content', FileSystem.storage.important
6770
Files need to be read from the same storage class they're saved to, and two files can have the same
6871
name if they're located in different storages. The options are:
6972

70-
#### storage.backedUp
71-
72-
The default. Files stored in this location will automatically be backed up by iCloud on iOS and
73-
[Auto Backup for Apps](https://developer.android.com/guide/topics/data/autobackup.html) on Android
74-
devices running Marshmallow or newer (6.0+). This is where you'd want to put user generated content.
75-
76-
Corresponds to `<Application_Home>/Documents` on iOS and a subdirectory of
77-
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
78-
on Android.
79-
80-
#### storage.important
81-
82-
For files that are possible to re-generate / re-download, but are still important to keep
83-
around during low storage situations. F.ex. offline maps. The system will almost always keep these
84-
files around.
85-
86-
Corresponds to `<Application_Home>/Library/Caches` with "do not backup" flag on iOS, and a
87-
subdirectory of
88-
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
89-
excluded from backup on Android.
90-
91-
#### storage.auxiliary
92-
93-
For files that can be re-created, and that the app can live without. On
94-
Android this storage behaves the same as `storage.important`, but on iOS the system can delete
95-
these files in low storage situations. To play it safe, you should gracefully handle the case where
96-
they are gone, by checking for their existence.
97-
98-
Corresponds to `<Application_Home>/Library/Caches` on iOS, and a subdirectory of
99-
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
100-
explicitly excluded from backup on Android.
101-
102-
103-
#### storage.temporary
104-
105-
For temporary caches and data. The system can get rid of these at any time, but you are
106-
still required to delete them manually to free up space when they are no longer in use.
73+
| Storage class | Description |
74+
|---------------|-------------|
75+
| `storage.backedUp` | These files are automatically backed up on supported devices
76+
| `storage.important` | Excluded from backup, but still kept around in low-storage situations
77+
| `storage.auxiliary` | Files that the app can function without. Can be deleted by the system in low-storage situations.
78+
| `storage.temporary` | For temporary files and caches. Can be deleted by the system any time.
10779

108-
Corresponds to `<Application_Home>/tmp` on iOS and
109-
[Context.getCacheDir()](https://developer.android.com/reference/android/content/Context.html#getCacheDir())
110-
on Android.
80+
For full details, see the [API Reference](docs/reference.md)
11181

11282
## Questions?
11383

‎docs/reference.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# API Reference
2+
3+
There is only one module, FileSystem, that can be imported like this:
4+
5+
```javascript
6+
import FileSystem from 'react-native-filesystem';
7+
```
8+
9+
## FileSystem
10+
11+
static **writeToFile** (path: `string`, content: `string`, storage: `string?`): `Promise`
12+
13+
Asynchronously writes the content to a file, and resolves the promise upon completion.
14+
Intermediary directories in the path are created automatically.
15+
16+
If no storage is specified, FileSystem.storage.backedUp is the default.
17+
18+
---
19+
static **readFile** (path: `string`, storage: `string?`): `Promise`
20+
21+
Asynchronously reads the file, and resolves the promise with the `string` content.
22+
23+
If no storage is specified, FileSystem.storage.backedUp is the default.
24+
25+
---
26+
static **deleteFile** (path: `string`, storage: `string?`): `Promise`
27+
28+
Asynchronously deletes the file, and resolves the promise upon completion.
29+
30+
If no storage is specified, FileSystem.storage.backedUp is the default.
31+
32+
---
33+
static **fileExists** (path: `string`, storage: `string?`): `Promise`
34+
35+
Asynchronously checks if the file exists, and resolves the promise with a `bool`. Will return
36+
`false` if a directory exists at the path.
37+
38+
If no storage is specified, FileSystem.storage.backedUp is the default.
39+
40+
---
41+
static **directoryExists** (path: `string`, storage: `string?`): `Promise`
42+
43+
Asynchronously checks if the directory exists, and resolves the promise with a `bool`. Will return
44+
`false` if a file exists at the path.
45+
46+
If no storage is specified, FileSystem.storage.backedUp is the default.
47+
48+
## FileSystem.storage
49+
50+
There are four different storage classes available.
51+
52+
#### storage.backedUp
53+
54+
The default. Files stored in this location will automatically be backed up by iCloud on all
55+
supported iOS versions (8.0+) and
56+
[Auto Backup for Apps](https://developer.android.com/guide/topics/data/autobackup.html) on Android
57+
devices running Marshmallow or newer (6.0+). This is where you'd want to put user generated content.
58+
59+
Corresponds to `<Application_Home>/Documents` on iOS and a subdirectory of
60+
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
61+
on Android.
62+
63+
#### storage.important
64+
65+
For files that are possible to re-generate / re-download, but are still important to keep
66+
around during low storage situations. F.ex. offline maps. The system will almost always keep these
67+
files around.
68+
69+
Corresponds to `<Application_Home>/Library/Caches` with "do not backup" flag on iOS, and a
70+
subdirectory of
71+
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
72+
excluded from backup on Android.
73+
74+
#### storage.auxiliary
75+
76+
On Android this storage behaves the same as `storage.important`.
77+
78+
This is for files that can be re-created, and that the app can live without. On iOS the system can
79+
delete these files in low storage situations. To play it safe, you should gracefully handle the
80+
case where they are gone, by checking for their existence.
81+
82+
Corresponds to `<Application_Home>/Library/Caches` on iOS, and a separate subdirectory of
83+
[Context.getFilesDir()](https://developer.android.com/reference/android/content/Context.html#getFilesDir())
84+
excluded from backup on Android.
85+
86+
*Under which circumstances can these files be deleted?*
87+
88+
To quote Apple's
89+
[File System Programming Guide](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html):
90+
91+
> In iOS 5.0 and later, the system may delete the Caches directory on rare occasions when the system
92+
> is very low on disk space. This will never occur while an app is running. However, be aware that
93+
> restoring from backup is not necessarily the only condition under which the Caches directory can
94+
> be erased.
95+
96+
97+
#### storage.temporary
98+
99+
For temporary caches and data. The system can get rid of these at any time, but you are
100+
still required to delete them manually to free up space when they are no longer in use.
101+
102+
Corresponds to `<Application_Home>/tmp` on iOS and
103+
[Context.getCacheDir()](https://developer.android.com/reference/android/content/Context.html#getCacheDir())
104+
on Android.

0 commit comments

Comments
 (0)