@lithia-js/core 1.0.0-canary.0

package/dist/context/route-context.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeContext = void 0;
+exports.getRouteContext = getRouteContext;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * 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
+ */
+exports.routeContext = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * 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);
+ * ```
+ */
+function getRouteContext() {
+    const ctx = exports.routeContext.getStore();
+    if (!ctx) {
+        throw new Error("Lithia route context not found. Are you calling a hook outside of a request handler?");
+    }
+    return ctx;
+}
+//# sourceMappingURL=route-context.js.map

package/dist/context/route-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-context.js","sourceRoot":"","sources":["../../src/context/route-context.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAyEH,0CAQC;AA/ED,uDAAqD;AAiDrD;;;;;;;GAOG;AACU,QAAA,YAAY,GAAG,IAAI,oCAAiB,EAAgB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe;IAC9B,MAAM,GAAG,GAAG,oBAAY,CAAC,QAAQ,EAAE,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACd,sFAAsF,CACtF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1 @@
+export declare function loadEnv(cwd: string): Record<string, string>;

package/dist/env.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnv = loadEnv;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const dotenv_1 = require("dotenv");
+function loadEnv(cwd) {
+    const envFiles = [".env", ".env.local"];
+    const envVars = {};
+    for (const file of envFiles) {
+        const filePath = (0, node_path_1.resolve)(cwd, file);
+        if ((0, node_fs_1.existsSync)(filePath)) {
+            try {
+                const parsed = (0, dotenv_1.parse)((0, node_fs_1.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;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":";;AAIA,0BA0BC;AA9BD,qCAAmD;AACnD,yCAAoC;AACpC,mCAA+B;AAE/B,SAAgB,OAAO,CAAC,GAAW;IAClC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACxC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAA,mBAAO,EAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACpC,IAAI,IAAA,oBAAU,EAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,IAAA,cAAK,EAAC,IAAA,sBAAY,EAAC,QAAQ,CAAC,CAAC,CAAC;gBAC7C,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACR,iCAAiC;YAClC,CAAC;QACF,CAAC;IACF,CAAC;IAED,oEAAoE;IACpE,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBACpC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/** 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 declare class LithiaError extends Error {
+    /** Machine-readable error code. */
+    code: string;
+    /** Severity level. */
+    level: LithiaErrorLevel;
+    /** Optional underlying cause. */
+    cause?: any | undefined;
+    constructor(
+    /** Machine-readable error code. */
+    code: string, message: string, 
+    /** Severity level. */
+    level?: LithiaErrorLevel, 
+    /** Optional underlying cause. */
+    cause?: any | undefined);
+}
+/** Error raised when the manifest version does not match the native schema. */
+export declare class SchemaVersionMismatchError extends LithiaError {
+    constructor(expected: string, received: string);
+}
+/** Error used when reading or parsing the manifest fails. */
+export declare class ManifestLoadError extends LithiaError {
+    constructor(cause: any);
+}
+/** Error raised when serving a static file but no MIME type is configured for its extension. */
+export declare class StaticFileMimeMissingError extends LithiaError {
+    constructor(extension: string, filePath: string);
+}
+/** Error raised when request data validation fails. */
+export declare class ValidationError extends LithiaError {
+    issues?: any[] | undefined;
+    constructor(message: string, issues?: any[] | undefined);
+}
+/** Error raised when a route module does not export a default async function. */
+export declare class InvalidRouteModuleError extends LithiaError {
+    constructor(filePath: string, reason: string);
+}
+export declare class InvalidEventModuleError extends LithiaError {
+    constructor(filePath: string, reason: string);
+}
+/** Error raised when the server bootstrap module (_server.ts) is invalid. */
+export declare class InvalidBootstrapModuleError extends LithiaError {
+    constructor(filePath: string, reason: string);
+}

package/dist/errors.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidBootstrapModuleError = exports.InvalidEventModuleError = exports.InvalidRouteModuleError = exports.ValidationError = exports.StaticFileMimeMissingError = exports.ManifestLoadError = exports.SchemaVersionMismatchError = exports.LithiaError = void 0;
+/** 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).
+ */
+class LithiaError extends Error {
+    code;
+    level;
+    cause;
+    constructor(
+    /** Machine-readable error code. */
+    code, message, 
+    /** Severity level. */
+    level = "error", 
+    /** Optional underlying cause. */
+    cause) {
+        super(message);
+        this.code = code;
+        this.level = level;
+        this.cause = cause;
+        this.name = "LithiaError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.LithiaError = LithiaError;
+/** Error raised when the manifest version does not match the native schema. */
+class SchemaVersionMismatchError extends LithiaError {
+    constructor(expected, received) {
+        super("SCHEMA_VERSION_MISMATCH", `Manifest version ${received} does not match expected version ${expected}`, "fatal", undefined);
+    }
+}
+exports.SchemaVersionMismatchError = SchemaVersionMismatchError;
+/** Error used when reading or parsing the manifest fails. */
+class ManifestLoadError extends LithiaError {
+    constructor(cause) {
+        super("MANIFEST_LOAD_ERROR", "Failed to load manifest.", "fatal", cause);
+    }
+}
+exports.ManifestLoadError = ManifestLoadError;
+/** Error raised when serving a static file but no MIME type is configured for its extension. */
+class StaticFileMimeMissingError extends LithiaError {
+    constructor(extension, filePath) {
+        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");
+    }
+}
+exports.StaticFileMimeMissingError = StaticFileMimeMissingError;
+/** Error raised when request data validation fails. */
+class ValidationError extends LithiaError {
+    issues;
+    constructor(message, issues) {
+        super("VALIDATION_ERROR", message, "error");
+        this.issues = issues;
+    }
+}
+exports.ValidationError = ValidationError;
+/** Error raised when a route module does not export a default async function. */
+class InvalidRouteModuleError extends LithiaError {
+    constructor(filePath, reason) {
+        super("INVALID_ROUTE_MODULE", `Invalid route module at '${filePath}': ${reason}. Route modules must export a default async function.`, "error");
+    }
+}
+exports.InvalidRouteModuleError = InvalidRouteModuleError;
+class InvalidEventModuleError extends LithiaError {
+    constructor(filePath, reason) {
+        super("INVALID_EVENT_MODULE", `Invalid event module at '${filePath}': ${reason}. Event modules must export a default function that accepts a Lithia instance.`, "error");
+    }
+}
+exports.InvalidEventModuleError = InvalidEventModuleError;
+/** Error raised when the server bootstrap module (_server.ts) is invalid. */
+class InvalidBootstrapModuleError extends LithiaError {
+    constructor(filePath, reason) {
+        super("INVALID_BOOTSTRAP_MODULE", `Invalid server bootstrap module at '${filePath}': ${reason}. The module must export a default async function.`, "fatal");
+    }
+}
+exports.InvalidBootstrapModuleError = InvalidBootstrapModuleError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAGA;;;;;GAKG;AACH,MAAa,WAAY,SAAQ,KAAK;IAG7B;IAGA;IAEA;IAPR;IACC,mCAAmC;IAC5B,IAAY,EACnB,OAAe;IACf,sBAAsB;IACf,QAA0B,OAAO;IACxC,iCAAiC;IAC1B,KAAW;QAElB,KAAK,CAAC,OAAO,CAAC,CAAC;QAPR,SAAI,GAAJ,IAAI,CAAQ;QAGZ,UAAK,GAAL,KAAK,CAA4B;QAEjC,UAAK,GAAL,KAAK,CAAM;QAGlB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAkB,CAAC,CAAC;IAC1D,CAAC;CACD;AAdD,kCAcC;AAED,+EAA+E;AAC/E,MAAa,0BAA2B,SAAQ,WAAW;IAC1D,YAAY,QAAgB,EAAE,QAAgB;QAC7C,KAAK,CACJ,yBAAyB,EACzB,oBAAoB,QAAQ,oCAAoC,QAAQ,EAAE,EAC1E,OAAO,EACP,SAAS,CACT,CAAC;IACH,CAAC;CACD;AATD,gEASC;AAED,6DAA6D;AAC7D,MAAa,iBAAkB,SAAQ,WAAW;IACjD,YAAY,KAAU;QACrB,KAAK,CAAC,qBAAqB,EAAE,0BAA0B,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1E,CAAC;CACD;AAJD,8CAIC;AAED,gGAAgG;AAChG,MAAa,0BAA2B,SAAQ,WAAW;IAC1D,YAAY,SAAiB,EAAE,QAAgB;QAC9C,KAAK,CACJ,0BAA0B,EAC1B,0CAA0C,SAAS,mBAAmB,QAAQ,2EAA2E,EACzJ,OAAO,CACP,CAAC;IACH,CAAC;CACD;AARD,gEAQC;AAED,uDAAuD;AACvD,MAAa,eAAgB,SAAQ,WAAW;IAGvC;IAFR,YACC,OAAe,EACR,MAAc;QAErB,KAAK,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAFrC,WAAM,GAAN,MAAM,CAAQ;IAGtB,CAAC;CACD;AAPD,0CAOC;AAED,iFAAiF;AACjF,MAAa,uBAAwB,SAAQ,WAAW;IACvD,YAAY,QAAgB,EAAE,MAAc;QAC3C,KAAK,CACJ,sBAAsB,EACtB,4BAA4B,QAAQ,MAAM,MAAM,uDAAuD,EACvG,OAAO,CACP,CAAC;IACH,CAAC;CACD;AARD,0DAQC;AAED,MAAa,uBAAwB,SAAQ,WAAW;IACvD,YAAY,QAAgB,EAAE,MAAc;QAC3C,KAAK,CACJ,sBAAsB,EACtB,4BAA4B,QAAQ,MAAM,MAAM,gFAAgF,EAChI,OAAO,CACP,CAAC;IACH,CAAC;CACD;AARD,0DAQC;AAED,6EAA6E;AAC7E,MAAa,2BAA4B,SAAQ,WAAW;IAC3D,YAAY,QAAgB,EAAE,MAAc;QAC3C,KAAK,CACJ,0BAA0B,EAC1B,uCAAuC,QAAQ,MAAM,MAAM,oDAAoD,EAC/G,OAAO,CACP,CAAC;IACH,CAAC;CACD;AARD,kEAQC"}

package/dist/hooks/dependency-hooks.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+ * ```
+ */
+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 declare function provide<T>(key: InjectionKey<T>, value: T): void;
+/**
+ * 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 declare function inject<T>(key: InjectionKey<T>): 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 declare function injectOptional<T>(key: InjectionKey<T>): T | undefined;

package/dist/hooks/dependency-hooks.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provide = provide;
+exports.inject = inject;
+exports.injectOptional = injectOptional;
+const lithia_context_1 = require("../context/lithia-context");
+/**
+ * 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();
+ * }
+ * ```
+ */
+function provide(key, value) {
+    (0, lithia_context_1.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;
+ * }
+ * ```
+ */
+function inject(key) {
+    const context = (0, lithia_context_1.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);
+}
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+function injectOptional(key) {
+    return (0, lithia_context_1.getLithiaContext)().dependencies.get(key);
+}
+//# sourceMappingURL=dependency-hooks.js.map

package/dist/hooks/dependency-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-hooks.js","sourceRoot":"","sources":["../../src/hooks/dependency-hooks.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAqDH,0BAEC;AAsBD,wBAQC;AAwBD,wCAEC;AA7GD,8DAA6D;AA4B7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,OAAO,CAAI,GAAoB,EAAE,KAAQ;IACxD,IAAA,iCAAgB,GAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,MAAM,CAAI,GAAoB;IAC7C,MAAM,OAAO,GAAG,IAAA,iCAAgB,GAAE,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACd,yBAAyB,MAAM,CAAC,GAAG,CAAC,8DAA8D,CAClG,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,cAAc,CAAI,GAAoB;IACrD,OAAO,IAAA,iCAAgB,GAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAkB,CAAC;AAClE,CAAC"}

package/dist/hooks/event-hooks.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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";
+/**
+ * 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 declare function useData<T>(): 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 declare function useSocket(): Socket;

package/dist/hooks/event-hooks.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useData = useData;
+exports.useSocket = useSocket;
+const event_context_1 = require("../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);
+ * }
+ * ```
+ */
+function useData() {
+    return (0, event_context_1.getEventContext)().data;
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+function useSocket() {
+    return (0, event_context_1.getEventContext)().socket;
+}
+//# sourceMappingURL=event-hooks.js.map

package/dist/hooks/event-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-hooks.js","sourceRoot":"","sources":["../../src/hooks/event-hooks.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAyBH,0BAEC;AAgCD,8BAEC;AA1DD,4DAA2D;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,OAAO;IACtB,OAAO,IAAA,+BAAe,GAAE,CAAC,IAAS,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,SAAS;IACxB,OAAO,IAAA,+BAAe,GAAE,CAAC,MAAM,CAAC;AACjC,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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;
+ * }
+ * ```
+ */
+export { type InjectionKey, inject, injectOptional, provide, } from "./dependency-hooks";
+export { useData } from "./event-hooks";
+export { useHeaders, useParams, useQuery, useRequest, useResponse, useRoute, useSocketServer, } from "./route-hooks";

package/dist/hooks/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSocketServer = exports.useRoute = exports.useResponse = exports.useRequest = exports.useQuery = exports.useParams = exports.useHeaders = exports.useData = exports.provide = exports.injectOptional = exports.inject = void 0;
+// Dependency injection hooks
+var dependency_hooks_1 = require("./dependency-hooks");
+Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return dependency_hooks_1.inject; } });
+Object.defineProperty(exports, "injectOptional", { enumerable: true, get: function () { return dependency_hooks_1.injectOptional; } });
+Object.defineProperty(exports, "provide", { enumerable: true, get: function () { return dependency_hooks_1.provide; } });
+// Socket.IO event hooks
+var event_hooks_1 = require("./event-hooks");
+Object.defineProperty(exports, "useData", { enumerable: true, get: function () { return event_hooks_1.useData; } });
+// HTTP Route hooks
+var route_hooks_1 = require("./route-hooks");
+Object.defineProperty(exports, "useHeaders", { enumerable: true, get: function () { return route_hooks_1.useHeaders; } });
+Object.defineProperty(exports, "useParams", { enumerable: true, get: function () { return route_hooks_1.useParams; } });
+Object.defineProperty(exports, "useQuery", { enumerable: true, get: function () { return route_hooks_1.useQuery; } });
+Object.defineProperty(exports, "useRequest", { enumerable: true, get: function () { return route_hooks_1.useRequest; } });
+Object.defineProperty(exports, "useResponse", { enumerable: true, get: function () { return route_hooks_1.useResponse; } });
+Object.defineProperty(exports, "useRoute", { enumerable: true, get: function () { return route_hooks_1.useRoute; } });
+Object.defineProperty(exports, "useSocketServer", { enumerable: true, get: function () { return route_hooks_1.useSocketServer; } });
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;AAEH,6BAA6B;AAC7B,uDAK4B;AAH3B,0GAAA,MAAM,OAAA;AACN,kHAAA,cAAc,OAAA;AACd,2GAAA,OAAO,OAAA;AAER,wBAAwB;AACxB,6CAAwC;AAA/B,sGAAA,OAAO,OAAA;AAChB,mBAAmB;AACnB,6CAQuB;AAPtB,yGAAA,UAAU,OAAA;AACV,wGAAA,SAAS,OAAA;AACT,uGAAA,QAAQ,OAAA;AACR,yGAAA,UAAU,OAAA;AACV,0GAAA,WAAW,OAAA;AACX,uGAAA,QAAQ,OAAA;AACR,8GAAA,eAAe,OAAA"}