@noxfly/noxus 3.0.0-dev.4 → 3.0.0-dev.5

package/.github/copilot-instructions.md

@@ -1,128 +0,0 @@
-# Copilot Instructions
-
-## Core Architecture
-- bootstrapApplication in [src/internal/bootstrap.ts](src/internal/bootstrap.ts) waits for Electron app readiness, applies log level config, wires the controller registrar, flushes DI, resolves NoxApp, registers routes and eager-loads, then returns a configured instance.
-- [src/internal/app.ts](src/internal/app.ts) wires ipcMain events, spawns paired request/socket MessageChannels per renderer, and delegates handling to Router and NoxSocket.
-- Package exports are split between renderer and main targets in [package.json](package.json); import Electron main APIs from @noxfly/noxus/main, renderer helpers from @noxfly/noxus or @noxfly/noxus/renderer, and preload helpers from @noxfly/noxus/preload.
-- Dependency injection centers on RootInjector in [src/DI/app-injector.ts](src/DI/app-injector.ts); @Injectable triggers auto-registration through [src/DI/injector-explorer.ts](src/DI/injector-explorer.ts) and supports singleton, scope, and transient lifetimes.
-- resetRootInjector() in [src/DI/app-injector.ts](src/DI/app-injector.ts) clears all bindings, singletons, and scoped instances — use it in tests to get a clean DI state between test suites.
-- There is no Module decorator — controllers and services are standalone, registered via @Injectable and @Controller decorators with explicit deps arrays.
-
-## Request Lifecycle
-- Request objects from [src/internal/request.ts](src/internal/request.ts) wrap Electron MessageEvents and spawn per-request DI scopes on Request.context. They expose params, body, and query (Record<string, string>).
-- Router in [src/internal/router.ts](src/internal/router.ts) indexes routes in a radix tree, merges controller-level and method-level decorators, and enforces root middlewares, route middlewares, then guards before invoking controller actions.
-- The radix tree in [src/utils/radix-tree.ts](src/utils/radix-tree.ts) prioritizes static segments over parameter segments during search, so `addNote/:id` won't be shadowed by `:id`.
-- ResponseException subclasses in [src/internal/exceptions.ts](src/internal/exceptions.ts) propagate status codes; throwing one short-circuits the pipeline so Router returns a structured error payload.
-- Batch requests use HTTP method BATCH and normalization logic in Router.handleBatch; payloads must satisfy IBatchRequestPayload to fan out atomic subrequests.
-
-## Communication Channels
-- ipcMain listens for gimme-my-port and posts two transferable ports back to the renderer: index 0 carries request/response traffic, index 1 is reserved for socket-style push messages.
-- NoxSocket in [src/internal/socket.ts](src/internal/socket.ts) maps sender IDs to {request, socket} channels and emits renderer events exclusively through channels.socket.port1. emit() returns void.
-- Renderer helpers in [src/internal/renderer-events.ts](src/internal/renderer-events.ts) expose RendererEventRegistry.tryDispatchFromMessageEvent to route push events; the preload script must start both ports and hand the second to this registry.
-- Renderer-facing bootstrap lives in [src/internal/renderer-client.ts](src/internal/renderer-client.ts); NoxRendererClient requests ports, wires request/socket handlers, tracks pending promises with configurable timeout (default 10s), and surfaces RendererEventRegistry for push consumption.
-- Preload scripts should call exposeNoxusBridge from [src/internal/preload-bridge.ts](src/internal/preload-bridge.ts) to publish window.noxus.requestPort; the helper sends 'gimme-my-port' and forwards both transferable ports with the configured init message.
-- When adjusting preload or renderer glue, ensure window.postMessage('init-port', ...) forwards both ports so the socket channel stays alive alongside the request channel.
-
-## Route Definitions
-- defineRoutes in [src/internal/routes.ts](src/internal/routes.ts) is the single source of truth for routing. It validates for duplicate and overlapping prefixes and supports nested children with inherited guards/middlewares.
-- Parent routes can omit the load function and serve only as shared prefix containers for children.
-- flattenRoutes recursively merges parent guards and middlewares into each child before validation.
-
-## Decorator Conventions
-- Controller paths omit leading/trailing slashes; method decorators (Get, Post, etc.) auto-trim segments via [src/decorators/method.decorator.ts](src/decorators/method.decorator.ts).
-- Guards registered through Authorize in [src/decorators/guards.decorator.ts](src/decorators/guards.decorator.ts) aggregate at controller and action scope; they must resolve truthy or Router throws UnauthorizedException.
-- Injectable lifetimes default to scope; use singleton for app-wide utilities (window managers, sockets) and transient for short-lived resources.
-
-## Dependency Injection Internals
-- InjectorExplorer in [src/DI/injector-explorer.ts](src/DI/injector-explorer.ts) accumulates registrations at import time and flushes in two phases (bind then resolve).
-- To avoid a circular dependency between InjectorExplorer and Router, controller registration is decoupled via a ControllerRegistrar callback set by bootstrapApplication through setControllerRegistrar(). There is no require() call.
-- flushAccumulated is serialized through a Promise-based lock (loadingLock) to prevent concurrent lazy module loads from corrupting the queue. Use waitForFlush() to await completion.
-- Phase 2 validates that declared deps have a corresponding binding or singleton, and emits warnings for missing ones at startup.
-
-## Logging and Utilities
-- Logger in [src/utils/logger.ts](src/utils/logger.ts) standardizes color-coded log, warn, error, and comment output; it supports configurable log levels via Logger.setLogLevel() and file output via Logger.enableFileLogging().
-- bootstrapApplication accepts a logLevel option ('debug' | 'info' | 'none' | LogLevel[]) to control framework verbosity.
-- Path resolution relies on RadixTree from [src/utils/radix-tree.ts](src/utils/radix-tree.ts); normalize controller and route paths to avoid duplicate slashes.
-- Request.params are filled by Router.extractParams; Request.query carries query parameters passed from the renderer; controllers read both directly from the Request object.
-
-## Build and Tooling
-- Run npm run build to invoke tsup with dual ESM/CJS outputs configured in [tsup.config.ts](tsup.config.ts); the postbuild script at [scripts/postbuild.js](scripts/postbuild.js) deduplicates license banners.
-- Node 20 or newer is required; no reflect-metadata is needed — all dependency information comes from explicit deps arrays.
-- Source uses baseUrl ./ with tsc-alias, so prefer absolute imports like src/module/file when editing framework code to match existing style.
-- Dist artifacts live under dist/ and are published outputs; regenerate them via the build script rather than editing directly.
-
-
-## Validating TypeScript changes
-
-MANDATORY: Always check for compilation errors before running any tests or validation scripts, or declaring work complete, then fix all compilation errors before moving forward.
-
-## Coding Guidelines
-
-### Indentation
-
-Use spaces, 4 for any file type, except yml that are 2 spaces.
-
-### Naming Conventions
-
-    Use PascalCase for type names
-    Use PascaleCase for class names and interfaces
-    Prefix interface names by an 'I'
-    Use PascalCase for enum values
-    Choose wisely enum over union types or consts
-    Prefer interfaces over types when possible
-    Use camelCase for function and method names
-    Use camelCase for property names and local variables
-    Use whole words in names when possible
-    Use kebab-case for file names, and avoid using the same name for multiple files in different directories to prevent confusion
-    suffix file names with their type (e.g., .service.ts, .controller.ts, .component.ts) to make it clear what the file contains and its role in the architecture
-
-### Types
-
-    Do not export types or functions unless you need to share it across multiple components
-    Do not introduce new types or values to the global namespace unless they are truly global concepts
-
-### Comments
-
-    Use JSDoc style comments for functions, interfaces, enums, and classes
-    Always include a description of what the function/class/interface/enum does, its parameters, its return value and an example (if applicable)
-    Use inline comments to explain why a particular implementation was chosen, especially if it's not obvious. Avoid stating what the code is doing, and instead focus on the reasoning behind it.
-
-### Strings
-
-    Always use "double quotes" for strings.
-    Use template literals for string interpolation and multi-line strings instead of concatenation.
-
-### Style
-
-    Use arrow functions => over anonymous function expressions.
-    Only surround arrow function parameters when necessary.
-    Only surround arrow function bodies with curly braces when they are not a direct return of an expression.
-    Always surround loop and conditional bodies with curly braces.
-    Open curly braces always go on the same line as whatever necessitates them
-    Use StrouStrup style for control statements (the else is on a new line after the closing brace of the if).
-    Whenever possible, use in top-level scopes export function x(…) {…} instead of export const x = (…) => {…}. One advantage of using the function keyword is that the stack-trace shows a good name when debugging.
-
-### Code Quality
-
-    All files must include the NoxFly copyright header
-    Prefer async and await over Promise and then calls
-    Always await a promise to make the function appearable in the stack trace, unless you have a good reason not to (e.g., you want it to run in the background and don't care about errors).
-    Look for existing test patterns before creating new structures
-    Prefer regex capture groups with names over numbered capture groups.
-    If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task
-    Never duplicate imports. Always reuse existing imports if they are present.
-    When removing an import, do not leave behind blank lines where the import was. Ensure the surrounding code remains compact.
-    Do not use any or unknown as the type for variables, parameters, or return values unless absolutely necessary. If they need type annotations, they should have proper types or interfaces defined.
-    Do not duplicate code. Always look for existing utility functions, helpers, or patterns in the codebase before implementing new functionality. Reuse and extend existing code whenever possible.
-    Avoid using bind(), call() and apply() solely to control this or partially apply arguments; prefer arrow functions or closures to capture the necessary context, and use these methods only when required by an API or interoperability.
-    Always think for the most performant code for future scalability, even if it requires more upfront work. Consider time and space complexity when designing algorithms and data structures, and prefer efficient patterns that will scale well as the codebase grows.
-    Always specify the `public`, `private`, or `protected` access modifier for class members, even if the default is public. This improves readability and makes the intended encapsulation clear to other developers.
-    Always use explicit return types for functions and methods, even when TypeScript can infer them. This improves readability and helps catch unintended return values or changes in the function's behavior over time.
-    Avoid using non-null assertions (!). Instead, handle potential null or undefined values explicitly through type guards, default values, or proper error handling to ensure safer and more robust code.
-    Always prefer composition over inheritance. Favor creating small, reusable functions and classes that can be combined to achieve complex behavior, rather than relying on deep inheritance hierarchies which can lead to tight coupling and reduced flexibility.
-    Always use strict equality (=== and !==) instead of loose equality (== and !=) to avoid unexpected type coercion and ensure more predictable comparisons.
-    Always ensure readme and copilot-instructions files are updated to reflect any architectural, structural, or convention changes made to the codebase. These documents serve as the primary reference for other developers and must accurately represent the current state of the project.
-    Do not hesitate to refactor existing code to improve readability, maintainability, or performance, even if it is not directly related to the task at hand. Continuous improvement of the codebase is essential for long-term success and developer satisfaction.
-    Do not hesitate to ask for help or clarification if a request is unclear.
-    Do not hesitate to suggest improvements or optimizations if you see an opportunity, even if it's outside the scope of your current task.
-    Always write unit tests for new functionality and bug fixes, and ensure existing tests are updated as necessary to reflect changes in the codebase. Aim for high test coverage and meaningful test cases that validate the expected behavior of the code.

package/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-    "typescript.tsdk": "node_modules\\typescript\\lib"
-}

package/AGENTS.md

@@ -1,5 +0,0 @@
-# Agents
-
-All project conventions, architecture details, and coding guidelines are maintained in the [Copilot Instructions](.github/copilot-instructions.md) file.
-
-Please refer to that file for context before making changes to this codebase.

package/eslint.config.js

@@ -1,109 +0,0 @@
-// @ts-nocheck
-const eslint = require("@eslint/js");
-const tseslint = require("typescript-eslint");
-const stylistic = require("@stylistic/eslint-plugin");
-
-module.exports = tseslint.config(
-    {
-        files: ["src/**/*.ts"],
-        extends: [
-            eslint.configs.recommended,
-            ...tseslint.configs.recommended,
-            ...tseslint.configs.stylistic,
-        ],
-        languageOptions: {
-            parserOptions: {
-                ecmaVersion: 2020,
-                sourceType: "module",
-                project: ["./tsconfig.json"],
-                tsconfigRootDir: __dirname,
-            }
-        },
-        plugins: {
-            "@stylistic": stylistic,
-        },
-        rules: {
-            "@typescript-eslint/no-empty-object-type": "off",
-
-            "@typescript-eslint/no-require-imports": "off",
-
-            "@typescript-eslint/explicit-member-accessibility": [
-                "error",
-                {
-                    "overrides": {
-                        "constructors": "no-public",
-                    }
-                }
-            ],
-            "@typescript-eslint/explicit-function-return-type": [
-                "error",
-                {
-                    "allowExpressions": true,
-                    "allowHigherOrderFunctions": true,
-                    "allowIIFEs": true,
-                }
-            ],
-            "@typescript-eslint/consistent-type-definitions": "off",
-            "@typescript-eslint/no-explicit-any": "off",
-            "@typescript-eslint/no-inferrable-types": "off",
-            "@typescript-eslint/no-empty-function": "off",
-            "@typescript-eslint/no-unused-vars": "off",
-            "@typescript-eslint/no-namespace": "off",
-            "@typescript-eslint/no-unsafe-function-type": "off",
-            "@typescript-eslint/prefer-readonly": "warn",
-
-            "@stylistic/object-curly-spacing": ["warn", "always"],
-            "@stylistic/no-whitespace-before-property": "error",
-            "@stylistic/space-before-blocks": ["warn", "always"],
-            "@stylistic/comma-spacing": [
-                "warn",
-                {
-                    "before": false,
-                    "after": true
-                }
-            ],
-            "@stylistic/block-spacing": ["warn", "always"],
-            "@stylistic/brace-style": [
-                "error",
-                "stroustrup",
-                {
-                    "allowSingleLine": true
-                }
-            ],
-            "@stylistic/function-call-spacing": ["error", "never"],
-            "@stylistic/arrow-spacing": "error",
-            "@stylistic/computed-property-spacing": "warn",
-            "@stylistic/generator-star-spacing": "error",
-            "@stylistic/indent": ["error", 4, { "SwitchCase": 1 }],
-            "@stylistic/semi": [2, "always"],
-            "@stylistic/no-extra-semi": "warn",
-            "@stylistic/semi-spacing": "warn",
-            "@stylistic/quotes": "off",
-            "@stylistic/keyword-spacing": [
-                "warn",
-                {
-                    "overrides": {
-                        "if": { "after": false },
-                        "for": { "after": false },
-                        "catch": { "after": false },
-                        "while": { "after": false },
-                        "as": { "after": false },
-                        "switch": { "after": false }
-                    }
-                }
-            ],
-
-            "eqeqeq": "error",
-            "no-duplicate-imports": "error",
-            "no-empty": "off",
-            "no-empty-function": "off",
-            "no-extra-boolean-cast": "off",
-            "no-inner-declarations": "off",
-            "no-unsafe-finally": "off",
-            "no-unsafe-optional-chaining": "error",
-            "no-unused-vars": "off",
-            "no-var": "error",
-            "no-useless-catch": "off",
-        },
-    },
-);

package/scripts/postbuild.js

@@ -1,31 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-function uniqueDocBlocks(filepath) {
-    if(!fs.existsSync(filepath)) {
-        return;
-    }
-
-    const content = fs.readFileSync(filepath, 'utf8');
-
-    const reg = /\/\*\*[\t ]*\n(?: \*.*\n)*? \* *@copyright.*\n(?: \*.*\n)*? \*\/\n?/gm;
-
-    let first = true;
-    const deduped = content.replace(reg, (match) => {
-        if (first) {
-            first = false;
-            return match; // keep the first
-        }
-        return ''; // remove others
-    });
-
-    fs.writeFileSync(filepath, deduped);
-}
-
-const distDir = path.join(__dirname, '../dist');
-
-for(const filename of fs.readdirSync(distDir)) {
-    if(filename.endsWith('.d.ts') || filename.endsWith('.d.mts')) {
-        uniqueDocBlocks(path.join(distDir, filename));
-    }
-}

package/src/DI/app-injector.ts

@@ -1,173 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { ForwardReference } from '../utils/forward-ref';
-import { Type } from '../utils/types';
-import { Token, TokenKey } from './token';
-
-/**
- * Lifetime of a binding in the DI container.
- * - singleton: created once, shared for the lifetime of the app.
- * - scope:     created once per request scope.
- * - transient: new instance every time it is resolved.
- */
-export type Lifetime = 'singleton' | 'scope' | 'transient';
-
-/**
- * Internal representation of a registered binding.
- */
-export interface IBinding<T = unknown> {
-    lifetime: Lifetime;
-    implementation: Type<T>;
-    /** Explicit constructor dependencies, declared by the class itself. */
-    deps: ReadonlyArray<TokenKey>;
-    instance?: T;
-}
-
-function keyOf<T>(k: TokenKey<T>): Type<T> | Token<T> {
-    return k;
-}
-
-/**
- * AppInjector is the core DI container.
- * It no longer uses reflect-metadata — all dependency information
- * comes from explicitly declared `deps` arrays on each binding.
- */
-export class AppInjector {
-    public readonly bindings = new Map<Type<unknown> | Token<unknown>, IBinding<unknown>>();
-    public readonly singletons = new Map<Type<unknown> | Token<unknown>, unknown>();
-    public readonly scoped = new Map<Type<unknown> | Token<unknown>, unknown>();
-
-    constructor(public readonly name: string | null = null) {}
-
-    /**
-     * Creates a child scope for per-request lifetime resolution.
-     */
-    public createScope(): AppInjector {
-        const scope = new AppInjector();
-        (scope as any).bindings = this.bindings;
-        (scope as any).singletons = this.singletons;
-        return scope;
-    }
-
-    /**
-     * Registers a binding explicitly.
-     */
-    public register<T>(
-        key: TokenKey<T>,
-        implementation: Type<T>,
-        lifetime: Lifetime,
-        deps: ReadonlyArray<TokenKey> = [],
-    ): void {
-        const k = keyOf(key) as TokenKey<unknown>;
-        if (!this.bindings.has(k)) {
-            this.bindings.set(k, { lifetime, implementation: implementation as Type<unknown>, deps });
-        }
-    }
-
-    /**
-     * Resolves a dependency by token or class reference.
-     */
-    public resolve<T>(target: TokenKey<T> | ForwardReference<T>): T {
-        if (target instanceof ForwardReference) {
-            return this._resolveForwardRef(target);
-        }
-
-        const k = keyOf(target) as TokenKey<unknown>;
-
-        if (this.singletons.has(k)) {
-            return this.singletons.get(k) as T;
-        }
-
-        const binding = this.bindings.get(k);
-
-        if (!binding) {
-            const name = target instanceof Token
-                ? target.description
-                : (target as Type<unknown>).name
-                ?? 'unknown';
-
-            throw new Error(
-                `[Noxus DI] No binding found for "${name}".\n`
-                + `Did you forget to declare it in @Injectable({ deps }) or in bootstrapApplication({ singletons })?`,
-            );
-        }
-
-        switch (binding.lifetime) {
-            case 'transient':
-                return this._instantiate(binding) as T;
-
-            case 'scope': {
-                if (this.scoped.has(k)) return this.scoped.get(k) as T;
-                const inst = this._instantiate(binding);
-                this.scoped.set(k, inst);
-                return inst as T;
-            }
-
-            case 'singleton': {
-                if (this.singletons.has(k)) return this.singletons.get(k) as T;
-                const inst = this._instantiate(binding);
-                this.singletons.set(k, inst);
-                if (binding.instance === undefined) {
-                    (binding as IBinding<unknown>).instance = inst as unknown;
-                }
-                return inst as T;
-            }
-        }
-    }
-
-    // -------------------------------------------------------------------------
-
-    private _resolveForwardRef<T>(ref: ForwardReference<T>): T {
-        let resolved: T | undefined;
-        return new Proxy({} as object, {
-            get: (_obj, prop, receiver) => {
-                resolved ??= this.resolve(ref.forwardRefFn()) as T;
-                const value = Reflect.get(resolved as object, prop, receiver);
-                return typeof value === 'function' ? (value as Function).bind(resolved) : value;
-            },
-            set: (_obj, prop, value, receiver) => {
-                resolved ??= this.resolve(ref.forwardRefFn()) as T;
-                return Reflect.set(resolved as object, prop, value, receiver);
-            },
-            getPrototypeOf: () => {
-                resolved ??= this.resolve(ref.forwardRefFn()) as T;
-                return Object.getPrototypeOf(resolved);
-            },
-        }) as T;
-    }
-
-    private _instantiate<T>(binding: IBinding<T>): T {
-        const resolvedDeps = binding.deps.map((dep) => this.resolve(dep));
-        return new binding.implementation(...resolvedDeps) as T;
-    }
-}
-
-/**
- * The global root injector. All singletons live here.
- */
-export const RootInjector = new AppInjector('root');
-
-/**
- * Resets the root injector to a clean state.
- * **Intended for testing only** — clears all bindings, singletons, and scoped instances
- * so that each test can start from a fresh DI container without restarting the process.
- */
-export function resetRootInjector(): void {
-    RootInjector.bindings.clear();
-    RootInjector.singletons.clear();
-    RootInjector.scoped.clear();
-    // Lazy import to avoid circular dependency (InjectorExplorer → app-injector → InjectorExplorer)
-    const { InjectorExplorer } = require('./injector-explorer') as typeof import('./injector-explorer');
-    InjectorExplorer.reset();
-}
-
-/**
- * Convenience function: resolve a token from the root injector.
- */
-export function inject<T>(t: TokenKey<T> | ForwardReference<T>): T {
-    return RootInjector.resolve(t);
-}

package/src/DI/injector-explorer.ts

@@ -1,201 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Lifetime, RootInjector } from './app-injector';
-import { TokenKey } from './token';
-import { Type } from '../utils/types';
-import { Logger } from '../utils/logger';
-import { Guard } from '../decorators/guards.decorator';
-import { Middleware } from '../decorators/middleware.decorator';
-
-export interface PendingRegistration {
-    key: TokenKey;
-    implementation: Type<unknown>;
-    lifetime: Lifetime;
-    deps: ReadonlyArray<TokenKey>;
-    isController: boolean;
-    pathPrefix?: string;
-}
-
-/**
- * Callback invoked for each controller registration discovered during flush.
- * Decouples InjectorExplorer from the Router to avoid circular imports.
- */
-export type ControllerRegistrar = (
-    controllerClass: Type<unknown>,
-    pathPrefix: string,
-    routeGuards: Guard[],
-    routeMiddlewares: Middleware[],
-) => void;
-
-/**
- * InjectorExplorer accumulates registrations emitted by decorators
- * at import time, then flushes them in two phases (bind → resolve)
- * once bootstrapApplication triggers processing.
- *
- * Because deps are now explicit arrays (no reflect-metadata), this class
- * no longer needs to introspect constructor parameter types.
- */
-export class InjectorExplorer {
-    private static readonly pending: PendingRegistration[] = [];
-    private static processed = false;
-    private static accumulating = false;
-    private static loadingLock: Promise<void> = Promise.resolve();
-    private static controllerRegistrar: ControllerRegistrar | null = null;
-
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-
-    /**
-     * Sets the callback used to register controllers.
-     * Must be called once before processPending (typically by bootstrapApplication).
-     */
-    public static setControllerRegistrar(registrar: ControllerRegistrar): void {
-        InjectorExplorer.controllerRegistrar = registrar;
-    }
-
-    public static enqueue(reg: PendingRegistration): void {
-        if (InjectorExplorer.processed && !InjectorExplorer.accumulating) {
-            InjectorExplorer._registerImmediate(reg);
-            return;
-        }
-        InjectorExplorer.pending.push(reg);
-    }
-
-    /**
-     * Two-phase flush of all pending registrations collected at startup.
-     * Called by bootstrapApplication after app.whenReady().
-     */
-    public static processPending(singletonOverrides?: Map<TokenKey, unknown>): void {
-        const queue = [...InjectorExplorer.pending];
-        InjectorExplorer.pending.length = 0;
-
-        InjectorExplorer._phaseOne(queue);
-        InjectorExplorer._phaseTwo(queue, singletonOverrides);
-
-        InjectorExplorer.processed = true;
-    }
-
-    /** Enters accumulation mode for lazy-loaded batches. */
-    public static beginAccumulate(): void {
-        InjectorExplorer.accumulating = true;
-    }
-
-    /**
-     * Exits accumulation mode and flushes queued registrations
-     * with the same two-phase guarantee as processPending.
-     * Serialised through a lock to prevent concurrent lazy loads from corrupting the queue.
-     */
-    public static flushAccumulated(
-        routeGuards: Guard[] = [],
-        routeMiddlewares: Middleware[] = [],
-        pathPrefix = '',
-    ): Promise<void> {
-        InjectorExplorer.loadingLock = InjectorExplorer.loadingLock.then(() => {
-            InjectorExplorer.accumulating = false;
-            const queue = [...InjectorExplorer.pending];
-            InjectorExplorer.pending.length = 0;
-            InjectorExplorer._phaseOne(queue);
-
-            // Stamp the path prefix on controller registrations
-            for (const reg of queue) {
-                if (reg.isController) reg.pathPrefix = pathPrefix;
-            }
-
-            InjectorExplorer._phaseTwo(queue, undefined, routeGuards, routeMiddlewares);
-        });
-
-        return InjectorExplorer.loadingLock;
-    }
-
-    /**
-     * Returns a Promise that resolves once all pending flushAccumulated calls
-     * have completed. Useful for awaiting lazy-load serialisation.
-     */
-    public static waitForFlush(): Promise<void> {
-        return InjectorExplorer.loadingLock;
-    }
-
-    /**
-     * Resets the explorer state. Intended for tests only.
-     */
-    public static reset(): void {
-        InjectorExplorer.pending.length = 0;
-        InjectorExplorer.processed = false;
-        InjectorExplorer.accumulating = false;
-        InjectorExplorer.loadingLock = Promise.resolve();
-        InjectorExplorer.controllerRegistrar = null;
-    }
-
-    // -------------------------------------------------------------------------
-    // Private helpers
-    // -------------------------------------------------------------------------
-
-    /** Phase 1: register all bindings without instantiating anything. */
-    private static _phaseOne(queue: PendingRegistration[]): void {
-        for (const reg of queue) {
-            RootInjector.register(reg.key, reg.implementation, reg.lifetime, reg.deps);
-        }
-    }
-
-    /** Phase 2: validate deps, resolve singletons and register controllers via the registrar callback. */
-    private static _phaseTwo(
-        queue: PendingRegistration[],
-        overrides?: Map<TokenKey, unknown>,
-        routeGuards: Guard[] = [],
-        routeMiddlewares: Middleware[] = [],
-    ): void {
-        // Early dependency validation: warn about deps that have no binding
-        for (const reg of queue) {
-            for (const dep of reg.deps) {
-                if (!RootInjector.bindings.has(dep as any) && !RootInjector.singletons.has(dep as any)) {
-                    Logger.warn(`[Noxus DI] "${reg.implementation.name}" declares dep "${(dep as any).name ?? dep}" which has no binding`);
-                }
-            }
-        }
-
-        for (const reg of queue) {
-            // Apply value overrides (e.g. singleton instances provided via bootstrapApplication config)
-            if (overrides?.has(reg.key)) {
-                const override = overrides.get(reg.key);
-                RootInjector.singletons.set(reg.key as any, override);
-                Logger.log(`Registered ${reg.implementation.name} as singleton (overridden)`);
-                continue;
-            }
-
-            if (reg.lifetime === 'singleton') {
-                RootInjector.resolve(reg.key);
-            }
-
-            if (reg.isController) {
-                if (!InjectorExplorer.controllerRegistrar) {
-                    throw new Error('[Noxus DI] No controller registrar set. Call InjectorExplorer.setControllerRegistrar() before processing.');
-                }
-                InjectorExplorer.controllerRegistrar(
-                    reg.implementation,
-                    reg.pathPrefix ?? '',
-                    routeGuards,
-                    routeMiddlewares,
-                );
-            } else if (reg.lifetime !== 'singleton') {
-                Logger.log(`Registered ${reg.implementation.name} as ${reg.lifetime}`);
-            }
-        }
-    }
-
-    private static _registerImmediate(reg: PendingRegistration): void {
-        RootInjector.register(reg.key, reg.implementation, reg.lifetime, reg.deps);
-
-        if (reg.lifetime === 'singleton') {
-            RootInjector.resolve(reg.key);
-        }
-
-        if (reg.isController && InjectorExplorer.controllerRegistrar) {
-            InjectorExplorer.controllerRegistrar(reg.implementation, '', [], []);
-        }
-    }
-}