@adaas/a-utils 0.1.12 → 0.1.14

package/dist/index.d.ts

@@ -1,30 +1,443 @@
-import { A_Component, A_Error, A_TYPES__Error_Serialized, A_TYPES__Entity_Serialized, A_Meta, A_TYPES__FeatureExtendDecoratorMeta, A_TYPES__FeatureDefineDecoratorMeta, A_Entity, A_Scope, A_TYPES__ConceptENVVariables, A_TYPES__Fragment_Constructor, A_Fragment, A_Container, A_Feature, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor } from '@adaas/a-concept';
+import { A_Fragment, A_Error, A_Component, A_TYPES__Error_Serialized, A_TYPES__Entity_Serialized, A_Meta, A_TYPES__FeatureExtendDecoratorMeta, A_TYPES__FeatureDefineDecoratorMeta, A_Entity, A_Scope, A_TYPES__ConceptENVVariables, A_TYPES__Fragment_Constructor, A_Container, A_Feature, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor } from '@adaas/a-concept';
 import { A_TYPES__Container_Constructor } from '@adaas/a-concept/dist/src/global/A-Container/A-Container.types';
 
+declare enum A_ChannelRequestStatuses {
+    /**
+     * Request is pending
+     */
+    PENDING = "PENDING",
+    /***
+     * Request was successful
+     */
+    SUCCESS = "SUCCESS",
+    /**
+     * Request failed
+     */
+    FAILED = "FAILED"
+}
+
+type A_ChannelRequestContext_Serialized<_ParamsType extends Record<string, any> = Record<string, any>, _ResultType extends Record<string, any> = Record<string, any>> = {
+    params: _ParamsType;
+    result?: _ResultType;
+    status: string;
+    errors?: string[];
+};
+
+declare class A_ChannelRequestContext<_ParamsType extends Record<string, any> = Record<string, any>, _ResultType extends Record<string, any> = Record<string, any>> extends A_Fragment {
+    protected _params: _ParamsType;
+    protected _result?: _ResultType;
+    protected _errors: Set<Error>;
+    protected _status: A_ChannelRequestStatuses;
+    constructor(params?: Partial<_ParamsType>);
+    /**
+     * Returns the status of the request
+     */
+    get status(): A_ChannelRequestStatuses;
+    /**
+     * Returns the parameters of the request
+     */
+    get failed(): boolean;
+    /**
+     * Returns the Params of the Request
+     */
+    get params(): _ParamsType;
+    /**
+     * Returns the Result of the Request
+     */
+    get data(): _ResultType | undefined;
+    get errors(): Set<Error> | undefined;
+    /**
+     * Adds an error to the context
+     *
+     * @param error
+     */
+    fail(error: A_Error): void;
+    /**
+     * Sets the result of the request
+     *
+     * @param result
+     */
+    succeed(result: _ResultType): void;
+    /**
+     * Serializes the context to a JSON object
+     *
+     * @returns
+     */
+    toJSON(): A_ChannelRequestContext_Serialized<_ParamsType, _ResultType>;
+}
+
+/**
+ * A-Channel - A powerful, extensible communication channel component
+ *
+ * A-Channel provides a structured approach to implementing various communication patterns
+ * such as HTTP clients, WebSocket connections, message queues, and other messaging systems.
+ * It offers a complete lifecycle management system with extensible hooks for custom behavior.
+ *
+ * ## Key Features:
+ * - 🔄 **Lifecycle Management** - Complete connection and processing lifecycle with hooks
+ * - 📡 **Multiple Communication Patterns** - Request/Response and Fire-and-Forget messaging
+ * - 🛡️ **Error Handling** - Comprehensive error capture and management
+ * - 🎯 **Type Safety** - Full TypeScript support with generic types
+ * - 🔧 **Extensible** - Component-based architecture for custom behavior
+ * - ⚡ **Concurrent Processing** - Handle multiple requests simultaneously
+ *
+ * ## Basic Usage:
+ * ```typescript
+ * const channel = new A_Channel();
+ * A_Context.root.register(channel);
+ *
+ * // Request/Response pattern
+ * const response = await channel.request({ action: 'getData', id: 123 });
+ *
+ * // Fire-and-forget pattern
+ * await channel.send({ type: 'notification', message: 'Hello World' });
+ * ```
+ *
+ * ## Custom Implementation:
+ * ```typescript
+ * class HttpChannel extends A_Channel {}
+ *
+ * class HttpProcessor extends A_Component {
+ *     @A_Feature.Extend({ scope: [HttpChannel] })
+ *     async [A_ChannelFeatures.onRequest](
+ *         @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+ *     ) {
+ *         const response = await fetch(context.params.url);
+ *         (context as any)._result = await response.json();
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ./README.md} For complete documentation and examples
+ */
 declare class A_Channel extends A_Component {
     /**
-     * Indicates whether the channel is processing requests
+     * Indicates whether the channel is currently processing requests.
+     * This flag is managed automatically during request/send operations.
+     *
+     * @readonly
      */
     protected _processing: boolean;
     /**
-     * Indicates whether the channel is connected
+     * Promise that resolves when the channel initialization is complete.
+     * Ensures that onConnect lifecycle hook has been executed before
+     * any communication operations.
+     *
+     * @private
      */
     protected _initialized?: Promise<void>;
     /**
-      * Indicates whether the channel is processing requests
-      */
+     * Internal cache storage for channel-specific data.
+     * Can be used by custom implementations for caching responses,
+     * connection pools, or other channel-specific state.
+     *
+     * @protected
+     */
+    protected _cache: Map<string, any>;
+    /**
+     * Creates a new A_Channel instance.
+     *
+     * The channel must be registered with A_Context before use:
+     * ```typescript
+     * const channel = new A_Channel();
+     * A_Context.root.register(channel);
+     * ```
+     */
+    constructor();
+    /**
+     * Indicates whether the channel is currently processing requests.
+     *
+     * @returns {boolean} True if channel is processing, false otherwise
+     */
     get processing(): boolean;
     /**
-     * Indicates whether the channel is connected
+     * Promise that resolves when the channel is fully initialized.
+     *
+     * Automatically calls the onConnect lifecycle hook if not already called.
+     * This ensures the channel is ready for communication operations.
+     *
+     * @returns {Promise<void>} Promise that resolves when initialization is complete
      */
     get initialize(): Promise<void>;
+    /**
+     * Connection lifecycle hook - called during channel initialization.
+     *
+     * Override this method in custom components to implement connection logic:
+     * - Initialize network connections
+     * - Load configuration
+     * - Validate environment
+     * - Set up connection pools
+     *
+     * @example
+     * ```typescript
+     * class DatabaseChannel extends A_Channel {}
+     *
+     * class DatabaseConnector extends A_Component {
+     *     @A_Feature.Extend({ scope: [DatabaseChannel] })
+     *     async [A_ChannelFeatures.onConnect]() {
+     *         await this.initializeDatabase();
+     *         console.log('Database channel connected');
+     *     }
+     * }
+     * ```
+     */
+    onConnect(...args: any[]): Promise<void>;
+    /**
+     * Disconnection lifecycle hook - called during channel cleanup.
+     *
+     * Override this method in custom components to implement cleanup logic:
+     * - Close network connections
+     * - Save state
+     * - Release resources
+     * - Clear caches
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [DatabaseChannel] })
+     * async [A_ChannelFeatures.onDisconnect]() {
+     *     await this.closeConnections();
+     *     console.log('Database channel disconnected');
+     * }
+     * ```
+     */
+    onDisconnect(...args: any[]): Promise<void>;
+    /**
+     * Pre-request processing hook - called before main request processing.
+     *
+     * Use this hook for:
+     * - Request validation
+     * - Authentication
+     * - Rate limiting
+     * - Logging
+     * - Request transformation
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [HttpChannel] })
+     * async [A_ChannelFeatures.onBeforeRequest](
+     *     @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+     * ) {
+     *     // Validate required parameters
+     *     if (!context.params.url) {
+     *         throw new Error('URL is required');
+     *     }
+     * }
+     * ```
+     */
+    onBeforeRequest(...args: any[]): Promise<void>;
+    /**
+     * Main request processing hook - core business logic goes here.
+     *
+     * This is where the main communication logic should be implemented:
+     * - Make HTTP requests
+     * - Send messages to queues
+     * - Execute database queries
+     * - Process business logic
+     *
+     * Set the result in the context: `(context as any)._result = yourResult;`
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [HttpChannel] })
+     * async [A_ChannelFeatures.onRequest](
+     *     @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+     * ) {
+     *     const response = await fetch(context.params.url);
+     *     (context as any)._result = await response.json();
+     * }
+     * ```
+     */
+    onRequest(...args: any[]): Promise<void>;
+    /**
+     * Post-request processing hook - called after successful request processing.
+     *
+     * Use this hook for:
+     * - Response transformation
+     * - Logging
+     * - Analytics
+     * - Caching results
+     * - Cleanup
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [HttpChannel] })
+     * async [A_ChannelFeatures.onAfterRequest](
+     *     @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+     * ) {
+     *     console.log(`Request completed in ${Date.now() - context.startTime}ms`);
+     *     await this.cacheResponse(context.params, context.data);
+     * }
+     * ```
+     */
+    onAfterRequest(...args: any[]): Promise<void>;
+    /**
+     * Error handling hook - called when any operation fails.
+     *
+     * Use this hook for:
+     * - Error logging
+     * - Error transformation
+     * - Alerting
+     * - Retry logic
+     * - Fallback mechanisms
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [HttpChannel] })
+     * async [A_ChannelFeatures.onError](
+     *     @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+     * ) {
+     *     console.error('Request failed:', context.params, context.failed);
+     *     await this.logError(context);
+     *     await this.sendAlert(context);
+     * }
+     * ```
+     */
+    onError(...args: any[]): Promise<void>;
+    /**
+     * Send operation hook - called for fire-and-forget messaging.
+     *
+     * Use this hook for:
+     * - Message broadcasting
+     * - Event publishing
+     * - Notification sending
+     * - Queue operations
+     *
+     * @example
+     * ```typescript
+     * @A_Feature.Extend({ scope: [EventChannel] })
+     * async [A_ChannelFeatures.onSend](
+     *     @A_Inject(A_ChannelRequestContext) context: A_ChannelRequestContext
+     * ) {
+     *     const { eventType, payload } = context.params;
+     *     await this.publishEvent(eventType, payload);
+     * }
+     * ```
+     */
+    onSend(...args: any[]): Promise<void>;
+    /**
+     * Initializes the channel by calling the onConnect lifecycle hook.
+     *
+     * This method is called automatically when accessing the `initialize` property.
+     * You can also call it manually if needed.
+     *
+     * @returns {Promise<void>} Promise that resolves when connection is established
+     */
     connect(): Promise<void>;
-    request(params: any): Promise<any>;
-    send(message: any): Promise<void>;
+    /**
+     * Disconnects the channel by calling the onDisconnect lifecycle hook.
+     *
+     * Use this method to properly cleanup resources when the channel is no longer needed.
+     *
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Sends a request and waits for a response (Request/Response pattern).
+     *
+     * This method follows the complete request lifecycle:
+     * 1. Ensures channel is initialized
+     * 2. Creates request scope and context
+     * 3. Calls onBeforeRequest hook
+     * 4. Calls onRequest hook (main processing)
+     * 5. Calls onAfterRequest hook
+     * 6. Returns the response context
+     *
+     * If any step fails, the onError hook is called and the error is captured
+     * in the returned context.
+     *
+     * @template _ParamsType The type of request parameters
+     * @template _ResultType The type of response data
+     * @param params The request parameters
+     * @returns {Promise<A_ChannelRequestContext<_ParamsType, _ResultType>>} Request context with response
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const response = await channel.request({ action: 'getData', id: 123 });
+     *
+     * // Typed usage
+     * interface UserRequest { userId: string; }
+     * interface UserResponse { name: string; email: string; }
+     *
+     * const userResponse = await channel.request<UserRequest, UserResponse>({
+     *     userId: 'user-123'
+     * });
+     *
+     * if (!userResponse.failed) {
+     *     console.log('User:', userResponse.data.name);
+     * }
+     * ```
+     */
+    request<_ParamsType extends Record<string, any> = Record<string, any>, _ResultType extends Record<string, any> = Record<string, any>>(params: _ParamsType): Promise<A_ChannelRequestContext<_ParamsType, _ResultType>>;
+    /**
+     * Sends a fire-and-forget message (Send pattern).
+     *
+     * This method is used for one-way communication where no response is expected:
+     * - Event broadcasting
+     * - Notification sending
+     * - Message queuing
+     * - Logging operations
+     *
+     * The method follows this lifecycle:
+     * 1. Ensures channel is initialized
+     * 2. Creates send scope and context
+     * 3. Calls onSend hook
+     * 4. Completes without returning data
+     *
+     * If the operation fails, the onError hook is called but no error is thrown
+     * to the caller (fire-and-forget semantics).
+     *
+     * @template _ParamsType The type of message parameters
+     * @param message The message to send
+     * @returns {Promise<void>} Promise that resolves when send is complete
+     *
+     * @example
+     * ```typescript
+     * // Send notification
+     * await channel.send({
+     *     type: 'user.login',
+     *     userId: 'user-123',
+     *     timestamp: new Date().toISOString()
+     * });
+     *
+     * // Send to message queue
+     * await channel.send({
+     *     queue: 'email-queue',
+     *     payload: {
+     *         to: 'user@example.com',
+     *         subject: 'Welcome!',
+     *         body: 'Welcome to our service!'
+     *     }
+     * });
+     * ```
+     */
+    send<_ParamsType extends Record<string, any> = Record<string, any>>(message: _ParamsType): Promise<void>;
+    /**
+     * @deprecated This method is deprecated and will be removed in future versions.
+     * Use request() or send() methods instead depending on your communication pattern.
+     *
+     * For request/response pattern: Use request()
+     * For fire-and-forget pattern: Use send()
+     * For consumer patterns: Implement custom consumer logic using request() in a loop
+     */
+    consume<T extends Record<string, any> = Record<string, any>>(): Promise<A_ChannelRequestContext<any, T>>;
 }
 
 declare class A_ChannelError extends A_Error {
     static readonly MethodNotImplemented = "A-Channel Method Not Implemented";
+    protected _context?: A_ChannelRequestContext;
+    /**
+     * Channel Error allows to keep track of errors within a channel if something goes wrong
+     *
+     *
+     * @param originalError
+     * @param context
+     */
+    constructor(originalError: string | A_Error | Error | any, context?: A_ChannelRequestContext | string);
+    /***
+     * Returns Context of the error
+     */
+    get context(): A_ChannelRequestContext | undefined;
 }
 
 declare enum A_TYPES__CommandMetaKey {
@@ -206,6 +619,12 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
     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.
      */
@@ -258,9 +677,11 @@ declare class A_Command<InvokeType extends A_TYPES__Command_Init = A_TYPES__Comm
      * @returns
      */
     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 {