@lithia-js/core 1.0.0-canary.2 → 1.0.0-canary.4

package/src/config.ts

@@ -1,212 +0,0 @@
-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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-/**
- * 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

@@ -1,89 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-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

@@ -1,96 +0,0 @@
-/** 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

@@ -1,122 +0,0 @@
-/**
- * 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;
-}