Merge pull request #14417 from blakeembrey/improve-accepts

Improve `accepts` definition, update `raw-body`

accepts/index.d.ts

@@ -3,29 +3,60 @@
 // Definitions by: Stefan Reichel <https://github.com/bomret>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
-/// <reference types="node" />
-import { IncomingMessage } from "http";
-
 declare namespace accepts {
+    export interface Headers {
+        [key: string]: string | string[];
+    }
+
     export interface Accepts {
-        charset(charsets: string[]): string | string[] | boolean;
-        charset(...charsets: string[]): string | string[] | boolean;
+        /**
+         * Return the first accepted charset. If nothing in `charsets` is accepted, then `false` is returned.
+         */
+        charset(charsets: string[]): string | false;
+        charset(...charsets: string[]): string | false;
+
+        /**
+         * Return the charsets that the request accepts, in the order of the client's preference (most preferred first).
+         */
         charsets(): string[];
 
-        encoding(encodings: string[]): string | string[] | boolean;
-        encoding(...encodings: string[]): string | string[] | boolean;
+        /**
+         * Return the first accepted encoding. If nothing in `encodings` is accepted, then `false` is returned.
+         */
+        encoding(encodings: string[]): string | false;
+        encoding(...encodings: string[]): string | false;
+
+        /**
+         * Return the encodings that the request accepts, in the order of the client's preference (most preferred first).
+         */
         encodings(): string[];
 
-        language(languages: string[]): string | string[] | boolean;
-        language(...languages: string[]): string | string[] | boolean;
+        /**
+         * Return the first accepted language. If nothing in `languages` is accepted, then `false` is returned.
+         */
+        language(languages: string[]): string | false;
+        language(...languages: string[]): string | false;
+
+        /**
+         * Return the languages that the request accepts, in the order of the client's preference (most preferred first).
+         */
         languages(): string[];
 
-        type(types: string[]): string | string[] | boolean;
-        type(...types: string[]): string | string[] | boolean;
+        /**
+         * Return the first accepted type (and it is returned as the same text as what appears in the `types` array). If nothing in `types` is accepted, then `false` is returned.
+         *
+         * The `types` array can contain full MIME types or file extensions. Any value that is not a full MIME types is passed to `require('mime-types').lookup`.
+         */
+        type(types: string[]): string | false;
+        type(...types: string[]): string | false;
+
+        /**
+         * Return the types that the request accepts, in the order of the client's preference (most preferred first).
+         */
         types(): string[];
     }
 }
 
-declare function accepts(req: IncomingMessage): accepts.Accepts;
+declare function accepts(req: { headers: accepts.Headers }): accepts.Accepts;
 
 export = accepts;

raw-body/index.d.ts

@@ -11,24 +11,53 @@ declare namespace getRawBody {
     export type Encoding = string | true;
 
     export interface Options {
-        length?: number;
-        limit?: number;
-        encoding?: Encoding;
+        /**
+         * The length of the stream. If the contents of the stream do not add up to this length, an 400 error code is returned.
+         */
+        length?: number | string | null;
+        /**
+         * The byte limit of the body. This is the number of bytes or any string format supported by `bytes`, for example `1000`, `'500kb'` or `'3mb'`. If the body ends up being larger than this limit, a `413` error code is returned.
+         */
+        limit?: number | string | null;
+        /**
+         * The encoding to use to decode the body into a string. By default, a `Buffer` instance will be returned when no encoding is specified. Most likely, you want `utf-8`, so setting encoding to `true` will decode as `utf-8`. You can use any type of encoding supported by `iconv-lite`.
+         */
+        encoding?: Encoding | null;
     }
 
     export interface RawBodyError extends Error {
+        /**
+         * The limit in bytes.
+         */
         limit?: number;
+        /**
+         * The expected length of the stream.
+         */
         length?: number;
         expected?: number;
+        /**
+         * The received bytes.
+         */
         received?: number;
+        /**
+         * The invalid encoding.
+         */
         encoding?: string;
+        /**
+         * The corresponding status code for the error.
+         */
         status: number;
         statusCode: number;
+        /**
+         * Either `entity.too.large`, `request.aborted`, `request.size.invalid`, `stream.encoding.set`, or `encoding.unsupported`.
+         */
         type: string;
     }
 }
 
-
+/**
+ * Gets the entire buffer of a stream either as a `Buffer` or a string. Validates the stream's length against an expected length and maximum limit. Ideal for parsing request bodies.
+ */
 declare function getRawBody(stream: Readable, callback: (err: getRawBody.RawBodyError, body: Buffer) => void): void;
 declare function getRawBody(stream: Readable, options: (getRawBody.Options & { encoding: getRawBody.Encoding }) | getRawBody.Encoding, callback: (err: getRawBody.RawBodyError, body: string) => void): void;
 declare function getRawBody(stream: Readable, options: getRawBody.Options, callback: (err: getRawBody.RawBodyError, body: Buffer) => void): void;