@adaas/a-concept 0.1.59 → 0.1.61

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.1.59",
-  "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.",
+  "version": "0.1.61",
+  "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",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -16,9 +16,9 @@
     "url": "git+https://github.com/ADAAS-org/adaas-a-concept.git"
   },
   "keywords": [
-    "sdk",
-    "ai",
-    "rag"
+    "adaas",
+    "ai framework",
+    "a-concept"
   ],
   "bugs": {
     "url": "https://github.com/ADAAS-org/adaas-a-concept/issues"

package/src/global/A-Component/A-Component.meta.ts

@@ -6,7 +6,7 @@ import { A_TYPES__ComponentMetaKey } from "./A-Component.constants";
 import { A_TYPES__FeatureDefineDecoratorMeta } from "../A-Feature/A-Feature.types";
 
 
-export class A_ComponentMeta extends A_Meta<A_TYPES__ComponentMeta> {
+export class A_ComponentMeta<T extends A_TYPES__ComponentMeta = A_TYPES__ComponentMeta> extends A_Meta<T> {
 
     /**
      * Allows to get all the injections for a given handler

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

@@ -37,6 +37,7 @@ import { A_Fragment } from "../A-Fragment/A-Fragment.class";
 import { A_TYPES__InjectableTargets } from "../A-Inject/A-Inject.types";
 import { A_TYPES__ConceptAbstractions } from "../A-Concept/A-Concept.constants";
 import { A_CommonHelper } from "@adaas/a-concept/helpers/A_Common.helper";
+import { A_TYPES__Fragment_Constructor } from "../A-Fragment/A-Fragment.types";
 
 
 
@@ -117,6 +118,9 @@ export class A_Context {
 
 
 
+
+    protected _globals = new Map<string, any>();
+
     /**
      * Private constructor to enforce singleton pattern.
      * 
@@ -346,54 +350,72 @@ export class A_Context {
       * 
       * @param container 
       */
-    static meta(
+    static meta<T extends A_ContainerMeta>(
         /**
          * Get meta for the specific container class by constructor.
          */
         container: A_TYPES__Container_Constructor,
-    ): A_ContainerMeta
-    static meta(
+    ): T
+    static meta<T extends A_ContainerMeta>(
         /**
          * Get meta for the specific container instance.
          */
         container: A_Container,
-    ): A_ContainerMeta
-    static meta(
+    ): T
+    static meta<T extends A_EntityMeta>(
         /**
          * Get meta for the specific entity class by constructor.
          */
         entity: A_TYPES__Entity_Constructor,
-    ): A_EntityMeta
-    static meta(
+    ): T
+    static meta<T extends A_EntityMeta>(
         /**
          * Get meta for the specific entity instance.
          */
         entity: A_Entity,
-    ): A_EntityMeta
-    static meta(
+    ): T
+    static meta<T extends A_ComponentMeta>(
         /**
          * Get meta for the specific component class by constructor.
          */
         component: A_TYPES__Component_Constructor,
-    ): A_ComponentMeta
-    static meta(
+    ): T
+    static meta<T extends A_ComponentMeta>(
         /**
          * Get meta for the specific component instance.
          */
         component: A_Component,
-    ): A_ComponentMeta
-    static meta(
+    ): T
+    static meta<T extends A_Meta>(
+        /**
+         * Get meta for the specific component class by constructor.
+         */
+        fragment: A_TYPES__Fragment_Constructor,
+    ): T
+    static meta<T extends A_Meta>(
+        /**
+         * Get meta for the specific component instance.
+         */
+        fragment: A_Fragment,
+    ): T
+    static meta<T extends A_ComponentMeta>(
         /**
          * Get meta for the specific component by its name.
          */
         component: string,
-    ): A_ComponentMeta
+    ): T
     static meta(
         /**
-         * Get meta for the specific injectable target (class or instance).
+         * Get meta for the specific meta linked component (class or instance).
          */
-        target: A_TYPES__InjectableTargets,
+        target: A_TYPES__MetaLinkedComponentConstructors | A_TYPES__MetaLinkedComponents,
     ): A_ComponentMeta
+    static meta<T extends A_Meta>(
+        /**
+         * Get meta for the specific class or instance
+         */
+        constructor: new (...args: any[]) => any
+    ): T
     static meta<T extends Record<string, any>>(
         /**
          * Get meta for the specific class or instance
@@ -469,7 +491,21 @@ export class A_Context {
 
                 break;
             }
-            // 7) If param1 is string then we need to find the component by its name
+            // 7) If param1 is instance of A_Fragment
+            case A_TypeGuards.isFragmentInstance(param1): {
+                property = param1.constructor as A_TYPES__Fragment_Constructor;
+                metaType = A_ComponentMeta;
+
+                break;
+            }
+            // 8) If param1 is class of A_Fragment
+            case A_TypeGuards.isFragmentConstructor(param1): {
+                property = param1;
+                metaType = A_EntityMeta;
+
+                break;
+            }
+            // 9) If param1 is string then we need to find the component by its name
             case typeof param1 === 'string': {
                 const found = Array.from(instance._metaStorage)
                     .find(([c]) => c.name === param1
@@ -484,7 +520,7 @@ export class A_Context {
 
                 break;
             }
-            // 8) If param1 is any other class or function
+            // 10) If param1 is any other class or function
             default: {
                 property = param1;
                 metaType = A_Meta;
@@ -504,6 +540,47 @@ export class A_Context {
     }
 
 
+
+    /**
+     * Allows to set meta for the specific class or instance.
+     * 
+     * @param param1 
+     * @param meta 
+     */
+    static setMeta<T extends A_ContainerMeta, S extends A_Container>(
+        param1: S,
+        meta: T
+    )
+    static setMeta<T extends A_EntityMeta, S extends A_Entity>(
+        param1: S,
+        meta: T
+    )
+    static setMeta<T extends A_ComponentMeta, S extends A_Component>(
+        param1: S,
+        meta: T
+    )
+    static setMeta<T extends A_Meta>(
+        param1: new (...args: any[]) => any,
+        meta: T
+    )
+    static setMeta<T extends A_Meta>(
+        param1: A_TYPES__MetaLinkedComponentConstructors | A_TYPES__MetaLinkedComponents,
+        meta: T
+    ) {
+        const instance = A_Context.getInstance();
+
+        const existingMeta = A_Context.meta(param1);
+
+        const constructor = typeof param1 === 'function'
+            ? param1
+            : param1.constructor as A_TYPES__MetaLinkedComponentConstructors;
+
+        instance._metaStorage.set(constructor, existingMeta ? meta.from(existingMeta) : meta);
+    }
+
+
+
+
     /**
      * 
      * This method allows to get the issuer of a specific scope.

package/src/global/A-Error/A_Error.class.ts

@@ -134,6 +134,12 @@ export class A_Error<
          */
         error: Error
     )
+    constructor(
+        /**
+         * Original JS Error
+         */
+        error: unknown
+    )
     constructor(
         /**
          * Error message
@@ -145,7 +151,7 @@ export class A_Error<
         description: string
     )
     constructor(
-        param1: _ConstructorType | Error | string | A_Error,
+        param1: _ConstructorType | Error | string | A_Error | any,
         param2?: string
     ) {
         //  to prevent errors accumulation in the stack trace it returns the original error if provided param1 is A_Error
@@ -178,10 +184,7 @@ export class A_Error<
                 break;
 
             default:
-                throw new A_Error(
-                    A_CONSTANTS__ERROR_CODES.VALIDATION_ERROR,
-                    'Invalid parameters provided to A_Error constructor'
-                );
+                super('An unknown error occurred.');
         }
 
         const initializer = this.getInitializer(param1, param2);

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

@@ -1,13 +1,28 @@
+import { A_MetaDecorator } from "./A-Meta.decorator";
+import { A_TYPES__Meta_Constructor } from "./A-Meta.types";
+
 /**
  * A Meta is an entity that stores all the metadata for the specific entity like container, component, feature, etc. 
  * 
  * [!] Meta can be different depending on the type of input data
  */
 export class A_Meta<
-    _StorageItems extends Record<string, any> = any,
+    _StorageItems extends Record<any, any> = any,
     _SerializedType extends Record<string, any> = Record<string, any>
 > implements Iterable<[keyof _StorageItems, _StorageItems[keyof _StorageItems]]> {
 
+    /**
+     * Allows to set a custom meta class for the Component or Container or Entity, or anything else. 
+     * 
+     * @param target 
+     * @returns 
+     */
+    static Define<T extends A_Meta>(target: A_TYPES__Meta_Constructor<T>) {
+        return A_MetaDecorator(target);
+    }
+
+
+
     protected meta: Map<keyof _StorageItems, _StorageItems[keyof _StorageItems]> = new Map();
 
 

package/src/global/A-Meta/A-Meta.decorator.ts

@@ -0,0 +1,26 @@
+import { A_Context } from "../A-Context/A-Context.class";
+import { A_Meta } from "./A-Meta.class";
+import { A_TYPES__MetaLinkedComponentConstructors } from "./A-Meta.types";
+
+
+
+
+/**
+ * 
+ * This decorator should allow to set a default meta type for the class, this helps to avoid
+ * the need to create custom meta classes for each class.
+ * 
+ * @returns 
+ */
+export function A_MetaDecorator<T extends A_Meta>(
+    constructor: new (...args: any[]) => T
+) {
+    return function <TTarget extends A_TYPES__MetaLinkedComponentConstructors>(
+        target: TTarget
+    ): TTarget {
+        // Store meta info on the target class itself for the Meta decorator to pick up
+        A_Context.setMeta(target, new constructor());
+
+        return target;
+    };
+}

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

@@ -4,18 +4,31 @@ import { A_Container } from "../A-Container/A-Container.class";
 import { A_TYPES__Container_Constructor } from "../A-Container/A-Container.types";
 import { A_Entity } from "../A-Entity/A-Entity.class";
 import { A_TYPES__Entity_Constructor } from "../A-Entity/A-Entity.types";
+import { A_Fragment } from "../A-Fragment/A-Fragment.class";
+import { A_TYPES__Fragment_Constructor } from "../A-Fragment/A-Fragment.types";
+import { A_Meta } from "./A-Meta.class";
 
 
+// ============================================================================
+// --------------------------- Primary Types ----------------------------------
+// ============================================================================
+/**
+ * Meta constructor type
+ */
+export type A_TYPES__Meta_Constructor<T = A_Meta> = new (...args: any[]) => T;
 /**
  * Components that can have Meta associated with them
  */
 export type A_TYPES__MetaLinkedComponents = A_Container
     | A_Component
     | A_Entity
+    | A_Fragment
 /**
  * Constructors of components that can have Meta associated with them
  */
-export type A_TYPES__MetaLinkedComponentConstructors = A_TYPES__Container_Constructor
+export type A_TYPES__MetaLinkedComponentConstructors = new (...args: any[]) => any
+    | A_TYPES__Container_Constructor
     | A_TYPES__Component_Constructor
     | A_TYPES__Entity_Constructor
+    | A_TYPES__Fragment_Constructor
 

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

@@ -1045,7 +1045,16 @@ export class A_Scope<
          */
         entity: A_TYPES__Entity_Constructor<T>
     ): T | undefined
-
+    resolveFlat<T extends A_Entity>(
+        /**
+         * Provide an entity constructor to resolve its instance or an array of instances from the scope
+         */
+        entity: A_TYPES__Entity_Constructor<T>,
+        /**
+         * Only Aseid Provided, in this case one entity will be returned
+         */
+        instructions: { query: { aseid: string | ASEID } }
+    ): T | undefined
     resolveFlat<T extends A_Entity>(
         /**
          * Provide an entity constructor to resolve its instance or an array of instances from the scope

package/src/global/ASEID/ASEID.class.ts

@@ -148,6 +148,14 @@ export class ASEID {
         return this._shard;
     }
 
+    /**
+     * Get the hash of the ASEID, Unique identifier based on the ASEID string
+     * Useful when aseid details should not be exposed directly
+     */
+    get hash(): string {
+        return A_IdentityHelper.hashString(this.toString());
+    }
+
     /**
      * get Internal Initializer based on the type of the parameter provided
      * 

package/src/helpers/A_Identity.helper.ts

@@ -49,5 +49,23 @@ export class A_IdentityHelper {
         return String(Number(formattedNumber)); // Convert to number and back to string to remove leading zeros
     }
 
+    /**
+     * Generates a simple hash string from the input string.
+     * 
+     * 
+     * @param input 
+     * @returns
+     */
+    static hashString(input: string): string {
+        let hash = 0, i, chr;
+        if (input.length === 0) return hash.toString();
+        for (i = 0; i < input.length; i++) {
+            chr = input.charCodeAt(i);
+            hash = ((hash << 5) - hash) + chr;
+            hash |= 0; // Convert to 32bit integer
+        }
+        return hash.toString();
+    }
+
 
 }

package/src/index.ts

@@ -65,6 +65,7 @@ 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 { A_MetaDecorator } from './global/A-Meta/A-Meta.decorator';
 export * from './global/A-Meta/A-Meta.types';
 
 export { A_Fragment } from './global/A-Fragment/A-Fragment.class';

package/tests/A-Meta.test.ts

@@ -5,6 +5,8 @@ import { A_Concept } from "@adaas/a-concept/global/A-Concept/A-Concept.class";
 import { A_Context } from "@adaas/a-concept/global/A-Context/A-Context.class";
 import { A_Feature } from "@adaas/a-concept/global/A-Feature/A-Feature.class";
 import { A_Meta } from "@adaas/a-concept/global/A-Meta/A-Meta.class";
+import { A_Inject } from "@adaas/a-concept/global/A-Inject/A-Inject.decorator";
+import { A_TYPES__ComponentMeta } from "@adaas/a-concept/global/A-Component/A-Component.types";
 
 jest.retryTimes(0);
 
@@ -128,4 +130,45 @@ describe('A-Meta tests', () => {
         expect(metaE.get(A_TYPES__ComponentMetaKey.EXTENSIONS)?.get('.*\\.testFeature$')?.map(e => e.handler)).toContain('test3');
         expect(metaE.get(A_TYPES__ComponentMetaKey.EXTENSIONS)?.get('.*\\.testFeature$')?.map(e => e.handler)).not.toContain('test2');
     })
+    it('Should allow to inherit meta properly', async () => {
+
+        class InjectableComponent extends A_Component { }
+
+        class CustomComponentMeta extends A_ComponentMeta<{ customField: string } & A_TYPES__ComponentMeta> {
+
+            get customField(): string | undefined {
+                return this.get('customField');
+            }
+        }
+
+        @A_Meta.Define(CustomComponentMeta)
+        class CustomComponent extends A_Component {
+
+            static Test(){
+
+            }
+
+            constructor(
+                @A_Inject(InjectableComponent) public injectableComponent: InjectableComponent
+            ) {
+                super();
+            }
+
+            @A_Feature.Extend({
+                name: 'testFeature'
+            })
+            async feature() {
+
+            }
+        }
+
+
+        const meta = A_Context.meta<CustomComponentMeta>(CustomComponent);
+
+        expect(meta).toBeInstanceOf(CustomComponentMeta);
+        expect(meta).toHaveProperty('customField');
+
+        expect(meta.get(A_TYPES__ComponentMetaKey.EXTENSIONS)?.size()).toBe(1);
+        expect(meta.get(A_TYPES__ComponentMetaKey.EXTENSIONS)?.has('.*\\.testFeature$')).toBe(true);
+    })
 })  

package/tests/ASEID.test.ts

@@ -22,6 +22,41 @@ describe('ASEID Tests', () => {
         expect(aseid.version).toBe('v1');
         expect(aseid.shard).toBe('shard1');
         expect(aseid.toString()).toBe('my-concept@my-scope:my-entity:shard1.123@v1');
+    });
+      it('Should allow to create a new ASEID and use hash for identity', async () => {
+        const aseid1 = new ASEID({
+            concept: 'my-concept',
+            scope: 'my-scope',
+            entity: 'my-entity',
+            id: '123',
+            version: 'v1',
+            shard: 'shard1'
+        });
+
+        const aseid2 = new ASEID({
+            concept: 'my-concept',
+            scope: 'my-scope',
+            entity: 'my-entity',
+            id: '123',
+            version: 'v1',
+            shard: 'shard1'
+        });
+
+        const aseid3 = new ASEID({
+            concept: 'my-concept',
+            scope: 'my-scope',
+            entity: 'my-entity',
+            id: '124',
+            version: 'v1',
+            shard: 'shard1'
+        });
+
+        expect(aseid1.hash).toBeDefined();
+        expect(aseid2.hash).toBeDefined();
+        expect(aseid3.hash).toBeDefined();
+
+        expect(aseid1.hash).not.toBe(aseid3.hash);
+        expect(aseid1.hash).toBe(aseid2.hash);  
     });
     it('Should allow to create a new ASEID object with required parameters only', async () => {
         const aseid = new ASEID({