@noony-serverless/core 0.1.0 → 0.1.5

package/build/middlewares/queryParametersMiddleware.js

@@ -20,6 +20,50 @@ const convertQueryToRecord = (query) => {
     }
     return result;
 };
+/**
+ * Middleware class that validates and processes query parameters from the request URL.
+ * Extracts query parameters and validates that required parameters are present.
+ *
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic query parameter validation:
+ * ```typescript
+ * import { Handler, QueryParametersMiddleware } from '@noony-serverless/core';
+ *
+ * const searchHandler = new Handler()
+ *   .use(new QueryParametersMiddleware(['q', 'type']))
+ *   .handle(async (context) => {
+ *     const { q, type } = context.req.query;
+ *     const results = await search(q, type);
+ *     return { success: true, results, query: q, type };
+ *   });
+ * ```
+ *
+ * @example
+ * Pagination with required parameters:
+ * ```typescript
+ * const listHandler = new Handler()
+ *   .use(new QueryParametersMiddleware(['page', 'limit']))
+ *   .handle(async (context) => {
+ *     const { page, limit, sort } = context.req.query;
+ *     const items = await getItems(parseInt(page), parseInt(limit), sort);
+ *     return { success: true, items, pagination: { page, limit } };
+ *   });
+ * ```
+ *
+ * @example
+ * Optional parameters (empty required array):
+ * ```typescript
+ * const flexibleHandler = new Handler()
+ *   .use(new QueryParametersMiddleware([])) // No required parameters
+ *   .handle(async (context) => {
+ *     const { filter, sort, category } = context.req.query || {};
+ *     const data = await getData({ filter, sort, category });
+ *     return { success: true, data };
+ *   });
+ * ```
+ */
 class QueryParametersMiddleware {
     requiredParams;
     constructor(requiredParams = []) {
@@ -36,6 +80,67 @@ class QueryParametersMiddleware {
     }
 }
 exports.QueryParametersMiddleware = QueryParametersMiddleware;
+/**
+ * Factory function that creates a query parameter processing middleware.
+ * Extracts and validates query parameters from the request URL.
+ *
+ * @param requiredParams - Array of parameter names that must be present (default: empty array)
+ * @returns BaseMiddleware object with query parameter processing logic
+ *
+ * @example
+ * API endpoint with required search parameters:
+ * ```typescript
+ * import { Handler, queryParametersMiddleware } from '@noony-serverless/core';
+ *
+ * const searchApiHandler = new Handler()
+ *   .use(queryParametersMiddleware(['q'])) // 'q' parameter is required
+ *   .handle(async (context) => {
+ *     const { q, category, sort } = context.req.query;
+ *     const searchResults = await performSearch(q, { category, sort });
+ *     return { success: true, results: searchResults };
+ *   });
+ * ```
+ *
+ * @example
+ * E-commerce product listing with filters:
+ * ```typescript
+ * const productListHandler = new Handler()
+ *   .use(queryParametersMiddleware(['category'])) // Category is required
+ *   .handle(async (context) => {
+ *     const { category, price_min, price_max, brand, sort } = context.req.query;
+ *     const products = await getProducts({
+ *       category,
+ *       priceRange: { min: price_min, max: price_max },
+ *       brand,
+ *       sortBy: sort || 'name'
+ *     });
+ *     return { success: true, products, filters: { category, brand, sort } };
+ *   });
+ * ```
+ *
+ * @example
+ * Flexible API with optional parameters:
+ * ```typescript
+ * const dataHandler = new Handler()
+ *   .use(queryParametersMiddleware()) // No required parameters
+ *   .handle(async (context) => {
+ *     const queryParams = context.req.query || {};
+ *     const {
+ *       page = '1',
+ *       limit = '10',
+ *       sort = 'created_at',
+ *       order = 'desc'
+ *     } = queryParams;
+ *
+ *     const data = await fetchData({
+ *       pagination: { page: parseInt(page), limit: parseInt(limit) },
+ *       sorting: { field: sort, order }
+ *     });
+ *
+ *     return { success: true, data, meta: { page, limit, sort, order } };
+ *   });
+ * ```
+ */
 const queryParametersMiddleware = (requiredParams = []) => ({
     async before(context) {
         const host = (Array.isArray(context.req.headers.host)

package/build/middlewares/rateLimitingMiddleware.d.ts

@@ -86,8 +86,69 @@ declare class MemoryStore implements RateLimitStore {
     destroy(): void;
 }
 /**
- * Rate Limiting Middleware
- * Implements sliding window rate limiting with comprehensive features
+ * Rate Limiting Middleware with sliding window implementation.
+ * Implements comprehensive rate limiting with dynamic limits, custom storage, and security features.
+ *
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic API rate limiting:
+ * ```typescript
+ * import { Handler, RateLimitingMiddleware } from '@noony-serverless/core';
+ *
+ * const apiHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 100,
+ *     windowMs: 60000, // 1 minute
+ *     message: 'Too many API requests'
+ *   }))
+ *   .handle(async (context) => {
+ *     const data = await getApiData();
+ *     return { success: true, data };
+ *   });
+ * ```
+ *
+ * @example
+ * Authentication endpoint with strict limits:
+ * ```typescript
+ * const loginHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 5,
+ *     windowMs: 60000, // 1 minute
+ *     message: 'Too many login attempts',
+ *     statusCode: 429
+ *   }))
+ *   .handle(async (context) => {
+ *     const { email, password } = context.req.parsedBody;
+ *     const token = await authenticate(email, password);
+ *     return { success: true, token };
+ *   });
+ * ```
+ *
+ * @example
+ * Dynamic limits based on user authentication:
+ * ```typescript
+ * const smartApiHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 50, // Default for unauthenticated
+ *     windowMs: 60000,
+ *     dynamicLimits: {
+ *       authenticated: {
+ *         maxRequests: 1000,
+ *         windowMs: 60000,
+ *         matcher: (context) => !!context.user
+ *       },
+ *       premium: {
+ *         maxRequests: 5000,
+ *         windowMs: 60000,
+ *         matcher: (context) => context.user?.plan === 'premium'
+ *       }
+ *     }
+ *   }))
+ *   .handle(async (context) => {
+ *     return { success: true, limit: 'applied dynamically' };
+ *   });
+ * ```
  */
 export declare class RateLimitingMiddleware implements BaseMiddleware {
     private store;
@@ -96,9 +157,52 @@ export declare class RateLimitingMiddleware implements BaseMiddleware {
     before(context: Context): Promise<void>;
 }
 /**
- * Rate Limiting Middleware Factory
- * @param options Rate limiting configuration
- * @returns BaseMiddleware
+ * Factory function that creates a rate limiting middleware.
+ * Provides flexible rate limiting with configurable options and presets.
+ *
+ * @param options - Rate limiting configuration options
+ * @returns BaseMiddleware instance
+ *
+ * @example
+ * Using preset configurations:
+ * ```typescript
+ * import { Handler, rateLimiting, RateLimitPresets } from '@noony-serverless/core';
+ *
+ * // Strict limits for sensitive endpoints
+ * const authHandler = new Handler()
+ *   .use(rateLimiting(RateLimitPresets.AUTH))
+ *   .handle(async (context) => {
+ *     return await handleAuthentication(context.req.parsedBody);
+ *   });
+ *
+ * // Standard API limits
+ * const apiHandler = new Handler()
+ *   .use(rateLimiting(RateLimitPresets.API))
+ *   .handle(async (context) => {
+ *     return await handleApiRequest(context);
+ *   });
+ * ```
+ *
+ * @example
+ * Custom rate limiting with skip conditions:
+ * ```typescript
+ * const conditionalHandler = new Handler()
+ *   .use(rateLimiting({
+ *     maxRequests: 100,
+ *     windowMs: 60000,
+ *     skip: (context) => {
+ *       // Skip rate limiting for admin users
+ *       return context.user?.role === 'admin';
+ *     },
+ *     keyGenerator: (context) => {
+ *       // Rate limit per user instead of IP
+ *       return context.user?.id || context.req.ip || 'anonymous';
+ *     }
+ *   }))
+ *   .handle(async (context) => {
+ *     return { success: true, message: 'Request processed' };
+ *   });
+ * ```
  */
 export declare const rateLimiting: (options?: RateLimitOptions) => BaseMiddleware;
 /**

package/build/middlewares/rateLimitingMiddleware.js

@@ -104,8 +104,69 @@ const getRateLimit = (context, options) => {
     };
 };
 /**
- * Rate Limiting Middleware
- * Implements sliding window rate limiting with comprehensive features
+ * Rate Limiting Middleware with sliding window implementation.
+ * Implements comprehensive rate limiting with dynamic limits, custom storage, and security features.
+ *
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic API rate limiting:
+ * ```typescript
+ * import { Handler, RateLimitingMiddleware } from '@noony-serverless/core';
+ *
+ * const apiHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 100,
+ *     windowMs: 60000, // 1 minute
+ *     message: 'Too many API requests'
+ *   }))
+ *   .handle(async (context) => {
+ *     const data = await getApiData();
+ *     return { success: true, data };
+ *   });
+ * ```
+ *
+ * @example
+ * Authentication endpoint with strict limits:
+ * ```typescript
+ * const loginHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 5,
+ *     windowMs: 60000, // 1 minute
+ *     message: 'Too many login attempts',
+ *     statusCode: 429
+ *   }))
+ *   .handle(async (context) => {
+ *     const { email, password } = context.req.parsedBody;
+ *     const token = await authenticate(email, password);
+ *     return { success: true, token };
+ *   });
+ * ```
+ *
+ * @example
+ * Dynamic limits based on user authentication:
+ * ```typescript
+ * const smartApiHandler = new Handler()
+ *   .use(new RateLimitingMiddleware({
+ *     maxRequests: 50, // Default for unauthenticated
+ *     windowMs: 60000,
+ *     dynamicLimits: {
+ *       authenticated: {
+ *         maxRequests: 1000,
+ *         windowMs: 60000,
+ *         matcher: (context) => !!context.user
+ *       },
+ *       premium: {
+ *         maxRequests: 5000,
+ *         windowMs: 60000,
+ *         matcher: (context) => context.user?.plan === 'premium'
+ *       }
+ *     }
+ *   }))
+ *   .handle(async (context) => {
+ *     return { success: true, limit: 'applied dynamically' };
+ *   });
+ * ```
  */
 class RateLimitingMiddleware {
     store;
@@ -179,9 +240,52 @@ class RateLimitingMiddleware {
 }
 exports.RateLimitingMiddleware = RateLimitingMiddleware;
 /**
- * Rate Limiting Middleware Factory
- * @param options Rate limiting configuration
- * @returns BaseMiddleware
+ * Factory function that creates a rate limiting middleware.
+ * Provides flexible rate limiting with configurable options and presets.
+ *
+ * @param options - Rate limiting configuration options
+ * @returns BaseMiddleware instance
+ *
+ * @example
+ * Using preset configurations:
+ * ```typescript
+ * import { Handler, rateLimiting, RateLimitPresets } from '@noony-serverless/core';
+ *
+ * // Strict limits for sensitive endpoints
+ * const authHandler = new Handler()
+ *   .use(rateLimiting(RateLimitPresets.AUTH))
+ *   .handle(async (context) => {
+ *     return await handleAuthentication(context.req.parsedBody);
+ *   });
+ *
+ * // Standard API limits
+ * const apiHandler = new Handler()
+ *   .use(rateLimiting(RateLimitPresets.API))
+ *   .handle(async (context) => {
+ *     return await handleApiRequest(context);
+ *   });
+ * ```
+ *
+ * @example
+ * Custom rate limiting with skip conditions:
+ * ```typescript
+ * const conditionalHandler = new Handler()
+ *   .use(rateLimiting({
+ *     maxRequests: 100,
+ *     windowMs: 60000,
+ *     skip: (context) => {
+ *       // Skip rate limiting for admin users
+ *       return context.user?.role === 'admin';
+ *     },
+ *     keyGenerator: (context) => {
+ *       // Rate limit per user instead of IP
+ *       return context.user?.id || context.req.ip || 'anonymous';
+ *     }
+ *   }))
+ *   .handle(async (context) => {
+ *     return { success: true, message: 'Request processed' };
+ *   });
+ * ```
  */
 const rateLimiting = (options = {}) => new RateLimitingMiddleware(options);
 exports.rateLimiting = rateLimiting;

package/build/middlewares/responseWrapperMiddleware.d.ts

@@ -1,11 +1,180 @@
 import { BaseMiddleware } from '../core/handler';
 import { Context } from '../core/core';
+/**
+ * Middleware class that wraps response data in a standardized format.
+ * Automatically wraps the response with success flag, payload, and timestamp.
+ *
+ * @template T - The type of response data being wrapped
+ * @implements {BaseMiddleware}
+ *
+ * @example
+ * Basic response wrapping:
+ * ```typescript
+ * import { Handler, ResponseWrapperMiddleware, setResponseData } from '@noony-serverless/core';
+ *
+ * interface UserResponse {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const getUserHandler = new Handler()
+ *   .use(new ResponseWrapperMiddleware<UserResponse>())
+ *   .handle(async (context) => {
+ *     const user = await getUser(context.params.id);
+ *     setResponseData(context, user);
+ *     // Response will be: { success: true, payload: user, timestamp: "..." }
+ *   });
+ * ```
+ *
+ * @example
+ * API response with metadata:
+ * ```typescript
+ * interface ApiResponse {
+ *   items: any[];
+ *   pagination: { page: number; total: number };
+ * }
+ *
+ * const listItemsHandler = new Handler()
+ *   .use(new ResponseWrapperMiddleware<ApiResponse>())
+ *   .handle(async (context) => {
+ *     const items = await getItems();
+ *     const response: ApiResponse = {
+ *       items,
+ *       pagination: { page: 1, total: items.length }
+ *     };
+ *     setResponseData(context, response);
+ *   });
+ * ```
+ *
+ * @example
+ * Combination with error handling:
+ * ```typescript
+ * const secureHandler = new Handler()
+ *   .use(new AuthenticationMiddleware())
+ *   .use(new ResponseWrapperMiddleware<any>())
+ *   .use(new ErrorHandlerMiddleware())
+ *   .handle(async (context) => {
+ *     const data = await getSecureData(context.user.id);
+ *     setResponseData(context, data);
+ *   });
+ * ```
+ */
 export declare class ResponseWrapperMiddleware<T> implements BaseMiddleware {
     after(context: Context): Promise<void>;
 }
+/**
+ * Factory function that creates a response wrapper middleware.
+ * Automatically wraps response data in a standardized format with success flag and timestamp.
+ *
+ * @template T - The type of response data being wrapped
+ * @returns BaseMiddleware object with response wrapping logic
+ *
+ * @example
+ * Simple API endpoint:
+ * ```typescript
+ * import { Handler, responseWrapperMiddleware, setResponseData } from '@noony-serverless/core';
+ *
+ * const healthCheckHandler = new Handler()
+ *   .use(responseWrapperMiddleware<{ status: string; uptime: number }>())
+ *   .handle(async (context) => {
+ *     setResponseData(context, {
+ *       status: 'healthy',
+ *       uptime: process.uptime()
+ *     });
+ *     // Response: { success: true, payload: { status: "healthy", uptime: 12345 }, timestamp: "..." }
+ *   });
+ * ```
+ *
+ * @example
+ * RESTful CRUD operations:
+ * ```typescript
+ * const createUserHandler = new Handler()
+ *   .use(bodyParser())
+ *   .use(responseWrapperMiddleware<{ id: string; message: string }>())
+ *   .handle(async (context) => {
+ *     const userData = context.req.parsedBody;
+ *     const newUser = await createUser(userData);
+ *     setResponseData(context, {
+ *       id: newUser.id,
+ *       message: 'User created successfully'
+ *     });
+ *   });
+ * ```
+ *
+ * @example
+ * Microservice communication:
+ * ```typescript
+ * const orderProcessingHandler = new Handler()
+ *   .use(authenticationMiddleware)
+ *   .use(responseWrapperMiddleware<{ orderId: string; status: string; estimatedDelivery: string }>())
+ *   .handle(async (context) => {
+ *     const order = await processOrder(context.req.parsedBody);
+ *     setResponseData(context, {
+ *       orderId: order.id,
+ *       status: order.status,
+ *       estimatedDelivery: order.estimatedDelivery
+ *     });
+ *   });
+ * ```
+ */
 export declare const responseWrapperMiddleware: <T>() => BaseMiddleware;
 /**
- * Helper function to set response data in context for later wrapping
+ * Helper function to set response data in context for later wrapping.
+ * This function should be used in handlers when using ResponseWrapperMiddleware.
+ *
+ * @template T - The type of data being set
+ * @param context - The request context
+ * @param data - The data to be included in the response payload
+ *
+ * @example
+ * Setting simple response data:
+ * ```typescript
+ * import { setResponseData } from '@noony-serverless/core';
+ *
+ * const handler = new Handler()
+ *   .use(responseWrapperMiddleware())
+ *   .handle(async (context) => {
+ *     const message = "Hello, World!";
+ *     setResponseData(context, { message, timestamp: new Date().toISOString() });
+ *   });
+ * ```
+ *
+ * @example
+ * Setting complex response data:
+ * ```typescript
+ * const dashboardHandler = new Handler()
+ *   .use(responseWrapperMiddleware())
+ *   .handle(async (context) => {
+ *     const stats = await getDashboardStats(context.user.id);
+ *     const notifications = await getNotifications(context.user.id);
+ *
+ *     setResponseData(context, {
+ *       user: context.user,
+ *       stats,
+ *       notifications,
+ *       lastLogin: new Date().toISOString()
+ *     });
+ *   });
+ * ```
+ *
+ * @example
+ * Conditional response data:
+ * ```typescript
+ * const userProfileHandler = new Handler()
+ *   .use(responseWrapperMiddleware())
+ *   .handle(async (context) => {
+ *     const userId = context.params.id;
+ *     const user = await getUser(userId);
+ *
+ *     if (user) {
+ *       setResponseData(context, { user, found: true });
+ *     } else {
+ *       context.res.status(404);
+ *       setResponseData(context, { message: 'User not found', found: false });
+ *     }
+ *   });
+ * ```
  */
 export declare function setResponseData<T>(context: Context, data: T): void;
 //# sourceMappingURL=responseWrapperMiddleware.d.ts.map