@adaas/a-concept 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A-Concept is a framework of the new generation that is tailored to use AI, enabling developers to create AI-powered applications with ease. It provides a structured approach to building, managing, and deploying AI-driven solutions.",
   "license": "Apache-2.0",
   "author": {

package/src/env/env.base.ts

@@ -31,7 +31,7 @@ export class A_CONCEPT_BASE_ENV {
    * Environment of the application e.g. development, production, staging
    */
   static get A_CONCEPT_ENVIRONMENT() {
-    return "production";
+    return "development";
   }
   /**
    * Runtime environment of the application e.g. browser, node

package/src/lib/A-Context/A-Context.class.ts

@@ -36,9 +36,9 @@ import {
 } from "@adaas/a-concept/a-entity";
 import { A_TYPES__A_StageStep } from "@adaas/a-concept/a-stage";
 import { A_TYPES__ContextEnvironment } from "./A-Context.types";
-import { A_TypeGuards} from "@adaas/a-concept/helpers/A_TypeGuards.helper";
-import { A_FormatterHelper} from "@adaas/a-concept/helpers/A_Formatter.helper";
-import { A_CommonHelper} from "@adaas/a-concept/helpers/A_Common.helper";
+import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
+import { A_FormatterHelper } from "@adaas/a-concept/helpers/A_Formatter.helper";
+import { A_CommonHelper } from "@adaas/a-concept/helpers/A_Common.helper";
 import { A_ContextError } from "./A-Context.error";
 import {
     A_Fragment,
@@ -684,17 +684,7 @@ export class A_Context {
             throw new A_ContextError(A_ContextError.InvalidScopeParameterError, `Invalid parameter provided to get scope. Component of type ${name} is not allowed for scope allocation.`);
 
         switch (true) {
-            case this.isAllowedForScopeAllocation(param1):
-
-                // Check if the parameter has a scope allocated
-                if (!instance._registry.has(param1))
-                    throw new A_ContextError(
-                        A_ContextError.ScopeNotFoundError,
-                        `Invalid parameter provided to get scope. Component of type ${name} does not have a scope allocated. Make sure to allocate a scope using A_Context.allocate() method before trying to get the scope.`
-                    );
 
-                // If the parameter is allowed for scope allocation, return the scope
-                return instance._registry.get(param1)!;
 
             case this.isAllowedToBeRegistered(param1):
 
@@ -707,6 +697,18 @@ export class A_Context {
 
                 // If the parameter is allowed to be registered, return the scope from the storage
                 return instance._scopeStorage.get(param1)!;
+
+            case this.isAllowedForScopeAllocation(param1):
+
+                // Check if the parameter has a scope allocated
+                if (!instance._registry.has(param1))
+                    throw new A_ContextError(
+                        A_ContextError.ScopeNotFoundError,
+                        `Invalid parameter provided to get scope. Component of type ${name} does not have a scope allocated. Make sure to allocate a scope using A_Context.allocate() method before trying to get the scope.`
+                    );
+
+                // If the parameter is allowed for scope allocation, return the scope
+                return instance._registry.get(param1)!;
             default:
                 throw new A_ContextError(A_ContextError.InvalidScopeParameterError, `Invalid parameter provided to get scope. Component of type ${name} is not allowed to be registered.`);
         }
@@ -1076,7 +1078,8 @@ export class A_Context {
      */
     static isAllowedForScopeAllocation(param: any): param is A_TYPES__ScopeLinkedComponents {
         return A_TypeGuards.isContainerInstance(param)
-            || A_TypeGuards.isFeatureInstance(param);
+            || A_TypeGuards.isFeatureInstance(param)
+            || A_TypeGuards.isEntityInstance(param);
     }
     /**
      * Type guard to check if the param is allowed to be registered in the context.

package/src/lib/A-Dependency/A-Dependency-Query.decorator.ts

@@ -0,0 +1,90 @@
+
+import { A_Context } from "@adaas/a-concept/a-context";
+import { A_Meta } from "@adaas/a-concept/a-meta";
+import { A_TYPES__ComponentMetaKey } from "@adaas/a-concept/a-component";
+import { A_TYPES__ContainerMetaKey } from "@adaas/a-concept/a-container";
+import { A_TYPES__A_Dependency_EntityInjectionPagination, A_TYPES__A_Dependency_EntityInjectionQuery, A_TYPES__A_Dependency_EntityResolutionConfig, A_TYPES__A_Dependency_QueryDecoratorReturn } from "./A-Dependency.types";
+import { A_DependencyError } from "./A-Dependency.error";
+import type { A_Entity } from "@adaas/a-concept/a-entity";
+import { A_TYPES__EntityMetaKey } from "@adaas/a-concept/a-entity";
+import {
+    A_TYPES__A_InjectDecorator_Meta,
+    A_TYPES__InjectableTargets
+} from "@adaas/a-concept/a-inject";
+import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
+import { A_CommonHelper } from "@adaas/a-concept/helpers/A_Common.helper";
+
+/**
+ * Query Decorator is only applicable for Entities since Scope instance may have multiple entities but only one component or container, so there is no need for such complex resolution strategies for them, but for entities it is a common case to have multiple instances and need to specify which one(s) to inject.
+ * 
+ * 
+ * @param query 
+ * @returns 
+ */
+export function A_Dependency_Query<T extends A_Entity = A_Entity>(
+    query: Partial<A_TYPES__A_Dependency_EntityInjectionQuery<T>>,
+    pagination?: Partial<A_TYPES__A_Dependency_EntityInjectionPagination>
+): A_TYPES__A_Dependency_QueryDecoratorReturn {
+
+    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-All 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;
+
+            case A_TypeGuards.isEntityInstance(target):
+                metaKey = A_TYPES__EntityMetaKey.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].resolutionStrategy = {
+            query: {
+                ...paramsArray[parameterIndex].resolutionStrategy.query,
+                ...query
+            },
+            pagination: {
+                ...paramsArray[parameterIndex].resolutionStrategy.pagination,
+                ...pagination
+            }
+        }
+
+        // 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/lib/A-Dependency/A-Dependency.class.ts

@@ -14,6 +14,7 @@ import {
 } from "./A-Dependency.types";
 import { A_TYPES__Ctor } from "@adaas/a-concept/types";
 import { A_Dependency_All } from "./A-Dependency-All.decorator";
+import { A_Dependency_Query } from "./A-Dependency-Query.decorator";
 
 
 export class A_Dependency<
@@ -74,6 +75,16 @@ export class A_Dependency<
         return A_Dependency_All;
     }
 
+    /**
+     * Allows to indicate that the dependency should be resolved by specific query parameters
+     * e.g. by ASEID, name, type, custom properties, etc.
+     * 
+     * @returns
+     */
+    static get Query(): typeof A_Dependency_Query {
+        return A_Dependency_Query;
+    }
+
     protected _name: string;
     protected _target?: A_TYPES__Ctor<T>;
     protected _resolutionStrategy!: A_TYPES__A_DependencyResolutionStrategy;

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

@@ -4,7 +4,7 @@ import { A_TYPES__Ctor } from "@adaas/a-concept/types";
 import { A_Caller } from "@adaas/a-concept/a-caller";
 import { A_Component } from "@adaas/a-concept/a-component";
 import { A_Container } from "@adaas/a-concept/a-container";
-import { A_Entity } from "@adaas/a-concept/a-entity"
+import { A_Entity, A_TYPES__Entity_Constructor } from "@adaas/a-concept/a-entity"
 import { A_Error } from "@adaas/a-concept/a-error";
 import { A_Feature } from "@adaas/a-concept/a-feature";
 import { A_Fragment } from "@adaas/a-concept/a-fragment";
@@ -163,3 +163,14 @@ export type A_TYPES__A_Dependency_AllDecoratorReturn<T = any> = (
     propertyKey: string | symbol | undefined,
     parameterIndex: number
 ) => void
+
+export type A_TYPES__A_Dependency_QueryTarget<T extends A_Entity = A_Entity> = T
+    | A_TYPES__Entity_Constructor<T>
+/**
+ * A-Dependency Query decorator return type
+ */
+export type A_TYPES__A_Dependency_QueryDecoratorReturn<T = any> = (
+    target: T,
+    propertyKey: string | symbol | undefined,
+    parameterIndex: number
+) => void

package/src/lib/A-Dependency/index.ts

@@ -13,5 +13,6 @@ export { A_Dependency_Flat } from './A-Dependency-Flat.decorator';
 export { A_Dependency_Load } from './A-Dependency-Load.decorator';
 export { A_Dependency_Parent } from './A-Dependency-Parent.decorator';
 export { A_Dependency_Require } from './A-Dependency-Require.decorator';
+export { A_Dependency_Query } from './A-Dependency-Query.decorator';
 
 

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

@@ -179,8 +179,10 @@ export class A_Scope<
     get parent(): A_Scope | undefined {
         return this._parent;
     }
+    
     /**
-     * A_Scope refers to the visibility and accessibility of :
+     * A_Scope is a unique A-Concept Structure that allows to operate with A-Concept Primitives and Models in a specific context and with specific rules.  
+     *  It refers to the visibility and accessibility of :
      * - variables, 
      * - Components, 
      * - Context Fragments 

package/src/lib/A-Scope/A-Scope.types.ts

@@ -89,7 +89,7 @@ export type A_TYPES__ScopeLinkedConstructors = A_TYPES__Container_Constructor |
 /**
  * A list of components that can have a scope associated with them
  */
-export type A_TYPES__ScopeLinkedComponents = A_Container | A_Feature;
+export type A_TYPES__ScopeLinkedComponents = A_Container | A_Feature | A_Entity
 /**
  * A list of components that are dependent on a scope and do not have their own scope
  */

package/tests/A-Dependency.test.ts

@@ -455,4 +455,71 @@ describe('A-Dependency tests', () => {
 
     });
 
+    it('Should be possible to use query decorator for A_Entities in scope', async () => {
+
+        class MyEntity_A extends A_Entity<{ name: string, group: string }> {
+            name!: string;
+            group!: string;
+
+            fromNew(newEntity: { name: string; group: string }): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+                this.group = newEntity.group;
+            }
+        }
+
+        class MyComponent extends A_Component {
+            @A_Feature.Extend()
+            async simpleQuery(
+                @A_Dependency.Query<MyEntity_A>({ name: 'Entity 1' })
+                @A_Inject(MyEntity_A) entity: MyEntity_A,
+            ) {
+                expect(entity.name).toBe('Entity 1');
+            }
+
+            @A_Feature.Extend()
+            async andQuery(
+                @A_Dependency.Query<MyEntity_A>({ name: 'Entity 1', group: 'Group 1' })
+                @A_Inject(MyEntity_A) entity: MyEntity_A,
+            ) {
+                expect(entity.name).toBe('Entity 1');
+                expect(entity.group).toBe('Group 1');
+            }
+
+            @A_Feature.Extend()
+            async paginationQuery(
+                @A_Dependency.Query<MyEntity_A>({ name: 'Entity 1' }, { count: 2 })
+                @A_Inject(MyEntity_A) entities: MyEntity_A[],
+            ) {
+
+                expect(entities.length).toBe(2);
+                expect(entities[0].name).toBe('Entity 1');
+                expect(entities[0].group).toBe('Group 1');
+                expect(entities[1].name).toBe('Entity 1');
+                expect(entities[1].group).toBe('Group 2');
+            }
+        }
+
+        const scope = new A_Scope({
+            name: 'Test Scope',
+            components: [MyComponent],
+            entities: [
+                new MyEntity_A({ name: 'Entity 1', group: 'Group 1' }),
+                new MyEntity_A({ name: 'Entity 2', group: 'Group 1' }),
+                new MyEntity_A({ name: 'Entity 1', group: 'Group 2' }),
+                new MyEntity_A({ name: 'Entity 2', group: 'Group 2' }),
+                new MyEntity_A({ name: 'Entity 3', group: 'Group 2' }),
+                new MyEntity_A({ name: 'Entity 1', group: 'Group 3' }),
+                new MyEntity_A({ name: 'Entity 2', group: 'Group 3' }),
+            ]
+        });
+
+        const componentInstance = scope.resolve(MyComponent);
+
+        await componentInstance?.call('simpleQuery');
+        await componentInstance?.call('andQuery');
+        await componentInstance?.call('paginationQuery');
+
+    });
+
 });

package/tests/A-Entity.test.ts

@@ -6,6 +6,7 @@ import {
 } from "@adaas/a-concept/a-entity";
 import { A_Feature } from "@adaas/a-concept/a-feature";
 import { ASEID } from '@adaas/a-concept/aseid';
+import { A_Scope } from "@adaas/a-concept/a-scope";
 
 jest.retryTimes(0);
 
@@ -21,6 +22,106 @@ describe('A-Entity tests', () => {
         expect(entity.aseid.concept).toBe('a-concept');
 
     });
+    it('Should handle proper types declaration', async () => {
+        type MyInitType = {
+            name: string;
+            customId: number;
+        }
+
+        type mySerializedType = {
+            name: string;
+            serializedFlag: boolean;
+            customId: number;
+        } & A_TYPES__Entity_Serialized;
+
+        class MyEntity extends A_Entity<MyInitType, mySerializedType> {
+            public name!: string;
+            public customId!: number;
+
+            fromNew(newEntity: MyInitType): void {
+                super.fromNew(newEntity);
+                this.name = newEntity.name;
+                this.customId = newEntity.customId;
+            }
+
+            fromJSON(serialized: mySerializedType): void {
+                this.aseid = new ASEID(serialized.aseid);
+                this.name = serialized.name;
+                this.customId = serialized.customId;
+                return;
+            }
+
+
+            toJSON(): mySerializedType {
+                return {
+                    ...super.toJSON(),
+                    name: this.name,
+                    customId: this.customId,
+                    serializedFlag: true,
+                };
+            }
+        }
+
+
+        const entityInstance = new MyEntity({
+            name: 'Test Entity',
+            customId: 42,
+        });
+
+        expect(entityInstance.name).toBe('Test Entity');
+        expect(entityInstance.customId).toBe(42);
+
+        const serialized = entityInstance.toJSON();
+        expect(serialized.name).toBe('Test Entity');
+        expect(serialized.customId).toBe(42);
+        expect(serialized.serializedFlag).toBe(true);
+
+        const deserializedEntity = new MyEntity(serialized);
+        expect(deserializedEntity.name).toBe('Test Entity');
+        expect(deserializedEntity.customId).toBe(42);
+        expect(deserializedEntity.aseid.toString()).toBe(entityInstance.aseid.toString());
+    });
+    it('Should be possible to allocate a scope for entity', async () => {
+
+        let resultScope: A_Scope | undefined = undefined;
+
+
+        class MyEntity extends A_Entity {
+
+            scope!: A_Scope;
+
+            fromNew(newEntity: any): void {
+                super.fromNew(newEntity);
+
+                resultScope = new A_Scope({ name: 'entity-scope' });
+
+                this.scope = A_Context.allocate(this, resultScope);
+            }
+
+            fromUndefined(): void {
+                super.fromUndefined();
+
+                resultScope = new A_Scope({ name: 'entity-scope' });
+
+                this.scope = A_Context.allocate(this, resultScope);
+            }
+
+        }
+
+
+        const entityInstance = new MyEntity();
+
+
+        const ParentScope = new A_Scope({
+            name: 'parent-scope',
+            entities: [entityInstance]
+        });
+
+        expect(resultScope).toBeInstanceOf(A_Scope);
+        expect(entityInstance.scope).toBe(resultScope);
+        expect(resultScope!.issuer()).toBe(entityInstance);
+        expect(A_Context.scope(entityInstance)).toBe(ParentScope);
+    });
     it('Should Allow to create an entity with overridden ASEID Scope or Concept', async () => {
         class MyEntity extends A_Entity {
             static get entity(): string {