tezx 2.0.11 → 3.0.0

package/middleware/basicAuth.d.ts

@@ -1,81 +0,0 @@
-import { Context } from "../core/context.js";
-import { CallbackReturn, Middleware } from "../types/index.js";
-/**
- * Supported authentication method types.
- */
-export type AuthMethod = "basic" | "api-key" | "bearer-token";
-export type AuthCredential = {
-    username?: any;
-    password?: any;
-    token?: any;
-    apiKey?: any;
-};
-/**
- * Configuration options for dynamic basic authentication.
- */
-export type DynamicBasicAuthOptions = {
-    /**
-     * 🔐 Function to validate the provided credentials.
-     * @param method - The method of authentication.
-     * @param credentials - The extracted credentials.
-     * @param ctx - The current request context.
-     * @returns A boolean or Promise resolving to whether the credentials are valid.
-     */
-    validateCredentials: (method: AuthMethod, credentials: AuthCredential, ctx: Context) => boolean | Promise<boolean>;
-    /**
-     * 🔒 Function to dynamically determine the realm for authentication prompt.
-     * @param ctx - The current request context.
-     * @returns The authentication realm string.
-     */
-    getRealm?: (ctx: Context) => string;
-    /**
-     * ❌ Custom handler for unauthorized access.
-     * @param ctx - The current request context.
-     * @param error - Optional error information.
-     * @returns A CallbackReturn to end the response.
-     */
-    onUnauthorized?: (ctx: Context, error?: Error) => CallbackReturn;
-    /**
-     * 🚦 Rate-limiting configuration.
-     */
-    rateLimit?: {
-        /**
-         * 🧠 Custom cache or storage for rate-limit tracking.
-         */
-        storage?: {
-            get: (key: string) => {
-                count: number;
-                resetTime: number;
-            } | undefined;
-            set: (key: string, value: {
-                count: number;
-                resetTime: number;
-            }) => void;
-            clearExpired: () => void;
-        };
-        /** 🔁 Max requests allowed within the window */
-        maxRequests: number;
-        /** ⏲️ Duration of window in milliseconds */
-        windowMs: number;
-    };
-    /**
-     * 🛠 Supported authentication types.
-     * @default ["basic"]
-     */
-    supportedMethods?: AuthMethod[];
-    /**
-     * 🧑‍⚖️ Optional RBAC (Role-Based Access Control) check.
-     * @param ctx - The current request context.
-     * @param credentials - The validated credentials.
-     * @returns Whether access is allowed.
-     */
-    checkAccess?: (ctx: Context, credentials: AuthCredential) => boolean | Promise<boolean>;
-};
-/**
- * 🔐 Middleware for flexible authentication using Basic, API Key, or Bearer Token.
- * Supports rate limiting, IP filtering, and role-based access control.
- *
- * @param options - Custom authentication handler options.
- * @returns A middleware function.
- */
-export declare const basicAuth: (options: DynamicBasicAuthOptions) => Middleware;

package/middleware/basicAuth.js

@@ -1,67 +0,0 @@
-import { GlobalConfig } from "../core/config.js";
-import { colorText } from "../utils/colors.js";
-import { createRateLimitDefaultStorage, isRateLimit } from "./detectBot.js";
-export const basicAuth = (options) => {
-    const { validateCredentials, getRealm = () => "Restricted Area", onUnauthorized = (ctx, error) => {
-        const realm = getRealm(ctx);
-        ctx.setStatus = 401;
-        ctx.header("WWW-Authenticate", `Basic realm="${realm}"`);
-        ctx.body = { error: error?.message };
-    }, rateLimit, supportedMethods = ["basic", "api-key", "bearer-token"], checkAccess, } = options;
-    let storage = rateLimit?.storage;
-    if (rateLimit && !rateLimit.storage) {
-        storage = createRateLimitDefaultStorage();
-    }
-    return async function basicAuth(ctx, next) {
-        let authMethod;
-        let credentials = {};
-        const authHeader = ctx.req.headers.get("authorization");
-        if (authHeader) {
-            if (authHeader.startsWith("Basic ")) {
-                authMethod = "basic";
-                const base64Credentials = authHeader.split(" ")[1];
-                const decoded = Buffer.from(base64Credentials, "base64").toString("utf-8");
-                const [username, password] = decoded.split(":");
-                credentials = { username, password };
-            }
-            else if (authHeader.startsWith("Bearer ")) {
-                authMethod = "bearer-token";
-                credentials = { token: authHeader.split(" ")[1] };
-            }
-        }
-        else if (ctx.headers.get("x-api-key")) {
-            authMethod = "api-key";
-            credentials = { apiKey: ctx.headers.get("x-api-key") };
-        }
-        if (!authMethod || !supportedMethods.includes(authMethod)) {
-            GlobalConfig.debugging.error(`${colorText("[AUTH]", "bgRed")} Unsupported or missing authentication method.`);
-            return onUnauthorized(ctx, new Error("Unsupported authentication method"));
-        }
-        if (rateLimit) {
-            let key = `${ctx.req.remoteAddress.address}:${ctx.req.remoteAddress.port}`;
-            const { check, entry } = isRateLimit(ctx, key, storage, rateLimit.maxRequests, rateLimit.windowMs);
-            if (check) {
-                const retryAfter = Math.ceil((entry.resetTime - Date.now()) / 1000);
-                ctx.headers.set("Retry-After", retryAfter.toString());
-                return onUnauthorized(ctx, new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`));
-            }
-        }
-        try {
-            const isValid = await validateCredentials(authMethod, credentials, ctx);
-            if (!isValid) {
-                throw new Error("Invalid credentials.");
-            }
-            if (checkAccess) {
-                const hasAccess = await checkAccess(ctx, credentials);
-                if (!hasAccess) {
-                    return onUnauthorized(ctx, new Error("Access denied."));
-                }
-            }
-            return await next();
-        }
-        catch (error) {
-            GlobalConfig.debugging.error(`${colorText("[AUTH]", "bgRed")} Failure for method: ${ctx.method}`);
-            return onUnauthorized(ctx, error);
-        }
-    };
-};

package/middleware/cacheControl.d.ts

@@ -1,48 +0,0 @@
-import { Context } from "../core/context.js";
-import { Middleware } from "../types/index.js";
-export type CacheRule = {
-    /**
-     * 🎯 Condition to determine if this rule applies.
-     */
-    condition: (ctx: Context) => boolean;
-    /**
-     * ⏳ Maximum age (in seconds) for caching.
-     */
-    maxAge: number;
-    /**
-     * 🌐 Cache scope: "public" or "private".
-     */
-    scope: "public" | "private";
-    /**
-     * 🔄 Enable or disable revalidation with ETag.
-     */
-    enableETag: boolean;
-    /**
-     * 🏷️ Vary header for cache variations.
-     */
-    vary?: string[];
-};
-export type CacheSettings = Pick<CacheRule, "maxAge" | "scope" | "enableETag" | "vary">;
-export type CacheOptions = {
-    /**
-     * 🧪 Weak ETag generation (optional).
-     */
-    useWeakETag?: boolean;
-    /**
-     * 📝 Logging function for cache events.
-     */
-    logEvent?: (event: "cached" | "no-cache" | "error", ctx: Context, error?: Error) => void;
-    /**
-     * 🛠️ Default cache settings.
-     */
-    defaultSettings: CacheSettings;
-    /**
-     * 🔧 Custom rules for dynamic caching behavior.
-     */
-    rules?: CacheRule[];
-};
-/**
- * Middleware to manage HTTP caching headers dynamically.
- * @param options - Custom options for dynamic caching behavior.
- */
-export declare const cacheControl: (options: CacheOptions) => Middleware;

package/middleware/cacheControl.js

@@ -1,53 +0,0 @@
-import { GlobalConfig } from "../core/config.js";
-export const cacheControl = (options) => {
-    const { defaultSettings, useWeakETag = false, rules = [], logEvent = (event, ctx, error) => {
-        if (event === "error") {
-            GlobalConfig.debugging.error(`[CACHE] ${event.toUpperCase()}: ${error?.message}`);
-        }
-        else {
-            GlobalConfig.debugging.success(`[CACHE] ${event.toUpperCase()} for ${ctx.method} ${ctx.pathname}`);
-        }
-    }, } = options;
-    return async function cacheControl(ctx, next) {
-        if (!["GET", "HEAD"].includes(ctx.method)) {
-            return await next();
-        }
-        try {
-            await next();
-            const matchedRule = rules.find((rule) => rule.condition(ctx)) || null;
-            const { maxAge, scope, enableETag, vary } = matchedRule || defaultSettings;
-            const cacheControlValue = `${scope}, max-age=${maxAge}`;
-            ctx.header("Cache-Control", cacheControlValue);
-            const expiresDate = new Date(Date.now() + maxAge * 1000).toUTCString();
-            ctx.header("Expires", expiresDate);
-            if (vary?.length) {
-                ctx.header("Vary", vary.join(", "));
-            }
-            if (enableETag) {
-                const responseBody = typeof ctx.resBody === "string"
-                    ? ctx.resBody
-                    : JSON.stringify(ctx.resBody ?? "");
-                const etag = await generateETag(responseBody, useWeakETag);
-                const ifNoneMatch = ctx.req.headers.get("if-none-match");
-                if (ifNoneMatch === etag) {
-                    ctx.setStatus = 304;
-                    ctx.body = null;
-                    logEvent("cached", ctx);
-                    return;
-                }
-                ctx.header("ETag", etag);
-            }
-            logEvent("cached", ctx);
-        }
-        catch (error) {
-            logEvent("error", ctx, error);
-            ctx.setStatus = 500;
-            ctx.body = { error: "Failed to set cache headers." };
-        }
-    };
-};
-const generateETag = async (content, weak = false) => {
-    const crypto = await import("node:crypto");
-    const hash = crypto.createHash("md5").update(content).digest("hex");
-    return weak ? `W/"${hash}"` : `"${hash}"`;
-};

package/middleware/detectBot.d.ts

@@ -1,121 +0,0 @@
-import { Context, Middleware } from "../index.js";
-import { CallbackReturn } from "../types/index.js";
-export type DetectBotReason = "User-Agent" | "Blacklisted IP" | "Query Parameter" | "Rate Limiting" | "Custom Detector" | "Multiple Indicators";
-export type BotDetectionResult = {
-    isBot: boolean;
-    reason?: DetectBotReason;
-    indicators: string[];
-};
-export type DetectBotOptions = {
-    /**
-     * 🤖 List of bot-like user-agent substrings to detect
-     * @default ["bot", "spider", "crawl", "slurp"]
-     */
-    botUserAgents?: string[];
-    /**
-     * ⚠️ Maximum allowed requests in the time window
-     * @default 30 requests
-     */
-    maxRequests?: number;
-    /**
-     * ⏱️ Time window in milliseconds for rate limiting
-     * @default 60000 (1 minute)
-     */
-    windowMs?: number;
-    /**
-     * 🚫 IP blacklist checker
-     * @default () => false
-     */
-    isBlacklisted?: (ctx: Context, remoteAddress: string) => boolean | Promise<boolean>;
-    /**
-     * 🔍 Query parameter name for bot identification
-     * @default "bot"
-     */
-    queryKeyBot?: string;
-    /**
-     * 🛡️ Action to take when bot is detected
-     * @default "block"
-     */
-    onBotDetected?: "block" | ((ctx: Context, result: BotDetectionResult) => CallbackReturn);
-    /**
-     * ⚖️ Enable rate-limiting based detection
-     * @default false
-     */
-    enableRateLimiting?: boolean;
-    /**
-     * 🔎 Custom bot detection logic
-     * @default () => false
-     */
-    customBotDetector?: (ctx: Context) => boolean | Promise<boolean>;
-    /**
-     * ✉️ Custom response for blocked requests
-     */
-    customBlockedResponse?: (ctx: Context, result: BotDetectionResult) => CallbackReturn;
-    /**
-     * 🔄 Custom cache storage implementation (e.g., using `Map`, `Redis`, etc.).
-     * By default, it uses a `Map<string, { count: number; resetTime: number }>`.
-     */
-    storage?: {
-        get: (key: string) => {
-            count: number;
-            resetTime: number;
-        } | undefined;
-        set: (key: string, value: {
-            count: number;
-            resetTime: number;
-        }) => void;
-        clearExpired: () => void;
-    };
-    /**
-     * 📊 Minimum confidence score to consider as bot (0-1)
-     * @default 0.5
-     */
-    confidenceThreshold?: number;
-};
-/**
- * 🤖 Advanced bot detection middleware with multiple detection methods
- *
- * Features:
- * - User-Agent analysis
- * - IP blacklisting
- * - Query parameter detection
- * - Rate limiting
- * - Custom detection logic
- * - Confidence-based scoring
- *
- * @param {DetectBotOptions} options - Configuration options
- * @returns {Middleware} Configured middleware
- *
- * @example
- * // Basic usage
- * app.use(detectBot());
- *
- * // Custom configuration
- * app.use(detectBot({
- *   botUserAgents: ["bot", "crawler"],
- *   isBlacklistedIP: async (ip) => await checkIPReputation(ip),
- *   onBotDetected: (ctx, { reason }) => {
- *     ctx.status = 403;
- *     return ctx.json({ error: `Bot detected (${reason})` });
- *   }
- * }));
- */
-export declare const detectBot: (options?: DetectBotOptions) => Middleware;
-export declare function createRateLimitDefaultStorage(): {
-    get: (key: string) => {
-        count: number;
-        resetTime: number;
-    } | undefined;
-    set: (key: string, value: {
-        count: number;
-        resetTime: number;
-    }) => Map<string, {
-        count: number;
-        resetTime: number;
-    }>;
-    clearExpired: () => void;
-};
-export declare function isRateLimit(ctx: Context, key: string, store: any, maxRequests: number, windowMs: number): {
-    check: boolean;
-    entry: any;
-};

package/middleware/detectBot.js

@@ -1,98 +0,0 @@
-import { GlobalConfig } from "../core/config.js";
-export const detectBot = (options = {}) => {
-    const { botUserAgents = ["bot", "spider", "crawl", "slurp"], maxRequests = 30, windowMs = 60000, isBlacklisted = async () => false, queryKeyBot = "bot", onBotDetected = "block", enableRateLimiting = false, customBotDetector = async () => false, customBlockedResponse = (ctx, { reason }) => {
-        ctx.setStatus = 403;
-        return ctx.json({ error: `Bot detected: ${reason}` });
-    }, storage, confidenceThreshold = 0.5, } = options;
-    let store = storage;
-    if (enableRateLimiting) {
-        store = createRateLimitDefaultStorage();
-    }
-    return async function detectBot(ctx, next) {
-        const detectionResult = {
-            isBot: false,
-            indicators: [],
-        };
-        const userAgent = ctx.headers.get("user-agent")?.toLowerCase() || "";
-        const remoteAddress = `${ctx.req.remoteAddress?.address}:${ctx.req.remoteAddress?.port}` ||
-            "unknown";
-        const isBotQuery = ctx.req.query[queryKeyBot] === "true";
-        if (botUserAgents.some((agent) => userAgent.includes(agent))) {
-            detectionResult.indicators.push("User-Agent");
-        }
-        if (await isBlacklisted(ctx, remoteAddress)) {
-            detectionResult.indicators.push("Blacklisted IP");
-        }
-        if (isBotQuery) {
-            detectionResult.indicators.push("Query Parameter");
-        }
-        const key = `${ctx.req.remoteAddress.address}:${ctx.req.remoteAddress.port}`;
-        if (enableRateLimiting &&
-            isRateLimit(ctx, key, store, maxRequests, windowMs).check) {
-            detectionResult.indicators.push("Rate Limiting");
-        }
-        if (await customBotDetector(ctx)) {
-            detectionResult.indicators.push("Custom Detector");
-        }
-        detectionResult.isBot = detectionResult.indicators.length > 0;
-        if (detectionResult.indicators.length > 1) {
-            detectionResult.reason = "Multiple Indicators";
-            const confidence = Math.min(0.3 * detectionResult.indicators.length, 1);
-            detectionResult.isBot = confidence >= confidenceThreshold;
-        }
-        else if (detectionResult.indicators.length === 1) {
-            detectionResult.reason = detectionResult.indicators[0];
-        }
-        if (detectionResult.isBot) {
-            GlobalConfig.debugging.warn(`Bot detected: ${detectionResult.reason}`, {
-                ip: remoteAddress,
-                userAgent,
-                indicators: detectionResult.indicators,
-            });
-            if (onBotDetected === "block") {
-                return customBlockedResponse(ctx, detectionResult);
-            }
-            else if (typeof onBotDetected === "function") {
-                return onBotDetected(ctx, detectionResult);
-            }
-        }
-        return await next();
-    };
-};
-export function createRateLimitDefaultStorage() {
-    const store = new Map();
-    return {
-        get: (key) => store.get(key),
-        set: (key, value) => store.set(key, value),
-        clearExpired: () => {
-            const now = Date.now();
-            for (const [key, entry] of store.entries()) {
-                if (now >= entry.resetTime) {
-                    store.delete(key);
-                }
-            }
-        },
-    };
-}
-export function isRateLimit(ctx, key, store, maxRequests, windowMs) {
-    store.clearExpired();
-    const now = Date.now();
-    let entry = store.get(key) || { count: 0, resetTime: now + windowMs };
-    if (now < entry.resetTime) {
-        entry.count++;
-        if (entry.count > maxRequests) {
-            return {
-                check: true,
-                entry: entry,
-            };
-        }
-    }
-    else {
-        entry = { count: 1, resetTime: now + windowMs };
-    }
-    store.set(key, entry);
-    return {
-        check: false,
-        entry: entry,
-    };
-}

package/middleware/detectLocale.d.ts

@@ -1,55 +0,0 @@
-import { Context, Middleware } from "../index.js";
-/**
- * Options for the detectLocale middleware.
- */
-export type DetectLocaleOptions = {
-    /**
-     * 🌐 List of allowed locales.
-     * e.g., ["en", "fr", "bn"]
-     */
-    supportedLocales: string[];
-    /**
-     * 🏠 Default locale if none is matched from query, cookie, or headers.
-     * @default "en"
-     */
-    defaultLocale?: string;
-    /**
-     * 🔍 Name of the query parameter to check for locale.
-     * Example: /?lang=fr
-     * @default "lang"
-     */
-    queryKeyLocale?: string;
-    /**
-     * 🍪 Name of the cookie used to store locale preference.
-     * @default "locale"
-     */
-    cookieKeyLocale?: string;
-    /**
-     * 🗺️ Key under which the locale will be attached to the context object.
-     * Example: ctx.locale = "en"
-     * @default "locale"
-     */
-    localeContextKey?: string;
-    /**
-     * 🛠️ Optional custom function to programmatically detect locale.
-     * Called last before fallback.
-     * Should return a supported locale or undefined.
-     */
-    customLocaleDetector?: (ctx: Context) => string | undefined;
-};
-/**
- * 🌍 Middleware that detects and sets the user's preferred locale.
- *
- * Detection order:
- * 1. Query parameter (e.g., ?lang=fr)
- * 2. Cookie value (e.g., locale=fr)
- * 3. Accept-Language HTTP header
- * 4. Custom detector function (if provided)
- * 5. Default locale (fallback)
- *
- * The detected locale is stored in `ctx[localeContextKey]`.
- *
- * @param options - Configuration options for locale detection.
- * @returns Middleware function that attaches locale to the context.
- */
-export declare const detectLocale: (options: DetectLocaleOptions) => Middleware;

package/middleware/detectLocale.js

@@ -1,39 +0,0 @@
-import { GlobalConfig } from "../core/config.js";
-export const detectLocale = (options) => {
-    const { supportedLocales, defaultLocale = "en", queryKeyLocale = "lang", cookieKeyLocale = "locale", localeContextKey = "locale", customLocaleDetector, } = options;
-    return async function detectLocale(ctx, next) {
-        let detectedLocale;
-        const queryLocale = ctx.req.query[queryKeyLocale];
-        if (queryLocale && supportedLocales.includes(queryLocale)) {
-            detectedLocale = queryLocale;
-        }
-        if (!detectedLocale) {
-            const cookieLocale = ctx.cookies.get(cookieKeyLocale);
-            if (cookieLocale && supportedLocales.includes(cookieLocale)) {
-                detectedLocale = cookieLocale;
-            }
-        }
-        if (!detectedLocale) {
-            const acceptLanguage = ctx.req.headers.get("accept-language");
-            if (acceptLanguage) {
-                const preferredLocales = acceptLanguage
-                    .split(",")
-                    .map((lang) => lang.split(";")[0].trim())
-                    .filter((lang) => supportedLocales.includes(lang));
-                detectedLocale = preferredLocales[0];
-            }
-        }
-        if (!detectedLocale && customLocaleDetector) {
-            const customLocale = customLocaleDetector(ctx);
-            if (customLocale && supportedLocales.includes(customLocale)) {
-                detectedLocale = customLocale;
-            }
-        }
-        if (!detectedLocale) {
-            detectedLocale = defaultLocale;
-        }
-        ctx[localeContextKey] = detectedLocale;
-        GlobalConfig.debugging.success(`Detected locale: ${detectedLocale}`);
-        return await next();
-    };
-};

package/middleware/lazyLoadModules.d.ts

@@ -1,72 +0,0 @@
-import { Context, Middleware } from "../index.js";
-export type LazyModuleLoader<T> = () => Promise<T>;
-export interface CacheItem<T = any> {
-    module: T;
-    expiresAt: number;
-}
-export 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) => Promise<LazyModuleLoader<T> | null> | null | LazyModuleLoader<T>;
-    /**
-     * 🔍 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;
-    /**
-     * 🔄 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;
-    };
-    /**
-     * ⏳ 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;