@adaas/a-concept 0.0.55 → 0.0.57

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

@@ -9,8 +9,8 @@ import {
 } from "./A-Entity.types";
 import { A_CONSTANTS__DEFAULT_ERRORS } from "@adaas/a-utils/dist/src/constants/errors.constants";
 import { A_Context } from "../A-Context/A-Context.class";
-import { A_TYPES__FeatureCallParams } from "../A-Feature/A-Feature.types";
 import { A_Scope } from "../A-Scope/A-Scope.class";
+import { A_CONSTANTS__DEFAULT_ENV_VARIABLES, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY } from "@adaas/a-concept/constants/env.constants";
 
 
 
@@ -27,8 +27,10 @@ export class A_Entity<
 >
     implements A_TYPES__IEntity {
 
-    aseid!: ASEID;
 
+    // ====================================================================
+    // ================== Static A-Entity Information ============================
+    // ====================================================================
 
     /**
      * Entity Identifier that corresponds to the class name
@@ -40,6 +42,49 @@ export class A_Entity<
             .replace(/_/g, '-');
     }
 
+    /**
+     * DEFAULT Namespace of the entity from environment variable A_CONCEPT_NAMESPACE
+     * [!] If environment variable is not set, it will default to 'a-concept'
+     */
+    static get namespace(): string {
+        return process && process.env ? process.env[A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_NAMESPACE] || 'a-concept' : 'a-concept';
+    }
+
+    /**
+     * DEFAULT Scope of the entity from environment variable A_CONCEPT_DEFAULT_SCOPE
+     * [!] If environment variable is not set, it will default to 'core'
+     * [!] Scope is an application specific identifier that can be used to group entities together
+     * [!] e.g. 'default', 'core', 'public', 'internal', etc
+     */
+    static get scope(): string {
+        return process && process.env ? process.env[A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_DEFAULT_SCOPE] || 'core' : 'core';
+    }
+
+    // ====================================================================
+    // ================== Instance A-Entity Information ====================
+    // ====================================================================
+
+    /**
+     * ASEID is an entity identifier that is unique across the system
+     * A - A_Concept or Application
+     * S - System or Scope
+     * E - Entity
+     * ID - Identifier
+     * 
+     * [!] ASEID is immutable and should not be changed after the entity is created
+     * 
+     * [!] ASEID is composed of the following parts:
+     * - namespace: an application specific identifier from where the entity is coming from
+     * - scope: the scope of the entity from Application Namespace
+     * - entity: the name of the entity from Application Namespace
+     * - id: the unique identifier of the entity
+     *
+     * [!] For more information about ASEID, please refer to the ASEID class documentation]
+     */
+    aseid!: ASEID;
+
+
+
     /**
      * Create a new A_entity instance from Aseid String
      * e.g. project@scope:entity:0000000001
@@ -50,7 +95,7 @@ export class A_Entity<
         /**
          * ASEID string that represents the entity
          */
-        aseid: string
+        aseid?: string
     )
     /**
      * Create a new A_entity instance from Aseid instance
@@ -84,15 +129,72 @@ export class A_Entity<
         /**
          * Constructor object that represents the entity
          */
-        newEntity: _ConstructorType
+        newEntity?: _ConstructorType
     )
-    constructor(props: string | ASEID | _SerializedType | _ConstructorType) {
+    constructor(props?: string | ASEID | _SerializedType | _ConstructorType) {
 
         const initializer = this.getInitializer(props);
         // the returned initializer is already bound to `this` (we used .bind(this)),
         // so calling it will run the appropriate logic on this instance:
         initializer.call(this, props);
     }
+    // ====================================================================
+    // ================== DUPLICATED ASEID Getters ========================
+    // ====================================================================
+
+    /**
+     * Extracts the ID from the ASEID
+     * ID is the unique identifier of the entity
+     */
+    get id(): string | number {
+        return this.aseid.id;
+    }
+
+    /**
+     * Extracts the namespace from the ASEID
+     * namespace is an application specific identifier from where the entity is coming from
+     */
+    get namespace(): string {
+        return this.aseid.namespace
+    }
+
+    /**
+     * Extracts the scope from the ASEID
+     * scope is the scope of the entity from Application Namespace
+     */
+    get scope(): string {
+        return this.aseid.scope;
+    }
+
+    /**
+     * Extracts the entity from the ASEID
+     * entity is the name of the entity from Application Namespace
+     * 
+     */
+    get entity(): string {
+        return this.aseid.entity;
+    }
+
+    /**
+     * Extracts the version from the ASEID
+     * version is the version of the entity
+     */
+
+    get version(): string | undefined {
+        return this.aseid.version;
+    }
+
+    /**
+     * Extracts the shard from the ASEID
+     * shard is the shard of the entity
+     */
+    get shard(): string | undefined {
+        return this.aseid.shard;
+    }
+
+    // ====================================================================
+    // ================== Constructor Helpers =============================
+    // ====================================================================
 
 
     // --- Type guards used to classify `props` properly ---
@@ -126,10 +228,42 @@ export class A_Entity<
         return !!x && typeof x === "object" && !("aseid" in (x as object));
     }
 
-    // --- Overloads: provide precise return-type depending on input ---
+    /**
+     * Determines the appropriate initializer method based on the type of `props`.
+     * The method checks if `props` is:  
+     * 1) a string that matches ASEID format -> fromASEID
+     * 2) an ASEID instance -> fromASEID
+     * 3) a serialized object (has 'aseid') -> fromJSON
+     * 4) a plain object with no 'aseid' -> treat as constructor props -> fromNew
+     * 
+     * [!] If `props` is undefined, it will call fromUndefined method
+     * 
+     * If none of the above, it throws an error indicating incorrect constructor usage.
+     * 
+     * 
+     * To get a custom initializer, override this method in the child class.
+     * Example:
+     * ```typescript
+     * protected getInitializer(
+     *   props?: string | ASEID | _SerializedType | _ConstructorType
+     * ): (props: any) => void | (() => void) {
+     *   if('customField' in props) {
+     *       return this.fromCustomField.bind(this);
+     *   }
+     *   return super.getInitializer(props);
+     * }
+     * ```
+     * @param props
+     * @returns The appropriate initializer method
+     */
     protected getInitializer(
-        props: string | ASEID | _SerializedType | _ConstructorType
-    ): (props: any) => void {
+        props?: string | ASEID | _SerializedType | _ConstructorType
+    ): (props: any) => void | (() => void) {
+
+        if (!props) {
+            return this.fromUndefined
+        }
+
         // 1) string that matches ASEID format -> fromASEID
         if (this.isStringASEID(props)) {
             return this.fromASEID as (p: string) => void;
@@ -155,67 +289,10 @@ export class A_Entity<
     }
 
 
-
-
-    // ====================================================================
-    // ================== DUPLICATED ASEID Getters ========================
-    // ====================================================================
-
-    /**
-     * Extracts the ID from the ASEID
-     * ID is the unique identifier of the entity
-     */
-    get id(): string | number {
-        return this.aseid.id;
-    }
-
-    /**
-     * Extracts the namespace from the ASEID
-     * namespace is an application specific identifier from where the entity is coming from
-     */
-    get namespace(): string {
-        return this.aseid.namespace
-    }
-
     /**
-     * Extracts the scope from the ASEID
-     * scope is the scope of the entity from Application Namespace
-     */
-    get scope(): string {
-        return this.aseid.scope;
-    }
-
-    /**
-     * Extracts the entity from the ASEID
-     * entity is the name of the entity from Application Namespace
+     * Call a feature of the component with the provided scope
      * 
-     */
-    get entity(): string {
-        return this.aseid.entity;
-    }
-
-    /**
-     * Extracts the version from the ASEID
-     * version is the version of the entity
-     */
-
-    get version(): string | undefined {
-        return this.aseid.version;
-    }
-
-    /**
-     * Extracts the shard from the ASEID
-     * shard is the shard of the entity
-     */
-    get shard(): string | undefined {
-        return this.aseid.shard;
-    }
-
-
-
-
-    /**
-     * Call a feature of the component
+     * [!] If the provided scope is not inherited from the entity scope, it will be inherited
      * 
      * @param lifecycleMethod 
      * @param args 
@@ -228,8 +305,6 @@ export class A_Entity<
         //  or it can be inherited from the entity scope
         // [!Not Now!] however, each feature should create own scope regardless of the passed scope
         //  to avoid any possible side effects
-
-
         if (scope && !scope.isInheritedFrom(A_Context.scope(this))) {
             scope = scope.inherit(A_Context.scope(this));
         }
@@ -244,8 +319,6 @@ export class A_Entity<
     // ================== Entity Base Methods =============================
     // ====================================================================
 
-
-
     /**
      * The default method that can be called and extended to load entity data.
      */
@@ -275,6 +348,13 @@ export class A_Entity<
     // ================== Entity Serialization ============================
     // ====================================================================
 
+    /**
+     * Create a new entity from ASEID string or instance
+     * [!] Executed when the constructor is called with a string or ASEID instance that represents the ASEID
+     * [!] Executes By Default with new A_Entity('aseid-string') or new A_Entity(new ASEID(...)) if getInitializer has not been overridden
+     * 
+     * @param aseid 
+     */
     fromASEID(aseid: string | ASEID): void {
         if (typeof aseid === 'string' && ASEID.isASEID(aseid)) {
             this.aseid = new ASEID(aseid);
@@ -285,14 +365,56 @@ export class A_Entity<
         }
     }
 
+    /**
+     * Handles the case when no props are provided to the constructor.
+     * This method can be overridden in child classes to set default values or perform specific initialization logic.
+     * By default, it does nothing.
+     * 
+     * 
+     * @returns 
+     */
+    fromUndefined(): void {
+        this.aseid = new ASEID({
+            namespace: (this.constructor as typeof A_Entity).namespace,
+            scope: (this.constructor as typeof A_Entity).scope,
+            entity: (this.constructor as typeof A_Entity).entity,
+            id: `${new Date().getTime().toString()}-${Math.floor(Math.random() * 10000000).toString()}`,
+        });
+        return;
+    }
+
+    /**
+     * Create a new entity from constructor object
+     * [!] Executed when the constructor is called with an object that does not contain "aseid" property
+     * [!] Executes By Default with new A_Entity({}) if getInitializer has not been overridden
+     * 
+     * @param newEntity 
+     * @returns 
+     */
     fromNew(newEntity: _ConstructorType): void {
-        // this.aseid = new ASEID
+        this.aseid = new ASEID({
+            namespace: (this.constructor as typeof A_Entity).namespace,
+            scope: (this.constructor as typeof A_Entity).scope,
+            entity: (this.constructor as typeof A_Entity).entity,
+            id: `${new Date().getTime().toString()}-${Math.floor(Math.random() * 10000000).toString()}`,
+        });
 
         return;
     }
 
+
+    /**
+     * Creates a new entity from serialized object
+     * 
+     * [!] Executed when the constructor is called with an object that contains "aseid" property
+     * [!] Executes By Default with new A_Entity({ aseid: '...' }) if getInitializer has not been overridden
+     * 
+     * 
+     * @param serialized 
+     * @returns 
+     */
     fromJSON(serialized: _SerializedType): void {
-        this.aseid = new ASEID((serialized).aseid);
+        this.aseid = new ASEID(serialized.aseid);
         return;
     }
 
@@ -300,6 +422,8 @@ export class A_Entity<
 
     /**
      * Converts the entity to a JSON object 
+     * [!] This method should be extended in the child classes to include all properties of the entity
+     * [!] Includes aseid by default 
      * 
      * 
      * @returns 
@@ -311,6 +435,12 @@ export class A_Entity<
     }
 
 
+    /**
+     * Returns the string representation of the entity
+     * what is basically the ASEID string
+     * 
+     * @returns 
+     */
     toString(): string {
         return this.aseid ? this.aseid.toString() : this.constructor.name;
     }

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

@@ -9,6 +9,7 @@ import { A_Component } from "../A-Component/A-Component.class";
 import { A_Entity } from "../A-Entity/A-Entity.class";
 import {
     A_TYPES__A_InjectDecorator_EntityInjectionInstructions,
+    A_TYPES__A_InjectDecorator_EntityInjectionQuery,
     A_TYPES__A_InjectDecorator_Injectable
 } from "@adaas/a-concept/decorators/A-Inject/A-Inject.decorator.types";
 
@@ -176,20 +177,20 @@ export class A_Scope {
      * @param component 
      * @returns 
      */
-    has(
-        component: typeof A_Component
+    has<T extends A_Component>(
+        component: new (...args: any[]) => T
     ): boolean
-    has(
-        entity: typeof A_Entity
+    has<T extends A_Entity>(
+        entity: new (...args: any[]) => T
     ): boolean
-    has(
-        fragment: typeof A_Fragment
+    has<T extends A_Fragment>(
+        fragment: new (...args: any[]) => T
     ): boolean
     has(
         constructor: string
     ): boolean
-    has(
-        entity: typeof A_Fragment | typeof A_Component | typeof A_Entity | string
+    has<T extends A_Fragment | A_Component | A_Entity>(
+        entity: T | string | (new (...args: any[]) => T)
     ): boolean {
 
 
@@ -218,31 +219,35 @@ export class A_Scope {
                 return false;
             }
 
-            case A_CommonHelper.isInheritedFrom(entity, A_Component): {
-                const found = this.params.components.includes(entity as { new(...args: any[]): A_Component });
+            case typeof entity === 'function'
+                && A_CommonHelper.isInheritedFrom(entity, A_Component): {
+                    const found = this.params.components.includes(entity as { new(...args: any[]): A_Component });
 
-                if (!found && !!this._parent)
-                    return this._parent.has(entity as any);
+                    if (!found && !!this._parent) {
+                        return this._parent.has(entity as any);
+                    }
 
-                return found;
-            }
+                    return found;
+                }
 
-            case A_CommonHelper.isInheritedFrom(entity, A_Entity): {
-                const entities = Array.from(this._entities.values());
+            case typeof entity === 'function'
+                && A_CommonHelper.isInheritedFrom(entity, A_Entity): {
+                    const entities = Array.from(this._entities.values());
 
-                const found = entities.find(e => e instanceof entity);
+                    const found = entities.find(e => e instanceof entity);
 
-                return !!found;
-            }
+                    return !!found;
+                }
 
-            case A_CommonHelper.isInheritedFrom(entity, A_Fragment): {
-                const found = this._fragments.has(entity);
+            case typeof entity === 'function'
+                && A_CommonHelper.isInheritedFrom(entity, A_Fragment): {
+                    const found = this._fragments.has(entity);
 
-                if (!found && !!this._parent)
-                    return this._parent.has(entity as any);
+                    if (!found && !!this._parent)
+                        return this._parent.has(entity as any);
 
-                return found;
-            }
+                    return found;
+                }
 
             default: {
                 return false;
@@ -251,7 +256,6 @@ export class A_Scope {
     }
 
 
-
     /**
      * Merges two scopes into a new one
      * 
@@ -300,10 +304,10 @@ export class A_Scope {
     resolve<T extends A_TYPES__A_InjectDecorator_Injectable>(
         component: T
     ): InstanceType<T>
-    resolve<T extends { new(...args: any[]): A_Entity }>(
-        entity: T,
-        instructions: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
-    ): InstanceType<T>
+    resolve<T extends A_Entity>(
+        entity: { new(...args: any[]): T },
+        instructions: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions<T>>
+    ): T | Array<T>
     resolve<T extends A_TYPES__A_InjectDecorator_Injectable>(
         component: Array<T>
     ): Array<InstanceType<T>>
@@ -313,6 +317,7 @@ export class A_Scope {
         param2?: string | Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
     ): Array<InstanceType<T>> | InstanceType<T> {
 
+
         switch (true) {
             case Array.isArray(param1): {
                 return param1.map(c => this.resolveOnce(param1 as any, param2 as any));
@@ -372,7 +377,7 @@ export class A_Scope {
 
         switch (true) {
             case A_CommonHelper.isInheritedFrom(component, A_Entity): {
-                return this.resolveEntity(component as typeof A_Entity, instructions) as InstanceType<T>;
+                return this.resolveEntity(component as any, instructions) as InstanceType<T>;
             }
 
             case A_CommonHelper.isInheritedFrom(component, A_Fragment): {
@@ -395,18 +400,18 @@ export class A_Scope {
 
     private resolveEntity<T extends { new(...args: any[]): A_Entity }>(
         entity: T,
-        instructions?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
-    ): InstanceType<T> | undefined {
+        instructions?: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions<InstanceType<T>>>
+    ): InstanceType<T> | undefined | InstanceType<T>[] {
 
-        const query = instructions?.query || {};
+        const query = instructions?.query || {} as Partial<A_TYPES__A_InjectDecorator_EntityInjectionQuery<InstanceType<T>>>;
         const count = instructions?.pagination?.count || 1;
 
-
         switch (true) {
             case !instructions: {
 
                 const entities = Array.from(this._entities.values());
 
+
                 const found = entities.find(e => e instanceof entity);
 
                 switch (true) {
@@ -417,7 +422,7 @@ export class A_Scope {
                         return this._parent.resolveEntity(entity, instructions);
 
                     default:
-                        throw new Error(`Fragment ${entity.name} not found in the scope ${this.name}`);
+                        throw new Error(`Entity ${entity.name} not found in the scope ${this.name}`);
                 }
             }
 
@@ -428,6 +433,7 @@ export class A_Scope {
                 }
 
             case !!query.aseid
+                && typeof query.aseid === 'object'
                 && query.aseid instanceof ASEID
                 && this._entities.has(query.aseid.toString()): {
                     return this._entities.get(query.aseid.toString()) as InstanceType<T>;
@@ -441,16 +447,35 @@ export class A_Scope {
                 const found = entities.filter(
                     e => e instanceof entity
                 ).find(e => {
-
-
                     return String(e.id) === String(query.id)
                 });
 
                 return found as InstanceType<T>;
             }
 
-            default:
-                throw new Error(`Entity ${entity.constructor.name} not found in the scope ${this.name}`);
+            default: {
+                const entities = Array.from(this._entities.values());
+
+                const found = entities.filter(
+                    e => e instanceof entity
+                ).filter(e => {
+                    return Object.entries(query).every(([key, value]) => {
+                        if (key in e) {
+                            return (e as any)[key] === value;
+                        }
+                        return false;
+                    });
+                });
+
+                if (found.length === 0 && !!this._parent)
+                    return this._parent.resolveEntity(entity, instructions);
+
+                if (count === 1)
+                    return found[0] as InstanceType<T>;
+
+                return found as InstanceType<T>[];
+            }
+
         }
     }
 
@@ -460,6 +485,7 @@ export class A_Scope {
 
         const fragmentInstancePresented = this.fragments.some(fr => fr instanceof fragment);
 
+
         switch (true) {
 
             case fragmentInstancePresented && this._fragments.has(fragment):
@@ -545,17 +571,27 @@ export class A_Scope {
      * 
      * @param fragment 
      */
+    register<T extends A_Component>(component: new (...args: any[]) => T): void
     register(entity: A_Entity): void
     register(component: A_Component): void
     register(fragment: A_Fragment): void
     register(
-        param1: A_Fragment | A_Component | A_Entity
+        param1: A_Fragment | A_Component | A_Entity | (new (...args: any[]) => A_Component)
     ): void {
+        switch (true) {
+            case param1 instanceof A_Component && !this._components.has(param1.constructor): {
+                this._components.set(param1.constructor, param1);
 
+                const allowedComponent = this.components.find(c => c === param1.constructor);
 
-        console.log(`Registering in scope ${this.name}:`, param1);
+                if (!allowedComponent) {
+                    this.components.push(param1.constructor as any);
+                }
+
+                A_Context.register(this, param1);
+                break;
+            }
 
-        switch (true) {
             case param1 instanceof A_Entity && !this._entities.has(param1.aseid.toString()): {
                 this._entities.set(param1.aseid.toString(), param1);
                 A_Context.register(this, param1);
@@ -587,6 +623,13 @@ export class A_Scope {
                 break;
             }
 
+            case typeof param1 === 'function' && A_CommonHelper.isInheritedFrom(param1, A_Component): {
+                const allowedComponent = this.components.find(c => c === param1);
+
+                if (!allowedComponent)
+                    this.components.push(param1);
+                break;
+            }
             default:
                 if (param1 instanceof A_Entity)
                     throw new Error(`Entity with ASEID ${param1.aseid.toString()} is already registered in the scope ${this.name}`);

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

@@ -6,6 +6,7 @@ import { A_Container } from "../A-Container/A-Container.class";
 import { A_Scope } from "../A-Scope/A-Scope.class";
 import { A_StageError } from "./A-Stage.error";
 import { A_FeatureCaller } from "../A-Feature/A-FeatureCaller.class";
+import { A_Entity } from "../A-Entity/A-Entity.class";
 
 
 /**
@@ -30,10 +31,10 @@ export class A_Stage {
         this._steps = _steps;
         this.name = `${this.feature.name}::a-stage:[sync:${this
             .syncSteps
-            .map(s => s.component.name + '.' + s.handler)
+            .map(s => typeof s.component === 'string' ? s.component : s.component.name + '.' + s.handler)
             .join(' -> ')}][async:${this
                 .asyncSteps
-                .map(s => s.component.name + '.' + s.handler)
+                .map(s => typeof s.component === 'string' ? s.component : s.component.name + '.' + s.handler)
                 .join(' -> ')}]`;
 
     }
@@ -87,9 +88,11 @@ export class A_Stage {
         return Promise
             .all(A_Context
                 .meta(
-                    step.component instanceof A_Container
+                    // TODO: fix types
+                    (step.component instanceof A_Container
                         ? step.component.constructor
-                        : step.component
+                        : step.component) as any
+
                 )
                 .injections(step.handler)
                 .map(async arg => {
@@ -100,7 +103,7 @@ export class A_Stage {
                     if (A_CommonHelper.isInheritedFrom(arg.target, A_Feature))
                         return this.feature;
 
-                    return scope.resolve(arg.target)
+                    return scope.resolve((arg as any).target, (arg as any).instructions)
                 })
             )
     }
@@ -134,10 +137,11 @@ export class A_Stage {
         // TODO: probably would be better to do it another way. let's think about it
         const instance = component instanceof A_Container
             ? component
-            : this.feature.Scope.resolve(component);
+            // TODO: fix types
+            : this.feature.Scope.resolve(component as any);
 
         if (!instance)
-            throw new Error(`Unable to resolve component ${component.name}`);
+            throw new Error(`Unable to resolve component ${typeof component === 'string' ? component : component.name} from scope ${this.feature.Scope.name}`);
 
         if (!instance[handler])
             throw new Error(`Handler ${handler} not found in ${instance.constructor.name}`);