@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/types/middleware/index.d.ts

@@ -0,0 +1,25 @@
+export { Middleware, ExpressHandler, ExpressoMiddleware, MiddlewareOptions, MiddlewareCategory, MiddlewareEntry, MiddlewarePipelineInfo, ConditionalMiddlewareConfig, } from "./middleware-service.js";
+export { ErrorHandlerOptions, IMiddleware, HealthCheckOptions, } from "./middleware-interface.js";
+export { middlewareResolver, isMiddlewareAvailable, isPackageAvailable, resolvePackage, getAvailableMiddleware, getRegisteredMiddleware, clearMiddlewareCache, getPackageName, MIDDLEWARE_REGISTRY, RegisteredMiddlewareName, } from "./middleware-resolver.js";
+export { MiddlewareProfiler, MiddlewareMetrics, ProfilerStats, } from "./middleware-profiler.js";
+export { MiddlewarePresetName, MiddlewarePreset, PresetMiddlewareConfig, ApplyPresetOptions, MIDDLEWARE_PRESETS, getPreset, getPresetNames, getPresetsByTag, createPreset, mergePresets, } from "./middleware-presets.js";
+export type { OptionsJson } from "./interfaces/body-parser.interface.js";
+export type { CorsOptions } from "./interfaces/cors.interface.js";
+export type { CompressionOptions } from "./interfaces/compression.interface.js";
+export type { CookieSessionOptions } from "./interfaces/cookie-session/cookie-session.interface.js";
+export type { OptionsHelmet } from "./interfaces/helmet.interface.js";
+export type { SessionOptions } from "./interfaces/express-session.interface.js";
+export type { Keygrip } from "./interfaces/cookie-session/keygrip.interface.js";
+export type { CookieParserOptions } from "./interfaces/cookie-parser.interface.js";
+export type { ServeFaviconOptions } from "./interfaces/serve-favicon.interface.js";
+export type { RateLimitOptions } from "./interfaces/express-rate-limit.interface.js";
+export type { multer } from "./interfaces/multer.interface.js";
+export type { OptionsUrlencoded } from "./interfaces/url-encoded.interface.js";
+export type * as IMorgan from "./interfaces/morgan.interface.js";
+export { ContentNegotiationService, FormatterRegistry, AcceptHeaderParser, JsonFormatter, XmlFormatter, CsvFormatter, YamlFormatter, PlainTextFormatter, } from "./content-negotiation/index.js";
+export type { IContentFormatter, ContentNegotiationOptions, AcceptHeaderEntry, NegotiationResult, CsvFormatOptions, XmlFormatOptions, YamlFormatOptions, } from "./interfaces/content-negotiation.interface.js";
+export { use, compose, when, parallel, timeout } from "./middleware-utils.js";
+export { MiddlewareRegistry, getMiddlewareRegistry, resetMiddlewareRegistry, } from "./middleware-registry.js";
+export type { MiddlewareEntry as RegistryMiddlewareEntry } from "./middleware-registry.js";
+export { setGlobalUploadConfig, getGlobalUploadConfig, hasGlobalUploadConfig, clearGlobalUploadConfig, mergeUploadConfigs, } from "./upload-registry.js";
+export type { ParseOptions, MiddlewareLoggerConfig, LoggerImplementation, MorganLoggerOptions, PinoLoggerOptions, WinstonLoggerOptions, SecurityConfig, SecurityPreset, EnhancedRateLimitConfig, CsrfConfig, RateLimitStrategy, CompressConfig, CompressionAlgorithm, CompressionImplementation, SessionConfig, SessionType, JwtSessionOptions, UploadConfig, UploadHandler, StorageProvider, StaticConfig, PresetName, MiddlewareConfig, OptimizationConfig, PipelineAnalysis, Recommendation, RecommendationType, RecommendationSeverity, RegisteredMiddleware, } from "./middleware-config.js";

package/lib/esm/types/middleware/interfaces/body-parser.interface.d.ts

@@ -0,0 +1,31 @@
+import * as http from "http";
+interface OptionsJson {
+    /** 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;
+    /**
+     *
+     * The reviver option is passed directly to JSON.parse as the second argument.
+     */
+    reviver?(key: string, value: any): any;
+    /**
+     * When set to `true`, will only accept arrays and objects;
+     * when `false` will accept anything JSON.parse accepts. Defaults to `true`.
+     */
+    strict?: boolean | undefined;
+}
+export { OptionsJson };

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

@@ -0,0 +1,98 @@
+import express from "express";
+interface CompressionFilter {
+    (req: express.Request, res: express.Response): boolean;
+}
+interface CompressionOptions {
+    /**
+     * @default zlib.constants.Z_DEFAULT_CHUNK or 16384
+     * @see {@link https://nodejs.org/api/zlib.html#zlib_memory_usage_tuning| Node.js documentation}
+     * @see {@link https://github.com/expressjs/compression#chunksize|chunkSize documentation}
+     */
+    chunkSize?: number | undefined;
+    /**
+     * A function to decide if the response should be considered for compression. This function is called as
+     * `filter(req, res)` and is expected to return `true` to consider the response for compression, or `false` to
+     * not compress the response.
+     *
+     * The default filter function uses the `compressible` module to determine if `res.getHeader('Content-Type')`
+     * is compressible.
+     *
+     * @see {@link https://github.com/expressjs/compression#filter|`filter` documentation}
+     * @see {@link https://www.npmjs.com/package/compressible|compressible module}
+     */
+    filter?: CompressionFilter | undefined;
+    /**
+     * The level of zlib compression to apply to responses. A higher level will result in better compression, but
+     * will take longer to complete. A lower level will result in less compression, but will be much faster.
+     *
+     * This is an integer in the range of `0` (no compression) to `9` (maximum compression). The special value `-1`
+     * can be used to mean the "default compression level", which is a default compromise between speed and
+     * compression (currently equivalent to level 6).
+     *
+     * - `-1` Default compression level (also `zlib.constants.Z_DEFAULT_COMPRESSION`).
+     * - `0` No compression (also `zlib.constants.Z_NO_COMPRESSION`).
+     * - `1` Fastest compression (also `zlib.constants.Z_BEST_SPEED`).
+     * - `2`
+     * - `3`
+     * - `4`
+     * - `5`
+     * - `6` (currently what `zlib.constants.Z_DEFAULT_COMPRESSION` points to).
+     * - `7`
+     * - `8`
+     * - `9` Best compression (also `zlib.constants.Z_BEST_COMPRESSION`).
+     *
+     * **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
+     *
+     * @default zlib.constants.DEFAULT_COMPRESSION or -1
+     * @see {@link https://github.com/expressjs/compression#level|`level` documentation}
+     */
+    level?: number | undefined;
+    /**
+     * This specifies how much memory should be allocated for the internal compression state and is an integer in
+     * the range of `1` (minimum level) and `9` (maximum level).
+     *
+     * @default zlib.constants.DEFAULT_MEMLEVEL or 8
+     * @see {@link https://nodejs.org/api/zlib.html#zlib_memory_usage_tuning|Node.js documentation}
+     * @see {@link https://github.com/expressjs/compression#memlevel|`memLevel` documentation}
+     */
+    memLevel?: number | undefined;
+    /**
+     * This is used to tune the compression algorithm. This value only affects the compression ratio, not the
+     * correctness of the compressed output, even if it is not set appropriately.
+     *
+     * - `zlib.constants.Z_DEFAULT_STRATEGY` Use for normal data.
+     * - `zlib.constants.Z_FILTERED` Use for data produced by a filter (or predictor). Filtered data consists mostly of small
+     *   values with a somewhat random distribution. In this case, the compression algorithm is tuned to compress
+     *   them better. The effect is to force more Huffman coding and less string matching; it is somewhat intermediate
+     *   between `zlib.constants.Z_DEFAULT_STRATEGY` and `zlib.constants.Z_HUFFMAN_ONLY`.
+     * - `zlib.constants.Z_FIXED` Use to prevent the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
+     * - `zlib.constants.Z_HUFFMAN_ONLY` Use to force Huffman encoding only (no string match).
+     * - `zlib.constants.Z_RLE` Use to limit match distances to one (run-length encoding). This is designed to be almost as
+     *    fast as `zlib.constants.Z_HUFFMAN_ONLY`, but give better compression for PNG image data.
+     *
+     * **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
+     */
+    strategy?: number | undefined;
+    /**
+     * The byte threshold for the response body size before compression is considered for the response, defaults to
+     * 1kb. This is a number of bytes or any string accepted by the bytes module.
+     *
+     * **Note** this is only an advisory setting; if the response size cannot be determined at the time the response
+     * headers are written, then it is assumed the response is *over* the threshold. To guarantee the response size
+     * can be determined, be sure set a `Content-Length` response header.
+     *
+     * @see {@link https://www.npmjs.com/package/bytes|`bytes` module}
+     * @see {@link https://github.com/expressjs/compression#threshold|`threshold` documentation}
+     */
+    threshold?: number | string | undefined;
+    /**
+     * @default zlib.constants.Z_DEFAULT_WINDOWBITS or 15.
+     * @see {@link https://nodejs.org/api/zlib.html#zlib_memory_usage_tuning|Node.js documentation}
+     */
+    windowBits?: number | undefined;
+    /**
+     * In addition , `zlib` options may be passed in to the options object.
+     */
+    [property: string]: any;
+}
+export { CompressionOptions };

package/lib/esm/types/middleware/interfaces/content-negotiation.interface.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Content negotiation interfaces and types for ExpressoTS.
+ * Provides type-safe content negotiation with support for multiple formats,
+ * quality values, and custom formatters.
+ */
+/**
+ * Interface for content formatters that serialize data to specific formats.
+ * @template T - The type of data being formatted (defaults to unknown)
+ */
+export interface IContentFormatter<T = unknown> {
+    /**
+     * Checks if this formatter can handle the given content type.
+     * @param contentType - The content type to check (e.g., "application/json")
+     * @returns True if this formatter can handle the content type
+     */
+    canFormat(contentType: string): boolean;
+    /**
+     * Formats the data according to this formatter's format.
+     * @param data - The data to format
+     * @returns The formatted data as a string or Buffer
+     */
+    format(data: T): string | Buffer | Promise<string | Buffer>;
+    /**
+     * Gets the content type this formatter produces.
+     * @returns The MIME type (e.g., "application/json")
+     */
+    getContentType(): string;
+    /**
+     * Gets all content types this formatter supports.
+     * Useful for wildcard matching (e.g., "application/star").
+     * @returns Array of supported MIME types
+     */
+    getSupportedTypes(): Array<string>;
+    /**
+     * Gets the priority/quality of this formatter for content negotiation.
+     * Higher values are preferred. Default is 1.0.
+     * @returns Priority value between 0.0 and 1.0
+     */
+    getPriority?(): number;
+}
+/**
+ * Options for CSV formatting.
+ */
+export interface CsvFormatOptions {
+    /** Fields to include in CSV output. If not specified, all fields are included. */
+    fields?: Array<string>;
+    /** Whether to include headers in CSV output. Default: true */
+    includeHeaders?: boolean;
+    /** CSV delimiter. Default: "," */
+    delimiter?: string;
+    /** Custom transformation function applied to each row before formatting */
+    transform?: (row: unknown) => unknown;
+    /** Whether to escape values. Default: true */
+    escape?: boolean;
+}
+/**
+ * Options for XML formatting.
+ */
+export interface XmlFormatOptions {
+    /** Root element name. Default: "root" */
+    rootElement?: string;
+    /** Item element name for arrays. Default: "item" */
+    itemElement?: string;
+    /** Attributes to include on elements */
+    attributes?: Array<string>;
+    /** Whether to pretty print XML. Default: false */
+    prettyPrint?: boolean;
+    /** XML declaration. Default: true */
+    xmlDeclaration?: boolean;
+    /** Custom attribute mapping function */
+    attributeMap?: (key: string, value: unknown) => Record<string, string>;
+}
+/**
+ * Options for YAML formatting.
+ */
+export interface YamlFormatOptions {
+    /** Indentation level. Default: 2 */
+    indent?: number;
+    /** Whether to quote all strings. Default: false */
+    quoteStrings?: boolean;
+    /** Line width. Default: 80 */
+    lineWidth?: number;
+}
+/**
+ * Content negotiation configuration options.
+ */
+export interface ContentNegotiationOptions {
+    /** Default format to use when Accept header is missing or no match found. Default: "application/json" */
+    defaultFormat?: string;
+    /** Array of built-in formatter classes */
+    formatters?: Array<new () => IContentFormatter>;
+    /** Array of custom formatter classes (auto-discovered via DI if @provide() decorated) */
+    customFormatters?: Array<new () => IContentFormatter>;
+    /** Whether to return 406 Not Acceptable if format not supported. Default: false */
+    strictMode?: boolean;
+    /** Fallback chain of formats to try if primary format fails. */
+    fallbackChain?: Array<string>;
+    /** Whether to negotiate wildcard Accept headers (star/star). Default: true */
+    negotiateWildcards?: boolean;
+    /** Whether to negotiate partial content types (application/star). Default: true */
+    negotiatePartial?: boolean;
+    /** Whether to support quality values (q=0.9) in Accept headers. Default: true */
+    qualityValueSupport?: boolean;
+    /** Whether to cache formatter instances. Default: true */
+    cacheFormatters?: boolean;
+    /** Whether to lazy load formatters. Default: true */
+    lazyLoad?: boolean;
+    /** Content types to preload. Default: ["application/json"] */
+    preload?: Array<string>;
+    /** Format-specific default options */
+    formatDefaults?: {
+        csv?: CsvFormatOptions;
+        xml?: XmlFormatOptions;
+        yaml?: YamlFormatOptions;
+    };
+}
+/**
+ * Parsed Accept header entry with quality value.
+ */
+export interface AcceptHeaderEntry {
+    /** Content type (e.g., "application/json") */
+    type: string;
+    /** Quality value (0.0 to 1.0). Default: 1.0 */
+    quality: number;
+    /** Subtype (e.g., "json" from "application/json") */
+    subtype?: string;
+    /** Main type (e.g., "application" from "application/json") */
+    mainType?: string;
+    /** Parameters (e.g., version in "application/vnd.api+json;version=1.0") */
+    parameters?: Record<string, string>;
+}
+/**
+ * Content negotiation result.
+ */
+export interface NegotiationResult {
+    /** Selected formatter */
+    formatter: IContentFormatter;
+    /** Selected content type */
+    contentType: string;
+    /** Quality value of the match */
+    quality: number;
+}

package/lib/esm/types/middleware/interfaces/cookie-parser.interface.d.ts

@@ -0,0 +1,9 @@
+interface CookieParserOptions {
+    /**
+     * A function used for decoding cookies.
+     * By default, `decodeURIComponent` is used.
+     * You can provide a custom decoding function here.
+     */
+    decode?(val: string): string;
+}
+export { CookieParserOptions };

package/lib/esm/types/middleware/interfaces/cookie-session/cookie-session.interface.d.ts

@@ -0,0 +1,57 @@
+import { Keygrip } from "./keygrip.interface.js";
+interface CookieSessionOptions {
+    /**
+     * The name of the cookie to set, defaults to session.
+     */
+    name?: string | undefined;
+    /**
+     * The list of keys to use to sign & verify cookie values. Set cookies are always signed with keys[0], while the other keys are valid for verification, allowing for key rotation.
+     */
+    keys: Array<string> | Keygrip;
+    /**
+     * A string which will be used as single key if keys is not provided.
+     */
+    secret?: string | undefined;
+    /**
+     * a number representing the milliseconds from Date.now() for expiry.
+     */
+    maxAge?: number | undefined;
+    /**
+     * a Date object indicating the cookie's expiration date (expires at the end of session by default).
+     */
+    expires?: Date | undefined;
+    /**
+     * a string indicating the path of the cookie (/ by default).
+     */
+    path?: string | undefined;
+    /**
+     * a string indicating the domain of the cookie (no default).
+     */
+    domain?: string | undefined;
+    /**
+     * a boolean or string indicating whether the cookie is a "same site" cookie (false by default). This can be set to 'strict', 'lax', 'none', or true (which maps to 'strict').
+     */
+    sameSite?: "strict" | "lax" | "none" | boolean | undefined;
+    /**
+     * a boolean indicating whether the cookie is only to be sent over HTTPS (false by default for HTTP, true by default for HTTPS).
+     */
+    secure?: boolean | undefined;
+    /**
+     * a boolean indicating whether the cookie is only to be sent over HTTPS (use this if you handle SSL not in your node process).
+     */
+    secureProxy?: boolean | undefined;
+    /**
+     * a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (true by default).
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * a boolean indicating whether the cookie is to be signed (true by default). If this is true, another cookie of the same name with the .sig suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of cookie-name=cookie-value against the
+     * first Keygrip key. This signature key is used to detect tampering the next time a cookie is received.
+     */
+    signed?: boolean | undefined;
+    /**
+     * a boolean indicating whether to overwrite previously set cookies of the same name (true by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.
+     */
+    overwrite?: boolean | undefined;
+}
+export { CookieSessionOptions };

package/lib/esm/types/middleware/interfaces/cookie-session/keygrip.interface.d.ts

@@ -0,0 +1,27 @@
+interface Keygrip {
+    /**
+     * Signs the provided data and returns the signature as a string.
+     * @param data Data to be signed.
+     * @returns Signature string.
+     */
+    sign(data: any): string;
+    /**
+     * Verifies the provided data against a given digest (signature).
+     * @param data Data to be verified.
+     * @param digest Signature to verify against.
+     * @returns True if the verification is successful, otherwise false.
+     */
+    verify(data: any, digest: string): boolean;
+    /**
+     * Retrieves the index of the provided data in relation to a given digest (signature).
+     * @param data Data to find the index for.
+     * @param digest Signature to search for.
+     * @returns Index of the data, or -1 if not found.
+     */
+    index(data: any, digest: string): number;
+}
+interface KeygripFunction {
+    new (keys: ReadonlyArray<string>, algorithm?: string, encoding?: string): Keygrip;
+    (keys: ReadonlyArray<string>, algorithm?: string, encoding?: string): Keygrip;
+}
+export { KeygripFunction as Keygrip };

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

@@ -0,0 +1,57 @@
+/**
+ * Represents the possible values for the `origin` property in the `CorsOptions` interface.
+ */
+type StaticOrigin = boolean | string | RegExp | (boolean | string | RegExp)[];
+/**
+ * A function type to define a custom origin configuration in the `CorsOptions` interface.
+ *
+ * @param requestOrigin - The origin of the incoming request, or undefined if not available.
+ * @param callback - A callback function to indicate whether the request origin is allowed or not.
+ */
+type CustomOrigin = (requestOrigin: string | undefined, callback: (err: Error | null, origin?: StaticOrigin) => void) => void;
+/**
+ * Interface to define Cross-Origin Resource Sharing (CORS) options.
+ */
+interface CorsOptions {
+    /**
+     * Configures the Access-Control-Allow-Origin CORS header.
+     *
+     * @default '*' (allows requests from any origin)
+     */
+    origin?: StaticOrigin | CustomOrigin | undefined;
+    /**
+     * Configures the Access-Control-Allow-Methods CORS header.
+     *
+     * @default 'GET,HEAD,PUT,PATCH,POST,DELETE' (allows these HTTP methods)
+     */
+    methods?: string | Array<string> | undefined;
+    /**
+     * Configures the Access-Control-Allow-Headers CORS header.
+     */
+    allowedHeaders?: string | Array<string> | undefined;
+    /**
+     * Configures the Access-Control-Expose-Headers CORS header.
+     */
+    exposedHeaders?: string | Array<string> | undefined;
+    /**
+     * Configures the Access-Control-Allow-Credentials CORS header.
+     */
+    credentials?: boolean | undefined;
+    /**
+     * Configures the Access-Control-Max-Age CORS header.
+     */
+    maxAge?: number | undefined;
+    /**
+     * If true, allows preflight requests to pass to the next handler.
+     *
+     * @default false
+     */
+    preflightContinue?: boolean | undefined;
+    /**
+     * Defines the status code to be sent to the client on a successful OPTIONS request, as a part of the preflight request.
+     *
+     * @default 204
+     */
+    optionsSuccessStatus?: number | undefined;
+}
+export { CorsOptions };