@mxweb/core 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.2] - 2024-12-18
+
+### Changed
+
+- **Build**: Improved terser configuration for logger module
+  - Added custom `terserWithOptions()` plugin for file-specific minification
+  - Logger module now keeps console calls while still being minified
+  - Other modules continue to have console calls removed during minification
+  - Added `loggerMinifyOptions` with `drop_console: false` for logger
+
+## [1.0.1] - 2024-12-16
+
+### Changed
+
+- **Config**: Refactored `forRoot()` to return a factory function for lazy initialization via `InjectRegistry`
+  - `forRoot()` now accepts optional `name` parameter for custom inject naming
+  - Updated to use new `InjectRegistry` pattern with `registry.set(name, factory)`
+  - Improved type safety for `get()` and `getAsync()` methods with conditional return types
+
+- **Application**: Major refactoring of dependency injection system
+  - Changed `ApplicationInjects` from object/async function to `InjectFactory[]` array
+  - Added `InjectRegistry` wrapper for safe inject registration (`get`/`set` only)
+  - Implemented lazy initialization - inject instances created on first `getInject()` call
+  - Added `getInject()` (async) and `getInjectSync()` methods for accessing injects
+  - Injects are now stored as `InjectEntry` with factory and lazy instance
+
+- **ExecuteContext**: Added support for lazy inject initialization
+  - Added `setRegistry()` method to set registry reference
+  - Changed `getInject()` to async method for lazy initialization
+  - Added `getInjectSync()` for synchronous access (only if already initialized)
+  - Added `isInjectInitialized()` method to check inject state
+  - Injects stored as `InjectEntry` with factory and optional instance
+  - Changed `getLocalInject()` to async method for lazy initialization
+  - Added `getLocalInjectSync()` for synchronous access to feature injects
+
+- **Feature**: Refactored feature inject system to use factory pattern
+  - Changed `FeatureInjects` from object to `FeatureInjectFactory[]` array
+  - Added `FeatureInjectRegistry` wrapper for safe inject registration
+  - Implemented lazy initialization - inject instances created on first `getInject()` call
+  - Added `getInjectSync()` for synchronous access (only if already initialized)
+  - Added `isInjectInitialized()` method to check inject state
+  - Lifecycle hooks (`onFeature`, `onFeatureDestroy`) now called at appropriate times
+
+- **Service**: Updated inject methods for async pattern
+  - Changed `getInject()` to async method returning `Promise<T | undefined>`
+  - Added `getInjectSync()` for synchronous access (only if already initialized)
+
+- **Decorator**: Updated inject decorators for async pattern
+  - Changed `Inject()` to async function returning `Promise<T | undefined>`
+  - Added `InjectSync()` for synchronous access (only if already initialized)
+
+- **Common**: Added new types for improved dependency injection
+  - Added `InjectInstanceFactory<T>` - factory function type that receives `InjectRegistry`
+  - Added `InjectEntry<T>` - entry containing factory and lazily-initialized instance
+  - Added `InjectRegistry` interface - wrapper with `get`/`set` methods only
+  - Updated `InjectFactory` type to work with new `InjectRegistry`
+  - Added `FeatureInjectInstanceFactory<T>` - factory function for feature injects
+  - Added `FeatureInjectEntry<T>` - entry for feature inject factory and instance
+  - Added `FeatureInjectRegistry` interface - wrapper for feature inject registration
+  - Added `FeatureInjectFactory` type for feature inject factories
+
+## [1.0.0] - 2024-12-16
+
+### Added
+
+- Initial release of `@mxweb/core` framework
+- Configuration management system (`Config` class) with:
+  - Synchronous and asynchronous configuration providers
+  - Lazy evaluation of configuration factories
+  - Singleton pattern for consistent configuration
+  - Support for default values in `get()` and `getAsync()` methods
+  - `getOrThrow()` and `getAsyncOrThrow()` methods for required configurations
+  - `has()` method to check configuration existence
+  - `getAll()` method to retrieve all built configurations
+  - `reset()` method for testing purposes

package/dist/application.d.ts

@@ -2,48 +2,58 @@ import { NextRequest } from "next/server";
 import { Feature } from "./feature";
 import { Filter, Guard, Interceptor } from "./execute";
 import { ApplicationHooksOptions } from "./hooks";
-import { ApplicationInject, AsyncFn, Pipe, RoutePayload } from "./common";
+import { ApplicationInject, InjectEntry, InjectFactory, InjectRegistry, Pipe, RoutePayload } from "./common";
 /**
  * Type for application-level dependency injection configuration.
- * Can be either a plain object or an async function that returns the injects object.
+ * An array of inject factory functions that register injects via InjectRegistry.
  *
- * @example
- * // Plain object
- * const injects: ApplicationInjects = {
- *   db: new DatabaseConnection(),
- *   config: Config.forRoot(),
- * };
+ * @remarks
+ * Uses the new factory pattern for lazy initialization of injects.
+ * Each factory receives an InjectRegistry to register its inject.
  *
- * // Async function
- * const injects: ApplicationInjects = async () => ({
- *   db: await Connection.create(),
- * });
+ * @example
+ * ```ts
+ * const injects: ApplicationInjects = [
+ *   Config.forRoot(),           // Registers "config" inject
+ *   Database.forRoot("db"),     // Registers "db" inject
+ *   async (registry) => {       // Custom factory
+ *     const config = await registry.get<Config>("config");
+ *     registry.set("cache", () => new Cache(config));
+ *   },
+ * ];
+ * ```
  */
-export type ApplicationInjects = AsyncFn<Record<string, ApplicationInject>>;
+export type ApplicationInjects = InjectFactory[];
 /**
  * Type for CORS origins configuration.
  * Can be a static array of allowed origins or a function that dynamically resolves origins.
  *
  * @example
+ * ```ts
  * // Static origins
  * const cors: ApplicationCors = ["https://example.com", "https://api.example.com"];
  *
- * // Dynamic origins from config
- * const cors: ApplicationCors = async (injects) => {
- *   const config = injects.get("config");
- *   return config.get("allowedOrigins");
+ * // Dynamic origins from registry
+ * const cors: ApplicationCors = async (registry) => {
+ *   const config = await registry.get<Config>("config");
+ *   return config?.get<string[]>("allowedOrigins") ?? [];
  * };
+ * ```
  */
-export type ApplicationCors = string[] | ((injects: Map<string, ApplicationInject>) => string[] | Promise<string[]>);
+export type ApplicationCors = string[] | ((registry: InjectRegistry) => string[] | Promise<string[]>);
 /**
  * Configuration options for creating an Application instance.
  *
  * @template Key - The key used to extract path segments from Next.js catch-all route params
  *
  * @example
+ * ```ts
  * const options: ApplicationOptions = {
  *   key: "path",
- *   injects: { db: Connection.forRoot() },
+ *   injects: [
+ *     Config.forRoot(),
+ *     Database.forRoot(),
+ *   ],
  *   guards: [AuthGuard],
  *   filters: [GlobalExceptionFilter],
  *   interceptors: [LoggingInterceptor],
@@ -53,11 +63,12 @@ export type ApplicationCors = string[] | ((injects: Map<string, ApplicationInjec
  *   onRequest: (req, method) => console.log(`${method} request`),
  *   onResponse: (ctx) => console.log("Response sent"),
  * };
+ * ```
  */
 export interface ApplicationOptions<Key extends string = "path"> extends ApplicationHooksOptions {
     /** The key used to extract path segments from catch-all route params. Defaults to "path". */
     key?: Key;
-    /** Global dependency injection configuration */
+    /** Array of inject factories for dependency injection */
     injects?: ApplicationInjects;
     /** Global guards applied to all routes */
     guards?: Guard[];
@@ -89,10 +100,10 @@ export interface ApplicationOptions<Key extends string = "path"> extends Applica
  * import "@/features/products/product.feature";
  *
  * const app = Application.create({
- *   injects: {
- *     db: Connection.forRoot(),
- *     config: Config.forRoot(),
- *   },
+ *   injects: [
+ *     Config.forRoot(),
+ *     Database.forRoot(),
+ *   ],
  *   guards: [AuthGuard],
  *   cors: ["https://example.com"],
  * });
@@ -150,42 +161,73 @@ export declare class Application<Key extends string = "path"> {
      */
     private constructor();
     /**
-     * Retrieves a global inject instance by name.
+     * Retrieves a global inject instance by name (async for lazy initialization).
+     *
+     * @template T - The type of the inject instance
+     * @param name - The name of the inject to retrieve
+     * @returns Promise resolving to the inject instance if found, undefined otherwise
+     *
+     * @example
+     * ```ts
+     * const db = await Application.getInject<DatabaseConnection>("db");
+     * const config = await Application.getInject<Config>("config");
+     * ```
+     */
+    static getInject<T extends ApplicationInject = ApplicationInject>(name: string): Promise<T | undefined>;
+    /**
+     * Retrieves a global inject instance by name (sync - only if already initialized).
      *
      * @template T - The type of the inject instance
      * @param name - The name of the inject to retrieve
-     * @returns The inject instance if found, undefined otherwise
+     * @returns The inject instance if found and initialized, undefined otherwise
      *
      * @example
-     * const db = Application.getInject<DatabaseConnection>("db");
-     * const config = Application.getInject<Config>("config");
+     * ```ts
+     * const config = Application.getInjectSync<Config>("config");
+     * ```
      */
-    static getInject<T extends ApplicationInject = ApplicationInject>(name: string): T | undefined;
+    static getInjectSync<T extends ApplicationInject = ApplicationInject>(name: string): T | undefined;
     /**
-     * Retrieves all registered global injects.
+     * Retrieves all registered global inject entries.
      *
-     * @returns A new Map containing all inject name-instance pairs
+     * @returns A new Map containing all inject name-entry pairs
+     *
+     * @remarks
+     * Entries contain factories and optionally initialized instances.
      *
      * @example
+     * ```ts
      * const injects = Application.getInjects();
-     * for (const [name, instance] of injects) {
-     *   console.log(`Inject: ${name}`);
+     * for (const [name, entry] of injects) {
+     *   console.log(`Inject: ${name}, initialized: ${!!entry.instance}`);
      * }
+     * ```
+     */
+    static getInjects(): Map<string, InjectEntry>;
+    /** Flag indicating if inject registry has been created */
+    private static registryCreated;
+    /** The InjectRegistry instance */
+    private static registry;
+    /**
+     * Creates the InjectRegistry wrapper for safe inject registration.
+     * This method is idempotent - subsequent calls return the same registry.
+     *
+     * @returns The InjectRegistry instance
      */
-    static getInjects(): Map<string, ApplicationInject>;
-    /** Flag indicating if injects have been loaded */
-    private static injectsLoaded;
+    private static createInjectRegistry;
+    /** Flag indicating if inject factories have been registered */
+    private static factoriesRegistered;
     /**
-     * Loads and initializes all application-level injects.
-     * This method is idempotent - subsequent calls will not reload injects.
+     * Registers all inject factories from options.
+     * This method is idempotent - subsequent calls will not re-register.
      *
      * @remarks
-     * - Supports both plain object and async function for injects configuration
-     * - Calls onInit lifecycle hook on each inject
-     * - Registers shutdown handlers after loading
-     * - Loads CORS configuration after injects are ready
+     * - Creates the InjectRegistry wrapper
+     * - Processes each factory in order (factories just register, don't create instances)
+     * - Registers shutdown handlers after all factories are registered
+     * - Loads CORS configuration (may need injects)
      */
-    private static loadInjects;
+    private static registerInjectFactories;
     /**
      * Registers process shutdown handlers for graceful cleanup.
      * Handles SIGTERM and SIGINT signals to properly destroy injects.
@@ -323,7 +365,7 @@ export declare class Application<Key extends string = "path"> {
      *
      * @remarks
      * The returned handler:
-     * 1. Loads application injects
+     * 1. Registers inject factories (lazy - instances created on first get)
      * 2. Initializes features
      * 3. Creates Application instance
      * 4. Executes application onRequest hook
@@ -341,7 +383,10 @@ export declare class Application<Key extends string = "path"> {
      * ```ts
      * const app = Application.create({
      *   key: "path",
-     *   injects: { db: Connection.forRoot() },
+     *   injects: [
+     *     Config.forRoot(),
+     *     Database.forRoot(),
+     *   ],
      *   guards: [AuthGuard],
      *   cors: ["https://example.com"],
      *   onStart: () => console.log("App started"),

package/dist/application.js

@@ -1 +1 @@
-"use strict";var e=require("./error.js"),t=require("./context.js"),s=require("./response.js"),r=require("./hooks.js"),o=require("./common.js");const n={key:"path"};class i{constructor(e,t,o){this.request=e,this.method=t,this.payload=o,this.feature=null,this.route=null,this.response=new s.ServerResponse,this.requestHooks=new r.RequestHooks(i.hooks)}static getInject(e){return t.executeContext.getInject(e)}static getInjects(){return new Map(t.executeContext.injections)}static async loadInjects(){if(this.injectsLoaded)return;const e=this.options.injects;if(!e)return void(this.injectsLoaded=!0);const s="function"==typeof e?await e():e;for(const[e,r]of Object.entries(s))"function"==typeof r.onInit&&await r.onInit(),t.executeContext.setInject(e,r);this.injectsLoaded=!0,this.registerShutdown(),await this.loadCors()}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.executeContext.injections)if("function"==typeof s.onDestroy)try{await s.onDestroy()}catch(e){}process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(t.executeContext.injections))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of i.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...i.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t.executeContext))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t.executeContext,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...i.filters];for(const r of s)try{const s=new r,o=await s.catch(e,t.executeContext);if(o instanceof Response)return o}catch{continue}return null}async executeInterceptors(e){const s=[...this.route?.route.getReflect().getInterceptors()??new Set,...i.interceptors];if(!s.length)return e();let r=e;for(let e=s.length-1;e>=0;e--){const o=new(0,s[e]),n=r;r=()=>o.intercept(t.executeContext,n)}return r()}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...i.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=i.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=i.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");if(!s)return e;const r=new Headers(e.headers);return t.includes("*")?r.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(r.set("Access-Control-Allow-Origin",s),r.set("Vary","Origin")),r.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),r.set("Access-Control-Allow-Headers","Content-Type, Authorization"),r.set("Access-Control-Max-Age","86400"),new Response(e.body,{status:e.status,statusText:e.statusText,headers:r})}async dispatch(){const s=this.route,r=this.feature,o=t.executeContext.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=r.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(o);const n=await this.executeInterceptors(()=>t(o));return this.response.success(n)}catch(t){const s=await this.executeFilters(t);if(s)return s;if(t instanceof e.HttpError){switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return this.response.internalServer(t)}return this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=i.options.key||n.key,o=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,o))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:o,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:o,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const a=await t.executeContext.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(a)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await i.loadInjects(),await i.loadImports();const r=new i(t,e,s);return await r.requestHooks.appRequest(t,e),await r.match.bind(r)()}}static create(e=n){return this.options=e,this.hooks=new r.ApplicationHooks(this.options),e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[o.RouteMethod.GET]:i.createHandler(o.RouteMethod.GET),[o.RouteMethod.POST]:i.createHandler(o.RouteMethod.POST),[o.RouteMethod.PUT]:i.createHandler(o.RouteMethod.PUT),[o.RouteMethod.PATCH]:i.createHandler(o.RouteMethod.PATCH),[o.RouteMethod.DELETE]:i.createHandler(o.RouteMethod.DELETE),[o.RouteMethod.HEAD]:i.createHeadHandler(),[o.RouteMethod.OPTIONS]:i.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await i.loadInjects(),await i.loadImports();const s=new i(e,o.RouteMethod.HEAD,t);await s.requestHooks.appRequest(e,o.RouteMethod.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await i.loadInjects();const t=this.corsOrigins,r=e.headers.get("origin"),o=s.ServerResponse.options();if(!t.length||!r)return o;const n=new Headers(o.headers);return t.includes("*")?n.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(n.set("Access-Control-Allow-Origin",r),n.set("Vary","Origin")),n.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),n.set("Access-Control-Allow-Headers","Content-Type, Authorization"),n.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:n})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}i.features=new Set,i.guards=new Set,i.filters=new Set,i.interceptors=new Set,i.pipes=new Set,i.corsOrigins=[],i.options=n,i.initialized=!1,i.initPromise=null,i.shutdownRegistered=!1,i.injectsLoaded=!1,exports.Application=i;
+"use strict";var e=require("./error.js"),t=require("./context.js"),s=require("./response.js"),r=require("./hooks.js"),n=require("./common.js");const o={key:"path"};class i{constructor(e,t,n){this.request=e,this.method=t,this.payload=n,this.feature=null,this.route=null,this.response=new s.ServerResponse,this.requestHooks=new r.RequestHooks(i.hooks)}static getInject(e){return t.executeContext.getInject(e)}static getInjectSync(e){return t.executeContext.getInjectSync(e)}static getInjects(){return new Map(t.executeContext.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.executeContext.getInject(e),set(e,s){t.executeContext.setInject(e,s)}},t.executeContext.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,this.registerShutdown(),await this.loadCors()}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.executeContext.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy()}catch(e){}process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of i.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...i.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t.executeContext))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t.executeContext,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...i.filters];for(const r of s)try{const s=new r,n=await s.catch(e,t.executeContext);if(n instanceof Response)return n}catch{continue}return null}async executeInterceptors(e){const s=[...this.route?.route.getReflect().getInterceptors()??new Set,...i.interceptors];if(!s.length)return e();let r=e;for(let e=s.length-1;e>=0;e--){const n=new(0,s[e]),o=r;r=()=>n.intercept(t.executeContext,o)}return r()}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...i.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=i.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=i.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");if(!s)return e;const r=new Headers(e.headers);return t.includes("*")?r.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(r.set("Access-Control-Allow-Origin",s),r.set("Vary","Origin")),r.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),r.set("Access-Control-Allow-Headers","Content-Type, Authorization"),r.set("Access-Control-Max-Age","86400"),new Response(e.body,{status:e.status,statusText:e.statusText,headers:r})}async dispatch(){const s=this.route,r=this.feature,n=t.executeContext.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=r.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(n);const o=await this.executeInterceptors(()=>t(n));return this.response.success(o)}catch(t){const s=await this.executeFilters(t);if(s)return s;if(t instanceof e.HttpError){switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return this.response.internalServer(t)}return this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=i.options.key||o.key,n=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,n))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:n,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:n,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const a=await t.executeContext.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(a)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await i.registerInjectFactories(),await i.loadImports();const r=new i(t,e,s);return await r.requestHooks.appRequest(t,e),await r.match.bind(r)()}}static create(e=o){return this.options=e,this.hooks=new r.ApplicationHooks(this.options),e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[n.RouteMethod.GET]:i.createHandler(n.RouteMethod.GET),[n.RouteMethod.POST]:i.createHandler(n.RouteMethod.POST),[n.RouteMethod.PUT]:i.createHandler(n.RouteMethod.PUT),[n.RouteMethod.PATCH]:i.createHandler(n.RouteMethod.PATCH),[n.RouteMethod.DELETE]:i.createHandler(n.RouteMethod.DELETE),[n.RouteMethod.HEAD]:i.createHeadHandler(),[n.RouteMethod.OPTIONS]:i.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await i.registerInjectFactories(),await i.loadImports();const s=new i(e,n.RouteMethod.HEAD,t);await s.requestHooks.appRequest(e,n.RouteMethod.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await i.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),n=s.ServerResponse.options();if(!t.length||!r)return n;const o=new Headers(n.headers);return t.includes("*")?o.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(o.set("Access-Control-Allow-Origin",r),o.set("Vary","Origin")),o.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),o.set("Access-Control-Allow-Headers","Content-Type, Authorization"),o.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:o})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}i.features=new Set,i.guards=new Set,i.filters=new Set,i.interceptors=new Set,i.pipes=new Set,i.corsOrigins=[],i.options=o,i.initialized=!1,i.initPromise=null,i.shutdownRegistered=!1,i.registryCreated=!1,i.factoriesRegistered=!1,exports.Application=i;

package/dist/application.mjs

@@ -1 +1 @@
-import{HttpError as e}from"./error.mjs";import{executeContext as t}from"./context.mjs";import{ServerResponse as s}from"./response.mjs";import{RequestHooks as r,ApplicationHooks as n}from"./hooks.mjs";import{RouteMethod as o}from"./common.mjs";const i={key:"path"};class a{constructor(e,t,n){this.request=e,this.method=t,this.payload=n,this.feature=null,this.route=null,this.response=new s,this.requestHooks=new r(a.hooks)}static getInject(e){return t.getInject(e)}static getInjects(){return new Map(t.injections)}static async loadInjects(){if(this.injectsLoaded)return;const e=this.options.injects;if(!e)return void(this.injectsLoaded=!0);const s="function"==typeof e?await e():e;for(const[e,r]of Object.entries(s))"function"==typeof r.onInit&&await r.onInit(),t.setInject(e,r);this.injectsLoaded=!0,this.registerShutdown(),await this.loadCors()}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.injections)if("function"==typeof s.onDestroy)try{await s.onDestroy()}catch(e){}process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(t.injections))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of a.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...a.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...a.filters];for(const r of s)try{const s=new r,n=await s.catch(e,t);if(n instanceof Response)return n}catch{continue}return null}async executeInterceptors(e){const s=[...this.route?.route.getReflect().getInterceptors()??new Set,...a.interceptors];if(!s.length)return e();let r=e;for(let e=s.length-1;e>=0;e--){const n=new(0,s[e]),o=r;r=()=>n.intercept(t,o)}return r()}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...a.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=a.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=a.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");if(!s)return e;const r=new Headers(e.headers);return t.includes("*")?r.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(r.set("Access-Control-Allow-Origin",s),r.set("Vary","Origin")),r.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),r.set("Access-Control-Allow-Headers","Content-Type, Authorization"),r.set("Access-Control-Max-Age","86400"),new Response(e.body,{status:e.status,statusText:e.statusText,headers:r})}async dispatch(){const s=this.route,r=this.feature,n=t.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=r.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(n);const o=await this.executeInterceptors(()=>t(n));return this.response.success(o)}catch(t){const s=await this.executeFilters(t);if(s)return s;if(t instanceof e){switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return this.response.internalServer(t)}return this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=a.options.key||i.key,n=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,n))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:n,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:n,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const o=await t.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(o)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await a.loadInjects(),await a.loadImports();const r=new a(t,e,s);return await r.requestHooks.appRequest(t,e),await r.match.bind(r)()}}static create(e=i){return this.options=e,this.hooks=new n(this.options),e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[o.GET]:a.createHandler(o.GET),[o.POST]:a.createHandler(o.POST),[o.PUT]:a.createHandler(o.PUT),[o.PATCH]:a.createHandler(o.PATCH),[o.DELETE]:a.createHandler(o.DELETE),[o.HEAD]:a.createHeadHandler(),[o.OPTIONS]:a.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await a.loadInjects(),await a.loadImports();const s=new a(e,o.HEAD,t);await s.requestHooks.appRequest(e,o.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await a.loadInjects();const t=this.corsOrigins,r=e.headers.get("origin"),n=s.options();if(!t.length||!r)return n;const o=new Headers(n.headers);return t.includes("*")?o.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(o.set("Access-Control-Allow-Origin",r),o.set("Vary","Origin")),o.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),o.set("Access-Control-Allow-Headers","Content-Type, Authorization"),o.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:o})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}a.features=new Set,a.guards=new Set,a.filters=new Set,a.interceptors=new Set,a.pipes=new Set,a.corsOrigins=[],a.options=i,a.initialized=!1,a.initPromise=null,a.shutdownRegistered=!1,a.injectsLoaded=!1;export{a as Application};
+import{HttpError as e}from"./error.mjs";import{executeContext as t}from"./context.mjs";import{ServerResponse as s}from"./response.mjs";import{RequestHooks as r,ApplicationHooks as n}from"./hooks.mjs";import{RouteMethod as i}from"./common.mjs";const o={key:"path"};class a{constructor(e,t,n){this.request=e,this.method=t,this.payload=n,this.feature=null,this.route=null,this.response=new s,this.requestHooks=new r(a.hooks)}static getInject(e){return t.getInject(e)}static getInjectSync(e){return t.getInjectSync(e)}static getInjects(){return new Map(t.injections)}static createInjectRegistry(){return this.registryCreated||(this.registry={get:async e=>t.getInject(e),set(e,s){t.setInject(e,s)}},t.setRegistry(this.registry),this.registryCreated=!0),this.registry}static async registerInjectFactories(){if(this.factoriesRegistered)return;const e=this.options.injects;if(!e||!e.length)return void(this.factoriesRegistered=!0);const t=this.createInjectRegistry();for(const s of e)await s(t);this.factoriesRegistered=!0,this.registerShutdown(),await this.loadCors()}static registerShutdown(){if(this.shutdownRegistered)return;this.shutdownRegistered=!0;const e=async()=>{for(const e of this.features)await e.destroyInjects();for(const[e,s]of t.injections)if(s.instance&&"function"==typeof s.instance.onDestroy)try{await s.instance.onDestroy()}catch(e){}process.exit(0)};process.on("SIGTERM",e),process.on("SIGINT",e)}static async loadCors(){const e=this.options.cors;e&&(Array.isArray(e)?this.corsOrigins=e:this.corsOrigins=await e(this.registry))}static async loadImports(){if(!this.initialized)return this.initPromise||(this.initPromise=(async()=>{this.initialized=!0})()),this.initPromise}isMatchFeature(e,t){for(const s of a.features)if(this.route=s.matchRoute(e,t),this.route)return this.feature=s,!0;return null}async executeGuards(){const e=this.route?.route.getReflect().getGuards()??new Set,s=[...a.guards,...e];if(!s.length)return!0;for(const e of s)try{const s=new e;if(!await s.canActivate(t))return!1}catch{return!1}return!0}async executeMiddlewares(){const e=this.route.route.getMiddlewares();if(!e.length)return!0;for(const s of e){let e=!1;const r=()=>{e=!0};try{if(await s(t,r),!e)return!1}catch{return!1}}return!0}async executeFilters(e){const s=[...this.route?.route.getReflect().getFilters()??new Set,...a.filters];for(const r of s)try{const s=new r,n=await s.catch(e,t);if(n instanceof Response)return n}catch{continue}return null}async executeInterceptors(e){const s=[...this.route?.route.getReflect().getInterceptors()??new Set,...a.interceptors];if(!s.length)return e();let r=e;for(let e=s.length-1;e>=0;e--){const n=new(0,s[e]),i=r;r=()=>n.intercept(t,i)}return r()}async executePipes(e){const t=this.route?.route.getReflect().getPipes()??new Set,s=[...a.pipes,...t];if(!s.length)return e;let r=e;for(const e of s){const t=new e;r=await t.transform(r)}return r}checkCors(){const e=a.corsOrigins;if(!e.length)return!0;const t=this.request.headers.get("origin");return!t||(e.includes("*")||e.includes(t))}applyCorsHeaders(e){const t=a.corsOrigins;if(!t.length)return e;const s=this.request.headers.get("origin");if(!s)return e;const r=new Headers(e.headers);return t.includes("*")?r.set("Access-Control-Allow-Origin","*"):t.includes(s)&&(r.set("Access-Control-Allow-Origin",s),r.set("Vary","Origin")),r.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),r.set("Access-Control-Allow-Headers","Content-Type, Authorization"),r.set("Access-Control-Max-Age","86400"),new Response(e.body,{status:e.status,statusText:e.statusText,headers:r})}async dispatch(){const s=this.route,r=this.feature,n=t.getContextOrThrow();try{if(!await this.executeGuards())return this.response.forbidden();if(!await this.executeMiddlewares())return this.response.forbidden();const e=s.route.getAction();let t=null;if("string"==typeof e){const s=r.getController();"function"==typeof s._initDependencies&&await s._initDependencies(),"function"==typeof s[e]&&(t=s[e].bind(s))}else"function"==typeof e&&(t=e);if(!t)return this.response.internalServer(new Error("Route action handler not found"));await this.executePipes(n);const i=await this.executeInterceptors(()=>t(n));return this.response.success(i)}catch(t){const s=await this.executeFilters(t);if(s)return s;if(t instanceof e){switch(t.statusCode){case 400:return this.response.badRequest(t.message,t.error);case 401:return this.response.unauthorized(t.message,t.error);case 403:return this.response.forbidden(t.message,t.error);case 404:return this.response.notFound(t.message,t.error);case 409:return this.response.conflict(t.message,t.error);case 422:return this.response.unprocessableEntity(t.message,t.error);case 429:return this.response.tooManyRequests(t.message,t.error);case 501:return this.response.notImplemented(t.message,t.error);case 502:return this.response.badGateway(t.message,t.error);case 503:return this.response.serviceUnavailable(t.message,t.error);case 504:return this.response.gatewayTimeout(t.message,t.error)}return this.response.internalServer(t)}return this.response.internalServer(t)}}async match(){let e=null;try{if(!this.checkCors())return this.applyCorsHeaders(this.response.forbidden("CORS not allowed"));const s=await this.payload.params,r=a.options.key||o.key,n=s?.[r]?.join("/")||"";if(!this.isMatchFeature(this.method,n))return this.applyCorsHeaders(this.response.notFound("Route not found",{method:this.method,path:n,params:s}));await this.feature.loadInjects(),e={req:this.request,res:this.response,method:this.method,path:n,params:this.route.params,wildcards:this.route.wildcards,reflect:this.route.route.getReflect(),feature:this.feature},this.requestHooks.setFeatureHooks(this.feature.getHooks()),await this.requestHooks.featureRequest(e);const i=await t.run(e,()=>this.dispatch());return await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e),this.applyCorsHeaders(i)}catch(t){return e&&(await this.requestHooks.featureResponse(e),await this.requestHooks.appResponse(e)),this.applyCorsHeaders(this.response.internalServer(t))}}static createHandler(e){return async(t,s)=>{await a.registerInjectFactories(),await a.loadImports();const r=new a(t,e,s);return await r.requestHooks.appRequest(t,e),await r.match.bind(r)()}}static create(e=o){return this.options=e,this.hooks=new n(this.options),e.guards&&e.guards.forEach(e=>this.guards.add(e)),e.filters&&e.filters.forEach(e=>this.filters.add(e)),e.interceptors&&e.interceptors.forEach(e=>this.interceptors.add(e)),e.pipes&&e.pipes.forEach(e=>this.pipes.add(e)),{[i.GET]:a.createHandler(i.GET),[i.POST]:a.createHandler(i.POST),[i.PUT]:a.createHandler(i.PUT),[i.PATCH]:a.createHandler(i.PATCH),[i.DELETE]:a.createHandler(i.DELETE),[i.HEAD]:a.createHeadHandler(),[i.OPTIONS]:a.createOptionsHandler()}}static createHeadHandler(){return async(e,t)=>{await a.registerInjectFactories(),await a.loadImports();const s=new a(e,i.HEAD,t);await s.requestHooks.appRequest(e,i.HEAD);const r=await s.match.bind(s)();return new Response(null,{status:r.status,statusText:r.statusText,headers:r.headers})}}static createOptionsHandler(){return async e=>{await a.registerInjectFactories();const t=this.corsOrigins,r=e.headers.get("origin"),n=s.options();if(!t.length||!r)return n;const i=new Headers(n.headers);return t.includes("*")?i.set("Access-Control-Allow-Origin","*"):t.includes(r)&&(i.set("Access-Control-Allow-Origin",r),i.set("Vary","Origin")),i.set("Access-Control-Allow-Methods","GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"),i.set("Access-Control-Allow-Headers","Content-Type, Authorization"),i.set("Access-Control-Max-Age","86400"),new Response(null,{status:204,headers:i})}}static register(...e){return e.forEach(e=>this.features.add(e)),this}}a.features=new Set,a.guards=new Set,a.filters=new Set,a.interceptors=new Set,a.pipes=new Set,a.corsOrigins=[],a.options=o,a.initialized=!1,a.initPromise=null,a.shutdownRegistered=!1,a.registryCreated=!1,a.factoriesRegistered=!1;export{a as Application};

package/dist/common.d.ts

@@ -1,3 +1,4 @@
+import { Callback } from "@mxweb/utils";
 /**
  * @fileoverview Common types, interfaces, and utilities used throughout the @mxweb/core framework.
  * This module provides foundational types for dependency injection, routing, and lifecycle management.
@@ -73,6 +74,77 @@ export interface FeatureInject {
      */
     onFeatureDestroy?(): void | Promise<void>;
 }
+/**
+ * Factory function that creates a feature inject instance.
+ * Receives the registry to access other feature injects.
+ *
+ * @template T - The type of the inject instance (must extend FeatureInject)
+ *
+ * @example
+ * ```ts
+ * const repoFactory: FeatureInjectInstanceFactory<ProductRepository> = async (registry) => {
+ *   const db = await registry.get<DatabaseConnection>("db");
+ *   return new ProductRepository(db!);
+ * };
+ * ```
+ */
+export type FeatureInjectInstanceFactory<T extends FeatureInject = FeatureInject> = (registry: FeatureInjectRegistry) => T | Promise<T>;
+/**
+ * Entry stored in the feature injection map.
+ * Contains factory and lazily-initialized instance.
+ *
+ * @template T - The type of the inject instance (must extend FeatureInject)
+ */
+export interface FeatureInjectEntry<T extends FeatureInject = FeatureInject> {
+    /** Factory function to create the instance */
+    factory: FeatureInjectInstanceFactory<T>;
+    /** Lazily-initialized instance (undefined until first access) */
+    instance?: T;
+}
+/**
+ * Wrapper object for feature inject registration.
+ * Only exposes get/set to prevent accidental removal.
+ *
+ * @remarks
+ * This interface is passed to feature inject factories to allow them to
+ * access other injects and register themselves.
+ */
+export interface FeatureInjectRegistry {
+    /**
+     * Retrieves a feature inject by name (async for lazy initialization).
+     *
+     * @template T - The expected type of the inject
+     * @param name - The name of the inject to retrieve
+     * @returns Promise resolving to the inject instance or undefined
+     */
+    get<T extends FeatureInject = FeatureInject>(name: string): Promise<T | undefined>;
+    /**
+     * Registers a feature inject factory by name.
+     *
+     * @template T - The type of the inject instance
+     * @param name - The name to register the inject under
+     * @param factory - Factory function that creates the inject instance
+     */
+    set<T extends FeatureInject = FeatureInject>(name: string, factory: FeatureInjectInstanceFactory<T>): void;
+}
+/**
+ * Factory function that registers feature injects via the registry.
+ * Used in Feature.create({ injects: [...] }) array.
+ *
+ * @example
+ * ```ts
+ * const feature = Feature.create({
+ *   controller: ProductController,
+ *   router: Router.register(...),
+ *   injects: [
+ *     (registry) => {
+ *       registry.set("productRepo", () => new ProductRepository());
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export type FeatureInjectFactory = Callback<void | Promise<void>, [FeatureInjectRegistry]>;
 /**
  * Utility type for values that can be either synchronous or async.
  * Commonly used for configuration that may need async resolution.
@@ -301,6 +373,83 @@ export declare class InjectionRegistry {
      */
     static hasInstance(name: string): boolean;
 }
+/**
+ * Factory function that creates an inject instance.
+ * Receives the registry to access other injects.
+ *
+ * @template T - The type of the inject instance (must extend ApplicationInject)
+ *
+ * @example
+ * ```ts
+ * const dbFactory: InjectInstanceFactory<DatabaseConnection> = async (registry) => {
+ *   const config = await registry.get<Config>("config");
+ *   return new DatabaseConnection(config?.get("dbUrl"));
+ * };
+ * ```
+ */
+export type InjectInstanceFactory<T extends ApplicationInject = ApplicationInject> = (registry: InjectRegistry) => T | Promise<T>;
+/**
+ * Entry stored in the injection map.
+ * Contains factory and lazily-initialized instance.
+ *
+ * @template T - The type of the inject instance (must extend ApplicationInject)
+ */
+export interface InjectEntry<T extends ApplicationInject = ApplicationInject> {
+    /** Factory function to create the instance */
+    factory: InjectInstanceFactory<T>;
+    /** Lazily-initialized instance (undefined until first access) */
+    instance?: T;
+}
+/**
+ * Wrapper object for inject registration.
+ * Only exposes get/set to prevent accidental removal.
+ *
+ * @remarks
+ * This interface is passed to inject factories to allow them to
+ * access other injects and register themselves.
+ *
+ * @example
+ * ```ts
+ * Config.forRoot("config"); // Returns (registry: InjectRegistry) => void
+ *
+ * // Inside the factory:
+ * registry.set("config", () => new Config());
+ * const db = await registry.get<Database>("db");
+ * ```
+ */
+export interface InjectRegistry {
+    /**
+     * Retrieves an inject by name (async for lazy initialization).
+     *
+     * @template T - The expected type of the inject
+     * @param name - The name of the inject to retrieve
+     * @returns Promise resolving to the inject instance or undefined
+     */
+    get<T extends ApplicationInject = ApplicationInject>(name: string): Promise<T | undefined>;
+    /**
+     * Registers an inject factory by name.
+     *
+     * @template T - The type of the inject instance
+     * @param name - The name to register the inject under
+     * @param factory - Factory function that creates the inject instance
+     */
+    set<T extends ApplicationInject = ApplicationInject>(name: string, factory: InjectInstanceFactory<T>): void;
+}
+/**
+ * Factory function that registers injects via the registry.
+ * Used in Application.create({ injects: [...] }) array.
+ *
+ * @example
+ * ```ts
+ * const app = Application.create({
+ *   injects: [
+ *     Config.forRoot(),      // Returns InjectFactory
+ *     Database.forRoot(),    // Returns InjectFactory
+ *   ],
+ * });
+ * ```
+ */
+export type InjectFactory = Callback<void | Promise<void>, [InjectRegistry]>;
 /**
  * Enumeration of supported HTTP methods.
  * Used throughout the framework for route matching and handler creation.