README updates

packages/agent-base/README.md

@@ -2,9 +2,20 @@ agent-base
 ==========
 ### Turn a function into an [`http.Agent`][http.Agent] instance
 
-This module provides an `http.Agent` generator. That is, you pass it an async
-callback function, and it returns a new `http.Agent` instance that will invoke the
-given callback function when sending outbound HTTP requests.
+This module is a thin wrapper around the base `http.Agent` class.
+
+It provides an absract class that must define a `connect()` function,
+which is responsible for creating the underlying socket that the HTTP
+client requests will use.
+
+The `connect()` function may return an arbitrary `Duplex` stream, or
+another `http.Agent` instance to delegate the request to, and may be
+asynchronous (by defining an `async` function).
+
+Instances of this agent can be used with the `http` and `https`
+modules. To differentiate, the options parameter in the `connect()`
+function includes a `secureEndpoint` property, which can be checked
+to determine what type of socket should be returned.
 
 #### Some subclasses:
 
@@ -16,96 +27,41 @@ Send a pull request to list yours!
  * [`pac-proxy-agent`][pac-proxy-agent]: A PAC file proxy `http.Agent` implementation for HTTP and HTTPS
  * [`socks-proxy-agent`][socks-proxy-agent]: A SOCKS proxy `http.Agent` implementation for HTTP and HTTPS
 
-
-Installation
-------------
-
-Install with `npm`:
-
-``` bash
-$ npm install agent-base
-```
-
-
 Example
 -------
 
-Here's a minimal example that creates a new `net.Socket` connection to the server
-for every HTTP request (i.e. the equivalent of `agent: false` option):
+Here's a minimal example that creates a new `net.Socket` or `tls.Socket`
+based on the `secureEndpoint` property. This agent can be used with both
+the `http` and `https` modules.
 
 ```ts
 import * as net from 'net';
 import * as tls from 'tls';
 import * as http from 'http';
 import { Agent } from 'agent-base';
 
-const agent = new Agent(function (req, opts) {
-  var socket;
-  // `secureEndpoint` is true when using the "https" module
-  if (opts.secureEndpoint) {
-    socket = tls.connect(opts);
-  } else {
-    socket = net.connect(opts);
+class MyAgent extends Agent {
+  connect(req, opts) {
+    // `secureEndpoint` is true when using the "https" module
+    if (opts.secureEndpoint) {
+      return tls.connect(opts);
+    } else {
+      return net.connect(opts);
+    }
   }
-  return socket;
 });
 
+// Keep alive enabled means that `connect()` will only be
+// invoked when a new connection needs to be created
+const agent = new MyAgent({ keepAlive: true });
+
 // Pass the `agent` option when creating the HTTP request
 http.get('http://nodejs.org/api/', { agent }, (res) => {
   console.log('"response" event!', res.headers);
   res.pipe(process.stdout);
 });
 ```
 
-Returning a Promise or using an `async` function is also supported:
-
-```ts
-new Agent(async (req, opts) => {
-  await sleep(1000);
-  // etc…
-});
-```
-
-Return another `http.Agent` instance to "pass through" the responsibility
-for that HTTP request to that agent:
-
-```ts
-new Agent((req, opts) => {
-  return opts.secureEndpoint ? https.globalAgent : http.globalAgent;
-});
-```
-
-
-API
----
-
-## Agent(Function callback[, Object options]) → [http.Agent][]
-
-Creates a base `http.Agent` that will execute the callback function `callback`
-for every HTTP request that it is used as the `agent` for. The callback function
-is responsible for creating a `stream.Duplex` instance of some kind that will be
-used as the underlying socket in the HTTP request.
-
-The `options` object accepts the following properties:
-
-  * `timeout` - Number - Timeout for the `callback()` function in milliseconds. Defaults to Infinity (optional).
-
-The callback function should have the following signature:
-
-### callback(http.ClientRequest req, Object options, Function cb) → undefined
-
-The ClientRequest `req` can be accessed to read request headers and
-and the path, etc. The `options` object contains the options passed
-to the `http.request()`/`https.request()` function call, and is formatted
-to be directly passed to `net.connect()`/`tls.connect()`, or however
-else you want a Socket to be created. Pass the created socket to
-the callback function `cb` once created, and the HTTP request will
-continue to proceed.
-
-If the `https` module is used to invoke the HTTP request, then the
-`secureEndpoint` property on `options` _will be set to `true`_.
-
-
 License
 -------
 

packages/data-uri-to-buffer/README.md

@@ -5,22 +5,11 @@ data-uri-to-buffer
 This module accepts a ["data" URI][rfc] String of data, and returns a
 node.js `Buffer` instance with the decoded data.
 
-
-Installation
-------------
-
-Install with `npm`:
-
-``` bash
-$ npm install data-uri-to-buffer
-```
-
-
 Example
 -------
 
 ``` js
-import dataUriToBuffer from 'data-uri-to-buffer';
+import { dataUriToBuffer } from 'data-uri-to-buffer';
 
 // plain-text data is supported
 let uri = 'data:,Hello%2C%20World!';

packages/data-uri-to-buffer/test/data-uri-to-buffer.test.ts

@@ -1,5 +1,5 @@
 import assert from 'assert';
-import dataUriToBuffer from '../src';
+import { dataUriToBuffer } from '../src';
 
 describe('data-uri-to-buffer', function () {
 	it('should decode bare-bones Data URIs', function () {

packages/degenerator/README.md

@@ -26,17 +26,6 @@ async function foo() {
 With the compiled output code, you can evaluate the code using the `vm` module
 in Node.js, or save the code to a file and require it, or whatever.
 
-
-Installation
-------------
-
-Install with `npm`:
-
-```bash
-$ npm install degenerator
-```
-
-
 Example
 -------
 
@@ -62,7 +51,7 @@ instance with the `vm` module:
 
 ```typescript
 import vm from 'vm';
-import degenerator from 'degenerator';
+import { degenerator } from 'degenerator';
 
 // The `get()` function is Promise-based (error handling omitted for brevity)
 function get(endpoint: string) {

packages/get-uri/README.md

@@ -14,17 +14,6 @@ easily extensible with more:
 | `http`    | [HTTP URIs][http]               | `http://www.example.com/path/to/name`
 | `https`   | [HTTPS URIs][https]             | `https://www.example.com/path/to/name`
 
-
-Installation
-------------
-
-Install with `npm`:
-
-``` bash
-$ npm install get-uri
-```
-
-
 Example
 -------
 

packages/http-proxy-agent/README.md

@@ -6,46 +6,24 @@ This module provides an `http.Agent` implementation that connects to a specified
 HTTP or HTTPS proxy server, and can be used with the built-in `http` module.
 
 __Note:__ For HTTP proxy usage with the `https` module, check out
-[`node-https-proxy-agent`](https://github.com/TooTallNate/node-https-proxy-agent).
-
-Installation
-------------
-
-Install with `npm`:
-
-``` bash
-$ npm install http-proxy-agent
-```
+[`https-proxy-agent`](../https-proxy-agent).
 
 
 Example
 -------
 
-``` js
-var url = require('url');
-var http = require('http');
-var HttpProxyAgent = require('http-proxy-agent');
+```ts
+import * as http from 'http';
+import { HttpProxyAgent } from 'http-proxy-agent';
 
-// HTTP/HTTPS proxy to connect to
-var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
-console.log('using proxy server %j', proxy);
+const agent = new HttpProxyAgent('http://168.63.76.32:3128');
 
-// HTTP endpoint for the proxy to connect to
-var endpoint = process.argv[2] || 'http://nodejs.org/api/';
-console.log('attempting to GET %j', endpoint);
-var opts = url.parse(endpoint);
-
-// create an instance of the `HttpProxyAgent` class with the proxy server information
-var agent = new HttpProxyAgent(proxy);
-opts.agent = agent;
-
-http.get(opts, function (res) {
+http.get('http://nodejs.org/api/', { agent }, (res) => {
   console.log('"response" event!', res.headers);
   res.pipe(process.stdout);
 });
 ```
 
-
 License
 -------
 

packages/https-proxy-agent/README.md

@@ -13,69 +13,31 @@ Since this agent implements the CONNECT HTTP method, it also works with other
 protocols that use this method when connecting over proxies (i.e. WebSockets).
 See the "Examples" section below for more.
 
-
-Installation
-------------
-
-Install with `npm`:
-
-``` bash
-$ npm install https-proxy-agent
-```
-
-
 Examples
 --------
 
 #### `https` module example
 
-``` js
-var url = require('url');
-var https = require('https');
-var HttpsProxyAgent = require('https-proxy-agent');
-
-// HTTP/HTTPS proxy to connect to
-var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
-console.log('using proxy server %j', proxy);
+```ts
+import * as https from 'https';
+import { HttpsProxyAgent } from 'https-proxy-agent';
 
-// HTTPS endpoint for the proxy to connect to
-var endpoint = process.argv[2] || 'https://graph.facebook.com/tootallnate';
-console.log('attempting to GET %j', endpoint);
-var options = url.parse(endpoint);
+const agent = new HttpsProxyAgent('http://168.63.76.32:3128');
 
-// create an instance of the `HttpsProxyAgent` class with the proxy server information
-var agent = new HttpsProxyAgent(proxy);
-options.agent = agent;
-
-https.get(options, function (res) {
+https.get('https://example.com', { agent }, (res) => {
   console.log('"response" event!', res.headers);
   res.pipe(process.stdout);
 });
 ```
 
 #### `ws` WebSocket connection example
 
-``` js
-var url = require('url');
-var WebSocket = require('ws');
-var HttpsProxyAgent = require('https-proxy-agent');
-
-// HTTP/HTTPS proxy to connect to
-var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
-console.log('using proxy server %j', proxy);
-
-// WebSocket endpoint for the proxy to connect to
-var endpoint = process.argv[2] || 'ws://echo.websocket.org';
-var parsed = url.parse(endpoint);
-console.log('attempting to connect to WebSocket %j', endpoint);
+```ts
+import WebSocket from 'ws';
+import { HttpsProxyAgent } from 'https-proxy-agent';
 
-// create an instance of the `HttpsProxyAgent` class with the proxy server information
-var options = url.parse(proxy);
-
-var agent = new HttpsProxyAgent(options);
-
-// finally, initiate the WebSocket connection
-var socket = new WebSocket(endpoint, { agent: agent });
+const agent = new HttpsProxyAgent('http://168.63.76.32:3128');
+const socket = new WebSocket('ws://echo.websocket.org', { agent });
 
 socket.on('open', function () {
   console.log('"open" event!');
@@ -91,20 +53,19 @@ socket.on('message', function (data, flags) {
 API
 ---
 
-### new HttpsProxyAgent(Object options)
+### new HttpsProxyAgent(proxy: string | URL, options?: HttpsProxyAgentOptions)
 
 The `HttpsProxyAgent` class implements an `http.Agent` subclass that connects
 to the specified "HTTP(s) proxy server" in order to proxy HTTPS and/or WebSocket
 requests. This is achieved by using the [HTTP `CONNECT` method][CONNECT].
 
-The `options` argument may either be a string URI of the proxy server to use, or an
-"options" object with more specific properties:
+The `proxy` argument is the URL for the proxy server.
+
+The `options` argument accepts the usual `http.Agent` constructor options, and
+some additional properties:
 
-  * `host` - String - Proxy host to connect to (may use `hostname` as well). Required.
-  * `port` - Number - Proxy port to connect to. Required.
-  * `protocol` - String - If `https:`, then use TLS to connect to the proxy.
-  * `headers` - Object - Additional HTTP headers to be sent on the HTTP CONNECT method.
-  * Any other options given are passed to the `net.connect()`/`tls.connect()` functions.
+ * `headers` - Object containing additional headers to send to the proxy server
+   in the `CONNECT` request.
 
 
 License