tezx 2.0.11 → 3.0.0

package/utils/file.js

@@ -0,0 +1,96 @@
+import { TezXError } from "../core/error.js";
+import { runtime } from "./runtime.js";
+export async function fileExists(path) {
+    switch (runtime) {
+        case "node": {
+            const { access } = await import("node:fs/promises");
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        case "bun":
+            return Bun.file(path).exists();
+        case "deno":
+            try {
+                await Deno.stat(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        default:
+            return false;
+    }
+}
+export async function getFileBuffer(path) {
+    switch (runtime) {
+        case "node": {
+            const { readFile } = await import("node:fs/promises");
+            return readFile(path);
+        }
+        case "bun": {
+            return new Uint8Array(await Bun.file(path).arrayBuffer());
+        }
+        case "deno":
+            return Deno.readFile(path);
+        default:
+            throw new TezXError("Unsupported runtime environment");
+    }
+}
+export async function readStream(path) {
+    switch (runtime) {
+        case "node": {
+            const { createReadStream } = await import("node:fs");
+            const { Readable } = await import("node:stream");
+            return Readable.toWeb(createReadStream(path));
+        }
+        case "bun": {
+            return Bun.file(path).stream();
+        }
+        case "deno": {
+            return (await Deno.open(path, { read: true })).readable;
+        }
+        default:
+            throw new TezXError("Unsupported runtime environment");
+    }
+}
+export async function fileSize(path) {
+    switch (runtime) {
+        case "node": {
+            const { stat } = await import("node:fs/promises");
+            const st = await stat(path);
+            return { size: st.size, mtime: st.mtime };
+        }
+        case "bun": {
+            const st = await Bun.file(path).stat();
+            return { size: st.size, mtime: st.mtime };
+        }
+        case "deno": {
+            const st = await Deno.stat(path);
+            return {
+                size: st.size,
+                mtime: st.mtime ?? new Date(),
+            };
+        }
+        default:
+            throw new TezXError("Unsupported runtime: " + runtime);
+    }
+}
+export async function etagDigest(algo = "MD5", data) {
+    const encoded = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    if (runtime === "bun") {
+        return Bun.hash(data, 256).toString(16);
+    }
+    if (globalThis?.crypto?.subtle) {
+        const buffer = await crypto.subtle.digest(algo, encoded);
+        return Array.from(new Uint8Array(buffer))
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+    const { createHash } = await import("node:crypto");
+    return createHash(algo).update(encoded).digest("hex");
+}

package/utils/formData.d.ts

@@ -1 +1,41 @@
-export declare function sanitized(title: string): string;
+import { Context } from "../index.js";
+import { FormDataOptions } from "../types/index.js";
+/**
+ * Parses and validates multipart/form-data from the request context.
+ *
+ * This helper extracts form fields and files from the request's FormData,
+ * applies validation rules defined in the `options`, and returns a structured
+ * object with key-value pairs, where values can be strings, Files, or arrays of them.
+ *
+ * Validation includes:
+ * - File MIME type whitelist
+ * - Maximum file size per file
+ * - Maximum number of files per field
+ * - Maximum combined size of all uploaded files
+ * - Maximum length of individual text fields
+ * - Optional sanitization of text fields (if enabled)
+ *
+ * Repeated form field keys will result in an array of values.
+ *
+ * @param {Context} ctx - The HTTP request context containing the FormData.
+ * @param {FormDataOptions} [options] - Configuration options to control parsing and validation.
+ * @throws {Error} Throws if any validation rule is violated (e.g., file too large, too many files).
+ * @returns {Promise<Record<string, string | File | (string | File)[]>>} A Promise resolving to an object mapping form field names
+ * to their respective values. Values are strings or File objects, or arrays if multiple values per key exist.
+ *
+ * @example
+ * ```ts
+ * import { useFormData } from "tezx/helper";
+ *
+ * const formData = await useFormData(ctx, {
+ *   allowedTypes: ["image/jpeg", "image/png"],
+ *   maxSize: 5 * 1024 * 1024, // 5MB per file
+ *   maxFiles: 3,
+ *   maxTotalSize: 15 * 1024 * 1024, // 15MB total
+ *   maxFieldSize: 1000,
+ *   sanitized: true
+ * });
+ * ```
+ */
+export declare function useFormData<T extends Record<string, string | File | (string | File)[]>>(ctx: Context, options?: FormDataOptions): Promise<T>;
+export declare function processFile(file: File, key: string, options: FormDataOptions, totalGetter: () => number): Promise<File>;

package/utils/formData.js

@@ -1,10 +1,59 @@
-export function sanitized(title) {
-    const base = title
-        .toLowerCase()
-        .trim()
-        .replace(/[_\s]+/g, "-")
-        .replace(/[^a-z0-9-.]+/g, "")
-        .replace(/--+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return base;
+import { sanitized } from "./low-level.js";
+export async function useFormData(ctx, options) {
+    const fd = await ctx.req.formData();
+    const result = {};
+    let totalFileBytes = 0;
+    for (const [key, originalVal] of fd.entries()) {
+        let val = originalVal;
+        if (val instanceof File && options) {
+            val = await processFile(val, key, options, () => totalFileBytes);
+            totalFileBytes += val.size;
+            if (typeof options.maxTotalSize === "number" &&
+                totalFileBytes > options.maxTotalSize) {
+                throw new Error(`Total file bytes exceeded maxTotalSize=${options.maxTotalSize}`);
+            }
+        }
+        else if (typeof val === "string" &&
+            options?.maxFieldSize &&
+            val.length > options.maxFieldSize) {
+            throw new Error(`Field "${key}" length ${val.length} exceeds maxFieldSize=${options.maxFieldSize}`);
+        }
+        if (key in result) {
+            if (!Array.isArray(result[key])) {
+                result[key] = [result[key]];
+            }
+            result[key].push(val);
+        }
+        else {
+            result[key] = val;
+        }
+        if (val instanceof File && typeof options?.maxFiles === "number") {
+            const filesForKey = Array.isArray(result[key])
+                ? result[key].filter((v) => v instanceof File).length
+                : result[key] instanceof File
+                    ? 1
+                    : 0;
+            if (filesForKey > options.maxFiles) {
+                throw new Error(`Field "${key}" exceeds maxFiles (${options.maxFiles})`);
+            }
+        }
+    }
+    return result;
+}
+export async function processFile(file, key, options, totalGetter) {
+    let name = file.name;
+    if (options.sanitized) {
+        name = `${Date.now()}-${sanitized(name)}`;
+    }
+    if (Array.isArray(options.allowedTypes) &&
+        !options.allowedTypes.includes(file.type)) {
+        throw new Error(`Field "${key}": invalid file type "${file.type}". Allowed: ${options.allowedTypes.join(", ")}`);
+    }
+    if (typeof options.maxSize === "number" && file.size > options.maxSize) {
+        throw new Error(`Field "${key}": file size ${file.size} > maxSize ${options.maxSize}`);
+    }
+    if (name !== file.name) {
+        return new File([await file.arrayBuffer()], name, { type: file.type });
+    }
+    return file;
 }

package/utils/generateID.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generate a fast, unique ID string using timestamp and random values.
+ *
+ * **Note:** This function is generally fast, but `generateUUID()` using
+ * `crypto.randomUUID()` is even faster and more standardized in modern environments.
+ *
+ * Use `generateUUID()` if you want a UUID v4 string that is cryptographically secure
+ * and ultra-fast (native implementation).
+ *
+ * Format: [timestamp in hex]-[random 12 hex chars]
+ *
+ * @returns {string} Unique ID string
+ */
+export declare function generateID(): string;
+/**
+ * Generate a cryptographically secure UUID (version 4).
+ *
+ * This uses the Web Crypto API's `crypto.randomUUID()` method to generate a
+ * unique identifier. The UUID conforms to RFC4122 version 4 standard.
+ *
+ * @returns {string} A unique UUID string (e.g., "e7b2bfb2-86f5-4a6d-9e7f-b5121a2b8e7d").
+ *
+ * @runtime Supported in:
+ * - ✅ Bun (native Web Crypto, extremely fast)
+ * - ✅ Deno (native Web Crypto, fast)
+ * - ✅ Node.js (v15+): via global `crypto.randomUUID()`
+ *   ⚠️ In Node.js v14 or below, this will throw an error unless you polyfill `crypto`
+ *
+ * @example
+ * const uuid = generateUUID();
+ * console.log(uuid); // "a63e47b6-6a3b-4d53-90b6-8db2f2d07943"
+ */
+export declare function generateUUID(): string;
+/**
+ * Generate a short nonce (JS-only, low-GC) by sampling the BASE64 charset.
+ * This function intentionally uses Math.random for speed and low allocation.
+ * If you require cryptographic randomness, swap with crypto.randomFillSync.
+ *
+ * @param {number} [length=16] - nonce length in characters
+ * @returns {string} generated nonce string
+ */
+export declare function generateRandomBase64(length?: number): string;

package/utils/generateID.js

@@ -0,0 +1,32 @@
+export function generateID() {
+    const timestamp = Date.now().toString(16);
+    let randomHex = "";
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.getRandomValues === "function") {
+        const array = new Uint8Array(6);
+        crypto.getRandomValues(array);
+        for (let i = 0; i < array.length; i++) {
+            randomHex += array[i].toString(16).padStart(2, "0");
+        }
+    }
+    else {
+        randomHex = Math.floor(Math.random() * 0xffffffffffff)
+            .toString(16)
+            .padStart(12, "0");
+    }
+    return `${timestamp}-${randomHex}`;
+}
+export function generateUUID() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function")
+        return crypto.randomUUID();
+    return generateID();
+}
+export function generateRandomBase64(length = 16) {
+    let result = "";
+    const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    for (let i = 0; i < length; i++) {
+        const idx = Math.floor(Math.random() * 64);
+        result += BASE64[idx];
+    }
+    return result;
+}

package/utils/httpStatusMap.d.ts

@@ -1 +1,15 @@
+/**
+ * A mapping of HTTP status codes to their standard reason phrases.
+ *
+ * This object maps common HTTP status codes to their
+ * respective textual descriptions, useful for setting
+ * or interpreting HTTP response status texts.
+ *
+ * @constant {Record<number, string>}
+ *
+ * @example
+ * httpStatusMap[200]; // "OK"
+ * httpStatusMap[404]; // "Not Found"
+ * httpStatusMap[418]; // "I'm a Teapot"
+ */
 export declare const httpStatusMap: Record<number, string>;

package/utils/low-level.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Normalizes an HTTP header key to "Title-Case" format.
+ * For example, `"content-type"` becomes `"Content-Type"`.
+ *
+ * @param {string} key - The HTTP header key to normalize.
+ * @returns {string} The normalized header key in Title-Case format.
+ *
+ * @example
+ * normalizeHeaderKey("content-type"); // → "Content-Type"
+ * normalizeHeaderKey("x-custom-header"); // → "X-Custom-Header"
+ */
+export declare function normalizeHeaderKey(key: string): string;
+/**
+ * Extracts the file extension from a given file path or filename.
+ * The returned extension is always lowercase.
+ *
+ * @param {string} filePath - The full file path or filename.
+ * @returns {string} The file extension without the dot, or an empty string if none found.
+ *
+ * @example
+ * extensionExtract("image.PNG"); // → "png"
+ * extensionExtract("/path/to/archive.tar.gz"); // → "gz"
+ * extensionExtract("filename"); // → ""
+ */
+export declare function extensionExtract(filePath: string): string;
+/**
+ * Combines a base path and a relative path, then splits the combined path into segments,
+ * filtering out any `".."` segments to sanitize the path.
+ *
+ * @param {string} basePath - The base path (e.g., "/api").
+ * @param {string} path - The relative or additional path to combine (e.g., "users/123").
+ * @param {string[]} [out] - Optional array to append the segments to.
+ * @returns {string[]} Array of sanitized path segments (without `".."`).
+ *
+ * @example
+ * sanitizePathSplitBasePath("/api", "users/../admin"); // returns ["api", "admin"]
+ */
+export declare function sanitizePathSplitBasePath(basePath: string, path: string, out?: string[]): string[];
+/**
+ * Splits a path string into segments, ignoring `".."` segments to sanitize the path.
+ *
+ * @param {string} path - The path string to split (e.g., "/api/users/../admin").
+ * @param {string[]} [out] - Optional array to append the segments to.
+ * @returns {string[]} Array of sanitized path segments (without `".."`).
+ *
+ * @example
+ * sanitizePathSplit("/api/users/../admin"); // returns ["api", "users", "admin"]
+ */
+export declare function sanitizePathSplit(path: string, out?: string[]): string[];
+/**
+ * Ultra-fast string slugifier.
+ * Uses low-level string operations to reduce RegExp overhead.
+ * Falls back to minimal replacements if environment lacks full RegExp support.
+ *
+ * @param {string} title - Input string to slugify
+ * @returns {string} - Slugified, URL-safe string
+ */
+export declare function sanitized(title: string): string;

package/utils/low-level.js

@@ -0,0 +1,108 @@
+export function normalizeHeaderKey(key) {
+    let result = "";
+    let upperNext = true;
+    for (let i = 0; i < key.length; i++) {
+        const ch = key.charCodeAt(i);
+        if (ch === 45) {
+            result += "-";
+            upperNext = true;
+        }
+        else {
+            result += upperNext
+                ? String.fromCharCode(ch >= 97 && ch <= 122 ? ch - 32 : ch)
+                : String.fromCharCode(ch >= 65 && ch <= 90 ? ch + 32 : ch);
+            upperNext = false;
+        }
+    }
+    return result;
+}
+export function extensionExtract(filePath) {
+    let lastDot = -1;
+    for (let i = filePath.length - 1; i >= 0; i--) {
+        if (filePath[i] === ".") {
+            lastDot = i;
+            break;
+        }
+    }
+    if (lastDot === -1 || lastDot === filePath.length - 1)
+        return "";
+    let ext = "";
+    for (let i = lastDot + 1; i < filePath.length; i++) {
+        let c = filePath.charCodeAt(i);
+        if (c >= 65 && c <= 90) {
+            c += 32;
+        }
+        ext += String.fromCharCode(c);
+    }
+    return ext;
+}
+export function sanitizePathSplitBasePath(basePath, path, out) {
+    const combined = `${basePath}/${path}`;
+    const parts = out ?? [];
+    let segStart = 0;
+    let i = 0;
+    const len = combined.length;
+    while (i < len) {
+        const code = combined.charCodeAt(i);
+        if (code === 47 || code === 92) {
+            if (segStart < i) {
+                const seg = combined.slice(segStart, i);
+                if (seg !== "..")
+                    parts.push(seg);
+            }
+            segStart = i + 1;
+        }
+        i++;
+    }
+    if (segStart < len) {
+        const seg = combined.slice(segStart, len);
+        if (seg !== "..")
+            parts.push(seg);
+    }
+    return parts;
+}
+export function sanitizePathSplit(path, out) {
+    const parts = out ?? [];
+    let segStart = 0;
+    let i = 0;
+    const len = path.length;
+    while (i < len) {
+        const code = path.charCodeAt(i);
+        if (code === 47 || code === 92) {
+            if (segStart < i) {
+                const seg = path.slice(segStart, i);
+                if (seg !== "..")
+                    parts.push(seg);
+            }
+            segStart = i + 1;
+        }
+        i++;
+    }
+    if (segStart < len) {
+        const seg = path.slice(segStart, len);
+        if (seg !== "..")
+            parts.push(seg);
+    }
+    return parts;
+}
+export function sanitized(title) {
+    const len = title.length;
+    let result = "";
+    let dash = false;
+    for (let i = 0; i < len; i++) {
+        let ch = title.charCodeAt(i);
+        if (ch >= 65 && ch <= 90)
+            ch += 32;
+        if ((ch >= 97 && ch <= 122) || (ch >= 48 && ch <= 57) || ch === 46) {
+            result += String.fromCharCode(ch);
+            dash = false;
+        }
+        else if (ch === 32 || ch === 95 || ch === 45) {
+            if (!dash && result.length > 0) {
+                result += "-";
+                dash = true;
+            }
+        }
+    }
+    return result.endsWith("-") ? result.slice(0, -1) : result;
+}

package/utils/mimeTypes.d.ts

@@ -0,0 +1,4 @@
+export declare const mimeTypes: {
+    [key: string]: string;
+};
+export declare const defaultMimeType = "application/octet-stream";

package/utils/{staticFile.js → mimeTypes.js}

@@ -1,4 +1,3 @@
-import { Environment } from "../core/environment.js";
 export const mimeTypes = {
     html: "text/html",
     htm: "text/html",
@@ -103,55 +102,3 @@ export const mimeTypes = {
     gcode: "text/x.gcode",
 };
 export const defaultMimeType = "application/octet-stream";
-export async function getFiles(dir, basePath = "/", ref, option) {
-    const files = [];
-    const runtime = Environment.getEnvironment;
-    if (runtime == "deno") {
-        for await (const entry of Deno.readDir(dir)) {
-            const path = `${dir}/${entry.name}`;
-            if (entry.isDirectory) {
-                files.push(...(await getFiles(path, `${basePath}/${entry.name}`, ref, option)));
-            }
-            else {
-                const x = `${basePath}/${entry.name}`;
-                files.push({
-                    file: path,
-                    path: x.replace(/\\/g, "/"),
-                });
-            }
-        }
-    }
-    else {
-        const fs = await import("node:fs/promises");
-        const path = await import("node:path");
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                files.push(...(await getFiles(fullPath, `${basePath}/${entry.name}`, ref, option)));
-            }
-            else {
-                const path = `${basePath}/${entry.name}`;
-                files.push({
-                    file: fullPath,
-                    path: path.replace(/\\/g, "/"),
-                });
-            }
-        }
-    }
-    files.forEach((r) => {
-        ref.get(r.path, (ctx) => {
-            if (option.cacheControl) {
-                ctx.headers.set("Cache-Control", option.cacheControl);
-            }
-            if (option.headers) {
-                for (const key in option.headers) {
-                    let value = option.headers?.[key];
-                    ctx.headers.set(key, value);
-                }
-            }
-            return ctx.sendFile(r.file);
-        });
-    });
-    return files;
-}

package/utils/rateLimit.d.ts

@@ -0,0 +1,18 @@
+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(key: string, store: any, maxRequests: number, windowMs: number): {
+    check: boolean;
+    entry: any;
+};

package/utils/rateLimit.js

@@ -0,0 +1,37 @@
+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(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/utils/response.d.ts

@@ -0,0 +1,18 @@
+import { Context } from "../core/context.js";
+import { TezXError } from "../core/error.js";
+import { HttpBaseResponse } from "../types/index.js";
+export declare let notFoundResponse: (ctx: Context) => HttpBaseResponse;
+export declare function handleErrorResponse(err: TezXError | undefined, ctx: Context): Promise<HttpBaseResponse>;
+/**
+ * Converts a template literal array and values into a single string.
+ * If a plain string is passed, it returns the string itself.
+ *
+ * @param input - A string or a template literal array.
+ * @param values - Values for template literal placeholders.
+ * @returns Concatenated string.
+ */
+export declare function toString(input: string | readonly string[], values: any[]): string;
+export declare function determineContentTypeBody(body: any): {
+    type: string;
+    body: any;
+};

package/utils/response.js

@@ -0,0 +1,58 @@
+import { GlobalConfig } from "../core/config.js";
+import { TezXError } from "../core/error.js";
+export let notFoundResponse = (ctx) => {
+    const { method, pathname } = ctx;
+    return ctx.text(`${method}: '${pathname}' could not find\n`, {
+        status: 404,
+    });
+};
+export async function handleErrorResponse(err = TezXError.internal(), ctx) {
+    if (err instanceof TezXError) {
+        GlobalConfig.debugging.error(err.details ?? err?.message);
+        return ctx
+            .status(err.statusCode ?? 500)
+            .send(err.details ?? err?.message ?? "Internal Server Error");
+    }
+    return await handleErrorResponse(TezXError.internal(), ctx);
+}
+export function toString(input, values) {
+    if (typeof input === "string") {
+        return input;
+    }
+    let result = "";
+    for (let i = 0; i < input.length; i++) {
+        result += input[i];
+        if (i < values.length)
+            result += values[i];
+    }
+    return result;
+}
+export function determineContentTypeBody(body) {
+    if (typeof body === "string" ||
+        typeof body === "number" ||
+        typeof body === "boolean") {
+        return { type: "text/plain; charset=utf-8", body: String(body) };
+    }
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+        return { type: "application/octet-stream", body };
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(body)) {
+        return { type: "application/octet-stream", body };
+    }
+    if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) {
+        return { type: "application/octet-stream", body };
+    }
+    if (typeof Blob !== "undefined" && body instanceof Blob) {
+        return { type: body.type || "application/octet-stream", body };
+    }
+    if (typeof body === "object" && typeof body?.pipe === "function") {
+        return { type: "application/octet-stream", body };
+    }
+    if (typeof body === "object") {
+        return {
+            type: "application/json; charset=utf-8",
+            body: JSON.stringify(body),
+        };
+    }
+    return { type: "text/plain; charset=utf-8", body: String(body ?? "") };
+}

package/{core/environment.d.ts → utils/runtime.d.ts}

@@ -1,3 +1,4 @@
 export declare class Environment {
     static get getEnvironment(): "node" | "bun" | "deno" | "unknown";
 }
+export declare const runtime: "node" | "bun" | "deno" | "unknown";

package/{core/environment.js → utils/runtime.js}

@@ -9,3 +9,4 @@ export class Environment {
         return "unknown";
     }
 }
+export const runtime = Environment.getEnvironment;