change req.is() to return the canonical mime type

docs/api/request.md

@@ -154,22 +154,33 @@ this.body = yield db.find('something');
 
   Check if the incoming request contains the "Content-Type"
   header field, and it contains any of the give mime `type`s.
-  If there is no request body, `null` is returned.
+  If there is no request body, `undefined` is returned.
-  If there is no content type, `false` is returned.
+  If there is no content type, or the match fails `false` is returned.
-  Otherwise, it returns the first `type` that matches.
+  Otherwise, it returns the matching content-type.
 
 ```js
 // With Content-Type: text/html; charset=utf-8
 this.is('html'); // => 'html'
 this.is('text/html'); // => 'text/html'
-this.is('text/*', 'text/html'); // => 'text/*'
+this.is('text/*', 'text/html'); // => 'text/html'
 
 // When Content-Type is application/json
 this.is('json', 'urlencoded'); // => 'json'
 this.is('application/json'); // => 'application/json'
-this.is('html', 'application/*'); // => 'application/*'
+this.is('html', 'application/*'); // => 'application/json'
 
 this.is('html'); // => false
+```
+
+  For example if you want to ensure that
+  only images are sent to a given route:
+
+```js
+if (this.is('image/*')) {
+  // process
+} else {
+  this.throw(415, 'images only!');
+}
 ```
 
 ### req.accepts(types)

lib/request.js

@@ -497,12 +497,12 @@ module.exports = {
    *     // With Content-Type: text/html; charset=utf-8
    *     this.is('html'); // => 'html'
    *     this.is('text/html'); // => 'text/html'
-   *     this.is('text/*', 'application/json'); // => 'text/*'
+   *     this.is('text/*', 'application/json'); // => 'text/html'
    *
    *     // When Content-Type is application/json
    *     this.is('json', 'urlencoded'); // => 'json'
    *     this.is('application/json'); // => 'application/json'
-   *     this.is('html', 'application/*'); // => 'application/*'
+   *     this.is('html', 'application/*'); // => 'application/json'
    *
    *     this.is('html'); // => false
    *
@@ -538,7 +538,7 @@ module.exports = {
           mt = ~type.indexOf('/') ? type : mime.lookup(type);
       }
 
-      if (mimeMatch(mt, ct)) return type;
+      if (mimeMatch(mt, ct)) return ct;
     }
 
     // no matches

test/request/is.js

@@ -1,6 +1,7 @@
 
-var should = require('should');
 var context = require('../context');
+var should = require('should');
+var assert = require('assert');
 
 describe('ctx.is(type)', function(){
   it('should ignore params', function(){
@@ -8,16 +9,16 @@ describe('ctx.is(type)', function(){
     ctx.header['content-type'] = 'text/html; charset=utf-8';
     ctx.header['transfer-encoding'] = 'chunked';
 
-    ctx.is('text/*').should.equal('text/*');
+    ctx.is('text/*').should.equal('text/html');
   })
 
   describe('when no body is given', function(){
     it('should return null', function(){
       var ctx = context();
 
-      should(ctx.is()).null;
+      assert(null == ctx.is());
-      should(ctx.is('image/*')).null;
+      assert(null == ctx.is('image/*'));
-      should(ctx.is('text/*', 'image/*')).null;
+      assert(null == ctx.is('image/*', 'text/*'));
     })
   })
 
@@ -48,11 +49,11 @@ describe('ctx.is(type)', function(){
       ctx.header['content-type'] = 'image/png';
       ctx.header['transfer-encoding'] = 'chunked';
 
-      ctx.is('png').should.equal('png');
+      ctx.is('png').should.equal('image/png');
-      ctx.is('.png').should.equal('.png');
+      ctx.is('.png').should.equal('image/png');
       ctx.is('image/png').should.equal('image/png');
-      ctx.is('image/*').should.equal('image/*');
+      ctx.is('image/*').should.equal('image/png');
-      ctx.is('*/png').should.equal('*/png');
+      ctx.is('*/png').should.equal('image/png');
 
       ctx.is('jpeg').should.be.false;
       ctx.is('.jpeg').should.be.false;
@@ -68,11 +69,11 @@ describe('ctx.is(type)', function(){
       ctx.header['content-type'] = 'image/png';
       ctx.header['transfer-encoding'] = 'chunked';
 
-      ctx.is('png').should.equal('png');
+      ctx.is('png').should.equal('image/png');
-      ctx.is('.png').should.equal('.png');
+      ctx.is('.png').should.equal('image/png');
-      ctx.is('text/*', 'image/*').should.equal('image/*');
+      ctx.is('text/*', 'image/*').should.equal('image/png');
-      ctx.is('image/*', 'text/*').should.equal('image/*');
+      ctx.is('image/*', 'text/*').should.equal('image/png');
-      ctx.is('image/*', 'image/png').should.equal('image/*');
+      ctx.is('image/*', 'image/png').should.equal('image/png');
       ctx.is('image/png', 'image/*').should.equal('image/png');
 
       ctx.is('jpeg').should.be.false;
@@ -83,14 +84,14 @@ describe('ctx.is(type)', function(){
   })
 
   describe('when Content-Type: application/x-www-form-urlencoded', function(){
-    it('should match `urlencoded', function(){
+    it('should match "urlencoded"', function(){
       var ctx = context();
       ctx.header['content-type'] = 'application/x-www-form-urlencoded';
       ctx.header['transfer-encoding'] = 'chunked';
 
-      ctx.is('urlencoded').should.equal('urlencoded');
+      ctx.is('urlencoded').should.equal('application/x-www-form-urlencoded');
-      ctx.is('json', 'urlencoded').should.equal('urlencoded');
+      ctx.is('json', 'urlencoded').should.equal('application/x-www-form-urlencoded');
-      ctx.is('urlencoded', 'json').should.equal('urlencoded');
+      ctx.is('urlencoded', 'json').should.equal('application/x-www-form-urlencoded');
     })
   })
 })