@adaas/a-concept 0.1.24 → 0.1.25

package/src/global/A-Scope/A-Scope.class.ts

@@ -10,6 +10,7 @@ import {
     A_TYPES__A_InjectDecorator_EntityInjectionInstructions,
     A_TYPES__A_InjectDecorator_EntityInjectionQuery,
     A_TYPES__InjectableConstructors,
+    A_TYPES__InjectableTargets,
 } from "@adaas/a-concept/global/A-Inject/A-Inject.types";
 import { A_Fragment } from "../A-Fragment/A-Fragment.class";
 import { A_Context } from "../A-Context/A-Context.class";
@@ -267,6 +268,31 @@ export class A_Scope<
     protected initFragments(_fragments?: _FragmentType) { _fragments?.forEach(this.register.bind(this)); }
 
 
+    // ==========================================================================
+    // --------------------Scope Public Methods-----------------------------------
+    // ==========================================================================
+    /**
+     * This method is used to destroy the scope and all its registered components, fragments and entities
+     * 
+     * [!] This method deregisters all components, fragments and entities from the A-Context
+     * [!] This method also clears all internal registries and collections
+     */
+    destroy() {
+        this._components.forEach(component => A_Context.deregister(component));
+        this._fragments.forEach(fragment => A_Context.deregister(fragment));
+        this._entities.forEach(entity => A_Context.deregister(entity));
+
+        this._components.clear();
+        this._errors.clear();
+        this._fragments.clear();
+        this._entities.clear();
+
+        if (this.issuer()) {
+            A_Context.deallocate(this);
+        }
+    }
+
+
     /**
      * Returns the issuer of the scope, useful for debugging and tracking purposes
      * 
@@ -499,7 +525,7 @@ export class A_Scope<
          */
         name: string
     ): A_TYPES__Fragment_Constructor<T>
-    resolveConstructor<T extends A_TYPES__ScopeResolvableComponents>(name: string): A_TYPES__Entity_Constructor<T> | A_TYPES__Component_Constructor<T> | A_TYPES__Fragment_Constructor<T> {
+    resolveConstructor<T extends A_TYPES__ScopeResolvableComponents>(name: string): A_TYPES__Entity_Constructor<T> | A_TYPES__Component_Constructor<T> | A_TYPES__Fragment_Constructor<T> | undefined {
         // 1) Check components
         const component = Array.from(this.allowedComponents).find(
             c => c.name === name
@@ -527,10 +553,7 @@ export class A_Scope<
             return this._parent.resolveConstructor(name) as any;
         }
 
-        throw new A_ScopeError(
-            A_ScopeError.ResolutionError,
-            `Component or Entity with name ${name} not found in the scope ${this.name}`
-        );
+        return undefined;
     }
 
 
@@ -550,25 +573,25 @@ export class A_Scope<
          * Provide a component constructor to resolve its instance from the scope
          */
         component: A_TYPES__Component_Constructor<T>
-    ): T
+    ): T | undefined
     resolve<T extends A_TYPES__Component_Constructor[]>(
         /**
          * Provide an array of component constructors to resolve their instances from the scope
          */
         components: [...T]
-    ): Array<InstanceType<T[number]>>
+    ): Array<InstanceType<T[number]>> | undefined
     resolve<T extends A_Fragment>(
         /**
          * Provide a fragment constructor to resolve its instance from the scope
          */
         fragment: A_TYPES__Fragment_Constructor<T>
-    ): T
+    ): T | undefined
     resolve<T extends A_TYPES__Fragment_Constructor[]>(
         /**
          * Provide an array of fragment constructors to resolve their instances from the scope
          */
         fragments: [...T]
-    ): Array<InstanceType<T[number]>>
+    ): Array<InstanceType<T[number]>> | undefined
     resolve<T extends A_Entity>(
         /**
          * Provide an entity constructor to resolve its instance or an array of instances from the scope
@@ -582,7 +605,7 @@ export class A_Scope<
          * Provide an entity constructor to resolve its instance from the scope
          */
         scope: new (...args: any[]) => T
-    ): T
+    ): T | undefined
     resolve<T extends A_Entity>(
         /**
          * Provide an entity constructor to resolve its instance or an array of instances from the scope
@@ -595,7 +618,7 @@ export class A_Scope<
     ): Array<T>
     resolve<T extends A_TYPES__ScopeResolvableComponents>(
         constructorName: string
-    ): T
+    ): T | undefined
     // base definition
     resolve<T extends A_TYPES__ScopeResolvableComponents>(
         /**
@@ -603,21 +626,21 @@ export class A_Scope<
          */
         param1: A_TYPES__InjectableConstructors,
 
-    ): T | Array<T>
+    ): T | Array<T> | undefined
     resolve<T extends A_TYPES__ScopeLinkedConstructors>(
         /**
          * Provide a component, fragment or entity constructor or an array of constructors to resolve its instance(s) from the scope
          */
         param1: InstanceType<T>,
 
-    ): T | Array<T>
+    ): T | Array<T> | undefined
     resolve<T extends A_TYPES__ScopeResolvableComponents>(
         /**
          * Provide a component, fragment or entity constructor or an array of constructors to resolve its instance(s) from the scope
          */
         param1: A_TYPES__InjectableConstructors | Array<A_TYPES__InjectableConstructors>,
         param2?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
-    ): T | Array<T> {
+    ): T | Array<T> | undefined {
         switch (true) {
             case A_TypeGuards.isArray(param1): {
                 return param1.map(c => {
@@ -637,7 +660,9 @@ export class A_Scope<
             }
 
             default: {
-                throw new A_Error(`Invalid parameter provided to resolve method: ${param1} in scope ${this.name}`);
+                throw new A_ScopeError(
+                    A_ScopeError.ResolutionError,
+                    `Invalid parameter provided to resolve method: ${param1} in scope ${this.name}`);
             }
         }
     }
@@ -663,7 +688,7 @@ export class A_Scope<
          * Provide the name of the component, fragment or entity to resolve
          */
         name: string
-    ): _EntityType[number] | InstanceType<_ComponentType[number]> | _FragmentType[number] {
+    ): _EntityType[number] | InstanceType<_ComponentType[number]> | _FragmentType[number] | undefined {
         // 1) Check components
         const component = Array.from(this.allowedComponents).find(
             c => c.name === name
@@ -691,10 +716,7 @@ export class A_Scope<
             return this._parent.resolveByName(name) as any;
         }
 
-        throw new A_ScopeError(
-            A_ScopeError.ResolutionError,
-            `Component or Entity with name ${name} not found in the scope ${this.name}`
-        );
+        return undefined;
     }
 
     /**
@@ -707,22 +729,12 @@ export class A_Scope<
     private resolveOnce(
         component: any,
         instructions?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
-    ): A_TYPES__ScopeResolvableComponents | A_Scope | A_TYPES__ScopeLinkedComponents | Array<A_TYPES__ScopeResolvableComponents> {
-
-        const componentName = A_TypeGuards.isFunction(component) ? component.name : component.constructor.name || String(component);
+    ): A_TYPES__ScopeResolvableComponents | A_Scope | A_TYPES__ScopeLinkedComponents | Array<A_TYPES__ScopeResolvableComponents> | undefined {
 
+        const componentName = A_CommonHelper.getComponentName(component);
 
         if (!component || !this.has(component))
-            throw new A_ScopeError(
-                A_ScopeError.ResolutionError,
-                `Injected Component ${componentName} not found in the scope`
-            );
-
-        if (A_TypeGuards.isScopeConstructor(component))
-            component
-
-        if (typeof component == 'function' && component.name === 'A_Scope')
-            component
+            return undefined;
 
         switch (true) {
             case A_TypeGuards.isConstructorAllowedForScopeAllocation(component): {
@@ -750,7 +762,7 @@ export class A_Scope<
 
     private resolveIssuer(
         ctor: A_TYPES__ScopeLinkedConstructors
-    ): A_TYPES__ScopeLinkedComponents {
+    ): A_TYPES__ScopeLinkedComponents | undefined {
 
         const issuer = this.issuer();
 
@@ -765,10 +777,7 @@ export class A_Scope<
             return this._parent.resolveIssuer(ctor);
         }
 
-        throw new A_ScopeError(
-            A_ScopeError.ResolutionError,
-            `Issuer ${ctor.name} not found in the scope ${this.name}`
-        );
+        return undefined;
     }
 
     /**
@@ -783,7 +792,7 @@ export class A_Scope<
     private resolveEntity<T extends A_Entity>(
         entity: A_TYPES__Entity_Constructor<T>,
         instructions?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions<T>>
-    ): T | Array<T> {
+    ): T | Array<T> | undefined {
 
         const query = instructions?.query || {} as Partial<A_TYPES__A_InjectDecorator_EntityInjectionQuery<T>>;
         const count = instructions?.pagination?.count || 1;
@@ -806,10 +815,7 @@ export class A_Scope<
                         return this._parent.resolveEntity(entity, instructions);
 
                     default:
-                        throw new A_ScopeError(
-                            A_ScopeError.ResolutionError,
-                            `Entity ${entity.name} not found in the scope ${this.name}`
-                        );
+                        return undefined;
                 }
             }
             /**
@@ -884,7 +890,7 @@ export class A_Scope<
      * @param fragment 
      * @returns 
      */
-    private resolveFragment<T extends A_Fragment>(fragment: A_TYPES__Fragment_Constructor<T>): _FragmentType[number] {
+    private resolveFragment<T extends A_Fragment>(fragment: A_TYPES__Fragment_Constructor<T>): _FragmentType[number] | undefined {
         const fragmentInstancePresented = this._fragments.get(fragment);
 
         switch (true) {
@@ -895,10 +901,7 @@ export class A_Scope<
                 return this._parent.resolveFragment(fragment);
 
             default:
-                throw new A_ScopeError(
-                    A_ScopeError.ResolutionError,
-                    `Fragment ${fragment.name} not found in the scope ${this.name}`
-                );
+                return undefined;
         }
     }
     /**
@@ -916,7 +919,7 @@ export class A_Scope<
      * @param component 
      * @returns 
      */
-    private resolveComponent<T extends A_Component>(component: A_TYPES__Component_Constructor<T>): InstanceType<_ComponentType[number]> {
+    private resolveComponent<T extends A_Component>(component: A_TYPES__Component_Constructor<T>): InstanceType<_ComponentType[number]> | undefined {
 
         //  The idea here that in case when Scope has no exact component we have to resolve it from the _parent
         //  BUT: if it's not presented in _parent  we have to check for inheritance
@@ -935,15 +938,40 @@ export class A_Scope<
 
                 const resolvedArgs = (argsMeta?.get('constructor') || [])
                     .map(arg => {
-                        if ('instructions' in arg) {
+                        // for Error handling purposes
+                        const componentName = A_CommonHelper.getComponentName(arg.target)
+
+                        if ('instructions' in arg && !!arg.instructions) {
                             const { target, instructions } = arg
-                            return this.resolve(
-                                target,
-                                instructions
-                            );
+                            const dependency = this.resolve(target as any, instructions);
+                            if (!dependency)
+                                throw new A_ScopeError(
+                                    A_ScopeError.ResolutionError,
+                                    `Unable to resolve dependency ${componentName} for component ${component.name} in scope ${this.name}`
+                                );
+
+                            return dependency;
+                        } else {
+                            const { target, require, create, defaultArgs } = arg;
+
+                            let dependency = this.resolve(target as any);
+
+                            if (create && !dependency && A_TypeGuards.isAllowedForDependencyDefaultCreation(target)) {
+                                const newDependency = new target(...defaultArgs);
+
+                                this.register(newDependency);
+                                return newDependency;
+                            }
+
+                            if (require && !dependency) {
+                                throw new A_ScopeError(
+                                    A_ScopeError.ResolutionError,
+                                    `Unable to resolve required dependency ${componentName} for component ${component.name} in scope ${this.name}`
+                                );
+                            }
+
+                            return dependency;
                         }
-                        // TODO: Fix types mismatch here
-                        return this.resolve<T>(arg.target as any);
                     });
 
                 const newComponent = new component(...resolvedArgs)
@@ -1128,7 +1156,7 @@ export class A_Scope<
                         `Fragment ${param1.constructor.name} is already registered in the scope ${this.name}`
                     );
                 else {
-                    const componentName = A_TypeGuards.isFunction(param1) ? param1.name : param1?.constructor?.name || String(param1);
+                    const componentName = A_CommonHelper.getComponentName(param1);
 
                     throw new A_ScopeError(
                         A_ScopeError.RegistrationError,

package/src/global/A-Stage/A-Stage.class.ts

@@ -12,6 +12,7 @@ import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
 import { A_TYPES__ScopeResolvableComponents } from "../A-Scope/A-Scope.types";
 import { A_TYPES__Container_Constructor } from "../A-Container/A-Container.types";
 import { A_TYPES__Component_Constructor } from "../A-Component/A-Component.types";
+import { A_CommonHelper } from "@adaas/a-concept/helpers/A_Common.helper";
 
 
 
@@ -141,11 +142,30 @@ export class A_Stage {
                         case A_TypeGuards.isFeatureConstructor(arg.target):
                             return this._feature;
 
-                        case A_TypeGuards.isEntityConstructor(arg.target) && 'instructions' in arg:
+                        case A_TypeGuards.isEntityConstructor(arg.target) && 'instructions' in arg && !!arg.instructions:
                             return scope.resolve(arg.target, arg.instructions)
 
-                        default:
+                        default: {
+                            const { target, require, create, defaultArgs } = arg;
+
+                            let dependency = scope.resolve(target as any);
+
+                            if (create && !dependency && A_TypeGuards.isAllowedForDependencyDefaultCreation(target)) {
+                                const newDependency = new target(...defaultArgs);
+
+                                scope.register(newDependency);
+                                return newDependency;
+                            }
+
+                            if (require && !dependency) {
+                                throw new A_StageError(
+                                    A_StageError.ArgumentsResolutionError,
+                                    `Unable to resolve required argument ${A_CommonHelper.getComponentName(arg.target)} for stage ${this.name} in scope ${scope.name}`
+                                );
+                            }
+
                             return scope.resolve(arg.target)
+                        }
                     }
                 })
             )

package/src/global/A-Stage/A-Stage.error.ts

@@ -3,6 +3,8 @@ import { A_Error } from "../A-Error/A_Error.class";
 
 export class A_StageError extends A_Error {
 
+    static readonly ArgumentsResolutionError = 'A-Stage Arguments Resolution Error';
+
 
     static get CompileError(): string {
         return 'Unable to compile A-Stage';

package/src/helpers/A_Common.helper.ts

@@ -201,4 +201,105 @@ export class A_CommonHelper {
         // For any other cases
         throw new Error('Unable to clone the object. Unsupported type.');
     }
+
+    /**
+     * Get a readable name for a component (string, class, function, React element, instance, etc.)
+     *
+     * Covers:
+     * - string tags ("div")
+     * - symbols (Symbol.for('xxx'))
+     * - functions and classes (with name or displayName)
+     * - React elements (object with `type`)
+     * - component instances (constructor.name)
+     * - objects with custom toString returning meaningful info
+     *
+     * Falls back to sensible defaults ("Unknown" / "Anonymous").
+     */
+    static getComponentName(component: any): string {
+        const UNKNOWN = 'Unknown';
+        const ANONYMOUS = 'Anonymous';
+
+        if (component === null || component === undefined) {
+            return UNKNOWN;
+        }
+
+        // Strings (HTML tags or explicit names)
+        if (typeof component === 'string') {
+            return component || UNKNOWN;
+        }
+
+        // Symbols
+        if (typeof component === 'symbol') {
+            try {
+                return component.toString();
+            } catch {
+                return UNKNOWN;
+            }
+        }
+
+        // Arrays - try to derive from first element
+        if (Array.isArray(component)) {
+            if (component.length === 0) return UNKNOWN;
+            return this.getComponentName(component[0]);
+        }
+
+        // Functions and classes
+        if (typeof component === 'function') {
+            const fnAny = component as any;
+            // Common React convention
+            if (fnAny.displayName) return String(fnAny.displayName);
+            if (fnAny.name) return String(fnAny.name);
+
+            // Try to extract a name from source if possible
+            try {
+                const src = Function.prototype.toString.call(component);
+                // class Foo { ... } or function foo() { ... } or foo => ...
+                const match = src.match(/^(?:class\s+([A-Za-z0-9_$]+)|function\s+([A-Za-z0-9_$]+)|([A-Za-z0-9_$]+)\s*=>)/);
+                if (match) {
+                    return match[1] || match[2] || match[3] || ANONYMOUS;
+                }
+            } catch {
+                // fallthrough
+            }
+            return ANONYMOUS;
+        }
+
+        // Objects (instances, React elements, plain objects)
+        if (typeof component === 'object') {
+            const objAny = component as any;
+
+            // React element: { type: ComponentOrString, props: ... }
+            if (objAny.type) {
+                return this.getComponentName(objAny.type);
+            }
+
+            // React forwardRef / memo wrappers often expose displayName
+            if (objAny.displayName) return String(objAny.displayName);
+            if (objAny.name) return String(objAny.name);
+
+            // Instance: use constructor name if available and not Object
+            if (objAny.constructor && objAny.constructor.name && objAny.constructor.name !== 'Object') {
+                return String(objAny.constructor.name);
+            }
+
+            // If object implements a meaningful toString, try it
+            try {
+                const s = objAny.toString();
+                if (typeof s === 'string' && s !== '[object Object]') {
+                    return s;
+                }
+            } catch {
+                // ignore
+            }
+
+            return ANONYMOUS;
+        }
+
+        // Fallback for other types
+        try {
+            return String(component);
+        } catch {
+            return UNKNOWN;
+        }
+    }
 }

package/src/helpers/A_TypeGuards.helper.ts

@@ -315,6 +315,14 @@ export class A_TypeGuards {
             || A_TypeGuards.isComponentInstance(param);
     }
 
+    static isAllowedForDependencyDefaultCreation(param: any): param is A_TYPES__Entity_Constructor | A_TYPES__Component_Constructor {
+        return A_TypeGuards.isComponentConstructor(param)
+            || A_CommonHelper.isInheritedFrom(param, A_Component)
+            || A_TypeGuards.isEntityConstructor(param)
+            || A_CommonHelper.isInheritedFrom(param, A_Entity)
+
+    }
+
     /**
      * Allows to check if the provided param is of constructor type.
      * 

package/src/index.ts

@@ -0,0 +1,88 @@
+// =================================================================================================
+// ============================= Export Framework Components =======================================
+// =================================================================================================
+export * from './constants/env.constants';
+export * from './types/A_Common.types';
+
+// ---------------------- Major Components ----------------------
+export { A_Context } from './global/A-Context/A-Context.class';
+export * from './global/A-Context/A-Context.types';
+
+export { A_Concept } from './global/A-Concept/A-Concept.class';
+export { A_ConceptMeta } from './global/A-Concept/A-Concept.meta';
+export * from './global/A-Concept/A-Concept.types';
+
+export { A_Container } from './global/A-Container/A-Container.class';
+export { A_ContainerMeta } from './global/A-Container/A-Container.meta';
+export * from './global/A-Container/A-Container.class';
+
+export { A_Component } from './global/A-Component/A-Component.class';
+export { A_ComponentMeta } from './global/A-Component/A-Component.meta';
+export * from './global/A-Component/A-Component.types';
+
+export { A_Entity } from './global/A-Entity/A-Entity.class';
+export * from './global/A-Entity/A-Entity.types';
+
+
+// ---------------------- Common Components ----------------------
+export { A_Abstraction } from './global/A-Abstraction/A-Abstraction.class';
+export { A_AbstractionError } from './global/A-Abstraction/A-Abstraction.error';
+export * from './global/A-Abstraction/A-Abstraction.types';
+
+export { A_Caller } from './global/A-Caller/A_Caller.class';
+export { A_CallerError } from './global/A-Caller/A_Caller.error';
+export * from './global/A-Caller/A_Caller.types';
+
+export { A_Error } from './global/A-Error/A_Error.class';
+export * from './global/A-Error/A_Error.types';
+
+export { ASEID } from './global/ASEID/ASEID.class';
+export { ASEID_Error } from './global/ASEID/ASEID.error';
+export * from './global/ASEID/ASEID.types';
+
+export { A_Feature } from './global/A-Feature/A-Feature.class';
+export { A_FeatureError } from './global/A-Feature/A-Feature.error';
+export * from './global/A-Feature/A-Feature.types';
+
+export { A_Stage } from './global/A-Stage/A-Stage.class';
+export { A_StageError } from './global/A-Stage/A-Stage.error';
+export * from './global/A-Stage/A-Stage.types';
+
+export { A_Scope } from './global/A-Scope/A-Scope.class';
+export { A_ScopeError } from './global/A-Scope/A-Scope.error';
+export * from './global/A-Scope/A-Scope.types';
+
+export { A_Meta } from './global/A-Meta/A-Meta.class';
+export * from './global/A-Meta/A-Meta.types';
+
+export { A_Fragment } from './global/A-Fragment/A-Fragment.class';
+export * from './global/A-Fragment/A-Fragment.types';
+
+export { A_Dependency } from './global/A-Dependency/A-Dependency.class';
+export { A_DependencyError } from './global/A-Dependency/A-Dependency.error';
+export * from './global/A-Dependency/A-Dependency.types';
+
+
+// =================================================================================================
+// =============================== Export Decorators ===============================================
+// =================================================================================================
+export { A_Inject } from './global/A-Inject/A-Inject.decorator';
+export * from './global/A-Inject/A-Inject.types';
+export { A_Feature_Define } from './global/A-Feature/A-Feature-Define.decorator';
+export { A_Feature_Extend } from './global/A-Feature/A-Feature-Extend.decorator';
+export { A_Abstraction_Extend } from './global/A-Abstraction/A-Abstraction-Extend.decorator';
+export { A_Dependency_Require } from './global/A-Dependency/A-Dependency-Require.decorator';
+export { A_Dependency_Load } from './global/A-Dependency/A-Dependency-Load.decorator';
+export { A_Dependency_Default } from './global/A-Dependency/A-Dependency-Default.decorator';
+
+
+// =================================================================================================
+// =============================== Export Helpers ================================================
+// =================================================================================================
+export { A_CommonHelper } from './helpers/A_Common.helper';
+export { A_FormatterHelper } from './helpers/A_Formatter.helper';
+export { A_IdentityHelper, A_ID_TYPES__TimeId_Parts } from './helpers/A_Identity.helper';
+export { A_StepsManager } from './global/A-StepManager/A-StepManager.class';
+export { A_StepManagerError } from './global/A-StepManager/A-StepManager.error';
+export { A_TypeGuards } from './helpers/A_TypeGuards.helper';
+

package/tests/A-Component.test.ts

@@ -27,7 +27,7 @@ describe('A-Component tests', () => {
         A_Context.root.register(MyComponent);
         A_Context.root.register(DependentComponent);
 
-        const dependentComponent = A_Context.root.resolve(DependentComponent);
+        const dependentComponent = A_Context.root.resolve(DependentComponent)!;
 
         expect(dependentComponent.dependency).toBeInstanceOf(MyComponent);
     });

package/tests/A-Concept.test.ts

@@ -98,14 +98,13 @@ describe('A-Concept tests', () => {
         const containerBScope = A_Context.scope(containerB)
 
         expect(containerAScope.resolveConstructor('MyEntityA')).toBe(MyEntityA);
-        expect(() => {
-            containerAScope.resolveConstructor('MyEntityB');
-        }).toThrow();
+        const undefinedMyEntityB = containerAScope.resolveConstructor('MyEntityB');
+        expect(undefinedMyEntityB).toBeUndefined();
 
         expect(containerBScope.resolveConstructor('MyEntityB')).toBe(MyEntityB);
-        expect(() => {
-            containerBScope.resolveConstructor('MyEntityA');
-        }).toThrow();
+        const undefinedMyEntityA = containerBScope.resolveConstructor('MyEntityA');
+
+        expect(undefinedMyEntityA).toBeUndefined();
 
         expect(concept.scope.resolve(MyContext)).toEqual(sharedContext);
         expect(concept.scope.resolve(MyContext)).toEqual(sharedContext);