tezx 1.0.31 → 1.0.33

package/cjs/index.js

@@ -7,4 +7,4 @@ var server_1 = require("./core/server");
 Object.defineProperty(exports, "TezX", { enumerable: true, get: function () { return server_1.TezX; } });
 var params_1 = require("./utils/params");
 Object.defineProperty(exports, "useParams", { enumerable: true, get: function () { return params_1.useParams; } });
-exports.version = "1.0.31";
+exports.version = "1.0.33";

package/cjs/middleware/i18nMiddleware.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.i18nMiddleware = void 0;
+const config_1 = require("../core/config");
+const i18nMiddleware = (options) => {
+    const { loadTranslations, defaultCacheDuration = 3600000, isCacheValid = (cached) => cached.expiresAt > Date.now(), detectLanguage = (ctx) => ctx.req.query.lang ||
+        ctx.cookies?.get('lang') ||
+        ctx.headers.get('accept-language')?.split(',')[0] ||
+        options.defaultLanguage ||
+        'en', defaultLanguage = 'en', fallbackChain = [], translationFunctionKey = 't', formatMessage = (message, options = {}) => {
+        return Object.entries(options).reduce((msg, [key, value]) => msg.replace(new RegExp(`{{${key}}}`, 'g'), String(value)), message);
+    }, cacheTranslations = true } = options;
+    const translationCache = {};
+    return async (ctx, next) => {
+        try {
+            const detectedLanguage = detectLanguage(ctx);
+            const languageChain = [
+                detectedLanguage,
+                ...fallbackChain,
+                defaultLanguage
+            ].filter(Boolean);
+            let translations = null;
+            let selectedLanguage = defaultLanguage;
+            for (const lang of languageChain) {
+                const normalizedLang = lang.split('-')[0].toLowerCase();
+                if (cacheTranslations && translationCache[normalizedLang]) {
+                    const cached = translationCache[normalizedLang];
+                    if (isCacheValid(cached, normalizedLang)) {
+                        translations = cached.translations;
+                        selectedLanguage = lang;
+                        break;
+                    }
+                    delete translationCache[normalizedLang];
+                }
+                try {
+                    const { translations: loadedTranslations, expiresAt } = await loadTranslations(normalizedLang);
+                    let expirationTime = Date.now() + defaultCacheDuration;
+                    if (expiresAt instanceof Date) {
+                        expirationTime = expiresAt.getTime();
+                    }
+                    else if (typeof expiresAt === 'number') {
+                        expirationTime = expiresAt;
+                    }
+                    translations = loadedTranslations;
+                    selectedLanguage = lang;
+                    if (cacheTranslations) {
+                        translationCache[normalizedLang] = {
+                            translations,
+                            expiresAt: expirationTime,
+                        };
+                    }
+                    break;
+                }
+                catch (error) {
+                    config_1.GlobalConfig.debugging.warn(`Translation load failed for ${lang}:`, error);
+                }
+            }
+            if (!translations) {
+                throw new Error('No translations available');
+            }
+            ctx[translationFunctionKey] = (key, options) => {
+                const value = key.split('.').reduce((acc, k) => {
+                    return (acc && typeof acc === 'object') ? acc[k] : undefined;
+                }, translations);
+                const message = typeof value === 'string' ? value : key;
+                return formatMessage(message, options);
+            };
+            ctx.language = selectedLanguage;
+            ctx.languageChain = languageChain;
+            return await next();
+        }
+        catch (error) {
+            config_1.GlobalConfig.debugging.error('i18n processing error:', error);
+            ctx.setStatus = 500;
+            throw error;
+        }
+    };
+};
+exports.i18nMiddleware = i18nMiddleware;

package/cjs/middleware/index.js

@@ -24,3 +24,6 @@ __exportStar(require("./secureHeaders"), exports);
 __exportStar(require("./xssProtection"), exports);
 __exportStar(require("./sanitizeHeader"), exports);
 __exportStar(require("./rateLimiter"), exports);
+__exportStar(require("./pagination"), exports);
+__exportStar(require("./i18nMiddleware"), exports);
+__exportStar(require("./lazyLoadModules"), exports);

package/cjs/middleware/lazyLoadModules.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lazyLoadModules = void 0;
+const config_1 = require("../core/config");
+;
+const lazyLoadModules = (options) => {
+    const { moduleKey = (ctx) => ctx.req.params[queryKeyModule] || ctx.req.query[queryKeyModule], getModuleLoader, queryKeyModule = "module", moduleContextKey = "module", cacheTTL = 3600000, dependencies = {}, enableCache = true, cacheStorage = new Map(), lifecycleHooks = {}, validateModule } = options;
+    return async (ctx, next) => {
+        let moduleName = moduleKey(ctx) || ctx.req.params[queryKeyModule] || ctx.req.query[queryKeyModule];
+        if (!moduleName) {
+            config_1.GlobalConfig.debugging.warn("No module specified for lazy loading.");
+            return await next();
+        }
+        try {
+            if (enableCache) {
+                const cached = cacheStorage.get(moduleName);
+                if (cached) {
+                    if (cached.expiresAt > Date.now()) {
+                        cacheStorage.delete(moduleName);
+                    }
+                    else {
+                        config_1.GlobalConfig.debugging.info(`Using cached module: ${moduleName}`);
+                        ctx[moduleContextKey] = cached?.module;
+                        lifecycleHooks.onCacheHit?.(moduleName, ctx[moduleContextKey], ctx);
+                        lifecycleHooks.onComplete?.(moduleName, ctx[moduleContextKey], ctx);
+                        return await next();
+                    }
+                }
+            }
+            if (!getModuleLoader) {
+                throw new Error(`No module loader found for module: ${moduleName}`);
+            }
+            const moduleLoader = getModuleLoader(ctx);
+            if (!moduleLoader) {
+                throw new Error(`No loader found for module: ${moduleName}`);
+            }
+            lifecycleHooks.onLoad?.(moduleName, ctx);
+            const module = await moduleLoader();
+            if (validateModule && !validateModule(module)) {
+                throw new Error(`Module validation failed for: ${moduleName}`);
+            }
+            ctx.dependencies = dependencies;
+            if (module.init && typeof module.init === "function") {
+                module.init(dependencies, ctx);
+            }
+            if (enableCache) {
+                cacheStorage.set(moduleName, {
+                    module,
+                    expiresAt: Date.now() + cacheTTL
+                });
+                lifecycleHooks.onCacheSet?.(moduleName, module, ctx);
+            }
+            ctx[moduleContextKey] = module;
+            lifecycleHooks.onComplete?.(moduleName, module, ctx);
+            config_1.GlobalConfig.debugging.success(`Successfully loaded module: ${moduleName}`);
+        }
+        catch (error) {
+            config_1.GlobalConfig.debugging.error(`Error loading module: ${moduleName}`, error);
+            lifecycleHooks.onError?.(moduleName, error, ctx);
+            ctx.setStatus = 500;
+            throw error;
+        }
+        return await next();
+    };
+};
+exports.lazyLoadModules = lazyLoadModules;

package/cjs/middleware/pagination.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginationHandler = void 0;
+const paginationHandler = (options = {}) => {
+    const { defaultPage = 1, defaultLimit = 10, maxLimit = 100, queryKeyPage = "page", queryKeyLimit = "limit", countKey = "total", dataKey = "data", getDataSource, } = options;
+    return async (ctx, next) => {
+        const rawPage = ctx.req.query[queryKeyPage];
+        const rawLimit = ctx.req.query[queryKeyLimit];
+        const page = Math.max(parseInt(rawPage || `${defaultPage}`, 10), 1);
+        const limit = Math.min(Math.max(parseInt(rawLimit || `${defaultLimit}`, 10), 1), maxLimit);
+        const offset = (page - 1) * limit;
+        ctx.pagination = {
+            page,
+            limit,
+            offset: offset,
+            queryKeyPage,
+            queryKeyLimit
+        };
+        if (getDataSource) {
+            try {
+                const dataSourceResponse = await getDataSource(ctx, { page, limit, offset });
+                const total = dataSourceResponse?.[countKey];
+                const data = dataSourceResponse?.[dataKey];
+                if (typeof total !== "number" || !Array.isArray(data)) {
+                    throw new Error("Invalid data structure returned by getDataSource.");
+                }
+                ctx.body = {
+                    [dataKey]: data,
+                    [countKey]: total,
+                    pagination: {
+                        page,
+                        limit,
+                        totalItems: total,
+                        totalPages: Math.ceil(total / limit),
+                        hasNextPage: page < Math.ceil(total / limit),
+                        hasPrevPage: page > 1,
+                        nextPage: page < Math.ceil(total / limit) ? page + 1 : null,
+                        prevPage: page > 1 ? page - 1 : null,
+                    },
+                };
+            }
+            catch (error) {
+                ctx.setStatus = 500;
+                ctx.body = { error: "Internal Server Error", };
+                throw new Error("Error fetching or processing data:", error?.message);
+            }
+        }
+        return await next();
+    };
+};
+exports.paginationHandler = paginationHandler;

package/cjs/middleware/request-id.js

@@ -2,12 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestID = void 0;
 const helper_1 = require("../helper");
-const requestID = (headerName = "X-Request-ID") => {
+const requestID = (headerName = "X-Request-ID", contextKey = "requestID") => {
     return (ctx, next) => {
         const existingID = ctx.headers?.get(headerName.toLowerCase()) ||
             ctx.headers?.get(headerName);
         const requestId = existingID || `req-${(0, helper_1.generateID)()}`;
-        ctx.state.set("requestID", requestId);
+        ctx.set(contextKey, requestId);
         ctx.header(headerName, requestId);
         return next();
     };

package/index.js

@@ -1,4 +1,4 @@
 export { Router } from "./core/router";
 export { TezX } from "./core/server";
 export { useParams } from "./utils/params";
-export let version = "1.0.31";
+export let version = "1.0.33";

package/middleware/i18nMiddleware.d.ts

@@ -0,0 +1,101 @@
+import { Context, Middleware } from "..";
+export type TranslationMap = {
+    [key: string]: string | TranslationMap;
+};
+export type loadTranslations = (language: string) => Promise<{
+    translations: TranslationMap;
+    expiresAt?: Date | number;
+}>;
+export type I18nOptions = {
+    /**
+      * 🌐 Function to load translations dynamically
+      * @param language - Language code to load (e.g., "en-US")
+      * @returns Promise with translations map and optional expiration
+      */
+    loadTranslations: (language: string) => Promise<{
+        translations: TranslationMap;
+        expiresAt?: Date | number;
+    }>;
+    /**
+     * ⏱️ Default cache duration in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    defaultCacheDuration?: number;
+    /**
+     * 🔄 Function to check if cached translations are stale
+     * @default Checks expiration time
+     * @example
+     * isCacheValid: (cached, lang) => {
+     *   return cached.expiresAt > Date.now() &&
+     *          cached.version === getCurrentVersion(lang);
+     * }
+     */
+    isCacheValid?: (cached: {
+        translations: TranslationMap;
+        expiresAt: number;
+    }, language: string) => boolean;
+    /**
+     * 🔍 Custom language detection function
+     * @default Checks query param → cookie → Accept-Language header → default
+     * @example
+     * detectLanguage: (ctx) => ctx.cookies.get('user_lang') || 'en'
+     */
+    detectLanguage?: (ctx: Context) => string;
+    /**
+     * 🏠 Default fallback language
+     * @default "en"
+     */
+    defaultLanguage?: string;
+    /**
+     * 🔀 Language fallback chain (most specific to least)
+     * @example ["fr-CA", "fr", "en"] // Try Canadian French → French → English
+     */
+    fallbackChain?: string[];
+    /**
+     * 🗝️ Context property name for translation function
+     * @default "t"
+     */
+    translationFunctionKey?: string;
+    /**
+     * 💬 Message formatting function
+     * @default Basic template replacement ({{key}})
+     * @example
+     * formatMessage: (msg, vars) => {
+     *   return msg.replace(/\{(\w+)\}/g, (_, k) => vars[k]);
+     * }
+     */
+    formatMessage?: (message: string, options?: Record<string, any>) => string;
+    /**
+     * 🗃️ Cache loaded translations
+     * @default true
+     */
+    cacheTranslations?: boolean;
+};
+/**
+ * 🌍 Advanced i18n middleware with dynamic loading and fallback support
+ *
+ * Features:
+ * - Hierarchical language resolution
+ * - Nested translation keys
+ * - Template interpolation
+ * - Optional caching
+ * - Custom language detection
+ *
+ * @param {I18nOptions} options - Configuration options
+ * @returns {Middleware} Configured middleware
+ *
+ * @example
+ * // Basic usage
+ * app.use(i18nMiddleware({
+ *   loadTranslations: lang => import(`./locales/${lang}.json`),
+ *   defaultLanguage: 'en'
+ * }));
+ *
+ * // With caching and custom detection
+ * app.use(i18nMiddleware({
+ *   loadTranslations: fetchTranslations,
+ *   detectLanguage: ctx => ctx.get('X-Language'),
+ *   cacheTranslations: true
+ * }));
+ */
+export declare const i18nMiddleware: (options: I18nOptions) => Middleware;

package/middleware/i18nMiddleware.js

@@ -0,0 +1,75 @@
+import { GlobalConfig } from "../core/config";
+export const i18nMiddleware = (options) => {
+    const { loadTranslations, defaultCacheDuration = 3600000, isCacheValid = (cached) => cached.expiresAt > Date.now(), detectLanguage = (ctx) => ctx.req.query.lang ||
+        ctx.cookies?.get('lang') ||
+        ctx.headers.get('accept-language')?.split(',')[0] ||
+        options.defaultLanguage ||
+        'en', defaultLanguage = 'en', fallbackChain = [], translationFunctionKey = 't', formatMessage = (message, options = {}) => {
+        return Object.entries(options).reduce((msg, [key, value]) => msg.replace(new RegExp(`{{${key}}}`, 'g'), String(value)), message);
+    }, cacheTranslations = true } = options;
+    const translationCache = {};
+    return async (ctx, next) => {
+        try {
+            const detectedLanguage = detectLanguage(ctx);
+            const languageChain = [
+                detectedLanguage,
+                ...fallbackChain,
+                defaultLanguage
+            ].filter(Boolean);
+            let translations = null;
+            let selectedLanguage = defaultLanguage;
+            for (const lang of languageChain) {
+                const normalizedLang = lang.split('-')[0].toLowerCase();
+                if (cacheTranslations && translationCache[normalizedLang]) {
+                    const cached = translationCache[normalizedLang];
+                    if (isCacheValid(cached, normalizedLang)) {
+                        translations = cached.translations;
+                        selectedLanguage = lang;
+                        break;
+                    }
+                    delete translationCache[normalizedLang];
+                }
+                try {
+                    const { translations: loadedTranslations, expiresAt } = await loadTranslations(normalizedLang);
+                    let expirationTime = Date.now() + defaultCacheDuration;
+                    if (expiresAt instanceof Date) {
+                        expirationTime = expiresAt.getTime();
+                    }
+                    else if (typeof expiresAt === 'number') {
+                        expirationTime = expiresAt;
+                    }
+                    translations = loadedTranslations;
+                    selectedLanguage = lang;
+                    if (cacheTranslations) {
+                        translationCache[normalizedLang] = {
+                            translations,
+                            expiresAt: expirationTime,
+                        };
+                    }
+                    break;
+                }
+                catch (error) {
+                    GlobalConfig.debugging.warn(`Translation load failed for ${lang}:`, error);
+                }
+            }
+            if (!translations) {
+                throw new Error('No translations available');
+            }
+            ctx[translationFunctionKey] = (key, options) => {
+                const value = key.split('.').reduce((acc, k) => {
+                    return (acc && typeof acc === 'object') ? acc[k] : undefined;
+                }, translations);
+                const message = typeof value === 'string' ? value : key;
+                return formatMessage(message, options);
+            };
+            ctx.language = selectedLanguage;
+            ctx.languageChain = languageChain;
+            return await next();
+        }
+        catch (error) {
+            GlobalConfig.debugging.error('i18n processing error:', error);
+            ctx.setStatus = 500;
+            throw error;
+        }
+    };
+};

package/middleware/index.d.ts

@@ -7,3 +7,6 @@ export * from "./secureHeaders";
 export * from "./xssProtection";
 export * from "./sanitizeHeader";
 export * from "./rateLimiter";
+export * from "./pagination";
+export * from "./i18nMiddleware";
+export * from './lazyLoadModules';

package/middleware/index.js

@@ -6,3 +6,6 @@ export * from "./secureHeaders";
 export * from "./xssProtection";
 export * from "./sanitizeHeader";
 export * from "./rateLimiter";
+export * from "./pagination";
+export * from "./i18nMiddleware";
+export * from './lazyLoadModules';

package/middleware/lazyLoadModules.d.ts

@@ -0,0 +1,78 @@
+import { Context, Middleware } from "..";
+export type LazyModuleLoader<T> = () => Promise<T>;
+export interface CacheItem<T = any> {
+    module: T;
+    expiresAt: number;
+}
+interface LazyLoadOptions<T> {
+    /**
+     * 🗺️ Key to identify the module to load. This can be a function that extracts the module name from the request context.
+     * @default (ctx) => ctx.req.params[queryKeyModule] || ctx.req.query[queryKeyModule]
+     */
+    moduleKey?: (ctx: Context) => string;
+    /**
+     * 🛠️ Function that returns a loader function for the specified module, used to dynamically load the module.
+     * If this function returns null, it indicates no loader is available for the module.
+     */
+    getModuleLoader: (ctx: Context) => LazyModuleLoader<T> | null;
+    /**
+     * 🔍 Query parameter name to select which module to load (e.g., "module").
+     * @default "module"
+     */
+    queryKeyModule?: string;
+    /**
+     * 📦 Key to attach the loaded module to the context object.
+     * @default "module"
+     */
+    moduleContextKey?: string;
+    /**
+     * ⚙️ Dependencies to inject into the module during initialization.
+     */
+    dependencies?: Record<string, any>;
+    /**
+     * 🔄 Enable caching of loaded modules to avoid re-loading them repeatedly.
+     * @default true
+     */
+    enableCache?: boolean;
+    /**
+     * 🔄 Custom cache storage implementation (e.g., using `Map`, `Redis`, etc.).
+     * By default, it uses a `Map<string, CacheItem<T>>`.
+     */
+    cacheStorage?: {
+        get: (key: string) => CacheItem<T> | undefined;
+        set: (key: string, value: CacheItem<T>) => void;
+        delete: (key: string) => void;
+        clear?: () => void;
+    };
+    /**
+     * ⏳ Cache Time-To-Live (TTL) in milliseconds. This determines how long cached modules are valid.
+     * @default 3600000 (1 hour)
+     */
+    cacheTTL?: number;
+    /**
+     * 🌟 Lifecycle hooks for the module loading process.
+     * These hooks allow for custom actions at various stages of loading the module (e.g., when a module is loaded or when cache is hit).
+     */
+    lifecycleHooks?: {
+        onLoad?: (moduleName: string, ctx: Context) => void;
+        onError?: (moduleName: string, error: Error, ctx: Context) => void;
+        onComplete?: (moduleName: string, module: T, ctx: Context) => void;
+        onCacheHit?: (moduleName: string, module: T, ctx: Context) => void;
+        onCacheSet?: (moduleName: string, module: T, ctx: Context) => void;
+    };
+    /**
+     * 🛡️ Module validation function to ensure the module meets specific criteria before use.
+     * This function will be called after the module is loaded to verify its structure or behavior.
+     * If validation fails, an error is thrown.
+     */
+    validateModule?: (module: T) => boolean;
+}
+/**
+ * Middleware for handling lazy loading of modules. This middleware allows dynamically loading modules based on route or query parameters.
+ * It supports caching, lifecycle hooks, and module validation.
+ *
+ * @param options - Custom options for lazy loading, including caching, hooks, and module validation.
+ * @returns A middleware function to use in your application.
+ */
+export declare const lazyLoadModules: <T = any>(options: LazyLoadOptions<T>) => Middleware;
+export {};

package/middleware/lazyLoadModules.js

@@ -0,0 +1,62 @@
+import { GlobalConfig } from "../core/config";
+;
+export const lazyLoadModules = (options) => {
+    const { moduleKey = (ctx) => ctx.req.params[queryKeyModule] || ctx.req.query[queryKeyModule], getModuleLoader, queryKeyModule = "module", moduleContextKey = "module", cacheTTL = 3600000, dependencies = {}, enableCache = true, cacheStorage = new Map(), lifecycleHooks = {}, validateModule } = options;
+    return async (ctx, next) => {
+        let moduleName = moduleKey(ctx) || ctx.req.params[queryKeyModule] || ctx.req.query[queryKeyModule];
+        if (!moduleName) {
+            GlobalConfig.debugging.warn("No module specified for lazy loading.");
+            return await next();
+        }
+        try {
+            if (enableCache) {
+                const cached = cacheStorage.get(moduleName);
+                if (cached) {
+                    if (cached.expiresAt > Date.now()) {
+                        cacheStorage.delete(moduleName);
+                    }
+                    else {
+                        GlobalConfig.debugging.info(`Using cached module: ${moduleName}`);
+                        ctx[moduleContextKey] = cached?.module;
+                        lifecycleHooks.onCacheHit?.(moduleName, ctx[moduleContextKey], ctx);
+                        lifecycleHooks.onComplete?.(moduleName, ctx[moduleContextKey], ctx);
+                        return await next();
+                    }
+                }
+            }
+            if (!getModuleLoader) {
+                throw new Error(`No module loader found for module: ${moduleName}`);
+            }
+            const moduleLoader = getModuleLoader(ctx);
+            if (!moduleLoader) {
+                throw new Error(`No loader found for module: ${moduleName}`);
+            }
+            lifecycleHooks.onLoad?.(moduleName, ctx);
+            const module = await moduleLoader();
+            if (validateModule && !validateModule(module)) {
+                throw new Error(`Module validation failed for: ${moduleName}`);
+            }
+            ctx.dependencies = dependencies;
+            if (module.init && typeof module.init === "function") {
+                module.init(dependencies, ctx);
+            }
+            if (enableCache) {
+                cacheStorage.set(moduleName, {
+                    module,
+                    expiresAt: Date.now() + cacheTTL
+                });
+                lifecycleHooks.onCacheSet?.(moduleName, module, ctx);
+            }
+            ctx[moduleContextKey] = module;
+            lifecycleHooks.onComplete?.(moduleName, module, ctx);
+            GlobalConfig.debugging.success(`Successfully loaded module: ${moduleName}`);
+        }
+        catch (error) {
+            GlobalConfig.debugging.error(`Error loading module: ${moduleName}`, error);
+            lifecycleHooks.onError?.(moduleName, error, ctx);
+            ctx.setStatus = 500;
+            throw error;
+        }
+        return await next();
+    };
+};

package/middleware/pagination.d.ts

@@ -0,0 +1,89 @@
+import { Context, Middleware } from "..";
+export type PaginationOptions = {
+    /**
+     * 🔢 Default page number when not specified
+     * @default 1
+     * @example 1 // Start from first page
+     */
+    defaultPage?: number;
+    /**
+     * 📏 Default items per page
+     * @default 10
+     * @example 25 // Show 25 items by default
+     */
+    defaultLimit?: number;
+    /**
+     * ⚠️ Maximum allowed items per page
+     * @default 100
+     * @example 50 // Never return more than 50 items
+     */
+    maxLimit?: number;
+    /**
+     * 🔍 Query parameter name for page number
+     * @default "page"
+     * @example "p" // Use ?p=2 instead of ?page=2
+     */
+    queryKeyPage?: string;
+    /**
+     * 🔍 Query parameter name for items limit
+     * @default "limit"
+     * @example "size" // Use ?size=20
+     */
+    queryKeyLimit?: string;
+    /**
+     * 📊 Key to read total count from response
+     * @default "total"
+     * @example "totalCount" // Read from response.totalCount
+     */
+    countKey?: string;
+    /**
+     * 📦 Key containing the data array in response
+     * @default "data"
+     * @example "items" // Process response.items array
+     */
+    dataKey?: string;
+    /**
+     * 🛠️ Function to fetch data dynamically
+     * @param ctx - Request context
+     * @param pagination - Pagination details
+     * @returns Promise with data and total count
+     * @example
+     * getDataSource: async (ctx, { page, limit }) => {
+     *   return db.find().skip((page-1)*limit).limit(limit);
+     * }
+     */
+    getDataSource?: (ctx: Context, pagination: {
+        page: number;
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        [key: string]: any;
+    }>;
+};
+/**
+ * 🗂️ Advanced pagination middleware with dynamic data fetching
+ *
+ * Features:
+ * - Automatic pagination parameter handling
+ * - Dynamic data source integration
+ * - Comprehensive pagination metadata
+ * - Built-in error handling
+ *
+ * @param {PaginationOptions} [options={}] - Configuration options
+ * @returns {Middleware} Configured middleware
+ *
+ * @example
+ * // Basic usage
+ * app.get('/users', paginationHandler(), getUsers);
+ *
+ * // With dynamic data source
+ * app.get('/products', paginationHandler({
+ *   getDataSource: async (ctx, { page, limit }) => {
+ *     return await Product.findAndCountAll({
+ *       offset: (page-1)*limit,
+ *       limit
+ *     });
+ *   }
+ * }));
+ */
+export declare const paginationHandler: (options?: PaginationOptions) => Middleware;

package/middleware/pagination.js

@@ -0,0 +1,47 @@
+export const paginationHandler = (options = {}) => {
+    const { defaultPage = 1, defaultLimit = 10, maxLimit = 100, queryKeyPage = "page", queryKeyLimit = "limit", countKey = "total", dataKey = "data", getDataSource, } = options;
+    return async (ctx, next) => {
+        const rawPage = ctx.req.query[queryKeyPage];
+        const rawLimit = ctx.req.query[queryKeyLimit];
+        const page = Math.max(parseInt(rawPage || `${defaultPage}`, 10), 1);
+        const limit = Math.min(Math.max(parseInt(rawLimit || `${defaultLimit}`, 10), 1), maxLimit);
+        const offset = (page - 1) * limit;
+        ctx.pagination = {
+            page,
+            limit,
+            offset: offset,
+            queryKeyPage,
+            queryKeyLimit
+        };
+        if (getDataSource) {
+            try {
+                const dataSourceResponse = await getDataSource(ctx, { page, limit, offset });
+                const total = dataSourceResponse?.[countKey];
+                const data = dataSourceResponse?.[dataKey];
+                if (typeof total !== "number" || !Array.isArray(data)) {
+                    throw new Error("Invalid data structure returned by getDataSource.");
+                }
+                ctx.body = {
+                    [dataKey]: data,
+                    [countKey]: total,
+                    pagination: {
+                        page,
+                        limit,
+                        totalItems: total,
+                        totalPages: Math.ceil(total / limit),
+                        hasNextPage: page < Math.ceil(total / limit),
+                        hasPrevPage: page > 1,
+                        nextPage: page < Math.ceil(total / limit) ? page + 1 : null,
+                        prevPage: page > 1 ? page - 1 : null,
+                    },
+                };
+            }
+            catch (error) {
+                ctx.setStatus = 500;
+                ctx.body = { error: "Internal Server Error", };
+                throw new Error("Error fetching or processing data:", error?.message);
+            }
+        }
+        return await next();
+    };
+};

package/middleware/request-id.d.ts

@@ -13,4 +13,4 @@ import { Middleware } from "../core/router";
  * app.use(requestID());
  * ```
  */
-export declare const requestID: (headerName?: string) => Middleware;
+export declare const requestID: (headerName?: string, contextKey?: string) => Middleware;

package/middleware/request-id.js

@@ -1,10 +1,10 @@
 import { generateID } from "../helper";
-export const requestID = (headerName = "X-Request-ID") => {
+export const requestID = (headerName = "X-Request-ID", contextKey = "requestID") => {
     return (ctx, next) => {
         const existingID = ctx.headers?.get(headerName.toLowerCase()) ||
             ctx.headers?.get(headerName);
         const requestId = existingID || `req-${generateID()}`;
-        ctx.state.set("requestID", requestId);
+        ctx.set(contextKey, requestId);
         ctx.header(headerName, requestId);
         return next();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tezx",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "description": "TezX is a high-performance, lightweight JavaScript framework designed for speed, scalability, and flexibility. It enables efficient routing, middleware management, and static file serving with minimal configuration. Fully compatible with Node.js, Deno, and Bun.",
   "main": "cjs/index.js",
   "module": "index.js",