@fishka/express 0.9.6 → 0.9.7

package/dist/cjs/router.js

@@ -38,7 +38,7 @@ exports.mount = mount;
 const assertions_1 = require("@fishka/assertions");
 const url = __importStar(require("url"));
 const api_types_1 = require("./api.types");
-const http_types_1 = require("./http.types");
+const http_status_codes_1 = require("./http-status-codes");
 const error_handling_1 = require("./error-handling");
 const thread_local_storage_1 = require("./thread-local/thread-local-storage");
 const conversion_utils_1 = require("./utils/conversion.utils");
@@ -103,7 +103,7 @@ function createRouteHandler(method, endpoint) {
         if (tls?.requestId) {
             response.requestId = tls.requestId;
         }
-        response.status = response.status || http_types_1.OK_STATUS;
+        response.status = response.status || http_status_codes_1.HTTP_OK;
         res.status(response.status);
         res.send(response);
     };
@@ -119,12 +119,12 @@ function validateUrlParameters(req, { $path, $query, }) {
             // Run Global Validation if registered.
             const globalValidator = api_types_1.URL_PARAMETER_INFO[key]?.validator;
             if (globalValidator) {
-                (0, assertions_1.callValueAssertion)(value, globalValidator, `${http_types_1.BAD_REQUEST_STATUS}`);
+                (0, assertions_1.callValueAssertion)(value, globalValidator, `${http_status_codes_1.HTTP_BAD_REQUEST}`);
             }
             // Run Local Validation.
             const validator = $path?.[key];
             if (validator) {
-                (0, assertions_1.callValueAssertion)(value, validator, `${http_types_1.BAD_REQUEST_STATUS}`);
+                (0, assertions_1.callValueAssertion)(value, validator, `${http_status_codes_1.HTTP_BAD_REQUEST}`);
             }
         }
         const parsedUrl = url.parse(req.url, true);
@@ -136,16 +136,16 @@ function validateUrlParameters(req, { $path, $query, }) {
                 // Query params can be string | string[] | undefined. Global validators usually expect string.
                 // We only validate if it's a single value or handle array in validator.
                 // For simplicity, we pass value as is (unknown) to assertion.
-                (0, assertions_1.callValueAssertion)(value, globalValidator, `${http_types_1.BAD_REQUEST_STATUS}`);
+                (0, assertions_1.callValueAssertion)(value, globalValidator, `${http_status_codes_1.HTTP_BAD_REQUEST}`);
             }
             const validator = $query?.[key];
             if (validator) {
-                (0, assertions_1.callValueAssertion)(value, validator, `${http_types_1.BAD_REQUEST_STATUS}`);
+                (0, assertions_1.callValueAssertion)(value, validator, `${http_status_codes_1.HTTP_BAD_REQUEST}`);
             }
         }
     }
     catch (error) {
-        throw new api_types_1.HttpError(http_types_1.BAD_REQUEST_STATUS, (0, assertions_1.getMessageFromError)(error));
+        throw new api_types_1.HttpError(http_status_codes_1.HTTP_BAD_REQUEST, (0, assertions_1.getMessageFromError)(error));
     }
 }
 /**
@@ -178,23 +178,23 @@ async function executeBodyEndpoint(route, req, res) {
         // Handle validation based on whether validator is an object or function
         if (typeof validator === 'function') {
             // It's a ValueAssertion (function)
-            (0, assertions_1.callValueAssertion)(apiRequest, validator, `${http_types_1.BAD_REQUEST_STATUS}: request body`);
+            (0, assertions_1.callValueAssertion)(apiRequest, validator, `${http_status_codes_1.HTTP_BAD_REQUEST}: request body`);
         }
         else {
             // It's an ObjectAssertion - use validateObject
             // We strictly assume it is an object because of the type definition (function | object)
             const objectValidator = validator;
             const isEmptyValidator = Object.keys(objectValidator).length === 0;
-            const error = (0, assertions_1.validateObject)(apiRequest, objectValidator, `${http_types_1.BAD_REQUEST_STATUS}: request body`, {
+            const errorMessage = (0, assertions_1.validateObject)(apiRequest, objectValidator, `${http_status_codes_1.HTTP_BAD_REQUEST}: request body`, {
                 failOnUnknownFields: !isEmptyValidator,
             });
-            (0, assertions_1.assertTruthy)(!error, error);
+            (0, api_types_1.assertHttp)(!errorMessage, http_status_codes_1.HTTP_BAD_REQUEST, errorMessage || 'Request body validation failed');
         }
     }
     catch (error) {
         if (error instanceof api_types_1.HttpError)
             throw error;
-        throw new api_types_1.HttpError(http_types_1.BAD_REQUEST_STATUS, (0, assertions_1.getMessageFromError)(error));
+        throw new api_types_1.HttpError(http_status_codes_1.HTTP_BAD_REQUEST, (0, assertions_1.getMessageFromError)(error));
     }
     const requestContext = newRequestContext(apiRequest, req, res);
     validateUrlParameters(req, { $path: route.$path, $query: route.$query });

package/dist/esm/api.types.d.ts

@@ -5,6 +5,38 @@ export declare class HttpError extends Error {
     readonly details?: Record<string, unknown> | undefined;
     constructor(status: number, message: string, details?: Record<string, unknown> | undefined);
 }
+/**
+ * Asserts that a condition is true, throwing an HttpError with the specified status code if false.
+ * This function is designed for HTTP-specific validation where you want to throw appropriate HTTP status codes.
+ *
+ * @param condition - The condition to check. If false, an HttpError will be thrown.
+ * @param status - The HTTP status code to use in the HttpError (e.g., 400 for Bad Request, 404 for Not Found).
+ * @param message - The error message to include in the HttpError.
+ *
+ * @throws {HttpError} If the condition is false, throws an HttpError with the specified status and message.
+ *
+ * @example
+ * ```typescript
+ * // Validate required parameter
+ * assertHttp(typeof userId === 'string', HTTP_BAD_REQUEST, 'User ID must be a string');
+ *
+ * // Validate resource existence
+ * assertHttp(user !== null, HTTP_NOT_FOUND, 'User not found');
+ *
+ * // Validate authorization
+ * assertHttp(user.isAdmin, HTTP_FORBIDDEN, 'Admin access required');
+ *
+ * // Validate authentication
+ * assertHttp(req.headers.authorization, HTTP_UNAUTHORIZED, 'Authorization header required');
+ * ```
+ *
+ * @see {@link HttpError}
+ * @see {@link HTTP_BAD_REQUEST}
+ * @see {@link HTTP_NOT_FOUND}
+ * @see {@link HTTP_FORBIDDEN}
+ * @see {@link HTTP_UNAUTHORIZED}
+ */
+export declare function assertHttp(condition: boolean, status: number, message: string): void;
 export interface ApiResponse<ResponseEntity = unknown> {
     /** Result of the call. A single entity for non-paginated ${by-id} requests or an array for list queries. */
     result: ResponseEntity;

package/dist/esm/api.types.js

@@ -1,13 +1,48 @@
 import { assertString, assertTruthy } from '@fishka/assertions';
+import { HTTP_BAD_REQUEST } from './http-status-codes';
 export class HttpError extends Error {
     constructor(status, message, details) {
         super(message);
         this.status = status;
         this.details = details;
-        // Restore prototype chain for instanceof checks
+        // Restore the prototype chain for instanceof checks.
         Object.setPrototypeOf(this, HttpError.prototype);
     }
 }
+/**
+ * Asserts that a condition is true, throwing an HttpError with the specified status code if false.
+ * This function is designed for HTTP-specific validation where you want to throw appropriate HTTP status codes.
+ *
+ * @param condition - The condition to check. If false, an HttpError will be thrown.
+ * @param status - The HTTP status code to use in the HttpError (e.g., 400 for Bad Request, 404 for Not Found).
+ * @param message - The error message to include in the HttpError.
+ *
+ * @throws {HttpError} If the condition is false, throws an HttpError with the specified status and message.
+ *
+ * @example
+ * ```typescript
+ * // Validate required parameter
+ * assertHttp(typeof userId === 'string', HTTP_BAD_REQUEST, 'User ID must be a string');
+ *
+ * // Validate resource existence
+ * assertHttp(user !== null, HTTP_NOT_FOUND, 'User not found');
+ *
+ * // Validate authorization
+ * assertHttp(user.isAdmin, HTTP_FORBIDDEN, 'Admin access required');
+ *
+ * // Validate authentication
+ * assertHttp(req.headers.authorization, HTTP_UNAUTHORIZED, 'Authorization header required');
+ * ```
+ *
+ * @see {@link HttpError}
+ * @see {@link HTTP_BAD_REQUEST}
+ * @see {@link HTTP_NOT_FOUND}
+ * @see {@link HTTP_FORBIDDEN}
+ * @see {@link HTTP_UNAUTHORIZED}
+ */
+export function assertHttp(condition, status, message) {
+    assertTruthy(condition, () => new HttpError(status, message));
+}
 /** Converts an API response value into a standardized ApiResponse structure. */
 export function response(result) {
     return { result };
@@ -27,5 +62,5 @@ export function registerUrlParameter(name, info) {
  */
 export function assertUrlParameter(name) {
     assertString(name, 'Url parameter name must be a string');
-    assertTruthy(URL_PARAMETER_INFO[name], `Invalid URL parameter: '${name}'. Please register it using 'registerUrlParameter('${name}', ...)'`);
+    assertHttp(URL_PARAMETER_INFO[name] !== undefined, HTTP_BAD_REQUEST, `Invalid URL parameter: '${name}'. Please register it using 'registerUrlParameter('${name}', ...)'`);
 }

package/dist/esm/auth/auth-strategy.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Basic authentication strategy using username/password validation.
  * Parses HTTP Basic Authorization header and validates credentials.
@@ -51,7 +51,7 @@ export class BasicAuthStrategy {
     async validateCredentials({ username, password }) {
         const user = await this.verifyFn(username, password);
         if (!user) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'Invalid username or password');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'Invalid username or password');
         }
         return user;
     }

package/dist/esm/auth/auth.utils.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Creates a middleware that enforces authentication using the provided strategy.
  * The authenticated user is stored in the context under the 'authUser' key.
@@ -16,7 +16,7 @@ export function createAuthMiddleware(strategy, onSuccess) {
         // If no credentials found (and strategy returned undefined), we must deny access here.
         // In a composite strategy scenario, we might want to try the next strategy, but this helper is for a single strategy enforcement.
         if (!credentials) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'No credentials provided or invalid format');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'No credentials provided or invalid format');
         }
         // Validate credentials and get authenticated user
         const user = await strategy.validateCredentials(credentials);
@@ -42,7 +42,7 @@ export function createAuthMiddleware(strategy, onSuccess) {
 export function getAuthUser(context) {
     const user = context.authUser;
     if (!user) {
-        throw new HttpError(UNAUTHORIZED_STATUS, 'User not found in context. Did you add auth middleware?');
+        throw new HttpError(HTTP_UNAUTHORIZED, 'User not found in context. Did you add auth middleware?');
     }
     return user;
 }

package/dist/esm/auth/bearer-auth-strategy.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Bearer authentication strategy (commonly used for JWTs).
  * Extracts the token from the 'Authorization: Bearer <token>' header.
@@ -48,7 +48,7 @@ export class BearerAuthStrategy {
     async validateCredentials(token) {
         const user = await this.verifyFn(token);
         if (!user) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'Invalid token');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'Invalid token');
         }
         return user;
     }

package/dist/esm/error-handling.js

@@ -1,6 +1,6 @@
 import { getMessageFromError } from '@fishka/assertions';
 import { HttpError } from './api.types';
-import { BAD_REQUEST_STATUS, INTERNAL_ERROR_STATUS } from './http.types';
+import { HTTP_BAD_REQUEST, HTTP_INTERNAL_SERVER_ERROR } from './http-status-codes';
 import { getRequestLocalStorage } from './thread-local/thread-local-storage';
 import { wrapAsApiResponse } from './utils/conversion.utils';
 function buildApiResponse(error) {
@@ -20,7 +20,7 @@ function buildApiResponse(error) {
         response = {
             ...wrapAsApiResponse(undefined),
             error: errorMessage && errorMessage.length > 0 ? errorMessage : 'Internal error',
-            status: INTERNAL_ERROR_STATUS,
+            status: HTTP_INTERNAL_SERVER_ERROR,
         };
     }
     if (requestId) {
@@ -36,7 +36,7 @@ export function catchRouteErrors(fn) {
         }
         catch (error) {
             const apiResponse = buildApiResponse(error);
-            if (apiResponse.status >= INTERNAL_ERROR_STATUS) {
+            if (apiResponse.status >= HTTP_INTERNAL_SERVER_ERROR) {
                 console.error(`catchRouteErrors: ${req.path}`, error);
             }
             else {
@@ -59,7 +59,7 @@ export async function catchAllMiddleware(error, _, res, next) {
     // Report as critical. This kind of error should never happen.
     console.error('catchAllMiddleware:', getMessageFromError(error));
     const apiResponse = error instanceof SyntaxError // JSON body parsing error.
-        ? buildApiResponse(`${BAD_REQUEST_STATUS}: Failed to parse request: ${error.message}`)
+        ? buildApiResponse(`${HTTP_BAD_REQUEST}: Failed to parse request: ${error.message}`)
         : buildApiResponse(error);
     res.status(apiResponse.status);
     res.send(apiResponse);

package/dist/esm/http-status-codes.d.ts

@@ -0,0 +1,179 @@
+/** The request has succeeded (200) */
+export declare const HTTP_OK = 200;
+/** The request has been fulfilled, and a new resource is created (201) */
+export declare const HTTP_CREATED = 201;
+/** The request has been accepted for processing, but the processing is not yet complete (202) */
+export declare const HTTP_ACCEPTED = 202;
+/** The server successfully processed the request, and is not returning any content (204) */
+export declare const HTTP_NO_CONTENT = 204;
+/** The request has been successfully processed, but is returning no content (205) */
+export declare const HTTP_RESET_CONTENT = 205;
+/** The server is delivering only part of the resource due to a range header sent by the client (206) */
+export declare const HTTP_PARTIAL_CONTENT = 206;
+/** The IM used the server processed a request successfully, but the response is transformed (226) */
+export declare const HTTP_IM_USED = 226;
+/** The resource has been moved permanently to a new URL (301) */
+export declare const HTTP_MOVED_PERMANENTLY = 301;
+/** The resource is available at a different URL (302) */
+export declare const HTTP_FOUND = 302;
+/** The resource has not been modified since the last request (304) */
+export declare const HTTP_NOT_MODIFIED = 304;
+/** The server could not understand the request due to invalid syntax (400) */
+export declare const HTTP_BAD_REQUEST = 400;
+/** The client must authenticate itself to get the requested response (401) */
+export declare const HTTP_UNAUTHORIZED = 401;
+/** The client does not have access rights to the content (403) */
+export declare const HTTP_FORBIDDEN = 403;
+/** The server cannot find the requested resource (404) */
+export declare const HTTP_NOT_FOUND = 404;
+/** The request method is known by the server but is not supported by the target resource (405) */
+export declare const HTTP_METHOD_NOT_ALLOWED = 405;
+/** The client must authenticate using a proxy (407) */
+export declare const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407;
+/** The server timed out waiting for the request (408) */
+export declare const HTTP_REQUEST_TIMEOUT = 408;
+/** The request conflicts with the current state of the server (409) */
+export declare const HTTP_CONFLICT = 409;
+/** The resource requested is no longer available and will not be available again (410) */
+export declare const HTTP_GONE = 410;
+/** The request does not meet the preconditions that the server requires (412) */
+export declare const HTTP_PRECONDITION_FAILED = 412;
+/** The client sent a request that is too large for the server to process (413) */
+export declare const HTTP_PAYLOAD_TOO_LARGE = 413;
+/** The URI requested by the client is too long for the server to process (414) */
+export declare const HTTP_URI_TOO_LONG = 414;
+/** The media format of the requested data is not supported by the server (415) */
+export declare const HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
+/** The range specified by the client cannot be fulfilled (416) */
+export declare const HTTP_RANGE_NOT_SATISFIABLE = 416;
+/** The expectation given in the request header could not be met by the server (417) */
+export declare const HTTP_EXPECTATION_FAILED = 417;
+/** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+export declare const HTTP_IM_A_TEAPOT = 418;
+/** The request was well-formed but was unable to be followed due to semantic errors (422) */
+export declare const HTTP_UNPROCESSABLE_ENTITY = 422;
+/** The resource that is being accessed is locked (423) */
+export declare const HTTP_LOCKED = 423;
+/** The resource requested is dependent on another resource that has failed (424) */
+export declare const HTTP_FAILED_DEPENDENCY = 424;
+/** The server is unwilling to risk processing a request that might be replayed (425) */
+export declare const HTTP_TOO_EARLY = 425;
+/** The client needs to upgrade its protocol (426) */
+export declare const HTTP_UPGRADE_REQUIRED = 426;
+/** The server requires the request to be conditional (428) */
+export declare const HTTP_PRECONDITION_REQUIRED = 428;
+/** The client has sent too many requests in a given amount of time (429) */
+export declare const HTTP_TOO_MANY_REQUESTS = 429;
+/** The request header fields are too large (431) */
+export declare const HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431;
+/** The client closed the connection with the server before the request was completed (444) */
+export declare const HTTP_CONNECTION_CLOSED_WITHOUT_RESPONSE = 444;
+/** The client requested an unavailable legal action (451) */
+export declare const HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451;
+/** The server encountered an internal error and was unable to complete the request (500) */
+export declare const HTTP_INTERNAL_SERVER_ERROR = 500;
+/** The request method is not supported by the server and cannot be handled (501) */
+export declare const HTTP_NOT_IMPLEMENTED = 501;
+/** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+export declare const HTTP_BAD_GATEWAY = 502;
+/** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+export declare const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+export declare const HTTP_GATEWAY_TIMEOUT = 504;
+/**
+ * An object containing common HTTP status codes.
+ * These constants can be used to improve code readability and maintainability.
+ * @deprecated Use individual HTTP_* constants for better tree-shaking
+ */
+export declare const HttpStatusCode: {
+    /** The request has succeeded (200) */
+    OK: number;
+    /** The request has been fulfilled, and a new resource is created (201) */
+    CREATED: number;
+    /** The request has been accepted for processing, but the processing is not yet complete (202) */
+    ACCEPTED: number;
+    /** The server successfully processed the request, and is not returning any content (204) */
+    NO_CONTENT: number;
+    /** The request has been successfully processed, but is returning no content (205) */
+    RESET_CONTENT: number;
+    /** The server is delivering only part of the resource due to a range header sent by the client (206) */
+    PARTIAL_CONTENT: number;
+    /** The IM used the server processed a request successfully, but the response is transformed (226) */
+    IM_USED: number;
+    /** The resource has been moved permanently to a new URL (301) */
+    MOVED_PERMANENTLY: number;
+    /** The resource is available at a different URL (302) */
+    FOUND: number;
+    /** The resource has not been modified since the last request (304) */
+    NOT_MODIFIED: number;
+    /** The server could not understand the request due to invalid syntax (400) */
+    BAD_REQUEST: number;
+    /** The client must authenticate itself to get the requested response (401) */
+    UNAUTHORIZED: number;
+    /** The client does not have access rights to the content (403) */
+    FORBIDDEN: number;
+    /** The server cannot find the requested resource (404) */
+    NOT_FOUND: number;
+    /** The request method is known by the server but is not supported by the target resource (405) */
+    METHOD_NOT_ALLOWED: number;
+    /** The client must authenticate using a proxy (407) */
+    PROXY_AUTHENTICATION_REQUIRED: number;
+    /** The server timed out waiting for the request (408) */
+    REQUEST_TIMEOUT: number;
+    /** The request conflicts with the current state of the server (409) */
+    CONFLICT: number;
+    /** The resource requested is no longer available and will not be available again (410) */
+    GONE: number;
+    /** The request does not meet the preconditions that the server requires (412) */
+    PRECONDITION_FAILED: number;
+    /** The client sent a request that is too large for the server to process (413) */
+    PAYLOAD_TOO_LARGE: number;
+    /** The URI requested by the client is too long for the server to process (414) */
+    URI_TOO_LONG: number;
+    /** The media format of the requested data is not supported by the server (415) */
+    UNSUPPORTED_MEDIA_TYPE: number;
+    /** The range specified by the client cannot be fulfilled (416) */
+    RANGE_NOT_SATISFIABLE: number;
+    /** The expectation given in the request header could not be met by the server (417) */
+    EXPECTATION_FAILED: number;
+    /** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+    IM_A_TEAPOT: number;
+    /** The request was well-formed but was unable to be followed due to semantic errors (422) */
+    UNPROCESSABLE_ENTITY: number;
+    /** The resource that is being accessed is locked (423) */
+    LOCKED: number;
+    /** The resource requested is dependent on another resource that has failed (424) */
+    FAILED_DEPENDENCY: number;
+    /** The server is unwilling to risk processing a request that might be replayed (425) */
+    TOO_EARLY: number;
+    /** The client needs to upgrade its protocol (426) */
+    UPGRADE_REQUIRED: number;
+    /** The server requires the request to be conditional (428) */
+    PRECONDITION_REQUIRED: number;
+    /** The client has sent too many requests in a given amount of time (429) */
+    TOO_MANY_REQUESTS: number;
+    /** The request header fields are too large (431) */
+    REQUEST_HEADER_FIELDS_TOO_LARGE: number;
+    /** The client closed the connection with the server before the request was completed (444) */
+    CONNECTION_CLOSED_WITHOUT_RESPONSE: number;
+    /** The client requested an unavailable legal action (451) */
+    UNAVAILABLE_FOR_LEGAL_REASONS: number;
+    /** The server encountered an internal error and was unable to complete the request (500) */
+    INTERNAL_SERVER_ERROR: number;
+    /** The request method is not supported by the server and cannot be handled (501) */
+    NOT_IMPLEMENTED: number;
+    /** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+    BAD_GATEWAY: number;
+    /** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+    SERVICE_UNAVAILABLE: number;
+    /** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+    GATEWAY_TIMEOUT: number;
+};
+/**
+ * Returns the reason phrase corresponding to the given HTTP status code.
+ * This is useful for converting status codes into human-readable messages.
+ *
+ * @param statusCode - The HTTP status code for which to get the reason phrase.
+ * @returns The reason phrase associated with the given status code, or "Unknown Status Code" if the status code is not recognized.
+ */
+export declare const getHttpStatusCodeReasonPhrase: (statusCode: number) => string;