DefinitelyTyped/restify/index.d.ts

// Type definitions for node.js REST framework 2.0
// Project: https://github.com/mcavage/node-restify
// Definitions by: Bret Little <https://github.com/blittle>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/// <reference types="node" />

import http = require('http');
import Logger = require('bunyan');
import url = require('url');


interface addressInterface {
    port: number;
    family: string;
    address: string;
}

interface requestFileInterface {
    path: string;
    type: string;
}

/**
 * Comes from authorizationParser plugin
 */
interface requestAuthorization {
    scheme: string;
    credentials: string;
    basic?: {
        username: string;
        password: string;
    }
}

interface Request extends http.IncomingMessage {
    /**
     * builds an absolute URI for the request.
     * @private
     * @function absoluteUri
     * @param    {String} path a url path
     * @returns  {String}
     */
    absoluteUri: (path: string) => string;

    /**
     * returns any header off the request. also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     * @public
     * @function header
     * @param    {String} name  the name of the header
     * @param    {String} value default value if header isn't found on the req
     * @returns  {String}
     */
    header: (name: string, value?: string) => string;

    /**
     * returns any trailer header off the request. also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     * @public
     * @function trailer
     * @param    {String} name  the name of the header
     * @param    {String} value default value if header isn't found on the req
     * @returns  {String}
     */
    trailer: (name: string, value?: string) => string;

    /**
     * checks if the accept header is present and has the value requested.
     * e.g., req.accepts('html');
     * @public
     * @function accepts
     * @param    {String | Array} types an array of accept type headers
     * @returns  {Boolean}
     */
    accepts: (types: string | string[]) => boolean;

    /**
     * checks if the request accepts the encoding types.
     * @public
     * @function acceptsEncoding
     * @param    {String | Array} types an array of accept type headers
     * @returns  {Boolean}
     */
    acceptsEncoding: (types: string | string[]) => boolean;

    /**
     * Check if the incoming request contains the Content-Type header field, and
     * if it contains the given mime type.
     * @public
     * @function is
     * @param    {String} type  a content-type header value
     * @returns  {Boolean}
     */
    is: (type: string) => boolean;

    /**
     * Check if the incoming request is chunked.
     * @public
     * @function isChunked
     * @returns  {Boolean}
     */
    isChunked: () => boolean;

    /**
     * Check if the incoming request is kept alive.
     * @public
     * @function isKeepAlive
     * @returns  {Boolean}
     */
    isKeepAlive: () => boolean;

    /**
     * Check if the incoming request has been upgraded.
     * @public
     * @function isUpgradeRequest
     * @returns  {Boolean}
     */
    isUpgradeRequest: () => boolean;

    /**
     * Check if the incoming request is an upload verb.
     * @public
     * @function isUpload
     * @returns  {Boolean}
     */
    isUpload: () => boolean;

    /**
     * retrieves the user-agent header.
     * @public
     * @function userAgent
     * @returns  {String}
     */
    userAgent: () => string;

    /**
     * Start the timer for a request handler function. You must explicitly invoke
     * endHandlerTimer() after invoking this function. Otherwise timing information
     * will be inaccurate.
     * @public
     * @function startHandlerTimer
     * @param    {String}    handlerName The name of the handler.
     * @returns  {undefined}
     */
    startHandlerTimer: (handlerName: string) => void;

    /**
     * Stop the timer for a request handler function.
     * @public
     * @function endHandlerTimer
     * @param    {String}    handlerName The name of the handler.
     * @returns  {undefined}
     */
    endHandlerTimer: (handlerName: string) => void;

    getLogger: (component: string) => any;

    /**
     * gets the content-length header off the request.
     * @public
     * @function getContentLength
     * @returns {Number}
     */
    getContentLength: () => number;

    /**
     * @see getContentLength
     * @function contentLength
     */
    contentLength: () => number;

    /**
     * gets the content-type header.
     * @public
     * @function getContentType
     * @returns {String}
     */
    getContentType: () => string;

    /**
     * @see getContentType
     */
    contentType: () => string;

    /**
     * retrieves the complete URI requested by the client.
     * @public
     * @function getHref
     * @returns {String}
     */
    getHref: () => string;

    /**
     * @see getHref
     */
    href: () => string;

    log: Logger;
    /**
     * retrieves the request uuid. was created when the request was setup.
     * @public
     * @function getId
     * @returns  {String}
     */
    getId: () => string;

    /**
     * @see getId
     */
    id: () => string;

    /**
     * retrieves the cleaned up url path.
     * e.g., /foo?a=1  =>  /foo
     * @public
     * @function getPath
     * @returns  {String}
     */
    getPath: () => string;

    /**
     * @see getPath
     */
    path: () => string;

    /**
     * returns the raw query string
     * @public
     * @function getQuery
     * @returns  {String}
     */
    getQuery: () => string;

    /**
     * @see getQuery
     */
    query: () => string;
    secure: boolean;

    /**
      * returns ms since epoch when request was setup.
      * @public
      * @function time
      * @returns  {Number}
      */
    time: () => number;

    /**
     * returns a parsed URL object.
     * @public
     * @function getUrl
     * @returns  {Object}
     */
    getUrl: () => url.Url;

    /**
     * returns the accept-version header.
     * @public
     * @function getVersion
     * @returns  {String}
     */
    getVersion: () => string;

    /**
     * @see getVersion
     */
    version: () => string;
    params: any;
    files?: { [name: string]: requestFileInterface };

    /**
     * Check if the incoming request is encrypted.
     * @public
     * @function isSecure
     * @returns  {Boolean}
     */
    isSecure: () => boolean;
    /** available when bodyParser plugin is used */
    body?: any;
    /** available when authorizationParser plugin is used */
    username?: string;
    /** available when authorizationParser plugin is used */
    authorization?: requestAuthorization;

    timers: HandlerTiming[];
}

/**
 * Timer object used to identify how long a specific handler took to run
 *
 * @property {String} name The name of the handler.
 * @property {Array} time A tuple of [seconds, nanoseconds], how long the handler took.
 */
interface HandlerTiming {
    name: string;
    time: [number, number];
}

interface Response extends http.ServerResponse {
    header: (key: string, value?: any) => any;
    cache: (type?: any, options?: Object) => any;
    status: (code: number) => any;
    send: (status?: any, body?: any, headers?: { [header: string]: string }) => any;
    json: (status?: any, body?: any, headers?: { [header: string]: string }) => any;
    code: number;
    contentLength: number;
    charSet(value: string): void;
    contentType: string;
    headers: Object;
    id: string;
}

interface RouteSpec {
    method: string;
    name: string;
    path: string | RegExp;
    versions: string[];
}

interface Route {
    name: string;
    method: string;
    path: RoutePathRegex;
    spec: RouteSpec;
    types: string[];
    versions: string[];
}

interface RouteOptions {
    name: string;
    method: string;
    path?: string | RegExp;
    url?: string | RegExp;
    urlParamPattern?: RegExp;
    contentType?: string | string[];
    versions?: string | string[];
}

interface RoutePathRegex extends RegExp {
    restifyParams: string[];
}

interface Router {
    name: string;
    mounts: { [routeName: string]: Route };
    versions: string[];
    contentType: string[];
    routes: {
        DELETE: Route[];
        GET: Route[];
        HEAD: Route[];
        OPTIONS: Route[];
        PATCH: Route[];
        POST: Route[];
        PUT: Route[];
    };
    log?: any;
    toString: () => string;

    /**
     * Takes an object of route params and query params, and 'renders' a URL
     * @param    {String} routeName the route name
     * @param    {Object} params    an object of route params
     * @param    {Object} query     an object of query params
     * @returns  {String}
     */
    render: (routeName: string, params: Object, query?: Object) => string;

    /**
     * adds a route.
     * @param    {Object} options an options object
     * @returns  {String}         returns the route name if creation is successful.
     */
    mount: (options: Object) => string | boolean;

    /**
     * unmounts a route.
     * @param    {String} name the route name
     * @returns  {String}      the name of the deleted route (or false if it was not matched)
     */
    unmount: (name: string) => string | boolean;

    /**
     * finds the route for a given request and response.
     * @param    {Request}  req      the request object
     * @param    {Response} res      the response object
     * @param    {Function} callback operation callback
     * @returns  {undefined}
     */
    find: (req: Request, res: Response, callback: (err: Error, route: Route) => void) => void;
}

interface Server extends http.Server {
    use(handler: RequestHandler, ...handlers: RequestHandler[]): Server;
    use(handler: RequestHandler[], ...handlers: RequestHandler[]): Server;
    use(handler: RequestHandler, ...handlers: RequestHandler[][]): Server;
    use(handler: RequestHandler[], ...handlers: RequestHandler[][]): Server;

    post(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    post(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    post(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    post(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    patch(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    patch(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    patch(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    patch(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    put(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    put(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    put(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    put(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    del(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    del(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    del(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    del(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    get(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    get(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    get(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    get(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    head(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    head(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    head(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    head(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    opts(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[]): string;
    opts(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[]): string;
    opts(route: any, routeCallBack: RequestHandler, ...routeCallBacks: RequestHandler[][]): string;
    opts(route: any, routeCallBack: RequestHandler[], ...routeCallBacks: RequestHandler[][]): string;

    name: string;
    version: string;
    log: Object;
    acceptable: string[];
    url: string;
    address: () => addressInterface;
    listen(...args: any[]): any;
    close(...args: any[]): any;
    pre(routeCallBack: RequestHandler): Server;
    server: http.Server;
    router: Router;
    routes: Route[];
    toString: () => string;
}

interface ServerOptions {
    certificate?: string;
    key?: string;
    formatters?: Object;
    log?: Object;
    name?: string;
    spdy?: Object;
    version?: string;
    responseTimeHeader?: string;
    responseTimeFormatter?: (durationInMilliseconds: number) => any;
    handleUpgrades?: boolean;
    router?: Router;
    httpsServerOptions?: any;
}

interface ClientOptions {
    accept?: string;
    connectTimeout?: number;
    requestTimeout?: number;
    dtrace?: Object;
    gzip?: Object;
    headers?: Object;
    log?: Object;
    retry?: Object;
    signRequest?: Function;
    url?: string;
    userAgent?: string;
    version?: string;
}

interface Client {
    get: (opts: string | { path?: string; [name: string]: any }, callback?: (err: any, req: Request, res: Response, obj: any) => any) => any;
    head: (opts: string | { path?: string; [name: string]: any }, callback?: (err: any, req: Request, res: Response) => any) => any;
    post: (opts: string | { path?: string; [name: string]: any }, object: any, callback?: (err: any, req: Request, res: Response, obj: any) => any) => any;
    put: (opts: string | { path?: string; [name: string]: any }, object: any, callback?: (err: any, req: Request, res: Response, obj: any) => any) => any;
    patch: (opts: string | { path?: string; [name: string]: any }, object: any, callback?: (err: any, req: Request, res: Response, obj: any) => any) => any;
    del: (opts: string | { path?: string; [name: string]: any }, callback?: (err: any, req: Request, res: Response) => any) => any;
    basicAuth: (username: string, password: string) => any;
}

interface HttpClient extends Client {
    get: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
    head: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
    post: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
    put: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
    patch: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
    del: (opts?: string | { path?: string; [name: string]: any }, callback?: Function) => any;
}

interface ThrottleOptions {
    burst?: number;
    rate?: number;
    ip?: boolean;
    xff?: boolean;
    username?: boolean;
    tokensTable?: Object;
    maxKeys?: number;
    overrides?: Object;
}

interface Next {
    (err?: any): any;
    ifError?: (err?: any) => any;
}

interface RequestHandler {
    (req: Request, res: Response, next: Next): any;
}

interface CORS {
    (cors?: {
        origins?: string[];
        credentials?: boolean;
        headers?: string[];
    }): RequestHandler;
    origins: string[];
    ALLOW_HEADERS: string[];
    credentials: boolean;
}

export function createServer(options?: ServerOptions): Server;

export function createJsonClient(options?: ClientOptions): Client;
export function createStringClient(options?: ClientOptions): Client;
export function createClient(options?: ClientOptions): HttpClient;

export class HttpError { constructor(cause: any, message?: any); }

declare class DefiniteHttpError {
    constructor(message?: any);
    constructor(cause: any, message?: any);
}

export class BadRequestError extends DefiniteHttpError { }
export class UnauthorizedError extends DefiniteHttpError { }
export class PaymentRequiredError extends DefiniteHttpError { }
export class ForbiddenError extends DefiniteHttpError { }
export class NotFoundError extends DefiniteHttpError { }
export class MethodNotAllowedError extends DefiniteHttpError { }
export class NotAcceptableError extends DefiniteHttpError { }
export class ProxyAuthenticationRequiredError extends DefiniteHttpError { }
export class RequestTimeoutError extends DefiniteHttpError { }
export class ConflictError extends DefiniteHttpError { }
export class GoneError extends DefiniteHttpError { }
export class LengthRequiredError extends DefiniteHttpError { }
export class RequestEntityTooLargeError extends DefiniteHttpError { }
export class RequesturiTooLargeError extends DefiniteHttpError { }
export class UnsupportedMediaTypeError extends DefiniteHttpError { }
export class RequestedRangeNotSatisfiableError extends DefiniteHttpError { }
export class ExpectationFailedError extends DefiniteHttpError { }
export class ImATeapotError extends DefiniteHttpError { }
export class UnprocessableEntityError extends DefiniteHttpError { }
export class LockedError extends DefiniteHttpError { }
export class FailedDependencyError extends DefiniteHttpError { }
export class UnorderedCollectionError extends DefiniteHttpError { }
export class UpgradeRequiredError extends DefiniteHttpError { }
export class PreconditionRequiredError extends DefiniteHttpError { }
export class TooManyRequestsError extends DefiniteHttpError { }
export class RequestHeaderFieldsTooLargeError extends DefiniteHttpError { }
export class InternalServerError extends DefiniteHttpError { }
export class NotImplementedError extends DefiniteHttpError { }
export class BadGatewayError extends DefiniteHttpError { }
export class ServiceUnavailableError extends DefiniteHttpError { }
export class GatewayTimeoutError extends DefiniteHttpError { }
export class HttpVersionNotSupportedError extends DefiniteHttpError { }
export class VariantAlsoNegotiatesError extends DefiniteHttpError { }
export class InsufficientStorageError extends DefiniteHttpError { }
export class BandwidthLimitExceededError extends DefiniteHttpError { }
export class NotExtendedError extends DefiniteHttpError { }
export class NetworkAuthenticationRequiredError extends DefiniteHttpError { }
export class RestError extends DefiniteHttpError { }

export class PreconditionFailedError extends RestError { }
export class BadDigestError extends RestError { }
export class BadMethodError extends RestError { }
export class InternalError extends RestError { }
export class InvalidArgumentError extends RestError { }
export class InvalidContentError extends RestError { }
export class InvalidCredentialsError extends RestError { }
export class InvalidHeaderError extends RestError { }
export class InvalidVersionError extends RestError { }
export class MissingParameterError extends RestError { }
export class NotAuthorizedError extends RestError { }
export class RequestExpiredError extends RestError { }
export class RequestThrottledError extends RestError { }
export class ResourceNotFoundError extends RestError { }
export class WrongAcceptError extends RestError { }


export function acceptParser(parser: any): RequestHandler;
export function authorizationParser(): RequestHandler;
export function dateParser(skew?: number): RequestHandler;
export function queryParser(options?: Object): RequestHandler;
export function urlEncodedBodyParser(options?: Object): RequestHandler[];
export function jsonp(): RequestHandler;
export function gzipResponse(options?: Object): RequestHandler;
export function bodyParser(options?: Object): RequestHandler[];
export function requestLogger(options?: Object): RequestHandler;
export function serveStatic(options?: Object): RequestHandler;
export function throttle(options?: ThrottleOptions): RequestHandler;
export function conditionalRequest(): RequestHandler[];
export function auditLogger(options?: Object): Function;
export function fullResponse(): RequestHandler;
export var defaultResponseHeaders: any;
export var CORS: CORS;

export module pre {
    export function pause(): RequestHandler;
    export function sanitizePath(options?: any): RequestHandler;
    export function userAgentConnection(options?: any): RequestHandler;
}