@shohaghinfo/aerojs 0.1.0

package/dist/response.js

@@ -0,0 +1,375 @@
+/**
+ * @file response.ts
+ * @description AeroResponse wrapper around Node.js ServerResponse.
+ */
+import { Readable } from 'node:stream';
+/**
+ * Wrapper around Node.js `ServerResponse` providing a chainable,
+ * developer-friendly API for headers, status codes, cookies, and body transmission.
+ */
+export class AeroResponse {
+    /**
+     * Underlying Node.js ServerResponse instance.
+     */
+    raw;
+    /**
+     * Internal marker to check whether the response payload has been dispatched.
+     */
+    _isSent = false;
+    /**
+     * Cached response body payload before serialization and final transmission.
+     */
+    _bodyPayload = undefined;
+    /**
+     * List of set cookies to be written to headers.
+     */
+    _cookieHeaders = [];
+    /**
+     * Flag indicating if the current request is a HEAD request.
+     */
+    isHead = false;
+    /**
+     * Custom serializer function (custom fast-json-stringify or schema-based).
+     */
+    serializer;
+    /**
+     * Custom decorator storage for plugin and application extensions.
+     */
+    customProperties = new Map();
+    /**
+     * Creates an instance of AeroResponse.
+     *
+     * @param raw - The underlying Node.js ServerResponse.
+     */
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /**
+     * Returns whether HTTP response headers have already been sent to the client.
+     */
+    get headersSent() {
+        return this.raw.headersSent;
+    }
+    /**
+     * Returns whether the response has finished sending.
+     */
+    get isSent() {
+        return this._isSent || this.raw.writableEnded;
+    }
+    /**
+     * Returns the current HTTP status code.
+     */
+    get statusCode() {
+        return this.raw.statusCode;
+    }
+    /**
+     * Sets the HTTP status code (chainable).
+     *
+     * @param code - HTTP status code (e.g. 200, 404).
+     * @returns this
+     */
+    status(code) {
+        this.raw.statusCode = code;
+        return this;
+    }
+    /**
+     * Sets one or more HTTP response headers (chainable).
+     *
+     * @param nameOrHeaders - Header name or key-value object of headers.
+     * @param value - Header value when first argument is a header name.
+     * @returns this
+     */
+    set(nameOrHeaders, value) {
+        if (this.raw.headersSent) {
+            return this;
+        }
+        if (typeof nameOrHeaders === 'string') {
+            if (value !== undefined) {
+                this.raw.setHeader(nameOrHeaders, value);
+            }
+        }
+        else if (typeof nameOrHeaders === 'object' && nameOrHeaders !== null) {
+            for (const [key, val] of Object.entries(nameOrHeaders)) {
+                if (val !== undefined) {
+                    this.raw.setHeader(key, val);
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * Retrieves a previously queued or set response header.
+     *
+     * @param name - Header name.
+     * @returns Header value or undefined.
+     */
+    get(name) {
+        return this.raw.getHeader(name);
+    }
+    /**
+     * Removes a queued response header.
+     *
+     * @param name - Header name to remove.
+     * @returns this
+     */
+    removeHeader(name) {
+        if (!this.raw.headersSent) {
+            this.raw.removeHeader(name);
+        }
+        return this;
+    }
+    /**
+     * Sets the `Content-Type` header (chainable).
+     *
+     * @param contentType - MIME type (e.g., 'application/json', 'text/html').
+     * @returns this
+     */
+    type(contentType) {
+        let type = contentType;
+        if (type === 'json')
+            type = 'application/json; charset=utf-8';
+        else if (type === 'html')
+            type = 'text/html; charset=utf-8';
+        else if (type === 'text')
+            type = 'text/plain; charset=utf-8';
+        return this.set('Content-Type', type);
+    }
+    /**
+     * Sets a cookie on the response using the `Set-Cookie` header.
+     *
+     * @param name - Cookie name.
+     * @param value - Cookie string value.
+     * @param options - Cookie configuration options.
+     * @returns this
+     */
+    cookie(name, value, options = {}) {
+        const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+        const path = options.path ?? '/';
+        parts.push(`Path=${path}`);
+        if (options.maxAge !== undefined) {
+            parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+        }
+        if (options.domain) {
+            parts.push(`Domain=${options.domain}`);
+        }
+        if (options.expires) {
+            parts.push(`Expires=${options.expires.toUTCString()}`);
+        }
+        if (options.httpOnly) {
+            parts.push('HttpOnly');
+        }
+        if (options.secure) {
+            parts.push('Secure');
+        }
+        if (options.sameSite) {
+            const sameSiteValue = typeof options.sameSite === 'string'
+                ? options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1).toLowerCase()
+                : 'Lax';
+            parts.push(`SameSite=${sameSiteValue}`);
+        }
+        const cookieStr = parts.join('; ');
+        this._cookieHeaders.push(cookieStr);
+        this.raw.setHeader('Set-Cookie', this._cookieHeaders);
+        return this;
+    }
+    /**
+     * Clears a cookie by expiring it immediately.
+     *
+     * @param name - Cookie name.
+     * @param options - Cookie options (path and domain should match original cookie).
+     * @returns this
+     */
+    clearCookie(name, options = {}) {
+        return this.cookie(name, '', {
+            ...options,
+            expires: new Date(0),
+            maxAge: 0,
+        });
+    }
+    /**
+     * Redirects the client to the specified URL.
+     *
+     * @param url - Destination URL.
+     * @param status - HTTP redirect status code (defaults to 302).
+     */
+    redirect(url, status = 302) {
+        this.status(status);
+        this.set('Location', url);
+        this.type('text/plain; charset=utf-8');
+        this.send(`Redirecting to ${url}`);
+    }
+    /**
+     * Sends a JSON response with proper Content-Type.
+     *
+     * @param data - Object, array, or primitive to serialize as JSON.
+     */
+    json(data) {
+        if (!this.raw.getHeader('Content-Type')) {
+            this.type('application/json; charset=utf-8');
+        }
+        const payload = this.serializer ? this.serializer(data) : JSON.stringify(data);
+        this.send(payload);
+    }
+    /**
+     * Sends a plain text response.
+     *
+     * @param data - Text content to send.
+     */
+    text(data) {
+        if (!this.raw.getHeader('Content-Type')) {
+            this.type('text/plain; charset=utf-8');
+        }
+        this.send(String(data));
+    }
+    /**
+     * Sends an HTML response.
+     *
+     * @param data - HTML markup string.
+     */
+    html(data) {
+        if (!this.raw.getHeader('Content-Type')) {
+            this.type('text/html; charset=utf-8');
+        }
+        this.send(data);
+    }
+    /**
+     * Automatically determines content type and transmits data.
+     *
+     * - null / undefined: 204 No Content
+     * - Buffer: application/octet-stream
+     * - Stream: pipes stream directly
+     * - String: text/html or text/plain
+     * - Object: application/json
+     *
+     * @param data - Payload data.
+     */
+    send(data) {
+        if (this._isSent || this.raw.writableEnded) {
+            return;
+        }
+        this._bodyPayload = data;
+        // Handle null or undefined
+        if (data === null || data === undefined) {
+            if (!this.raw.statusCode || this.raw.statusCode === 200) {
+                this.status(204);
+            }
+            this.raw.removeHeader('Content-Type');
+            this.raw.removeHeader('Content-Length');
+            this.flushEnd();
+            return;
+        }
+        // Handle Stream (e.g. fs.createReadStream)
+        if (data instanceof Readable) {
+            this._isSent = true;
+            if (!this.raw.getHeader('Content-Type')) {
+                this.type('application/octet-stream');
+            }
+            if (this.isHead) {
+                this.raw.end();
+            }
+            else {
+                data.pipe(this.raw);
+            }
+            return;
+        }
+        // Handle Buffer
+        if (Buffer.isBuffer(data)) {
+            if (!this.raw.getHeader('Content-Type')) {
+                this.type('application/octet-stream');
+            }
+            this.set('Content-Length', Buffer.byteLength(data));
+            this.flushEnd(data);
+            return;
+        }
+        // Handle String
+        if (typeof data === 'string') {
+            if (!this.raw.getHeader('Content-Type')) {
+                const trimmed = data.trim();
+                if (trimmed.startsWith('<') && trimmed.endsWith('>')) {
+                    this.type('text/html; charset=utf-8');
+                }
+                else {
+                    this.type('text/plain; charset=utf-8');
+                }
+            }
+            const buffer = Buffer.from(data, 'utf-8');
+            this.set('Content-Length', buffer.length);
+            this.flushEnd(buffer);
+            return;
+        }
+        // Handle Number / Boolean / BigInt
+        if (typeof data === 'number' || typeof data === 'boolean' || typeof data === 'bigint') {
+            const str = String(data);
+            if (!this.raw.getHeader('Content-Type')) {
+                this.type('text/plain; charset=utf-8');
+            }
+            const buffer = Buffer.from(str, 'utf-8');
+            this.set('Content-Length', buffer.length);
+            this.flushEnd(buffer);
+            return;
+        }
+        // Handle Object / Array
+        if (typeof data === 'object') {
+            if (!this.raw.getHeader('Content-Type')) {
+                this.type('application/json; charset=utf-8');
+            }
+            const serialized = this.serializer ? this.serializer(data) : JSON.stringify(data);
+            const buffer = Buffer.from(serialized, 'utf-8');
+            this.set('Content-Length', buffer.length);
+            this.flushEnd(buffer);
+            return;
+        }
+        // Fallback
+        const str = String(data);
+        const buffer = Buffer.from(str, 'utf-8');
+        this.set('Content-Length', buffer.length);
+        this.flushEnd(buffer);
+    }
+    /**
+     * Finalizes the HTTP response output.
+     *
+     * @param chunk - Optional final data chunk.
+     */
+    flushEnd(chunk) {
+        this._isSent = true;
+        if (this.isHead) {
+            this.raw.end();
+        }
+        else if (chunk !== undefined) {
+            this.raw.end(chunk);
+        }
+        else {
+            this.raw.end();
+        }
+    }
+    /**
+     * Retrieves the raw unsent or sent payload.
+     */
+    get payload() {
+        return this._bodyPayload;
+    }
+    /**
+     * Sets or overrides the response payload.
+     */
+    set payload(val) {
+        this._bodyPayload = val;
+    }
+    /**
+     * Retrieves a custom decorator property.
+     *
+     * @param key - Name of the decorated property.
+     */
+    getCustom(key) {
+        return this.customProperties.get(key);
+    }
+    /**
+     * Sets a custom decorator property.
+     *
+     * @param key - Name of the decorated property.
+     * @param value - Value to associate with the key.
+     */
+    setCustom(key, value) {
+        this.customProperties.set(key, value);
+    }
+}
+//# sourceMappingURL=response.js.map

package/dist/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"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"}

package/dist/router.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @file router.ts
+ * @description Radix Tree routing engine supporting route params, wildcards, and method matching.
+ */
+import type { DefaultState } from './context.js';
+import type { Middleware } from './middleware.js';
+/**
+ * Route definition holding method, pattern, handlers, and optional schema.
+ */
+export interface Route<State = DefaultState> {
+    /**
+     * HTTP method (e.g., 'GET', 'POST', 'ALL').
+     */
+    readonly method: string;
+    /**
+     * Original registered path pattern.
+     */
+    readonly path: string;
+    /**
+     * Middleware handler stack for this route.
+     */
+    readonly handlers: readonly Middleware<State>[];
+    /**
+     * Optional JSON Schema validation definitions.
+     */
+    readonly schema?: RouteSchema;
+}
+/**
+ * Route schema for request validation and response serialization.
+ */
+export interface RouteSchema {
+    body?: unknown;
+    query?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<string | number, unknown>;
+}
+/**
+ * Route matching result containing the matched route, params, and handlers.
+ */
+export interface RouteMatch<State = DefaultState> {
+    /**
+     * The matched route definition.
+     */
+    readonly route: Route<State>;
+    /**
+     * Extracted path parameter dictionary.
+     */
+    readonly params: Record<string, string>;
+    /**
+     * Resolved handlers to execute.
+     */
+    readonly handlers: readonly Middleware<State>[];
+}
+/**
+ * Normalizes a URL path by stripping trailing slashes while preserving root `/`.
+ *
+ * @param path - Input URL path.
+ * @returns Normalized URL path.
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Chainable route builder for configuring multiple HTTP methods on a single path.
+ */
+export declare class RouteChain<State = DefaultState> {
+    private readonly router;
+    private readonly path;
+    constructor(router: Router<State>, path: string);
+    get(...handlers: Middleware<State>[]): this;
+    post(...handlers: Middleware<State>[]): this;
+    put(...handlers: Middleware<State>[]): this;
+    patch(...handlers: Middleware<State>[]): this;
+    delete(...handlers: Middleware<State>[]): this;
+    all(...handlers: Middleware<State>[]): this;
+    options(...handlers: Middleware<State>[]): this;
+    head(...handlers: Middleware<State>[]): this;
+}
+/**
+ * High-performance Radix Tree router supporting route parameters,
+ * wildcards, trailing-slash normalization, and 405 Method Not Allowed discovery.
+ */
+export declare class Router<State = DefaultState> {
+    private readonly root;
+    private readonly allRoutes;
+    /**
+     * Registers a new route in the Radix Tree.
+     *
+     * @param method - HTTP method (e.g., 'GET', 'POST', 'ALL').
+     * @param path - URL pattern (e.g., '/users/:id/posts/:postId').
+     * @param handlers - One or more middleware handlers.
+     * @returns this
+     */
+    add(method: string, path: string, handlers: Middleware<State>[], schema?: RouteSchema): this;
+    /**
+     * Matches an incoming HTTP request method and path against the Radix Tree.
+     *
+     * @param method - HTTP method.
+     * @param path - URL pathname.
+     * @returns RouteMatch or null if no route matches.
+     */
+    match(method: string, path: string): RouteMatch<State> | null;
+    /**
+     * Checks whether ANY route is registered for the specified path,
+     * regardless of the HTTP method (used for 405 Method Not Allowed detection).
+     *
+     * @param path - URL pathname.
+     * @returns True if at least one route matches the path.
+     */
+    hasPath(path: string): boolean;
+    /**
+     * Retrieves all HTTP methods registered for a given path.
+     *
+     * @param path - URL pathname.
+     * @returns Array of allowed HTTP method strings.
+     */
+    allowedMethods(path: string): string[];
+    /**
+     * Recursively traverses the Radix Tree matching static, param, and wildcard segments.
+     */
+    private searchNode;
+    /**
+     * Registers a sub-router with a URL prefix.
+     *
+     * @param prefix - Base path prefix (e.g., '/api/v1').
+     * @param subRouter - Router instance to mount.
+     * @returns this
+     */
+    mount(prefix: string, subRouter: Router<State>): this;
+    /**
+     * Creates a chainable RouteChain for configuring handlers on a path.
+     *
+     * @param path - URL path.
+     * @returns RouteChain instance.
+     */
+    route(path: string): RouteChain<State>;
+    get(path: string, ...handlers: Middleware<State>[]): this;
+    post(path: string, ...handlers: Middleware<State>[]): this;
+    put(path: string, ...handlers: Middleware<State>[]): this;
+    patch(path: string, ...handlers: Middleware<State>[]): this;
+    delete(path: string, ...handlers: Middleware<State>[]): this;
+    all(path: string, ...handlers: Middleware<State>[]): this;
+    options(path: string, ...handlers: Middleware<State>[]): this;
+    head(path: string, ...handlers: Middleware<State>[]): this;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}