needle - npm Package Compare versions

Comparing version 1.5.1 to 1.5.2

package.json

 {
   "name": "needle",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "The leanest and most handsome HTTP client in the Nodelands.",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -122,3 +122,3 @@ Needle
 
-### needle.head(url, [options,] callback)
+### needle.head(url[, options][, callback])
 
@@ -138,3 +138,3 @@ ```js
 
-### needle.get(url, [options,] callback)
+### needle.get(url[, options][, callback])
 
@@ -147,3 +147,3 @@ ```js
 
-### needle.post(url, data, [options,] callback)
+### needle.post(url, data[, options][, callback])
 
@@ -160,3 +160,3 @@ ```js
 
-### needle.put(url, data, [options,] callback)
+### needle.put(url, data[, options][, callback])
 
@@ -177,7 +177,7 @@ ```js
 
-### needle.patch(url, data, [options,] callback)
+### needle.patch(url, data[, options][, callback])
 
 Same behaviour as PUT.
 
-### needle.delete(url, data, [options,] callback)
+### needle.delete(url, data[, options][, callback])
 
@@ -195,3 +195,3 @@ ```js
 
-### needle.request(method, url, data, [options,] callback)
+### needle.request(method, url, data[, options][, callback])
 
@@ -212,3 +212,3 @@ Generic request. This not only allows for flexibility, but also lets you perform a GET request with data, in which case will be appended to the request as a query string, unless you pass a `json: true` option (read below).
 
-Now, if you set pass `json: true` among the options, Needle won't set your params as a querystring but instead send a JSON representation of your data through the request's body.
+Now, if you set pass `json: true` among the options, Needle won't set your params as a querystring but instead send a JSON representation of your data through the request's body, as well as set the `Content-Type` and `Accept` headers to `application/json`.
 
@@ -221,4 +221,50 @@ ```js
 
-More examples after this short break.
+Events
+------
 
+All of the above methods return a Readable stream that emits the following events:
+
+### Event: `'response'`
+
+ - `response <http.IncomingMessage>`
+ 
+Emitted when the underlying [http.ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest) emits a response event. This is after the connection is established and the header received, but before any of it is processed (e.g. authorization required or redirect to be followed). No data has been consumed at this point.
+
+### Event: `'redirect'`
+
+Indicates that the a redirect is being followed. This means that the response code was a redirect (`301`, `302`, `303`, `307`) and the given [redirect options](#redirect-options) allowed following the URL received in the `Location` header.
+
+### Event: `'header'`
+
+ - `statusCode <Integer>`
+ - `headers <Object>`
+ 
+Triggered after the header has been processed, and just before the data is to be consumed. This implies that no redirect was followed and/or authentication header was received. In other words, we got a "valid" response. 
+
+### Event: `'end'`
+
+ - `exception <Error>` (optional)
+
+Emitted when the response process has completed, either because all data has been consumed or an error ocurred somewhere in the middle. That's why the event callback's first argument may be an Error object. In other words:
+
+```js
+var resp = needle.get('something.worthy/of/being/streamed/by/needle');
+resp.pipe(somewhereElse);
+resp.on('end', function(err) {
+  if (err) console.log('An error ocurred: ' + err.message);
+})
+```
+
+### Event: `'err'`
+
+ - `exception <Error>` (optional)
+
+Emitted when an error ocurrs. This should only happen once in the lifecycle of a Needle request.
+
+### Event: `'timeout'`
+
+ - `type <String>`
+
+Emitted when an timeout error occurs. Type can be either 'open_timeout' or 'read_timeout'. This will called right before aborting the request, which will also trigger an `err` event, a described above, with an `ECONNRESET` (Socket hang up) exception.
+
 Request options
@@ -231,3 +277,3 @@ ---------------
  - `json`        : When `true`, sets content type to `application/json` and sends request body as JSON string, instead of a query string.
-  - `open_timeout`: (or `timeout`) Returns error if connection takes longer than X milisecs to establish. Defaults to `10000` (10 secs). `0` means no timeout.
+ - `open_timeout`: (or `timeout`) Returns error if connection takes longer than X milisecs to establish. Defaults to `10000` (10 secs). `0` means no timeout.
  - `read_timeout`: Returns error if data transfer takes longer than X milisecs, after connection is established. Defaults to `0` (no timeout).
@@ -234,0 +280,0 @@ - `follow_max`  : (or `follow`) Number of redirects to follow. Defaults to `0`. See below for more redirect options.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

187154

increased by1.11%

Number of lines in readme file

557

increased by9%

No dependency changes