diff --git a/README.md b/README.md index a2e7f85..70e1d06 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ type XhrOptions = String | { withCredentials: Boolean?, responseType: String?, beforeSend: Function? + qs: Any? } xhr := (XhrOptions, Callback) => Request ``` @@ -193,6 +194,17 @@ A function being called right before the `send` method of the `XMLHttpRequest` o Pass an `XMLHttpRequest` object (or something that acts like one) to use instead of constructing a new one using the `XMLHttpRequest` or `XDomainRequest` constructors. Useful for testing. +### `options.qs` + +A value to be transformed into a query string. This library does not provide +a serializer for `options.qs` out of the box: you must define it yourself as +`xhr.qsSerialize`. + +If `options.qs` is defined, and `xhr.qsSerialize` is not, then an +Error will be thrown. + +For more, see [Query string support](#query-string-support). + ## FAQ - Why is my server's JSON response not parsed? I returned the right content-type. @@ -216,6 +228,8 @@ xhr({ } }) ``` +- How can I support query strings? + - See [Query string support](#query-string-support) ## Mocking Requests You can override the constructor used to create new requests for testing. When you're making a new request: @@ -231,6 +245,31 @@ xhr.XMLHttpRequest = MockXMLHttpRequest xhr.XDomainRequest = MockXDomainRequest ``` +## Query string support +There are many ways to stringify query parameters; consequently, `xhr` makes no +assumptions about how to handle them, and does not support the `qs` option out +of the box. + +To support the `qs` option, define an `xhr.qsSerialize` function. This function +accepts the value of `options.qs` as its first argument, and returns a string +that is appended to the URL. + +You do not need to include a leading "?" in the value that you return from +`xhr.qsSerialize`. + +```js +var xhr = require('xhr') +var qs = require('qs') + +xhr.qsSerialize = qs.stringify + +xhr.get('/foo', { + qs: { + bar: true + } +}) +``` + ## MIT Licenced [1]: http://xhr.spec.whatwg.org/#the-send()-method diff --git a/index.js b/index.js index cfa102a..bd5911d 100644 --- a/index.js +++ b/index.js @@ -7,6 +7,7 @@ var xtend = require("xtend") module.exports = createXHR createXHR.XMLHttpRequest = window.XMLHttpRequest || noop createXHR.XDomainRequest = "withCredentials" in (new createXHR.XMLHttpRequest()) ? createXHR.XMLHttpRequest : window.XDomainRequest +createXHR.qsSerialize = null // Define this as a function to support the `qs` option forEachArray(["get", "put", "post", "patch", "head", "delete"], function(method) { createXHR[method === "delete" ? "del" : method] = function(uri, options, callback) { @@ -139,9 +140,17 @@ function _createXHR(options) { } } + var qsStringifyDefined = isFunction(createXHR.qsSerialize); + + if (options.qs && !qsStringifyDefined) { + throw new Error("To use the 'qs' option, first define an 'xhr.qsSerialize' function.") + } + + var qs = options.qs && qsStringifyDefined ? '?' + createXHR.qsSerialize(options.qs) : '' + var key var aborted - var uri = xhr.url = options.uri || options.url + var uri = xhr.url = (options.uri || options.url) + qs var method = xhr.method = options.method || "GET" var body = options.body || options.data var headers = xhr.headers = options.headers || {}