@adaas/a-utils 0.1.11 → 0.1.13

package/README.md

@@ -59,45 +59,73 @@ const channel = new A_Channel();
 
 ### A-Command
 
-A powerful command execution system that provides structured command patterns with lifecycle management, status tracking, and serialization capabilities.
+A powerful command execution system that provides structured command patterns with lifecycle management, event handling, status tracking, and serialization capabilities.
 
-**Basic Usage:**
+> 📚 **[Complete A-Command Documentation](./src/lib/A-Command/README.md)** - Comprehensive guide with examples, API reference, and advanced usage patterns.
+
+**Quick Start:**
 ```typescript
 import { A_Command } from '@adaas/a-utils';
+import { A_Context } from '@adaas/a-concept';
 
-// Create a command
-const command = new A_Command({});
+// Create and execute a simple command
+const command = new A_Command({ action: 'greet', name: 'World' });
+A_Context.root.register(command);
 
-// Execute the command
 await command.execute();
 
 console.log(command.status); // 'COMPLETED'
 console.log(command.duration); // Execution time in ms
 ```
 
-**Advanced Usage:**
+**Advanced Example:**
 ```typescript
-// Command with custom logic
-class CustomCommand extends A_Command {
-    async execute() {
-        // Your custom command logic here
-        return await super.execute();
+// Typed command with custom logic
+interface UserCreateParams {
+    name: string;
+    email: string;
+}
+
+interface UserCreateResult {
+    userId: string;
+    createdAt: string;
+}
+
+class CreateUserCommand extends A_Command<UserCreateParams, UserCreateResult> {}
+
+// Custom execution logic using components
+class UserProcessor extends A_Component {
+    @A_Feature.Extend({ scope: [CreateUserCommand] })
+    async execute(@A_Inject(A_Memory) memory: A_Memory<UserCreateResult>) {
+        // Your business logic here
+        await memory.set('userId', 'user-123');
+        await memory.set('createdAt', new Date().toISOString());
     }
 }
 
-// Serialization
-const command = new A_Command({});
-await command.execute();
+// Execute with event handling
+const command = new CreateUserCommand({
+    name: 'John Doe',
+    email: 'john@example.com'
+});
+
+command.on('complete', (cmd) => {
+    console.log('User created:', cmd.result);
+});
 
-const serialized = command.toJSON();
-const deserializedCommand = new A_Command(serialized);
+A_Context.root.register(UserProcessor);
+A_Context.root.register(command);
+await command.execute();
 ```
 
-**Features:**
-- Command execution with lifecycle management
-- Status tracking (INITIALIZED, PROCESSING, COMPLETED, FAILED)
-- Built-in timing and duration tracking
-- JSON serialization/deserialization
+**Key Features:**
+- ✅ **Complete Lifecycle Management** - Automatic progression through init → compile → execute → complete/fail
+- ✅ **Event-Driven Architecture** - Subscribe to lifecycle events and custom events  
+- ✅ **State Persistence** - Full serialization/deserialization support
+- ✅ **Type Safety** - Full TypeScript support with generic types
+- ✅ **Error Handling** - Comprehensive error capture and management
+- ✅ **Execution Tracking** - Built-in timing and duration tracking
+- ✅ **Component Integration** - Extensible through A-Component architecture
 - Scope integration with dependency injection
 - Memory management integration
 
@@ -284,13 +312,15 @@ const manifest = new A_Manifest([
 
 ### A-Memory
 
-A type-safe memory management system for storing intermediate values and tracking errors during complex operations.
+A type-safe memory management system for storing intermediate values and tracking errors during complex operations. Fully integrated with A-Command for state management.
+
+> 💡 **Note:** A-Memory is automatically used by A-Command for result and error storage. See [A-Command Documentation](./src/lib/A-Command/README.md) for integration examples.
 
 **Basic Usage:**
 ```typescript
 import { A_Memory } from '@adaas/a-utils';
 
-// Create memory instance
+// Create typed memory instance
 const memory = new A_Memory<{
     userId: string;
     userData: any;
@@ -299,16 +329,19 @@ const memory = new A_Memory<{
     userId: '12345'
 });
 
-// Store values
-memory.set('userData', { name: 'John', email: 'john@example.com' });
-memory.set('processedData', processUserData(memory.get('userData')));
+// Store and retrieve values
+await memory.set('userData', { name: 'John', email: 'john@example.com' });
+await memory.set('processedData', processUserData(memory.get('userData')));
+
+// Access values with type safety
+const userId = memory.get('userId'); // string | undefined
+const userData = memory.get('userData'); // any | undefined
 
 // Check prerequisites
 const hasRequired = await memory.verifyPrerequisites(['userId', 'userData']);
 console.log(hasRequired); // true
 
-// Access values
-const userId = memory.get('userId');
+// Serialize all data
 const allData = memory.toJSON();
 ```
 
@@ -318,20 +351,42 @@ import { A_Error } from '@adaas/a-concept';
 
 const memory = new A_Memory();
 
-// Errors are automatically tracked
+// Add errors during processing
 try {
     // Some operation that might fail
-    throw new A_Error('Something went wrong');
+    throw new Error('Something went wrong');
 } catch (error) {
-    memory.addError(error);
+    await memory.error(new A_Error({ 
+        title: 'Operation Failed',
+        message: error.message 
+    }));
 }
 
 // Check for errors
 if (memory.Errors) {
-    console.log('Errors occurred:', memory.Errors);
+    console.log('Errors occurred:', Array.from(memory.Errors));
 }
 ```
 
+**Integration with A-Command:**
+```typescript
+// A-Memory is automatically used by A-Command
+class DataProcessor extends A_Component {
+    @A_Feature.Extend({ scope: [MyCommand] })
+    async execute(@A_Inject(A_Memory) memory: A_Memory<ResultType>) {
+        // Store intermediate results
+        await memory.set('step1', 'completed');
+        await memory.set('step2', { data: 'processed' });
+        
+        // Access stored values
+        const step1Result = memory.get('step1');
+        
+        // Results automatically become command.result
+    }
+}
+```
+```
+
 **Features:**
 - Type-safe value storage
 - Prerequisite verification

package/dist/index.d.mts

@@ -33,7 +33,11 @@ declare enum A_TYPES__CommandMetaKey {
     ABSTRACTIONS = "a-command-abstractions"
 }
 declare enum A_CONSTANTS__A_Command_Status {
+    CREATED = "CREATED",
+    INITIALIZATION = "INITIALIZATION",
     INITIALIZED = "INITIALIZED",
+    COMPILATION = "COMPILATION",
+    COMPILED = "COMPILED",
     IN_PROGRESS = "IN_PROGRESS",
     COMPLETED = "COMPLETED",
     FAILED = "FAILED"
@@ -58,11 +62,11 @@ type A_TYPES__Command_Constructor<T = A_Command> = new (...args: any[]) => T;
 /**
  * Command initialization type
  */
-type A_TYPES__Command_Init = any;
+type A_TYPES__Command_Init = Record<string, any>;
 /**
  * Command serialized type
  */
-type A_TYPES__Command_Serialized<ResultType extends Record<string, any> = Record<string, any>> = {
+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
      */
@@ -71,6 +75,10 @@ type A_TYPES__Command_Serialized<ResultType extends Record<string, any> = Record
      * 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
      */
@@ -121,7 +129,7 @@ type A_TYPES__CommandMeta = {
     }>;
 };
 
-declare 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>> {
+declare 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 = A_CONSTANTS__A_Command_Event> extends A_Entity<InvokeType, A_TYPES__Command_Serialized<InvokeType, ResultType>> {
     /**
      * Command Identifier that corresponds to the class name
      */
@@ -195,9 +203,15 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
     /**
      * Command invocation parameters
      */
-    params: InvokeType | A_TYPES__Command_Serialized<ResultType> | string);
+    params: InvokeType | A_TYPES__Command_Serialized<InvokeType, ResultType> | string);
     init(): Promise<void>;
     compile(): Promise<void>;
+    /**
+     * Processes the command execution
+     *
+     * @returns
+     */
+    process(): Promise<void>;
     /**
      * Executes the command logic.
      */
@@ -243,16 +257,18 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
      *
      * @param serialized
      */
-    fromJSON(serialized: A_TYPES__Command_Serialized<ResultType>): void;
+    fromJSON(serialized: A_TYPES__Command_Serialized<InvokeType, ResultType>): void;
     /**
      * Converts the Command instance to a plain object
      *
      * @returns
      */
-    toJSON(): A_TYPES__Command_Serialized<ResultType>;
+    toJSON(): A_TYPES__Command_Serialized<InvokeType, ResultType>;
+    protected checkScopeInheritance(): void;
 }
 
 declare class A_CommandError extends A_Error {
+    static readonly CommandScopeBindingError = "A-Command Scope Binding Error";
 }
 
 interface Ifspolyfill {
@@ -768,6 +784,17 @@ declare class A_Memory<_MemoryType extends Record<string, any> = Record<string,
      * @param error
      */
     error(error: A_Error): Promise<void>;
+    /**
+     * Retrieves a value from the context memory
+     *
+     * @param key
+     * @returns
+     */
+    get<K extends keyof _MemoryType>(
+    /**
+     * Key to retrieve the value for
+     */
+    key: K): _MemoryType[K] | undefined;
     /**
      * Saves a value in the context memory
      *

package/dist/index.d.ts

@@ -33,7 +33,11 @@ declare enum A_TYPES__CommandMetaKey {
     ABSTRACTIONS = "a-command-abstractions"
 }
 declare enum A_CONSTANTS__A_Command_Status {
+    CREATED = "CREATED",
+    INITIALIZATION = "INITIALIZATION",
     INITIALIZED = "INITIALIZED",
+    COMPILATION = "COMPILATION",
+    COMPILED = "COMPILED",
     IN_PROGRESS = "IN_PROGRESS",
     COMPLETED = "COMPLETED",
     FAILED = "FAILED"
@@ -58,11 +62,11 @@ type A_TYPES__Command_Constructor<T = A_Command> = new (...args: any[]) => T;
 /**
  * Command initialization type
  */
-type A_TYPES__Command_Init = any;
+type A_TYPES__Command_Init = Record<string, any>;
 /**
  * Command serialized type
  */
-type A_TYPES__Command_Serialized<ResultType extends Record<string, any> = Record<string, any>> = {
+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
      */
@@ -71,6 +75,10 @@ type A_TYPES__Command_Serialized<ResultType extends Record<string, any> = Record
      * 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
      */
@@ -121,7 +129,7 @@ type A_TYPES__CommandMeta = {
     }>;
 };
 
-declare 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>> {
+declare 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 = A_CONSTANTS__A_Command_Event> extends A_Entity<InvokeType, A_TYPES__Command_Serialized<InvokeType, ResultType>> {
     /**
      * Command Identifier that corresponds to the class name
      */
@@ -195,9 +203,15 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
     /**
      * Command invocation parameters
      */
-    params: InvokeType | A_TYPES__Command_Serialized<ResultType> | string);
+    params: InvokeType | A_TYPES__Command_Serialized<InvokeType, ResultType> | string);
     init(): Promise<void>;
     compile(): Promise<void>;
+    /**
+     * Processes the command execution
+     *
+     * @returns
+     */
+    process(): Promise<void>;
     /**
      * Executes the command logic.
      */
@@ -243,16 +257,18 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
      *
      * @param serialized
      */
-    fromJSON(serialized: A_TYPES__Command_Serialized<ResultType>): void;
+    fromJSON(serialized: A_TYPES__Command_Serialized<InvokeType, ResultType>): void;
     /**
      * Converts the Command instance to a plain object
      *
      * @returns
      */
-    toJSON(): A_TYPES__Command_Serialized<ResultType>;
+    toJSON(): A_TYPES__Command_Serialized<InvokeType, ResultType>;
+    protected checkScopeInheritance(): void;
 }
 
 declare class A_CommandError extends A_Error {
+    static readonly CommandScopeBindingError = "A-Command Scope Binding Error";
 }
 
 interface Ifspolyfill {
@@ -768,6 +784,17 @@ declare class A_Memory<_MemoryType extends Record<string, any> = Record<string,
      * @param error
      */
     error(error: A_Error): Promise<void>;
+    /**
+     * Retrieves a value from the context memory
+     *
+     * @param key
+     * @returns
+     */
+    get<K extends keyof _MemoryType>(
+    /**
+     * Key to retrieve the value for
+     */
+    key: K): _MemoryType[K] | undefined;
     /**
      * Saves a value in the context memory
      *

package/dist/index.js

@@ -92,7 +92,11 @@ var A_TYPES__CommandMetaKey = /* @__PURE__ */ ((A_TYPES__CommandMetaKey2) => {
   return A_TYPES__CommandMetaKey2;
 })(A_TYPES__CommandMetaKey || {});
 var A_CONSTANTS__A_Command_Status = /* @__PURE__ */ ((A_CONSTANTS__A_Command_Status2) => {
+  A_CONSTANTS__A_Command_Status2["CREATED"] = "CREATED";
+  A_CONSTANTS__A_Command_Status2["INITIALIZATION"] = "INITIALIZATION";
   A_CONSTANTS__A_Command_Status2["INITIALIZED"] = "INITIALIZED";
+  A_CONSTANTS__A_Command_Status2["COMPILATION"] = "COMPILATION";
+  A_CONSTANTS__A_Command_Status2["COMPILED"] = "COMPILED";
   A_CONSTANTS__A_Command_Status2["IN_PROGRESS"] = "IN_PROGRESS";
   A_CONSTANTS__A_Command_Status2["COMPLETED"] = "COMPLETED";
   A_CONSTANTS__A_Command_Status2["FAILED"] = "FAILED";
@@ -137,6 +141,15 @@ var A_Memory = class extends aConcept.A_Fragment {
   async error(error) {
     this._errors.add(error);
   }
+  /**
+   * Retrieves a value from the context memory
+   * 
+   * @param key 
+   * @returns 
+   */
+  get(key) {
+    return this._memory.get(key);
+  }
   /**
    * Saves a value in the context memory
    * 
@@ -175,6 +188,9 @@ var A_Memory = class extends aConcept.A_Fragment {
     return obj;
   }
 };
+var A_CommandError = class extends aConcept.A_Error {
+};
+A_CommandError.CommandScopeBindingError = "A-Command Scope Binding Error";
 
 // src/lib/A-Command/A-Command.entity.ts
 var A_Command = class extends aConcept.A_Entity {
@@ -275,28 +291,49 @@ var A_Command = class extends aConcept.A_Entity {
   // --------------------------------------------------------------------------
   // should create a new Task in DB  with basic records
   async init() {
-    this._status = "IN_PROGRESS" /* IN_PROGRESS */;
-    this._startTime = /* @__PURE__ */ new Date();
-    if (!this.scope.isInheritedFrom(aConcept.A_Context.scope(this))) {
-      this.scope.inherit(aConcept.A_Context.scope(this));
+    if (this._status !== "CREATED" /* CREATED */) {
+      return;
     }
+    this._status = "INITIALIZATION" /* INITIALIZATION */;
+    this._startTime = /* @__PURE__ */ new Date();
+    this.checkScopeInheritance();
     this.emit("init");
-    return await this.call("init", this.scope);
+    await this.call("init", this.scope);
+    this._status = "INITIALIZED" /* INITIALIZED */;
   }
   // Should compile everything before execution
   async compile() {
+    if (this._status !== "INITIALIZED" /* INITIALIZED */) {
+      return;
+    }
+    this.checkScopeInheritance();
+    this._status = "COMPILATION" /* COMPILATION */;
     this.emit("compile");
-    return await this.call("compile", this.scope);
+    await this.call("compile", this.scope);
+    this._status = "COMPILED" /* COMPILED */;
+  }
+  /**
+   * Processes the command execution
+   * 
+   * @returns 
+   */
+  async process() {
+    if (this._status !== "COMPILED" /* COMPILED */)
+      return;
+    this._status = "IN_PROGRESS" /* IN_PROGRESS */;
+    this.checkScopeInheritance();
+    this.emit("execute");
+    await this.call("execute", this.scope);
   }
   /**
    * Executes the command logic.
    */
   async execute() {
+    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) {
       await this.fail();
@@ -306,6 +343,7 @@ var A_Command = class extends aConcept.A_Entity {
    * Marks the command as completed
    */
   async complete() {
+    this.checkScopeInheritance();
     this._status = "COMPLETED" /* COMPLETED */;
     this._endTime = /* @__PURE__ */ new Date();
     this._result = this.scope.resolve(A_Memory).toJSON();
@@ -316,6 +354,7 @@ var A_Command = class extends aConcept.A_Entity {
    * Marks the command as failed
    */
   async fail() {
+    this.checkScopeInheritance();
     this._status = "FAILED" /* FAILED */;
     this._endTime = /* @__PURE__ */ new Date();
     this._errors = this.scope.resolve(A_Memory).Errors;
@@ -371,7 +410,7 @@ var A_Command = class extends aConcept.A_Entity {
     this._executionScope = new aConcept.A_Scope();
     this._executionScope.register(new A_Memory());
     this._params = newEntity;
-    this._status = "INITIALIZED" /* INITIALIZED */;
+    this._status = "CREATED" /* CREATED */;
   }
   /**
    * Allows to convert serialized data to Command instance
@@ -397,7 +436,8 @@ var A_Command = class extends aConcept.A_Entity {
         memory.error(new aConcept.A_Error(err));
       });
     }
-    this._status = serialized.status || "INITIALIZED" /* INITIALIZED */;
+    this._params = serialized.params;
+    this._status = serialized.status || "CREATED" /* CREATED */;
   }
   /**
    * Converts the Command instance to a plain object
@@ -409,6 +449,7 @@ var A_Command = class extends aConcept.A_Entity {
       ...super.toJSON(),
       code: this.code,
       status: this._status,
+      params: this._params,
       startedAt: this._startTime ? this._startTime.toISOString() : void 0,
       endedAt: this._endTime ? this._endTime.toISOString() : void 0,
       duration: this.duration,
@@ -416,8 +457,21 @@ var A_Command = class extends aConcept.A_Entity {
       errors: this.errors ? Array.from(this.errors).map((err) => err.toJSON()) : void 0
     };
   }
-};
-var A_CommandError = class extends aConcept.A_Error {
+  checkScopeInheritance() {
+    let attachedScope;
+    try {
+      attachedScope = aConcept.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(aConcept.A_Context.scope(this))) {
+      this.scope.inherit(aConcept.A_Context.scope(this));
+    }
+  }
 };
 
 // src/lib/A-Config/A-Config.constants.ts