@adaas/a-utils 0.1.17 → 0.1.19

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

@@ -5,4 +5,15 @@ export class A_CommandError extends A_Error {
 
 
     static readonly CommandScopeBindingError = 'A-Command Scope Binding Error';
+
+    static readonly ExecutionError = 'A-Command Execution Error';
+
+
+    static readonly ResultProcessingError = 'A-Command Result Processing Error';
+
+
+    /**
+     * Error indicating that the command was interrupted during execution
+     */
+    static readonly CommandInterruptedError = 'A-Command Interrupted Error';
 }

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

@@ -1,72 +1,148 @@
 import { A_Command } from "./A-Command.entity";
-import { A_CONSTANTS__A_Command_Event, A_CONSTANTS__A_Command_Status, } from "./A-Command.constants";
+import { A_Command_Event, A_Command_Status, } from "./A-Command.constants";
 import { A_TYPES__Entity_Serialized, A_TYPES__Error_Serialized } from "@adaas/a-concept";
 
-
-
 // ============================================================================
 // --------------------------- Primary Types ----------------------------------
 // ============================================================================
+
 /**
- * Command constructor type
- * Uses the generic type T to specify the type of the entity
+ * Command Constructor Type
+ * 
+ * Generic constructor type for creating command instances.
+ * Used for dependency injection and factory patterns.
+ * 
+ * @template T - The command class type extending A_Command
  */
 export type A_TYPES__Command_Constructor<T = A_Command> = new (...args: any[]) => T;
+
 /**
- * Command initialization type
+ * Command Initialization Parameters
+ * 
+ * Base type for command parameters. Commands should extend this with
+ * specific parameter types for their use case.
+ * 
+ * @example
+ * ```typescript
+ * interface UserCommandParams extends A_TYPES__Command_Init {
+ *   userId: string;
+ *   action: 'create' | 'update' | 'delete';
+ * }
+ * ```
  */
 export type A_TYPES__Command_Init = Record<string, any>;
+
 /**
- * Command serialized type
+ * Command Serialized Format
+ * 
+ * Complete serialized representation of a command including all state,
+ * timing information, results, and errors. Used for persistence,
+ * transmission between services, and state restoration.
+ * 
+ * @template ParamsType - Type of command parameters
+ * @template ResultType - Type of command execution result
+ * 
+ * @example
+ * ```typescript
+ * const serialized: A_TYPES__Command_Serialized<
+ *   { userId: string },
+ *   { success: boolean }
+ * > = command.toJSON();
+ * ```
  */
 export type A_TYPES__Command_Serialized<
     ParamsType extends Record<string, any> = Record<string, any>,
     ResultType extends Record<string, any> = Record<string, any>
 > = {
     /**
-     * Unique code of the command
+     * Unique identifier for the command type (derived from class name)
      */
     code: string;
+    
     /**
-     * Current status of the command
+     * Current execution status of the command
      */
-    status: A_CONSTANTS__A_Command_Status;
+    status: A_Command_Status;
+    
     /**
-     * Parameters used to invoke the command
+     * Parameters used to initialize the command
      */
     params: ParamsType;
+    
+    // --------------------------------------------------
+    // Timing Information
     // --------------------------------------------------
+    
+    /**
+     * ISO timestamp when the command was created
+     */
+    createdAt: string;
+    
     /**
-     * The time when the command was created
+     * ISO timestamp when command execution started (if started)
      */
     startedAt?: string;
+    
     /**
-     * The time when the command execution ended
+     * ISO timestamp when command execution ended (if completed/failed)
      */
     endedAt?: string;
+    
     /**
-     * Duration of the command execution in milliseconds
+     * Total execution duration in milliseconds (if completed/failed)
      */
     duration?: number;
+    
+    /**
+     * Time between creation and execution start in milliseconds
+     */
+    idleTime?: number;
+    
     // --------------------------------------------------
+    // Execution Results
+    // --------------------------------------------------
+    
     /**
-     * Result of the command execution
+     * Result data produced by successful command execution
      */
     result?: ResultType;
+    
     /**
-     * List of errors occurred during the command execution
+     * Array of serialized errors that occurred during execution
      */
-    errors?: Array<A_TYPES__Error_Serialized>;
+    error?: A_TYPES__Error_Serialized;
 } & A_TYPES__Entity_Serialized
 
 // ============================================================================
-// ---------------------------- Common Types ----------------------------------
+// ---------------------------- Event Types -----------------------------------
 // ============================================================================
+
 /**
- * Command listener type
+ * Command Event Listener Function
+ * 
+ * Type definition for event listener functions that can be registered
+ * to respond to command lifecycle events.
+ * 
+ * @template InvokeType - Type of command initialization parameters
+ * @template ResultType - Type of command execution result  
+ * @template LifecycleEvents - Union type of custom lifecycle event names
+ * 
+ * @param command - The command instance that triggered the event
+ * 
+ * @example
+ * ```typescript
+ * const listener: A_TYPES__Command_Listener<UserParams, UserResult> = (command) => {
+ *   console.log(`Command ${command?.code} triggered event`);
+ * };
+ * 
+ * command.on('onExecute', listener);
+ * ```
  */
 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_CONSTANTS__A_Command_Event
+    LifecycleEvents extends string = A_Command_Event
 > = (command?: A_Command<InvokeType, ResultType, LifecycleEvents>) => void;
+
+
+

package/src/lib/A-Command/README.md

@@ -43,22 +43,24 @@ npm install @adaas/a-utils
 
 ```typescript
 import { A_Command } from '@adaas/a-utils/lib/A-Command/A-Command.entity';
-import { A_Context } from '@adaas/a-concept';
+import { A_Scope } from '@adaas/a-concept';
 
-// Create a basic command
+// Create a basic command with parameters
 const command = new A_Command({
     action: 'greet',
     name: 'World'
 });
 
-// Register command in context
-A_Context.root.register(command);
+// Register command in scope for dependency injection
+const scope = A_Scope.context();
+scope.register(command);
 
-// Execute the command
+// Execute the command (automatically handles complete lifecycle)
 await command.execute();
 
-console.log(`Command status: ${command.status}`);
+console.log(`Command status: ${command.status}`); // COMPLETED
 console.log(`Execution duration: ${command.duration}ms`);
+console.log(`Command result:`, command.result);
 ```
 
 ### Typed Command with Custom Parameters and Result
@@ -99,7 +101,7 @@ console.log(`Created user: ${result?.userId}`);
 ```typescript
 import { A_Component, A_Feature, A_Inject } from '@adaas/a-concept';
 import { A_Memory } from '@adaas/a-utils/lib/A-Memory/A-Memory.context';
-import { A_CONSTANTS_A_Command_Features } from '@adaas/a-utils/lib/A-Command/A-Command.constants';
+import { A_CommandFeatures } from '@adaas/a-utils/lib/A-Command/A-Command.constants';
 
 // Define command types
 interface OrderProcessParams {
@@ -115,37 +117,75 @@ interface OrderProcessResult {
     paymentProcessed: boolean;
 }
 
-class ProcessOrderCommand extends A_Command<OrderProcessParams, OrderProcessResult> {}
+class ProcessOrderCommand extends A_Command<OrderProcessParams, OrderProcessResult> {
+    
+    /**
+     * Custom execution logic with feature-based processing
+     * This method is automatically called during command execution
+     */
+    @A_Feature.Define({
+        template: [
+            {
+                name: 'orderNumber',
+                component: 'OrderProcessor',
+                handler: 'generateOrderNumber'
+            },
+            {
+                name: 'totalAmount', 
+                component: 'OrderProcessor',
+                handler: 'calculateTotal'
+            },
+            {
+                name: 'paymentProcessed',
+                component: 'PaymentProcessor', 
+                handler: 'processPayment'
+            }
+        ]
+    })
+    protected async [A_CommandFeatures.onExecute](): Promise<void> {
+        console.log(`Processing order ${this.params.orderId} for customer ${this.params.customerId}`);
+    }
+}
 
-// Create a component with custom execution logic
+// Create components with specialized handlers
 class OrderProcessor extends A_Component {
     
-    @A_Feature.Extend({ scope: [ProcessOrderCommand] })
-    async [A_CONSTANTS_A_Command_Features.EXECUTE](
-        @A_Inject(A_Memory) memory: A_Memory<OrderProcessResult>
-    ) {
-        // Access command parameters through the command instance
-        const command = A_Context.scope(this).resolve(ProcessOrderCommand);
-        const { orderId, items, customerId } = command.params;
-        
-        // Process the order
-        const orderNumber = `ORD-${Date.now()}`;
-        const totalAmount = items.reduce((sum, item) => sum + (item.quantity * 10), 0);
-        const estimatedDelivery = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
-        
-        // Store results in memory
-        await memory.set('orderNumber', orderNumber);
-        await memory.set('totalAmount', totalAmount);
-        await memory.set('estimatedDelivery', estimatedDelivery);
-        await memory.set('paymentProcessed', true);
-        
-        console.log(`Processed order ${orderNumber} for customer ${customerId}`);
+    generateOrderNumber() {
+        return `ORD-${Date.now()}`;
+    }
+    
+    calculateTotal(@A_Inject(ProcessOrderCommand) command: ProcessOrderCommand) {
+        return command.params.items.reduce((sum, item) => sum + (item.quantity * 10), 0);
     }
 }
 
-// Usage
-A_Context.reset();
-A_Context.root.register(OrderProcessor);
+class PaymentProcessor extends A_Component {
+    
+    async processPayment(@A_Inject(ProcessOrderCommand) command: ProcessOrderCommand) {
+        console.log(`Processing payment for order ${command.params.orderId}`);
+        // Simulate payment processing
+        await new Promise(resolve => setTimeout(resolve, 100));
+        return true;
+    }
+}
+
+// Usage with A_Concept architecture
+const concept = new A_Concept({
+    containers: [
+        new A_Container({
+            name: 'Order Processing',
+            components: [
+                ProcessOrderCommand,
+                OrderProcessor,
+                PaymentProcessor,
+                A_Memory,
+                A_Logger
+            ]
+        })
+    ]
+});
+
+await concept.load();
 
 const command = new ProcessOrderCommand({
     orderId: 'order-123',
@@ -156,7 +196,7 @@ const command = new ProcessOrderCommand({
     ]
 });
 
-A_Context.root.register(command);
+concept.scope.register(command);
 await command.execute();
 
 console.log('Order processed:', command.result);
@@ -193,11 +233,24 @@ console.log('Duration:', command.duration, 'ms');
 
 ### Lifecycle Phases
 
+A-Command follows a structured lifecycle with automatic state transitions:
+
 1. **CREATED** - Initial state when command is instantiated
-2. **INITIALIZATION** - Setting up execution scope and dependencies
-3. **INITIALIZED** - Ready for compilation
-4. **COMPILATION** - Preparing execution environment
-5. **COMPILED** - Ready for execution
+2. **INITIALIZED** - Dependencies resolved and scope configured  
+3. **COMPILED** - Execution environment prepared and validated
+4. **EXECUTING** - Command is currently running
+5. **COMPLETED** - Execution finished successfully
+6. **FAILED** - Execution encountered errors and terminated
+
+### Status Transitions
+
+The command automatically transitions through states during execution:
+
+```
+CREATED → INITIALIZED → COMPILED → EXECUTING → COMPLETED/FAILED
+```
+
+Each transition triggers corresponding lifecycle events that you can subscribe to for monitoring and custom logic.
 6. **COMPLETED** - Successfully finished execution
 7. **FAILED** - Execution failed with errors
 
@@ -443,43 +496,86 @@ enum A_CONSTANTS_A_Command_Features {
 
 ## Examples
 
-### File Processing Command
+The A-Command library comes with comprehensive examples demonstrating various usage patterns and architectures. These examples are fully documented with detailed explanations of concepts and implementation patterns.
+
+### 📁 Example Files
+
+#### Multi-Service Distributed Processing
+**File:** `examples/A-Command-examples.ts`
+
+This example demonstrates advanced multi-service command processing architecture:
+
+- **Multi-Service Architecture**: Commands distributed across Service A and Service B
+- **Inter-Service Communication**: Commands routed between services using channels
+- **Shared Memory**: State sharing between services for coordinated processing
+- **Lifecycle Management**: Complete command lifecycle across distributed services
+- **Component-Based Processing**: Specialized processors for different execution phases
 
 ```typescript
-interface FileProcessParams {
-    filePath: string;
-    operation: 'compress' | 'encrypt' | 'convert';
-    options: Record<string, any>;
-}
+// Example: Command processing across multiple services
+const command = new TestCommand({ userId: '123' });
+const channel = scope.resolve(SimpleChannel);
+const result = await channel.execute(command); // Distributed execution
+```
+
+**Key Concepts Covered:**
+- Service container registration and discovery
+- Command routing and channel implementation
+- Cross-service state management with shared memory
+- Pre/main/post execution phases across services
+- Result aggregation from distributed processing
 
-interface FileProcessResult {
-    outputPath: string;
-    originalSize: number;
-    processedSize: number;
-    processingTime: number;
+#### Feature-Driven Template Processing
+**File:** `examples/A-Command-examples-2.ts`
+
+This example showcases feature-driven command architecture using templates:
+
+- **Template-Based Execution**: Result properties mapped to component handlers
+- **Automated Processing**: Framework automatically calls mapped component methods
+- **Modular Components**: Specialized components for different result aspects
+- **Result Compilation**: Handler outputs automatically compiled into result object
+- **Container-Based Execution**: Integrated execution environment with dependency injection
+
+```typescript
+// Example: Feature template mapping result properties to handlers
+@A_Feature.Define({
+    template: [
+        { name: 'itemName', component: 'ComponentA', handler: 'resolveItemName' },
+        { name: 'itemPrice', component: 'ComponentB', handler: 'calculatePrice' }
+    ]
+})
+protected async [A_CommandFeatures.onExecute](): Promise<void> {
+    // Template processing happens automatically after this method
 }
+```
 
-class FileProcessCommand extends A_Command<FileProcessParams, FileProcessResult> {}
+**Key Concepts Covered:**
+- Feature template configuration and mapping
+- Component handler automatic execution
+- Result property compilation from handler outputs
+- Container-based dependency injection
+- Modular component architecture
 
-class FileProcessor extends A_Component {
-    
-    @A_Feature.Extend({ scope: [FileProcessCommand] })
-    async [A_CONSTANTS_A_Command_Features.EXECUTE](
-        @A_Inject(A_Memory) memory: A_Memory<FileProcessResult>
-    ) {
-        const command = A_Context.scope(this).resolve(FileProcessCommand);
-        const { filePath, operation, options } = command.params;
-        
-        const startTime = Date.now();
-        
-        // Simulate file processing
-        await new Promise(resolve => setTimeout(resolve, 1000));
-        
-        const endTime = Date.now();
-        
-        await memory.set('outputPath', `processed_${filePath}`);
-        await memory.set('originalSize', 1024);
-        await memory.set('processedSize', 512);
+### 🚀 Running the Examples
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd adaas-a-utils
+
+# Install dependencies
+npm install
+
+# Run multi-service distributed processing example
+npx ts-node examples/A-Command-examples.ts
+
+# Run feature-driven template processing example
+npx ts-node examples/A-Command-examples-2.ts
+```
+
+### 📚 Additional Examples
+
+#### Basic Command Creation
         await memory.set('processingTime', endTime - startTime);
     }
 }

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

@@ -1,4 +1,4 @@
-import { A_Caller, A_Concept, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_Container, A_Context, A_Inject, A_Scope, A_ScopeError } from "@adaas/a-concept";
+import { A_Caller, A_Concept, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_Container, A_Context, A_Fragment, A_Inject, A_Scope, A_ScopeError } from "@adaas/a-concept";
 import { ConfigReader } from "./components/ConfigReader.component";
 import { A_Config } from "./A-Config.context";
 import { A_Polyfill } from "../A-Polyfill/A-Polyfill.component";
@@ -28,7 +28,7 @@ export class A_ConfigLoader extends A_Container {
                 defaults: {}
             });
 
-            this.scope.register(newConfig);
+            this.scope.register<A_Fragment>(newConfig);
         }
 
 

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

@@ -5,7 +5,9 @@ import { A_CONSTANTS__CONFIG_ENV_VARIABLES_ARRAY } from "./A-Config.constants";
 
 export class A_Config<
     T extends Array<string | A_TYPES__ConceptENVVariables[number]> = any[]
-> extends A_Fragment {
+> extends A_Fragment<{
+    [key in T[number]]: any
+}> {
 
     config: A_TYPES__ConfigContainerConstructor<T>;
 
@@ -50,21 +52,33 @@ export class A_Config<
      * @param property 
      * @returns 
      */
-    get<_OutType = any>(
-        property: T[number] | typeof this.DEFAULT_ALLOWED_TO_READ_PROPERTIES[number]
-    ): _OutType {
+    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)
             || this.DEFAULT_ALLOWED_TO_READ_PROPERTIES.includes(property as any)
             || !(this.config.strict)
         )
-            return this.VARIABLES.get(A_FormatterHelper.toUpperSnakeCase(property)) as _OutType;
+            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;
+
     }
 
 
+    //  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

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

@@ -18,7 +18,7 @@ export class ConfigReader extends A_Component {
     async attachContext(
         @A_Inject(A_Container) container: A_Container,
         @A_Inject(A_Feature) feature: A_Feature,
-        @A_Inject(A_Config) config?: A_Config,
+        @A_Inject(A_Config) config?: A_Config<any>,
     ) {
         if (!config) {
             config= new A_Config({