@adaas/a-utils 0.1.11 → 0.1.13

package/examples/command-examples.ts

@@ -0,0 +1,268 @@
+/**
+ * A-Command Examples
+ * 
+ * This file contains practical examples of using A-Command for various scenarios.
+ * Run with: npx ts-node examples/command-examples.ts
+ */
+
+import { A_Command } from '../src/lib/A-Command/A-Command.entity';
+import { A_CONSTANTS_A_Command_Features } from '../src/lib/A-Command/A-Command.constants';
+import { A_Memory } from '../src/lib/A-Memory/A-Memory.context';
+import { A_Component, A_Context, A_Feature, A_Inject, A_Error } from '@adaas/a-concept';
+
+// Example 1: Basic Command Usage
+async function basicCommandExample() {
+    console.log('\n=== Basic Command Example ===');
+    
+    const command = new A_Command({
+        action: 'greet',
+        name: 'World'
+    });
+
+    A_Context.root.register(command);
+
+    // Add event listeners
+    command.on('init', () => console.log('Command initializing...'));
+    command.on('complete', () => console.log('Command completed!'));
+
+    await command.execute();
+
+    console.log(`Status: ${command.status}`);
+    console.log(`Duration: ${command.duration}ms`);
+    console.log(`Code: ${command.code}`);
+}
+
+// Example 2: Typed Command with Custom Logic
+interface UserCreateParams {
+    name: string;
+    email: string;
+    role: 'admin' | 'user';
+}
+
+interface UserCreateResult {
+    userId: string;
+    createdAt: string;
+    profileCreated: boolean;
+}
+
+class CreateUserCommand extends A_Command<UserCreateParams, UserCreateResult> {}
+
+class UserCreationService extends A_Component {
+    
+    @A_Feature.Extend({ scope: [CreateUserCommand] })
+    async [A_CONSTANTS_A_Command_Features.EXECUTE](
+        @A_Inject(A_Memory) memory: A_Memory<UserCreateResult>
+    ) {
+        const command = A_Context.scope(this).resolve(CreateUserCommand);
+        const { name, email, role } = command.params;
+        
+        console.log(`Creating user: ${name} (${email}) with role: ${role}`);
+        
+        // Simulate user creation
+        const userId = `user_${Date.now()}`;
+        const createdAt = new Date().toISOString();
+        
+        // Store results in memory
+        await memory.set('userId', userId);
+        await memory.set('createdAt', createdAt);
+        await memory.set('profileCreated', true);
+        
+        console.log(`User created with ID: ${userId}`);
+    }
+}
+
+async function typedCommandExample() {
+    console.log('\n=== Typed Command with Custom Logic Example ===');
+    
+    A_Context.reset();
+    A_Context.root.register(UserCreationService);
+    
+    const command = new CreateUserCommand({
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user'
+    });
+
+    A_Context.root.register(command);
+    await command.execute();
+
+    console.log('User creation result:', command.result);
+}
+
+// Example 3: Command Serialization and Persistence
+async function serializationExample() {
+    console.log('\n=== Command Serialization Example ===');
+    
+    A_Context.reset();
+    A_Context.root.register(UserCreationService);
+    
+    // Create and execute original command
+    const originalCommand = new CreateUserCommand({
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin'
+    });
+
+    A_Context.root.register(originalCommand);
+    await originalCommand.execute();
+
+    // Serialize command
+    const serialized = originalCommand.toJSON();
+    console.log('Command serialized for storage/transmission');
+
+    // Simulate storage and retrieval
+    const serializedJson = JSON.stringify(serialized);
+    const parsedData = JSON.parse(serializedJson);
+
+    // Restore command from serialized data
+    const restoredCommand = new CreateUserCommand(parsedData);
+    
+    console.log('Command restored from serialization:');
+    console.log(`- Status: ${restoredCommand.status}`);
+    console.log(`- Duration: ${restoredCommand.duration}ms`);
+    console.log(`- User ID: ${restoredCommand.result?.userId}`);
+    console.log(`- Created At: ${restoredCommand.result?.createdAt}`);
+}
+
+// Example 4: Error Handling
+class FailingCommand extends A_Command<{ shouldFail: boolean }, { success: boolean }> {}
+
+class FailingService extends A_Component {
+    
+    @A_Feature.Extend({ scope: [FailingCommand] })
+    async [A_CONSTANTS_A_Command_Features.EXECUTE](
+        @A_Inject(A_Memory) memory: A_Memory<{ success: boolean }>
+    ) {
+        const command = A_Context.scope(this).resolve(FailingCommand);
+        
+        if (command.params.shouldFail) {
+            // Add error to memory
+            await memory.error(new A_Error({
+                title: 'Intentional Failure',
+                message: 'This command was designed to fail',
+                code: 'INTENTIONAL_FAIL'
+            }));
+            
+            throw new Error('Command failed as requested');
+        }
+        
+        await memory.set('success', true);
+    }
+}
+
+async function errorHandlingExample() {
+    console.log('\n=== Error Handling Example ===');
+    
+    A_Context.reset();
+    A_Context.root.register(FailingService);
+    
+    // Test successful command
+    const successCommand = new FailingCommand({ shouldFail: false });
+    A_Context.root.register(successCommand);
+    await successCommand.execute();
+    
+    console.log(`Success command - Status: ${successCommand.status}`);
+    console.log(`Success command - Result:`, successCommand.result);
+    
+    // Test failing command
+    const failCommand = new FailingCommand({ shouldFail: true });
+    A_Context.root.register(failCommand);
+    await failCommand.execute();
+    
+    console.log(`Fail command - Status: ${failCommand.status}`);
+    console.log(`Fail command - Is Failed: ${failCommand.isFailed}`);
+    console.log(`Fail command - Errors:`, Array.from(failCommand.errors?.values() || []));
+}
+
+// Example 5: Custom Events
+type FileProcessEvents = 'validation-started' | 'processing' | 'cleanup';
+
+class FileProcessCommand extends A_Command<
+    { filePath: string; operation: string },
+    { outputPath: string; size: number },
+    FileProcessEvents
+> {}
+
+class FileProcessor extends A_Component {
+    
+    @A_Feature.Extend({ scope: [FileProcessCommand] })
+    async [A_CONSTANTS_A_Command_Features.EXECUTE](
+        @A_Inject(A_Memory) memory: A_Memory<{ outputPath: string; size: number }>
+    ) {
+        const command = A_Context.scope(this).resolve(FileProcessCommand);
+        const { filePath, operation } = command.params;
+        
+        // Emit custom events during processing
+        command.emit('validation-started');
+        console.log(`Validating file: ${filePath}`);
+        await new Promise(resolve => setTimeout(resolve, 100));
+        
+        command.emit('processing');
+        console.log(`Processing file with operation: ${operation}`);
+        await new Promise(resolve => setTimeout(resolve, 200));
+        
+        command.emit('cleanup');
+        console.log('Cleaning up temporary files');
+        await new Promise(resolve => setTimeout(resolve, 50));
+        
+        await memory.set('outputPath', `processed_${filePath}`);
+        await memory.set('size', 1024);
+    }
+}
+
+async function customEventsExample() {
+    console.log('\n=== Custom Events Example ===');
+    
+    A_Context.reset();
+    A_Context.root.register(FileProcessor);
+    
+    const command = new FileProcessCommand({
+        filePath: 'document.pdf',
+        operation: 'compress'
+    });
+
+    // Subscribe to custom events
+    command.on('validation-started', () => console.log('📋 Validation phase started'));
+    command.on('processing', () => console.log('⚙️  Processing phase started'));
+    command.on('cleanup', () => console.log('🧹 Cleanup phase started'));
+    
+    // Subscribe to lifecycle events
+    command.on('complete', () => console.log('✅ File processing completed'));
+
+    A_Context.root.register(command);
+    await command.execute();
+
+    console.log('Final result:', command.result);
+}
+
+// Run all examples
+async function runAllExamples() {
+    console.log('🚀 Running A-Command Examples\n');
+    
+    try {
+        await basicCommandExample();
+        await typedCommandExample();
+        await serializationExample();
+        await errorHandlingExample();
+        await customEventsExample();
+        
+        console.log('\n✅ All examples completed successfully!');
+    } catch (error) {
+        console.error('\n❌ Example failed:', error);
+    }
+}
+
+// Export for use as module or run directly
+export {
+    basicCommandExample,
+    typedCommandExample,
+    serializationExample,
+    errorHandlingExample,
+    customEventsExample,
+    runAllExamples
+};
+
+// Run if this file is executed directly
+if (require.main === module) {
+    runAllExamples();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-utils",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

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

@@ -5,7 +5,11 @@ export enum A_TYPES__CommandMetaKey {
 }
 
 export enum A_CONSTANTS__A_Command_Status {
+    CREATED = 'CREATED',
+    INITIALIZATION = 'INITIALIZATION',
     INITIALIZED = 'INITIALIZED',
+    COMPILATION = 'COMPILATION',
+    COMPILED = 'COMPILED',
     IN_PROGRESS = 'IN_PROGRESS',
     COMPLETED = 'COMPLETED',
     FAILED = 'FAILED',

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

@@ -9,13 +9,14 @@ import {
 } from "./A-Command.constants";
 import { A_Context, A_Entity, A_Error, A_Scope } from "@adaas/a-concept";
 import { A_Memory } from "../A-Memory/A-Memory.context";
+import { A_CommandError } from "./A-Command.error";
 
 
 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_CONSTANTS__A_Command_Event
-> extends A_Entity<InvokeType, A_TYPES__Command_Serialized<ResultType>> {
+    LifecycleEvents extends string | A_CONSTANTS__A_Command_Event = A_CONSTANTS__A_Command_Event
+> extends A_Entity<InvokeType, A_TYPES__Command_Serialized<InvokeType, ResultType>> {
 
     // ====================================================================
     // ================== Static A-Command Information ====================
@@ -136,7 +137,7 @@ export class A_Command<
         /**
          * Command invocation parameters
          */
-        params: InvokeType | A_TYPES__Command_Serialized<ResultType> | string
+        params: InvokeType | A_TYPES__Command_Serialized<InvokeType, ResultType> | string
     ) {
         super(params as any)
     }
@@ -148,32 +149,63 @@ export class A_Command<
 
     // should create a new Task in DB  with basic records
     async init(): Promise<void> {
-        this._status = A_CONSTANTS__A_Command_Status.IN_PROGRESS;
-        this._startTime = new Date();
-        if (!this.scope.isInheritedFrom(A_Context.scope(this))) {
-            this.scope.inherit(A_Context.scope(this));
+        //  first check statuis if it passed then - skip
+        if (this._status !== A_CONSTANTS__A_Command_Status.CREATED) {
+            return;
         }
 
+        this._status = A_CONSTANTS__A_Command_Status.INITIALIZATION;
+        this._startTime = new Date();
+
+        this.checkScopeInheritance();
 
         this.emit('init');
-        return await this.call('init', this.scope);
+        await this.call('init', this.scope);
+        this._status = A_CONSTANTS__A_Command_Status.INITIALIZED;
     }
 
     // Should compile everything before execution
     async compile() {
+        if (this._status !== A_CONSTANTS__A_Command_Status.INITIALIZED) {
+            return;
+        }
+
+        this.checkScopeInheritance();
+
+        this._status = A_CONSTANTS__A_Command_Status.COMPILATION;
         this.emit('compile');
-        return await this.call('compile', this.scope);
+        await this.call('compile', this.scope);
+        this._status = A_CONSTANTS__A_Command_Status.COMPILED;
+    }
+
+    /**
+     * Processes the command execution
+     * 
+     * @returns 
+     */
+    async process() {
+        if (this._status !== A_CONSTANTS__A_Command_Status.COMPILED)
+            return;
+
+        this._status = A_CONSTANTS__A_Command_Status.IN_PROGRESS;
+
+        this.checkScopeInheritance();
+
+        this.emit('execute');
+
+        await this.call('execute', this.scope);
     }
 
     /**
      * Executes the command logic.
      */
     async execute(): Promise<any> {
+        this.checkScopeInheritance();
+
         try {
             await this.init();
             await this.compile();
-            this.emit('execute');
-            await this.call('execute', this.scope);
+            await this.process();
             await this.complete();
 
         } catch (error) {
@@ -185,6 +217,8 @@ export class A_Command<
      * Marks the command as completed
      */
     async complete() {
+        this.checkScopeInheritance();
+
         this._status = A_CONSTANTS__A_Command_Status.COMPLETED;
         this._endTime = new Date();
         this._result = this.scope.resolve(A_Memory).toJSON() as ResultType;
@@ -198,6 +232,8 @@ export class A_Command<
      * Marks the command as failed
      */
     async fail() {
+        this.checkScopeInheritance();
+
         this._status = A_CONSTANTS__A_Command_Status.FAILED;
         this._endTime = new Date();
         this._errors = this.scope.resolve(A_Memory).Errors;
@@ -265,7 +301,7 @@ export class A_Command<
 
         this._params = newEntity;
 
-        this._status = A_CONSTANTS__A_Command_Status.INITIALIZED;
+        this._status = A_CONSTANTS__A_Command_Status.CREATED;
     }
 
 
@@ -277,7 +313,7 @@ export class A_Command<
      * 
      * @param serialized 
      */
-    fromJSON(serialized: A_TYPES__Command_Serialized<ResultType>): void {
+    fromJSON(serialized: A_TYPES__Command_Serialized<InvokeType, ResultType>): void {
         super.fromJSON(serialized);
 
         this._executionScope = new A_Scope();
@@ -303,7 +339,10 @@ export class A_Command<
             });
         }
 
-        this._status = serialized.status || A_CONSTANTS__A_Command_Status.INITIALIZED;
+        this._params = serialized.params
+
+        this._status = serialized.status || A_CONSTANTS__A_Command_Status.CREATED;
+
     }
 
 
@@ -312,11 +351,12 @@ export class A_Command<
      * 
      * @returns 
      */
-    toJSON(): A_TYPES__Command_Serialized<ResultType> {
+    toJSON(): A_TYPES__Command_Serialized<InvokeType, ResultType> {
         return {
             ...super.toJSON(),
             code: this.code,
             status: this._status,
+            params: this._params,
             startedAt: this._startTime ? this._startTime.toISOString() : undefined,
             endedAt: this._endTime ? this._endTime.toISOString() : undefined,
             duration: this.duration,
@@ -324,4 +364,23 @@ export class A_Command<
             errors: this.errors ? Array.from(this.errors).map(err => err.toJSON()) : undefined
         }
     };
+
+
+    protected checkScopeInheritance(): void {
+        let attachedScope: A_Scope;
+        try {
+            attachedScope = A_Context.scope(this);
+        } catch (error) {
+            throw new A_CommandError({
+                title: A_CommandError.CommandScopeBindingError,
+                description: `Command ${this.code} is not bound to any context scope. Ensure the command is properly registered within a context before execution.`,
+                originalError: error
+            });
+        }
+
+        if (!this.scope.isInheritedFrom(A_Context.scope(this))) {
+            this.scope.inherit(A_Context.scope(this));
+        }
+    }
+
 }

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

@@ -3,4 +3,6 @@ import { A_Error } from "@adaas/a-concept";
 
 export class A_CommandError extends A_Error {
 
+
+    static readonly CommandScopeBindingError = 'A-Command Scope Binding Error';
 }

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

@@ -15,11 +15,12 @@ export type A_TYPES__Command_Constructor<T = A_Command> = new (...args: any[]) =
 /**
  * Command initialization type
  */
-export type A_TYPES__Command_Init = any;
+export type A_TYPES__Command_Init = Record<string, any>;
 /**
  * Command serialized type
  */
 export type A_TYPES__Command_Serialized<
+    ParamsType extends Record<string, any> = Record<string, any>,
     ResultType extends Record<string, any> = Record<string, any>
 > = {
     /**
@@ -30,6 +31,10 @@ export type A_TYPES__Command_Serialized<
      * Current status of the command
      */
     status: A_CONSTANTS__A_Command_Status;
+    /**
+     * Parameters used to invoke the command
+     */
+    params: ParamsType;
     // --------------------------------------------------
     /**
      * The time when the command was created