docs: Add Identifiers Changelog entry

- Import additional exception classes from `src/interfaces/Exceptions`
- Modify `Inject` function to:
  - Accept `init` parameter as a function or `true` for instantiation
  - Throw specific errors: `DependencyResolutionError`, `InjectorError`, `NoInstantiationMethodError`
  - Ensure necessary dependencies are handled properly
  - Define property with `Object.defineProperty` for performance
- Add `hasConstructor` helper function to check if an object has a constructor

.github/workflows/CreateRelease.yml

@@ -35,7 +35,7 @@ jobs:
               id: get_version
               run: |
                   VERSION=$(npm run version:show | tail -n 1)
-                  echo "VERSION=$VERSION" >> $GITHUB_ENV
+                  echo "VERSION=v$VERSION" >> $GITHUB_ENV
               shell: bash
 
             - name: Get previous release tag

CHANGELOG.md

@@ -0,0 +1,59 @@
+# 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).
+
+## [Unreleased]
+
+### Added
+
+- feat: Add a full description of `Identifiers` as JSDoc comment.
+  This establishes the definition of what an `Identifiers` is.
+
+
+### Deprecated
+
+
+### Removed
+
+
+### Fixed
+
+
+### Security
+
+
+## [0.0.14]
+
+### Added
+
+- Added **ChangeLog** file and format it according to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+- Added reference to **Semantic Versioning** in the changelog file. (History will be updated on time).
+- Version format is now `v0.0.0` instead of `0.0.0`. Changes to this are also reflected in the workflos.
+- Add `Identifiers` and `Jest` Sections to the `README.md` file.
+- feat: Add new Error `InitializationError` to reflect errors during initialization of a dependency.
+- feat: Add initialization error handling and refactor Inject.
+- feat: After injecting a dependency, the lazzy loading getter will be replaced with the dependency itself.
+- feat: remove the use of a private property to store the injected dependencies. Now the dependencies are stored in the property itself.
+- test: Add tests for the new features.
+
+
+### Deprecated
+
+- Deprecated the old version format `0.0.0`.
+
+### Removed
+
+
+### Fixed
+
+
+### Security
+
+
+---
+
+[unreleased]: https://github.com/PxaMMaxP/TSinjex/compare/0.0.14...HEAD
+[0.0.14]: https://github.com/PxaMMaxP/TSinjex/compare/0.0.13...v0.0.14

README.md

@@ -6,8 +6,14 @@
 
 ## Configuration
 
+### Identifiers
+
+Strings and symbols are possible for the **identifiers**.
+
 ### Jest
 
+For the use of TSinjex with Jest, the corresponding source files can be found under `./src` of the TSinjex node_module folder. To use these files, the `moduleNameMapper` must be configured in the Jest configuration file. The following example shows how to configure the Jest configuration file to use the source files of TSinjex.
+
 #### Example jest setup
 
 ```ts

package.json

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

src/__tests__/Decorators.spec.ts

@@ -1,3 +1,4 @@
+/* istanbul ignore file */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { Inject } from 'src/decorators/Inject';
 import { DependencyResolutionError } from 'src/interfaces/Exceptions';
@@ -117,6 +118,130 @@ export function test_InjectDecorator(
             }
             expect(_error).toBeInstanceOf(DependencyResolutionError);
         });
+
+        it('should replace the property with the resolved dependency', () => {
+            container.register('MockDependencyIdentifier', {
+                value: 'test-value',
+            });
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier')
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+
+                public isDependencyTypeofFunction() {
+                    return typeof this._dependency === 'function';
+                }
+            }
+
+            const instance = new TestClass();
+
+            expect(instance.getDependency().value).toBe('test-value');
+
+            expect(instance.isDependencyTypeofFunction()).toBe(false);
+            expect(instance.getDependency().value).toBe('test-value');
+        });
+
+        it('should use a empty initializer when none is provided but true', () => {
+            container.register(
+                'MockDependencyIdentifier',
+                class X {
+                    public value: string = 'test-value';
+                    constructor() {}
+                },
+            );
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier', true)
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+            }
+
+            const instance = new TestClass();
+            expect(instance.getDependency().value).toBe('test-value');
+        });
+
+        it('should throw an error when the dependency has no instantiation method', () => {
+            container.register('MockDependencyIdentifier', {
+                value: 'test-value',
+            });
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier', true)
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+            }
+
+            expect(() => {
+                const instance = new TestClass();
+                instance.getDependency();
+            }).toThrow(new RegExp('No instantiation method found for.*'));
+        });
+
+        it('should not throw an error when the dependency has no instantiation method if not necessary', () => {
+            container.register('MockDependencyIdentifier', {
+                value: 'test-value',
+            });
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier', true, false)
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+            }
+
+            expect(() => {
+                const instance = new TestClass();
+                instance.getDependency();
+            }).not.toThrow(new RegExp('No instantiation method found for.*'));
+        });
+
+        it('should throw an error when the dependency cannot be resolved', () => {
+            container.register('MockDependencyIdentifier', null);
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier', true)
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+            }
+
+            expect(() => {
+                const instance = new TestClass();
+                instance.getDependency();
+            }).toThrow(new RegExp('.*could not be resolved.*'));
+        });
+
+        it('should not throw an error when the dependency cannot be resolved if not necessary', () => {
+            container.register('MockDependencyIdentifier', null);
+
+            class TestClass {
+                @Inject('MockDependencyIdentifier', true, false)
+                private readonly _dependency!: any;
+
+                public getDependency() {
+                    return this._dependency;
+                }
+            }
+
+            expect(() => {
+                const instance = new TestClass();
+                instance.getDependency();
+            }).not.toThrow(new RegExp('.*could not be resolved.*'));
+        });
     });
 }
 

src/__tests__/Functions.spec.ts

@@ -1,3 +1,4 @@
+/* istanbul ignore file */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { ITSinjex, ITSinjex_ } from 'src/interfaces/ITSinjex';
 

src/__tests__/ITSinjex.spec.ts

@@ -1,3 +1,4 @@
+/* istanbul ignore file */
 import { ITSinjex_, ITSinjex } from '../interfaces/ITSinjex';
 
 /**

src/classes/TSinjex.ts

@@ -114,7 +114,7 @@ export class TSinjex implements ITSinjex {
         }
 
         if (dependency.deprecated) {
-            console.warn(`Dependency ${identifier} is deprecated`);
+            console.warn(`Dependency ${identifier.toString()} is deprecated`);
 
             // Remove the deprecation warning; it should only be logged once.
             dependency.deprecated = false;

src/decorators/Inject.ts

@@ -1,3 +1,9 @@
+import {
+    DependencyResolutionError,
+    InitializationError,
+    InjectorError,
+    NoInstantiationMethodError,
+} from 'src/interfaces/Exceptions';
 import { TSinjex } from '../classes/TSinjex';
 import { Identifier } from '../types/Identifier';
 import { InitDelegate } from '../types/InitDelegate';
@@ -8,12 +14,17 @@ import { InitDelegate } from '../types/InitDelegate';
  * @template U The type of the property to be injected.
  * @param identifier The identifier used to resolve the class in the DI container.
  * @see {@link Identifier} for more information on identifiers.
- * @param init An optional initializer function to transform the dependency before injection.
+ * @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 necessary 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 A {@link DependencyResolutionError} if the dependency is not found and necessary.
+ * @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
  * class MyClass {
@@ -31,47 +42,110 @@ import { InitDelegate } from '../types/InitDelegate';
  */
 export function Inject<T, U>(
     identifier: Identifier,
-    init?: InitDelegate<T, U>,
+    init?: InitDelegate<T, U> | true,
     necessary = true,
 ) {
     return function (target: unknown, propertyKey: string | symbol): void {
-        // Unique symbol to store the private property
-        const privatePropertyKey: unique symbol = Symbol();
-        // Get the DI container instance
-        const diContainer = TSinjex.getInstance();
-
-        // Function to evaluate the dependency lazily
-        // to avoid circular dependencies, not found dependencies, etc.
-        const evaluate = (): T | undefined => {
-            return diContainer.resolve<T>(identifier, necessary);
+        /**
+         * Function to evaluate the dependency lazily
+         * to avoid circular dependencies, not found dependencies, etc.
+         * @returns The resolved dependency or undefined if the dependency is not found.
+         */
+        const resolve = (): T | undefined => {
+            return TSinjex.getInstance().resolve<T>(identifier, necessary);
         };
 
-        // Define the property
         Object.defineProperty(target, propertyKey, {
             get() {
-                // If the property is not defined, evaluate the dependency
-                if (!this.hasOwnProperty(privatePropertyKey)) {
-                    if (init) {
-                        try {
-                            this[privatePropertyKey] = init(evaluate() as T);
-                        } catch (error) {
-                            if (necessary) {
-                                throw error;
-                            }
-                        }
-                    } else {
-                        this[privatePropertyKey] = evaluate();
-                    }
-                }
+                let instance: T | U | undefined;
 
-                return this[privatePropertyKey];
-            },
-            // Not necessary to set the property
-            // set(value: PropertieType) {
-            //     this[privatePropertyKey] = value;
-            // },
-            enumerable: true,
+                const dependency: T | undefined = tryAndCatch(
+                    () => resolve(),
+                    necessary,
+                    identifier,
+                    DependencyResolutionError,
+                );
+
+                if (dependency != null) {
+                    const initFunction: (() => U) | undefined =
+                        typeof init === 'function' && dependency != null
+                            ? (): U => init(dependency)
+                            : init === true && hasConstructor(dependency)
+                              ? (): U => new dependency() as U
+                              : undefined;
+
+                    if (init == null) instance = dependency;
+                    else if (initFunction != null)
+                        instance = tryAndCatch(
+                            initFunction,
+                            necessary,
+                            identifier,
+                            InitializationError,
+                        );
+                    else if (necessary)
+                        throw new NoInstantiationMethodError(identifier);
+                } else if (necessary)
+                    throw new DependencyResolutionError(identifier);
+
+                /**
+                 * Replace itself with the resolved dependency
+                 * for performance reasons.
+                 */
+                Object.defineProperty(this, propertyKey, {
+                    value: instance,
+                    writable: false,
+                    enumerable: false,
                     configurable: false,
                 });
+
+                return instance;
+            },
+            /**
+             * Make the property configurable to allow replacing it
+             */
+            configurable: true,
+        });
     };
 }
+
+/**
+ * Tries to execute a function and catches any errors that occur.
+ * If the function is necessary and an error occurs, it throws the error
+ * with the specified error class and identifier.
+ * @param fn The function to execute.
+ * @param necessary If true, throws an error if an error occurs.
+ * @param identifier The identifier of the dependency.
+ * @param errorClass The error class to throw if an error occurs.
+ * @returns The result of the function or undefined if an error occurs and the function is not necessary.
+ */
+function tryAndCatch<ReturnType, ErrorType>(
+    fn: () => ReturnType,
+    necessary: boolean,
+    identifier?: Identifier,
+    errorClass?: ErrorType,
+): ReturnType | undefined {
+    try {
+        return fn();
+    } catch (error) {
+        if (necessary)
+            throw new (errorClass != null ? errorClass : error)(
+                identifier ?? 'not specified',
+                error,
+            );
+        else return undefined;
+    }
+}
+
+/**
+ * Checks if an object has a constructor.
+ * @param obj The object to check.
+ * @returns True if the object has a constructor, false otherwise.
+ */
+function hasConstructor<T>(obj: T): obj is T & { new (): unknown } {
+    const _obj = obj as unknown as { prototype?: { constructor?: unknown } };
+
+    return (
+        _obj?.prototype != null &&
+        typeof _obj.prototype.constructor === 'function'
+    );
+}

src/interfaces/Exceptions.ts

@@ -1,3 +1,4 @@
+import { Identifier } from 'src/types/Identifier';
 import { ITSinjex } from './ITSinjex';
 
 /**
@@ -23,8 +24,61 @@ export class DependencyResolutionError extends TSinjexError {
      * Creates a new instance of {@link DependencyResolutionError}
      * @param identifier **The identifier of the dependency**
      */
-    constructor(identifier: string) {
-        super(`Dependency ${identifier} could not be resolved.`);
+    constructor(identifier: Identifier) {
+        super(`Dependency ${identifier.toString()} could not be resolved.`);
         this.name = 'TSinjexResolutionError';
     }
 }
+
+/**
+ * Error class for Injector errors in {@link ITSinjex}.
+ * @see {@link ITSinjex.inject}
+ */
+export class InjectorError extends TSinjexError {
+    /**
+     * Creates a new instance of {@link InjectorError}
+     * @param identifier **The identifier of the dependency**
+     * @param originalError **The original error that caused the injection error**
+     */
+    constructor(identifier: Identifier, originalError?: Error) {
+        super(
+            `Error injecting dependency ${identifier.toString()} with error: "${originalError}"`,
+        );
+        this.name = 'TSinjexInjectorError';
+    }
+}
+
+/**
+ * Error class for missing instantiation methods in {@link ITSinjex}.
+ * @see {@link ITSinjex.inject}
+ */
+export class NoInstantiationMethodError extends TSinjexError {
+    /**
+     * Creates a new instance of {@link NoInstantiationMethodError}
+     * @param identifier **The identifier of the dependency**
+     */
+    constructor(identifier: Identifier) {
+        super(
+            `No instantiation method found for dependency ${identifier.toString()}.`,
+        );
+        this.name = 'TSinjexNoInstantiationMethodError';
+    }
+}
+
+/**
+ * Error class for errors during the initialization of a dependency in {@link ITSinjex}.
+ * @see {@link ITSinjex.inject}
+ */
+export class InitializationError extends TSinjexError {
+    /**
+     * Creates a new instance of {@link InitializationError}
+     * @param identifier **The identifier of the dependency**
+     * @param originalError **The original error that caused the initialization error**
+     */
+    constructor(identifier: Identifier, originalError?: Error) {
+        super(
+            `Error initializing dependency ${identifier.toString()} with error: "${originalError}"`,
+        );
+        this.name = 'TSinjexInitializationError';
+    }
+}

src/types/Identifier.ts

@@ -1,11 +1,35 @@
 /**
- * The dependency identifier.
- * You can use any string as identifier.
- * To create order, it is also possible to
- * provide these with a separator: `GroupA.ClassZ`.
- * The convection for naming is as follows:
- * The name should generally correspond to the interface that is relevant.
- * I.e. a class `ClassA` that implements the interface `IClassA` and is
- * registered as a dependent class is registered under the interface name `IClassA`.
+ * ## The dependency identifier
+ *
+ * You can use any string or Symbol as identifier. The identifier is used to
+ * register a class in the TSinjex DI (Dependency Injection) container.
+ * See **Hierarchical identifiers** for more information on `.` in identifiers.
+ *
+ * ### Hierarchical identifiers
+ * To create hierarchical identifiers, you can use a dot `.` as a separator.
+ * E.g. `Parent.Child` or `Parent.Child.Grandchild`.
+ *
+ * ### Merge functionality
+ * You can merge multiple dependencies into one by resolving them with
+ * a identifier that is a prefix of the actual identifiers.
+ * E.g. `Parent` resolves `Parent.*` and returns a mixin of all children.
+ * Merging will only work, if the main identifier is not registered.
+ * Grandchildren are not included in the mixin but you can use something like
+ * `Parent.Child.Grandchild` to merge all direct children of Grandchild,
+ * e.g. `Parent.Child.Grandchild.*`.
+ * If you don't want to allow merging, you must register the dependencies
+ * with the full identifier. E.g. `Parent` or `Parent.Child.Grandchild`.
+ *
+ * ### Naming convention
+ * The name of a dependency should generally correspond to the interface that is implemented.
+ * E.g. a class `ClassA` that implements the interface `IClassA` and is registered
+ * as a dependent class is registered under the interface name `IClassA`.
+ *
+ * The mixin parts of the class are registered under the interface name `IClassA.*`.
+ * E.g. `IClassA.IClassZ`, `IClassA.IClassY`, etc.
+ *
+ * #### Static/Constructor Identifier naming
+ * The identifier for a static or constructor dependency should be the same as the class name
+ * postfixed with `_`. E.g. `IClassA_` for the the static or constructor interface of class `IClassA`.
  */
-export type Identifier = string;
+export type Identifier = string | symbol;