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

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;
-}

package/src/hooks/event-hooks.ts

@@ -1,69 +0,0 @@
-/**
- * Socket.IO event hooks for Lithia.
- *
- * Provides hooks to access event-specific data in Socket.IO event handlers.
- * All hooks must be called within a Socket.IO event handler.
- *
- * @module hooks/event-hooks
- */
-
-import type { Socket } from "socket.io";
-import { getEventContext } from "../context/event-context";
-
-/**
- * Accesses the data payload sent with a Socket.IO event.
- *
- * Returns the data that the client sent when emitting the event.
- * The structure and type of the data depends on what the client sends.
- *
- * @returns The event data payload
- * @throws {Error} If called outside of an event handler
- * @template T - Type of the event data
- *
- * @example
- * ```typescript
- * // Handler for 'chat:message' event
- * export default async function handler() {
- *   const data = useData<{ message: string; userId: string }>();
- *   console.log('Received message:', data.message);
- *   console.log('From user:', data.userId);
- * }
- * ```
- */
-export function useData<T>(): T {
-	return getEventContext().data as T;
-}
-
-/**
- * Accesses the Socket.IO socket instance for the current event.
- *
- * Returns the socket that triggered the event, allowing you to emit
- * messages back to the client, join/leave rooms, or access socket metadata.
- *
- * @returns The Socket.IO socket instance
- * @throws {Error} If called outside of an event handler
- *
- * @example
- * ```typescript
- * // Handler for 'chat:message' event
- * export default async function handler() {
- *   const socket = useSocket();
- *   const data = useData<{ message: string }>();
- *
- *   // Emit response back to the client
- *   socket.emit('message:received', { success: true });
- *
- *   // Broadcast to other clients
- *   socket.broadcast.emit('new:message', data);
- *
- *   // Join a room
- *   socket.join('chat-room');
- *
- *   // Access socket metadata
- *   console.log('Socket ID:', socket.id);
- * }
- * ```
- */
-export function useSocket(): Socket {
-	return getEventContext().socket;
-}

package/src/hooks/index.ts

@@ -1,58 +0,0 @@
-/**
- * Lithia hooks for accessing context and dependencies.
- *
- * This module provides a composable API for accessing request/event data
- * and managing dependencies through dependency injection.
- *
- * ## Hook Categories
- *
- * ### Route Hooks (HTTP Requests)
- * - `useRequest()`: Access the current request object
- * - `useResponse()`: Access the current response object
- * - `useRoute()`: Access the matched route metadata
- * - `useParams()`: Access route parameters (e.g., `/users/:id`)
- * - `useQuery()`: Access URL query parameters
- * - `useHeaders()`: Access request headers
- *
- * ### Event Hooks (Socket.IO)
- * - `useData()`: Access event payload data
- *
- * ### Dependency Injection Hooks (Both)
- * - `provide()`: Register a dependency in the container
- * - `inject()`: Retrieve a required dependency
- * - `injectOptional()`: Retrieve an optional dependency
- *
- * @module hooks
- *
- * @example
- * ```typescript
- * import { useParams, inject } from '@lithia-js/core';
- *
- * export default async function handler() {
- *   const { id } = useParams<{ id: string }>();
- *   const db = inject(dbKey);
- *   const user = await db.findUser(id);
- *   return user;
- * }
- * ```
- */
-
-// Dependency injection hooks
-export {
-	type InjectionKey,
-	inject,
-	injectOptional,
-	provide,
-} from "./dependency-hooks";
-// Socket.IO event hooks
-export { useData } from "./event-hooks";
-// HTTP Route hooks
-export {
-	useHeaders,
-	useParams,
-	useQuery,
-	useRequest,
-	useResponse,
-	useRoute,
-	useSocketServer,
-} from "./route-hooks";

package/src/hooks/route-hooks.ts

@@ -1,177 +0,0 @@
-/**
- * HTTP route hooks for Lithia.
- *
- * Provides convenient hooks to access request-specific data in route handlers.
- * All hooks must be called within an HTTP request handler or middleware.
- *
- * @module hooks/route-hooks
- */
-
-import type { IncomingHttpHeaders } from "node:http";
-import type { Route } from "@lithia-js/native";
-import type { Server } from "socket.io";
-import { getRouteContext } from "../context/route-context";
-import type { LithiaRequest, Params, Query } from "../server/request";
-import type { LithiaResponse } from "../server/response";
-
-/**
- * Accesses the current HTTP request object.
- *
- * Provides access to all request properties including params, query,
- * headers, body, and other request metadata.
- *
- * @returns The current LithiaRequest instance
- * @throws {Error} If called outside of a request handler
- *
- * @example
- * ```typescript
- * export default async function handler() {
- *   const req = useRequest();
- *   console.log(req.method, req.url);
- * }
- * ```
- */
-export function useRequest(): LithiaRequest {
-	return getRouteContext().req;
-}
-
-/**
- * Accesses the current HTTP response object.
- *
- * Used to send responses back to the client, set headers, status codes, etc.
- *
- * @returns The current LithiaResponse instance
- * @throws {Error} If called outside of a request handler
- *
- * @example
- * ```typescript
- * export default async function handler() {
- *   const res = useResponse();
- *   res.status(200).json({ message: 'Success' });
- * }
- * ```
- */
-export function useResponse(): LithiaResponse {
-	return getRouteContext().res;
-}
-
-/**
- * Accesses the current matched route definition.
- *
- * Contains metadata about the current route including path pattern,
- * HTTP method, and handler information.
- *
- * @returns The matched Route, or undefined if no route matched or called before route resolution
- * @throws {Error} If called outside of a request handler
- *
- * @example
- * ```typescript
- * export default async function handler() {
- *   const route = useRoute();
- *   console.log('Handling route:', route?.path);
- * }
- * ```
- */
-export function useRoute(): Route | undefined {
-	return getRouteContext().route;
-}
-
-/**
- * Accesses route parameters (dynamic segments).
- *
- * Extracts parameters from dynamic route segments like `/users/:id`.
- *
- * @returns Object containing route parameters
- * @throws {Error} If called outside of a request handler
- * @template T - Type of the params object
- *
- * @example
- * ```typescript
- * // Route: /users/:id
- * export default async function handler() {
- *   const { id } = useParams<{ id: string }>();
- *   console.log('User ID:', id);
- * }
- * ```
- */
-export function useParams<T extends Params = Params>(): T {
-	return getRouteContext().req.params as T;
-}
-
-/**
- * Accesses URL query parameters.
- *
- * Extracts query string parameters from the request URL.
- *
- * @returns Object containing query parameters
- * @throws {Error} If called outside of a request handler
- * @template T - Type of the query object
- *
- * @example
- * ```typescript
- * // URL: /search?q=lithia&page=1
- * export default async function handler() {
- *   const { q, page } = useQuery<{ q: string; page: string }>();
- *   console.log('Search:', q, 'Page:', page);
- * }
- * ```
- */
-export function useQuery<T extends Query = Query>(): T {
-	return getRouteContext().req.query as T;
-}
-
-/**
- * Accesses HTTP request headers.
- *
- * Returns all headers sent with the request.
- *
- * @returns Object containing HTTP headers
- * @throws {Error} If called outside of a request handler
- *
- * @example
- * ```typescript
- * export default async function handler() {
- *   const headers = useHeaders();
- *   const auth = headers.authorization;
- *   console.log('Auth header:', auth);
- * }
- * ```
- */
-export function useHeaders(): IncomingHttpHeaders {
-	return getRouteContext().req.headers;
-}
-
-/**
- * Accesses the Socket.IO server instance from within an HTTP route handler.
- *
- * This hook allows HTTP routes to interact with Socket.IO, enabling you to
- * emit events to connected clients, broadcast messages, or manage rooms in
- * response to HTTP requests.
- *
- * @returns The Socket.IO Server instance
- * @throws {Error} If called outside of a request handler
- *
- * @example
- * ```typescript
- * // HTTP route that triggers real-time updates
- * export default async function handler() {
- *   const io = useSocketServer();
- *   const { message } = useQuery<{ message: string }>();
- *
- *   // Broadcast to all connected clients
- *   io.emit('notification', { message, timestamp: Date.now() });
- *
- *   // Emit to a specific room
- *   io.to('admin-room').emit('alert', { message });
- *
- *   // Get all connected sockets
- *   const sockets = await io.fetchSockets();
- *   console.log(`Broadcasting to ${sockets.length} clients`);
- *
- *   return { success: true, clients: sockets.length };
- * }
- * ```
- */
-export function useSocketServer(): Server {
-	return getRouteContext().socketServer;
-}

package/src/lib.ts

@@ -1,27 +0,0 @@
-export { defineConfig, LithiaConfig } from "./config";
-export { loadEnv } from "./env";
-export {
-	InjectionKey,
-	inject,
-	injectOptional,
-	provide,
-	useData,
-	useHeaders,
-	useParams,
-	useQuery,
-	useRequest,
-	useResponse,
-	useRoute,
-	useSocketServer,
-} from "./hooks";
-export { Lithia } from "./lithia";
-export { logger } from "./logger";
-export { EventErrorInfo, EventHandler } from "./server/event-processor";
-export { validate } from "./server/middlewares/validation";
-export { LithiaRequest, Params, Query } from "./server/request";
-export {
-	LithiaHandler,
-	LithiaMiddleware,
-	RequestErrorInfo,
-} from "./server/request-processor";
-export { LithiaResponse } from "./server/response";