@adaas/a-utils 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-utils",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "A-Utils is a set of utilities that are used across the ADAAS ecosystem. This package is designed to be a collection of utilities that are used across the ADAAS ecosystem.",
   "license": "Apache-2.0",
   "main": "./dist/index.cjs",
@@ -80,7 +80,7 @@
     "build": "tsup --config tsup.config.ts"
   },
   "dependencies": {
-    "@adaas/a-concept": "^0.1.44"
+    "@adaas/a-concept": "^0.1.46"
   },
   "devDependencies": {
     "@types/chai": "^4.3.14",

package/src/index.ts

@@ -59,6 +59,12 @@ export { A_MemoryError } from './lib/A-Memory/A-Memory.error';
 export * from './lib/A-Memory/A-Memory.constants';
 export * from './lib/A-Memory/A-Memory.types';
 
+// ============================================================================
+// A-Execution Components
+// ============================================================================
+export { A_ExecutionContext } from './lib/A-Execution/A-Execution.context';
+// export * from './lib/A-Execution/A-Execution.types';
+
 // ============================================================================
 // A-Operation Components
 // ============================================================================

package/src/lib/A-Channel/A-Channel.constants.ts

@@ -7,53 +7,53 @@ export enum A_ChannelFeatures {
     /**
      * Allows to extend timeout logic and behavior
      */
-    onTimeout = 'onTimeout',
+    onTimeout = '_A_Channel_onTimeout',
     /**
      * Allows to extend retry logic and behavior
      */
-    onRetry = 'onRetry',
+    onRetry = '_A_Channel_onRetry',
     /**
      * Allows to extend circuit breaker logic and behavior
      */
-    onCircuitBreakerOpen = 'onCircuitBreakerOpen',
+    onCircuitBreakerOpen = '_A_Channel_onCircuitBreakerOpen',
     /**
      * Allows to extend cache logic and behavior
      */
-    onCache = 'onCache',
+    onCache = '_A_Channel_onCache',
     /**
      * Allows to extend connection logic and behavior
      */
-    onConnect = 'onConnect',
+    onConnect = '_A_Channel_onConnect',
     /**
      * Allows to extend disconnection logic and behavior
      */
-    onDisconnect = 'onDisconnect',
+    onDisconnect = '_A_Channel_onDisconnect',
     /**
      * Allows to extend request preparation logic and behavior
      */
-    onBeforeRequest = 'onBeforeRequest',
+    onBeforeRequest = '_A_Channel_onBeforeRequest',
     /**
      * Allows to extend request sending logic and behavior
      */
-    onRequest = 'onRequest',
+    onRequest = '_A_Channel_onRequest',
     /**
      * Allows to extend request post-processing logic and behavior
      */
-    onAfterRequest = 'onAfterRequest',
+    onAfterRequest = '_A_Channel_onAfterRequest',
     /**
      * Allows to extend error handling logic and behavior
      * 
      * [!] The same approach uses for ALL errors within the channel
      */
-    onError = 'onError',
+    onError = '_A_Channel_onError',
     /**
      * Allows to extend send logic and behavior
      */
-    onSend = 'onSend',
+    onSend = '_A_Channel_onSend',
     /**
      * Allows to extend consume logic and behavior
      */
-    onConsume = 'onConsume',
+    onConsume = '_A_Channel_onConsume',
 }
 
 

package/src/lib/A-Command/A-Command.constants.ts

@@ -10,27 +10,27 @@ export enum A_Command_Status {
      * Initial state when command is instantiated but not yet ready for execution
      */
     CREATED = 'CREATED',
-    
+
     /**
      * Command has been initialized with execution scope and dependencies
      */
     INITIALIZED = 'INITIALIZED',
-    
+
     /**
      * Command has been compiled and is ready for execution
      */
     COMPILED = 'COMPILED',
-    
+
     /**
      * Command is currently being executed
      */
     EXECUTING = 'EXECUTING',
-    
+
     /**
      * Command has completed successfully
      */
     COMPLETED = 'COMPLETED',
-    
+
     /**
      * Command execution has failed with errors
      */
@@ -47,13 +47,13 @@ export enum A_Command_Status {
 export enum A_CommandTransitions {
     /** Transition from CREATED to INITIALIZED state */
     CREATED_TO_INITIALIZED = 'created_initialized',
-    
+
     /** Transition from INITIALIZED to EXECUTING state */
     INITIALIZED_TO_EXECUTING = 'initialized_executing',
-    
+
     /** Transition from EXECUTING to COMPLETED state (success path) */
     EXECUTING_TO_COMPLETED = 'executing_completed',
-    
+
     /** Transition from EXECUTING to FAILED state (error path) */
     EXECUTING_TO_FAILED = 'executing_failed',
 }
@@ -68,42 +68,87 @@ export enum A_CommandTransitions {
  * to inject custom logic into command execution.
  */
 export enum A_CommandFeatures {
+    /**
+     * Triggered during command initialization phase
+     * Use to set up execution environment, validate parameters, or prepare resources
+     */
+    onInit = '_A_Command_onInit',
+
+    /**
+     * Triggered before command execution starts
+     * Use for pre-execution validation, logging, or setup tasks
+     */
+    onBeforeExecute = '_A_Command_onBeforeExecute',
+
+    /**
+     * Main command execution logic
+     * Core business logic should be implemented here
+     */
+    onExecute = '_A_Command_onExecute',
+
+    /**
+     * Triggered after command execution completes (success or failure)
+     * Use for cleanup, logging, or post-processing tasks
+     */
+    onAfterExecute = '_A_Command_onAfterExecute',
+
+    /**
+     * Triggered when command completes successfully
+     * Use for success-specific operations like notifications or result processing
+     */
+    onComplete = '_A_Command_onComplete',
+
+    /**
+     * Triggered when command execution fails
+     * Use for error handling, cleanup, or failure notifications
+     */
+    onFail = '_A_Command_onFail',
+
+    /**
+     * Triggered when an error occurs during execution
+     * Use for error logging, transformation, or recovery attempts
+     */
+    onError = '_A_Command_onError',
+}
+
+
+export enum A_CommandEvent {
     /**
      * Triggered during command initialization phase
      * Use to set up execution environment, validate parameters, or prepare resources
      */
     onInit = 'onInit',
-    
+
     /**
      * Triggered before command execution starts
      * Use for pre-execution validation, logging, or setup tasks
      */
     onBeforeExecute = 'onBeforeExecute',
-    
+
     /**
      * Main command execution logic
      * Core business logic should be implemented here
      */
     onExecute = 'onExecute',
-    
+
     /**
      * Triggered after command execution completes (success or failure)
      * Use for cleanup, logging, or post-processing tasks
      */
     onAfterExecute = 'onAfterExecute',
-    
+
     /**
      * Triggered when command completes successfully
      * Use for success-specific operations like notifications or result processing
      */
     onComplete = 'onComplete',
-    
+
     /**
      * Triggered when command execution fails
      * Use for error handling, cleanup, or failure notifications
      */
     onFail = 'onFail',
-    
+
     /**
      * Triggered when an error occurs during execution
      * Use for error logging, transformation, or recovery attempts
@@ -111,14 +156,11 @@ export enum A_CommandFeatures {
     onError = 'onError',
 }
 
-
-
-
 /**
  * Type alias for command lifecycle event names
  * Represents all available events that can be listened to on a command instance
  */
-export type A_Command_Event = keyof typeof A_CommandFeatures;
+export type A_CommandEvents = keyof typeof A_CommandEvent;
 
 
 

package/src/lib/A-Command/A-Command.entity.ts

@@ -1,21 +1,22 @@
 import {
+    A_Command_ExecutionContext,
     A_TYPES__Command_Init,
     A_TYPES__Command_Listener,
     A_TYPES__Command_Serialized
 } from "./A-Command.types";
 import {
     A_CommandFeatures,
-    A_Command_Event,
     A_Command_Status,
-    A_CommandTransitions
+    A_CommandTransitions,
+    A_CommandEvent
 } from "./A-Command.constants";
-import { A_Caller, A_Context, A_Dependency, A_Entity, A_Error, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import {  A_Context, A_Dependency, A_Entity, A_Error, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
 import { A_CommandError } from "./A-Command.error";
-import { A_OperationContext } from "../A-Operation/A-Operation.context";
 import { A_StateMachine } from "../A-StateMachine/A-StateMachine.component";
 import { A_StateMachineFeatures } from "../A-StateMachine/A-StateMachine.constants";
 import { A_Logger } from "../A-Logger/A-Logger.component";
 import { A_StateMachineTransition } from "../A-StateMachine/A-StateMachineTransition.context";
+import { A_ExecutionContext } from "../A-Execution/A-Execution.context";
 
 /**
  * A_Command - Advanced Command Pattern Implementation
@@ -79,7 +80,7 @@ import { A_StateMachineTransition } from "../A-StateMachine/A-StateMachineTransi
 export class A_Command<
     InvokeType extends A_TYPES__Command_Init = A_TYPES__Command_Init,
     ResultType extends Record<string, any> = Record<string, any>,
-    LifecycleEvents extends string | A_Command_Event = A_Command_Event,
+    LifecycleEvents extends string | keyof typeof A_CommandEvent = keyof typeof A_CommandEvent,
 > extends A_Entity<InvokeType, A_TYPES__Command_Serialized<InvokeType, ResultType>> {
 
     // ====================================================================
@@ -118,7 +119,7 @@ export class A_Command<
 
     /** Map of event listeners organized by event name */
     protected _listeners: Map<
-        LifecycleEvents | A_Command_Event,
+        LifecycleEvents | keyof typeof A_CommandEvent,
         Set<A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>>
     > = new Map();
 
@@ -173,6 +174,12 @@ export class A_Command<
     get scope(): A_Scope {
         return this._executionScope;
     }
+    /**
+     * Execution context associated with the command
+     */
+    get context(): A_ExecutionContext<A_Command_ExecutionContext<InvokeType, ResultType>> {
+        return this.scope.resolve(A_ExecutionContext<A_Command_ExecutionContext<InvokeType, ResultType>>)!;
+    }
 
     /**
      * Unique command type identifier
@@ -325,7 +332,7 @@ export class A_Command<
         this._createdAt = new Date();
         this._status = A_Command_Status.INITIALIZED;
 
-        this.emit(A_CommandFeatures.onInit);
+        this.emit(A_CommandEvent.onInit);
     }
 
     @A_Feature.Extend()
@@ -342,7 +349,7 @@ export class A_Command<
         this._startTime = new Date();
         this._status = A_Command_Status.EXECUTING;
 
-        this.emit(A_CommandFeatures.onExecute);
+        this.emit(A_CommandEvent.onExecute);
     }
 
     @A_Feature.Extend()
@@ -358,7 +365,7 @@ export class A_Command<
         this._endTime = new Date();
         this._status = A_Command_Status.COMPLETED;
 
-        this.emit(A_CommandFeatures.onComplete);
+        this.emit(A_CommandEvent.onComplete);
     }
 
     @A_Feature.Extend()
@@ -376,7 +383,7 @@ export class A_Command<
 
         this._status = A_Command_Status.FAILED;
 
-        this.emit(A_CommandFeatures.onFail);
+        this.emit(A_CommandEvent.onFail);
     }
 
 
@@ -438,7 +445,7 @@ export class A_Command<
     protected async [A_CommandFeatures.onFail](
         @A_Dependency.Required()
         @A_Inject(A_StateMachine) stateMachine: A_StateMachine,
-        @A_Inject(A_OperationContext) operation: A_OperationContext,
+        @A_Inject(A_ExecutionContext) operation: A_ExecutionContext<A_Command_ExecutionContext<InvokeType, ResultType>>,
         ...args: any[]
     ): Promise<void> {
         await stateMachine.transition(A_Command_Status.EXECUTING, A_Command_Status.FAILED);
@@ -464,7 +471,7 @@ export class A_Command<
         try {
             this.checkScopeInheritance();
 
-            const context = new A_OperationContext('execute-command');
+            const context = new A_ExecutionContext<A_Command_ExecutionContext<InvokeType, ResultType>>('execute-command');
 
             this.scope.register(context);
 
@@ -493,7 +500,7 @@ export class A_Command<
 
 
 
-                    this.on(A_CommandFeatures.onComplete, () => {
+                    this.on(A_CommandEvent.onComplete, () => {
 
                         onBeforeExecuteFeature.interrupt();
                         onExecuteFeature.interrupt();
@@ -536,6 +543,16 @@ export class A_Command<
 
     /**
      * Marks the command as completed
+     * 
+     * 
+     * Calling This method will set the command status to COMPLETED, record the end time,
+     * store the result, emit the onComplete event, and destroy the execution scope.
+     *
+     * [!] After Calling this method, the command is considered fully processed And further processing will be INTERRUPTED. 
+     * [!] If the command is already processed (COMPLETED or FAILED), this method does nothing.
+     * [!] This method can be called with optional result data to store with the command.
+     * 
+     * @param result - Optional result data to store with the command
      */
     async complete(result?: ResultType) {
         if (this.isProcessed) return;
@@ -579,7 +596,7 @@ export class A_Command<
      * @param event 
      * @param listener 
      */
-    on(event: LifecycleEvents | A_Command_Event, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
+    on(event: LifecycleEvents | A_CommandEvent, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
         if (!this._listeners.has(event)) {
             this._listeners.set(event, new Set());
         }
@@ -591,7 +608,7 @@ export class A_Command<
      * @param event 
      * @param listener 
      */
-    off(event: LifecycleEvents | A_Command_Event, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
+    off(event: LifecycleEvents | A_CommandEvent, listener: A_TYPES__Command_Listener<InvokeType, ResultType, LifecycleEvents>) {
         this._listeners.get(event)?.delete(listener);
     }
     /**
@@ -599,7 +616,7 @@ export class A_Command<
      * 
      * @param event 
      */
-    emit(event: LifecycleEvents | A_Command_Event) {
+    emit(event: LifecycleEvents | keyof typeof A_CommandEvent) {
         this._listeners.get(event)?.forEach(async listener => {
             listener(this);
         });

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

@@ -1,5 +1,5 @@
 import { A_Command } from "./A-Command.entity";
-import { A_Command_Event, A_Command_Status, } from "./A-Command.constants";
+import { A_CommandEvent, A_Command_Status, } from "./A-Command.constants";
 import { A_TYPES__Entity_Serialized, A_TYPES__Error_Serialized } from "@adaas/a-concept";
 
 // ============================================================================
@@ -58,55 +58,55 @@ export type A_TYPES__Command_Serialized<
      * Unique identifier for the command type (derived from class name)
      */
     code: string;
-    
+
     /**
      * Current execution status of the command
      */
     status: A_Command_Status;
-    
+
     /**
      * Parameters used to initialize the command
      */
     params: ParamsType;
-    
+
     // --------------------------------------------------
     // Timing Information
     // --------------------------------------------------
-    
+
     /**
      * ISO timestamp when the command was created
      */
     createdAt: string;
-    
+
     /**
      * ISO timestamp when command execution started (if started)
      */
     startedAt?: string;
-    
+
     /**
      * ISO timestamp when command execution ended (if completed/failed)
      */
     endedAt?: string;
-    
+
     /**
      * Total execution duration in milliseconds (if completed/failed)
      */
     duration?: number;
-    
+
     /**
      * Time between creation and execution start in milliseconds
      */
     idleTime?: number;
-    
+
     // --------------------------------------------------
     // Execution Results
     // --------------------------------------------------
-    
+
     /**
      * Result data produced by successful command execution
      */
     result?: ResultType;
-    
+
     /**
      * Array of serialized errors that occurred during execution
      */
@@ -141,8 +141,16 @@ export type A_TYPES__Command_Serialized<
 export type A_TYPES__Command_Listener<
     InvokeType extends A_TYPES__Command_Init = A_TYPES__Command_Init,
     ResultType extends Record<string, any> = Record<string, any>,
-    LifecycleEvents extends string = A_Command_Event
+    LifecycleEvents extends string = keyof typeof A_CommandEvent
 > = (command?: A_Command<InvokeType, ResultType, LifecycleEvents>) => void;
 
 
 
+
+export type A_Command_ExecutionContext<
+    InvokeType extends A_TYPES__Command_Init = A_TYPES__Command_Init,
+    ResultType extends Record<string, any> = Record<string, any>,
+> = {
+    result: ResultType,
+    params: InvokeType,
+}

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

@@ -1,20 +1,21 @@
-import { A_CommonHelper, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_FormatterHelper, A_Fragment, A_TYPES__ConceptENVVariables } from "@adaas/a-concept";
+import { A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_FormatterHelper, A_TYPES__ConceptENVVariables } from "@adaas/a-concept";
 import { A_TYPES__ConfigContainerConstructor } from "./A-Config.types";
+import { A_ExecutionContext } from "../A-Execution/A-Execution.context";
 import { A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY } from "./A-Config.constants";
+import { A_ConfigError } from "./A-Config.error";
 
 
 export class A_Config<
     T extends Array<string | A_TYPES__ConceptENVVariables[number]> = any[]
-> extends A_Fragment<{
-    [key in T[number]]: any
-}> {
-
-    config: A_TYPES__ConfigContainerConstructor<T>;
-
-
-    private VARIABLES: Map<T[number], any> = new Map<T[number], any>();
-
-    CONFIG_PROPERTIES!: T;
+> extends A_ExecutionContext<
+    { [key in T[number]]: any; } & {
+        [key in typeof A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY[number]]: any
+    } & {
+        [key in typeof A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY[number]]: any
+    }
+> {
+    protected _strict: boolean;
+    protected _configProperties!: T;
 
     protected DEFAULT_ALLOWED_TO_READ_PROPERTIES = [
         ...A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY,
@@ -25,60 +26,45 @@ export class A_Config<
     constructor(
         config: Partial<A_TYPES__ConfigContainerConstructor<T>>
     ) {
-        super({
-            name: 'A_Config'
-        });
-
-        this.config = A_CommonHelper.deepCloneAndMerge<A_TYPES__ConfigContainerConstructor<T>>(config as any, {
-            strict: false,
-            defaults: {},
-            variables: A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY as any as T
-        } as any);
-
-        this.CONFIG_PROPERTIES = this.config.variables ? this.config.variables : [] as any as T;
-
-        this.config.variables.forEach((variable) => {
-            this.VARIABLES.set(
-                A_FormatterHelper.toUpperSnakeCase(variable),
-                this.config.defaults[variable]
+        super('a-config');
+
+        this._strict = config.strict ?? false;
+        this._configProperties = config.variables ?? [] as any;
+
+
+        for (const key in config.defaults) {
+            this.set(
+                A_FormatterHelper.toUpperSnakeCase(key),
+                config.defaults[key as T[number]]
             );
-        });
+        }
+    }
+
+
+    get strict(): boolean {
+        return this._strict;
     }
 
 
     /** 
-     * This method is used to get the configuration property by name
-     * 
-     * @param property 
-     * @returns 
-     */
+      * This method is used to get the configuration property by name
+      * 
+      * @param property 
+      * @returns 
+      */
     get<K extends T[number]>(
         property: K | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]
     ): { [key in T[number]]: any; }[K] | undefined {
-        if (this.CONFIG_PROPERTIES.includes(property as any)
+        if (this._configProperties.includes(property as any)
             || this.DEFAULT_ALLOWED_TO_READ_PROPERTIES.includes(property as any)
-            || !(this.config.strict)
+            || !this._strict
         )
-            return this.VARIABLES.get(A_FormatterHelper.toUpperSnakeCase(property));
-
-        throw new Error('Property not exists or not allowed to read') as never;
-        // return this.concept.Errors.throw(A_SDK_CONSTANTS__ERROR_CODES.CONFIGURATION_PROPERTY_NOT_EXISTS_OR_NOT_ALLOWED_TO_READ) as never;
+            return super.get(A_FormatterHelper.toUpperSnakeCase(property));
 
+        throw new A_ConfigError('Property not exists or not allowed to read');
     }
 
 
-    //  get<_OutType = any>(
-    //         property: T[number] | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number] | string
-    //     ): _OutType {
-    //         if (this.CONFIG_PROPERTIES.includes(property as any)
-    //             || this.DEFAULT_ALLOWED_TO_READ_PROPERTIES.includes(property as any)
-    //             || !(this.config.strict)
-    //         )
-    //             return this.VARIABLES.get(A_FormatterHelper.toUpperSnakeCase(property)) as _OutType;
-
-    //         throw new Error('Property not exists or not allowed to read') as never;
-    //         // return this.concept.Errors.throw(A_SDK_CONSTANTS__ERROR_CODES.CONFIGURATION_PROPERTY_NOT_EXISTS_OR_NOT_ALLOWED_TO_READ) as never;
-    //     }
     /**
      * 
      * This method is used to set the configuration property by name
@@ -118,14 +104,7 @@ export class A_Config<
                     }));
 
         for (const { property, value } of array) {
-
-            let targetValue = value
-                ? value
-                : this.config?.defaults
-                    ? this.config.defaults[property as T[number]]
-                    : undefined;
-
-            this.VARIABLES.set(A_FormatterHelper.toUpperSnakeCase(property), targetValue);
+            super.set(A_FormatterHelper.toUpperSnakeCase(property), value);
         }
     }
 }