docs: reflect changes to changelog

CHANGELOG.md

@@ -17,6 +17,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [1.2.0]
+
+### Added
+
+-   docs: added complete Typedoc-style documentation for all `inject()` overloads  
+    Includes parameter descriptions, usage examples, and detailed error annotations for each variant.
+
+## [1.1.0]
+
+### Added
+
+-   feat: exported `inject()` function from the public API via `index.ts`  
+    The function is now available as part of the main module exports.
+
 ## [1.0.0]
 
 ### Added
@@ -133,6 +147,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ---
 
 [unreleased]: https://github.com/20Max01/TSinjex/compare/v1.0.0...HEAD
+[1.1.0]: https://github.com/20Max01/TSinjex/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/20Max01/TSinjex/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/20Max01/TSinjex/compare/v0.4.0...v1.0.0
 [0.4.0]: https://github.com/20Max01/TSinjex/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/20Max01/TSinjex/compare/v0.2.0...v0.3.0

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-injex",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Simple boilerplate code free dependency injection system for TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

src/functions/inject.ts

@@ -9,34 +9,141 @@ import { Identifier } from '../types/Identifier.js';
 import { InitDelegate } from '../types/InitDelegate.js';
 
 /**
- * A function to inject a dependency from a DI (Dependency Injection) container into a variable.
+ * Resolves a dependency by its identifier without initialization or instantiation.
- * @template T The type of the dependency to be injected.
+ * @template T The expected type of the dependency.
- * @template U The type of the property to be injected.
+ * @param identifier The identifier used to resolve the dependency from the container.
- * @param identifier The identifier used to resolve the class in the DI container.
+ * @returns The resolved dependency.
- * @see {@link Identifier} for more information on identifiers.
- * @param init Optional an initializer function to transform the dependency before injection
- * or true to instantiate the dependency if it has a constructor.
- * @see {@link InitDelegate} for more information on initializer functions.
- * @param isNecessary If true, throws an error if the dependency is not found.
- * @returns The resolved dependency or undefined if the dependency is not necessary
- * and not found, or throws an error if the dependency is necessary and not found.
- * @throws **Only throws errors if the dependency is necessary.**
  * @throws A {@link DependencyResolutionError} if the dependency is not found.
- * @throws A {@link InjectorError} if an error occurs during the injection process.
- * @throws A {@link NoInstantiationMethodError} if the dependency does not have a constructor.
- * @throws An {@link InitializationError} if an error occurs during the initialization process.
  * @example
  * ```ts
- * let myDependency = inject<MyDependency>('MyDependencyIdentifier');
+ * const logger = inject<Logger>('Logger');
  * ```
+ */
+export function inject<T>(identifier: Identifier): T;
+
+/**
+ * Resolves and instantiates a dependency using its constructor.
+ * @template T The expected class type of the dependency.
+ * @param identifier The identifier used to resolve the dependency from the container.
+ * @param shouldInit Set to `true` to instantiate the dependency after resolution.
+ * @returns The resolved and instantiated dependency.
+ * @throws A {@link DependencyResolutionError} if the dependency is not found.
+ * @throws A {@link NoInstantiationMethodError} if the dependency has no constructor.
+ * @throws An {@link InitializationError} if instantiation fails.
  * @example
  * ```ts
- * let logger = inject<ILogger>('ILogger_', (x: ILogger_) => x.getLogger('Tags'), false);
+ * const instance = inject<Service>('Service', true);
+ * ```
+ */
+export function inject<T>(identifier: Identifier, shouldInit: true): T;
+
+/**
+ * Resolves and instantiates a dependency using its constructor, optionally failing silently.
+ * @template T The expected class type of the dependency.
+ * @param identifier The identifier used to resolve the dependency from the container.
+ * @param shouldInit Set to `true` to instantiate the dependency.
+ * @param isNecessary If `false`, resolution or instantiation errors return `undefined` instead of throwing.
+ * @returns The resolved and instantiated dependency, or `undefined` if resolution or instantiation fails.
+ * @example
+ * ```ts
+ * const instance = inject<Service>('OptionalService', true, false);
+ * if (instance) instance.doSomething();
+ * ```
+ */
+export function inject<T>(
+    identifier: Identifier,
+    shouldInit: true,
+    isNecessary: false,
+): T | undefined;
+
+/**
+ * Resolves a dependency without instantiating it, optionally failing silently.
+ * @template T The expected type of the dependency.
+ * @param identifier The identifier used to resolve the dependency from the container.
+ * @param shouldInit Set to `false` to skip instantiation.
+ * @param isNecessary If `false`, resolution errors return `undefined` instead of throwing.
+ * @returns The resolved dependency, or `undefined` if not found.
+ * @example
+ * ```ts
+ * const config = inject<Config>('Config', false, false) ?? getDefaultConfig();
+ * ```
+ */
+export function inject<T>(
+    identifier: Identifier,
+    shouldInit: false,
+    isNecessary: false,
+): T | undefined;
+
+/**
+ * Resolves a dependency and applies a custom initializer function to transform the result.
+ * @template T The original dependency type.
+ * @template U The final return type after initialization.
+ * @param identifier The identifier used to resolve the dependency.
+ * @param init A function to transform or initialize the dependency.
+ * @returns The transformed dependency.
+ * @throws A {@link DependencyResolutionError} if the dependency is not found.
+ * @throws An {@link InitializationError} if the initializer throws.
+ * @example
+ * ```ts
+ * const client = inject<Api>('Api', (api) => api.getClient());
  * ```
  */
 export function inject<T, U>(
     identifier: Identifier,
-    init?: InitDelegate<T, U> | true,
+    init: InitDelegate<T, U>,
+): U;
+
+/**
+ * Resolves a dependency and applies a custom initializer function, optionally failing silently.
+ * @template T The original dependency type.
+ * @template U The final return type after initialization.
+ * @param identifier The identifier used to resolve the dependency.
+ * @param init A function to transform or initialize the dependency.
+ * @param isNecessary If `false`, resolution or initializer errors return `undefined` instead of throwing.
+ * @returns The transformed dependency, or `undefined` if resolution or initialization fails.
+ * @example
+ * ```ts
+ * const db = inject<Database, Pool>('Database', (d) => d.getPool(), false);
+ * if (db) db.query('SELECT * FROM users');
+ * ```
+ */
+export function inject<T, U>(
+    identifier: Identifier,
+    init: InitDelegate<T, U>,
+    isNecessary: false,
+): U | undefined;
+
+/**
+ * A function to inject a dependency from a DI (Dependency Injection) container into a variable.
+ * This is the actual implementation that handles all overload variants.
+ * @template T The original dependency type.
+ * @template U The final return type after optional initialization or transformation.
+ * @param identifier The identifier used to resolve the dependency.
+ * @see {@link Identifier} for more information on identifiers.
+ * @param init Optional: either `true` to instantiate via constructor, `false` to skip, or a function to transform the dependency.
+ * @see {@link InitDelegate} for more information on initializer functions.
+ * @param isNecessary If `true`, throws on failure; if `false`, returns `undefined` on resolution or initialization errors.
+ * @returns The resolved dependency or result of initialization, or `undefined` if not necessary and resolution fails.
+ * @throws A {@link DependencyResolutionError} if the dependency is not found (and necessary).
+ * @throws A {@link NoInstantiationMethodError} if instantiation is requested but no constructor exists.
+ * @throws An {@link InitializationError} if the initializer throws an error.
+ * @throws A {@link InjectorError} for unknown errors during resolution or transformation.
+ * @example
+ * ```ts
+ * const service = inject<Service>('Service');
+ * ```
+ * @example
+ * ```ts
+ * const instance = inject<Service>('Service', true);
+ * ```
+ * @example
+ * ```ts
+ * const logger = inject<ILogger>('ILogger_', (x) => x.getLogger('Module'), false);
+ * ```
+ */
+export function inject<T, U>(
+    identifier: Identifier,
+    init?: InitDelegate<T, U> | true | false,
     isNecessary = true,
 ): T | U | undefined {
     let instance: T | U | undefined;
@@ -56,7 +163,7 @@ export function inject<T, U>(
                   ? (): U => new dependency() as U
                   : undefined;
 
-        if (init == null) instance = dependency;
+        if (init == null || init === false) instance = dependency;
         else if (initFunction != null)
             instance = tryAndCatch(
                 initFunction,

src/index.ts

@@ -14,6 +14,7 @@ export * from './helper/ImplementsStatic.js';
 // Functions
 export * from './functions/resolve.js';
 export * from './functions/register.js';
+export * from './functions/inject.js';
 
 // Interfaces & Types
 export type * from './interfaces/ITSinjex.js';