@lithia-js/core 1.0.0-canary.0

package/dist/lithia.d.ts

@@ -0,0 +1,447 @@
+/**
+ * Core runtime entry for Lithia.
+ *
+ * This module provides the main `Lithia` class, which orchestrates the entire
+ * framework lifecycle including:
+ * - Building the project with the native Rust compiler
+ * - Loading route and event manifests
+ * - Managing the HTTP server lifecycle
+ * - Configuration management and hot-reloading
+ * - Dependency injection and global middleware
+ * - Lifecycle event emission (built, error, config:changed)
+ *
+ * @module lithia
+ */
+import { EventEmitter } from "node:events";
+import { type Event, type Route } from "@lithia-js/native";
+import { type LithiaOptions } from "./config";
+import type { InjectionKey } from "./hooks/dependency-hooks";
+import type { LithiaMiddleware } from "./server/request-processor";
+/**
+ * The runtime environment mode.
+ *
+ * Influences logging verbosity, error output formatting, and features like
+ * configuration hot-reloading (enabled only in development).
+ */
+export type Environment = "production" | "development";
+/**
+ * Options required to create a Lithia instance.
+ *
+ * These options configure the fundamental paths and environment settings
+ * that Lithia needs to build and run your application.
+ */
+export interface LithiaCreateOptions {
+    /**
+     * Runtime environment mode.
+     *
+     * - `development`: Enables config watching, verbose logging, source maps
+     * - `production`: Optimized for performance with minimal logging
+     */
+    environment: Environment;
+    /**
+     * Absolute path to the source directory containing application code.
+     *
+     * @example "./src"
+     */
+    sourceRoot: string;
+    /**
+     * Absolute path to the output directory for compiled JavaScript.
+     *
+     * @example "./dist"
+     */
+    outRoot: string;
+}
+/**
+ * Lithia runtime controller and main framework orchestrator.
+ *
+ * This is the core class that manages the entire Lithia application lifecycle.
+ * It acts as a singleton and coordinates:
+ * - Project compilation via the native Rust builder
+ * - Route and event manifest loading
+ * - HTTP server lifecycle management
+ * - Configuration management with hot-reloading in development
+ * - Global middleware and dependency injection
+ * - Lifecycle event emission and handling
+ *
+ * @remarks
+ * Always use `Lithia.create()` to obtain the singleton instance.
+ * Direct instantiation is not supported.
+ *
+ * @example
+ * ```typescript
+ * const lithia = await Lithia.create({
+ *   environment: 'development',
+ *   sourceRoot: './src',
+ *   outRoot: './dist'
+ * });
+ *
+ * lithia.build();
+ * await lithia.start();
+ * ```
+ */
+export declare class Lithia {
+    /** Singleton instance of Lithia. */
+    private static instance;
+    /** Current runtime environment (production or development). */
+    private environment;
+    /** Absolute path to the source directory. */
+    private sourceRoot;
+    /** Absolute path to the compiled output directory. */
+    private outRoot;
+    /** Array of loaded application routes from the manifest. */
+    private routes;
+    /** Array of loaded Socket.IO events from the manifest. */
+    private events;
+    /** Current runtime configuration. */
+    private config;
+    /** Event emitter for lifecycle events (built, error, config:changed). */
+    private emitter;
+    /** Configuration provider that handles loading and watching. */
+    private configProvider;
+    /** HTTP server instance (created when start() is called). */
+    private httpServer?;
+    /** Flag indicating whether the HTTP server is currently running. */
+    private serverRunning;
+    /** Handle for the configuration file watcher (development only). */
+    private configWatchHandle?;
+    /**
+     * Global middlewares executed for every HTTP request.
+     *
+     * These run before route-specific handlers and can modify requests,
+     * responses, or perform authentication/logging.
+     */
+    globalMiddlewares: LithiaMiddleware[];
+    /**
+     * Global dependency injection container.
+     *
+     * Stores dependencies registered via `provide()` that can be injected
+     * into route handlers and middlewares.
+     */
+    globalDependencies: Map<any, any>;
+    /**
+     * Gets the current runtime configuration.
+     *
+     * @returns The current LithiaOptions configuration object
+     */
+    get options(): LithiaOptions;
+    /**
+     * Private constructor to enforce singleton pattern.
+     *
+     * Use `Lithia.create()` instead of instantiating directly.
+     *
+     * @private
+     */
+    private constructor();
+    /**
+     * Creates or returns the global Lithia singleton instance.
+     *
+     * This is the primary entry point for creating a Lithia application.
+     * On first call, it initializes the framework with the provided options,
+     * loads configuration, and (in development mode) sets up configuration
+     * hot-reloading.
+     *
+     * Subsequent calls return the same singleton instance.
+     *
+     * @param options - Configuration for paths and environment
+     * @returns The initialized Lithia singleton instance
+     *
+     * @example
+     * ```typescript
+     * const lithia = await Lithia.create({
+     *   environment: 'development',
+     *   sourceRoot: path.resolve('./src'),
+     *   outRoot: path.resolve('./dist')
+     * });
+     * ```
+     */
+    static create(options: LithiaCreateOptions): Promise<Lithia>;
+    /**
+     * Registers a global middleware to run on every HTTP request.
+     *
+     * Middlewares are executed in the order they are registered, before
+     * route-specific handlers. They can modify the request/response or
+     * perform cross-cutting concerns like logging and authentication.
+     *
+     * @param middleware - The middleware function to register
+     * @returns The Lithia instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * lithia.use(async (req, res, next) => {
+     *   console.log(`${req.method} ${req.url}`);
+     *   await next();
+     * });
+     * ```
+     */
+    use(middleware: LithiaMiddleware): this;
+    /**
+     * Registers a global dependency for dependency injection.
+     *
+     * Registered dependencies can be injected into route handlers and
+     * middlewares using the `inject()` hook.
+     *
+     * @param key - The injection key (use `createInjectionKey<T>()` to create)
+     * @param value - The dependency value to provide
+     * @returns The Lithia instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const dbKey = createInjectionKey<Database>('database');
+     * lithia.provide(dbKey, new Database());
+     * ```
+     */
+    provide<T>(key: InjectionKey<T>, value: T): this;
+    /**
+     * Initializes the Lithia instance with configuration and environment settings.
+     *
+     * This method:
+     * - Sets up the environment, source root, and output root
+     * - Loads the initial configuration from lithia.config.ts
+     * - Configures the event emitter for lifecycle events
+     * - Sets up configuration hot-reloading (development mode only)
+     *
+     * @param options - Initialization options
+     * @private
+     */
+    private initialize;
+    /**
+     * Sets up configuration file watching in development mode.
+     *
+     * Monitors lithia.config.ts for changes and emits `config:changed` events.
+     * Logs configuration diffs and warns when changes require a server restart.
+     *
+     * @private
+     */
+    private setupConfigWatcher;
+    /**
+     * Checks if a configuration key change requires a server restart.
+     *
+     * @param key - The configuration key that changed
+     * @returns True if the change requires restarting the server
+     * @private
+     */
+    private configChangeRequiresRestart;
+    /**
+     * Loads and executes the optional user bootstrap module.
+     *
+     * Looks for `src/app/_server.ts` (compiled to `dist/app/_server.js`).
+     * The bootstrap module should export an async default function that
+     * receives the Lithia instance and can register middlewares, providers, etc.
+     *
+     * @throws {InvalidBootstrapModuleError} If the module has invalid structure
+     * @private
+     */
+    private loadBootstrapModule;
+    /**
+     * Validates the structure of the bootstrap module.
+     *
+     * Ensures the module:
+     * - Has a default export
+     * - Default export is a function
+     * - Default export is async
+     *
+     * @param mod - The loaded module
+     * @param filePath - Path to the module file (for error messages)
+     * @throws {InvalidBootstrapModuleError} If validation fails
+     * @private
+     */
+    private validateBootstrapModule;
+    /**
+     * Starts the HTTP server.
+     *
+     * This method:
+     * 1. Loads and executes the optional bootstrap module (_server.ts)
+     * 2. Creates the HTTP server with current configuration
+     * 3. Starts listening on the configured host and port
+     *
+     * Safe to call multiple times; subsequent calls are no-ops while the
+     * server is running.
+     *
+     * @throws {InvalidBootstrapModuleError} If bootstrap module is invalid
+     * @throws {Error} If server fails to start
+     *
+     * @example
+     * ```typescript
+     * await lithia.start();
+     * // Server is now listening on configured port
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the HTTP server.
+     *
+     * Gracefully shuts down the server and closes all active connections.
+     * No-op if the server isn't currently running.
+     *
+     * @example
+     * ```typescript
+     * await lithia.stop();
+     * // Server is now stopped
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Executes a function within the Lithia context.
+     *
+     * Provides access to the global dependency container during execution.
+     * Used internally by the request processor to make dependencies available
+     * to route handlers and middlewares.
+     *
+     * @param fn - Async function to execute within the context
+     * @returns The result of the function execution
+     * @template T - The return type of the function
+     *
+     * @example
+     * ```typescript
+     * const result = await lithia.runWithContext(async () => {
+     *   const db = inject(dbKey);
+     *   return db.query('SELECT * FROM users');
+     * });
+     * ```
+     */
+    runWithContext<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Gets the current runtime environment.
+     *
+     * @returns The environment mode ('production' or 'development')
+     */
+    getEnvironment(): Environment;
+    /**
+     * Gets the currently loaded routes from the manifest.
+     *
+     * Routes are loaded after a successful build via the `loadRoutes()` method.
+     *
+     * @returns Array of route definitions
+     */
+    getRoutes(): Route[];
+    /**
+     * Gets the currently loaded Socket.IO events from the manifest.
+     *
+     * Events are loaded after a successful build via the `loadEvents()` method.
+     *
+     * @returns Array of event definitions
+     */
+    getEvents(): Event[];
+    /**
+     * Gets the current runtime configuration.
+     *
+     * @returns The current LithiaOptions configuration object
+     */
+    getConfig(): LithiaOptions;
+    /**
+     * Configures internal event handlers for the lifecycle emitter.
+     *
+     * Sets up handlers for:
+     * - `built` event: Triggered after successful compilation, loads routes and events
+     * - `error` event: Logs errors with appropriate severity and exits on fatal errors
+     *
+     * @private
+     */
+    private configureEventEmitter;
+    /**
+     * Compiles the project using the native Rust compiler.
+     *
+     * This performs a synchronous build that:
+     * - Scans the source directory for routes and events
+     * - Compiles TypeScript to JavaScript
+     * - Generates route and event manifests (routes.json, events.json)
+     *
+     * On success, emits the `built` event with build duration in milliseconds.
+     * On failure, emits the `error` event.
+     *
+     * @example
+     * ```typescript
+     * lithia.on('built', () => {
+     *   console.log('Build complete!');
+     * });
+     * lithia.build();
+     * ```
+     */
+    build(): void;
+    /**
+     * Loads and validates a JSON manifest file.
+     *
+     * @param fileName - Name of the manifest file (e.g., 'routes.json')
+     * @returns The parsed manifest object
+     * @throws {ManifestLoadError} If the file cannot be read or parsed
+     * @throws {SchemaVersionMismatchError} If the manifest version doesn't match
+     * @private
+     */
+    private loadManifest;
+    /**
+     * Loads and validates the routes manifest generated by the compiler.
+     *
+     * Reads `routes.json` from the output directory and populates the
+     * internal routes array. This is automatically called after a successful
+     * build (via the `built` event handler).
+     *
+     * On error, emits an `error` event and leaves routes unchanged.
+     */
+    loadRoutes(): void;
+    /**
+     * Loads and validates the events manifest generated by the compiler.
+     *
+     * Reads `events.json` from the output directory and populates the
+     * internal events array. This is automatically called after a successful
+     * build (via the `built` event handler).
+     *
+     * On error, emits an `error` event and leaves events unchanged.
+     */
+    loadEvents(): void;
+    /**
+     * Gets the internal EventEmitter instance.
+     *
+     * The event emitter is used for lifecycle events like:
+     * - `built`: Emitted after successful compilation
+     * - `error`: Emitted when errors occur
+     * - `config:changed`: Emitted when configuration is updated (dev mode)
+     *
+     * @returns The internal EventEmitter instance
+     */
+    getEventEmitter(): EventEmitter<any>;
+    /**
+     * Emits a lifecycle event.
+     *
+     * @param event - The event name to emit
+     * @param payload - Optional payload data for the event
+     * @returns True if the event had listeners, false otherwise
+     *
+     * @example
+     * ```typescript
+     * lithia.emit('custom:event', { data: 'value' });
+     * ```
+     */
+    emit(event: string, payload?: any): boolean;
+    /**
+     * Registers a listener for a lifecycle event.
+     *
+     * @param event - The event name to listen for
+     * @param listener - Callback function to execute when the event is emitted
+     *
+     * @example
+     * ```typescript
+     * lithia.on('built', (durationMs) => {
+     *   console.log(`Build took ${durationMs}ms`);
+     * });
+     *
+     * lithia.on('error', (error) => {
+     *   console.error('An error occurred:', error);
+     * });
+     * ```
+     */
+    on(event: string, listener: (...args: any[]) => void): void;
+    /**
+     * Cleans up resources and removes all event listeners.
+     *
+     * This method should be called when shutting down the application to:
+     * - Close the configuration file watcher
+     * - Remove all event listeners to prevent memory leaks
+     *
+     * @example
+     * ```typescript
+     * await lithia.stop();
+     * lithia.close();
+     * ```
+     */
+    close(): void;
+}