# remoteStorage.js
-This is a library for adding remoteStorage support to your client-side app. See http://tutorial.unhosted.5apps.com/ for example usage. [[Download](https://github.com/unhosted/remoteStorage.js/raw/master/build/latest/remoteStorage.js)]
-## Code example
+[](http://travis-ci.org/remotestorage/remotestorage.js)
+[](https://david-dm.org/remotestorage/remotestorage.js#info=devDependencies)
+[](https://codeclimate.com/github/remotestorage/remotestorage.js)
-Include remoteStorage.js in your HTML (before the app.js which calls it):
+remoteStorage.js is a JavaScript library for storing user data locally in the
+browser, as well as connecting to [remoteStorage](http://remotestorage.io)
+servers and syncing data across devices and applications.
-```html
-<script src="path/to/remoteStorage.js"></script>
-<script src="path/to/your/app.js"></script>
-```
+### Where to get help?
-Your `app.js`:
+* See [remotestorage.io](http://remotestorage.io/) for documentation, community
+ forums, and links
+* Get instant support via IRC in
+ [#remotestorage](irc://irc.freenode.net:7000/remotestorage) on Freenode
-```js
-remoteStorage.getStorageInfo('user@example.com', function(err, storageInfo) {
- var token = remoteStorage.receiveToken();
- if(token) {
- //we can access the 'notes' category on the remoteStorage of user@example.com:
- var client = remoteStorage.createClient(storageInfo, 'notes', token);
- client.put('foo', 'bar', function(err) {
- client.get('foo', function(err, data) {
- client.delete('foo', function(err) {
- });
- });
- });
- } else {
- //get an access token for 'notes' by dancing OAuth with the remoteStorage of user@example.com:
- window.location = remoteStorage.createOAuthAddress(storageInfo, ['notes'], window.location.href);
- }
-});
-```
+### Running a local test server
-## Function reference
-### remoteStorage.getStorageInfo(userAddress, callback)
+To develop remoteStorage-enabled apps, you need to have a
+remoteStorage-compatible storage account. We recommend
+[reStore](https://github.com/jcoglan/restore) for running a local test server.
+(Use the latest version from GitHub, not npm!)
- userAddress: string of the form 'user@host'
- callback: function(err, storageInfo)
- -err: null, or a string describing what went wrong
- -storageInfo: an object describing some details of the user's remoteStorage
+You can also get an account with a hoster, or use one of the various other
+remoteStorage server implementations:
+[get storage](http://remotestorage.io/get/).
-### remoteStorage.createOAuthAddress(storageInfo, categories, redirectUri)
+### Which version to choose?
- storageInfo: the object you got from the getStorageInfo call
- categories: an array of strings describing categories of data you will be accessing.
- @returns: string, the url you should go to for the OAuth dance
-See https://github.com/unhosted/website/wiki/categories for a list of categories you might want to access.
+You can either use a stable release or the current HEAD build. Stable releases
+can be found in [release/](https://github.com/remotestorage/remotestorage.js/tree/master/release/).
+Directories with a `-rcX` suffix contain release candidates, which may be used
+for testing but aren't necessarily "stable" releases.
-### remoteStorage.receiveToken()
+[release/head](https://github.com/remotestorage/remotestorage.js/tree/master/release/head/)
+contains a semi-current HEAD build. It is updated manually and irregularly. To
+build an up-to-date version of all files, run `make all` in the repository
+root.
- @returns: when coming back from the OAuth dance, a string containing the bearer token. Otherwise, null.
+### Which build file to use for my app?
-### remoteStorage.createClient(storageInfo, category, bearerToken)
+There are a number of different builds available:
- storageInfo: the object you got from the getStorageInfo call
- category: one of the strings from the array you passed to createOAuthAddress earlier
- @returns: a Client
+* <kbd>remotestorage.js</kbd> - Contains all components of remotestorage.js for
+ running in a browser.
+* <kbd>remotestorage.amd.js</kbd> - The same as remotestorage.js, but wrapped
+ for use with
+ [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) loaders
+ such as [RequireJS](http://requirejs.org/).
+* <kbd>remotestorage.min.js</kbd> - Minified version of remotestorage.js
+* <kbd>remotestorage-nocache.js</kbd> - Contains a version of remotestorage.js
+ without any caching features included. Use this if you want your app to write
+ directly to the remote server **without caching** any data in the browser's
+ storage (localStorage or indexedDB).
+* <kbd>remotestorage-nocache.amd.js</kbd>,
+ <kbd>remotestorage-nocache.min.js</kbd> - same as the other .amd / .min
+ build, but based on remotestorage-nocache.js.
-### Client.get(key, callback)
-
- key: a string, identifying which element you want to retrieve
- callback: function(err, data)
- -err: null, or a string describing what went wrong
- -data: undefined, or a string, that is the current value of 'key' within 'category' on the user's remoteStorage
+### Running tests
-#### Client.put(key, value, callback)
+Install development dependencies including the
+[testing framework](https://github.com/silverbucket/teste):
- key: a string, identifying which element you want to assign value to
- value: a string you want to assign to the element identified by key
- data: a string that, if successful, will be the new value of 'key' within 'category' on the user's remoteStorage
- callback: function(err)
- -err: null, or a string describing what went wrong
+ npm install
-### Client.delete(key, callback)
+Run all suites:
- key: a string, identifying which element you want to reset to undefined
- callback: function(err)
- -err: null, or a string describing what went wrong
+ npm test
-## Browser support
-This library relies heavily on [CORS](http://caniuse.com/#search=cors).
+Use the `teste` executable in order to test single files, like so e.g.:
-Known to work: Firefox, Chrome, Safari, Safari iOS.
+ node_modules/.bin/teste test/unit/baseclient-suite.js
-Might work: Firefox Mobile, Android stock browser, Opera 12+, Opera Mobile 12+, IE 10+.
+### How to build
-Planned: IE 8 & 9 (please [help with this](https://groups.google.com/d/topic/unhosted/Xk1hJMr9i9c/discussion)!).
+Make sure you have [Natural Docs](http://www.naturaldocs.org/) installed on
+your system (e.g. via `sudo apt-get install naturaldocs`).
-## Version and license
-This is version 0.5.3 of the library, and you can use it under AGPL or MIT license - whatever floats your boat. Pull requests are very welcome (if you're not on github you can email them to michiel at unhosted.org). To build:
+Display the available build tasks:
- cd build
- node build.js
+ make
+Build everything:
+
+ make all
projects / remotestorage.js / blobdiff