document querystring apis

docs/buildQueryString.md

@@ -0,0 +1,40 @@
+# buildQueryString(object)
+
+- [API](#api)
+- [How it works](#how-it-works)
+
+---
+
+### API
+
+`querystring = m.buildQueryString(object)`
+
+Argument     | Type                                       | Required | Description
+------------ | ------------------------------------------ | -------- | ---
+`object`     | `Object`                                   | Yes      | A key-value map to be converted into a string
+**returns**  | `String`                                   |          | A string representing the input object
+
+[How to read signatures](signatures.md)
+
+---
+
+### How it works
+
+The `m.buildQueryString` creates a querystring from an object. It's useful for manipulating URLs
+
+```javascript
+var querystring = m.buildQueryString({a: 1, b: 2})
+
+// querystring is "a=1&b=2"
+```
+
+#### Deep data structures
+
+Deep data structures are serialized in a way that is understood by popular web application servers such as PHP, Rails and ExpressJS
+
+```javascript
+var querystring = m.buildQueryString({a: ["hello", "world"]})
+
+// querystring is "a[0]=hello&a[1]=world"
+```
+

docs/parseQueryString.md

@@ -0,0 +1,59 @@
+# parseQueryString(string)
+
+- [API](#api)
+- [How it works](#how-it-works)
+
+---
+
+### API
+
+`object = m.parseQueryString(string)`
+
+Argument     | Type                                       | Required | Description
+------------ | ------------------------------------------ | -------- | ---
+`string`     | `String`                                   | Yes      | A querystring
+**returns**  | `Object`                                   |          | A key-value map
+
+[How to read signatures](signatures.md)
+
+---
+
+### How it works
+
+The `m.parseQueryString` method creates an object from a querystring. It is useful for handling data from URL
+
+```javascript
+var data = m.parseQueryString("a=hello&b=world")
+
+// data is {a: "hello", b: "world"}
+```
+
+#### Boolean type casting
+
+This method attempts to cast boolean values if possible. This helps prevents bugs related to loose truthiness and unintended type casts.
+
+```javascript
+var data = m.parseQueryString("a=true&b=false")
+
+// data is {a: true, b: false}
+```
+
+#### Leading question mark tolerance
+
+For convenience, the `m.parseQueryString` method ignores a leading question mark, if present:
+
+```javascript
+var data = m.parseQueryString("?a=hello&b=world")
+
+// data is {a: "hello", b: "world"}
+```
+
+#### Deep data structures
+
+Querystrings that contain bracket notation are correctly parsed into deep data structures
+
+```javascript
+m.parseQueryString("a[0]=hello&a[1]=world")
+
+// data is {a: ["hello", "world"]}
+```

docs/request.md

@@ -32,7 +32,7 @@ Argument               | Type                              | Required | Descript
 `options.type`         | `any = Function(any)`             | No       | A constructor to be applied to each object in the response. Defaults to the [identity function](https://en.wikipedia.org/wiki/Identity_function).
 `options.serialize`    | `string = Function(any)`          | No       | A serialization method to be applied to `data`. Defaults to `JSON.stringify`, or if `options.data` is an instance of [`FormData`](https://developer.mozilla.org/en/docs/Web/API/FormData), defaults to the [identity function](https://en.wikipedia.org/wiki/Identity_function) (i.e. `function(value) {return value}`).
 `options.deserialize`  | `any = Function(string)`          | No       | A deserialization method to be applied to the response. Defaults to a small wrapper around `JSON.parse` that returns `null` for empty responses.
-`options.extract`      | `string = Function(xhr, options)` | No       | A hook to specify how the XMLHttpRequest response should be read. Useful for reading response headers and cookies. Defaults to a function that returns `xhr.responseText`. If defined, `options.deserialize` is ignored.
+`options.extract`      | `string = Function(xhr, options)` | No       | A hook to specify how the XMLHttpRequest response should be read. Useful for reading response headers and cookies. Defaults to a function that returns `xhr.responseText`. If defined, the `xhr` parameter is the XMLHttpRequest instance used for the request, and `options` is the object that was passed to the `m.request` call. If a custom `extract` callback is set, `options.deserialize` is ignored.
 `options.initialValue` | `any`                             | No       | A value to populate the returned stream before the request completes
 `options.useBody`      | `Boolean`                         | No       | Force the use of the HTTP body section for `data` in `GET` requests when set to `true`, or the use of querystring for other HTTP methods when set to `false`. Defaults to `false` for `GET` requests and `true` for other methods.
 **returns**            | `Stream`                          |          | A stream that resolves to the response data, after it has been piped through the `extract`, `deserialize` and `type` methods