DefinitelyTyped/koa/koa-1.1.2.d.ts

// Type definitions for koa v1.1.2
// Project: https://github.com/koajs/koa
// Definitions by: jKey Lu <https://github.com/jkeylu>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/* =================== USAGE ===================

    import * as Koa from 'koa;
    var app = new Koa();

 =============================================== */

/// <reference path="../node/node.d.ts" />
/// <reference path="../cookies/cookies.d.ts" />

declare namespace Koa {

    // These open interfaces may be extended in an application-specific manner via declaration merging.
    // See for example method-override.d.ts (https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/method-override/method-override.d.ts)
    export interface Request { }
    export interface Response { }
    export interface Application { }
}

declare module "koa" {
    import * as net from 'net';
    import * as http from 'http';
    import * as events from 'events';
    import * as Cookies from 'cookies';

    interface IRequest extends Koa.Request {
            /**
             * Return request header.
             *
             * @readonly
             */
            header: any;
            /**
             * Return request header, alias as request.header
             *
             * @readonly
             */
            headers: any;
            /**
             * Get/Set request URL.
             */
            url: string;
            /**
             * Get origin of URL.
             */
            origin: string;
            /**
             * Get full request URL.
             *
             * @readonly
             */
            href: string;
            /**
             * Get/Set request method.
             */
            method: string;
            /**
             * Get request pathname.
             * Set pathname, retaining the query-string when present.
             */
            path: string;
            /**
             * Get parsed query-string.
             * Set query-string as an object.
             */
            query: any;
            /**
             * Get/Set query string.
             */
            querystring: string;
            /**
             * Get the search string. Same as the querystring except it includes the leading ?.
             * Set the search string. Same as response.querystring= but included for ubiquity.
             */
            search: string;
            /**
             * Parse the "Host" header field host and support X-Forwarded-Host when a proxy is enabled.
             *
             * @readonly
             */
            host: string;
            /**
             * Parse the "Host" header field hostname and support X-Forwarded-Host when a proxy is enabled.
             *
             * @readonly
             */
            hostname: string;
            /**
             * Check if the request is fresh, aka
             * Last-Modified and/or the ETag
             * still match.
             *
             * @readonly
             */
            fresh: boolean;
            /**
             * Check if the request is stale, aka
             * "Last-Modified" and / or the "ETag" for the
             * resource has changed.
             *
             * @readonly
             */
            stale: boolean;
            /**
             * Check if the request is idempotent.
             *
             * @readonly
             */
            idempotent: boolean;
            /**
             * Return the request socket.
             *
             * @readonly
             */
            socket: net.Socket;
            /**
             * Return the protocol string "http" or "https"
             * when requested with TLS. When the proxy setting
             * is enabled the "X-Forwarded-Proto" header
             * field will be trusted. If you're running behind
             * a reverse proxy that supplies https for you this
             * may be enabled.
             *
             * @readonly
             */
            protocol: string;
            /**
             * Short-hand for:
             *
             *    this.protocol == 'https'
             *
             * @readonly
             */
            secure: boolean;
            /**
             * Return the remote address, or when
             * `app.proxy` is `true` return
             * the upstream addr.
             *
             * @readonly
             */
            ip: string;
            /**
             * When `app.proxy` is `true`, parse
             * the "X-Forwarded-For" ip address list.
             *
             * For example if the value were "client, proxy1, proxy2"
             * you would receive the array `["client", "proxy1", "proxy2"]`
             * where "proxy2" is the furthest down-stream.
             *
             * @readonly
             */
            ips: string[];
            /**
             * Return subdomains as an array.
             *
             * Subdomains are the dot-separated parts of the host before the main domain of
             * the app. By default, the domain of the app is assumed to be the last two
             * parts of the host. This can be changed by setting `app.subdomainOffset`.
             *
             * For example, if the domain is "tobi.ferrets.example.com":
             * If `app.subdomainOffset` is not set, this.subdomains is `["ferrets", "tobi"]`.
             * If `app.subdomainOffset` is 3, this.subdomains is `["tobi"]`.
             *
             * @readonly
             */
            subdomains: string[];
            /**
             * Check if the given `type(s)` is acceptable, returning
             * the best match when true, otherwise `undefined`, in which
             * case you should respond with 406 "Not Acceptable".
             *
             * The `type` value may be a single mime type string
             * such as "application/json", the extension name
             * such as "json" or an array `["json", "html", "text/plain"]`. When a list
             * or array is given the _best_ match, if any is returned.
             *
             * Examples:
             *
             *     // Accept: text/html
             *     this.accepts('html');
             *     // => "html"
             *
             *     // Accept: text/*, application/json
             *     this.accepts('html');
             *     // => "html"
             *     this.accepts('text/html');
             *     // => "text/html"
             *     this.accepts('json', 'text');
             *     // => "json"
             *     this.accepts('application/json');
             *     // => "application/json"
             *
             *     // Accept: text/*, application/json
             *     this.accepts('image/png');
             *     this.accepts('png');
             *     // => undefined
             *
             *     // Accept: text/*;q=.5, application/json
             *     this.accepts(['html', 'json']);
             *     this.accepts('html', 'json');
             *     // => "json"
             */
            accepts(...types: string[]): string|boolean|string[];
            accepts(types: string[]): string|boolean|string[];
            /**
             * Return accepted encodings or best fit based on `encodings`.
             *
             * Given `Accept-Encoding: gzip, deflate`
             * an array sorted by quality is returned:
             *
             *     ['gzip', 'deflate']
             */
            acceptsEncodings(...encodings: string[]): string|string[];
            acceptsEncodings(encodings: string[]): string|string[];
            /**
             * Return accepted charsets or best fit based on `charsets`.
             *
             * Given `Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5`
             * an array sorted by quality is returned:
             *
             *     ['utf-8', 'utf-7', 'iso-8859-1']
             */
            acceptsCharsets(...charsets: string[]): string|string[];
            acceptsCharsets(charsets: string[]): string|string[];
            /**
             * Return accepted languages or best fit based on `langs`.
             *
             * Given `Accept-Language: en;q=0.8, es, pt`
             * an array sorted by quality is returned:
             *
             *     ['es', 'pt', 'en']
             */
            acceptsLanguages(...langs: string[]): string|string[];
            acceptsLanguages(langs: string[]): string|string[];
            /**
             * 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 content type, `false` is returned.
             * Otherwise, it returns the first `type` that matches.
             *
             * Examples:
             *
             *     // With Content-Type: text/html; charset=utf-8
             *     this.is('html'); // => 'html'
             *     this.is('text/html'); // => 'text/html'
             *     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/json'
             *
             *     this.is('html'); // => false
             */
            is(type: string): string|boolean;
            is(types: string[]): string|boolean;
            /**
             * Return request header.
             *
             * The `Referrer` header field is special-cased,
             * both `Referrer` and `Referer` are interchangeable.
             *
             * Examples:
             *
             *     this.get('Content-Type');
             *     // => "text/plain"
             *
             *     this.get('content-type');
             *     // => "text/plain"
             *
             *     this.get('Something');
             *     // => undefined
             */
            get(field: string): string;
    }

    interface IResponse extends Koa.Response{
            /**
             * Get/Set response status code.
             */
            status: number;
            /**
             * Get/Set response status message
             */
            message: string;
            /**
             * Get/Set response body.
             */
            body: any;
            /**
             * Return parsed response Content-Length when present.
             * Set Content-Length field to `n`.
             */
            length: number;
            /**
             * Check if a header has been written to the socket.
             *
             * @readonly
             */
            headerSent: boolean;
            /**
             * Vary on `field`.
             */
            vary(field: string): void;
            /**
             * Perform a 302 redirect to `url`.
             *
             * The string "back" is special-cased
             * to provide Referrer support, when Referrer
             * is not present `alt` or "/" is used.
             *
             * Examples:
             *
             *    this.redirect('back');
             *    this.redirect('back', '/index.html');
             *    this.redirect('/login');
             *    this.redirect('http://google.com');
             */
            redirect(url: string): void;
            redirect(url: string, alt: string): void;
            /**
             * Set Content-Disposition header to "attachment" with optional `filename`.
             */
            attachment(filename: string): void;
            /**
             * Return the response mime type void of
             * parameters such as "charset".
             *
             * Set Content-Type response header with `type` through `mime.lookup()`
             * when it does not contain a charset.
             *
             * Examples:
             *
             *     this.type = '.html';
             *     this.type = 'html';
             *     this.type = 'json';
             *     this.type = 'application/json';
             *     this.type = 'png';
             */
            type: string;
            /**
             * Get the Last-Modified date in Date form, if it exists.
             * Set the Last-Modified date using a string or a Date.
             *
             *     this.response.lastModified = new Date();
             *     this.response.lastModified = '2013-09-13';
             */
            lastModified: Date;
            /**
             * Get the ETag of a response.
             * Set the ETag of a response.
             * This will normalize the quotes if necessary.
             *
             *     this.response.etag = 'md5hashsum';
             *     this.response.etag = '"md5hashsum"';
             *     this.response.etag = 'W/"123456789"';
             */
            etag: string;
            /**
             * Set header `field` to `val`, or pass
             * an object of header fields.
             *
             * Examples:
             *
             *    this.set('Foo', ['bar', 'baz']);
             *    this.set('Accept', 'application/json');
             *    this.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
             */
            set(field: any): void;
            set(field: string, val: string): void;
            set(field: string, val: any[]): void;
            /**
             * Append additional header `field` with value `val`.
             *
             * Examples:
             *
             *    this.append('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
             *    this.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
             *    this.append('Warning', '199 Miscellaneous warning');
             */
            append(field: string, val: string): void;
            append(field: string, val: any[]): void;
            /**
             * Remove header `field`.
             */
            remove(field: string): void;
            /**
             * Checks if the request is writable.
             * Tests for the existence of the socket
             * as node sometimes does not set it.
             *
             * @readonly
             * @private
             */
            writable: boolean;
    }

    namespace koa {
        interface BaseRequest extends IRequest {
            /**
             * Get the charset when present or undefined.
             *
             * @readonly
             */
            charset: string;
            /**
             * Return parsed Content-Length when present.
             *
             * @readonly
             */
            length: number;
            /**
             * Return the request mime type void of
             * parameters such as "charset".
             *
             * @readonly
             */
            type: string;
            /**
             * Inspect implementation.
             */
            inspect(): any;
            /**
             * Return JSON representation.
             */
            toJSON(): any;
        }

        interface BaseResponse extends IResponse {
            /**
             * Return the request socket.
             *
             * @readonly
             */
            socket: net.Socket;
            /**
             * Return response header.
             *
             * @readonly
             */
            header: any;
            /**
             * Return response header, alias as response.header
             */
            headers: any;
            /**
             * Check whether the response is one of the listed types.
             * Pretty much the same as `this.request.is()`.
             */
            is(type: string): string|boolean;
            is(types: string[]): string|boolean;
            /**
             * Return response header.
             *
             * Examples:
             *
             *     this.get('Content-Type');
             *     // => "text/plain"
             *
             *     this.get('content-type');
             *     // => "text/plain"
             */
            get(field: string): string;
            /**
             * Inspect implementation.
             */
            inspect(): any;
            /**
             * Return JSON representation.
             */
            toJSON(): any;
        }

        interface BaseContext extends IRequest, IResponse {
            /**
             * util.inspect() implementation, which
             * just returns the JSON output.
             */
            inspect(): any;
            /**
             * Return JSON representation.
             *
             * Here we explicitly invoke .toJSON() on each
             * object, as iteration will otherwise fail due
             * to the getters and cause utilities such as
             * clone() to fail.
             */
            toJSON(): any;
            /**
             * Similar to .throw(), adds assertion.
             *
             *    this.assert(this.user, 401, 'Please login!');
             *
             * See: https://github.com/jshttp/http-assert
             */
            assert(test: any, status: number, message: string): void;
            /**
             * Throw an error with `msg` and optional `status`
             * defaulting to 500. Note that these are user-level
             * errors, and the message may be exposed to the client.
             *
             *    this.throw(403)
             *    this.throw('name required', 400)
             *    this.throw(400, 'name required')
             *    this.throw('something exploded')
             *    this.throw(new Error('invalid'), 400);
             *    this.throw(400, new Error('invalid'));
             *
             * See: https://github.com/jshttp/http-errors
             */
            throw(...args: any[]): void;
            /**
             * Default error handling.
             *
             * @private
             */
            onerror(err: Error): void;
        }

        interface Request extends BaseRequest {
            app: Application;
            ctx: Context;
            response: Response;
            req: http.IncomingMessage;
            res: http.ServerResponse;
        }

        interface Response extends BaseResponse {
            app: Application;
            ctx: Context;
            request: Request;
            req: http.IncomingMessage;
            res: http.ServerResponse;
        }

        interface Context extends BaseContext {
            request: Request;
            response: Response;
            app: Application;
            req: http.IncomingMessage;
            res: http.ServerResponse;
            originalUrl: string;
            cookies: Cookies.ICookies;
            accept: any;
            state: any;
        }

        interface Application extends events.EventEmitter , Koa.Application{
            env: string;
            subdomainOffset: number;
            middleware: any[];
            proxy: boolean;
            context: BaseContext;
            request: BaseRequest;
            response: BaseResponse;
            /**
             * Shorthand for:
             *
             *    http.createServer(app.callback()).listen(...)
             */
            listen(port: number, hostname?: string, backlog?: number, callback?: Function): http.Server;
            listen(port: number, hostname?: string, callback?: Function): http.Server;
            listen(path: string, callback?: Function): http.Server;
            listen(handle: any, listeningListener?: Function): http.Server;
            listen(): http.Server;
            /**
             * Return JSON representation.
             * We only bother showing settings.
             */
            inspect(): any;
            /**
             * Return JSON representation.
             * We only bother showing settings.
             */
            toJSON(): any;
            /**
             * Use the given middleware `fn`.
             */
            use(fn: Function): Application;
            /**
             * Return a request handler callback
             * for node's native http server.
             */
            callback(): (req: http.IncomingMessage, res: http.ServerResponse) => void;
            /**
             * Initialize a new context.
             *
             * @private
             */
            createContext(req: http.IncomingMessage, res: http.ServerResponse): Context;
            /**
             * Default error handler.
             *
             * @private
             */
            onerror(err: Error): void;
        }
    }

    interface KoaStatic {
        new (): koa.Application;
        (): koa.Application;
    }

    var koa: KoaStatic;

    export = koa;
}