@nexus-ioc/core 0.4.1 → 0.6.1

package/dist/types/decorators/injectable.d.ts

@@ -0,0 +1,37 @@
+import "reflect-metadata";
+import type { InjectableOptions } from "../interfaces";
+/**
+ * Marks a class as injectable, making it available for dependency injection.
+ *
+ * This decorator must be applied to any class that you want to use as a provider
+ * in the IoC container. It configures the scope and other options for the provider.
+ *
+ * @param options - Configuration options for the injectable
+ * @param options.scope - The lifecycle scope of the provider:
+ *   - `Scope.Singleton` (default): One instance shared across the entire application
+ *   - `Scope.Request`: New instance for each container.get() call
+ *   - `Scope.Transient`: New instance every time, even within the same dependency tree
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Singleton scope (default)
+ * @Injectable()
+ * class UserService {
+ *   constructor(private db: Database) {}
+ * }
+ *
+ * // Request scope
+ * @Injectable({ scope: Scope.Request })
+ * class RequestContext {
+ *   requestId = Math.random();
+ * }
+ *
+ * // Transient scope
+ * @Injectable({ scope: Scope.Transient })
+ * class Logger {
+ *   timestamp = Date.now();
+ * }
+ * ```
+ */
+export declare function Injectable(options?: InjectableOptions): ClassDecorator;

package/dist/types/decorators/nsModule.d.ts

@@ -0,0 +1,44 @@
+import "reflect-metadata";
+import type { ModuleMetadata } from "../interfaces";
+/**
+ * Defines a module in the application.
+ *
+ * A module is a class annotated with @NsModule() decorator that organizes
+ * the application structure. Modules can:
+ * - Declare providers that will be instantiated by the container
+ * - Import other modules to use their exported providers
+ * - Export providers to make them available to other modules
+ *
+ * @param metadata - Module configuration
+ * @param metadata.imports - Modules whose exported providers should be available in this module
+ * @param metadata.providers - Providers that belong to this module
+ * @param metadata.exports - Providers or modules to export (make available to importing modules)
+ * @returns A class decorator
+ * @throws {Error} If invalid metadata keys are provided
+ *
+ * @example
+ * ```typescript
+ * // Basic module
+ * @NsModule({
+ *   providers: [UserService, UserRepository],
+ *   exports: [UserService]
+ * })
+ * class UserModule {}
+ *
+ * // Module with imports
+ * @NsModule({
+ *   imports: [DatabaseModule, LoggerModule],
+ *   providers: [ProductService],
+ *   exports: [ProductService]
+ * })
+ * class ProductModule {}
+ *
+ * // Root module
+ * @NsModule({
+ *   imports: [UserModule, ProductModule],
+ *   providers: [AppService]
+ * })
+ * class AppModule {}
+ * ```
+ */
+export declare function NsModule(metadata: ModuleMetadata): ClassDecorator;

package/dist/types/decorators/optional.d.ts

@@ -0,0 +1,42 @@
+import "reflect-metadata";
+/**
+ * Marks a dependency as optional.
+ *
+ * When a dependency is marked as optional, the container will not throw an error
+ * if the provider is not found. Instead, it will inject `undefined`.
+ *
+ * This is useful for:
+ * - Optional features that may not be available in all configurations
+ * - Graceful degradation when certain services are not registered
+ * - Testing scenarios where you want to omit certain dependencies
+ *
+ * @returns A decorator that can be applied to constructor parameters or properties
+ *
+ * @example
+ * ```typescript
+ * // Optional constructor parameter
+ * @Injectable()
+ * class UserService {
+ *   constructor(
+ *     private db: Database,
+ *     @Optional() private cache?: CacheService
+ *   ) {
+ *     // cache will be undefined if CacheService is not registered
+ *   }
+ * }
+ *
+ * // Optional property injection
+ * @Injectable()
+ * class ProductService {
+ *   @Optional()
+ *   @Inject('ANALYTICS')
+ *   private analytics?: AnalyticsService;
+ *
+ *   trackEvent(event: string) {
+ *     // Only track if analytics service is available
+ *     this.analytics?.track(event);
+ *   }
+ * }
+ * ```
+ */
+export declare function Optional(): PropertyDecorator & ParameterDecorator;

package/dist/{index.d.ts → types/index.d.ts}

@@ -1,7 +1,10 @@
-export * from "./interfaces";
-export { NsModule } from "./decorators/nsModule";
+export { ContainerNotCompiledError } from "@nexus-ioc/shared";
+export { Container } from "./core/modules/container";
+export { NexusApplications } from "./core/nexus-applications";
+export { Global } from "./decorators/global";
 export { Inject } from "./decorators/inject";
 export { Injectable } from "./decorators/injectable";
-export { Global } from "./decorators/global";
+export { NsModule } from "./decorators/nsModule";
 export { Optional } from "./decorators/optional";
+export * from "./interfaces";
 export * from "./utils/helpers";

package/dist/types/interfaces/module-types.interface.d.ts

@@ -0,0 +1,158 @@
+import type { InjectionToken } from "./injection-token.interface";
+import type { Scope } from "./scope.interface";
+import type { Type } from "./type.interface";
+/**
+ * Represents a module class.
+ */
+export type Module = Type;
+/**
+ * Represents a provider that can be registered in a module.
+ *
+ * A provider can be:
+ * - A class decorated with @Injectable()
+ * - A ClassProvider (provides a different class than the token)
+ * - A ValueProvider (provides a static value)
+ * - A FactoryProvider (provides a value from a factory function)
+ *
+ * @template T - The type of value the provider creates
+ *
+ * @example
+ * ```typescript
+ * // Class provider (shorthand)
+ * @NsModule({
+ *   providers: [UserService]
+ * })
+ *
+ * // ClassProvider (explicit)
+ * @NsModule({
+ *   providers: [
+ *     { provide: UserService, useClass: MockUserService }
+ *   ]
+ * })
+ *
+ * // ValueProvider
+ * @NsModule({
+ *   providers: [
+ *     { provide: 'CONFIG', useValue: { apiUrl: 'https://api.example.com' } }
+ *   ]
+ * })
+ *
+ * // FactoryProvider
+ * @NsModule({
+ *   providers: [
+ *     {
+ *       provide: 'DATABASE',
+ *       useFactory: (config: Config) => createDatabase(config),
+ *       inject: ['CONFIG']
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+export type Provider<T = any> = ClassProvider<T> | ValueProvider<T> | FactoryProvider<T> | Type<T>;
+/**
+ * Provides a class instance, potentially different from the injection token.
+ *
+ * Use this when you want to:
+ * - Provide a mock or alternative implementation
+ * - Use a different class than the token
+ * - Override a provider in a specific module
+ *
+ * @template T - The type of instance to create
+ *
+ * @example
+ * ```typescript
+ * @NsModule({
+ *   providers: [
+ *     // Provide MockUserService when UserService is requested
+ *     {
+ *       provide: UserService,
+ *       useClass: MockUserService,
+ *       scope: Scope.Singleton
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+export interface ClassProvider<T = any> {
+    /** The injection token to register this provider under */
+    provide: InjectionToken;
+    /** The class to instantiate */
+    useClass: Type<T>;
+    /** The lifecycle scope (default: Singleton) */
+    scope?: Scope;
+}
+/**
+ * Provides a static value.
+ *
+ * Use this for:
+ * - Configuration objects
+ * - Constants
+ * - Pre-created instances
+ * - Primitive values (including null and undefined)
+ *
+ * Value providers are always singleton scope.
+ *
+ * @template T - The type of value to provide
+ *
+ * @example
+ * ```typescript
+ * @NsModule({
+ *   providers: [
+ *     { provide: 'API_URL', useValue: 'https://api.example.com' },
+ *     { provide: 'MAX_RETRIES', useValue: 3 },
+ *     { provide: 'CONFIG', useValue: { debug: true } },
+ *     { provide: 'OPTIONAL_VALUE', useValue: null }
+ *   ]
+ * })
+ * ```
+ */
+export interface ValueProvider<T = any> {
+    /** The injection token to register this provider under */
+    provide: InjectionToken;
+    /** The value to provide */
+    useValue: T;
+}
+/**
+ * Provides a value created by a factory function.
+ *
+ * Use this when:
+ * - The value requires complex initialization logic
+ * - The value depends on other providers
+ * - You need to create the value dynamically
+ * - You want to return a Promise for async initialization
+ *
+ * @template T - The type of value the factory creates
+ *
+ * @example
+ * ```typescript
+ * @NsModule({
+ *   providers: [
+ *     {
+ *       provide: 'DATABASE',
+ *       useFactory: async (config: Config) => {
+ *         const db = await createConnection(config.dbUrl);
+ *         await db.migrate();
+ *         return db;
+ *       },
+ *       inject: ['CONFIG'],
+ *       scope: Scope.Singleton
+ *     },
+ *     {
+ *       provide: 'LOGGER',
+ *       useFactory: () => createLogger({ level: 'info' })
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+export interface FactoryProvider<T = any> {
+    /** The injection token to register this provider under */
+    provide: InjectionToken;
+    /** The factory function that creates the value */
+    useFactory: (...args: any[]) => T | Promise<T>;
+    /** Tokens of dependencies to inject into the factory function */
+    inject?: InjectionToken[];
+    /** The lifecycle scope (default: Singleton) */
+    scope?: Scope;
+}

package/dist/types/interfaces/modules/container.interface.d.ts

@@ -0,0 +1,8 @@
+import type { ContainerBaseInterface } from "@nexus-ioc/shared";
+import type { Module } from "../module-types.interface";
+import type { ModuleGraphInterface } from "./module-graph.interface";
+export type { ContainerBaseInterface } from "@nexus-ioc/shared";
+export interface ContainerInterface extends ContainerBaseInterface {
+    run(rootModule: Module): Promise<void>;
+    graph: ModuleGraphInterface;
+}

package/dist/types/interfaces/modules/module-container.interface.d.ts

@@ -0,0 +1 @@
+export type { ModuleContainerInterface } from "@nexus-ioc/shared";

package/dist/{interfaces → types/interfaces}/modules/module-graph.interface.d.ts

@@ -1,6 +1,8 @@
+import type { GraphError } from "@nexus-ioc/shared";
 import type { AnalyzeModule } from "../../core/graph/analyze-module";
 import type { AnalyzeProvider } from "../../core/graph/analyze-provider";
 import type { InjectionToken } from "../injection-token.interface";
+export type { GraphError } from "@nexus-ioc/shared";
 export declare enum NodeTypeEnum {
     MODULE = "module",
     PROVIDER = "provider"
@@ -25,31 +27,9 @@ export type Edge = {
         unreached?: boolean;
     };
 };
-export type GraphError = {
-    type: "CD_IMPORTS";
-    path: string[];
-} | {
-    type: "CD_PROVIDERS";
-    path: [InjectionToken, InjectionToken][];
-} | {
-    type: "UNREACHED_DEP_CONSTRUCTOR";
-    token: string;
-    dependency: string;
-    position: number;
-} | {
-    type: "UNREACHED_DEP_PROPERTY";
-    token: string;
-    dependency: string;
-    key: string;
-} | {
-    type: "UNREACHED_DEP_FACTORY";
-    token: string;
-    dependency: string;
-    key: number;
-};
 export interface ModuleGraphInterface {
     compile(): Promise<void>;
-    getNode(token: InjectionToken): Node;
+    getNode(token: InjectionToken): Node | undefined;
     getEdge(token: InjectionToken): Edge[];
     getAllNodes(): Node[];
     getAllEdges(): Edge[][];

package/dist/{interfaces → types/interfaces}/nexus-application.interface.d.ts

@@ -4,5 +4,7 @@ import type { ModulePluginInterface } from "./plugins";
 export interface NexusApplicationInterface extends ModulePluginInterface {
     bootstrap(): Promise<this>;
     get<T>(token: InjectionToken): Promise<T | undefined>;
+    setParent(parentContainer: NexusApplicationInterface): this;
+    async(): this;
     errors: GraphError[];
 }

package/dist/types/interfaces/on-module-init.interface.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Lifecycle hook interface for module initialization.
+ *
+ * Implement this interface to execute custom logic when a provider is initialized.
+ * The `onModuleInit()` method is called after the provider instance is created
+ * and all its dependencies are injected.
+ *
+ * This is useful for:
+ * - Establishing database connections
+ * - Loading configuration
+ * - Initializing caches
+ * - Setting up event listeners
+ * - Any other initialization logic
+ *
+ * The method can be synchronous or asynchronous. If it returns a Promise,
+ * the container will wait for it to resolve before considering the provider
+ * fully initialized.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class DatabaseService implements OnModuleInit {
+ *   private connection: Connection;
+ *
+ *   async onModuleInit() {
+ *     // Called after DatabaseService is instantiated
+ *     this.connection = await createConnection({
+ *       host: 'localhost',
+ *       database: 'myapp'
+ *     });
+ *     console.log('Database connected');
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class CacheService implements OnModuleInit {
+ *   onModuleInit() {
+ *     // Synchronous initialization
+ *     this.warmUpCache();
+ *   }
+ * }
+ * ```
+ */
+export interface OnModuleInit {
+    /**
+     * Called after the provider is instantiated and dependencies are injected.
+     *
+     * @returns void or a Promise that resolves when initialization is complete
+     */
+    onModuleInit(): void | Promise<void>;
+}

package/dist/types/interfaces/scope.interface.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Defines the lifecycle scope of a provider.
+ *
+ * The scope determines how instances are created and cached:
+ *
+ * - **Singleton**: One instance is created and shared across the entire application.
+ *   The instance is cached globally and reused for all requests.
+ *
+ * - **Request**: A new instance is created for each `container.get()` call, but
+ *   the same instance is reused within that call's dependency tree. This is useful
+ *   for request-scoped data in web applications.
+ *
+ * - **Transient**: A new instance is created every time the provider is injected,
+ *   even within the same dependency tree. No caching is performed.
+ *
+ * @example
+ * ```typescript
+ * // Singleton - shared across the application
+ * @Injectable({ scope: Scope.Singleton })
+ * class DatabaseConnection {
+ *   // Only one instance exists
+ * }
+ *
+ * // Request - new instance per request
+ * @Injectable({ scope: Scope.Request })
+ * class RequestContext {
+ *   requestId = Math.random();
+ *   // Different requestId for each container.get() call
+ * }
+ *
+ * // Transient - new instance every time
+ * @Injectable({ scope: Scope.Transient })
+ * class Logger {
+ *   timestamp = Date.now();
+ *   // Different timestamp for each injection
+ * }
+ * ```
+ */
+export declare enum Scope {
+    /**
+     * Singleton scope - one instance shared across the entire application.
+     * This is the default scope.
+     */
+    Singleton = 0,
+    /**
+     * Request scope - new instance for each container.get() call,
+     * but shared within that call's dependency tree.
+     */
+    Request = 1,
+    /**
+     * Transient scope - new instance every time, no caching.
+     */
+    Transient = 2
+}

package/dist/types/interfaces/utils/hash-utils.interface.d.ts

@@ -0,0 +1 @@
+export type { HashUtilInterface } from "@nexus-ioc/shared";

package/dist/{interfaces → types/interfaces}/validate-module-keys.d.ts

@@ -3,5 +3,5 @@ export declare const MODULE_METADATA: {
     PROVIDERS: string;
     EXPORTS: string;
 };
-export declare const INVALID_MODULE_CONFIG_MESSAGE: (text: TemplateStringsArray, property: string) => string;
+export declare const INVALID_MODULE_CONFIG_MESSAGE: (_text: TemplateStringsArray, property: string) => string;
 export declare function validateModuleKeys(keys: string[]): void;

package/dist/{utils → types/utils}/hash-utils.browser.d.ts

@@ -1,6 +1,7 @@
 import type { HashUtilInterface } from "../interfaces";
 export declare class HashUtilBrowser implements HashUtilInterface {
+    private increment;
     hashString(value: string): Promise<string>;
     hashObject(value: object): Promise<string>;
-    randomStringGenerator(): string;
+    incrementString(): string;
 }

package/dist/types/utils/hash-utils.d.ts

@@ -0,0 +1,7 @@
+import type { HashUtilInterface } from "../interfaces";
+export declare class HashUtil implements HashUtilInterface {
+    private increment;
+    hashString(value: string): Promise<string>;
+    hashObject(value: object): Promise<string>;
+    incrementString(): string;
+}

package/dist/{utils → types/utils}/hash-utils.server.d.ts

@@ -1,6 +1,7 @@
 import type { HashUtilInterface } from "../interfaces";
 export declare class HashUtilsServer implements HashUtilInterface {
+    private increment;
     hashString(value: string): Promise<string>;
     hashObject(value: object): Promise<string>;
-    randomStringGenerator(): string;
+    incrementString(): string;
 }

package/dist/{utils → types/utils}/helpers.d.ts

@@ -13,4 +13,3 @@ export declare function isDynamicModule(module: Module | DynamicModule): module
 export declare function isGlobalModule(target: Module): boolean;
 export declare function getModuleLabel(module: Module | DynamicModule): string;
 export declare function getProviderScope(target: Provider): Scope;
-export declare function getProviderName(target: Provider): string;

package/package.json

@@ -1,63 +1,85 @@
 {
-	"name": "@nexus-ioc/core",
-	"version": "0.4.1",
-	"description": "A powerful IoC container for TypeScript applications",
-	"author": "Isqanderm <aleksandr.melnik.personal@gmail.com> (https://www.linkedin.com/in/isqander-melnik)",
-	"homepage": "https://github.com/Isqanderm/ioc#readme",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Isqanderm/ioc.git"
-	},
-	"bugs": {
-		"url": "https://github.com/Isqanderm/ioc/issues"
-	},
-	"keywords": [
-		"IoC",
-		"dependency injection",
-		"inversion control",
-		"typescript",
-		"DI",
-		"framework",
-		"container"
-	],
-	"files": [
-		"dist",
-		"package.json",
-		"LICENSE",
-		"README.md"
-	],
-	"main": "./dist/index.js",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"license": "MIT",
-	"peerDependencies": {
-		"reflect-metadata": "^0.1.12 || ^0.2.0"
-	},
-	"devDependencies": {
-		"@types/jest": "^29.5.12",
-		"jest": "^29.7.0",
-		"@nexus-ioc/testing": "^0.4.0",
-		"reflect-metadata": "^0.1.12 || ^0.2.0",
-		"sinon": "^18.0.0",
-		"typescript": "^5.5.3",
-		"ts-jest": "^29.1.4",
-		"ts-node": "^10.9.2",
-		"@types/node": "^22.5.4"
-	},
-	"dependencies": {
-		"tslib": "^2.6.3",
-		"uid": "^2.0.2"
-	},
-	"scripts": {
-		"build": "tsc",
-		"test": "jest",
-		"clean": "rm -rf ./dist && rm tsconfig.tsbuildinfo",
-		"test:watch": "jest --watch",
-		"code:format": "npx @biomejs/biome format --write",
-		"code:lint": "npx @biomejs/biome lint --write",
-		"code:check": "npx @biomejs/biome check",
-		"code:check:ci": "npx @biomejs/biome ci",
-		"code:check:apply": "npx @biomejs/biome check --write",
-		"test:ready": "echo 0"
-	}
+  "name": "@nexus-ioc/core",
+  "version": "0.6.1",
+  "description": "A powerful IoC container for TypeScript applications",
+  "author": "Isqanderm <aleksandr.melnik.personal@gmail.com> (https://www.linkedin.com/in/isqander-melnik)",
+  "homepage": "https://github.com/Isqanderm/ioc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Isqanderm/ioc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Isqanderm/ioc/issues"
+  },
+  "keywords": [
+    "IoC",
+    "dependency injection",
+    "inversion control",
+    "typescript",
+    "DI",
+    "framework",
+    "container"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "peerDependencies": {
+    "reflect-metadata": "^0.1.12 || ^0.2.0"
+  },
+  "devDependencies": {
+    "@nexus-ioc/testing": "^0.6.1",
+    "@types/node": "^24.8.1",
+    "@vitest/coverage-v8": "^3.0.0",
+    "reflect-metadata": "^0.1.12 || ^0.2.0",
+    "sinon": "^21.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@nexus-ioc/shared": "^0.6.1",
+    "tslib": "^2.6.3"
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node ../../scripts/fix-esm-imports.js dist/esm && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "test": "vitest run",
+    "clean": "rm -rf ./dist && rm -f tsconfig*.tsbuildinfo",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:memory": "vitest run --config vitest.memory.config.mts",
+    "code:format": "npx @biomejs/biome format --write",
+    "code:lint": "npx @biomejs/biome lint --write",
+    "code:check": "npx @biomejs/biome check",
+    "code:check:ci": "npx @biomejs/biome ci",
+    "code:check:apply": "npx @biomejs/biome check --write",
+    "test:ready": "echo 0"
+  },
+  "gitHead": "26c6fd169d8a091ed4f362ba789c58d10f03c6d8"
 }

package/dist/browser.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":";;;AAAA,gFAA6E;AAApE,sIAAA,wBAAwB,OAAA"}