		{
		"name": "shred",
		"version": "0.8.10",
		"description": "A simple HTTP client for Node.js and browsers. Supports gzip, cookies, redirects, and https.",
		"keywords":[
		"http",
		"client"
		],
		"licenses":[
		{
		"type": "MIT",
		"url": "https://github.com/automatthew/shred/blob/master/LICENSE"
		}
		],
		"homepage": "https://github.com/automatthew/shred",
		"bugs": {
		"url": "https://github.com/automatthew/shred/issues"
		},
		"author": {
		"name": "shred",
		"version": "1.0.0-alpha-01",
		"description": "A resource-oriented JavaScript HTTP client.",
		"keywords": [
		"http",
		"client"
		],
		"licenses": [
		{
		"type": "MIT",
		"url": "https://github.com/pandastrike/shred/blob/master/LICENSE"
		}
		],
		"homepage": "https://github.com/pandastrike/shred",
		"bugs": {
		"url": "https://github.com/pandastrike/shred/issues"
		},
		"authors": [
		{
		"name": "Dan Yoder",
		"email": "daniel.yoder@gmail.com"
		},
		"maintainers":[
		{ "name": "Dan Yoder", "email": "daniel.yoder@gmail.com" },
		{ "name": "Matthew King", "email": "automatthew@gmail.com" }
		],
		"contributors":[
		{ "name": "Dan Yoder", "email": "daniel.yoder@gmail.com" },
		{ "name": "Jason Campbell" },
		{ "name": "Matthew King", "email": "automatthew@gmail.com" },
		{ "name": "Nicolas LaCasse" },
		{ "name": "Andy Burke", "email": "aburke@bitflood.org" }
		],
		"main": "./lib/shred.js",
		"repository": {
		"type": "git",
		"url": "git://github.com/automatthew/shred.git"
		},
		"files": [
		"lib"
		],
		"dependencies": {
		"sprintf": "0.1.1",
		"ax": "0.1.8",
		"cookiejar": "1.3.1",
		"iconv-lite": ">= 0.1.2"
		},
		"devDependencies": {
		"coffee-script": "1.4.x",
		"testify": "0.2.x",
		"express": "2.5.10",
		"browserify": "1.8.3",
		"http-browserify": "https://github.com/spire-io/http-browserify/tarball/master",
		"uglify-js": "~1.2.5",
		"docco": "~0.3.0"
		},
		"email": "dan@pandastrike.com"
		},
		{
		"name": "Matthew King",
		"email": "matthew@pandastrike.com"
		}
		],
		"main": "./lib/shred.js",
		"repository": {
		"type": "git",
		"url": "git://github.com/pandastrike/shred.git"
		},
		"scripts": {
		"test": "node_modules/.bin/coffee test/tests.coffee"
		"prepublish": "coffee -o lib/ -c src/*.coffee",
		"test": "coffee test/shred.coffee"
		},
		"engine": "node >= 0.8.x"
		"dependencies": {
		"fairmont": "^0.7.4",
		"mutual": "^0.4.12",
		"url-template": "^2.0.4",
		"typely": "0.0.0",
		"c50n": "^0.6.0"
		},
		"devDependencies": {
		"coffee-script": "1.7.x",
		"through": "^2.3.4",
		"colors": "^0.6.2",
		"nodegit": "^0.1.3",
		"c50n": "^0.5.0"
		},
		"engine": "node >= 0.10.x"
		}

348

README.md

		@@ -1,259 +0,199 @@
		# Introduction
		# Overview

		Shred is an HTTP client library for node.js and browsers.
		Shred supports gzip, cookies, https, proxies, and redirects.
		Shred is an HTTP client that wraps HTTP interfaces so you can easily create CoffeeScript or JavaScript clients.

		# Installation
		Note Shred 1.0.x is a complete reboot of the project. The goal is the same, but the interface has changed drastically. Shred 1.0.x is _not_ backwards compatible with earlier versions.

		## Node.js
		HTTP is a rich protocol, but the low-level details of setting headers and checking response codes muck up our code. So we either ignore these nuances or write wrapper functions to hide the details.

		Shred can be installed through npm.
		Shred makes it easy to declaratively create API wrapper functions. Shred also features support for URL templates, response compression, authorization, and streaming responses. And more features are coming soon!

		npm install shred
		## Example: GitHub API

		## Browsers
		Here's how we would access the issues for the Shred project on Github:

		We use [Browserify](https://github.com/substack/node-browserify) to bundle Shred and all of its dependencies in one javascript file.
		Simply include the bundled version of shred in a script tag.
		```coffeescript
		{resource} = require "shred"
		{base64, read} = require "fairmont"

		<script src="browser/shred.bundle.js" />
		# read our personal github token from a file
		token = read(resolve(__dirname, "token")).trim()

		If you want smaller downloads, use the minified version.
		# define our API client
		github = resource "https://api.github.com/",
		issues: (resource) ->
		resource "repos/{owner}/{repo}/issues",
		create:
		method: "post"
		headers:
		accept: "application/vnd.github.v3.raw+json"
		expect: 201
		list:
		method: "get"
		headers:
		accept: "application/vnd.github.v3.raw+json"
		expect: 200

		<script src="browser/shred.bundle.min.js" />
		# later, use the API client -- here, we'll just list some issues
		github
		.on "error", (error) ->
		console.log error
		.issues owner: "pandastrike", repo: "shred"
		.list()
		.on "ready", (issues) ->
		for {number, title} in issues
		console.log number, title

		# Basic Usage

		First we need to require the Shred library and instantiate a new client.
		# let's create a new ticket...
		# this requires authorization
		github
		.issues owner: "pandastrike", repo: "shred"
		.create
		.authorize basic: { username: token, password: ""}
		.invoke
		title: "Create a Shred T-shirt Design"
		body: "We need a cool logo so we can go into the
		T-shirt business like Docker."
		labels: [ "ng" ]

		Browser:
		```

		var Shred = require("./shred");
		var shred = new Shred();
		# Install

		Node.js:
		<del>`npm install shred`</del>

		var Shred = require("shred");
		var shred = new Shred();
		The 1.0.x version of Shred is not yet available as an NPM. You'll have to `git clone` it and then `npm link` to it.

		Then we are ready to use `shred` to make HTTP requests.
		# Introduction

		## Simple GET request
		Shred exports one function: `resource`. That's it.

		Here is a simple GET request that gets some JSON data.
		The `resource` function takes a URL and an optional interface and returns a resource. Resources, in turn, are objects, imbued with the interface you specify, that can also be invoked as functions to create subsidiary resources.

		Let's start with a simple example. Let's just create a resource for the github API:

		```javascript
		var req = shred.get({
		url: "http://api.spire.io/",
		headers: {
		Accept: "application/json"
		},
		on: {
		// You can use response codes as events
		200: function(response) {
		// Shred will automatically JSON-decode response bodies that have a
		// JSON Content-Type
		console.log(response.content.data);
		},
		// Any other response means something's wrong
		response: function(response) {
		console.log("Oh no!");
		}
		}
		});
		```coffeescript
		github = resource "api.github.com"
		```

		## Response Handling
		By itself, that isn't very useful. But we can create a subsidiary resource for a repo:

		Shred uses HTTP status codes as event names.
		The above example has a handler for when the response comes back with status 200, and a catch-all "request" handler for all other cases.
		```coffeescript
		shred_repo = github "repos/pandastrike/shred"
		```

		You can also add listeners to the "success" event, the "error" event, and the most generic "response" event.
		Shred makes sure that only the most specific event handler gets called for a response.
		That's still not very useful, because we haven't provided our resource with an interface. But it illustrates the idea that resources are functions that generate subsidiary resources.

		## JSON Decoding
		Let's create an interface for listing issues in our repo:

		Shred will automatically decode JSON bodies if the response headers' Content-Type identifies it as JSON.
		Thus, we are able to get the to the decoded object with `response.content.data`.
		The original string representation is still available to us, in `response.content.body`.
		```coffeescript
		shred_issues = shred_repo "issues",
		list:
		method: "get"
		headers:
		accept: "application/vnd.github.v3.raw+json"
		expect: 200
		```

		Here is a POST to an accounts resource.
		Shred will automatically JSON-encode the POST body.
		We have handlers for the 201 "Created" status, 409 "Conflict" status, and a catch-all "response" handler.
		This imbues our new resource with an interface with one method: `list`. We've described that method based on Github's API docs. So now we can just call it like an ordinary method:

		## Simple POST request

		```javascript
		var req = shred.post({
		url: "http://localhost:8080/accounts",
		headers: {
		Content-Type: "application/json"
		},
		// Shred will JSON-encode PUT/POST bodies
		content: { username: "fred", email: "fred@flinstone.com" },
		on: {
		// you can use response codes as events
		201: function(response) {
		console.log("User Created");
		},
		409: function (response) {
		console.log("User with that name already exists.");
		},
		response: function(response) {
		// We got a 40X that is not a 409, or a 50X
		console.log("Oh no, something went wrong!");
		}
		}
		});
		```coffeescript
		shred_issues.list()
		.on "success", (response) ->
		# do something with the response
		.on "error", (error) ->
		# do something with the error
		```

		You can pass listeners directly into the shred request call, as in the above examples, or add listeners to the request with the `on` method:
		That's nice, but it's a bit tedious if we have to do this every time we want to look at the issues for a new repo. We can use URI templates ([RFC 6570][1]) to make this easier to do.

		```javascript
		req.on({
		404: function(response) {
		console.log("Not Found");
		},
		500: function(response) {
		console.log("Server Error, please try again later.");
		}
		});
		```
		```coffeescript
		repo = github "repos/{owner}/{repo}"

		You can also chain the events with 'on', if that's your style.

		```javascript
		req.on(
		404,
		function(response) {
		console.log("Not Found");
		}).on(500 function(response) {
		console.log("Server Error, please try again later.");
		});
		shred_repo = repo owner: "pandastrike", repo: "shred"
		```

		See [the wiki](https://github.com/automatthew/shred/wiki) for more examples.
		[1]:http://tools.ietf.org/html/rfc6570

		Also, we wrote [a blog post][blog] on why we wrote Shred instead of going with existing libraries.
		## Initializer Functions

		# Interface
		So that's nice, but we can do even better. We can decorate the `github` resource with this `repo` property, instead of having to define it separately. Instead of defining a description of a request, we simply provide an initializer function. The return value of the initializer function is the property's value.

		Shred has 4 methods: `shred.get`, `shred.put`, `shred.delete`, and `shred.post`.
		```coffeescript
		github = resource "api.github.com",
		repo: (resource) ->
		resource "repos/{owner}/{repo}"

		## Request Options
		shred_repo = github.repo owner: "pandastrike", repo: "shred"
		```

		* `url`: url to make the request to
		* `headers`: hash of headers to send with the request
		* `port`: port to send the request to
		* `query`: hash or string to send as the query parameters
		* `content`: data to send in the body of the request (also aliased to `body`)
		* `timeout`: length of time in ms (or a date structure with hours/minutes/seconds/millis) to wait before killing the connection
		* `proxy`: url of http proxy to use
		## Nested Interfaces

		## Even more examples!
		In this case, we've defined the `repo` method to be our repo resource, which we can now call as a method on the `github` resources.

		### timeouts
		We nest these definitions. Let's add the issues resource:

		```javascript
		var req = shred.get({
		url: "http://api.spire.io/",
		timeout: 1000, // time out in just 1 second
		on: {
		response: function(response) {
		console.log(response.content.data);
		},
		// let's watch for a timeout
		timeout: function( request ) {
		// note: we get the request here, not the response (since there was no response, silly!)
		console.log( 'Ooops, we timed out!' );
		}
		}
		});
		```coffeescript
		github = resource "api.github.com",
		repo: (resource) ->
		resource "repos/{owner}/{repo}/",
		issues: (resource) ->
		resource "issues",
		list:
		method: "get"
		headers:
		accept: "application/vnd.github.v3.raw+json"
		expect: 200

		// or we can pass an object with values like 'minutes', 'seconds' and 'milliseconds'
		var req = shred.get({
		url: "http://api.spire.io/",
		timeout: { minutes: 1, seconds: 30 }, // time out in 1 minute and 30 seconds
		on: {
		response: function(response) {
		console.log(response.content.data);
		},
		// let's watch for a timeout
		timeout: function( request ) {
		console.log( 'Ooops, we timed out!' );
		}
		}
		});
		shred_repo = github.repo owner: "pandastrike", repo: "shred"
		shred_repo.issues.list()
		.on "success", (response) ->
		# do something with the response
		.on "error", (error) ->
		# do something with the error

		```

		## Events
		In short, we've basically created Github client that we can now use however we please. Of course, it's not terribly useful because it only lets us list the issues of a repo. We'd have to add more methods to make it truly useful.

		Shred will fire an event with the status code of the response, if that event has any listeners.
		If the status code has no listeners, Shred will fire the "success" event or the "error" event, depending on whether the http response is a success (2XX) or error (4XX and 5XX).
		If the success/error event has no listeners, Shred will fire the most generic "response" event.
		Still, it's a very convenient interface and it's easy to see how we can describe any API this way.

		Shred will also emit a "request_error" event if the request errors out before a response comes back.
		## Default Error Handlers

		## Response
		Subordinate resources propagate success and error events up to their parent resources. So we can add a default error handler to our top-level resource and simplify the logic in the rest of code.

		The response is passed as the only argument to the event listeners.
		It has the following properties.
		```coffeescript
		github = resource "api.github.com",
		repo: (resource) ->
		resource "repos/{owner}/{repo}/",
		issues: (resource) ->
		resource "issues",
		list:
		method: "get"
		headers:
		accept: "application/vnd.github.v3.raw+json"
		expect: 200
		.on "error", (error) -> console.error error

		* `response.status`: status code of the response
		* `response.isError`: true iff the status code is >= 400
		* `response.content.body`: string representation of the response body
		* `response.content.data`: javascript object for the response body (if the Content-Type is JSON)
		github
		.repo owner: "pandastrike", repo: "shred"
		.issues
		.list()
		# we don't need an error handler here unless we're going to do
		# something more interesting than the default...
		.on "success", (response) ->
		# do something with the response
		```

		# Curl Logging
		## The `ready` Event

		Shred can log all of the requests it makes as [curl][curl] commands.
		You can use this to make requests from the command line with curl.
		Sometimes, we don't want to have to parse the body response ourselves. Shred gives us a `ready` event to use when the response body is ready. In fact, if the content type is JSON-based, Shred parses it for you.

		To enable this logging, set the `logCurl` option when initializing Shred.

		var shred = new Shred({ logCurl: true });

		Here is sample output from a shred request:

		curl -X GET http://localhost:1337 -H "Accept: application/json"


		# Feedback

		Feedback is highly encouraged in the form of [tickets][tickets] or pull requests. Thank you!

		# Code

		[Browse the annotated source.][docs]

		We'd love your contributions - don't hesitate to send us pull requests. We'll also happily add you as a committer after we've accepted it.

		# Tests

		You can run the tests in node with

		cake test

		There is currently no way to run the tests in the browser (coming soon...)


		# License

		Shred is MIT licensed.

		# Authors

		Shred is based on code originally written by Matthew King.
		That code was adapted and converted into a separate Node.js library by Dan Yoder, Jason Campbell, Nick LaCasse, and Vicent Piquer Suria.

		Current maintainers: [Dan Yoder][yoder], [Matthew King][king]

		[code]: https://github.com/automatthew/shred
		[tickets]: https://github.com/automatthew/shred/issues
		[license]: https://github.com/automatthew/shred/blob/master/LICENSE
		[yoder]: mailto:daniel.yoder@gmail.com
		[king]: mailto:automatthew@gmail.com
		[curl]: http://curl.haxx.se/
		[blog]: http://webcache.googleusercontent.com/search?q=cache:6RFaj1yLIZEJ:www.spire.io/posts/introducing-shred.html+http://www.spire.io/posts/introducing-shred.html&cd=1&hl=en&ct=clnk&gl=us
		```coffeescript
		github
		.repo owner: "pandastrike", repo: "shred"
		.issues
		.list()
		.on "ready", (issues) ->
		console.log number, title for {number, title} in issues

lib/shred.js

lib/shred/content.js

lib/shred/mixins/headers.js

lib/shred/parseUri.js

lib/shred/request.js

lib/shred/response.js

shred - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics

Dependency changes