dropbox-extra v0.0.2
An unfinished, unofficial wrapper around the Dropbox JavaScript SDK, inspired by fs-extra focused on node.js. I have no intentions of supporting browser-based usage.
Required API:
- emptyDir
- support root directory
- test with full folder access
mkDir
- resolve
- test with full folder access
mkdir (with option to resolve issue with existing folder)
- readdir
- remove
- move (with support to move root contents into subdirectory)
- upload
- stat (with support to stat a folder and return list of entries)
- sync (with cursor support)
Planned features:
It would be nice to take advantage of Dropbox's batch methods, which allows you to group multiple operations under a single job. However, at the moment, I don't really need this and it complicates things. I think there should be different methods, e.g. mkdirs for multiple new directories? Batch jobs do not appear to be atomic - ie some of the parts of a job can fail and some can succeed. It doesn't seem like there's much real benefit to using them unless you're moving large numbers of files?
Work out how to be sensible about case-sensitivty. I think I was cavalier using path_display instead of path_lower. Need to run tests in case-sensitive environment if possible.
- Support for promises and callbacks (https://github.com/RyanZim/universalify)
- Offer toggle for dry-run (i.e. don't modify the user's folder in any way)
- Will return fs-style error codes, e.g.
ENOTDIR
andENOENT
. - Handle retry-able errors: backing off and retrying, with jitter, as needed.
- Tolerant of paths without a leading slash, e.g. 'test/foo.txt' and '/test/foo.txt' are equivalent.
- Offers handy
upload
anddownload
methods which use Streams! - Offers handy
sync
methods to synchronize a local folder with one in Dropbox - Lets you interact with the root directory as if it were another folder, e.g.
emptyDir('/')
will remove all the files in the user's Dropbox. You can alsomove('/', '/foo')
the root directory's contents into a subfolder, and vice versa. remove
won't throw an error when the file doesn't exist,mkdir
won't throw an error when the directory exists, etc...
See also:
Getting started
npm install dropbox-extra -save
You'll need to acquire an OAUTH accessToken
from your user, or you can generate one for yourself on the developer page. Then you can initialize a dropbox
client like this:
var Dropbox = require('dropbox-extra');
var dropbox = new Dropbox(accessToken);
Examples
dropbox.writeFile('/hello.txt', 'World!', function(err, stat){
// There is now a file called hello.txt in the user's Dropbox
});
dropbox.sync('/folder/on/Dropbox', '/local/folder', function(err, cursor){
// The local folder is now identical to the folder on Dropbox
// Wait a while, perhaps wait for a webhook...
dropbox.sync(cursor);
});
API
emptyDir
path
dropbox.emptyDir('/foo', function(err){});
mkdir
dropbox.mkdir('/foo', function(err){});
move
dropbox.move('/from', '/to' function(err){});
readdir
dropbox.readdir('/folder', function(err){});
readFile
dropbox.readFile('/file.txt', function(err){});
remove
dropbox.remove('/folder/or/file', function(err){});
stat
dropbox.mkdir('/foo', function(err){});
writeFile
Behaves like fs.writeFile.
dropbox.writeFile('/test.txt', 'Hello world', function(err){});
Grievances
- Client methods have unexpected side-effects
The Dropbox cli modifies the object passed to a method. When you pass in arg to a method like this:
client.method(arg).then(..).catch(..);
Arg is set to undefined, so you cannot re-use it. I was reusing arg when retrying methods which result in retryable errors.
- Promises
I wanted to implement some retry logic in my error handler, like I needed to do for this library. You might consider something like:
client.method(arg).then(function(){..}).catch(function(err){
if (retry(err)) {
...
} else {
callback(err);
}
});
What do you expect to happen? You'll see the error and the process will die. What actually happens? The error is swallowed silently.
- Strange delays
There seems to be a strange issue with filesListFolder when after writing lots of files to the root directory calling filesListFolder doesn't seem to return. I need to implement some sort of timeout feature to make sure that the callback actually gets called. Otherwise it might choke up things....
https://www.dropboxforum.com/t5/API-Support-Feedback/Slow-response-from-list-folder/td-p/217063