@lithia-js/core 1.0.0-canary.0

package/src/config.ts

@@ -0,0 +1,212 @@
+import type { DeepPartial } from "@lithia-js/utils";
+import {
+	type C12InputConfig,
+	loadConfig,
+	type WatchConfigOptions,
+	watchConfig,
+} from "c12";
+import { klona } from "klona";
+
+/** Result type for lifecycle hooks — may be synchronous or async. */
+export type HookResult = void | Promise<void>;
+
+/** Available lifecycle hooks supported by the runtime. */
+export interface LithiaHooks {
+	/** Called before the HTTP server starts. */
+	"before:start": () => HookResult;
+	/** Called after the HTTP server has started. */
+	"after:start": () => HookResult;
+}
+
+/** Shape of the runtime configuration used by Lithia. */
+export interface LithiaOptions {
+	debug: boolean;
+	http: {
+		port: number;
+		host: string;
+		maxBodySize?: number;
+		ssl?: {
+			key: string;
+			cert: string;
+			passphrase?: string;
+		};
+		cors: {
+			origin?: string[];
+			methods?: string[];
+			allowedHeaders?: string[];
+			exposedHeaders?: string[];
+			credentials?: boolean;
+			maxAge?: number;
+		};
+		mimeTypes?: Record<string, string>;
+	};
+	static?: {
+		root: string;
+		prefix?: string;
+	};
+	studio: {
+		enabled: boolean;
+	};
+	logging: {
+		/** Enable request logging. Critical errors (5xx) are always logged. */
+		requests: boolean;
+		/** Enable event logging. Critical errors are always logged. */
+		events: boolean;
+	};
+	hooks: {
+		[K in keyof LithiaHooks]: LithiaHooks[K];
+	};
+}
+
+/** Partial configuration accepted by `defineConfig` and the config loader. */
+export interface LithiaConfig
+	extends DeepPartial<LithiaOptions>,
+		C12InputConfig<LithiaConfig> {}
+
+/** Default runtime configuration used when no overrides are provided. */
+export const DEFAULT_CONFIG: LithiaConfig = {
+	debug: false,
+	http: {
+		port: 3000,
+		host: "localhost",
+		maxBodySize: 1024 * 1024,
+		cors: {
+			origin: ["*"],
+			methods: ["*"],
+			allowedHeaders: ["*"],
+			exposedHeaders: ["X-Powered-By"],
+			credentials: false,
+			maxAge: 86400,
+		},
+	},
+	logging: {
+		requests: true,
+		events: true,
+	},
+	hooks: {},
+	studio: {
+		enabled: false,
+	},
+};
+
+type LoadConfigOptions = {
+	watch?: boolean;
+	c12?: WatchConfigOptions;
+	overrides?: LithiaConfig;
+};
+
+/** Error thrown when configuration validation fails. */
+export class ConfigValidationError extends Error {
+	constructor(
+		message: string,
+		public readonly field?: string,
+	) {
+		super(message);
+		this.name = "ConfigValidationError";
+	}
+}
+
+/** Context passed to `watchConfig` callbacks describing the updated config. */
+export interface ConfigUpdateContext {
+	/** Returns a list of diffs between old and new config. */
+	getDiff: () => Array<{
+		key: string;
+		type: string;
+		newValue: unknown;
+		oldValue: unknown;
+	}>;
+	/** The new fully materialized config. */
+	newConfig: LithiaOptions;
+	/** The previous config prior to the update. */
+	oldConfig: LithiaOptions;
+}
+
+/** Provider responsible for loading and optionally watching the runtime config. */
+export class ConfigProvider {
+	/**
+	 * Load the configuration, applying optional overrides.
+	 *
+	 * This delegates to `c12` for reading configuration files and defaults
+	 * and validates the resulting `LithiaOptions` before returning them.
+	 */
+	async loadConfig(overrides: LithiaConfig = {}, opts: LoadConfigOptions = {}) {
+		overrides = klona(overrides);
+
+		const configOptions = {
+			name: "lithia",
+			configFile: "lithia.config",
+			cwd: process.cwd(),
+			dotenv: true,
+			overrides,
+			defaults: DEFAULT_CONFIG,
+			...opts.c12,
+		};
+
+		const loadedConfig = await loadConfig<LithiaConfig>(configOptions);
+		const options = klona(loadedConfig.config) as LithiaOptions;
+
+		// overrides are already applied by c12; no need to re-assign here
+
+		this.validateConfig(options);
+
+		return options;
+	}
+
+	/**
+	 * Watch the configuration for changes and invoke `onChange` when updates occur.
+	 *
+	 * Returns a handle with a `close()` method to stop watching.
+	 */
+	async watchConfig(
+		onChange: (ctx: ConfigUpdateContext) => void | Promise<void>,
+		overrides: LithiaConfig = {},
+		opts: LoadConfigOptions = {},
+	) {
+		overrides = klona(overrides);
+
+		const configOptions = {
+			name: "lithia",
+			configFile: "lithia.config",
+			cwd: process.cwd(),
+			dotenv: true,
+			overrides,
+			defaults: DEFAULT_CONFIG,
+			...opts.c12,
+			watch: true,
+			onUpdate: async (context: any) => {
+				const newOptions = klona(context.newConfig.config) as LithiaOptions;
+				this.validateConfig(newOptions);
+
+				await onChange({
+					getDiff: context.getDiff,
+					newConfig: newOptions,
+					oldConfig: context.oldConfig.config as LithiaOptions,
+				});
+			},
+		};
+
+		const handle = await watchConfig<LithiaConfig>(configOptions as any);
+
+		return {
+			close: () => {
+				if (typeof (handle as any)?.close === "function") {
+					(handle as any).close();
+				}
+			},
+		};
+	}
+
+	private validateConfig(config: LithiaOptions): void {
+		if (config.http.port < 1 || config.http.port > 65535) {
+			throw new ConfigValidationError(
+				`HTTP port must be between 1 and 65535, got ${config.http.port}`,
+				"http.port",
+			);
+		}
+	}
+}
+
+/** Utility helper used by users to define their config with IDE type hints. */
+export function defineConfig(config: LithiaConfig): LithiaConfig {
+	return config;
+}

package/src/context/event-context.ts

@@ -0,0 +1,66 @@
+/**
+ * Event context module for Socket.IO events.
+ *
+ * Provides context specific to Socket.IO event handling, including access
+ * to event data passed from the client.
+ *
+ * @module context/event-context
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Socket } from "socket.io";
+
+/**
+ * Socket.IO event handler context.
+ *
+ * Contains event-specific information available to event handlers
+ * during Socket.IO event processing.
+ */
+export type EventContext = {
+	/**
+	 * Data payload sent with the event.
+	 *
+	 * Contains the data passed from the client when emitting the event.
+	 * The structure depends on what the client sends.
+	 */
+	data: any;
+
+	/**
+	 * The Socket.IO socket instance.
+	 *
+	 * Represents the client connection that triggered the event.
+	 */
+	socket: Socket;
+};
+
+/**
+ * AsyncLocalStorage instance for event context.
+ *
+ * Uses Node.js AsyncLocalStorage to provide implicit context propagation
+ * for Socket.IO event handling across async boundaries.
+ *
+ * @see https://nodejs.org/api/async_hooks.html#class-asynclocalstorage
+ */
+export const eventContext = new AsyncLocalStorage<EventContext>();
+
+/**
+ * Gets the current event context.
+ *
+ * @returns The current EventContext
+ * @throws {Error} If called outside of a Socket.IO event handler
+ *
+ * @example
+ * ```typescript
+ * const ctx = getEventContext();
+ * console.log('Event data:', ctx.data);
+ * ```
+ */
+export function getEventContext(): EventContext {
+	const ctx = eventContext.getStore();
+	if (!ctx) {
+		throw new Error(
+			"Lithia event context not found. Are you calling a hook outside of an event handler?",
+		);
+	}
+	return ctx;
+}

package/src/context/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Context management for Lithia.
+ *
+ * This module provides three separate context types using AsyncLocalStorage:
+ * - **LithiaContext**: Global application context with DI container
+ * - **RouteContext**: HTTP request-specific context
+ * - **EventContext**: Socket.IO event-specific context
+ *
+ * Each context is isolated and provides different information based on
+ * the execution environment (HTTP request vs Socket.IO event).
+ *
+ * @module context
+ */
+
+// Socket.IO event context
+export {
+	type EventContext,
+	eventContext,
+	getEventContext,
+} from "./event-context";
+// Lithia global context
+export {
+	getLithiaContext,
+	type LithiaContext,
+	lithiaContext,
+} from "./lithia-context";
+// HTTP route context
+export {
+	getRouteContext,
+	type RouteContext,
+	routeContext,
+} from "./route-context";

package/src/context/lithia-context.ts

@@ -0,0 +1,59 @@
+/**
+ * Lithia global context module.
+ *
+ * Provides the main application-level context that holds the global
+ * dependency injection container. This context is available throughout
+ * the entire request/event lifecycle.
+ *
+ * @module context/lithia-context
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Global Lithia application context.
+ *
+ * Holds the dependency injection container that is shared across
+ * the entire application and accessible in all request/event handlers.
+ */
+export interface LithiaContext {
+	/**
+	 * Global dependency injection container.
+	 *
+	 * Stores dependencies registered via `provide()` that can be injected
+	 * into handlers using `inject()` or `injectOptional()`.
+	 */
+	dependencies: Map<any, any>;
+}
+
+/**
+ * AsyncLocalStorage instance for Lithia application context.
+ *
+ * Uses Node.js AsyncLocalStorage to provide implicit context propagation
+ * across async boundaries without explicit parameter passing.
+ *
+ * @see https://nodejs.org/api/async_hooks.html#class-asynclocalstorage
+ */
+export const lithiaContext = new AsyncLocalStorage<LithiaContext>();
+
+/**
+ * Gets the current Lithia context.
+ *
+ * @returns The current LithiaContext
+ * @throws {Error} If called outside of a request or event handler context
+ *
+ * @example
+ * ```typescript
+ * const ctx = getLithiaContext();
+ * const db = ctx.dependencies.get(dbKey);
+ * ```
+ */
+export function getLithiaContext(): LithiaContext {
+	const ctx = lithiaContext.getStore();
+	if (!ctx) {
+		throw new Error(
+			"Lithia context not found. Are you accessing dependencies outside of a request or event handler?",
+		);
+	}
+	return ctx;
+}

package/src/context/route-context.ts

@@ -0,0 +1,89 @@
+/**
+ * Route context module for HTTP requests.
+ *
+ * Provides context specific to HTTP route handling, including access to
+ * the current request, response, and matched route information.
+ *
+ * @module context/route-context
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Route } from "@lithia-js/native";
+import type { Server } from "socket.io";
+import type { LithiaRequest } from "../server/request";
+import type { LithiaResponse } from "../server/response";
+
+/**
+ * HTTP route handler context.
+ *
+ * Contains request-specific information available to route handlers
+ * and middlewares during HTTP request processing.
+ */
+export interface RouteContext {
+	/**
+	 * The current HTTP request object.
+	 *
+	 * Provides access to request data like params, query, headers, and body.
+	 */
+	req: LithiaRequest;
+
+	/**
+	 * The current HTTP response object.
+	 *
+	 * Used to send responses back to the client.
+	 */
+	res: LithiaResponse;
+
+	/**
+	 * The matched route definition.
+	 *
+	 * Contains metadata about the current route including path, method,
+	 * and handler information. May be undefined before route resolution
+	 * or in 404 handlers.
+	 */
+	route?: Route;
+
+	/**
+	 * The Socket.IO server instance.
+	 *
+	 * Provides access to the Socket.IO server, allowing you to emit events
+	 * to all connected clients, manage rooms, or access server-level features
+	 * from within HTTP route handlers.
+	 *
+	 * This is useful for scenarios where an HTTP request needs to trigger
+	 * real-time updates to connected Socket.IO clients.
+	 */
+	socketServer: Server;
+}
+
+/**
+ * AsyncLocalStorage instance for route context.
+ *
+ * Uses Node.js AsyncLocalStorage to provide implicit context propagation
+ * for HTTP request handling across async boundaries.
+ *
+ * @see https://nodejs.org/api/async_hooks.html#class-asynclocalstorage
+ */
+export const routeContext = new AsyncLocalStorage<RouteContext>();
+
+/**
+ * Gets the current route context.
+ *
+ * @returns The current RouteContext
+ * @throws {Error} If called outside of an HTTP request handler
+ *
+ * @example
+ * ```typescript
+ * const ctx = getRouteContext();
+ * console.log(ctx.req.method, ctx.req.url);
+ * ```
+ */
+export function getRouteContext(): RouteContext {
+	const ctx = routeContext.getStore();
+	if (!ctx) {
+		throw new Error(
+			"Lithia route context not found. Are you calling a hook outside of a request handler?",
+		);
+	}
+	return ctx;
+}

package/src/env.ts

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "dotenv";
+
+export function loadEnv(cwd: string) {
+	const envFiles = [".env", ".env.local"];
+	const envVars: Record<string, string> = {};
+
+	for (const file of envFiles) {
+		const filePath = resolve(cwd, file);
+		if (existsSync(filePath)) {
+			try {
+				const parsed = parse(readFileSync(filePath));
+				Object.assign(envVars, parsed);
+			} catch {
+				// Ignore errors parsing env file
+			}
+		}
+	}
+
+	// Apply variables to process.env, but don't overwrite existing ones
+	for (const key in envVars) {
+		if (Object.hasOwn(envVars, key)) {
+			if (process.env[key] === undefined) {
+				process.env[key] = envVars[key];
+			}
+		}
+	}
+
+	return envVars;
+}

package/src/errors.ts

@@ -0,0 +1,96 @@
+/** Possible severity levels for a `LithiaError`. */
+export type LithiaErrorLevel = "fatal" | "error" | "warning" | "info";
+
+/** Base error class for Lithia runtime errors.
+ *
+ * All custom runtime errors extend `LithiaError` and provide a machine
+ * readable `code` and a `level` used for logging and control-flow (for
+ * instance `fatal` errors may terminate the process).
+ */
+export class LithiaError extends Error {
+	constructor(
+		/** Machine-readable error code. */
+		public code: string,
+		message: string,
+		/** Severity level. */
+		public level: LithiaErrorLevel = "error",
+		/** Optional underlying cause. */
+		public cause?: any,
+	) {
+		super(message);
+		this.name = "LithiaError";
+		Error.captureStackTrace?.(this, this.constructor as any);
+	}
+}
+
+/** Error raised when the manifest version does not match the native schema. */
+export class SchemaVersionMismatchError extends LithiaError {
+	constructor(expected: string, received: string) {
+		super(
+			"SCHEMA_VERSION_MISMATCH",
+			`Manifest version ${received} does not match expected version ${expected}`,
+			"fatal",
+			undefined,
+		);
+	}
+}
+
+/** Error used when reading or parsing the manifest fails. */
+export class ManifestLoadError extends LithiaError {
+	constructor(cause: any) {
+		super("MANIFEST_LOAD_ERROR", "Failed to load manifest.", "fatal", cause);
+	}
+}
+
+/** Error raised when serving a static file but no MIME type is configured for its extension. */
+export class StaticFileMimeMissingError extends LithiaError {
+	constructor(extension: string, filePath: string) {
+		super(
+			"STATIC_FILE_MIME_MISSING",
+			`No MIME type configured for extension '${extension}' when serving '${filePath}'. Please configure a MIME type for this extension in your Lithia config.`,
+			"error",
+		);
+	}
+}
+
+/** Error raised when request data validation fails. */
+export class ValidationError extends LithiaError {
+	constructor(
+		message: string,
+		public issues?: any[],
+	) {
+		super("VALIDATION_ERROR", message, "error");
+	}
+}
+
+/** Error raised when a route module does not export a default async function. */
+export class InvalidRouteModuleError extends LithiaError {
+	constructor(filePath: string, reason: string) {
+		super(
+			"INVALID_ROUTE_MODULE",
+			`Invalid route module at '${filePath}': ${reason}. Route modules must export a default async function.`,
+			"error",
+		);
+	}
+}
+
+export class InvalidEventModuleError extends LithiaError {
+	constructor(filePath: string, reason: string) {
+		super(
+			"INVALID_EVENT_MODULE",
+			`Invalid event module at '${filePath}': ${reason}. Event modules must export a default function that accepts a Lithia instance.`,
+			"error",
+		);
+	}
+}
+
+/** Error raised when the server bootstrap module (_server.ts) is invalid. */
+export class InvalidBootstrapModuleError extends LithiaError {
+	constructor(filePath: string, reason: string) {
+		super(
+			"INVALID_BOOTSTRAP_MODULE",
+			`Invalid server bootstrap module at '${filePath}': ${reason}. The module must export a default async function.`,
+			"fatal",
+		);
+	}
+}

package/src/hooks/dependency-hooks.ts

@@ -0,0 +1,122 @@
+/**
+ * Dependency injection hooks for Lithia.
+ *
+ * Provides a simple but powerful dependency injection system that works
+ * across both HTTP request handlers and Socket.IO event handlers.
+ *
+ * Dependencies can be provided globally (via `lithia.provide()`) or
+ * scoped to a specific request/event (via `provide()` in middlewares).
+ *
+ * @module hooks/dependency-hooks
+ */
+
+import { getLithiaContext } from "../context/lithia-context";
+
+/**
+ * Unique key for dependency injection.
+ *
+ * Can be:
+ * - A Symbol (recommended for type safety and uniqueness)
+ * - A string (simple but can conflict)
+ * - A class constructor (for class-based dependencies)
+ *
+ * @template T - Type of the dependency value
+ *
+ * @example
+ * ```typescript
+ * // Using Symbol (recommended)
+ * const dbKey = createInjectionKey<Database>('database');
+ *
+ * // Using string
+ * const dbKey = 'database';
+ *
+ * // Using class
+ * class Database {}
+ * const dbKey = Database;
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type InjectionKey<T> = symbol | string | { new (...args: any[]): T };
+
+/**
+ * Provides a dependency for injection.
+ *
+ * Registers a dependency in the current context's DI container.
+ * Should typically be called in middlewares or during application bootstrap.
+ *
+ * Dependencies are available for the entire lifecycle of the current
+ * request or event.
+ *
+ * @param key - Unique key to identify the dependency
+ * @param value - The dependency value to provide
+ * @template T - Type of the dependency value
+ *
+ * @example
+ * ```typescript
+ * // In a middleware
+ * export default async function authMiddleware(req, res, next) {
+ *   const user = await authenticate(req);
+ *   provide(userKey, user);
+ *   await next();
+ * }
+ * ```
+ */
+export function provide<T>(key: InjectionKey<T>, value: T): void {
+	getLithiaContext().dependencies.set(key, value);
+}
+
+/**
+ * Injects a dependency from the DI container.
+ *
+ * Retrieves a previously provided dependency. Throws an error if the
+ * dependency was not provided.
+ *
+ * @param key - The key of the dependency to inject
+ * @returns The dependency value
+ * @throws {Error} If the dependency is not found in the container
+ * @template T - Type of the dependency value
+ *
+ * @example
+ * ```typescript
+ * export default async function handler() {
+ *   const db = inject(dbKey);
+ *   const users = await db.query('SELECT * FROM users');
+ *   return users;
+ * }
+ * ```
+ */
+export function inject<T>(key: InjectionKey<T>): T {
+	const context = getLithiaContext();
+	if (!context.dependencies.has(key)) {
+		throw new Error(
+			`Dependency not found: ${String(key)}. Make sure to provide it using 'provide()' in a middleware.`,
+		);
+	}
+	return context.dependencies.get(key) as T;
+}
+
+/**
+ * Injects a dependency, returning undefined if not found.
+ *
+ * Like `inject()`, but returns undefined instead of throwing when the
+ * dependency is not available. Useful for optional dependencies.
+ *
+ * @param key - The key of the dependency to inject
+ * @returns The dependency value, or undefined if not found
+ * @template T - Type of the dependency value
+ *
+ * @example
+ * ```typescript
+ * export default async function handler() {
+ *   const user = injectOptional(userKey);
+ *   if (user) {
+ *     console.log('Authenticated as:', user.name);
+ *   } else {
+ *     console.log('Anonymous user');
+ *   }
+ * }
+ * ```
+ */
+export function injectOptional<T>(key: InjectionKey<T>): T | undefined {
+	return getLithiaContext().dependencies.get(key) as T | undefined;
+}