@shohaghinfo/aerojs 0.1.0

package/bin/aero.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * AeroJS Command-Line Interface Executable
+ */
+
+async function main() {
+  let AeroCLI;
+  try {
+    const mod = await import('../dist/cli/runner.js');
+    AeroCLI = mod.AeroCLI;
+  } catch {
+    const mod = await import('../src/cli/runner.js');
+    AeroCLI = mod.AeroCLI;
+  }
+
+  const exitCode = await AeroCLI.run(process.argv.slice(2));
+  process.exit(exitCode);
+}
+
+main().catch((err) => {
+  console.error('Fatal CLI Error:', err);
+  process.exit(1);
+});

package/dist/application.d.ts

@@ -0,0 +1,251 @@
+/**
+ * @file application.ts
+ * @description Main Aero framework application class orchestrating request lifecycle,
+ * routing, middleware composition, lifecycle hooks, and plugin registration.
+ */
+import { type Server, type IncomingMessage, type ServerResponse, type RequestListener } from 'node:http';
+import { AeroContext, type DefaultState } from './context.js';
+import { type Middleware } from './middleware.js';
+import { Router, type RouteSchema } from './router.js';
+import { type HookName, type HookMap } from './hooks.js';
+/**
+ * Global configuration options for an Aero application instance.
+ */
+export interface AeroOptions {
+    /**
+     * If true, includes error stack traces in error responses.
+     */
+    debug?: boolean;
+    /**
+     * Disables Aero's built-in 404 handler when no route matches.
+     */
+    disableDefault404?: boolean;
+    /**
+     * Maximum allowed body size in bytes (defaults to 1MB).
+     */
+    bodyLimit?: number;
+    /**
+     * Whether to trust proxy headers (X-Forwarded-For, X-Forwarded-Proto).
+     */
+    trustProxy?: boolean;
+}
+/**
+ * Custom error handler callback signature.
+ */
+export type ErrorHandler<State = DefaultState> = (error: Error, ctx: AeroContext<State>) => void | Promise<void>;
+/**
+ * Plugin function signature for extending Aero instances.
+ */
+export type AeroPlugin<State = DefaultState> = (app: Aero<State>, options?: Record<string, unknown>) => void | Promise<void>;
+/**
+ * Validation error details describing a schema discrepancy.
+ */
+export interface ValidationErrorDetail {
+    keyword: string;
+    dataPath: string;
+    message: string;
+}
+/**
+ * Performs lightweight JSON Schema validation without external dependencies.
+ *
+ * @param schema - JSON Schema definition.
+ * @param data - Target payload to validate.
+ * @param path - Current schema traversal path.
+ * @returns Array of validation errors if invalid, empty array if valid.
+ */
+export declare function validateSchema(schema: unknown, data: unknown, path?: string): ValidationErrorDetail[];
+/**
+ * Builds a fast JSON serializer for a response schema.
+ *
+ * @param schema - Response JSON schema.
+ * @returns Optimized serializer function.
+ */
+export declare function compileFastSerializer(schema?: unknown): (data: unknown) => string;
+/**
+ * Main application class in Aero.
+ */
+export declare class Aero<State = DefaultState> {
+    /**
+     * Internal configuration options.
+     */
+    readonly config: AeroOptions;
+    /**
+     * Global middleware stack.
+     */
+    private readonly middlewares;
+    /**
+     * Internal Radix Tree router.
+     */
+    private readonly router;
+    /**
+     * Lifecycle hooks store.
+     */
+    private readonly hooks;
+    /**
+     * Custom application error handler.
+     */
+    private customErrorHandler?;
+    /**
+     * Active HTTP server instance when listening.
+     */
+    private server?;
+    /**
+     * Application-level custom decorator store.
+     */
+    private readonly customDecorators;
+    /**
+     * Request-level decorator prototypes.
+     */
+    private readonly requestDecorators;
+    /**
+     * Response-level decorator prototypes.
+     */
+    private readonly replyDecorators;
+    /**
+     * Cached composed global middleware.
+     */
+    private composedGlobalMiddleware?;
+    /**
+     * Creates a new Aero application instance.
+     *
+     * @param options - Application configuration options.
+     */
+    constructor(options?: AeroOptions);
+    /**
+     * Registers a global middleware function or mounts a sub-router with a prefix.
+     *
+     * @param fnOrPrefix - Middleware function or URL prefix string.
+     * @param fnOrRouter - Middleware function or Router when first argument is a prefix.
+     * @returns this
+     */
+    use(fnOrPrefix: Middleware<State> | string, fnOrRouter?: Middleware<State> | Router<State>): this;
+    /**
+     * Adds an HTTP GET route.
+     */
+    get(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP POST route.
+     */
+    post(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP PUT route.
+     */
+    put(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP PATCH route.
+     */
+    patch(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP DELETE route.
+     */
+    delete(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds a route responding to all standard HTTP methods.
+     */
+    all(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP OPTIONS route.
+     */
+    options(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds an HTTP HEAD route.
+     */
+    head(path: string, ...handlers: Middleware<State>[]): this;
+    /**
+     * Adds a route with an explicit validation and serialization schema.
+     *
+     * @param method - HTTP method.
+     * @param path - URL pattern.
+     * @param schema - RouteSchema.
+     * @param handlers - Route handlers.
+     * @returns this
+     */
+    routeWithSchema(method: string, path: string, schema: RouteSchema, ...handlers: Middleware<State>[]): this;
+    /**
+     * Returns a chainable route builder for a given path.
+     *
+     * @param path - URL path.
+     * @returns RouteChain
+     */
+    route(path: string): import("./router.js").RouteChain<State>;
+    /**
+     * Registers a custom application error handler.
+     *
+     * @param handler - Error handler callback.
+     * @returns this
+     */
+    onError(handler: ErrorHandler<State>): this;
+    /**
+     * Registers a lifecycle hook.
+     *
+     * @param name - Hook name (e.g., 'onRequest', 'onSend').
+     * @param handler - Hook handler callback.
+     * @returns this
+     */
+    addHook<K extends HookName>(name: K, handler: HookMap<State>[K]): this;
+    /**
+     * Decorates the Aero application instance with a custom property or utility.
+     *
+     * @param name - Property name.
+     * @param value - Value or function.
+     * @returns this
+     */
+    decorate(name: string, value: unknown): this;
+    /**
+     * Decorates the request object for every incoming request.
+     *
+     * @param name - Property name.
+     * @param value - Value or factory.
+     * @returns this
+     */
+    decorateRequest(name: string, value: unknown): this;
+    /**
+     * Decorates the response object for every outgoing response.
+     *
+     * @param name - Property name.
+     * @param value - Value or factory.
+     * @returns this
+     */
+    decorateReply(name: string, value: unknown): this;
+    /**
+     * Registers a plugin with optional encapsulated configuration.
+     *
+     * @param plugin - Plugin function.
+     * @param options - Plugin options.
+     * @returns Promise resolving to this.
+     */
+    register(plugin: AeroPlugin<State>, options?: Record<string, unknown>): Promise<this>;
+    /**
+     * Handles an incoming Node.js HTTP request through the complete Aero pipeline.
+     *
+     * @param rawReq - Node.js IncomingMessage.
+     * @param rawRes - Node.js ServerResponse.
+     */
+    handleRequest(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+    /**
+     * Centralized error handler orchestrating onError hooks, custom error handlers,
+     * and uniform JSON error formatting.
+     *
+     * @param rawError - The error encountered during request processing.
+     * @param ctx - Active AeroContext.
+     */
+    private handleError;
+    /**
+     * Returns a standard Node.js request listener function `(req, res) => void`.
+     */
+    callback(): RequestListener;
+    /**
+     * Starts an HTTP server listening on the specified port and host.
+     *
+     * @param port - Port number (defaults to 3000).
+     * @param hostOrCallback - Hostname string or listening callback.
+     * @param callback - Listening callback if hostname is provided.
+     * @returns Running http.Server instance.
+     */
+    listen(port?: number, hostOrCallback?: string | (() => void), callback?: () => void): Server;
+    /**
+     * Gracefully shuts down the HTTP server.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=application.d.ts.map

package/dist/application.d.ts.map

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