caolan/quip

A chainable API for response objects in node

quip

A convenient chainable API for HTTP ServerResponse objects in node.

• Suited to quick and easy prototyping
• Works as a Connect middleware
• Allows you to pipe streams to the response, while easily setting up the headers and status code beforehand

Examples

responding with different status codes

res.ok('<h1>Hello World!</h1>');
res.notFound('Not found');

responding with different mime types

res.text('plain text');
res.json({'stringify': 'this object'});

chaining the two together (in any order)

res.error().json({error: 'something broke'});
res.xml().badRequest('<test></test>');

redirection

res.moved('http://permanent/new/location');
res.redirect('http://temporary/new/location');

custom headers

res.headers({'custom': 'header'}).text('some data');

piping data to a response object

// read posts.xml and pipe to response with mime type application/atom+xml
var feed = fs.createReadStream('posts.xml');
feed.pipe(res.atom());

The response is completed when data is passed to a status code or mime-type function, when a redirect is performed, or when a stream is piped to the response.

Usage

Use quip for specific responses:

var quip = require('quip'),
    http = require('http');

http.createServer(function (req, res) {
    quip(res).ok('example');
});

Enable for all response objects by using quip as a Connect middleware:

var connect = require('connect'),
    quip = require('quip'),

var app = connect(
    quip,
    function (req, res, next) {
        res.ok('example');
    }
);

API

• headers - add custom headers to response, returns updated response object
• status - set status code of response manually, returns updated response

Status Codes

By default, the response will have the status code 200 (OK), this can be updated using the following methods. Note that by passing some data to these methods, the response will complete. If you don't pass data it will return an updated response object, allowing you to chain calls together. If the data passed is an object then it will be treated as JSON and the mime type of the response will be updated accordingly.

Success

• res.ok
• res.created
• res.accepted
• res.noContent

Redirection

• res.moved
• res.redirect
• res.found - alias for redirect
• res.notModified

Client Error

• res.badRequest
• res.unauthorized
• res.forbidden
• res.notFound
• res.notAllowed
• res.conflict
• res.gone

Server Error

• res.error

Mime Types

By default, the response will have the mime-type text/html, this can be updated using the following methods. Note that by passing some data to these methods, the response will complete. If you don't pass data it will return an updated response object, allowing you to chain calls together. You can pass an object to the json and jsonp methods and it will be stringified before sending.

• res.text

• res.plain

• res.html

• res.xhtml

• res.css

• res.xml

• res.atom

• res.rss

• res.javascript

• res.json

• res.jsonp -- JSONP is a special case that always completes the request, and overrides any previous status code calls. There is no reliable way for a browser to interpret JSONP responses with a status code other than 200. Any error or status information should be included in the JSONP response itself. The jsonp method accepts 2 arguments, a callback name (string) and some JSON data (either a string or an object literal).

quip's Issues

Header Modification Failure - Node 0.12

_http_outgoing.js:386
throw new Error('Can\'t render headers after they are sent to the client.'
^
Error: Can't render headers after they are sent to the client.
at ServerResponse.OutgoingMessage._renderHeaders (_http_outgoing.js:386:11)
at ServerResponse.writeHead (_http_server.js:199:20)
at ServerResponse.res.write (C:\apps\swatchr\node_modules\quip\lib\quip.js:1
15:13)
at ServerResponse.OutgoingMessage.end (_http_outgoing.js:544:16)
at Array.write (C:\apps\swatchr\node_modules\connect\node_modules\finalhandl
er\index.js:126:9)
at listener (C:\apps\swatchr\node_modules\connect\node_modules\finalhandler\
node_modules\on-finished\index.js:164:15)
at onFinish (C:\apps\swatchr\node_modules\connect\node_modules\finalhandler\
node_modules\on-finished\index.js:95:5)
at callback (C:\apps\swatchr\node_modules\connect\node_modules\finalhandler\
node_modules\on-finished\node_modules\ee-first\index.js::10)
at IncomingMessage.onevent (C:\apps\swatchr\node_modules\connect\node_module
s\finalhandler\node_modules\on-finished\node_modules\ee-first\index.js:66:5)
at IncomingMessage.emit (events.js:104:17)

Specific test env was Node 0.12.2, using connect 3.3.5, on Windows 7 x64 and Windows 8x64. Since this worked well in Node 0.10, I suspect node 0.12 is the culprit, specifically the http module.

Dependency Issue

FYI - The nodeunit depancy is using your private github url, not the public http:// version. This makes "git submodule update --init --recursive" not function :(

awesome work thought!

TypeScript definitions

It would be nice to include typescript definitions. Something like this:

declare module 'quip' {
  import { IncomingMessage, ServerResponse } from 'http';

  type StatusCode =
    | 200
    | 201
    | 202
    | 204
    | 301
    | 302
    | 304
    | 400
    | 401
    | 403
    | 404
    | 405
    | 409
    | 410
    | 500;

  type RedirectionCode = 301 | 302;

  type ContentType =
    | 'text/plain'
    | 'text/html'
    | 'application/xhtml+xml'
    | 'text/css'
    | 'text/xml'
    | 'application/atom+xml'
    | 'application/rss+xml'
    | 'application/javascript'
    | 'application/json';

  interface QuipExtensions {
    status<T = any>(code: StatusCode): QuipResponse<T>;
    headers<T = any>(headers: { [key: string]: string }): QuipResponse<T>;
    ok<T = any>(): QuipResponseFunction<T>;
    created<T = any>(): QuipResponseFunction<T>;
    accepted<T = any>(): QuipResponseFunction<T>;
    noContent<T = any>(): QuipResponse<T>;
    moved<T = any>(loc: string): QuipResponse<T>;
    redirect<T = any>(loc: string, code?: RedirectionCode): QuipResponse<T>;
    found<T = any>(loc: string): QuipResponse<T>;
    notModified<T = any>(): QuipResponse<T>;
    badRequest<T = any>(): QuipResponseFunction<T>;
    unauthorized<T = any>(): QuipResponseFunction<T>;
    forbidden<T = any>(): QuipResponseFunction<T>;
    notFound<T = any>(): QuipResponseFunction<T>;
    notAllowed<T = any>(): QuipResponseFunction<T>;
    conflict<T = any>(): QuipResponseFunction<T>;
    gone<T = any>(): QuipResponseFunction<T>;
    error<T = any>(): QuipResponseFunction<T>;
    text<T = string>(data?: T): QuipResponse<T>;
    plain<T = string>(data?: T): QuipResponse<T>;
    html<T = string>(data?: T): QuipResponse<T>;
    xhtml<T = string>(data?: T): QuipResponse<T>;
    css<T = string>(data?: T): QuipResponse<T>;
    xml<T = string>(data?: T): QuipResponse<T>;
    atom<T = string>(data?: T): QuipResponse<T>;
    rss<T = string>(data?: T): QuipResponse<T>;
    javascript<T = string>(data?: T): QuipResponse<T>;
    json<T = any>(data?: T): QuipResponse<T>;
    mime<T = any>(type: ContentType, data?: T): QuipResponse<T>;
    jsonp<T = any>(callback: string, data?: T): QuipResponse<T>;
    send<T = any>(data?: T): QuipResponse<T>;
  }

  type QuipResponseFunction<T> = (data?: T) => QuipResponse<T>;

  export type QuipResponse<T = any> = ServerResponse &
    QuipExtensions & { body?: T };

  interface Quip {
    <T = any>(req: IncomingMessage, res: ServerResponse, next: Function): void;
  }

  const quip: Quip;

  export default quip;
}

Quip Moderation Notification Email

The quip core files at core/components/quip/model/quip/quipcomment.class.php at line 253, the $to variable were empty and there’s no coding to set the $to variable to the one that we set in the System Settings.
Hence I added a line of

$to = $this->xpdo->getOption('quip.emailsTo',null,$this->xpdo->getOption('emailsender'));

This is to get the value that we set in System Settings > quip > email > Email To field.

After adding the line of code, the notification email will be send to the email that has been set at the Email To field instead of to all Administrator's user's email.