@opra/http 1.0.0-beta.3

package/types/interfaces/http-incoming.interface.d.ts

@@ -0,0 +1,192 @@
+import type { Options as RangeParserOptions, Ranges as RangeParserRanges, Result as RangeParserResult } from 'range-parser';
+import { BodyReader } from '../utils/body-reader.js';
+import type { HttpOutgoing } from './http-outgoing.interface.js';
+import { NodeIncomingMessage } from './node-incoming-message.interface.js';
+/**
+ * @interface HttpIncoming
+ */
+export interface HttpIncoming extends NodeIncomingMessage {
+    res: HttpOutgoing;
+    baseUrl: string;
+    originalUrl: string;
+    /**
+     * Return the protocol string "http" or "https"
+     * When the "X-Forwarded-Proto" header field will be trusted
+     * and used if present.
+     */
+    protocol: string;
+    /**
+     * Return the remote address from the trusted proxy.
+     *
+     * This is the remote address on the socket unless "trust proxy" is set.
+     */
+    ip: string;
+    /**
+     * When "trust proxy" is set, trusted proxy addresses + client.
+     *
+     * For example if the value were "client, proxy1, proxy2"
+     * you would receive the array `["client", "proxy1", "proxy2"]`
+     * where "proxy2" is the furthest down-stream and "proxy1" and
+     * "proxy2" were trusted.
+     */
+    ips: string[];
+    /**
+     * Short-hand for:
+     *    req.protocol === 'https'
+     */
+    secure: boolean;
+    /**
+     * Used for signed cookies
+     */
+    secret?: string;
+    /**
+     * Parse the "Host" header field to a hostname.
+     *
+     * When the "trust proxy" setting trusts the socket
+     * address, the "X-Forwarded-Host" header field will
+     * be trusted.
+     */
+    hostname?: string;
+    /**
+     * Check if the request is fresh, aka
+     * Last-Modified and/or the ETag still match.
+     */
+    fresh: boolean;
+    /**
+     * Path parameter values
+     */
+    params: Record<string, any>;
+    /**
+     * Cookie parameter values
+     */
+    cookies?: Record<string, any>;
+    /**
+     * Return request header.
+     *
+     * The `Referrer` header field is special-cased,
+     * both `Referrer` and `Referer` are interchangeable.
+     *
+     * @example
+     *     req.get('Content-Type');
+     *     // => "text/plain"
+     *
+     *     req.get('content-type');
+     *     // => "text/plain"
+     *
+     *     req.get('Something');
+     *     // => undefined
+     *
+     */
+    header(name: 'set-cookie'): string[] | undefined;
+    header(name: string): string | undefined;
+    get(name: 'set-cookie'): string[] | undefined;
+    get(name: string): string | undefined;
+    /**
+     * 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", a comma-delimited list such as "json, html, text/plain",
+     * or an array `["json", "html", "text/plain"]`. When a list
+     * or array is given the _best_ match, if any is returned.
+     *
+     * @example
+     *     // Accept: text/html
+     *     req.accepts('html');
+     *     // => "html"
+     *
+     *     // Accept: text/*, application/json
+     *     req.accepts('html');
+     *     // => "html"
+     *     req.accepts('text/html');
+     *     // => "text/html"
+     *     req.accepts('json, text');
+     *     // => "json"
+     *     req.accepts('application/json');
+     *     // => "application/json"
+     *
+     *     // Accept: text/*, application/json
+     *     req.accepts('image/png');
+     *     req.accepts('png');
+     *     // => undefined
+     *
+     *     // Accept: text/*;q=.5, application/json
+     *     req.accepts(['html', 'json']);
+     *     req.accepts('html, json');
+     *     // => "json"
+     */
+    accepts(): string[];
+    accepts(type: string): string | false;
+    accepts(type: string[]): string | false;
+    accepts(...type: string[]): string | false;
+    /**
+     * Returns the first accepted charset of the specified character sets,
+     * based on the request's Accept-Charset HTTP header field.
+     * If none of the specified charsets is accepted, returns false.
+     *
+     * For more information, or if you have issues or concerns, see accepts.
+     */
+    acceptsCharsets(): string[];
+    acceptsCharsets(charsets: string[]): string | false;
+    acceptsCharsets(...charset: string[]): string | false;
+    /**
+     * Returns the first accepted encoding of the specified encodings,
+     * based on the request's Accept-Encoding HTTP header field.
+     * If none of the specified encodings is accepted, returns false.
+     *
+     * For more information, or if you have issues or concerns, see accepts.
+     */
+    acceptsEncodings(): string[];
+    acceptsEncodings(encodings: string[]): string | false;
+    acceptsEncodings(...encoding: string[]): string | false;
+    /**
+     * Returns the first accepted language of the specified languages,
+     * based on the request's Accept-Language HTTP header field.
+     * If none of the specified languages is accepted, returns false.
+     *
+     * For more information, or if you have issues or concerns, see accepts.
+     */
+    acceptsLanguages(): string[];
+    acceptsLanguages(lang: string): string | false;
+    acceptsLanguages(lang: string[]): string | false;
+    acceptsLanguages(...lang: string[]): string | false;
+    /**
+     * Check if the incoming request contains the "Content-Type"
+     * header field, and it contains the give mime `type`.
+     *
+     * @example
+     *      // With Content-Type: text/html; charset=utf-8
+     *      req.is('html');
+     *      req.is('text/html');
+     *      req.is('text/*');
+     *      // => true
+     *
+     *      // When Content-Type is application/json
+     *      req.is('json');
+     *      req.is('application/json');
+     *      req.is('application/*');
+     *      // => true
+     *
+     *      req.is('html');
+     *      // => false
+     */
+    is(type: string | string[]): string | false | null;
+    is(...types: string[]): string | false | null;
+    /**
+     * Parse Range header field, capping to the given `size`.
+     */
+    range(size: number, options?: RangeParserOptions): RangeParserRanges | RangeParserResult | undefined;
+    /**
+     * Receives the body
+     * @param options
+     */
+    readBody(options: BodyReader.Options): Promise<string | Buffer | undefined>;
+}
+/**
+ * @namespace HttpIncoming
+ */
+export declare namespace HttpIncoming {
+    function from(instance: HttpIncoming | NodeIncomingMessage.Initiator | string | Iterable<any> | AsyncIterable<any>): HttpIncoming;
+}

package/types/interfaces/http-outgoing.interface.d.ts

@@ -0,0 +1,144 @@
+import { type StrictOmit } from 'ts-gems';
+import type { HttpIncoming } from './http-incoming.interface.js';
+import { NodeOutgoingMessage } from './node-outgoing-message.interface.js';
+export interface HttpOutgoing extends StrictOmit<NodeOutgoingMessage, 'req' | 'appendHeader' | 'setHeader'> {
+    req: HttpIncoming;
+    readonly finished?: boolean;
+    appendHeader(name: string, value: string | readonly string[]): this;
+    setHeader(name: string, value: number | string | readonly string[]): this;
+    /**
+     * Set _Content-Disposition_ header to _attachment_ with optional `filename`.
+     */
+    attachment(filename?: string): this;
+    /** Clear cookie `name`. */
+    clearCookie(name: string, options?: CookieOptions): this;
+    /**
+     * Set cookie `name` to `val`, with the given `options`.
+     *
+     * Options:
+     *
+     *    - `maxAge`   max-age in milliseconds, converted to `expires`
+     *    - `signed`   sign the cookie
+     *    - `path`     defaults to "/"
+     *
+     * Examples:
+     *
+     *    // "Remember Me" for 15 minutes
+     *    res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
+     *
+     *    // save as above
+     *    res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
+     */
+    cookie(name: string, val: string, options: CookieOptions): this;
+    cookie(name: string, val: any, options: CookieOptions): this;
+    cookie(name: string, val: any): this;
+    /**
+     * Set _Content-Type_ response header with `type` through `mime.lookup()`
+     * when it does not contain "/", or set the Content-Type to `type` otherwise.
+     *
+     * @example
+     *     res.type('.html');
+     *     res.type('html');
+     *     res.type('json');
+     *     res.type('application/json');
+     *     res.type('png');
+     */
+    contentType(type: string): this;
+    /**
+     * Set Link header field with the given `links`.
+     *
+     * Examples:
+     *
+     *    res.links({
+     *      next: 'http://api.example.com/users?page=2',
+     *      last: 'http://api.example.com/users?page=5'
+     *    });
+     */
+    links(links: Record<string, string>): this;
+    /**
+     * Set the location header to `url`.
+     *
+     * The given `url` can also be the name of a mapped url, for
+     * example by default express supports "back" which redirects
+     * to the _Referrer_ or _Referer_ headers or "/".
+     *
+     * Examples:
+     *
+     *    res.location('/foo/bar').;
+     *    res.location('http://example.com');
+     *    res.location('../login'); // /blog/post/1 -> /blog/login
+     *
+     * Mounting:
+     *
+     *   When an application is mounted and `res.location()`
+     *   is given a path that does _not_ lead with "/" it becomes
+     *   relative to the mount-point. For example if the application
+     *   is mounted at "/blog", the following would become "/blog/login".
+     *
+     *      res.location('login');
+     *
+     *   While the leading slash would result in a location of "/login":
+     *
+     *      res.location('/login');
+     */
+    location(url: string): this;
+    /**
+     * Redirect to the given `url` with optional response `status`
+     * defaulting to 302.
+     *
+     * The resulting `url` is determined by `res.location()`, so
+     * it will play nicely with mounted apps, relative paths,
+     * `"back"` etc.
+     *
+     * Examples:
+     *
+     *    res.redirect('back');
+     *    res.redirect('/foo/bar');
+     *    res.redirect('http://example.com');
+     *    res.redirect(301, 'http://example.com');
+     *    res.redirect('http://example.com', 301);
+     *    res.redirect('../login'); // /blog/post/1 -> /blog/login
+     */
+    redirect(url: string): void;
+    redirect(status: number, url: string): void;
+    /**
+     * Set status `code`.
+     */
+    status(code: number): this;
+    /**
+     * Send given HTTP status code.
+     *
+     * Sets the response status to `statusCode` and the body of the
+     * response to the standard description from node's http.STATUS_CODES
+     * or the statusCode number if no description.
+     */
+    sendStatus(statusCode: number): this;
+    /**
+     * Send a response.
+     *
+     * @example
+     *     res.send(new Buffer('wahoo'));
+     *     res.send({ some: 'json' });
+     *     res.send('<p>some html</p>');
+     *     res.status(404).send('Sorry, cant find that');
+     */
+    send(body?: any): this;
+}
+export interface CookieOptions {
+    secret?: string;
+    maxAge?: number;
+    signed?: boolean;
+    expires?: Date;
+    httpOnly?: boolean;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    encode?: (val: string) => string;
+    sameSite?: boolean | 'lax' | 'strict' | 'none';
+}
+/**
+ * @namespace HttpIncoming
+ */
+export declare namespace HttpOutgoing {
+    function from(instance: HttpOutgoing | NodeOutgoingMessage.Initiator): HttpOutgoing;
+}

package/types/interfaces/node-incoming-message.interface.d.ts

@@ -0,0 +1,36 @@
+import http from 'http';
+import { Readable } from 'stream';
+/**
+ * @interface NodeIncomingMessage
+ */
+export interface NodeIncomingMessage extends Readable, Pick<http.IncomingMessage, 'httpVersion' | 'httpVersionMajor' | 'httpVersionMinor' | 'complete' | 'headers' | 'trailers' | 'rawHeaders' | 'rawTrailers' | 'method' | 'url'> {
+}
+/**
+ *
+ * @namespace NodeIncomingMessage
+ */
+export declare namespace NodeIncomingMessage {
+    interface Initiator {
+        httpVersionMajor?: number;
+        httpVersionMinor?: number;
+        method?: string;
+        url?: string;
+        headers?: Record<string, any> | string[];
+        trailers?: Record<string, any> | string[];
+        params?: Record<string, any>;
+        cookies?: Record<string, any>;
+        body?: any;
+        ip?: string;
+        ips?: string[];
+    }
+    /**
+     * Creates a new NodeIncomingMessage from given argument
+     * @param iterable
+     */
+    function from(iterable: string | Iterable<any> | AsyncIterable<any> | Initiator): NodeIncomingMessage;
+    /**
+     * Creates a new NodeIncomingMessage from given argument
+     * @param iterable
+     */
+    function fromAsync(iterable: string | Iterable<any> | AsyncIterable<any> | Initiator): Promise<NodeIncomingMessage>;
+}

package/types/interfaces/node-outgoing-message.interface.d.ts

@@ -0,0 +1,27 @@
+import http, { type OutgoingHttpHeaders } from 'http';
+import { Writable } from 'stream';
+import { NodeIncomingMessage } from './node-incoming-message.interface.js';
+export interface NodeOutgoingMessage extends Writable, Pick<http.ServerResponse, 'addTrailers' | 'getHeader' | 'getHeaders' | 'getHeaderNames' | 'flushHeaders' | 'removeHeader' | 'hasHeader' | 'headersSent' | 'statusCode' | 'statusMessage' | 'sendDate'> {
+    req: NodeIncomingMessage;
+    getRawHeaderNames(): string[];
+    appendHeader(name: string, value: string | readonly string[]): this;
+    setHeader(name: string, value: number | string | readonly string[]): this;
+}
+/**
+ *
+ * @namespace NodeOutgoingMessage
+ */
+export declare namespace NodeOutgoingMessage {
+    interface Initiator {
+        req: NodeIncomingMessage;
+        statusCode?: number;
+        statusMessage?: string;
+        headers?: OutgoingHttpHeaders | Headers | Map<string, any> | string[];
+        chunkedEncoding?: boolean;
+        sendDate?: boolean;
+        strictContentLength?: boolean;
+        body?: string | Iterable<any> | AsyncIterable<any> | Object;
+        parsedUrl?: URL;
+    }
+    function from(init: Initiator): NodeOutgoingMessage;
+}

package/types/type-guards.d.ts

@@ -0,0 +1,8 @@
+import type { HttpIncoming } from './interfaces/http-incoming.interface.js';
+import type { HttpOutgoing } from './interfaces/http-outgoing.interface.js';
+import type { NodeIncomingMessage } from './interfaces/node-incoming-message.interface.js';
+import type { NodeOutgoingMessage } from './interfaces/node-outgoing-message.interface.js';
+export declare function isNodeIncomingMessage(v: any): v is NodeIncomingMessage;
+export declare function isHttpIncoming(v: any): v is HttpIncoming;
+export declare function isNodeOutgoingMessage(v: any): v is NodeOutgoingMessage;
+export declare function isHttpOutgoing(v: any): v is HttpOutgoing;

package/types/utils/body-reader.d.ts

@@ -0,0 +1,38 @@
+import nodeStream from 'node:stream';
+import { EventEmitter } from 'events';
+import type { HttpIncoming } from '../interfaces/http-incoming.interface.js';
+/**
+ *
+ * @namespace BodyReader
+ */
+export declare namespace BodyReader {
+    interface Options {
+        limit?: number | string;
+    }
+}
+type Callback = (...args: any[]) => any;
+/**
+ *
+ * @class BodyReader
+ */
+export declare class BodyReader extends EventEmitter {
+    readonly req: HttpIncoming;
+    limit?: number;
+    protected _stream?: nodeStream.Readable;
+    protected _buffer?: string | Buffer[];
+    protected _completed?: boolean | undefined;
+    protected _receivedSize: number;
+    protected cleanup: Callback;
+    protected onAborted: Callback;
+    protected onData: Callback;
+    protected onEnd: Callback;
+    constructor(req: HttpIncoming, options?: BodyReader.Options);
+    read(): Promise<string | Buffer | undefined>;
+    protected _onEnd(error: any): void;
+    protected _cleanup(): void;
+    protected _onAborted(): void;
+    protected _onData(chunk: Buffer | string): void;
+    static read(req: HttpIncoming, options?: BodyReader.Options): Promise<string | Buffer | undefined>;
+    protected static encoderPipeline(req: HttpIncoming): nodeStream.Readable;
+}
+export {};

package/types/utils/common.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Verifies that the given val is a valid HTTP token
+ * per the rules defined in RFC 7230
+ * See https://tools.ietf.org/html/rfc7230#section-3.2.6
+ *
+ * https://github.com/nodejs/node/blob/main/lib/_http_common.js
+ */
+export declare function checkIsHttpToken(val: any): boolean;
+/**
+ * This function removes unnecessary frames from Node.js core errors.
+ *
+ * https://github.com/nodejs/node/blob/main/lib/internal/errors.js
+ */
+export declare function hideStackFrames(fn: Function): Function;
+export declare const validateHeaderName: Function;
+export declare const validateHeaderValue: Function;
+export declare function validateString(value: any, name?: string): void;

package/types/utils/concat-readable.d.ts

@@ -0,0 +1,2 @@
+import { Readable } from 'stream';
+export declare function concatReadable(...streams: Readable[]): Readable;

package/types/utils/convert-to-headers.d.ts

@@ -0,0 +1,2 @@
+export declare function convertToHeaders<T>(src: string[], dst: T, joinDuplicateHeaders?: boolean): T;
+export declare function convertToHeadersDistinct<T>(src: string[], dst: T): T;

package/types/utils/convert-to-raw-headers.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingHttpHeaders } from 'http';
+export declare function convertToRawHeaders(src: IncomingHttpHeaders | Record<string, any>): string[];

package/types/utils/match-known-fields.d.ts

@@ -0,0 +1,6 @@
+export declare const NO_DUPLICATES_FIELD = 0;
+export declare const COMMA_DELIMITED_FIELD = 1;
+export declare const SEMICOLON_DELIMITED_FIELD = 2;
+export declare const ARRAY_FIELD = 3;
+export type FIELD_FLAG = typeof NO_DUPLICATES_FIELD | typeof COMMA_DELIMITED_FIELD | typeof SEMICOLON_DELIMITED_FIELD | typeof ARRAY_FIELD;
+export declare function matchKnownFields(field: string): [string, FIELD_FLAG];

package/types/utils/wrap-exception.d.ts

@@ -0,0 +1,2 @@
+import { OpraHttpError } from '@opra/common';
+export declare function wrapException(error: any): OpraHttpError;