@noony-serverless/core 0.5.1 → 0.5.2

package/build/middlewares/errorHandlerMiddleware.d.ts

@@ -1,4 +1,28 @@
 import { BaseMiddleware, Context } from '../core';
+export interface ErrorCategory {
+    type: string;
+    userMessage: string;
+    httpStatus: number;
+    retryable: boolean;
+}
+export interface ErrorMatcher {
+    /**
+     * Function to determine if this category applies to the error.
+     * Return true if the error matches this category.
+     */
+    matches: (error: Error) => boolean;
+    /**
+     * The category to return if the error matches.
+     */
+    category: ErrorCategory;
+}
+export interface ErrorHandlerOptions {
+    /**
+     * Custom error categories to check before default ones.
+     * These are evaluated in order.
+     */
+    customCategories?: ErrorMatcher[];
+}
 /**
  * Middleware class for handling errors in the application.
  * Implements the `BaseMiddleware` interface and provides an asynchronous
@@ -9,12 +33,7 @@ import { BaseMiddleware, Context } from '../core';
  *
  * @remarks
  * This middleware should be registered to catch and process errors that occur
- * during request handling.
- *
- * @method onError
- * @param error - The error object that was thrown.
- * @param context - The context in which the error occurred.
- * @returns A promise that resolves when error handling is complete.
+ * during request handling. It supports custom error categorization via options.
  *
  * @example
  * Basic handler with error handling:
@@ -36,24 +55,32 @@ import { BaseMiddleware, Context } from '../core';
  * ```
  *
  * @example
- * Google Cloud Functions integration:
+ * Usage with custom categories:
  * ```typescript
- * import { http } from '@google-cloud/functions-framework';
  * import { Handler, ErrorHandlerMiddleware } from '@noony-serverless/core';
  *
- * const orderHandler = new Handler()
- *   .use(new ErrorHandlerMiddleware())
- *   .handle(async (request, context) => {
- *     // Handler logic that might throw errors
- *     return { success: true, data: processedOrder };
- *   });
- *
- * export const processOrder = http('processOrder', (req, res) => {
- *   return orderHandler.execute(req, res);
- * });
+ * const customCategories = [{
+ *   matches: (err) => err.message.includes('payment_failed'),
+ *   category: {
+ *     type: 'PAYMENT_ERROR',
+ *     userMessage: 'Payment processing failed',
+ *     httpStatus: 402,
+ *     retryable: false
+ *   }
+ * }];
+ *
+ * const handler = new Handler()
+ *   .use(new ErrorHandlerMiddleware({ customCategories }))
+ *   .handle(...);
  * ```
  */
 export declare class ErrorHandlerMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
+    private options?;
+    /**
+     * Creates an instance of ErrorHandlerMiddleware.
+     * @param {ErrorHandlerOptions} [options] - Configuration options for the middleware, including custom error categories.
+     */
+    constructor(options?: ErrorHandlerOptions | undefined);
     onError(error: Error, context: Context<TBody, TUser>): Promise<void>;
 }
 /**
@@ -61,6 +88,7 @@ export declare class ErrorHandlerMiddleware<TBody = unknown, TUser = unknown> im
  *
  * @template TBody - The type of the request body payload (preserves type chain)
  * @template TUser - The type of the authenticated user (preserves type chain)
+ * @param {ErrorHandlerOptions} [options] - Configuration options for the middleware.
  * @returns {BaseMiddleware} An object implementing the `onError` method to handle errors.
  *
  * @remarks
@@ -75,18 +103,31 @@ export declare class ErrorHandlerMiddleware<TBody = unknown, TUser = unknown> im
  * const loginHandler = new Handler()
  *   .use(errorHandler())
  *   .handle(async (request, context) => {
- *     const { username, password } = request.body || {};
- *
- *     if (!username || !password) {
- *       throw new HttpError(400, 'Credentials required', 'MISSING_CREDENTIALS');
- *     }
- *
- *     const user = await authenticateUser(username, password);
- *     return { success: true, data: { token: generateToken(user) } };
+ *     // ...
  *   });
  * ```
  *
  * @example
+ * Usage with custom categories:
+ * ```typescript
+ * import { Handler, errorHandler } from '@noony-serverless/core';
+ *
+ * const customCategories = [{
+ *   matches: (err) => err.message.includes('custom'),
+ *   category: {
+ *     type: 'CUSTOM_ERROR',
+ *     userMessage: 'A custom error occurred',
+ *     httpStatus: 400,
+ *     retryable: false
+ *   }
+ * }];
+ *
+ * const handler = new Handler()
+ *   .use(errorHandler({ customCategories }))
+ *   .handle(...)
+ * ```
+ *
+ * @example
  * Multiple middleware chain:
  * ```typescript
  * import { Handler, errorHandler, BodyParserMiddleware } from '@noony-serverless/core';
@@ -101,5 +142,5 @@ export declare class ErrorHandlerMiddleware<TBody = unknown, TUser = unknown> im
  *   });
  * ```
  */
-export declare const errorHandler: <TBody = unknown, TUser = unknown>() => BaseMiddleware<TBody, TUser>;
+export declare const errorHandler: <TBody = unknown, TUser = unknown>(options?: ErrorHandlerOptions) => BaseMiddleware<TBody, TUser>;
 //# sourceMappingURL=errorHandlerMiddleware.d.ts.map

package/build/middlewares/errorHandlerMiddleware.js

@@ -2,6 +2,63 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.errorHandler = exports.ErrorHandlerMiddleware = void 0;
 const core_1 = require("../core");
+// Optimization: Cache environment variables to avoid process.env access on every request
+const IS_DEVELOPMENT = process.env.NODE_ENV === 'development' || process.env.DEBUG === 'true';
+const DEBUG_API_RESPONSE = process.env.DEBUG_API_RESPONSE === 'true';
+// Optimization: Pre-allocate static error categories to reduce garbage collection pressure
+const DATABASE_ERROR = {
+    type: 'DATABASE_ERROR',
+    userMessage: 'Database temporarily unavailable. Please try again.',
+    httpStatus: 503,
+    retryable: true,
+};
+const TIMEOUT_ERROR = {
+    type: 'TIMEOUT_ERROR',
+    userMessage: 'Request took too long. Please try again.',
+    httpStatus: 504,
+    retryable: true,
+};
+const EXTERNAL_SERVICE_ERROR = {
+    type: 'EXTERNAL_SERVICE_ERROR',
+    userMessage: 'External service unavailable. Please try again later.',
+    httpStatus: 502,
+    retryable: true,
+};
+const INTERNAL_ERROR = {
+    type: 'INTERNAL_ERROR',
+    userMessage: 'An unexpected error occurred.',
+    httpStatus: 500,
+    retryable: false,
+};
+const categorizeError = (error, customMatchers) => {
+    // Check custom matchers first
+    if (customMatchers) {
+        for (const matcher of customMatchers) {
+            if (matcher.matches(error)) {
+                return matcher.category;
+            }
+        }
+    }
+    const message = error.message.toLowerCase();
+    // Database errors (MongoDB, Mongoose)
+    if (message.includes('mongodb') ||
+        message.includes('mongoose') ||
+        message.includes('buffering timed out')) {
+        return DATABASE_ERROR;
+    }
+    // Timeout errors
+    if (message.includes('timeout') || message.includes('timed out')) {
+        return TIMEOUT_ERROR;
+    }
+    // Network/external service errors
+    if (message.includes('econnrefused') ||
+        message.includes('network') ||
+        message.includes('fetch failed')) {
+        return EXTERNAL_SERVICE_ERROR;
+    }
+    // Default: generic server error
+    return INTERNAL_ERROR;
+};
 /**
  * Handles errors thrown during request processing and sends an appropriate JSON response.
  *
@@ -15,25 +72,33 @@ const core_1 = require("../core");
  * @param context - The request context containing request and response objects.
  * @returns A promise that resolves when the error response has been sent.
  */
-const handleError = async (error, context) => {
-    const isDevelopment = process.env.NODE_ENV === 'development' || process.env.DEBUG === 'true';
+const handleError = async (error, context, options) => {
+    // Safe property collection for logging
+    const errorType = error?.constructor?.name;
+    const errorMessage = error?.message;
     core_1.logger.error('Error processing request', {
-        errorMessage: error?.message,
+        errorType,
+        errorMessage,
         errorStack: error?.stack,
+        errorCode: error?.code,
+        httpStatus: error?.status,
         requestId: context.requestId,
+        url: context.req.url,
+        method: context.req.method,
         userAgent: context.req.headers?.['user-agent'],
         ip: context.req.ip || 'unknown',
     });
+    const timestamp = new Date().toISOString();
     if (error instanceof core_1.HttpError) {
         const responsePayload = {
             success: false,
             payload: {
                 error: error.message,
             },
-            timestamp: new Date().toISOString(),
+            timestamp,
         };
         // Only include sensitive details in development
-        if (isDevelopment && error.details) {
+        if (IS_DEVELOPMENT && error.details) {
             responsePayload.payload.details = error.details;
         }
         // Only include error codes for client errors (4xx), not server errors
@@ -41,26 +106,33 @@ const handleError = async (error, context) => {
             responsePayload.payload.code = error.code;
         }
         context.res.status(error.status).json(responsePayload);
+        return;
     }
-    else {
-        // For non-HttpError exceptions, provide generic error message in production
-        const errorMessage = isDevelopment
-            ? error.message
-            : 'Internal Server Error';
-        const responsePayload = {
-            error: 'Internal Server Error',
-            success: false,
-            payload: {
-                error: errorMessage,
-            },
-            timestamp: new Date().toISOString(),
+    // Categorize the error for appropriate response
+    const category = categorizeError(error, options?.customCategories);
+    const responsePayload = {
+        error: category.userMessage,
+        success: false,
+        payload: {
+            error: category.userMessage,
+            code: category.type,
+        },
+        timestamp,
+    };
+    // Add retryable hint for client
+    if (category.retryable) {
+        responsePayload.payload.retryable = true;
+        context.res.header('Retry-After', '5');
+    }
+    // Include full error details when DEBUG_API_RESPONSE is enabled (dev/local)
+    if (DEBUG_API_RESPONSE) {
+        responsePayload.payload.debug = {
+            originalError: error.message,
+            stack: error.stack,
+            errorType: error.constructor?.name,
         };
-        // Add stack trace in development for non-HTTP errors
-        if (isDevelopment && error.stack) {
-            responsePayload.payload.stack = error.stack;
-        }
-        context.res.status(500).json(responsePayload);
     }
+    context.res.status(category.httpStatus).json(responsePayload);
 };
 /**
  * Middleware class for handling errors in the application.
@@ -72,12 +144,7 @@ const handleError = async (error, context) => {
  *
  * @remarks
  * This middleware should be registered to catch and process errors that occur
- * during request handling.
- *
- * @method onError
- * @param error - The error object that was thrown.
- * @param context - The context in which the error occurred.
- * @returns A promise that resolves when error handling is complete.
+ * during request handling. It supports custom error categorization via options.
  *
  * @example
  * Basic handler with error handling:
@@ -99,26 +166,36 @@ const handleError = async (error, context) => {
  * ```
  *
  * @example
- * Google Cloud Functions integration:
+ * Usage with custom categories:
  * ```typescript
- * import { http } from '@google-cloud/functions-framework';
  * import { Handler, ErrorHandlerMiddleware } from '@noony-serverless/core';
  *
- * const orderHandler = new Handler()
- *   .use(new ErrorHandlerMiddleware())
- *   .handle(async (request, context) => {
- *     // Handler logic that might throw errors
- *     return { success: true, data: processedOrder };
- *   });
+ * const customCategories = [{
+ *   matches: (err) => err.message.includes('payment_failed'),
+ *   category: {
+ *     type: 'PAYMENT_ERROR',
+ *     userMessage: 'Payment processing failed',
+ *     httpStatus: 402,
+ *     retryable: false
+ *   }
+ * }];
  *
- * export const processOrder = http('processOrder', (req, res) => {
- *   return orderHandler.execute(req, res);
- * });
+ * const handler = new Handler()
+ *   .use(new ErrorHandlerMiddleware({ customCategories }))
+ *   .handle(...);
  * ```
  */
 class ErrorHandlerMiddleware {
+    options;
+    /**
+     * Creates an instance of ErrorHandlerMiddleware.
+     * @param {ErrorHandlerOptions} [options] - Configuration options for the middleware, including custom error categories.
+     */
+    constructor(options) {
+        this.options = options;
+    }
     async onError(error, context) {
-        await handleError(error, context);
+        await handleError(error, context, this.options);
     }
 }
 exports.ErrorHandlerMiddleware = ErrorHandlerMiddleware;
@@ -127,6 +204,7 @@ exports.ErrorHandlerMiddleware = ErrorHandlerMiddleware;
  *
  * @template TBody - The type of the request body payload (preserves type chain)
  * @template TUser - The type of the authenticated user (preserves type chain)
+ * @param {ErrorHandlerOptions} [options] - Configuration options for the middleware.
  * @returns {BaseMiddleware} An object implementing the `onError` method to handle errors.
  *
  * @remarks
@@ -141,15 +219,28 @@ exports.ErrorHandlerMiddleware = ErrorHandlerMiddleware;
  * const loginHandler = new Handler()
  *   .use(errorHandler())
  *   .handle(async (request, context) => {
- *     const { username, password } = request.body || {};
+ *     // ...
+ *   });
+ * ```
  *
- *     if (!username || !password) {
- *       throw new HttpError(400, 'Credentials required', 'MISSING_CREDENTIALS');
- *     }
+ * @example
+ * Usage with custom categories:
+ * ```typescript
+ * import { Handler, errorHandler } from '@noony-serverless/core';
  *
- *     const user = await authenticateUser(username, password);
- *     return { success: true, data: { token: generateToken(user) } };
- *   });
+ * const customCategories = [{
+ *   matches: (err) => err.message.includes('custom'),
+ *   category: {
+ *     type: 'CUSTOM_ERROR',
+ *     userMessage: 'A custom error occurred',
+ *     httpStatus: 400,
+ *     retryable: false
+ *   }
+ * }];
+ *
+ * const handler = new Handler()
+ *   .use(errorHandler({ customCategories }))
+ *   .handle(...)
  * ```
  *
  * @example
@@ -167,9 +258,9 @@ exports.ErrorHandlerMiddleware = ErrorHandlerMiddleware;
  *   });
  * ```
  */
-const errorHandler = () => ({
+const errorHandler = (options) => ({
     onError: async (error, context) => {
-        await handleError(error, context);
+        await handleError(error, context, options);
     },
 });
 exports.errorHandler = errorHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noony-serverless/core",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "A Middy base framework compatible with Firebase and GCP Cloud Functions with TypeScript",
   "main": "build/index.js",
   "types": "build/index.d.ts",