@lithia-js/core 1.0.0-canary.0

package/dist/logger.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.Logger = void 0;
+const utils_1 = require("@lithia-js/utils");
+function formatMeta(meta) {
+    if (meta === undefined)
+        return "";
+    try {
+        if (typeof meta === "string")
+            return meta;
+        return JSON.stringify(meta);
+    }
+    catch {
+        return String(meta);
+    }
+}
+class Logger {
+    info(msg, meta) {
+        const m = formatMeta(meta);
+        console.log(`  ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    warn(msg, meta) {
+        const symbol = (0, utils_1.yellow)((0, utils_1.bold)("○"));
+        const m = formatMeta(meta);
+        console.warn(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    error(msg, meta) {
+        const symbol = (0, utils_1.red)((0, utils_1.bold)("○"));
+        const m = formatMeta(meta);
+        console.error(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    success(msg, meta) {
+        const symbol = (0, utils_1.green)((0, utils_1.bold)("▲"));
+        const m = formatMeta(meta);
+        console.log(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    event(msg, meta) {
+        const symbol = (0, utils_1.blue)((0, utils_1.bold)("▲"));
+        const m = formatMeta(meta);
+        console.log(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    debug(msg, meta) {
+        const symbol = (0, utils_1.white)((0, utils_1.bold)("»"));
+        const m = formatMeta(meta);
+        console.log(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+    wait(msg, meta) {
+        const symbol = (0, utils_1.white)((0, utils_1.bold)("○"));
+        const m = formatMeta(meta);
+        console.log(`${symbol} ${msg}${m ? ` — ${m}` : ""}`);
+    }
+}
+exports.Logger = Logger;
+exports.logger = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/module-loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Import a module dynamically, bypassing the cache in development.
+ * This is useful for hot-reloading routes and configuration files.
+ *
+ * @param filePath Absolute path to the file to import
+ * @param isDevelopment Whether to use cache-busting (dev) or native import (prod)
+ */
+export declare function coldImport<T = any>(filePath: string, isDevelopment: boolean): Promise<T>;
+/**
+ * Check if a value is an async function.
+ */
+export declare function isAsyncFunction(fn: unknown): boolean;

package/dist/module-loader.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coldImport = coldImport;
+exports.isAsyncFunction = isAsyncFunction;
+const node_url_1 = require("node:url");
+const import_fresh_1 = __importDefault(require("import-fresh"));
+/**
+ * Import a module dynamically, bypassing the cache in development.
+ * This is useful for hot-reloading routes and configuration files.
+ *
+ * @param filePath Absolute path to the file to import
+ * @param isDevelopment Whether to use cache-busting (dev) or native import (prod)
+ */
+async function coldImport(filePath, isDevelopment) {
+    let mod;
+    if (isDevelopment) {
+        // Use import-fresh in development for cache-free imports
+        // Note: import-fresh uses require() under the hood
+        mod = (0, import_fresh_1.default)(filePath);
+    }
+    else {
+        // Production: use normal dynamic import via file URL
+        const importUrl = (0, node_url_1.pathToFileURL)(filePath).href;
+        mod = await Promise.resolve(`${importUrl}`).then(s => __importStar(require(s)));
+    }
+    // Normalize CommonJS module structure
+    // When importing CommonJS via dynamic import or some bundlers, it can return:
+    // { default: { default: fn, ... } }
+    // We need to unwrap it to: { default: fn, ... }
+    if (mod.default && typeof mod.default === "object" && mod.default.default) {
+        return mod.default;
+    }
+    return mod;
+}
+const AsyncFunction = (async () => { }).constructor;
+/**
+ * Check if a value is an async function.
+ */
+function isAsyncFunction(fn) {
+    return fn instanceof AsyncFunction;
+}
+//# sourceMappingURL=module-loader.js.map

package/dist/module-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.js","sourceRoot":"","sources":["../src/module-loader.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA,gCAyBC;AAOD,0CAEC;AA5CD,uCAAyC;AACzC,gEAAuC;AAEvC;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAC/B,QAAgB,EAChB,aAAsB;IAEtB,IAAI,GAAQ,CAAC;IAEb,IAAI,aAAa,EAAE,CAAC;QACnB,yDAAyD;QACzD,mDAAmD;QACnD,GAAG,GAAG,IAAA,sBAAW,EAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACP,qDAAqD;QACrD,MAAM,SAAS,GAAG,IAAA,wBAAa,EAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QAC/C,GAAG,GAAG,yBAAa,SAAS,uCAAC,CAAC;IAC/B,CAAC;IAED,sCAAsC;IACtC,8EAA8E;IAC9E,oCAAoC;IACpC,gDAAgD;IAChD,IAAI,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3E,OAAO,GAAG,CAAC,OAAY,CAAC;IACzB,CAAC;IAED,OAAO,GAAQ,CAAC;AACjB,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC,CAAC,WAAW,CAAC;AAEnD;;GAEG;AACH,SAAgB,eAAe,CAAC,EAAW;IAC1C,OAAO,EAAE,YAAY,aAAa,CAAC;AACpC,CAAC"}

package/dist/server/event-processor.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Event processor module for Socket.IO event handling.
+ *
+ * This module is the core of Lithia's Socket.IO event processing pipeline. It handles:
+ * - Event handler module loading with cache busting in development
+ * - Event context initialization for hooks
+ * - Error handling with logging and digest generation
+ * - Error event emission for centralized error handling
+ *
+ * @module server/event-processor
+ */
+import type { Event } from "@lithia-js/native";
+import type { Socket } from "socket.io";
+import type { Lithia } from "../lithia";
+/**
+ * Event handler function signature.
+ *
+ * The primary function exported from event files to handle Socket.IO events.
+ *
+ * @param socket - The Socket.IO socket instance that triggered the event
+ */
+export type EventHandler = (socket: Socket) => Promise<void>;
+/**
+ * Structure of an event module loaded from the file system.
+ *
+ * Event files must export a default async function that handles the event.
+ */
+export interface EventModule {
+    /**
+     * The default event handler function.
+     *
+     * This function is called when the event is triggered by a client.
+     */
+    default: (socket: Socket) => Promise<void>;
+}
+/**
+ * Standardized error information for event errors.
+ *
+ * Contains details about errors that occur during event processing.
+ *
+ * @internal
+ */
+export interface EventErrorInfo {
+    /** The event name that caused the error. */
+    eventName: string;
+    /** Human-readable error message. */
+    message: string;
+    /** ISO timestamp of when the error occurred. */
+    timestamp: string;
+    /** Short error digest for correlation with logs. */
+    digest: string;
+    /** Socket ID that triggered the error. */
+    socketId: string;
+    /** Error stack trace (development only). */
+    stack?: string;
+}
+/**
+ * Event processor for the Lithia Socket.IO pipeline.
+ *
+ * This class orchestrates the entire event processing flow from receiving
+ * a Socket.IO event to executing the handler. It manages:
+ *
+ * - **Event context**: Initializes context with event data for hooks
+ * - **Module loading**: Loads event handlers with cache busting in development
+ * - **Error handling**: Catches and logs errors with digest generation
+ * - **Error events**: Emits error events for centralized error handling
+ * - **Logging**: Logs all events with timing and error details
+ *
+ * @remarks
+ * The processor uses AsyncLocalStorage to provide event context to hooks,
+ * allowing event handlers to access data without explicit parameters.
+ *
+ * In development mode, event modules are reloaded on each event (cache busting).
+ * In production, modules are cached for better performance.
+ */
+export declare class EventProcessor {
+    private lithia;
+    /**
+     * Creates a new event processor.
+     *
+     * @param lithia - The Lithia application instance
+     */
+    constructor(lithia: Lithia);
+    /**
+     * Processes an incoming Socket.IO event through the complete pipeline.
+     *
+     * This is the main entry point for event processing. The method executes
+     * the following steps in order:
+     *
+     * 1. Initialize event context with data for hooks
+     * 2. Load the event handler module
+     * 3. Execute the event handler
+     * 4. Log the event with timing
+     *
+     * Any errors thrown during this process are caught and handled by
+     * {@link handleError}, which logs the error and emits an error event.
+     *
+     * @param socket - The Socket.IO socket that triggered the event
+     * @param event - The event definition from the manifest
+     * @param args - Additional arguments passed with the event
+     *
+     * @example
+     * ```typescript
+     * const processor = new EventProcessor(lithia);
+     * await processor.processEvent(socket, event, messageData);
+     * ```
+     */
+    processEvent(socket: Socket, event: Event, ...args: any[]): Promise<void>;
+    /**
+     * Centralized error handler for the event pipeline.
+     *
+     * This method handles all errors thrown during event processing:
+     *
+     * **Development mode:**
+     * - Returns detailed error messages to client
+     * - Includes full error stacks
+     * - Logs with error digest
+     *
+     * **Production mode:**
+     * - Returns generic error messages to client
+     * - Includes error digest for log correlation
+     * - Hides sensitive error details
+     *
+     * After logging, emits an 'error' event to the socket so the client
+     * can handle errors gracefully.
+     *
+     * @param err - The error that was thrown
+     * @param event - The event definition that caused the error
+     * @param socket - The Socket.IO socket that triggered the event
+     * @param start - High-resolution timestamp when event processing started
+     *
+     * @private
+     */
+    private handleError;
+    /**
+     * Logs a completed event with timing information.
+     *
+     * The log includes:
+     * - Event name
+     * - Socket ID
+     * - Processing duration in milliseconds
+     * - Success or error status
+     *
+     * Respects the `logging.events` configuration flag. Critical errors
+     * are always logged regardless of the flag.
+     *
+     * @param event - The event that was processed
+     * @param socket - The socket that triggered the event
+     * @param start - High-resolution timestamp when processing started
+     * @param isError - Whether the event resulted in an error
+     *
+     * @private
+     */
+    private logEvent;
+    /**
+     * Generates a short hexadecimal digest for error correlation.
+     *
+     * The digest is used to correlate server-side error logs with client-facing
+     * error responses. This allows developers to find the detailed error in logs
+     * using the digest shown to the client.
+     *
+     * The digest is generated from:
+     * - Error message and stack
+     * - Current timestamp
+     * - Random factor for uniqueness
+     *
+     * @param err - The error to generate a digest for
+     * @returns An 8-character hexadecimal digest
+     *
+     * @private
+     */
+    private generateErrorDigest;
+    /**
+     * Imports an event module from the file system.
+     *
+     * In **development mode**, uses cache-busting to reload the module on each
+     * event, enabling hot reloading without server restart.
+     *
+     * In **production mode**, uses standard dynamic imports with caching for
+     * better performance.
+     *
+     * The method also validates the module structure:
+     * - Must have a default export
+     * - Default export must be a function
+     * - Default export must be async
+     *
+     * @param event - The event whose module should be imported
+     * @returns The loaded and validated event module
+     * @throws {InvalidEventModuleError} If the module structure is invalid
+     * @throws {Error} If the module fails to load
+     *
+     * @private
+     */
+    private importEventModule;
+}

package/dist/server/event-processor.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Event processor module for Socket.IO event handling.
+ *
+ * This module is the core of Lithia's Socket.IO event processing pipeline. It handles:
+ * - Event handler module loading with cache busting in development
+ * - Event context initialization for hooks
+ * - Error handling with logging and digest generation
+ * - Error event emission for centralized error handling
+ *
+ * @module server/event-processor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventProcessor = void 0;
+const node_crypto_1 = require("node:crypto");
+const utils_1 = require("@lithia-js/utils");
+const event_context_1 = require("../context/event-context");
+const errors_1 = require("../errors");
+const logger_1 = require("../logger");
+const module_loader_1 = require("../module-loader");
+/**
+ * Event processor for the Lithia Socket.IO pipeline.
+ *
+ * This class orchestrates the entire event processing flow from receiving
+ * a Socket.IO event to executing the handler. It manages:
+ *
+ * - **Event context**: Initializes context with event data for hooks
+ * - **Module loading**: Loads event handlers with cache busting in development
+ * - **Error handling**: Catches and logs errors with digest generation
+ * - **Error events**: Emits error events for centralized error handling
+ * - **Logging**: Logs all events with timing and error details
+ *
+ * @remarks
+ * The processor uses AsyncLocalStorage to provide event context to hooks,
+ * allowing event handlers to access data without explicit parameters.
+ *
+ * In development mode, event modules are reloaded on each event (cache busting).
+ * In production, modules are cached for better performance.
+ */
+class EventProcessor {
+    lithia;
+    /**
+     * Creates a new event processor.
+     *
+     * @param lithia - The Lithia application instance
+     */
+    constructor(lithia) {
+        this.lithia = lithia;
+    }
+    /**
+     * Processes an incoming Socket.IO event through the complete pipeline.
+     *
+     * This is the main entry point for event processing. The method executes
+     * the following steps in order:
+     *
+     * 1. Initialize event context with data for hooks
+     * 2. Load the event handler module
+     * 3. Execute the event handler
+     * 4. Log the event with timing
+     *
+     * Any errors thrown during this process are caught and handled by
+     * {@link handleError}, which logs the error and emits an error event.
+     *
+     * @param socket - The Socket.IO socket that triggered the event
+     * @param event - The event definition from the manifest
+     * @param args - Additional arguments passed with the event
+     *
+     * @example
+     * ```typescript
+     * const processor = new EventProcessor(lithia);
+     * await processor.processEvent(socket, event, messageData);
+     * ```
+     */
+    async processEvent(socket, event, ...args) {
+        const start = process.hrtime.bigint();
+        // Initialize context for hooks
+        const eventCtx = {
+            data: args[0],
+            socket,
+        };
+        await this.lithia.runWithContext(async () => {
+            await event_context_1.eventContext.run(eventCtx, async () => {
+                try {
+                    // Import event module
+                    const module = await this.importEventModule(event);
+                    // Execute event handler
+                    await module.default(socket);
+                    // Log successful event
+                    this.logEvent(event, start);
+                }
+                catch (err) {
+                    // Handle and log error
+                    await this.handleError(err, event, socket, start);
+                }
+            });
+        });
+    }
+    // ==================== Error Handling ====================
+    /**
+     * Centralized error handler for the event pipeline.
+     *
+     * This method handles all errors thrown during event processing:
+     *
+     * **Development mode:**
+     * - Returns detailed error messages to client
+     * - Includes full error stacks
+     * - Logs with error digest
+     *
+     * **Production mode:**
+     * - Returns generic error messages to client
+     * - Includes error digest for log correlation
+     * - Hides sensitive error details
+     *
+     * After logging, emits an 'error' event to the socket so the client
+     * can handle errors gracefully.
+     *
+     * @param err - The error that was thrown
+     * @param event - The event definition that caused the error
+     * @param socket - The Socket.IO socket that triggered the event
+     * @param start - High-resolution timestamp when event processing started
+     *
+     * @private
+     */
+    async handleError(err, event, socket, start) {
+        const isDevelopment = this.lithia.getEnvironment() === "development";
+        // Generate error digest
+        const digest = this.generateErrorDigest(err);
+        // Build error details
+        const errorMessage = err instanceof Error ? err.message : "Internal Server Error";
+        const errorStack = err instanceof Error ? err.stack : undefined;
+        // Log error with digest (same format for both environments)
+        logger_1.logger.error(`[Event: ${event.name}] [Digest: ${(0, utils_1.red)(digest)}] ${errorStack || errorMessage}`);
+        // Build error information for client
+        const errorInfo = {
+            eventName: event.name,
+            message: isDevelopment
+                ? errorMessage
+                : "An error occurred while processing the event",
+            timestamp: new Date().toISOString(),
+            digest: digest,
+            socketId: socket.id,
+            stack: isDevelopment ? errorStack : undefined,
+        };
+        // Emit error event to the client
+        socket.emit("error", errorInfo);
+        // Log the event as failed
+        this.logEvent(event, start, true);
+    }
+    // ==================== Logging & Diagnostics ====================
+    /**
+     * Logs a completed event with timing information.
+     *
+     * The log includes:
+     * - Event name
+     * - Socket ID
+     * - Processing duration in milliseconds
+     * - Success or error status
+     *
+     * Respects the `logging.events` configuration flag. Critical errors
+     * are always logged regardless of the flag.
+     *
+     * @param event - The event that was processed
+     * @param socket - The socket that triggered the event
+     * @param start - High-resolution timestamp when processing started
+     * @param isError - Whether the event resulted in an error
+     *
+     * @private
+     */
+    logEvent(event, start, isError = false) {
+        // Always log errors, otherwise respect the logging.events flag
+        const shouldLog = isError || this.lithia.options.logging?.events !== false;
+        if (!shouldLog)
+            return;
+        const end = process.hrtime.bigint();
+        const duration = Number(end - start) / 1_000_000;
+        const durationStr = `${duration.toFixed(2)}ms`;
+        // Use same color scheme as requests for consistency
+        const statusStr = isError ? (0, utils_1.red)("ERROR") : (0, utils_1.green)("OK");
+        logger_1.logger.info(`[${statusStr}] EVENT ${event.name} - ${durationStr}`);
+    }
+    /**
+     * Generates a short hexadecimal digest for error correlation.
+     *
+     * The digest is used to correlate server-side error logs with client-facing
+     * error responses. This allows developers to find the detailed error in logs
+     * using the digest shown to the client.
+     *
+     * The digest is generated from:
+     * - Error message and stack
+     * - Current timestamp
+     * - Random factor for uniqueness
+     *
+     * @param err - The error to generate a digest for
+     * @returns An 8-character hexadecimal digest
+     *
+     * @private
+     */
+    generateErrorDigest(err) {
+        // Create a unique digest based on error message, timestamp, and random factor
+        const errorString = err instanceof Error ? `${err.message}${err.stack}` : String(err);
+        const hash = (0, node_crypto_1.createHash)("sha256")
+            .update(`${errorString}${Date.now()}${Math.random()}`)
+            .digest("hex");
+        // Return first 8 characters (similar to request-processor)
+        return hash.substring(0, 8);
+    }
+    // ==================== Module Loading ====================
+    /**
+     * Imports an event module from the file system.
+     *
+     * In **development mode**, uses cache-busting to reload the module on each
+     * event, enabling hot reloading without server restart.
+     *
+     * In **production mode**, uses standard dynamic imports with caching for
+     * better performance.
+     *
+     * The method also validates the module structure:
+     * - Must have a default export
+     * - Default export must be a function
+     * - Default export must be async
+     *
+     * @param event - The event whose module should be imported
+     * @returns The loaded and validated event module
+     * @throws {InvalidEventModuleError} If the module structure is invalid
+     * @throws {Error} If the module fails to load
+     *
+     * @private
+     */
+    async importEventModule(event) {
+        try {
+            const isDevelopment = this.lithia.getEnvironment() === "development";
+            const mod = await (0, module_loader_1.coldImport)(event.filePath, isDevelopment);
+            if (!mod.default) {
+                throw new errors_1.InvalidEventModuleError(event.filePath, "Missing default export");
+            }
+            if (typeof mod.default !== "function") {
+                throw new errors_1.InvalidEventModuleError(event.filePath, "Default export is not a function");
+            }
+            if (!(0, module_loader_1.isAsyncFunction)(mod.default)) {
+                throw new errors_1.InvalidEventModuleError(event.filePath, "Default export is not an async function");
+            }
+            return mod;
+        }
+        catch (err) {
+            if (err instanceof errors_1.InvalidEventModuleError) {
+                throw err;
+            }
+            throw new Error(`Failed to import event: ${event.name}`);
+        }
+    }
+}
+exports.EventProcessor = EventProcessor;
+//# sourceMappingURL=event-processor.js.map

package/dist/server/event-processor.js.map

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