cordova-promise-fs
Wraps the Cordova (and Chrome) File API in convenient functions (that return a Promise)
Are you entangled in a async callback mess to get even the simplest task done? Wait no longer -- here is cordova-promise-fs!
Getting started
# fetch code using bower bower install cordova-promise-fs bower install bluebird # a library that follows the Promise/A+ spec # ...or npm... npm install cordova-promise-fs npm install bluebird # a library that follows the Promise/A+ spec # install Cordova and plugins cordova platform add ios cordova plugin add cordova-plugin-file cordova plugin add cordova-plugin-file-transfer # optional
IMPORTANT: For iOS, use Cordova 3.7.0 or higher (due to a bug that affects requestFileSystem).
Or just download and include CordovaPromiseFS.js.
Usage
Initialize & configuration
var fs = ;
The Promise option expects a Promise library that follows the Promise/A+ spec, such as bluebird (github, download), promiscuous (github,file) or Angular's $q.
Note on concurrency: Concurrent uploads/downloads completely trash your mobile application. That's why I've put a concurrency limit on the number of downloads/uploads. Meteor sets this number on 30. In my experimental testing, I found 3 much more reasonable.
Browsing files
fs // checks if file exists. returns fileEntry or false.fs // returns a fileEntryfsdirpath // returns a dirEntryfs// return array with filenames (including path) optionString = 'r' // recursive listoptionString = 'd' // only list directoriesoptionString = 'f' // only list filesoptionString = 'e' // return results as FileEntry/DirectoryEntry (instead as path-string)optionString = 'rfe' // mix options! return entries of all files, recursively
Reading files
fs // returns text-content of a filefs // returns JSON-parsed contents of a filefs // returns URL to be used in js/html/css (file://....)fs// returns cordova internal URL (cdvfile://....)fs // returns Base64 encoded Data URI
Writing files
fs // writes a Blob, a String, or data (as JSON). Ensures directory exists.
File operations
fs // creates a filefs // ensures directory existsfs // move from src to dist. Ensures dest directory exists.fsfs // copy from src to dist. Ensures dest directory exists.fs // removes file. Resolves even if file was already removed.fs // removes file. Rejects when file does not exist.fs
Upload and download
FileTransfers with automatric retry and concurrency limit!
var promise = fs;var promise = fs;var promise = fs;var promise = fs; optionstrustAllHostsoptionsretry = 100020003000 // retry attemps: millisecond to wait before trying again.// plus all normal cordova-file-transfer options // upload/download augments the promise with two extra functions:promisepromise; // Gotcha: progress and abort() are unchainable;fs // won't return the augmented promise, just an ordinary one!
Utilities
fsfs // returns promise for the FileSystemfsfilenamepath // converts path to filename (last part after /)fs // converts path dirname (everything except part after last /)fsdeviceready // deviceready promisefsoptions // optionsfsisCordova // is Cordova App?
Normalized path
In CordovaPromiseFS, all filenames and paths are normalized:
- Directories should end with a
/
. - Filenames and directories should never start with a
/
. "./"
is converted to""
- ".." and "." are resolved.
This allows you to concatenate normalized paths, i.e.
=== + === 'dir1/dir2/';
If you're storing or saving paths, it is recommended to normalize
them first to avoid comparison problems. (i.e. paths are not recognized as the same because of a missing trailing slash).
Beware: the original entry.fullPath
might return a path which starts with a /
. This causes problems on Android, i.e.
var path = filesystemrootfullPath; // returns something starting with a `/`filesystemroot; // NullPointer error in android. Stupid!
This problem is solved in CordovaPromiseFS.
Changelog
1.2.5 (05/05/2017)
- Added Crosswalk
- Bugfix: list will return more than 100 entries
1.1.0 (05/05/2016)
- Fixed bug: download/upload support for different Cordova FileSystems.
1.0.0 (07/02/2016)
- Fixed bug in list function, thanks @sebastian-greco
- Improved code readability of transfer, thanks @youjenli
- There is no this, thanks @m0ppers
- Accept string as FileSystem, thanks @dortzur
- Normalize ".." in paths, thanks @starquake
0.13.0 (16/09/2015)
- Merged pull request from @Ijzerenhein. Fixed Chrome Persistent storage quota issue and added directory methods.
0.12.0 (17/03/2015)
- Merged pull request from @jakgra. Now you can write to hidden folders on Android. Thanks!
0.11.0 (17/03/2015)
- Minor improvements in upload
0.10.0 (21/12/2014)
- Support for other fileSystems (undocumented hack)
0.9.0 (28/11/2014)
- Normalize path everywhere.
0.8.0 (27/11/2014)
- Added test-suite, fixed few minor bugs.
0.7.0 (14/11/2014)
- bugfix toInternalURL functions and fix download argument order
0.6.0 (13/11/2014)
- Chrome Support!
0.5.0 (06/11/2014)
- Use
webpack
for the build proces - Fixed many small bugs
0.4.0 (06/11/2014)
- Various small changes
- Added
CordovaPromiseFS.js
for everybody who does not use Browserify/Webpack
0.3.0 (05/11/2014)
- Added
list
options (listr
ecursively, onlyf
iles, onlyd
irectories, return result ase
ntries)
0.2.0 (05/11/2014)
- Added
upload
anddownload
methods with concurrency limit
Contribute
Convert CommonJS to a browser-version:
npm install webpack -gnpm run-script prepublish
Run tests: Navigate to /test/index.html
, for example:
npm install static -gstatic .# http://localhost:8080/test/index.html
Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.
Contact
- @markmarijnissen
- http://www.madebymark.nl
- info@madebymark.nl
© 2014 - Mark Marijnissen