├── .jshintignore
├── .gitignore
├── .jshintrc
├── README.md
├── package.json
├── ampersand-sync-promise.js
└── test
    └── index.js


/.jshintignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .DS_Store
3 | 


--------------------------------------------------------------------------------
/.jshintrc:
--------------------------------------------------------------------------------
 1 | {
 2 |     "asi": false,
 3 |     "expr": true,
 4 |     "loopfunc": true,
 5 |     "curly": false,
 6 |     "evil": true,
 7 |     "white": true,
 8 |     "undef": true,
 9 |     "node": true,
10 |     "eqnull": true,
11 |     "predef": [
12 |         "require",
13 |         "exports",
14 |         "module"
15 |     ]
16 | }
17 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # ampersand-sync-promise
 2 | 
 3 | Standalone, modern-browser-only version of Backbone.Sync as Common JS module.
 4 | 
 5 | Use this instead of ampersand's standard sync to return a promise instead of an XHR object.
 6 | 
 7 | Uses the popular [Q library](https://www.npmjs.org/package/q) for promise implementation
 8 | 
 9 | All credit to the original Ampersand JS team.
10 | 
11 | ## install
12 | 
13 | ```
14 | npm install ampersand-sync-promise
15 | ```
16 | 
17 | ## running the tests
18 | 
19 | ```
20 | npm test
21 | ```
22 | 
23 | Tests are written in [tape](https://github.com/substack/tape) and since they require a browser environment it gets run in a headless browser using phantomjs via [tape-run](https://github.com/juliangruber/tape-run). Make sure you have phantomjs installed for this to work. 
24 | 
25 | You can also run `npm start` then open a browser.
26 | 
27 | <!-- starthide -->
28 | 
29 | ## license
30 | 
31 | MIT
32 | 
33 | <!-- endhide -->
34 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "ampersand-sync-promise",
 3 |   "description": "Standalone, modern-browser-only version of Backbone.Sync as Common JS module. Fork of the original ampersand-js-sync, but instead returns a promise.  All credit to original Ampersand JS team.",
 4 |   "version": "1.0.0",
 5 |   "author": "Stephen Grider <ste.grider@gmail.com",
 6 |   "bugs": {
 7 |     "url": "https://github.com/stephengrider/ampersand-sync-promise/issues"
 8 |   },
 9 |   "dependencies": {
10 |     "qs": "^1.2.1",
11 |     "tap-spec": "^0.2.0",
12 |     "underscore": "~1.6.0",
13 |     "xhr": "^1.10.0",
14 |     "q": "~1.0.1"
15 |   },
16 |   "devDependencies": {
17 |     "ampersand-model": "^4.0.1",
18 |     "ampersand-rest-collection": "^2.0.1",
19 |     "browserify": "^5.9.3",
20 |     "jshint": "^2.5.3",
21 |     "precommit-hook": "^1.0.7",
22 |     "run-browser": "~1.3.0",
23 |     "tape-run": "^0.3.0",
24 |     "redtape": "1.0.0"
25 |   },
26 |   "homepage": "https://github.com/stephengrider/ampersand-sync-promise",
27 |   "keywords": [
28 |     "backbone",
29 |     "sync",
30 |     "rest",
31 |     "ampersand"
32 |   ],
33 |   "license": "MIT",
34 |   "main": "ampersand-sync-promise.js",
35 |   "repository": {
36 |     "type": "git",
37 |     "url": "https://github.com/stephengrider/ampersand-sync-promise.git"
38 |   },
39 |   "scripts": {
40 |     "start": "run-browser test/*",
41 |     "test": "browserify test/* | tape-run | tap-spec"
42 |   },
43 |   "testling": {
44 |     "files": "test/*.js",
45 |     "browsers": [
46 |       "ie/8..latest",
47 |       "firefox/17..latest",
48 |       "firefox/nightly",
49 |       "chrome/22..latest",
50 |       "chrome/canary",
51 |       "opera/12..latest",
52 |       "opera/next",
53 |       "safari/5.1..latest",
54 |       "ipad/6.0..latest",
55 |       "iphone/6.0..latest",
56 |       "android-browser/4.2..latest"
57 |     ]
58 |   }
59 | }
60 | 


--------------------------------------------------------------------------------
/ampersand-sync-promise.js:
--------------------------------------------------------------------------------
  1 | var _ = require('underscore');
  2 | var xhr = require('xhr');
  3 | var qs = require('qs');
  4 | var q = require('q');
  5 | 
  6 | 
  7 | // Throw an error when a URL is needed, and none is supplied.
  8 | var urlError = function () {
  9 |     throw new Error('A "url" property or function must be specified');
 10 | };
 11 | 
 12 | 
 13 | module.exports = function (method, model, options) {
 14 |     var type = methodMap[method];
 15 |     var headers = {};
 16 | 
 17 |     // Default options, unless specified.
 18 |     _.defaults(options || (options = {}), {
 19 |         emulateHTTP: false,
 20 |         emulateJSON: false
 21 |     });
 22 | 
 23 |     // Default request options.
 24 |     var params = {type: type};
 25 | 
 26 |     // Ensure that we have a URL.
 27 |     if (!options.url) {
 28 |         params.url = _.result(model, 'url') || urlError();
 29 |     }
 30 | 
 31 |     // Ensure that we have the appropriate request data.
 32 |     if (options.data == null && model && (method === 'create' || method === 'update' || method === 'patch')) {
 33 |         params.json = options.attrs || model.toJSON(options);
 34 |     }
 35 | 
 36 |     // If passed a data param, we add it to the URL or body depending on request type
 37 |     if (options.data && type === 'GET') {
 38 |         // make sure we've got a '?'
 39 |         params.url += _.contains(params.url, '?') ? '&' : '?';
 40 |         params.url += qs.stringify(options.data);
 41 |     }
 42 | 
 43 |     // For older servers, emulate JSON by encoding the request into an HTML-form.
 44 |     if (options.emulateJSON) {
 45 |         headers['Content-Type'] = 'application/x-www-form-urlencoded';
 46 |         params.body = params.json ? {model: params.json} : {};
 47 |         delete params.json;
 48 |     }
 49 | 
 50 |     // For older servers, emulate HTTP by mimicking the HTTP method with `_method`
 51 |     // And an `X-HTTP-Method-Override` header.
 52 |     if (options.emulateHTTP && (type === 'PUT' || type === 'DELETE' || type === 'PATCH')) {
 53 |         params.type = 'POST';
 54 |         if (options.emulateJSON) params.body._method = type;
 55 |         headers['X-HTTP-Method-Override'] = type;
 56 |     }
 57 | 
 58 |     // When emulating JSON, we turn the body into a querystring.
 59 |     // We do this later to let the emulateHTTP run its course.
 60 |     if (options.emulateJSON) {
 61 |         params.body = qs.stringify(params.body);
 62 |     }
 63 | 
 64 |     // Start setting ajaxConfig options (headers, xhrFields).
 65 |     var ajaxConfig = (_.result(model, 'ajaxConfig') || {});
 66 | 
 67 |     // Combine generated headers with user's headers.
 68 |     if (ajaxConfig.headers) {
 69 |         _.extend(headers, ajaxConfig.headers);
 70 |     }
 71 |     params.headers = headers;
 72 | 
 73 |     //Set XDR for cross domain in IE8/9
 74 |     if (ajaxConfig.useXDR) {
 75 |         params.useXDR = true;
 76 |     }
 77 | 
 78 |     // Set raw xhr options.
 79 |     if (ajaxConfig.xhrFields) {
 80 |         var beforeSend = ajaxConfig.beforeSend;
 81 |         params.beforeSend = function (req) {
 82 |             for (var key in ajaxConfig.xhrFields) {
 83 |                 req[key] = ajaxConfig.xhrFields[key];
 84 |             }
 85 |             if (beforeSend) return beforeSend.apply(this, arguments);
 86 |         };
 87 |         params.xhrFields = ajaxConfig.xhrFields;
 88 |     }
 89 | 
 90 |     // Turn a jQuery.ajax formatted request into xhr compatible
 91 |     params.method = params.type;
 92 | 
 93 |     var deferred = q.defer();
 94 |     if(options.error && _.isFunction(options.error)){
 95 |       deferred.promise.fail(options.error);
 96 |     }
 97 |     if(options.success && _.isFunction(options.success)){
 98 |       deferred.promise.done(options.success);
 99 |     }
100 | 
101 |     var ajaxSettings = _.extend(params, options);
102 | 
103 |     // Make the request. The callback executes functions that are compatible
104 |     // With jQuery.ajax's syntax.
105 |     var request = options.xhr = xhr(ajaxSettings, function (err, resp, body) {
106 |         if (err) return deferred.reject(resp, 'error', err.message);
107 | 
108 |         if (body && typeof body === 'string') {
109 |           try {
110 |             body = JSON.parse(body);
111 |           } catch (e) {}
112 |         }
113 | 
114 |         if (options.success) return deferred.resolve(body, 'success', resp);
115 |     });
116 |     request.ajaxSettings = ajaxSettings;
117 |     model.trigger('request', model, request, options, ajaxSettings);
118 | 
119 |     return deferred.promise;
120 | };
121 | 
122 | // Map from CRUD to HTTP for our default `Backbone.sync` implementation.
123 | var methodMap = {
124 |     'create': 'POST',
125 |     'update': 'PUT',
126 |     'patch':  'PATCH',
127 |     'delete': 'DELETE',
128 |     'read':   'GET'
129 | };
130 | 


--------------------------------------------------------------------------------
/test/index.js:
--------------------------------------------------------------------------------
  1 | if (!Function.prototype.bind) {
  2 |   Function.prototype.bind = function (oThis) {
  3 |     if (typeof this !== "function") {
  4 |       // closest thing possible to the ECMAScript 5 internal IsCallable function
  5 |       throw new TypeError("Function.prototype.bind - what is trying to be bound is not callable");
  6 |     }
  7 | 
  8 |     var aArgs = Array.prototype.slice.call(arguments, 1),
  9 |         fToBind = this,
 10 |         fNOP = function () {},
 11 |         fBound = function () {
 12 |           return fToBind.apply(this instanceof fNOP && oThis ? this: oThis, aArgs.concat(Array.prototype.slice.call(arguments)));
 13 |         };
 14 | 
 15 |     fNOP.prototype = this.prototype;
 16 |     fBound.prototype = new fNOP();
 17 | 
 18 |     return fBound;
 19 |   };
 20 | }
 21 | 
 22 | var redtape = require('redtape');
 23 | var sync = require('../ampersand-sync-promise');
 24 | var Model = require('ampersand-model');
 25 | 
 26 | var Me = Model.extend({
 27 |   url: '/hi',
 28 |   props: {
 29 |     title: 'string',
 30 |     author: 'string',
 31 |     length: 'number'
 32 |   },
 33 |   ajaxConfig: {
 34 |     useXDR: true,
 35 |     xhrFields: {
 36 |       withCredentials: true
 37 |     }
 38 |   }
 39 | });
 40 | 
 41 | var model;
 42 | 
 43 | var test = redtape({
 44 |   beforeEach: function(cb){
 45 |     model = new Me({
 46 |       title: 'Midsummer Nights Dream',
 47 |       author: 'Shakespeare',
 48 |       length: 123
 49 |     });
 50 |     cb();
 51 |   },
 52 |   afterEach: function(cb) {
 53 | 
 54 |     cb();
 55 |   }
 56 | });
 57 | 
 58 | test('should allow models to overwrite ajax configs at the model level', function (t) {
 59 |   t.plan(3);
 60 | 
 61 |   model.on('request', function (model, xhr, options, ajaxSettings) {
 62 |     t.equal(ajaxSettings.type, 'GET');
 63 |     t.equal(ajaxSettings.xhrFields.withCredentials, true);
 64 |     t.equal(ajaxSettings.useXDR, true);
 65 |     t.end();
 66 |   });
 67 |   sync('read', model);
 68 | });
 69 | 
 70 | test('read', function (t) {
 71 | 
 72 |   model.on('request', function(model, xhr, options, ajaxSettings){
 73 |     t.equal(ajaxSettings.url, '/hi');
 74 |     t.equal(ajaxSettings.type, 'GET');
 75 |     t.ok(!ajaxSettings.json);
 76 |     t.ok(!ajaxSettings.data);
 77 |     t.end();
 78 |   });
 79 |   model.sync('read', model);
 80 | });
 81 | 
 82 | test('passing data', function (t) {
 83 |   // on reads it should be part of the URL
 84 | 
 85 |   model.on('request', function(model, xhr, options, ajaxSettings){
 86 |     t.equal(ajaxSettings.url, '/hi?a=a&one=1', 'data passed to reads should be made into a query string');
 87 |     t.end();
 88 |   });
 89 |   sync('read', model, {data: {a: 'a', one: 1}});
 90 | });
 91 | 
 92 | test('create', function (t) {
 93 |   model.on('request', function(model, xhr, options, ajaxSettings){
 94 |     t.equal(ajaxSettings.url, '/hi');
 95 |     t.equal(ajaxSettings.type, 'POST');
 96 |     t.equal(ajaxSettings.headers['Content-Type'], 'application/json');
 97 |     var data = ajaxSettings.json;
 98 |     t.equal(data.title, 'Midsummer Nights Dream');
 99 |     t.equal(data.author, 'Shakespeare');
100 |     t.equal(data.length, 123);
101 |     t.end();
102 |   });
103 |   
104 |   sync('create', model);
105 | });
106 | 
107 | test('update', function (t) {
108 | 
109 |   model.on('request', function(model, xhr, options, ajaxSettings){
110 |     t.equal(ajaxSettings.url, '/hi');
111 |     t.equal(ajaxSettings.type, 'PUT');
112 |     t.equal(ajaxSettings.headers['Content-Type'], 'application/json');
113 |     var data = ajaxSettings.json;
114 |     t.equal(data.title, 'Midsummer Nights Dream');
115 |     t.equal(data.author, 'Shakespeare');
116 |     t.end();
117 |   });
118 |   
119 |   sync('update', model);
120 | });
121 | 
122 | test('update with emulateHTTP and emulateJSON', function (t) {
123 |   
124 |   model.on('request', function(model, xhr, options, ajaxSettings){
125 |     t.equal(ajaxSettings.url, '/hi');
126 |     t.equal(ajaxSettings.type, 'POST');
127 |     t.equal(ajaxSettings.body, 'model%5Btitle%5D=Midsummer%20Nights%20Dream&model%5Bauthor%5D=Shakespeare&model%5Blength%5D=123&_method=PUT');
128 |     t.equal(ajaxSettings.headers['Content-Type'], 'application/x-www-form-urlencoded');
129 |     t.end();
130 |   });
131 | 
132 |   var options = {
133 |     emulateHTTP: true,
134 |     emulateJSON: true
135 |   };
136 | 
137 |   sync('update', model, options);
138 | 
139 | });
140 | 
141 | test('update with just emulateHTTP', function (t) {
142 | 
143 |   model.on('request', function(model, xhr, options, ajaxSettings){
144 |     t.equal(ajaxSettings.url, '/hi');
145 |     t.equal(ajaxSettings.type, 'POST');
146 |     t.equal(ajaxSettings.headers['Content-Type'], 'application/json');
147 |     var data = ajaxSettings.json;
148 |     t.equal(data.title, 'Midsummer Nights Dream');
149 |     t.equal(data.author, 'Shakespeare');
150 |     t.equal(data.length, 123);
151 |     t.end();
152 |   });
153 |   
154 |   var options = {
155 |     emulateHTTP: true
156 |   };
157 | 
158 |   sync('update', model, options);
159 | });
160 | 
161 | test("update with just emulateJSON", function (t) {
162 |   
163 | 
164 |   model.on('request', function(model, xhr, options, ajaxSettings){
165 |     t.equal(ajaxSettings.url, '/hi');
166 |     t.equal(ajaxSettings.type, 'PUT');
167 |     t.equal(ajaxSettings.headers['Content-Type'], 'application/x-www-form-urlencoded');
168 |     t.equal(ajaxSettings.body, 'model%5Btitle%5D=Midsummer%20Nights%20Dream&model%5Bauthor%5D=Shakespeare&model%5Blength%5D=123');
169 |     t.end();
170 |   });
171 |   
172 |   var options = {
173 |     emulateJSON: true
174 |   };
175 |   
176 |   sync('update', model, options);
177 |   
178 | });
179 | 
180 | test('delete', function (t) {
181 |   model.on('request', function(model, xhr, options, ajaxSettings){
182 |     t.equal(ajaxSettings.url, '/hi');
183 |     t.equal(ajaxSettings.type, 'DELETE');
184 |     t.notOk(ajaxSettings.data);
185 |     t.end();
186 |   });
187 |   
188 |   sync('delete', model);
189 | });
190 | 
191 | test('destroy with emulateHTTP', function (t) {
192 |   model.on('request', function(model, xhr, options, ajaxSettings){
193 |     t.equal(xhr.ajaxSettings.url, '/hi');
194 |     t.equal(xhr.ajaxSettings.type, 'POST');
195 |     t.equal(xhr.ajaxSettings.body, '_method=DELETE');
196 |     t.end();
197 |   });
198 | 
199 |   var options = {
200 |     emulateHTTP: true,
201 |     emulateJSON: true
202 |   };
203 |   sync('delete', model, options);
204 | });
205 | 
206 | test('urlError', function (t) {
207 |   t.throws(function () {
208 |     var xhr = sync('read', {});
209 |   }, Error);
210 |   t.end();
211 | });
212 | 
213 | test('Call user provided beforeSend function.', function (t) {
214 |   t.plan(1);
215 | 
216 |   var options = {
217 |     beforeSend: function (_xhr) {
218 |       t.pass();
219 |     },
220 |     emulateHTTP: true
221 |   };
222 |   sync('delete', model, options);
223 |   t.end();
224 | });
225 | 
226 | test('Sync returns a promise', function(t) {
227 |   t.plan(2);
228 |   
229 |   var promise = sync('read', model);
230 |   
231 |   t.ok(promise.done);
232 |   t.ok(promise.finally);
233 |   t.end();
234 | });


--------------------------------------------------------------------------------