@adaas/a-concept 0.0.56 → 0.0.57

package/src/base/A-Command/A_Command.entity.ts

@@ -0,0 +1,287 @@
+import { A_Entity } from "@adaas/a-concept/global/A-Entity/A-Entity.class";
+import { A_TYPES__Command_Constructor, A_TYPES__Command_Listener, A_TYPES__Command_Serialized } from "./A_Command.types";
+import { A_Error } from "@adaas/a-utils";
+import { A_Scope } from "@adaas/a-concept/global/A-Scope/A-Scope.class";
+import { A_Feature } from "@adaas/a-concept/global/A-Feature/A-Feature.class";
+import { A_CommandContext } from "./context/A_Command.context";
+import { A_CONSTANTS__A_Command_Event, A_CONSTANTS__A_Command_Status, A_CONSTANTS_A_Command_Features } from "./A_Command.constants";
+
+
+export class A_Command<
+    InvokeType extends A_TYPES__Command_Constructor = A_TYPES__Command_Constructor,
+    ResultType extends Record<string, any> = Record<string, any>
+> extends A_Entity<
+    InvokeType,
+    A_TYPES__Command_Serialized<ResultType>
+> {
+
+    protected _scope!: A_Scope;
+    protected _result?: ResultType;
+    protected _errors?: Set<A_Error>;
+
+    protected _params!: InvokeType;
+    protected _status!: A_CONSTANTS__A_Command_Status
+
+    protected _listeners: Map<A_CONSTANTS__A_Command_Event, Set<A_TYPES__Command_Listener<ResultType>>> = new Map();
+
+    protected _startTime?: Date;
+    protected _endTime?: Date
+
+    /**
+     * Execution Duration in milliseconds
+     */
+    get Duration() {
+        return this._endTime && this._startTime
+            ? this._endTime.getTime() - this._startTime.getTime()
+            : this._startTime
+                ? new Date().getTime() - this._startTime.getTime()
+                : undefined;
+    }
+
+
+    /**
+     * Command Execution A-Scope that inherits from scope where command was created
+     * 
+     * Command execution context is stored in A_CommandContext fragment within this scope
+     */
+    get Scope(): A_Scope {
+        return this._scope;
+    }
+
+    /**
+     * Unique code identifying the command type
+     * Example: 'user.create', 'task.complete', etc.
+     * 
+     */
+    get Code(): string {
+        return (this.constructor as typeof A_Command).name;
+    }
+    /**
+     * Current status of the command
+     */
+    get Status(): A_CONSTANTS__A_Command_Status {
+        return this._status;
+    }
+    /**
+     * Start time of the command execution
+     */
+    get StartedAt(): Date | undefined {
+        return this._startTime;
+    }
+    /**
+     * End time of the command execution
+     */
+    get EndedAt(): Date | undefined {
+        return this._endTime;
+    }
+    /**
+     * Result of the command execution stored in the context
+     */
+    get Result(): ResultType | undefined {
+        return this._result;
+    }
+    /**
+     * Errors encountered during the command execution stored in the context
+     */
+    get Errors(): Set<A_Error> | undefined {
+        return this._errors;
+    }
+    /**
+     * Parameters used to invoke the command
+     */
+    get Params(): InvokeType {
+        return this._params;
+    }
+
+
+    /**
+     * 
+     * A-Command represents an executable command with a specific code and parameters.
+     * It can be executed within a given scope and stores execution results and errors.
+     * 
+     * 
+     * A-Command should be context independent and execution logic should be based on attached components 
+     * 
+     * @param code 
+     * @param params 
+     */
+    constructor(
+        /**
+         * Command invocation parameters
+         */
+        params: InvokeType | A_TYPES__Command_Serialized<ResultType>
+    ) {
+        super(params as any);
+    }
+
+
+    // --------------------------------------------------------------------------
+    // A-Command Core Features
+    // --------------------------------------------------------------------------
+
+
+    /**
+     * Executes the command logic.
+     */
+    @A_Feature.Define()
+    async [A_CONSTANTS_A_Command_Features.EXECUTE](): Promise<any> {
+        this._status = A_CONSTANTS__A_Command_Status.IN_PROGRESS;
+        this._startTime = new Date();
+        try {
+            await this.call('execute', this._scope);
+            await this.complete();
+        } catch (error) {
+            await this.fail();
+        }
+    }
+
+    /**
+     * Marks the command as completed
+     */
+    @A_Feature.Define()
+    async [A_CONSTANTS_A_Command_Features.COMPLETE]() {
+        this._status = A_CONSTANTS__A_Command_Status.COMPLETED;
+        this._endTime = new Date();
+        this._result = this.Scope.resolve(A_CommandContext).toJSON() as ResultType;
+
+        this.call('complete', this._scope);
+    }
+
+
+    /**
+     * Marks the command as failed
+     */
+    @A_Feature.Define()
+    async [A_CONSTANTS_A_Command_Features.FAIL]() {
+        this._status = A_CONSTANTS__A_Command_Status.FAILED;
+        this._endTime = new Date();
+        this._errors = this.Scope.resolve(A_CommandContext).Errors;
+
+        this.call('fail', this._scope);
+    }
+
+
+    // --------------------------------------------------------------------------   
+    // A-Command Event-Emitter methods
+    // --------------------------------------------------------------------------
+
+    /**
+     * Registers an event listener for a specific event
+     * 
+     * @param event 
+     * @param listener 
+     */
+    on(event: A_CONSTANTS__A_Command_Event, listener: A_TYPES__Command_Listener<ResultType>) {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set());
+        }
+        this._listeners.get(event)!.add(listener);
+    }
+    /**
+     * Removes an event listener for a specific event
+     * 
+     * @param event 
+     * @param listener 
+     */
+    off(event: A_CONSTANTS__A_Command_Event, listener: A_TYPES__Command_Listener<ResultType>) {
+        this._listeners.get(event)?.delete(listener);
+    }
+    /**
+     * Emits an event to all registered listeners
+     * 
+     * @param event 
+     */
+    emit(event: A_CONSTANTS__A_Command_Event) {
+        this._listeners.get(event)?.forEach(listener => {
+            listener(this);
+        });
+    }
+
+
+    // --------------------------------------------------------------------------
+    // A-Entity Base Class Overrides
+    // --------------------------------------------------------------------------
+    // Serialization / Deserialization
+    // -------------------------------------------------------------------------
+
+
+    /**
+     * Allows to create a Command instance from new data
+     * 
+     * @param newEntity 
+     */
+    fromNew(newEntity: InvokeType): void {
+        super.fromNew(newEntity);
+
+
+        this._params = newEntity;
+
+        this._status = A_CONSTANTS__A_Command_Status.INITIALIZED;
+
+        this._scope = new A_Scope({
+            name: `a-command-scope::${this.id}`,
+            fragments: [
+                new A_CommandContext<ResultType>()
+            ]
+        });
+    }
+
+
+
+    /**
+     * Allows to convert serialized data to Command instance
+     * 
+     * [!] By default it omits params as they are not stored in the serialized data
+     * 
+     * @param serialized 
+     */
+    fromJSON(serialized: A_TYPES__Command_Serialized<ResultType>): void {
+        super.fromJSON(serialized);
+        if (serialized.startedAt) this._startTime = new Date(serialized.startedAt);
+        if (serialized.endedAt) this._endTime = new Date(serialized.endedAt);
+
+
+        const context = new A_CommandContext<ResultType>();
+
+        this._scope = new A_Scope({
+            name: `a-command-scope::${this.id}`,
+            fragments: [
+                context
+            ]
+        })
+        // Restore result and errors in the context
+        if (serialized.result) {
+            Object.entries(serialized.result).forEach(([key, value]) => {
+                context.save(key, value);
+            });
+        }
+
+        if (serialized.errors) {
+            serialized.errors.forEach(err => {
+                context.error(new A_Error(err));
+            });
+        }
+
+        this._status = serialized.status || A_CONSTANTS__A_Command_Status.INITIALIZED;
+    }
+
+
+    /**
+     * Converts the Command instance to a plain object
+     * 
+     * @returns 
+     */
+    toJSON(): A_TYPES__Command_Serialized<ResultType> {
+        return {
+            ...super.toJSON(),
+            code: this.Code,
+            status: this._status,
+            startedAt: this._startTime ? this._startTime.toISOString() : undefined,
+            endedAt: this._endTime ? this._endTime.toISOString() : undefined,
+            duration: this.Duration,
+            result: this.Result,
+            errors: this.Errors ? Array.from(this.Errors).map(err => err.toJSON()) : undefined
+        }
+    };
+
+}

package/src/base/A-Command/A_Command.types.ts

@@ -0,0 +1,34 @@
+import { A_TYPES__Entity_JSON } from "@adaas/a-concept/global/A-Entity/A-Entity.types";
+import { A_CommandContext } from "./context/A_Command.context";
+import { A_Command } from "./A_Command.entity";
+import { A_CONSTANTS__A_Command_Status } from "./A_Command.constants";
+import { A_Error, A_TYPES__Error } from "@adaas/a-utils";
+
+
+
+export type A_TYPES__Command_Constructor = {
+}
+
+
+
+export type A_TYPES__Command_Serialized<
+    ResultType extends Record<string, any> = Record<string, any>
+> = {
+    code: string;
+    status: A_CONSTANTS__A_Command_Status;
+
+    startedAt?: string;
+    endedAt?: string;
+    duration?: number;
+
+    result?: ResultType;
+    errors?: Array<A_TYPES__Error>;
+
+} & A_TYPES__Entity_JSON
+
+
+
+
+export type A_TYPES__Command_Listener<
+    T extends Record<string, any> = Record<string, any>
+> = (command?: A_Command<any, T>) => void;

package/src/base/A-Command/context/A_Command.context.ts

@@ -0,0 +1,114 @@
+import { A_Fragment } from "@adaas/a-concept/global/A-Fragment/A-Fragment.class";
+import { A_Error } from "@adaas/a-utils";
+
+
+export class A_CommandContext<
+    T extends Record<string, any> = Record<string, any>
+> extends A_Fragment {
+
+
+    /**
+     * Internal storage of all intermediate values
+     */
+    protected _memory: Map<keyof T, T[keyof T]>;
+    /**
+     * Errors encountered during the execution
+     */
+    protected _errors: Set<A_Error>;
+
+
+
+    /**
+     * ExecutionContext for the A-Command
+     * 
+     */
+    constructor(initialValues: T = {} as T) {
+        super();
+        this._memory = new Map(Object.entries(initialValues));
+        this._errors = new Set();
+    }
+
+
+    get Errors(): Set<A_Error> | undefined {
+        return this._errors.size > 0 ? this._errors : undefined;
+    }
+
+
+    /**
+     * Verifies that all required keys are present in the proxy values
+     * 
+     * @param requiredKeys 
+     * @returns 
+     */
+    verifyPrerequisites(
+        requiredKeys: Array<keyof T>
+    ): boolean {
+        return requiredKeys.every(key => this._memory.has(key));
+    }
+
+    /**
+     * Adds an error to the context
+     * 
+     * @param error 
+     */
+    error(error: A_Error): void {
+        this._errors.add(error);
+    }
+
+    /**
+     * Saves a value in the context memory
+     * 
+     * @param key 
+     * @param value 
+     */
+    save<K extends keyof T>(
+        /**
+         * Key to save the value under
+         */
+        key: K,
+        /**
+         * Value to save
+         */
+        value: T[K]
+    ): void {
+        this._memory.set(key, value);
+    }
+
+
+    /**
+     * Removes a value from the context memory by key
+     * 
+     * @param key 
+     */
+    drop(key: keyof T): void {
+        this._memory.delete(key);
+    }
+
+    /**
+     * Clears all stored values in the context memory
+     */
+    clear(): void {
+        this._memory.clear();
+    }
+
+
+    /**
+     * Converts all stored values to a plain object
+     * 
+     * [!] By default uses all saved in memory values 
+     * 
+     * @returns 
+     */
+    toJSON(): Record<string, any> {
+        const obj: Record<string, any> = {};
+
+        this._memory.forEach((value, key) => {
+            obj[key as string] =
+                typeof value === 'object' && value !== null && 'toJSON' in value && typeof value.toJSON === 'function'
+                    ? value.toJSON()
+                    : value;
+        })
+
+        return obj;
+    }
+}

package/src/base/A-Config/A-Config.context.ts

@@ -1,10 +1,11 @@
 import { A_CommonHelper, A_TYPES__Required } from "@adaas/a-utils";
 import { A_TYPES__ConfigContainerConstructor } from "./A-Config.types";
 import { A_Fragment } from "@adaas/a-concept/global/A-Fragment/A-Fragment.class";
+import { A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_TYPES__ConceptENVVariables } from "@adaas/a-concept/constants/env.constants";
 
 
 export class A_Config<
-    T extends string = any
+    T extends string = A_TYPES__ConceptENVVariables
 > extends A_Fragment {
 
     config: A_TYPES__ConfigContainerConstructor<T>;
@@ -14,12 +15,7 @@ export class A_Config<
 
     CONFIG_PROPERTIES: T[] = [];
 
-    protected DEFAULT_ALLOWED_TO_READ_PROPERTIES = [
-        'CONFIG_SDK_VALIDATION',
-        'CONFIG_VERBOSE',
-        'CONFIG_IGNORE_ERRORS',
-        'CONCEPT_ROOT_FOLDER',
-    ] as const;
+    protected DEFAULT_ALLOWED_TO_READ_PROPERTIES = A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY;
 
 
     constructor(
@@ -72,24 +68,24 @@ export class A_Config<
      * 
      * @param variables 
      */
-    set<V extends string = T | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]>(
+    set(
         variables: Array<{
-            property: V,
+            property: T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number],
             value: any
         }>
     )
-    set<V extends string = T | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]>(
-        variables: Record<V, any>
+    set(
+        variables: Partial<Record<T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number], any>>
     )
-    set<V extends string = T | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]>(
-        property: V,
+    set(
+        property: T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number],
         value: any
     )
-    set<V extends string = T | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]>(
-        property: V | Array<{
-            property: V,
+    set(
+        property: T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number] | Array<{
+            property: T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number],
             value: any
-        }> | Record<V, any>,
+        }> | Partial<Record<T | typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number], any>>,
         value?: any
     ) {
         const array = Array.isArray(property)

package/src/base/A-Config/components/ConfigReader.component.ts

@@ -22,13 +22,13 @@ export class ConfigReader extends A_Component {
         @A_Inject(A_Config) config: A_Config,
     ) {
 
-        const data = this.read(config.CONFIG_PROPERTIES);
+        const data = await this.read(config.CONFIG_PROPERTIES);
 
         config.set(data);
 
         const rootDir = await this.getProjectRoot();
 
-        config.set('CONCEPT_ROOT_FOLDER', rootDir);
+        config.set('A_CONCEPT_ROOT_FOLDER', rootDir);
     }
 
 
@@ -59,19 +59,6 @@ export class ConfigReader extends A_Component {
      * @returns {string|null} - The path to the root directory or null if package.json is not found
      */
     protected async getProjectRoot(startPath = __dirname) {
-        // let currentPath = startPath;
-
-        // const fs = await A_Polyfills.fs();
-
-        // while (!fs.existsSync(`${currentPath}/package.json`)) {
-        //     const parentPath = currentPath.substring(0, currentPath.lastIndexOf('/'));
-        //     if (parentPath === currentPath || parentPath === '') {
-        //         // Reached the root of the filesystem without finding package.json
-        //         return null;
-        //     }
-        //     currentPath = parentPath;
-        // }
-
         return process.cwd();
     }
 }

package/src/constants/env.constants.ts

@@ -0,0 +1,47 @@
+export const A_CONSTANTS__DEFAULT_ENV_VARIABLES = {
+    // ----------------------------------------------------------
+    // A-Concept Core Environment Variables
+    // ----------------------------------------------------------
+    // These environment variables are used by A-Concept core to configure the application
+    // ----------------------------------------------------------
+    /**
+     * Namespace of the application
+     * [!] Provided name will be used for all aseids in the application by default
+     */
+    A_CONCEPT_NAMESPACE: 'A_CONCEPT_NAMESPACE',
+    /**
+     * Default scope of the application
+     * [!] Provided name will be used for all aseids in the application by default
+     */
+    A_CONCEPT_DEFAULT_SCOPE: 'A_CONCEPT_DEFAULT_SCOPE',
+    /**
+     * Environment of the application e.g. development, production, staging
+     */
+    A_CONCEPT_ENVIRONMENT: 'A_CONCEPT_ENVIRONMENT',
+    /**
+     * Root folder of the application
+     * [!] Automatically set by A-Concept when the application starts
+     */
+    A_CONCEPT_ROOT_FOLDER: 'A_CONCEPT_ROOT_FOLDER',
+
+    CONFIG_SDK_VALIDATION: 'CONFIG_SDK_VALIDATION',
+    CONFIG_VERBOSE: 'CONFIG_VERBOSE',
+    CONFIG_IGNORE_ERRORS: 'CONFIG_IGNORE_ERRORS',
+} as const
+
+
+export type A_TYPES__ConceptENVVariables = (typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES)[keyof typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES];
+
+
+
+export const A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY = [
+    A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_NAMESPACE,
+    A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_ENVIRONMENT,
+    A_CONSTANTS__DEFAULT_ENV_VARIABLES.A_CONCEPT_ROOT_FOLDER,
+    A_CONSTANTS__DEFAULT_ENV_VARIABLES.CONFIG_VERBOSE,
+    A_CONSTANTS__DEFAULT_ENV_VARIABLES.CONFIG_IGNORE_ERRORS,
+] as const;
+
+
+
+

package/src/decorators/A-Inject/A-Inject.decorator.ts

@@ -46,9 +46,9 @@ export function A_Inject(
     fragment: { new(...args: any[]): A_Fragment }
 ): A_TYPES__A_InjectDecoratorReturn
 
-export function A_Inject(
-    entity: { new(...args: any[]): A_Entity },
-    config: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions>
+export function A_Inject<T extends A_Entity>(
+    entity: { new(...args: any[]): T },
+    config: Partial<A_TYPES__A_InjectDecorator_EntityInjectionInstructions<T>>
 ): A_TYPES__A_InjectDecoratorReturn
 
 // ====================== BASE FUNCTION ======================

package/src/decorators/A-Inject/A-Inject.decorator.types.ts

@@ -2,6 +2,7 @@ import { A_Component } from "@adaas/a-concept/global/A-Component/A-Component.cla
 import { A_Container } from "@adaas/a-concept/global/A-Container/A-Container.class";
 import { A_Entity } from "@adaas/a-concept/global/A-Entity/A-Entity.class";
 import { A_Feature } from "@adaas/a-concept/global/A-Feature/A-Feature.class";
+import { A_FeatureCaller } from "@adaas/a-concept/global/A-Feature/A-FeatureCaller.class";
 import { A_Fragment } from "@adaas/a-concept/global/A-Fragment/A-Fragment.class";
 import { A_Scope } from "@adaas/a-concept/global/A-Scope/A-Scope.class";
 import { ASEID } from "@adaas/a-utils";
@@ -60,21 +61,21 @@ export type A_TYPES__A_InjectDecorator_Injectable =
     | { new(...args: any[]): A_Container }
     | { new(...args: any[]): A_Scope }
     | { new(...args: any[]): A_Feature }
-    | { new(...args: any[]): A_Entity };
+    | { new(...args: any[]): A_Entity }
+    | { new(...args: any[]): A_FeatureCaller };
 
 
-export type A_TYPES__A_InjectDecorator_EntityInjectionInstructions = {
-    query: Partial<A_TYPES__A_InjectDecorator_EntityInjectionQuery>,
+export type A_TYPES__A_InjectDecorator_EntityInjectionInstructions<T extends A_Entity = A_Entity> = {
+    query: Partial<A_TYPES__A_InjectDecorator_EntityInjectionQuery<T>>,
     pagination: Partial<A_TYPES__A_InjectDecorator_EntityInjectionPagination>
 }
 
 
-export type A_TYPES__A_InjectDecorator_EntityInjectionQuery = {
-    aseid: string | ASEID,
-    id: string,
-    type: { new(...args: any[]): A_Entity },
-    entity: string
-}
+export type A_TYPES__A_InjectDecorator_EntityInjectionQuery<T extends A_Entity = A_Entity> = {
+    aseid: string,
+} & {
+    [key in keyof T]?: any
+};
 
 
 export type A_TYPES__A_InjectDecorator_EntityInjectionPagination = {

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

@@ -4,6 +4,8 @@ import { A_TYPES__A_ChannelAggregated, A_TYPES__A_ChannelAggregateMethods, A_TYP
 
 
 /**
+ * [!] DEPRECATED - use simply A_Component instead
+ * 
  * A_Channel is an abstraction over any Communication Type from event emitters to message queues, HTTP requests, etc.
  * 
  * A_Channel uses to connect Containers between each other. When