@noxfly/noxus 3.0.0-dev.1 → 3.0.0-dev.11

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,151 +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>;
-        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 {
-        return new Proxy({} as object, {
-            get: (_obj, prop, receiver) => {
-                const realType = ref.forwardRefFn();
-                const instance = this.resolve(realType) as Record<string | symbol, unknown>;
-                const value = Reflect.get(instance, prop, receiver);
-                return typeof value === 'function' ? (value as Function).bind(instance) : value;
-            },
-            set: (_obj, prop, value, receiver) => {
-                const realType = ref.forwardRefFn();
-                const instance = this.resolve(realType) as object;
-                return Reflect.set(instance, prop, value, receiver);
-            },
-            getPrototypeOf: () => {
-                const realType = ref.forwardRefFn();
-                return (realType as unknown as { prototype: object }).prototype;
-            },
-        }) 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');
-
-/**
- * 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,143 +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, Middleware } from "src/main";
-
-export interface PendingRegistration {
-    key: TokenKey;
-    implementation: Type<unknown>;
-    lifetime: Lifetime;
-    deps: ReadonlyArray<TokenKey>;
-    isController: boolean;
-    pathPrefix?: string;
-}
-
-/**
- * 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;
-
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-
-    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.
-     */
-    public static flushAccumulated(
-        routeGuards: Guard[] = [],
-        routeMiddlewares: Middleware[] = [],
-        pathPrefix = '',
-    ): void {
-        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);
-    }
-
-    // -------------------------------------------------------------------------
-    // 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: resolve singletons and register controllers in the router. */
-    private static _phaseTwo(
-        queue: PendingRegistration[],
-        overrides?: Map<TokenKey, unknown>,
-        routeGuards: Guard[] = [],
-        routeMiddlewares: Middleware[] = [],
-    ): void {
-        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) {
-                // Lazily import Router to avoid circular dependency at module load time
-                const { Router } = require('../internal/router') as { Router: { prototype: { registerController(t: Type<unknown>): void } } };
-                const router = RootInjector.resolve(Router as any) as { registerController(t: Type<unknown>, pathPrefix: string, routeGuards: Guard[], routeMiddlewares: Middleware[]): void };
-                router.registerController(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) {
-            const { Router } = require('../internal/router') as { Router: { prototype: { registerController(t: Type<unknown>): void } } };
-            const router = RootInjector.resolve(Router as any) as { registerController(t: Type<unknown>): void };
-            router.registerController(reg.implementation);
-        }
-    }
-}

package/src/DI/token.ts

@@ -1,53 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Type } from '../utils/types';
-
-/**
- * A DI token uniquely identifies a dependency.
- * It can wrap a class (Type<T>) or be a named symbol token.
- *
- * Using tokens instead of reflect-metadata means dependencies are
- * declared explicitly — no magic type inference, no emitDecoratorMetadata.
- *
- * @example
- * // Class token (most common)
- * const MY_SERVICE = token(MyService);
- *
- * // Named symbol token (for interfaces or non-class values)
- * const DB_URL = token<string>('DB_URL');
- */
-export class Token<T> {
-    public readonly description: string;
-
-    constructor(
-        public readonly target: Type<T> | string,
-    ) {
-        this.description = typeof target === 'string' ? target : target.name;
-    }
-
-    public toString(): string {
-        return `Token(${this.description})`;
-    }
-}
-
-/**
- * Creates a DI token for a class type or a named value.
- *
- * @example
- * export const MY_SERVICE = token(MyService);
- * export const DB_URL = token<string>('DB_URL');
- */
-export function token<T>(target: Type<T> | string): Token<T> {
-    return new Token<T>(target);
-}
-
-/**
- * The key used to look up a class token in the registry.
- * For class tokens, the key is the class constructor itself.
- * For named tokens, the key is the Token instance.
- */
-export type TokenKey<T = unknown> = Type<T> | Token<T>;

package/src/decorators/controller.decorator.ts

@@ -1,58 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { InjectorExplorer } from '../DI/injector-explorer';
-import { TokenKey } from '../DI/token';
-import { Type } from '../utils/types';
-
-export interface ControllerOptions {
-    /**
-     * Explicit constructor dependencies.
-     */
-    deps?: ReadonlyArray<TokenKey>;
-}
-
-export interface IControllerMetadata {
-    deps: ReadonlyArray<TokenKey>;
-}
-
-const controllerMetaMap = new WeakMap<object, IControllerMetadata>();
-
-/**
- * Marks a class as a Noxus controller.
- * Controllers are always scope-scoped injectables.
- * The route prefix and guards/middlewares are declared in defineRoutes(), not here.
- *
- * @example
- * @Controller({ deps: [UserService] })
- * export class UserController {
- *   constructor(private svc: UserService) {}
- *
- *   @Get('byId/:userId')
- *   getUserById(req: Request) { ... }
- * }
- */
-export function Controller(options: ControllerOptions = {}): ClassDecorator {
-    return (target) => {
-        const meta: IControllerMetadata = {
-            deps: options.deps ?? [],
-        };
-
-        controllerMetaMap.set(target, meta);
-
-        InjectorExplorer.enqueue({
-            key: target as unknown as Type<unknown>,
-            implementation: target as unknown as Type<unknown>,
-            lifetime: 'scope',
-            deps: options.deps ?? [],
-            isController: true,
-        });
-    };
-}
-
-export function getControllerMetadata(target: object): IControllerMetadata | undefined {
-    return controllerMetaMap.get(target);
-}

package/src/decorators/guards.decorator.ts

@@ -1,15 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Request } from '../internal/request';
-import { MaybeAsync } from '../utils/types';
-
-/**
- * A guard decides whether an incoming request should reach the handler.
- * Implement this interface and pass the class to @Controller({ guards }) or @Get('path', { guards }).
- */
-
-export type Guard = (request: Request) => MaybeAsync<boolean>;

package/src/decorators/injectable.decorator.ts

@@ -1,81 +0,0 @@
-/**
- * @copyright 2025 NoxFly
- * @license MIT
- * @author NoxFly
- */
-
-import { Lifetime } from '../DI/app-injector';
-import { InjectorExplorer } from '../DI/injector-explorer';
-import { Token, TokenKey } from '../DI/token';
-import { Type } from '../utils/types';
-
-export interface InjectableOptions {
-    /**
-     * Lifetime of this injectable.
-     * @default 'scope'
-     */
-    lifetime?: Lifetime;
-
-    /**
-     * Explicit list of constructor dependencies, in the same order as the constructor parameters.
-     * Each entry is either a class constructor or a Token created with token().
-     *
-     * This replaces reflect-metadata / emitDecoratorMetadata entirely.
-     *
-     * @example
-     * @Injectable({ lifetime: 'singleton', deps: [MyRepo, DB_URL] })
-     * class MyService {
-     *   constructor(private repo: MyRepo, private dbUrl: string) {}
-     * }
-     */
-    deps?: ReadonlyArray<TokenKey>;
-}
-
-/**
- * Marks a class as injectable into the Noxus DI container.
- *
- * Unlike the v2 @Injectable, this decorator:
- * - Does NOT require reflect-metadata or emitDecoratorMetadata.
- * - Requires you to declare deps explicitly when the class has constructor parameters.
- * - Supports standalone usage — no module declaration needed.
- *
- * @example
- * // No dependencies
- * @Injectable()
- * class Logger {}
- *
- * // With dependencies
- * @Injectable({ lifetime: 'singleton', deps: [Logger, MyRepo] })
- * class MyService {
- *   constructor(private logger: Logger, private repo: MyRepo) {}
- * }
- *
- * // With a named token
- * const DB_URL = token<string>('DB_URL');
- *
- * @Injectable({ deps: [DB_URL] })
- * class DbService {
- *   constructor(private url: string) {}
- * }
- */
-export function Injectable(options: InjectableOptions = {}): ClassDecorator {
-    const { lifetime = 'scope', deps = [] } = options;
-
-    return (target) => {
-        if (typeof target !== 'function' || !target.prototype) {
-            throw new Error(`@Injectable can only be applied to classes, not ${typeof target}`);
-        }
-
-        const key = target as unknown as Type<unknown>;
-
-        InjectorExplorer.enqueue({
-            key,
-            implementation: key,
-            lifetime,
-            deps,
-            isController: false,
-        });
-    };
-}
-
-export { Token, TokenKey };