Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ded/reqwest
browser asynchronous http requests
https://github.com/ded/reqwest
ajax javascript jquery jsonp reqwest
Last synced: about 17 hours ago
JSON representation
browser asynchronous http requests
- Host: GitHub
- URL: https://github.com/ded/reqwest
- Owner: ded
- Created: 2011-04-01T22:11:21.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2021-10-03T11:58:08.000Z (about 3 years ago)
- Last Synced: 2024-11-19T17:47:02.659Z (23 days ago)
- Topics: ajax, javascript, jquery, jsonp, reqwest
- Language: JavaScript
- Homepage:
- Size: 9.21 MB
- Stars: 2,937
- Watchers: 93
- Forks: 343
- Open Issues: 106
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-github-star - reqwest
- awesome-f2e-libs - **reqwest**
README
# It's AJAX
All over again. Includes support for xmlHttpRequest, JSONP, CORS, and CommonJS Promises A.
It is also isomorphic allowing you to `require('reqwest')` in `Node.js` through the peer dependency [xhr2](https://github.com/pwnall/node-xhr2), albeit the original intent of this library is for the browser. For a more thorough solution for Node.js, see [mikeal/request](https://github.com/request/request).
## API
``` js
reqwest('path/to/html', function (resp) {
qwery('#content').html(resp)
})
reqwest({
url: 'path/to/html'
, method: 'post'
, data: { foo: 'bar', baz: 100 }
, success: function (resp) {
qwery('#content').html(resp)
}
})
reqwest({
url: 'path/to/html'
, method: 'get'
, data: [ { name: 'foo', value: 'bar' }, { name: 'baz', value: 100 } ]
, success: function (resp) {
qwery('#content').html(resp)
}
})
reqwest({
url: 'path/to/json'
, type: 'json'
, method: 'post'
, error: function (err) { }
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
reqwest({
url: 'path/to/json'
, type: 'json'
, method: 'post'
, contentType: 'application/json'
, headers: {
'X-My-Custom-Header': 'SomethingImportant'
}
, error: function (err) { }
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
// Uses XMLHttpRequest2 credentialled requests (cookies, HTTP basic auth) if supported
reqwest({
url: 'path/to/json'
, type: 'json'
, method: 'post'
, contentType: 'application/json'
, crossOrigin: true
, withCredentials: true
, error: function (err) { }
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
reqwest({
url: 'path/to/data.jsonp?callback=?'
, type: 'jsonp'
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
reqwest({
url: 'path/to/data.jsonp?foo=bar'
, type: 'jsonp'
, jsonpCallback: 'foo'
, jsonpCallbackName: 'bar'
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
reqwest({
url: 'path/to/data.jsonp?foo=bar'
, type: 'jsonp'
, jsonpCallback: 'foo'
, success: function (resp) {
qwery('#content').html(resp.content)
}
, complete: function (resp) {
qwery('#hide-this').hide()
}
})
```
## Promises
``` js
reqwest({
url: 'path/to/data.jsonp?foo=bar'
, type: 'jsonp'
, jsonpCallback: 'foo'
})
.then(function (resp) {
qwery('#content').html(resp.content)
}, function (err, msg) {
qwery('#errors').html(msg)
})
.always(function (resp) {
qwery('#hide-this').hide()
})
```
``` js
reqwest({
url: 'path/to/data.jsonp?foo=bar'
, type: 'jsonp'
, jsonpCallback: 'foo'
})
.then(function (resp) {
qwery('#content').html(resp.content)
})
.fail(function (err, msg) {
qwery('#errors').html(msg)
})
.always(function (resp) {
qwery('#hide-this').hide()
})
```
``` js
var r = reqwest({
url: 'path/to/data.jsonp?foo=bar'
, type: 'jsonp'
, jsonpCallback: 'foo'
, success: function () {
setTimeout(function () {
r
.then(function (resp) {
qwery('#content').html(resp.content)
}, function (err) { })
.always(function (resp) {
qwery('#hide-this').hide()
})
}, 15)
}
})
```
## Options
* `url` a fully qualified uri
* `method` http method (default: `GET`)
* `headers` http headers (default: `{}`)
* `data` entity body for `PATCH`, `POST` and `PUT` requests. Must be a query `String` or `JSON` object
* `type` a string enum. `html`, `xml`, `json`, or `jsonp`. Default is inferred by resource extension. Eg: `.json` will set `type` to `json`. `.xml` to `xml` etc.
* `contentType` sets the `Content-Type` of the request. Eg: `application/json`
* `crossOrigin` for cross-origin requests for browsers that support this feature.
* `success` A function called when the request successfully completes
* `error` A function called when the request fails.
* `complete` A function called whether the request is a success or failure. Always called when complete.
* `jsonpCallback` Specify the callback function name for a `JSONP` request. This value will be used instead of the random (but recommended) name automatically generated by reqwest.
## Security
If you are *still* requiring support for IE6/IE7, consider including [JSON3](https://bestiejs.github.io/json3/) in your project. Or simply do the following
``` html
(function () {
if (!window.JSON) {
document.write('<scr' + 'ipt src="http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"><\/scr' + 'ipt>')
}
}());
```
## Contributing
``` sh
$ git clone git://github.com/ded/reqwest.git reqwest
$ cd !$
$ npm install
```
Please keep your local edits to `src/reqwest.js`.
The base `./reqwest.js` and `./reqwest.min.js` will be built upon releases.
## Running Tests
``` sh
make test
```
## Browser support
* IE6+
* Chrome 1+
* Safari 3+
* Firefox 1+
* Opera
## Ender Support
Reqwest can be used as an [Ender](http://enderjs.com) module. Add it to your existing build as such:
$ ender add reqwest
Use it as such:
``` js
$.ajax({ ... })
```
Serialize things:
``` js
$(form).serialize() // returns query string -> x=y&...
$(form).serialize({type:'array'}) // returns array name/value pairs -> [ { name: x, value: y}, ... ]
$(form).serialize({type:'map'}) // returns an object representation -> { x: y, ... }
$(form).serializeArray()
$.toQueryString({
foo: 'bar'
, baz: 'thunk'
}) // returns query string -> foo=bar&baz=thunk
```
Or, get a bit fancy:
``` js
$('#myform input[name=myradios]').serialize({type:'map'})['myradios'] // get the selected value
$('input[type=text],#specialthing').serialize() // turn any arbitrary set of form elements into a query string
```
## ajaxSetup
Use the `request.ajaxSetup` to predefine a data filter on all requests. See the example below that demonstrates JSON hijacking prevention:
``` js
$.ajaxSetup({
dataFilter: function (response, type) {
if (type == 'json') return response.substring('])}while(1);'.length)
else return response
}
})
```
## RequireJs and Jam
Reqwest can also be used with RequireJs and can be installed via jam
```
jam install reqwest
```
```js
define(function(require){
var reqwest = require('reqwest')
});
```
## spm
Reqwest can also be installed via spm [](http://spmjs.io/package/reqwest)
```
spm install reqwest
```
## jQuery and Zepto Compatibility
There are some differences between the *Reqwest way* and the
*jQuery/Zepto way*.
### method ###
jQuery/Zepto use `type` to specify the request method while Reqwest uses
`method` and reserves `type` for the response data type.
### dataType ###
When using jQuery/Zepto you use the `dataType` option to specify the type
of data to expect from the server, Reqwest uses `type`. jQuery also can
also take a space-separated list of data types to specify the request,
response and response-conversion types but Reqwest uses the `type`
parameter to infer the response type and leaves conversion up to you.
### JSONP ###
Reqwest also takes optional `jsonpCallback` and `jsonpCallbackName`
options to specify the callback query-string key and the callback function
name respectively while jQuery uses `jsonp` and `jsonpCallback` for
these same options.
But fear not! If you must work the jQuery/Zepto way then Reqwest has
a wrapper that will remap these options for you:
```js
reqwest.compat({
url: 'path/to/data.jsonp?foo=bar'
, dataType: 'jsonp'
, jsonp: 'foo'
, jsonpCallback: 'bar'
, success: function (resp) {
qwery('#content').html(resp.content)
}
})
// or from Ender:
$.ajax.compat({
...
})
```
If you want to install jQuery/Zepto compatibility mode as the default
then simply place this snippet at the top of your code:
```js
$.ajax.compat && $.ender({ ajax: $.ajax.compat });
```
**Happy Ajaxing!**