yinzerflow 0.4.4 → 0.5.0

package/index.d.ts

@@ -1,12 +1,5 @@
-export type CreateEnum<T> = T[keyof T];
-/**
- * Utility type for deep partial - makes all properties optional recursively
- * Used internally to create public configuration types from internal shapes
- */
-export type DeepPartial<T> = {
-	[P in keyof T]?: T[P] extends object ? T[P] extends Array<infer U> ? Array<U> // Keep arrays as-is, don't make array items partial
-	 : DeepPartial<T[P]> : T[P];
-};
+import { createClient } from 'redis';
+
 /**
  * Generic types for handler callbacks that define the structure of request data
  *
@@ -24,7 +17,7 @@ export type DeepPartial<T> = {
  * };
  *
  * // Custom types for specific endpoints
- * interface UserCreateContext extends InternalHandlerCallbackGenerics {
+ * interface UserCreateContext extends HandlerCallbackGenerics {
  *   body: { name: string; email: string; age: number };
  *   response: { id: string; name: string; email: string };
  *   state: { requestId: string; userAgent: string };
@@ -41,7 +34,7 @@ export type DeepPartial<T> = {
  * };
  * ```
  */
-export interface InternalHandlerCallbackGenerics {
+export interface HandlerCallbackGenerics {
 	/**
 	 * The expected type of the request body
 	 *
@@ -50,7 +43,7 @@ export interface InternalHandlerCallbackGenerics {
 	 *
 	 * @example
 	 * ```typescript
-	 * interface LoginContext extends InternalHandlerCallbackGenerics {
+	 * interface LoginContext extends HandlerCallbackGenerics {
 	 *   body: { username: string; password: string };
 	 * }
 	 *
@@ -69,7 +62,7 @@ export interface InternalHandlerCallbackGenerics {
 	 *
 	 * @example
 	 * ```typescript
-	 * interface UserListContext extends InternalHandlerCallbackGenerics {
+	 * interface UserListContext extends HandlerCallbackGenerics {
 	 *   response: { users: Array<{ id: string; name: string }>; total: number };
 	 * }
 	 *
@@ -93,7 +86,7 @@ export interface InternalHandlerCallbackGenerics {
 	 *
 	 * @example
 	 * ```typescript
-	 * interface SearchContext extends InternalHandlerCallbackGenerics {
+	 * interface SearchContext extends HandlerCallbackGenerics {
 	 *   query: { q: string; limit?: string; page?: string };
 	 * }
 	 *
@@ -106,7 +99,7 @@ export interface InternalHandlerCallbackGenerics {
 	 * };
 	 * ```
 	 */
-	query?: Record<string, string>;
+	query?: Record<string, unknown>;
 	/**
 	 * The expected type of route parameters
 	 *
@@ -115,7 +108,7 @@ export interface InternalHandlerCallbackGenerics {
 	 *
 	 * @example
 	 * ```typescript
-	 * interface UserDetailContext extends InternalHandlerCallbackGenerics {
+	 * interface UserDetailContext extends HandlerCallbackGenerics {
 	 *   params: { id: string; tab?: string };
 	 * }
 	 *
@@ -138,7 +131,7 @@ export interface InternalHandlerCallbackGenerics {
 	 *
 	 * @example
 	 * ```typescript
-	 * interface AuthContext extends InternalHandlerCallbackGenerics {
+	 * interface AuthContext extends HandlerCallbackGenerics {
 	 *   state: {
 	 *     user: User;
 	 *     permissions: string[];
@@ -160,6 +153,15 @@ export interface InternalHandlerCallbackGenerics {
 	 */
 	state?: Record<string, unknown>;
 }
+export type CreateEnum<T> = T[keyof T];
+/**
+ * Utility type for deep partial - makes all properties optional recursively
+ * Used internally to create public configuration types from internal shapes
+ */
+export type DeepPartial<T> = {
+	[P in keyof T]?: T[P] extends object ? T[P] extends Array<infer U> ? Array<U> // Keep arrays as-is, don't make array items partial
+	 : DeepPartial<T[P]> : T[P];
+};
 export declare const httpStatus: {
 	readonly ok: "OK";
 	readonly created: "Created";
@@ -464,7 +466,7 @@ export type InternalHttpMethod = CreateEnum<typeof httpMethod>;
  * @see {@link Response} for setting headers in responses
  */
 export type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
-interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
+interface Request$1<T extends HandlerCallbackGenerics = HandlerCallbackGenerics> {
 	/**
 	 * The HTTP protocol version (e.g., "HTTP/1.1").
 	 *
@@ -591,7 +593,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 *
 	 * // Typed body with generics
-	 * interface CreateUserRequest extends InternalHandlerCallbackGenerics {
+	 * interface CreateUserRequest extends HandlerCallbackGenerics {
 	 *   body: { name: string; email: string; age: number };
 	 * }
 	 *
@@ -608,7 +610,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 * ```
 	 *
-	 * @see {@link InternalHandlerCallbackGenerics} for custom body typing
+	 * @see {@link HandlerCallbackGenerics} for custom body typing
 	 */
 	body: T["body"];
 	/**
@@ -637,7 +639,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 *
 	 * // Typed query parameters with generics
-	 * interface UserListRequest extends InternalHandlerCallbackGenerics {
+	 * interface UserListRequest extends HandlerCallbackGenerics {
 	 *   query: { page: string; limit: string; search?: string; sort?: string };
 	 * }
 	 *
@@ -658,7 +660,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 * ```
 	 *
-	 * @see {@link InternalHandlerCallbackGenerics} for custom query typing
+	 * @see {@link HandlerCallbackGenerics} for custom query typing
 	 */
 	query: T["query"];
 	/**
@@ -688,7 +690,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 *
 	 * // Typed route parameters with generics
-	 * interface UserDetailRequest extends InternalHandlerCallbackGenerics {
+	 * interface UserDetailRequest extends HandlerCallbackGenerics {
 	 *   params: { id: string; tab?: string };
 	 * }
 	 *
@@ -712,7 +714,7 @@ interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerC
 	 * };
 	 * ```
 	 *
-	 * @see {@link InternalHandlerCallbackGenerics} for custom params typing
+	 * @see {@link HandlerCallbackGenerics} for custom params typing
 	 */
 	params: T["params"];
 	/**
@@ -945,7 +947,7 @@ interface Response$1 {
  * It contains the request and response objects, plus any custom state data
  * defined by the user through generics.
  *
- * @template T - Extends InternalHandlerCallbackGenerics to provide custom typing
+ * @template T - Extends HandlerCallbackGenerics to provide custom typing
  *
  * @example
  * ```typescript
@@ -968,7 +970,7 @@ interface Response$1 {
  * };
  *
  * // Advanced usage with custom state typing
- * interface AuthContext extends InternalHandlerCallbackGenerics {
+ * interface AuthContext extends HandlerCallbackGenerics {
  *   state: {
  *     user: User;
  *     permissions: string[];
@@ -991,7 +993,7 @@ interface Response$1 {
  * };
  * ```
  */
-export interface Context<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
+export interface Context<T extends HandlerCallbackGenerics = HandlerCallbackGenerics> {
 	/**
 	 * The incoming request object containing all request data and metadata
 	 *
@@ -1086,7 +1088,7 @@ export interface Context<T extends InternalHandlerCallbackGenerics = InternalHan
  * - **Void**: No response body (useful for middleware)
  * - **Error**: Thrown errors are caught by error handlers
  *
- * @template T - Extends InternalHandlerCallbackGenerics for custom typing
+ * @template T - Extends HandlerCallbackGenerics for custom typing
  * @param ctx - The request context containing request, response, and state objects
  * @param error - Optional error object (only provided to error handlers)
  * @returns Response data, promise, or void
@@ -1102,7 +1104,7 @@ export interface Context<T extends InternalHandlerCallbackGenerics = InternalHan
  * };
  *
  * // Typed route handler with custom state
- * interface UserContext extends InternalHandlerCallbackGenerics {
+ * interface UserContext extends HandlerCallbackGenerics {
  *   body: { name: string; email: string };
  *   response: { id: string; name: string; email: string };
  *   state: { user: User; permissions: string[] };
@@ -1145,9 +1147,9 @@ export interface Context<T extends InternalHandlerCallbackGenerics = InternalHan
  * ```
  *
  * @see {@link Context} for context interface details
- * @see {@link InternalHandlerCallbackGenerics} for custom typing options
+ * @see {@link HandlerCallbackGenerics} for custom typing options
  */
-export type HandlerCallback<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> = (ctx: Context<T>, error?: unknown) => Promise<T["response"] | void> | T["response"] | void;
+export type HandlerCallback<T extends HandlerCallbackGenerics = HandlerCallbackGenerics> = (ctx: Context<T>, error?: unknown) => Promise<T["response"] | void> | T["response"] | void;
 export type InternalGlobalHookOptions = {
 	routesToExclude: Array<string>;
 } & {
@@ -1603,6 +1605,231 @@ export interface LoggerConfig {
 		error: (...args: Array<unknown>) => void;
 	} | undefined;
 }
+/**
+ Time duration string format
+ 
+ Format: number followed by unit (s, m, h, d)
+ 
+ Units:
+ - s: seconds
+ - m: minutes
+ - h: hours
+ - d: days
+ 
+ @example
+ ```typescript
+ '30s'  // 30 seconds
+ '15m'  // 15 minutes
+ '2h'   // 2 hours
+ '1d'   // 1 day
+ ```
+ */
+export type TimeString = `${number}${"d" | "h" | "m" | "s"}`;
+export declare const rateLimitAlgorithm: {
+	readonly slidingWindowCounter: "sliding-window-counter";
+};
+export declare const rateLimitStoreType: {
+	readonly memory: "memory";
+	readonly redis: "redis";
+};
+/**
+ * Internal type for rate limit algorithm enum
+ * Generated from rateLimitAlgorithm constant
+ */
+export type RateLimitAlgorithm = CreateEnum<typeof rateLimitAlgorithm>;
+/**
+ * Internal type for rate limit store type enum
+ * Generated from rateLimitStoreType constant
+ */
+export type RateLimitStoreType = CreateEnum<typeof rateLimitStoreType>;
+export interface BaseStoreConfig {
+	/** Type of the store @default 'memory' */
+	type: RateLimitStoreType;
+}
+export interface MemoryStoreConfig extends BaseStoreConfig {
+	type: "memory";
+}
+/**
+ * Redis store configuration
+ */
+export interface RedisStoreConfig extends BaseStoreConfig {
+	type: "redis";
+	/** Redis client instance of ioredis or redis */
+	client: ReturnType<typeof createClient>;
+	/** Key prefix for the rate limit keys @default 'rate_limit:' */
+	keyPrefix?: string;
+	/** Maximum number of connection retry attempts @default 3 */
+	maxRetries?: number;
+	/** Delay between retry attempts in milliseconds @default 1000 */
+	retryDelay?: number;
+}
+/**
+ * Configuration for rate limit store
+ * This is a union type to future proof the code for other store types
+ */
+export type StoreConfig = MemoryStoreConfig | RedisStoreConfig;
+/**
+ * Options for per-route rate limiting
+ *
+ * Allows overriding global rate limit settings for specific routes.
+ * Use with the `rateLimit()` hook function in route options.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimit } from 'yinzerflow';
+ * import type { RateLimitOptions } from 'yinzerflow';
+ *
+ * // Using friendly time format
+ * const options: RateLimitOptions = {
+ *   max: 5,
+ *   windowMs: '1m' // 1 minute
+ * };
+ *
+ * // Or using milliseconds directly
+ * const optionsMs: RateLimitOptions = {
+ *   max: 5,
+ *   windowMs: 60000 // 1 minute
+ * };
+ *
+ * app.post('/api/auth/login',
+ *   { beforeRoute: [rateLimit(options)] },
+ *   async (ctx) => {
+ *     // Login logic
+ *   }
+ * );
+ * ```
+ */
+export interface RateLimitOptions {
+	/**
+	 * Enable or disable rate limiting
+	 * @default true
+	 * @example
+	 * ```typescript
+	 * enabled: true
+	 * ```
+	 */
+	enabled?: boolean;
+	/**
+	 * Rate limiting algorithm to use
+	 * @default 'sliding-window-counter'
+	 *
+	 * Available algorithms:
+	 * - 'sliding-window-counter': Memory efficient, Redis-ready, 99%+ accurate (recommended)
+	 * - 'token-bucket': (Future) Allows smooth traffic patterns with continuous refill
+	 *
+	 * @example
+	 * ```typescript
+	 * import { rateLimitAlgorithm } from 'yinzerflow';
+	 *
+	 * algorithm: rateLimitAlgorithm.slidingWindowCounter
+	 * ```
+	 */
+	algorithm?: RateLimitAlgorithm;
+	/**
+	 * Rate limiting store configuration
+	 *
+	 * Configure the storage backend for rate limiting data.
+	 * If not provided, defaults to in-memory storage.
+	 *
+	 * @example
+	 * ```typescript
+	 * // In-memory store (default)
+	 * const config = { algorithm: 'sliding-window-counter', window: '15m', max: 100 };
+	 *
+	 * // Redis store
+	 * const config = {
+	 *   algorithm: 'sliding-window-counter',
+	 *   window: '15m',
+	 *   max: 100,
+	 *   store: {
+	 *     type: 'redis',
+	 *     client: redisClient,
+	 *     keyPrefix: 'myapp:rate_limit:'
+	 *   }
+	 * };
+	 * ```
+	 */
+	store?: StoreConfig;
+	/**
+	 * Time window for rate limiting
+	 *
+	 * Accepts either:
+	 * - Friendly format: '30s', '15m', '2h', '1d'
+	 * - Milliseconds: 900000
+	 *
+	 * @default '15m' (15 minutes / 900000ms)
+	 *
+	 * @example
+	 * ```typescript
+	 * window: '30s'   // 30 seconds
+	 * window: '15m'   // 15 minutes
+	 * window: '2h'    // 2 hours
+	 * window: '1d'    // 1 day
+	 * ```
+	 */
+	window?: TimeString | number;
+	/**
+	 * Maximum requests per window
+	 * @default 100
+	 */
+	max?: number;
+	/**
+	 * Include standard rate limit headers in responses
+	 * @default true
+	 */
+	standardHeaders?: boolean;
+	/**
+	 * Skip counting successful requests (status < 400)
+	 * @default false
+	 */
+	skipSuccessfulRequests?: boolean;
+	/**
+	 * Skip counting failed requests (status >= 400)
+	 * @default false
+	 */
+	skipFailedRequests?: boolean;
+	/**
+	 * Store configuration
+	 * @default { type: 'memory' }
+	 */
+	store?: StoreConfig;
+	/**
+	 * Custom key generator function for identifying clients
+	 * @default (ctx) => ctx.request.ipAddress
+	 *
+	 * @example
+	 * ```typescript
+	 * // Rate limit by user ID instead of IP
+	 * keyGenerator: (ctx) => ctx.state.userId || ctx.request.ipAddress
+	 * ```
+	 */
+	keyGenerator?: (context: Context<any>) => string;
+	/**
+	 * Custom handler function called when rate limit is exceeded
+	 *
+	 * @param context - Request context
+	 * @param retryAfter - Seconds until the client can retry
+	 * @returns Response to send to client
+	 *
+	 * @example
+	 * ```typescript
+	 * handler: (ctx, retryAfter) => {
+	 *   ctx.response.setStatusCode(429);
+	 *   return {
+	 *     error: 'Too many requests',
+	 *     retryAfter,
+	 *     message: 'Please slow down'
+	 *   };
+	 * }
+	 * ```
+	 */
+	handler?: HandlerCallback<{
+		response: {
+			success: false;
+			message: string;
+		};
+	}>;
+}
 /**
  * Internal CORS Configuration Options
  * Provides fine-grained control over Cross-Origin Resource Sharing
@@ -1682,45 +1909,6 @@ export interface InternalCorsEnabledConfiguration {
 	 */
 	optionsSuccessStatus: InternalHttpStatusCode;
 }
-/**
- * Internal Connection Options
- */
-export interface InternalConnectionOptions {
-	/**
-	 * Default socket timeout in milliseconds (30 seconds)
-	 *
-	 * Standard timeout for most socket connections.
-	 * It is long enough for slow clients but short enough to prevent idle connections from staying open indefinitely.
-	 */
-	socketTimeout: number;
-	/**
-	 * Default graceful shutdown timeout in milliseconds (30 seconds)
-	 *
-	 * This is the maximum time to wait for a connection to complete before the server will close it.
-	 */
-	gracefulShutdownTimeout: number;
-	/**
-	 * Default keep-alive timeout in milliseconds (65 seconds)
-	 *
-	 * This is the maximum time a connection can be idle before the server will close it.
-	 * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
-	 * This is also to prevent a connection from staying open indefinitely.
-	 * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
-	 * AWS recommends a keep-alive timeout of 65 seconds because there idle timeout is 60 seconds.
-	 */
-	keepAliveTimeout: number;
-	/**
-	 * Default headers timeout in milliseconds (66 seconds)
-	 *
-	 * This is the maximum time to wait for a header from the client.
-	 * This is to allow for a connection to stay open for a period of time so subsequent requests can be handled without a new connection.
-	 * This is also to prevent a connection from staying open indefinitely.
-	 * This is also useful for load balancing and preventing a single server from being overwhelmed by a large number of connections.
-	 * It is recommended to set this value to be greater than the keep-alive timeout to prevent the server from closing the connection prematurely
-	 * before the keep-alive timeout has expired.
-	 */
-	headersTimeout: number;
-}
 /**
  * Internal Body Parser Security Configuration
  * Protects against DoS attacks, prototype pollution, and memory exhaustion
@@ -1946,15 +2134,22 @@ export interface InternalServerConfiguration {
 	 */
 	ipSecurity: InternalIpValidationConfig;
 	/**
-	 * Server connection options
+	 * Rate limiting configuration
+	 * Protects against DoS attacks and API abuse by limiting requests per IP
+	 * @default enabled with 100 requests per 15 minutes
 	 */
-	connectionOptions: InternalConnectionOptions;
+	rateLimit?: RateLimitOptions;
 	/**
-	 * Automatic graceful shutdown configuration
-	 * When enabled, YinzerFlow automatically sets up signal handlers for SIGTERM and SIGINT
+	 * Graceful shutdown timeout configuration
+	 * When set to a value greater than 0, YinzerFlow automatically sets up signal handlers for SIGTERM and SIGINT
+	 * and waits for all requests to complete before shutting down.
+	 * If the value is 0 (disabled), you must manually handle graceful shutdown by calling `app.close()` and `process.exit(0)`.
+	 * Note: If using container orchestrations, your container configuration should be at least 1 second more
+	 * than the graceful shutdown timeout to ensure all requests are completed, otherwise the container will be
+	 * killed before all requests are completed.
 	 * @default true
 	 */
-	autoGracefulShutdown: boolean;
+	gracefulShutdownTimeout: TimeString | number;
 }
 export type HttpMethodHandlers = Record<Lowercase<keyof typeof httpMethod>, InternalSetupMethod>;
 export type RouteGroupMethod = (prefix: string, callback: (group: RouteGroup) => void, options?: InternalRouteRegistryOptions) => RouteGroup;
@@ -2292,7 +2487,7 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
  *
  * // Full configuration example
  * const app = new YinzerFlow({
- *   port: 9000,
+ *   port: 3000,
  *   host: '0.0.0.0',
  *   logLevel: 'debug',
  *   networkLogs: true,
@@ -2349,6 +2544,7 @@ declare class SetupImpl implements InternalSetupImpl {
 export declare class YinzerFlow extends SetupImpl {
 	private _isListening;
 	private _server?;
+	private _globalRateLimiter?;
 	constructor(configuration?: ServerConfiguration);
 	private _setupServer;
 	private _processRequest;
@@ -2382,6 +2578,12 @@ export declare const log: {
 	table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
 	levels: typeof LOG_LEVELS;
 };
+export declare const rateLimitHook: (rateLimitOptions: RateLimitOptions) => HandlerCallback<{
+	response: {
+		success: false;
+		message: string;
+	};
+}>;
 export declare const colors: {
 	readonly reset: "\u001B[0m";
 	readonly cyan: "\u001B[96m";