@adaas/a-concept 0.0.56 → 0.0.58

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

@@ -1,5 +1,6 @@
 import {
     A_CommonHelper,
+    A_Error,
     A_Polyfills,
 } from "@adaas/a-utils";
 import { A_Component } from "../A-Component/A-Component.class";
@@ -20,6 +21,7 @@ import { A_TYPES__ContainerMetaKey } from "../A-Container/A-Container.types";
 import { A_TYPES__ComponentMetaKey } from "../A-Component/A-Component.types";
 import { A_TYPES__ConceptStage } from "../A-Concept/A_Concept.types";
 import { A_TYPES__A_DefineDecorator_Meta } from "@adaas/a-concept/decorators/A-Feature/A-Feature.decorator.types";
+import { A_CONSTANTS__DEFAULT_ENV_VARIABLES } from "@adaas/a-concept/constants/env.constants";
 
 
 
@@ -79,7 +81,7 @@ export class A_Context {
 
     private constructor() {
         this._root = new A_Scope({
-            name: 'root'
+            name: process && process.env ? process.env[A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_NAMESPACE] || 'a-concept' : 'a-concept'
         });
     }
 
@@ -147,6 +149,10 @@ export class A_Context {
 
         const newScope = param2 instanceof A_Scope ? param2 : new A_Scope(param2, param2);
 
+        if (!newScope.isInheritedFrom(A_Context.root)) {
+            newScope.inherit(A_Context.root);
+        }
+
         switch (true) {
             case param1 instanceof A_Container:
                 instance.containers.set(param1, newScope);
@@ -169,6 +175,14 @@ export class A_Context {
 
 
 
+    /**
+     * Get or Create Meta for the specific class or instance.
+     * This method will return the existing meta if it exists, or create a new one if it doesn't.
+     * 
+     * Meta object contains custom metadata based on the class type.
+     * 
+     * @param container 
+     */
     static meta(
         container: typeof A_Container,
     ): A_ContainerMeta
@@ -181,6 +195,9 @@ export class A_Context {
     static meta(
         entity: typeof A_Entity,
     ): A_ContainerMeta
+    static meta(
+        component: string,
+    ): A_ComponentMeta
     static meta(
         component: typeof A_Component,
     ): A_ComponentMeta
@@ -193,6 +210,7 @@ export class A_Context {
             | A_Entity
             | typeof A_Entity
             | { new(...args: any[]): any }
+            | string
     ): A_Meta<T>
     static meta<T extends Record<string, any>>(
         param1: typeof A_Component | typeof A_Container | A_Container
@@ -200,9 +218,9 @@ export class A_Context {
             | A_Entity
             | typeof A_Entity
             | { new(...args: any[]): any }
+            | string
     ): A_ContainerMeta | A_ComponentMeta | A_Meta<T> {
 
-
         const instance = this.getInstance();
 
         let metaStorage: WeakMap<typeof A_Container.constructor, A_Meta<any>>;
@@ -211,6 +229,7 @@ export class A_Context {
 
 
         switch (true) {
+            // 1) If param1 is instance of A_Container
             case param1 instanceof A_Container: {
 
                 metaStorage = instance.containersMeta;
@@ -219,7 +238,7 @@ export class A_Context {
 
                 break;
             }
-
+            // 2) If param1 is class of A_Container
             case A_CommonHelper.isInheritedFrom(param1, A_Container): {
                 metaStorage = instance.containersMeta;
                 property = param1 as typeof A_Container;
@@ -227,7 +246,7 @@ export class A_Context {
 
                 break;
             }
-
+            // 3) If param1 is instance of A_Component
             case param1 instanceof A_Component: {
                 metaStorage = instance.componentsMeta;
                 property = param1.constructor;
@@ -235,7 +254,7 @@ export class A_Context {
 
                 break;
             }
-
+            // 4) If param1 is class of A_Component
             case A_CommonHelper.isInheritedFrom(param1, A_Component): {
                 metaStorage = instance.componentsMeta;
                 property = param1 as typeof A_Component;
@@ -243,7 +262,7 @@ export class A_Context {
 
                 break;
             }
-
+            // 5) If param1 is instance of A_Entity
             case param1 instanceof A_Entity: {
                 metaStorage = instance.entitiesMeta;
                 property = param1.constructor;
@@ -251,15 +270,25 @@ export class A_Context {
 
                 break;
             }
-
+            // 6) If param1 is class of A_Entity
             case A_CommonHelper.isInheritedFrom(param1, A_Entity): {
                 metaStorage = instance.entitiesMeta;
                 property = param1 as typeof A_Entity;
                 metaType = A_EntityMeta;
+
                 break;
             }
+            // 7) If param1 is string then we need to find the component by its name
+            case typeof param1 === 'string': {
+                metaStorage = instance.componentsMeta;
+                const found = Array.from(instance.componentsMeta).find(([c]) => c.name === param1)!;
+                if (!(found && found.length)) throw new A_Error(`Component with name ${param1} not found`);
+                property = found[0];
+                metaType = A_ComponentMeta;
 
-
+                break;
+            }
+            // 8) If param1 is any other class or function
             default: {
                 metaStorage = instance.customMeta;
                 property = typeof (param1 as any) === 'function' ? param1 : param1.constructor;
@@ -281,6 +310,15 @@ export class A_Context {
 
 
 
+    /**
+     * Get the scope of the specific class or instance.
+     * 
+     * Every execution in Concept has its own scope.
+     * 
+     * This method will return the scope of the specific class or instance.
+     * 
+     * @param entity 
+     */
     static scope(
         entity: A_Entity
     ): A_Scope
@@ -589,4 +627,25 @@ export class A_Context {
                 break;
         }
     }
+
+
+    /**
+     * Resets the Context to its initial state.
+     */
+    static reset() {
+        const instance = A_Context.getInstance();
+
+        instance.containers = new WeakMap();
+        instance.features = new WeakMap();
+        instance.registry = new WeakMap();
+        instance.containersMeta = new Map();
+        instance.componentsMeta = new Map();
+        instance.entitiesMeta = new Map();
+        instance.customMeta = new Map();
+
+        instance._root = new A_Scope({
+            name: process && process.env ? process.env[A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_NAMESPACE] || 'a-concept' : 'a-concept'
+        });
+
+    }
 }

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 A_Context.root.name;
+    }
+
+    /**
+     * 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;
     }