@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/types/middleware/interfaces/helmet.interface.d.ts

@@ -0,0 +1,210 @@
+import { Request, Response } from "express";
+/**
+ * @typedef {string} cspDirectiveValue
+ * Possible values for Content Security Policy directives.
+ * Can be 'self', 'none', or a string.
+ */
+type cspDirectiveValue = "self" | "none" | string;
+/**
+ * @interface directiveOptions
+ * Options for defining Content Security Policy directives.
+ */
+interface directiveOptions {
+    "default-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "base-uri"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "font-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "form-action"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "frame-ancestors"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "img-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "object-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "script-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "script-src-attr"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "style-src"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+    "upgrade-insecure-requests"?: Array<cspDirectiveValue> | null | Array<(req: Request, res: Response) => string>;
+}
+/**
+ * @interface ContentSecurityPolicy
+ * Defines a Content Security Policy configuration.
+ */
+interface ContentSecurityPolicy {
+    /**
+     * A function that sets Content Security Policy.
+     *
+     * @param {directiveOptions} options - Optional configuration options for Content Security Policy.
+     * @returns {Function} A middleware function.
+     */
+    useDefaults?: false;
+    directives?: directiveOptions;
+    reportOnly?: boolean;
+}
+/**
+ * @typedef {Object} CrossOriginEmbedderPolicyOptions
+ * An optional policy for Cross-Origin Embedder Policy.
+ */
+interface CrossOriginEmbedderPolicyOptions {
+    /**
+     * An optional policy for Cross-Origin Embedder Policy.
+     */
+    policy?: "require-corp" | "credentialless";
+}
+/**
+ * @typedef {Object} CrossOriginOpenerPolicyOptions
+ * An optional policy for Cross-Origin Opener Policy.
+ */
+interface CrossOriginOpenerPolicyOptions {
+    /**
+     * An optional policy for Cross-Origin Opener Policy.
+     */
+    policy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
+}
+/**
+ * @typedef {Object} CrossOriginResourcePolicyOptions
+ * An optional policy for Cross-Origin Resource Policy.
+ */
+interface CrossOriginResourcePolicyOptions {
+    /**
+     * An optional policy for Cross-Origin Resource Policy.
+     */
+    policy?: "same-origin" | "same-site" | "cross-origin";
+}
+/**
+ * @typedef {string} ReferrerPolicyToken
+ * A type alias for Referrer Policy tokens.
+ */
+type ReferrerPolicyToken = "no-referrer" | "no-referrer-when-downgrade" | "no-referrer" | "no-referrer-when-downgrade" | "same-origin" | "origin" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | "";
+/**
+ * @typedef {Object} ReferrerPolicyOptions
+ * An optional policy for Referrer Policy.
+ */
+interface ReferrerPolicyOptions {
+    /**
+     * An optional policy for Referrer Policy.
+     */
+    policy?: ReferrerPolicyToken | Array<ReferrerPolicyToken> | false;
+}
+/**
+ * @typedef {Object} StrictTransportSecurityOptions
+ * Options for Strict Transport Security.
+ */
+interface StrictTransportSecurityOptions {
+    /**
+     * An optional max age for Strict Transport Security.
+     */
+    maxAge?: number;
+    /**
+     * An optional flag to include subdomains.
+     */
+    includeSubDomains?: boolean;
+    /**
+     * An optional flag for preload.
+     */
+    preload?: boolean;
+}
+/**
+ * @typedef {boolean|string} xContentTypeOptions
+ * Options for X-Content-Type-Options.
+ */
+type xContentTypeOptions = false | "nosniff";
+/**
+ * @typedef {Object} XDnsPrefetchControlOptions
+ * Options for X-DNS-Prefetch-Control.
+ */
+interface XDnsPrefetchControlOptions {
+    /**
+     * An optional flag to allow DNS prefetching.
+     */
+    allow?: boolean;
+}
+/**
+ * @typedef {Object} XFrameOptionsOptions
+ * Options for X-Frame-Options.
+ */
+interface XFrameOptionsOptions {
+    /**
+     * An optional action for X-Frame-Options.
+     */
+    action?: "deny" | "sameorigin" | false;
+}
+/**
+ * @typedef {Object} XPermittedCrossDomainPoliciesOptions
+ * Options for X-Permitted-Cross-Domain-Policies.
+ */
+interface XPermittedCrossDomainPoliciesOptions {
+    /**
+     * An optional policy for X-Permitted-Cross-Domain-Policies.
+     */
+    permittedPolicies?: "none" | "master-only" | "by-content-type" | "all";
+}
+/**
+ * @typedef {boolean} xPoweredByOptions
+ * Options for X-Powered-By.
+ */
+type xPoweredByOptions = false;
+/**
+ * @typedef {boolean} xXssProtectionOptions
+ * Options for X-XSS-Protection.
+ */
+type xXssProtectionOptions = false;
+/**
+ * @interface OptionsHelmet
+ * Options for Helmet middleware.
+ */
+export interface OptionsHelmet {
+    /**
+     * An optional Content Security Policy.
+     */
+    contentSecurityPolicy?: ContentSecurityPolicy | false;
+    /**
+     * An optional Cross-Origin Embedder Policy.
+     */
+    crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyOptions | boolean;
+    /**
+     * An optional Cross-Origin Opener Policy.
+     */
+    crossOriginOpenerPolicy?: boolean | CrossOriginOpenerPolicyOptions;
+    /**
+     * An optional Cross-Origin Resource Policy.
+     */
+    crossOriginResourcePolicy?: boolean | CrossOriginResourcePolicyOptions;
+    /**
+     * An optional flag for originAgentCluster.
+     */
+    originAgentCluster?: false;
+    /**
+     * An optional Referrer Policy.
+     */
+    referrerPolicy?: ReferrerPolicyOptions;
+    /**
+     * An optional Strict Transport Security.
+     */
+    strictTransportSecurity?: StrictTransportSecurityOptions;
+    /**
+     * An optional X-Content-Type-Options.
+     */
+    xContentTypeOptions?: xContentTypeOptions;
+    /**
+     * An optional X-DNS-Prefetch-Control.
+     */
+    xDnsPrefetchControl?: XDnsPrefetchControlOptions;
+    /**
+     * An optional X-Download-Options.
+     */
+    xDownloadOptions?: boolean | "noopen";
+    /**
+     * An optional X-Frame-Options.
+     */
+    xFrameOptions?: XFrameOptionsOptions;
+    /**
+     * An optional X-Permitted-Cross-Domain-Policies.
+     */
+    xPermittedCrossDomainPolicies?: XPermittedCrossDomainPoliciesOptions;
+    /**
+     * An optional X-Powered-By.
+     */
+    xPoweredBy?: xPoweredByOptions;
+    /**
+     * An optional X-XSS-Protection.
+     */
+    xXssProtection?: xXssProtectionOptions;
+}
+export {};

package/lib/esm/types/middleware/interfaces/morgan.interface.d.ts

@@ -0,0 +1,39 @@
+import http from "http";
+export interface StreamOptions {
+    /**
+     * Output stream for writing log lines.
+     */
+    write(str: string): void;
+}
+/***
+ * Morgan accepts these properties in the options object.
+ */
+export interface OptionsMorgan {
+    /***
+     * Buffer duration before writing logs to the stream, defaults to false.
+     * When set to true, defaults to 1000 ms.
+     * @deprecated
+     */
+    buffer?: boolean | undefined;
+    /***
+     * Write log line on request instead of response. This means that a
+     * requests will be logged even if the server crashes, but data from the
+     * response cannot be logged (like the response code).
+     */
+    immediate?: boolean | undefined;
+    /***
+     * Function to determine if logging is skipped, defaults to false. This
+     * function will be called as skip(req, res).
+     */
+    skip?(req: http.IncomingMessage, res: http.ServerResponse): boolean;
+    /***
+     * Output stream for writing log lines, defaults to process.stdout.
+     * @param str
+     */
+    stream?: StreamOptions | undefined;
+}
+export type FormatFn = (tokens: TokenIndexer, req: http.IncomingMessage, res: http.ServerResponse) => string;
+export type TokenCallbackFn = (req: http.IncomingMessage, res: http.ServerResponse, arg?: string | number) => string | number;
+export interface TokenIndexer {
+    [tokenName: string]: TokenCallbackFn;
+}

package/lib/esm/types/middleware/interfaces/multer.interface.d.ts

@@ -0,0 +1,253 @@
+import { RequestHandler } from "express";
+import { Readable } from "stream";
+declare global {
+    namespace Express {
+        namespace Multer {
+            /** Object containing file metadata and access information. */
+            interface File {
+                /** Name of the form field associated with this file. */
+                fieldname: string;
+                /** Name of the file on the uploader's computer. */
+                originalname: string;
+                /**
+                 * Value of the `Content-Transfer-Encoding` header for this file.
+                 * @deprecated since July 2015
+                 * @see RFC 7578, Section 4.7
+                 */
+                encoding: string;
+                /** Value of the `Content-Type` header for this file. */
+                mimetype: string;
+                /** Size of the file in bytes. */
+                size: number;
+                /**
+                 * A readable stream of this file. Only available to the `_handleFile`
+                 * callback for custom `StorageEngine`s.
+                 */
+                stream: Readable;
+                /** `DiskStorage` only: Directory to which this file has been uploaded. */
+                destination: string;
+                /** `DiskStorage` only: Name of this file within `destination`. */
+                filename: string;
+                /** `DiskStorage` only: Full path to the uploaded file. */
+                path: string;
+                /** `MemoryStorage` only: A Buffer containing the entire file. */
+                buffer: Buffer;
+            }
+        }
+        interface Request {
+            /** `Multer.File` object populated by `single()` middleware. */
+            file?: Multer.File | undefined;
+            /**
+             * Array or dictionary of `Multer.File` object populated by `array()`,
+             * `fields()`, and `any()` middleware.
+             */
+            files?: {
+                [fieldname: string]: Multer.File[];
+            } | Multer.File[] | undefined;
+        }
+    }
+}
+export declare namespace multer {
+    /**
+     * @see {@link https://github.com/expressjs/multer#api}
+     */
+    interface Multer {
+        /**
+         * Returns middleware that processes a single file associated with the
+         * given form field.
+         *
+         * The `Request` object will be populated with a `file` object containing
+         * information about the processed file.
+         *
+         * @param fieldName Name of the multipart form field to process.
+         */
+        single(fieldName: string): RequestHandler;
+        /**
+         * Returns middleware that processes multiple files sharing the same field
+         * name.
+         *
+         * The `Request` object will be populated with a `files` array containing
+         * an information object for each processed file.
+         *
+         * @param fieldName Shared name of the multipart form fields to process.
+         * @param maxCount Optional. Maximum number of files to process. (default: Infinity)
+         * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if more than `maxCount` files are associated with `fieldName`
+         */
+        array(fieldName: string, maxCount?: number): RequestHandler;
+        /**
+         * Returns middleware that processes multiple files associated with the
+         * given form fields.
+         *
+         * The `Request` object will be populated with a `files` object which
+         * maps each field name to an array of the associated file information
+         * objects.
+         *
+         * @param fields Array of `Field` objects describing multipart form fields to process.
+         * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if more than `maxCount` files are associated with `fieldName` for any field.
+         */
+        fields(fields: ReadonlyArray<Field>): RequestHandler;
+        /**
+         * Returns middleware that processes all files contained in the multipart
+         * request.
+         *
+         * The `Request` object will be populated with a `files` array containing
+         * an information object for each processed file.
+         */
+        any(): RequestHandler;
+        /**
+         * Returns middleware that accepts only non-file multipart form fields.
+         *
+         * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if any file is encountered.
+         */
+        none(): RequestHandler;
+    }
+    /**
+     * Returns a `StorageEngine` implementation configured to store files on
+     * the local file system.
+     *
+     * A string or function may be specified to determine the destination
+     * directory, and a function to determine filenames. If no options are set,
+     * files will be stored in the system's temporary directory with random 32
+     * character filenames.
+     */
+    function diskStorage(options: DiskStorageOptions): StorageEngine;
+    /**
+     * Returns a `StorageEngine` implementation configured to store files in
+     * memory as `Buffer` objects.
+     */
+    function memoryStorage(): StorageEngine;
+    type ErrorCode = "LIMIT_PART_COUNT" | "LIMIT_FILE_SIZE" | "LIMIT_FILE_COUNT" | "LIMIT_FIELD_KEY" | "LIMIT_FIELD_VALUE" | "LIMIT_FIELD_COUNT" | "LIMIT_UNEXPECTED_FILE";
+    class MulterError extends Error {
+        constructor(code: ErrorCode, field?: string);
+        /** Name of the MulterError constructor. */
+        name: string;
+        /** Identifying error code. */
+        code: ErrorCode;
+        /** Descriptive error message. */
+        message: string;
+        /** Name of the multipart form field associated with this error. */
+        field?: string | undefined;
+    }
+    /**
+     * a function to control which files should be uploaded and which should be skipped
+     * pass a boolean to indicate if the file should be accepted
+     * pass an error if something goes wrong
+     */
+    interface FileFilterCallback {
+        (error: Error): void;
+        (error: null, acceptFile: boolean): void;
+    }
+    /** Options for initializing a Multer instance. */
+    interface Options {
+        /**
+         * A `StorageEngine` responsible for processing files uploaded via Multer.
+         * Takes precedence over `dest`.
+         */
+        storage?: StorageEngine | undefined;
+        /**
+         * The destination directory for uploaded files. If `storage` is not set
+         * and `dest` is, Multer will create a `DiskStorage` instance configured
+         * to store files at `dest` with random filenames.
+         *
+         * Ignored if `storage` is set.
+         */
+        dest?: string | undefined;
+        /**
+         * An object specifying various limits on incoming data. This object is
+         * passed to Busboy directly, and the details of properties can be found
+         * at https://github.com/mscdex/busboy#busboy-methods.
+         */
+        limits?: {
+            /** Maximum size of each form field name in bytes. (Default: 100) */
+            fieldNameSize?: number | undefined;
+            /** Maximum size of each form field value in bytes. (Default: 1048576) */
+            fieldSize?: number | undefined;
+            /** Maximum number of non-file form fields. (Default: Infinity) */
+            fields?: number | undefined;
+            /** Maximum size of each file in bytes. (Default: Infinity) */
+            fileSize?: number | undefined;
+            /** Maximum number of file fields. (Default: Infinity) */
+            files?: number | undefined;
+            /** Maximum number of parts (non-file fields + files). (Default: Infinity) */
+            parts?: number | undefined;
+            /** Maximum number of headers. (Default: 2000) */
+            headerPairs?: number | undefined;
+        } | undefined;
+        /** Preserve the full path of the original filename rather than the basename. (Default: false) */
+        preservePath?: boolean | undefined;
+        /**
+         * Optional function to control which files are uploaded. This is called
+         * for every file that is processed.
+         *
+         * @param req The Express `Request` object.
+         * @param file Object containing information about the processed file.
+         * @param callback  a function to control which files should be uploaded and which should be skipped.
+         */
+        fileFilter?(req: Request, file: File, callback: FileFilterCallback): void;
+    }
+    /**
+     * Implementations of this interface are responsible for storing files
+     * encountered by Multer and returning information on how to access them
+     * once stored. Implementations must also provide a method for removing
+     * files in the event that an error occurs.
+     */
+    interface StorageEngine {
+        /**
+         * Store the file described by `file`, then invoke the callback with
+         * information about the stored file.
+         *
+         * File contents are available as a stream via `file.stream`. Information
+         * passed to the callback will be merged with `file` for subsequent
+         * middleware.
+         *
+         * @param req The Express `Request` object.
+         * @param file Object with `stream`, `fieldname`, `originalname`, `encoding`, and `mimetype` defined.
+         * @param callback Callback to specify file information.
+         */
+        _handleFile(req: Request, file: File, callback: (error?: any, info?: Partial<File>) => void): void;
+        /**
+         * Remove the file described by `file`, then invoke the callback with.
+         *
+         * `file` contains all the properties available to `_handleFile`, as
+         * well as those returned by `_handleFile`.
+         *
+         * @param req The Express `Request` object.
+         * @param file Object containing information about the processed file.
+         * @param callback Callback to indicate completion.
+         */
+        _removeFile(req: Request, file: Express.Multer.File, callback: (error: Error | null) => void): void;
+    }
+    interface DiskStorageOptions {
+        /**
+         * A string or function that determines the destination path for uploaded
+         * files. If a string is passed and the directory does not exist, Multer
+         * attempts to create it recursively. If neither a string or a function
+         * is passed, the destination defaults to `os.tmpdir()`.
+         *
+         * @param req The Express `Request` object.
+         * @param file Object containing information about the processed file.
+         * @param callback Callback to determine the destination path.
+         */
+        destination?: string | ((req: Request, file: Express.Multer.File, callback: (error: Error | null, destination: string) => void) => void) | undefined;
+        /**
+         * A function that determines the name of the uploaded file. If nothing
+         * is passed, Multer will generate a 32 character pseudorandom hex string
+         * with no extension.
+         *
+         * @param req The Express `Request` object.
+         * @param file Object containing information about the processed file.
+         * @param callback Callback to determine the name of the uploaded file.
+         */
+        filename?(req: Request, file: Express.Multer.File, callback: (error: Error | null, filename: string) => void): void;
+    }
+    /**
+     * An object describing a field name and the maximum number of files with
+     * that field name to accept.
+     */
+    interface Field {
+        /** The field name. */
+        name: string;
+        /** Optional maximum number of files per field to accept. (Default: Infinity) */
+        maxCount?: number | undefined;
+    }
+}

package/lib/esm/types/middleware/interfaces/serve-favicon.interface.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ServeFaviconOptions defines the available options for configuring the serve-favicon middleware.
+ */
+interface ServeFaviconOptions {
+    /**
+     * The cache-control max-age directive in ms, defaulting to 1 year.
+     * This can also be a string accepted by the `ms` module.
+     */
+    maxAge?: number | string | undefined;
+}
+export { ServeFaviconOptions };

package/lib/esm/types/middleware/interfaces/serve-static.interface.d.ts

@@ -0,0 +1,69 @@
+import http from "http";
+interface ServeStaticOptions<R extends http.ServerResponse = http.ServerResponse> {
+    /**
+     * Enable or disable accepting ranged requests, defaults to true.
+     * Disabling this will not send Accept-Ranges and ignore the contents of the Range request header.
+     */
+    acceptRanges?: boolean | undefined;
+    /**
+     * Enable or disable setting Cache-Control response header, defaults to true.
+     * Disabling this will ignore the immutable and maxAge options.
+     */
+    cacheControl?: boolean | undefined;
+    /**
+     * Set how "dotfiles" are treated when encountered. A dotfile is a file or directory that begins with a dot (".").
+     * Note this check is done on the path itself without checking if the path actually exists on the disk.
+     * If root is specified, only the dotfiles above the root are checked (i.e. the root itself can be within a dotfile when when set to "deny").
+     * The default value is 'ignore'.
+     * 'allow' No special treatment for dotfiles
+     * 'deny' Send a 403 for any request for a dotfile
+     * 'ignore' Pretend like the dotfile does not exist and call next()
+     */
+    dotfiles?: string | undefined;
+    /**
+     * Enable or disable etag generation, defaults to true.
+     */
+    etag?: boolean | undefined;
+    /**
+     * Set file extension fallbacks. When set, if a file is not found, the given extensions will be added to the file name and search for.
+     * The first that exists will be served. Example: ['html', 'htm'].
+     * The default value is false.
+     */
+    extensions?: Array<string> | false | undefined;
+    /**
+     * Let client errors fall-through as unhandled requests, otherwise forward a client error.
+     * The default value is true.
+     */
+    fallthrough?: boolean | undefined;
+    /**
+     * Enable or disable the immutable directive in the Cache-Control response header.
+     * If enabled, the maxAge option should also be specified to enable caching. The immutable directive will prevent supported clients from making conditional requests during the life of the maxAge option to check if the file has changed.
+     */
+    immutable?: boolean | undefined;
+    /**
+     * By default this module will send "index.html" files in response to a request on a directory.
+     * To disable this set false or to supply a new index pass a string or an array in preferred order.
+     */
+    index?: boolean | string | Array<string> | undefined;
+    /**
+     * Enable or disable Last-Modified header, defaults to true. Uses the file system's last modified value.
+     */
+    lastModified?: boolean | undefined;
+    /**
+     * Provide a max-age in milliseconds for http caching, defaults to 0. This can also be a string accepted by the ms module.
+     */
+    maxAge?: number | string | undefined;
+    /**
+     * Redirect to trailing "/" when the pathname is a dir. Defaults to true.
+     */
+    redirect?: boolean | undefined;
+    /**
+     * Function to set custom headers on response. Alterations to the headers need to occur synchronously.
+     * The function is called as fn(res, path, stat), where the arguments are:
+     * res the response object
+     * path the file path that is being sent
+     * stat the stat object of the file that is being sent
+     */
+    setHeaders?: ((res: R, path: string, stat: any) => any) | undefined;
+}
+export { ServeStaticOptions };

package/lib/esm/types/middleware/interfaces/url-encoded.interface.d.ts

@@ -0,0 +1,37 @@
+import * as http from "http";
+interface Options {
+    /** When set to true, then deflated (compressed) bodies will be inflated; when false, deflated bodies are rejected. Defaults to true. */
+    inflate?: boolean | undefined;
+    /**
+     * Controls the maximum request body size. If this is a number,
+     * then the value specifies the number of bytes; if it is a string,
+     * the value is passed to the bytes library for parsing. Defaults to '100kb'.
+     */
+    limit?: number | string | undefined;
+    /**
+     * The type option is used to determine what media type the middleware will parse
+     */
+    type?: string | Array<string> | ((req: http.IncomingMessage) => any) | undefined;
+    /**
+     * The verify option, if supplied, is called as verify(req, res, buf, encoding),
+     * where buf is a Buffer of the raw request body and encoding is the encoding of the request.
+     */
+    verify?(req: http.IncomingMessage, res: http.ServerResponse, buf: Buffer, encoding: string): void;
+}
+/**
+ * These are the options available to urlencodedParser.
+ */
+export interface OptionsUrlencoded extends Options {
+    /**
+     * The extended option allows to choose between parsing the URL-encoded data
+     * with the querystring library (when `false`) or the qs library (when `true`).
+     */
+    extended?: boolean | undefined;
+    /**
+     * The parameterLimit option controls the maximum number of parameters
+     * that are allowed in the URL-encoded data. If a request contains more parameters than this value,
+     * a 413 will be returned to the client. Defaults to 1000.
+     */
+    parameterLimit?: number | undefined;
+}
+export {};