tezx 2.0.11 → 3.0.0

package/middleware/cors.d.ts

@@ -1,10 +1,37 @@
-import { ctx as Context } from "../types/index.js";
+import { Middleware } from "../types/index.js";
 export type CorsOptions = {
-    origin?: string | RegExp | (string | RegExp)[] | ((reqOrigin: string) => boolean);
+    /**
+     * Allowed origins for CORS.
+     * Can be a string, an array of strings, or a function that returns a boolean.
+     */
+    origin?: string | string[] | ((reqOrigin: string) => boolean);
+    /**
+     * Allowed HTTP methods for CORS requests.
+     * Defaults to ['GET', 'POST', 'PUT', 'DELETE'].
+     */
     methods?: string[];
+    /**
+     * Allowed headers for CORS requests.
+     * Defaults to ['Content-Type', 'Authorization'].
+     */
     allowedHeaders?: string[];
+    /**
+     * Headers exposed to the browser.
+     */
     exposedHeaders?: string[];
+    /**
+     * Indicates whether credentials are allowed.
+     */
     credentials?: boolean;
+    /**
+     * Preflight cache duration in seconds.
+     */
     maxAge?: number;
 };
-export declare function cors(option?: CorsOptions): (ctx: Context, next: () => Promise<any>) => Promise<any>;
+/**
+ * Middleware for handling Cross-Origin Resource Sharing (CORS).
+ *
+ * @param option - Configuration options for CORS.
+ */
+declare function cors<T extends Record<string, any> = {}, Path extends string = any>(option?: CorsOptions): Middleware<T, Path>;
+export { cors, cors as default };

package/middleware/cors.js

@@ -1,33 +1,25 @@
-export function cors(option = {}) {
-    const { methods, allowedHeaders, credentials, exposedHeaders, maxAge, origin, } = option;
+function cors(option = {}) {
+    const { credentials, maxAge, origin } = option;
+    let methods = (option.methods || ["GET", "POST", "PUT", "DELETE"]).join(", ");
+    let allowedHeaders = (option.allowedHeaders || ["Content-Type", "Authorization"]).join(", ");
+    let exposedHeaders = option?.exposedHeaders?.join(", ");
     return async function cors(ctx, next) {
-        const reqOrigin = ctx.req.headers.get("origin") || "";
+        const reqOrigin = ctx.req.header("origin") || "";
         let allowOrigin = "*";
         if (typeof origin === "string") {
             allowOrigin = origin;
         }
-        else if (origin instanceof RegExp) {
-            allowOrigin = origin.test(reqOrigin) ? reqOrigin : "";
-        }
         else if (Array.isArray(origin)) {
-            const isAllowed = origin.some((item) => {
-                if (typeof item === "string") {
-                    return item === reqOrigin;
-                }
-                else if (item instanceof RegExp) {
-                    return item.test(reqOrigin);
-                }
-            });
-            allowOrigin = isAllowed ? reqOrigin : "";
+            allowOrigin = origin.includes(reqOrigin) ? reqOrigin : "";
         }
         else if (typeof origin === "function") {
             allowOrigin = origin(reqOrigin) ? reqOrigin : "";
         }
         ctx.headers.set("Access-Control-Allow-Origin", allowOrigin);
-        ctx.headers.set("Access-Control-Allow-Methods", (methods || ["GET", "POST", "PUT", "DELETE"]).join(", "));
-        ctx.headers.set("Access-Control-Allow-Headers", (allowedHeaders || ["Content-Type", "Authorization"]).join(", "));
+        ctx.headers.set("Access-Control-Allow-Methods", methods);
+        ctx.headers.set("Access-Control-Allow-Headers", allowedHeaders);
         if (exposedHeaders) {
-            ctx.headers.set("Access-Control-Expose-Headers", exposedHeaders.join(", "));
+            ctx.headers.set("Access-Control-Expose-Headers", exposedHeaders);
         }
         if (credentials) {
             ctx.headers.set("Access-Control-Allow-Credentials", "true");
@@ -36,11 +28,9 @@ export function cors(option = {}) {
             ctx.headers.set("Access-Control-Max-Age", maxAge.toString());
         }
         if (ctx.req.method === "OPTIONS") {
-            return new Response(null, {
-                status: 204,
-                headers: ctx.headers,
-            });
+            return new Response(null, { status: 204, headers: ctx.headers });
         }
         return await next();
     };
 }
+export { cors, cors as default };

package/middleware/detect-bot.d.ts

@@ -0,0 +1,113 @@
+import { Context, Middleware } from "../index.js";
+import { HttpBaseResponse } from "../types/index.js";
+/**
+ * ⚙️ Configuration options for the `detectBot` middleware.
+ */
+export type DetectBotOptions = {
+    /**
+     * 🤖 List of known bot-like User-Agent patterns.
+     * @default ["bot", "spider", "crawl", "slurp"]
+     * @example
+     * botUserAgents: ["bot", "crawler", "indexer"]
+     */
+    botUserAgents?: string[];
+    /**
+     * ⚖️ Enable rate-limiting based bot detection.
+     * Requires `getConnInfo()` import from TezX runtime.
+     * @default false
+     * @example
+     * enableRateLimiting: true
+     */
+    enableRateLimiting?: boolean;
+    /**
+     * ⚠️ Maximum allowed requests in the rate-limit window.
+     * Only used when `enableRateLimiting` is true.
+     * @default 30
+     */
+    maxRequests?: number;
+    /**
+     * ⏱️ Time window for rate-limiting (in milliseconds).
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * 🔄 Custom rate-limit storage implementation.
+     * Allows integration with Redis, Memcached, or in-memory stores.
+     * @default In-memory Map
+     * @example
+     * storage: {
+     *   get: (key) => myRedisClient.get(key),
+     *   set: (key, value) => myRedisClient.set(key, value),
+     *   clearExpired: () => {}
+     * }
+     */
+    storage?: {
+        get: (key: string) => {
+            count: number;
+            resetTime: number;
+        } | undefined;
+        set: (key: string, value: {
+            count: number;
+            resetTime: number;
+        }) => void;
+        clearExpired: () => void;
+    };
+    /**
+     * 🚫 Optional IP blacklist checker.
+     * Should return true if the current request’s IP is banned or suspicious.
+     * @default () => false
+     * @example
+     * isBlacklisted: (ctx) => ctx.req.remoteAddress.address === "192.168.0.10"
+     */
+    isBlacklisted?: (ctx: Context) => boolean | Promise<boolean>;
+    /**
+     * 🧠 Custom bot detector function.
+     * Use this for advanced heuristics (e.g., suspicious query params or headers).
+     * @example
+     * customBotDetector: (ctx) => ctx.query?.token === "weird"
+     */
+    customBotDetector?: (ctx: Context) => boolean | Promise<boolean>;
+    /**
+     * 🛡️ Action executed when a bot is detected.
+     * Can return a custom HTTP response (e.g., JSON, HTML, or redirect).
+     * @default Responds with 403 and JSON error.
+     * @example
+     * onBotDetected: (ctx, reason) => ctx.status(403).json({ error: `Blocked: ${reason}` })
+     */
+    onBotDetected?: (ctx: Context, reason: string) => HttpBaseResponse;
+};
+/**
+ * 🤖 Smart Bot Detection Middleware
+ *
+ * Detects automated or malicious requests using a combination of:
+ * - User-Agent analysis
+ * - IP blacklisting
+ * - Rate limiting
+ * - Custom detection logic
+ *
+ * 🧩 Supports:
+ * - Bun (uses precompiled RegExp for speed)
+ * - Node.js / Deno (optimized `includes()` loop)
+ *
+ * ⚙️ Requirements (for rate limiting):
+ * You must import `getConnInfo` from your runtime adapter:
+ * ```ts
+ * import { getConnInfo } from "tezx/bun";
+ * // or
+ * import { getConnInfo } from "tezx/node";
+ * // or
+ * import { getConnInfo } from "tezx/deno";
+ * ```
+ *
+ * 📦 Example Usage:
+ * ```ts
+ * import { detectBot } from "tezx/middleware/detectBot";
+ *
+ * app.use(detectBot({
+ *   enableRateLimiting: true,
+ *   botUserAgents: ["bot", "crawler"],
+ *   onBotDetected: (ctx, reason) => ctx.status(403).json({ error: `Bot detected: ${reason}` })
+ * }));
+ * ```
+ */
+export declare const detectBot: (opts?: DetectBotOptions) => Middleware;

package/middleware/detect-bot.js

@@ -0,0 +1,53 @@
+import { GlobalConfig } from "../core/config.js";
+import { createRateLimitDefaultStorage, isRateLimit, } from "../utils/rateLimit.js";
+import { runtime } from "../utils/runtime.js";
+export const detectBot = (opts = {}) => {
+    const botUAs = opts.botUserAgents || ["bot", "spider", "crawl", "slurp"];
+    let checkBot;
+    if (runtime === "bun") {
+        const botRegex = new RegExp(botUAs.join("|"), "i");
+        checkBot = (ua) => botRegex.test(ua);
+    }
+    else {
+        checkBot = (ua) => {
+            for (const b of botUAs)
+                if (ua.includes(b))
+                    return true;
+            return false;
+        };
+    }
+    const maxReq = opts.maxRequests || 30;
+    const winMs = opts.windowMs || 60000;
+    const enableRL = !!opts.enableRateLimiting;
+    const onBot = opts.onBotDetected ??
+        ((ctx, reason) => ctx.status(403).json({ error: `Bot detected: ${reason}` }));
+    let store = opts.storage;
+    if (enableRL && !store)
+        store = createRateLimitDefaultStorage();
+    return async (ctx, next) => {
+        const ua = ctx.headers.get("user-agent") || "";
+        if (checkBot(ua)) {
+            return onBot?.(ctx, "User-Agent");
+        }
+        if (await opts?.isBlacklisted?.(ctx)) {
+            return onBot?.(ctx, "Blacklisted IP");
+        }
+        if (enableRL) {
+            const addr = ctx.req.remoteAddress;
+            if (!addr) {
+                GlobalConfig.debugging.warn("[TezX detectBot] Missing remoteAddress. Use `getConnInfo(ctx)` to enable rate limiting.");
+            }
+            else {
+                const key = `${addr.address}:${addr.port || 0}`;
+                const { check, entry } = isRateLimit(key, store, maxReq, winMs);
+                if (check && addr.address) {
+                    return onBot?.(ctx, `Rate limit exceeded. Retry after ${Math.ceil((entry.resetTime - Date.now()) / 1000)} seconds.`);
+                }
+            }
+        }
+        if (await opts.customBotDetector?.(ctx)) {
+            return onBot?.(ctx, "Custom Detector");
+        }
+        return await next();
+    };
+};

package/middleware/i18n.d.ts

@@ -2,100 +2,193 @@ import { Context, Middleware } from "../index.js";
 export type TranslationMap = {
     [key: string]: string | TranslationMap;
 };
-export type loadTranslations = (language: string) => Promise<{
-    translations: TranslationMap;
-    expiresAt?: Date | number;
-}>;
-export type I18nOptions = {
+export type loadTranslations = (language: string) => Promise<TranslationMap>;
+/**
+ * 📦 Interface defining a pluggable cache adapter for i18n translations.
+ *
+ * You can implement this interface to provide custom caching logic —
+ * for example, in-memory, Redis, file-based, or distributed cache.
+ *
+ * @example
+ * ```ts
+ * const redisCache: I18nCacheAdapter = {
+ *   async get(lang) {
+ *     const data = await redis.get(`i18n:${lang}`);
+ *     return data ? JSON.parse(data) : null;
+ *   },
+ *   async set(lang, data) {
+ *     await redis.set(`i18n:${lang}`, JSON.stringify(data), 'PX', data.expiresAt - Date.now());
+ *   },
+ *   async delete(lang) {
+ *     await redis.del(`i18n:${lang}`);
+ *   }
+ * };
+ * ```
+ */
+export interface I18nCacheAdapter {
     /**
-     * 🌐 Function to load translations dynamically
-     * @param language - Language code to load (e.g., "en-US")
-     * @returns Promise with translations map and optional expiration
+     * Retrieve cached translations for a specific language.
+     *
+     * @param lang - The language code (e.g., `"en"`, `"bn"`, `"fr"`)
+     * @returns A Promise resolving to the cached translations object
+     *          or `null` if not available or expired.
      */
-    loadTranslations: (language: string) => Promise<{
+    get(lang: string): Promise<{
         translations: TranslationMap;
-        expiresAt?: Date | number;
-    }>;
-    /**
-     * ⏱️ Default cache duration in milliseconds
-     * @default 3600000 (1 hour)
-     */
-    defaultCacheDuration?: number;
+        expiresAt: number;
+    } | null>;
     /**
-     * 🔄 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);
-     * }
+     * Store translations in cache for a specific language.
+     *
+     * @param lang - The language code (e.g., `"en"`, `"es"`)
+     * @param data - An object containing the translation map and expiration timestamp.
+     * @returns A Promise that resolves when caching is complete.
      */
-    isCacheValid?: (cached: {
+    set(lang: string, data: {
         translations: TranslationMap;
         expiresAt: number;
-    }, language: string) => boolean;
+    }): Promise<void>;
+    /**
+     * Remove cached translations for a specific language.
+     *
+     * @param lang - The language code to delete.
+     * @returns A Promise that resolves when deletion is complete.
+     */
+    delete(lang: string): Promise<void>;
+}
+/**
+ * ⚙️ Configuration options for the TezX i18n middleware.
+ *
+ * This configuration provides flexibility for:
+ * - dynamic translation loading
+ * - custom caching strategies
+ * - language detection logic
+ * - message formatting and interpolation
+ *
+ * @example
+ * ```ts
+ * app.use(i18n({
+ *   loadTranslations: lang => import(`./locales/${lang}.json`),
+ *   detectLanguage: ctx => ctx.req.query.lang || 'en',
+ *   cacheTranslations: true,
+ *   cacheStorage: redisCache,
+ *   defaultLanguage: 'en',
+ *   formatMessage: (msg, vars) => msg.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k])
+ * }));
+ * ```
+ */
+export type I18nOptions = {
+    /**
+     * 🌐 Function responsible for loading translation data dynamically.
+     *
+     * This can load translations from local JSON, database, API, etc.
+     *
+     * @param language - Language code to load (e.g., `"en"`, `"bn-BD"`)
+     * @returns Promise resolving to translation map for that language.
+     */
+    loadTranslations: loadTranslations;
+    /**
+     * ⏱️ Default cache duration in milliseconds.
+     *
+     * Defines how long translations remain valid before reloading.
+     *
+     * @default 3600000 (1 hour)
+     */
+    defaultCacheDuration?: number;
     /**
-     * 🔍 Custom language detection function
-     * @default Checks query param → cookie → Accept-Language header → default
+     * 🔍 Function to detect the preferred user language.
+     *
+     * Determines language priority from request context.
+     * Common strategies include:
+     * - URL query parameter
+     * - Cookie
+     * - HTTP `Accept-Language` header
+     *
      * @example
-     * detectLanguage: (ctx) => ctx.cookies.get('user_lang') || 'en'
+     * detectLanguage: (ctx) => ctx.req.query.lang || ctx.cookies.lang || 'en'
      */
-    detectLanguage?: (ctx: Context) => string;
+    detectLanguage: (ctx: Context) => string;
     /**
-     * 🏠 Default fallback language
+     * 🏠 Default fallback language.
+     *
+     * Used when detected language translations are unavailable.
+     *
      * @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
+     * 🗝️ Context property key where the translation function (`t`) is attached.
+     *
      * @default "t"
+     * @example
+     * ```ts
+     * ctx.t("greeting.hello");
+     * ctx.t("user.welcome", { name: "Rakibul" });
+     * ```
      */
     translationFunctionKey?: string;
     /**
-     * 💬 Message formatting function
-     * @default Basic template replacement ({{key}})
-     * @example
-     * formatMessage: (msg, vars) => {
-     *   return msg.replace(/\{(\w+)\}/g, (_, k) => vars[k]);
-     * }
+     * 💬 Custom message formatting function.
+     *
+     * Handles variable interpolation (e.g., replacing `{{name}}` with actual value).
+     * You can override this for advanced templating logic.
+     *
+     * @param message - The base translation string.
+     * @param vars - Optional variable map for placeholders.
+     * @returns Formatted string with variables replaced.
+     *
+     * @default
+     * ```ts
+     * (msg, vars = {}) =>
+     *   Object.entries(vars).reduce(
+     *     (m, [k, v]) => m.replace(new RegExp(`{{${k}}}`, "g"), String(v)),
+     *     msg
+     *   );
+     * ```
      */
-    formatMessage?: (message: string, options?: Record<string, any>) => string;
+    formatMessage?: (message: string, vars?: Record<string, any>) => string;
     /**
-     * 🗃️ Cache loaded translations
-     * @default true
+     * 🔒 Custom cache validation logic.
+     *
+     * Checks whether cached translations are still valid.
+     *
+     * @param cached - Cached object with translations and expiry timestamp.
+     * @param lang - The language being validated.
+     * @returns `true` if cache is valid, otherwise `false`.
+     *
+     * @default
+     * ```ts
+     * (cached) => cached.expiresAt > Date.now()
+     * ```
+     */
+    isCacheValid?: (cached: {
+        translations: TranslationMap;
+        expiresAt: number;
+    }, lang: string) => boolean;
+    /**
+     * 🗃️ Whether to enable caching for translations.
+     *
+     * If disabled, translations are always loaded fresh.
+     *
+     * @default false
      */
     cacheTranslations?: boolean;
+    /**
+     * 💾 Optional external cache adapter for distributed or persistent caching.
+     *
+     * Supports any system implementing `I18nCacheAdapter` interface —
+     * such as Redis, filesystem, in-memory store, or custom backends.
+     *
+     * @example
+     * ```ts
+     * app.use(i18n({
+     *   loadTranslations,
+     *   cacheTranslations: true,
+     *   cacheStorage: redisCache
+     * }));
+     * ```
+     */
+    cacheStorage?: I18nCacheAdapter;
 };
-/**
- * 🌍 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(i18n({
- *   loadTranslations: lang => import(`./locales/${lang}.json`),
- *   defaultLanguage: 'en'
- * }));
- *
- * // With caching and custom detection
- * app.use(i18n({
- *   loadTranslations: fetchTranslations,
- *   detectLanguage: ctx => ctx.get('X-Language'),
- *   cacheTranslations: true
- * }));
- */
-export declare const i18n: (options: I18nOptions) => Middleware;
+declare const i18n: (options: I18nOptions) => Middleware;
+export { i18n as default, i18n };