raw-body/dist/index.d.ts

Get and validate the raw body of a readable stream.

/*!
 * raw-body
 * Copyright(c) 2013-2014 Jonathan Ong
 * Copyright(c) 2014-2022 Douglas Christopher Wilson
 * MIT Licensed
 */
import { Readable } from 'node:stream';
/**
 * The encoding to decode the body with. `true` decodes as `utf-8`.
 */
export type Encoding = string | true;
/**
 * The stream types accepted by `getRawBody`.
 */
export type NodeRawBodyStream = NodeJS.ReadableStream | Readable;
/**
 * The stream types accepted by `getRawBodyWeb`.
 */
export type WebRawBodyStream = ReadableStream<Uint8Array | string>;
/**
 * A streaming decoder, turning body chunks into a string.
 */
export interface Decoder {
    write(chunk: Buffer): string;
    end(): string | undefined;
}
export interface Options {
    /**
     * The expected length of the stream.
     */
    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'`.
     */
    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 encoding supported by `TextDecoder`.
     * `false` (or any other falsy value) disables decoding, returning
     * a `Buffer`.
     */
    encoding?: Encoding | false | null;
    /**
     * A function that receives the encoding and returns the decoder used to
     * turn the body into a string, instead of the built-in `TextDecoder`.
     * Compatible with `iconv-lite`'s `getDecoder`. Throwing signals the
     * encoding is unsupported.
     */
    decoder?: (encoding: string) => Decoder;
}
/**
 * The `type` values of the errors created by `raw-body`.
 */
export type RawBodyErrorType = 'encoding.unsupported' | 'entity.too.large' | 'request.aborted' | 'request.size.invalid' | 'stream.encoding.set' | 'stream.not.readable';
export interface RawBodyError extends Error {
    /**
     * The error code, when there is one, e.g. `ECONNABORTED` for
     * aborted requests.
     */
    code?: string;
    /**
     * The limit in bytes.
     */
    limit?: number;
    /**
     * The expected length of the stream.
     */
    length?: number;
    expected?: number;
    /**
     * The received bytes.
     */
    received?: number;
    /**
     * The encoding.
     */
    encoding?: string;
    /**
     * The corresponding status code for the error. Errors created by
     * `raw-body` always carry one, but errors passed through from the
     * stream or a custom decoder may not.
     */
    status?: number;
    statusCode?: number;
    /**
     * The error type. Set on every error created by `raw-body`, but
     * absent on errors passed through from the stream or a custom
     * decoder.
     */
    type?: RawBodyErrorType;
}
type Callback<T> = (err: RawBodyError | null, body: T) => void;
/**
 * Gets the entire buffer of a node stream as a `Buffer`, delivered to
 * the callback. Validates the stream's length against an expected
 * length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBody(stream: NodeRawBodyStream, callback: Callback<Buffer>): void;
/**
 * Gets the entire buffer of a node stream decoded as a string with the
 * given encoding, delivered to the callback. Validates the stream's
 * length against an expected length and maximum limit. Ideal for
 * parsing request bodies.
 */
declare function getRawBody(stream: NodeRawBodyStream, options: Readonly<Options & {
    encoding: Encoding;
}> | Encoding, callback: Callback<string>): void;
/**
 * Gets the entire buffer of a node stream as a `Buffer`, delivered to
 * the callback. Validates the stream's length against an expected
 * length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBody(stream: NodeRawBodyStream, options: Readonly<Options> | null, callback: Callback<Buffer>): void;
/**
 * Gets the entire buffer of a node stream decoded as a string with the
 * given encoding. Validates the stream's length against an expected
 * length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBody(stream: NodeRawBodyStream, options: Readonly<Options & {
    encoding: Encoding;
}> | Encoding): Promise<string>;
/**
 * Gets the entire buffer of a node stream as a `Buffer`. Validates the
 * stream's length against an expected length and maximum limit.
 * Ideal for parsing request bodies.
 */
declare function getRawBody(stream: NodeRawBodyStream, options?: Readonly<Options> | null): Promise<Buffer>;
/**
 * Gets the entire buffer of a web `ReadableStream` as a `Buffer`,
 * delivered to the callback. Validates the stream's length against an
 * expected length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBodyWeb(stream: WebRawBodyStream, callback: Callback<Buffer>): void;
/**
 * Gets the entire buffer of a web `ReadableStream` decoded as a string
 * with the given encoding, delivered to the callback. Validates the
 * stream's length against an expected length and maximum limit. Ideal
 * for parsing request bodies.
 */
declare function getRawBodyWeb(stream: WebRawBodyStream, options: Readonly<Options & {
    encoding: Encoding;
}> | Encoding, callback: Callback<string>): void;
/**
 * Gets the entire buffer of a web `ReadableStream` as a `Buffer`,
 * delivered to the callback. Validates the stream's length against an
 * expected length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBodyWeb(stream: WebRawBodyStream, options: Readonly<Options> | null, callback: Callback<Buffer>): void;
/**
 * Gets the entire buffer of a web `ReadableStream` decoded as a string
 * with the given encoding. Validates the stream's length against an
 * expected length and maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBodyWeb(stream: WebRawBodyStream, options: Readonly<Options & {
    encoding: Encoding;
}> | Encoding): Promise<string>;
/**
 * Gets the entire buffer of a web `ReadableStream` as a `Buffer`.
 * Validates the stream's length against an expected length and
 * maximum limit. Ideal for parsing request bodies.
 */
declare function getRawBodyWeb(stream: WebRawBodyStream, options?: Readonly<Options> | null): Promise<Buffer>;
export default getRawBody;
export { getRawBody, getRawBodyWeb };