From abb81eb642e621214896917de351c0e02e64a8ba Mon Sep 17 00:00:00 2001 From: Malte-Thorben Bruns Date: Tue, 21 Apr 2015 18:22:26 +0200 Subject: [PATCH] doc: reorganize & add better examples --- CHANGELOG.markdown | 15 +++++- README.markdown | 114 +++++++++++++++++----------------------- doc/api.markdown | 72 +++++++++++++++++++++++++ doc/plugin-api.markdown | 6 ++- doc/plugins.markdown | 9 +++- 5 files changed, 146 insertions(+), 70 deletions(-) create mode 100644 doc/api.markdown diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown index a1b4a7b..ef88dae 100644 --- a/CHANGELOG.markdown +++ b/CHANGELOG.markdown @@ -1,4 +1,17 @@ -# rail ChangeLog +# [RAIL](./README.markdown) ChangeLog + +## 2015-04-XX, [v0.2.0-alpha](https://github.com/skenqbx/rail/tree/v0.2.0-alpha) **_unstable_** + +### Notable changes + + - **globalClient**: The addition of a globalClient enables calls without instantiating a client + - **URL**: An URL can now be passed directly to `rail.call()` + +### Known issues + + - **servername**: The pending node.js issue [#9368](https://github.com/joyent/node/pull/9368) requires to set `agent=null` when using the `servername` option (affects all versions of node.js). + +## Commits ## 2015-04-21, [v0.1.0-alpha](https://github.com/skenqbx/rail/tree/v0.1.0-alpha) **_unstable_** diff --git a/README.markdown b/README.markdown index 7903bb3..8c8545a 100644 --- a/README.markdown +++ b/README.markdown @@ -12,8 +12,8 @@ Stability: 2 - Unstable ## Table of Contents - [Features](#features) - - [Usage](#usage) - - [API](#api) + - [Examples](#examples) + - [API](./doc/api.markdown) - [Plugins](./doc/plugins.markdown) - [Plugin API](./doc/plugin-api.markdown) - [Tests](#tests) @@ -33,13 +33,55 @@ Stability: 2 - Unstable - `retry` - (wip) timed multi-target retry - `validate` - (wip) response validation -## Usage +## Examples + +### globalClient - URL only + +```js +var RAIL = require('rail'); + +RAIL.call('https://www.github.com/', function(response) { + // consume response +}).end(); +``` + +### globalClient - URL & plugin options + +```js +var RAIL = require('rail'); + +RAIL.call({ + url: 'https://www.github.com/', + buffer: true +}, function(response) { + if (response.buffer) { + console.log(response.buffer.toString()); + } +}).end(); +``` + +### globalClient - request & plugin options ```js -var rail = require('rail'); +var RAIL = require('rail'); + +RAIL.call({ + host: 'www.github.com', + buffer: true +}, function(response) { + if (response.buffer) { + console.log(response.buffer.toString()); + } +}).end(); +``` + +### Custom client + +```js +var RAIL = require('rail'); // create a client that holds defaults & plugins -var client = rail({ +var client = new RAIL({ request: { host: 'github.com' // set default host }, @@ -75,68 +117,6 @@ call.write('hello'); call.end('world'); ``` -## API - -### RAIL.globalClient -A global `RAIL` object pre-loaded with `buffer`, `json`, `redirect` & `cookies` plugin. - -### RAIL.call(urlOrOptions, responseListener) -A convenience method ala. `https.request()` using `RAIL.globalClient`. - -See [rail.call()](#railcallopt_options-opt_responselistener). - -### new RAIL(opt_options) -Creates a new `RAIL` object. - -**opt_options** - - - `{string} proto` - One of `https`, `http2` or `http`, defaults to `https` - - `{Object} request` - holding default request options, see `https.request()` - - `{Object} *` - plugin options - -#### rail.plugins -An object holding loaded plugins. - -#### rail.proto -The default protocol for all calls. - -#### rail.defaults -The default request options for all calls. - -### rail.use(plugin, opt_options) -Loads a plugin. Currently only built-in plugins are supported (you could patch `RAIL.plugins` though). - -### rail.call(opt_options, opt_responseListener) -Factory method to create new `Call` objects, think `https.request()`. - -**opt_options** - -When `opt_options` is a string, it is handled like `opt_options.url`. - - - `{string} proto` - See [`new RAIL(opt_options)`](#new-railopt_options) - - `{string} url` - When given, the request options are set accordingly - - `{Object} request` - request options, see `https.request()` - - `{Object|boolean} *` - plugin options - -_Note: For convenience & compatibility with node core API, all request options can also be provided directly besides proto & plugin options._ - -### new Call(rail, opt_options) -Creates a new `Call` object. `Call` extends `stream.Writable`. - -### Event 'request' - -`function({Object} request)` - -### Event 'response' - -`function({Object} response)` - -### Event 'warn' - -`function({string} plugin, {string} status, {?string} opt_message)` - -### Event 'error' - ## Tests ```bash diff --git a/doc/api.markdown b/doc/api.markdown new file mode 100644 index 0000000..ed6f253 --- /dev/null +++ b/doc/api.markdown @@ -0,0 +1,72 @@ +# [RAIL](../README.markdown) API + +## Static Exports + +### RAIL.plugins +An object holding all built-in [plugins](./doc/plugins.markdown). + +### RAIL.globalClient +A global `RAIL` object pre-loaded with `buffer`, `json`, `redirect` & `cookies` plugin. + +### RAIL.call(urlOrOptions, responseListener) +A convenience method ala. `https.request()` using `RAIL.globalClient`. + +See [rail.call()](#railcallopt_options-opt_responselistener). + +## Class: RAIL +`RAIL` extends `events.EventEmitter`. + +### new RAIL(opt_options) +Creates a new `RAIL` object. + +**opt_options** + + - `{string} proto` - One of `https`, `http2` or `http`, defaults to `https` + - `{Object} request` - holding default request options, see `https.request()` + - `{Object} *` - plugin options + +#### rail.plugins +An object holding loaded plugins. + +#### rail.proto +The default protocol for all calls. + +#### rail.defaults +The default request options for all calls. + +### rail.use(plugin, opt_options) +Loads a plugin. Currently only built-in plugins are supported (you could patch `RAIL.plugins` though). + +### rail.call(opt_options, opt_responseListener) +Factory method to create new `Call` objects, think `https.request()`. + +**opt_options** + +When `opt_options` is a string, it is handled like `opt_options.url`. + + - `{string} proto` - See [`new RAIL(opt_options)`](#new-railopt_options) + - `{string} url` - When given, the request options are set accordingly + - `{Object} request` - request options, see `https.request()` + - `{Object|boolean} *` - plugin options + +_Note: For convenience & compatibility with node core API, all request options can also be provided directly besides proto & plugin options._ + +## Class: Call +`Call` extends `stream.Writable`. + +### new Call(rail, opt_options) +Creates a new `Call` object. + +### Event 'request' + +`function({Object} request)` + +### Event 'response' + +`function({Object} response)` + +### Event 'warn' + +`function({string} plugin, {string} status, {?string} opt_message)` + +### Event 'error' diff --git a/doc/plugin-api.markdown b/doc/plugin-api.markdown index ec8a2bc..0a6c927 100644 --- a/doc/plugin-api.markdown +++ b/doc/plugin-api.markdown @@ -1,5 +1,9 @@ -# RAIL Plugin API +# [RAIL](../README.markdown) Plugin API +## Table of Contents + + - [RAIL Plugin Events](#rail-plugin-events) + - [Interceptable Events](#interceptable-events) ## Example diff --git a/doc/plugins.markdown b/doc/plugins.markdown index 0af3093..aa47795 100644 --- a/doc/plugins.markdown +++ b/doc/plugins.markdown @@ -1,4 +1,11 @@ -# RAIL Plugins +# [RAIL](../README.markdown) Plugins + +## Table of Contents + + - [buffer](#buffer) + - [cookies](#cookies) + - [json](#json) + - [redirect](#redirect) ## buffer Buffers the response body and exports it as `response.buffer`.