@adaas/a-concept 0.1.56 → 0.1.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "description": "A-Concept is a framework to build new Applications within or outside the ADAAS ecosystem. This framework is designed to be modular structure regardless environment and program goal.",
   "license": "Apache-2.0",
   "main": "./dist/index.cjs",

package/src/global/A-Dependency/A-Dependency-Flat.decorator.ts

@@ -0,0 +1,68 @@
+
+import { A_Context } from "@adaas/a-concept/global/A-Context/A-Context.class";
+import { A_Meta } from "@adaas/a-concept/global/A-Meta/A-Meta.class";
+import { A_TYPES__ComponentMetaKey } from "@adaas/a-concept/global/A-Component/A-Component.constants";
+import { A_TYPES__ContainerMetaKey } from "@adaas/a-concept/global/A-Container/A-Container.constants";
+import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
+import { A_TYPES__A_InjectDecorator_Meta, A_TYPES__InjectableTargets } from "../A-Inject/A-Inject.types";
+import { A_TYPES__A_Dependency_FlatDecoratorReturn } from "./A-Dependency.types";
+import { A_DependencyError } from "./A-Dependency.error";
+import { A_CommonHelper } from "@adaas/a-concept/helpers/A_Common.helper";
+
+
+/**
+ * Should indicate which dependency is required
+ */
+export function A_Dependency_Flat(): A_TYPES__A_Dependency_FlatDecoratorReturn {
+
+    return function (
+        target: A_TYPES__InjectableTargets,
+        methodName: string | symbol | undefined,
+        parameterIndex: number
+    ) {
+        // for Error handling purposes
+        const componentName = A_CommonHelper.getComponentName(target)
+
+        if (!A_TypeGuards.isTargetAvailableForInjection(target)) {
+            throw new A_DependencyError(
+                A_DependencyError.InvalidDependencyTarget,
+                `A-Dependency cannot be used on the target of type ${typeof target} (${componentName})`
+            );
+        }
+
+        // determine the method name or 'constructor' for constructor injections
+        const method = methodName ? String(methodName) : 'constructor';
+        let metaKey;
+
+        switch (true) {
+            case A_TypeGuards.isComponentConstructor(target) || A_TypeGuards.isComponentInstance(target):
+                metaKey = A_TYPES__ComponentMetaKey.INJECTIONS;
+                break;
+
+            case A_TypeGuards.isContainerInstance(target):
+                metaKey = A_TYPES__ContainerMetaKey.INJECTIONS;
+                break;
+        }
+
+        // get existing meta or create a new one
+        const existedMeta = A_Context.meta(target).get(metaKey) || new A_Meta();
+        // get existing injections for the method or create a new array
+        const paramsArray: A_TYPES__A_InjectDecorator_Meta = existedMeta.get(method) || [];
+
+        // set the parameter injection info
+        paramsArray[parameterIndex] = {
+            ...(paramsArray[parameterIndex] || {}),
+            flat: true,
+        }
+        // save back the updated injections array
+        existedMeta.set(method, paramsArray);
+
+        // save back the updated meta info
+        A_Context
+            .meta(target)
+            .set(
+                metaKey,
+                existedMeta
+            );
+    }
+}

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

@@ -1,4 +1,5 @@
 import { A_Dependency_Default } from "./A-Dependency-Default.decorator";
+import { A_Dependency_Flat } from "./A-Dependency-Flat.decorator";
 import { A_Dependency_Load } from "./A-Dependency-Load.decorator";
 import { A_Dependency_Parent } from "./A-Dependency-Parent.decorator";
 import { A_Dependency_Require } from "./A-Dependency-Require.decorator";
@@ -41,6 +42,16 @@ export class A_Dependency {
         return A_Dependency_Parent;
     }
 
+    /**
+     * Allows to indicate that the dependency should be resolved in a flat manner
+     * Only in the same scope, without going up to parent scopes
+     * 
+     * @returns 
+     */
+    static get Flat(): typeof A_Dependency_Flat {
+        return A_Dependency_Flat;
+    }
+
     protected _name: string;
 
     /**

package/src/global/A-Dependency/A-Dependency.types.ts

@@ -32,4 +32,10 @@ export type A_TYPES__A_Dependency_ParentDecoratorReturn<T = any> = (
     target: T,
     propertyKey: string | symbol | undefined,
     parameterIndex: number
+) => void
+
+export type A_TYPES__A_Dependency_FlatDecoratorReturn<T = any> = (
+    target: T,
+    propertyKey: string | symbol | undefined,
+    parameterIndex: number
 ) => void

package/src/global/A-Inject/A-Inject.types.ts

@@ -39,6 +39,7 @@ export type A_TYPES__A_InjectDecorator_Meta = Array<{
     parent?: {
         layerOffset?: number
     },
+    flat?: boolean
     create?: boolean
     instructions?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>,
 }>;

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

@@ -200,6 +200,46 @@ export class A_Scope<
         initializer.call(this, param1, param2);
     }
 
+    /**
+     * Generator to iterate through all parent scopes
+     */
+    *parents(): Generator<A_Scope> {
+        let currentParent = this._parent;
+        while (currentParent) {
+            yield currentParent;
+            currentParent = currentParent._parent;
+        }
+    }
+
+    /**
+     * This method is used to retrieve a parent scope at a specific level
+     * 
+     * [!] Note that if the level is out of bounds, undefined is returned
+     * [!!] Uses negative values for levels (e.g. -1 for immediate parent, -2 for grandparent, etc.)
+     * 
+     * @param level 
+     * @returns 
+     */
+    parentOffset(
+        /**
+         * Level of the parent scope to retrieve
+         * 
+         * Examples:
+         * - level 0 - immediate parent
+         * - level -1 - grandparent
+         * - level -2 - great-grandparent
+         */
+        layerOffset: number
+    ): A_Scope | undefined {
+        let parentScope = this.parent;
+
+        while (layerOffset < -1 && parentScope) {
+            parentScope = parentScope.parent;
+            layerOffset++;
+        }
+
+        return parentScope;
+    }
 
 
     /**
@@ -461,7 +501,7 @@ export class A_Scope<
     ): boolean {
 
         let found = this.hasFlat(ctor as any);
-        
+
         if (!found && !!this._parent)
             try {
                 return this._parent.has(ctor as any);
@@ -1396,7 +1436,7 @@ export class A_Scope<
                         const componentName = A_CommonHelper.getComponentName(arg.target)
 
                         if ('instructions' in arg && !!arg.instructions) {
-                            const { target, instructions } = arg
+                            const { target, parent, flat, instructions } = arg
                             const dependency = this.resolve(target as any, instructions);
                             if (!dependency)
                                 throw new A_ScopeError(
@@ -1406,17 +1446,47 @@ export class A_Scope<
 
                             return dependency;
                         } else {
-                            const { target, require, create, defaultArgs } = arg;
+                            const { target, require, create, defaultArgs, parent, flat, } = arg;
 
-                            let dependency = this.resolve(target as any);
+                            let dependency;
 
+                            // ----------------- Resolution Strategies -----------------
+                            switch (true) {
+                                // 1) Flat resolution
+                                case flat: {
+                                    dependency = this.resolveFlat(target);
+                                    break;
+                                }
+                                // 2) Parent resolution
+                                case parent && typeof parent.layerOffset === 'number': {
+                                    const targetParent = this.parentOffset(parent.layerOffset);
+                                    if(!targetParent) {
+                                        throw new A_ScopeError(
+                                            A_ScopeError.ResolutionError,
+                                            `Unable to resolve parent scope at offset ${parent.layerOffset} for dependency ${componentName} for component ${component.name} in scope ${this.name}`
+                                        );
+                                    }
+                                    dependency = targetParent.resolve(target);
+
+                                    break;
+                                }
+                                // 3) Normal resolution
+                                default: {
+                                    dependency = this.resolve(target);
+                                    break;
+                                }
+                            }
+
+                            // ----------------- Post-Resolution Actions -----------------
+
+                            // 1) Create default instance in case when allowed
                             if (create && !dependency && A_TypeGuards.isAllowedForDependencyDefaultCreation(target)) {
-                                const newDependency = new target(...defaultArgs);
+                                dependency = new target(...defaultArgs);
 
-                                this.register(newDependency);
-                                return newDependency;
+                                this.register(dependency);
                             }
 
+                            // 2) Throw error in case when required but not resolved
                             if (require && !dependency) {
                                 throw new A_ScopeError(
                                     A_ScopeError.ResolutionError,
@@ -1424,6 +1494,8 @@ export class A_Scope<
                                 );
                             }
 
+
+                            //  Finally, return the dependency (either resolved or undefined)
                             return dependency;
                         }
                     });

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

@@ -140,29 +140,38 @@ export class A_Stage {
                             return this._feature;
 
                         default: {
-                            const { target, require, create, defaultArgs, parent } = arg;
+                            const { target, require, create, defaultArgs, parent, flat } = arg;
 
 
                             let dependency;
                             let targetScope = scope;
 
-                            if (parent && typeof parent.layerOffset === 'number') {
-                                let parentScope = scope.parent;
 
-                                let offset = parent.layerOffset;
-
-                                while (offset < -1 && parentScope) {
-                                    parentScope = parentScope.parent;
-                                    offset++;
+                            switch (true) {
+                                // 1) Flat resolution
+                                case flat: {
+                                    dependency = targetScope.resolveFlat(target);
+                                    break;
                                 }
-
-                                if (parentScope) {
-                                    dependency = parentScope.resolve(target);
-                                    targetScope = parentScope;
+                                // 2) Parent resolution
+                                case parent && typeof parent.layerOffset === 'number': {
+                                    const targetParent = targetScope.parentOffset(parent.layerOffset);
+                                    if (!targetParent) {
+                                        throw new A_StageError(
+                                            A_StageError.ArgumentsResolutionError,
+                                            `Unable to resolve parent scope at layer offset ${parent.layerOffset} for argument ${A_CommonHelper.getComponentName(arg.target)} for stage ${this.name} in scope ${scope.name}`
+                                        );
+                                    }
+                                    dependency = targetParent.resolve(target);
+                                    targetScope = targetParent;
+
+                                    break;
+                                }
+                                // 3) Normal resolution
+                                default: {
+                                    dependency = targetScope.resolve(target);
+                                    break;
                                 }
-
-                            } else {
-                                dependency = targetScope.resolve(target);
                             }
 
                             if (create && !dependency && A_TypeGuards.isAllowedForDependencyDefaultCreation(target)) {

package/tests/A-Dependency.test.ts

@@ -89,5 +89,203 @@ describe('A-Dependency tests', () => {
         expect(instance!.component).toBeInstanceOf(MyCustomEntity);
         expect(instance!.component.foo).toBe('bar');
     });
+    it('Should resolve only dependency on the same level with Flat directive', async () => {
+        class ParentComponent extends A_Component { }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Flat()
+                @A_Inject(ParentComponent) public parentComponent?: ParentComponent,
+            ) {
+                super();
+
+            }
+        }
+
+        const parentScope = new A_Scope({ components: [ParentComponent] });
+        const childScope = new A_Scope({ components: [ChildComponent] }, { parent: parentScope });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.parentComponent).toBeUndefined();
+    });
+
+    it('Should resolve create dependency with Create directive', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string }> {
+            name!: string;
+
+            fromNew(newEntity: { name: string; }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+            }
+        }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Default({ name: 'Entity A' })
+                @A_Inject(MyEntity_A) public myEntityA: MyEntity_A,
+            ) {
+                super();
+
+            }
+        }
+
+        const childScope = new A_Scope({ components: [ChildComponent], entities: [MyEntity_A] });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.myEntityA).toBeInstanceOf(MyEntity_A);
+        expect(instance!.myEntityA.name).toBe('Entity A');
+    });
+    it('Should resolve Parent entity if it exists, even if Default provided', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string }> {
+            name!: string;
+
+            fromNew(newEntity: { name: string; }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+            }
+        }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Default({ name: 'Child Entity' })
+                @A_Inject(MyEntity_A) public myEntityA: MyEntity_A,
+            ) {
+                super();
+
+            }
+        }
+
+        const parentScope = new A_Scope({ entities: [new MyEntity_A({ name: 'Parent Entity' })] });
+        const childScope = new A_Scope({ components: [ChildComponent] }, { parent: parentScope });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.myEntityA).toBeInstanceOf(MyEntity_A);
+        expect(instance!.myEntityA.name).toBe('Parent Entity');
+    });
+    it('Should resolve dependencies properly with combination of Directives', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string }> {
+            name!: string;
+
+            fromNew(newEntity: { name: string; }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+            }
+        }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Flat()
+                @A_Dependency.Default({ name: 'Child Entity' })
+                @A_Inject(MyEntity_A) public myEntityA: MyEntity_A,
+            ) {
+                super();
+
+            }
+        }
+
+        const parentScope = new A_Scope({ entities: [new MyEntity_A({ name: 'Parent Entity' })] });
+        const childScope = new A_Scope({ components: [ChildComponent] }, { parent: parentScope });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.myEntityA).toBeInstanceOf(MyEntity_A);
+        expect(instance!.myEntityA.name).toBe('Child Entity');
+    })
+    it('Should resolve dependency from parent scope with  Parent Directive', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string }> {
+            name!: string;
+
+            fromNew(newEntity: { name: string; }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+            }
+        }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Parent()
+                @A_Inject(MyEntity_A) public myEntityA: MyEntity_A,
+            ) {
+                super();
+
+            }
+        }
+
+        const parentScope = new A_Scope({
+            name: 'Parent Scope',
+            entities: [new MyEntity_A({ name: 'Parent Entity' })]
+        });
+        const childScope = new A_Scope({
+            name: 'Child Scope',
+            components: [ChildComponent],
+            entities: [new MyEntity_A({ name: 'Child Entity' })]
+        }, { parent: parentScope });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.myEntityA).toBeInstanceOf(MyEntity_A);
+        expect(instance!.myEntityA.name).toBe('Parent Entity');
+    });
+    it('Should resolve dependency from parent scope with  Parent Directive and offset', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string }> {
+            name!: string;
+
+            fromNew(newEntity: { name: string; }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+            }
+        }
+
+        class ChildComponent extends A_Component {
+            constructor(
+                @A_Dependency.Parent(-2)
+                @A_Inject(MyEntity_A) public myEntityA: MyEntity_A,
+            ) {
+                super();
+
+            }
+        }
+
+        const grandparentScope = new A_Scope({
+            name: 'Grandparent Scope',
+            entities: [new MyEntity_A({ name: 'Grandparent Entity' })]
+        });
+        
+        const parentScope = new A_Scope({
+            name: 'Parent Scope',
+            entities: [new MyEntity_A({ name: 'Parent Entity' })]
+        }, { parent: grandparentScope });
+
+        const childScope = new A_Scope({
+            name: 'Child Scope',
+            components: [ChildComponent],
+            entities: [new MyEntity_A({ name: 'Child Entity' })]
+        }, { parent: parentScope });
+
+        const instance = childScope.resolve(ChildComponent);
+
+        expect(instance).toBeDefined();
+        expect(instance).toBeInstanceOf(ChildComponent);
+        expect(instance!.myEntityA).toBeInstanceOf(MyEntity_A);
+        expect(instance!.myEntityA.name).toBe('Grandparent Entity');
+    });
 
 });