@lithia-js/core 1.0.0-canary.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @lithia-js/core@1.0.0-canary.0 build /home/runner/work/lithia/lithia/packages/core
+> tsc -p tsconfig.build.json
+

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @lithia-js/core
+
+## 1.0.0-canary.0
+
+### Major Changes
+
+- e9a0904: Lithia v1 canary release. Now with separated modules and napi bindings for build performance
+
+### Patch Changes
+
+- Updated dependencies [e9a0904]
+  - @lithia-js/native@1.0.0-canary.0
+  - @lithia-js/utils@1.0.0-canary.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lithiajs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+<div align="center">
+  <a href="https://github.com/lithia-framework/lithia">
+    <img alt="Lithia logo" src="https://raw.githubusercontent.com/lithia-framework/lithia/canary/.github/assets/logo.svg" height="128">
+  </a>
+  <h1>Lithia</h1>
+  <p><strong>The Node.js framework that makes API development feel like magic</strong></p>
+
+<a href="https://www.npmjs.com/package/lithia"><img alt="NPM version" src="https://img.shields.io/npm/v/lithia.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://github.com/lithia-framework/lithia/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/lithia.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://opencollective.com/lithiajs"><img alt="Support Lithia" src="https://img.shields.io/badge/Support%20Lithia-blueviolet.svg?style=for-the-badge&logo=OpenCollective&labelColor=000000&logoWidth=20"></a>
+
+</div>
+
+## Getting Started
+
+Lithia is a next-generation Node.js framework that enables you to build powerful APIs with file-based routing, built-in WebSocket support, and a beautiful development interface.
+
+- Visit our [Learn Lithia](https://lithiajs.com/docs) guide to get started.
+- Check out the [Examples](https://github.com/lithia-framework/lithia/tree/main/examples) to see Lithia in action.
+
+## Documentation
+
+Visit [https://lithiajs.com/docs](https://lithiajs.com/docs) to view the full documentation.
+
+## Community
+
+The Lithia community can be found on [GitHub Discussions](https://github.com/lithia-framework/lithia/discussions) where you can ask questions, voice ideas, and share your projects with other people.
+
+## Contributing
+
+Contributions to Lithia are welcome and highly appreciated. However, before you jump right into it, we would like you to review our [Contribution Guidelines](CONTRIBUTING.md) to make sure you have a smooth experience contributing to Lithia.
+
+---
+
+## Support the Project
+
+If Lithia makes your life easier, consider supporting it:
+
+- **Star** this repository
+- **Share** on social media
+- **Sponsor** via [OpenCollective](https://opencollective.com/lithiajs)
+- **Report bugs** and suggest improvements
+
+---
+
+## License
+
+Lithia is [MIT licensed](LICENSE). Free for personal and commercial use.
+
+---
+
+<div align="center">
+  <p><strong>Built with ❤️ by the Lithia community</strong></p>
+  <p>
+    <a href="https://github.com/lithia-framework/lithia">GitHub</a> •
+    <a href="https://lithiajs.com">Documentation</a> •
+    <a href="https://opencollective.com/lithiajs">OpenCollective</a> •
+    <a href="https://github.com/lithia-framework/lithia/discussions">Discussions</a>
+  </p>
+</div>

package/dist/config.d.ts

@@ -0,0 +1,101 @@
+import type { DeepPartial } from "@lithia-js/utils";
+import { type C12InputConfig, type WatchConfigOptions } from "c12";
+/** 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 declare const DEFAULT_CONFIG: LithiaConfig;
+type LoadConfigOptions = {
+    watch?: boolean;
+    c12?: WatchConfigOptions;
+    overrides?: LithiaConfig;
+};
+/** Error thrown when configuration validation fails. */
+export declare class ConfigValidationError extends Error {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/** 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 declare 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.
+     */
+    loadConfig(overrides?: LithiaConfig, opts?: LoadConfigOptions): Promise<LithiaOptions>;
+    /**
+     * Watch the configuration for changes and invoke `onChange` when updates occur.
+     *
+     * Returns a handle with a `close()` method to stop watching.
+     */
+    watchConfig(onChange: (ctx: ConfigUpdateContext) => void | Promise<void>, overrides?: LithiaConfig, opts?: LoadConfigOptions): Promise<{
+        close: () => void;
+    }>;
+    private validateConfig;
+}
+/** Utility helper used by users to define their config with IDE type hints. */
+export declare function defineConfig(config: LithiaConfig): LithiaConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigProvider = exports.ConfigValidationError = exports.DEFAULT_CONFIG = void 0;
+exports.defineConfig = defineConfig;
+const c12_1 = require("c12");
+const klona_1 = require("klona");
+/** Default runtime configuration used when no overrides are provided. */
+exports.DEFAULT_CONFIG = {
+    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,
+    },
+};
+/** Error thrown when configuration validation fails. */
+class ConfigValidationError extends Error {
+    field;
+    constructor(message, field) {
+        super(message);
+        this.field = field;
+        this.name = "ConfigValidationError";
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+/** Provider responsible for loading and optionally watching the runtime config. */
+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 = {}, opts = {}) {
+        overrides = (0, klona_1.klona)(overrides);
+        const configOptions = {
+            name: "lithia",
+            configFile: "lithia.config",
+            cwd: process.cwd(),
+            dotenv: true,
+            overrides,
+            defaults: exports.DEFAULT_CONFIG,
+            ...opts.c12,
+        };
+        const loadedConfig = await (0, c12_1.loadConfig)(configOptions);
+        const options = (0, klona_1.klona)(loadedConfig.config);
+        // 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, overrides = {}, opts = {}) {
+        overrides = (0, klona_1.klona)(overrides);
+        const configOptions = {
+            name: "lithia",
+            configFile: "lithia.config",
+            cwd: process.cwd(),
+            dotenv: true,
+            overrides,
+            defaults: exports.DEFAULT_CONFIG,
+            ...opts.c12,
+            watch: true,
+            onUpdate: async (context) => {
+                const newOptions = (0, klona_1.klona)(context.newConfig.config);
+                this.validateConfig(newOptions);
+                await onChange({
+                    getDiff: context.getDiff,
+                    newConfig: newOptions,
+                    oldConfig: context.oldConfig.config,
+                });
+            },
+        };
+        const handle = await (0, c12_1.watchConfig)(configOptions);
+        return {
+            close: () => {
+                if (typeof handle?.close === "function") {
+                    handle.close();
+                }
+            },
+        };
+    }
+    validateConfig(config) {
+        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");
+        }
+    }
+}
+exports.ConfigProvider = ConfigProvider;
+/** Utility helper used by users to define their config with IDE type hints. */
+function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

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

@@ -0,0 +1,53 @@
+/**
+ * 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 declare const eventContext: 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 declare function getEventContext(): EventContext;

package/dist/context/event-context.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../src/context/event-context.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAkDH,0CAQC;AAxDD,uDAAqD;AA0BrD;;;;;;;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,qFAAqF,CACrF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/context/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+export { type EventContext, eventContext, getEventContext, } from "./event-context";
+export { getLithiaContext, type LithiaContext, lithiaContext, } from "./lithia-context";
+export { getRouteContext, type RouteContext, routeContext, } from "./route-context";

package/dist/context/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeContext = exports.getRouteContext = exports.lithiaContext = exports.getLithiaContext = exports.getEventContext = exports.eventContext = void 0;
+// Socket.IO event context
+var event_context_1 = require("./event-context");
+Object.defineProperty(exports, "eventContext", { enumerable: true, get: function () { return event_context_1.eventContext; } });
+Object.defineProperty(exports, "getEventContext", { enumerable: true, get: function () { return event_context_1.getEventContext; } });
+// Lithia global context
+var lithia_context_1 = require("./lithia-context");
+Object.defineProperty(exports, "getLithiaContext", { enumerable: true, get: function () { return lithia_context_1.getLithiaContext; } });
+Object.defineProperty(exports, "lithiaContext", { enumerable: true, get: function () { return lithia_context_1.lithiaContext; } });
+// HTTP route context
+var route_context_1 = require("./route-context");
+Object.defineProperty(exports, "getRouteContext", { enumerable: true, get: function () { return route_context_1.getRouteContext; } });
+Object.defineProperty(exports, "routeContext", { enumerable: true, get: function () { return route_context_1.routeContext; } });
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,0BAA0B;AAC1B,iDAIyB;AAFxB,6GAAA,YAAY,OAAA;AACZ,gHAAA,eAAe,OAAA;AAEhB,wBAAwB;AACxB,mDAI0B;AAHzB,kHAAA,gBAAgB,OAAA;AAEhB,+GAAA,aAAa,OAAA;AAEd,qBAAqB;AACrB,iDAIyB;AAHxB,gHAAA,eAAe,OAAA;AAEf,6GAAA,YAAY,OAAA"}

package/dist/context/lithia-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare const lithiaContext: 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 declare function getLithiaContext(): LithiaContext;

package/dist/context/lithia-context.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"lithia-context.js","sourceRoot":"","sources":["../../src/context/lithia-context.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA0CH,4CAQC;AAhDD,uDAAqD;AAkBrD;;;;;;;GAOG;AACU,QAAA,aAAa,GAAG,IAAI,oCAAiB,EAAiB,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,SAAgB,gBAAgB;IAC/B,MAAM,GAAG,GAAG,qBAAa,CAAC,QAAQ,EAAE,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACd,iGAAiG,CACjG,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/context/route-context.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 declare const routeContext: 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 declare function getRouteContext(): RouteContext;