@adaas/a-utils 0.2.8 → 0.3.1

package/dist/node/lib/A-Channel/A-Channel.component.d.ts

@@ -0,0 +1,365 @@
+import { A_Component } from '@adaas/a-concept';
+import { A_OperationContext } from '../A-Operation/A-Operation.context.js';
+import { A_ChannelRequest } from './A-ChannelRequest.context.js';
+import '../A-Operation/A-Operation.types.js';
+import '../A-Execution/A-Execution.context.js';
+import './A-Channel.constants.js';
+
+/**
+ * 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_ChannelRequest) context: A_ChannelRequest
+ *     ) {
+ *         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 currently processing requests.
+     * This flag is managed automatically during request/send operations.
+     *
+     * @readonly
+     */
+    protected _processing: boolean;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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_ChannelRequest) context: A_ChannelRequest
+     * ) {
+     *     // 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_ChannelRequest) context: A_ChannelRequest
+     * ) {
+     *     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_ChannelRequest) context: A_ChannelRequest
+     * ) {
+     *     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_ChannelRequest) context: A_ChannelRequest
+     * ) {
+     *     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_ChannelRequest) context: A_ChannelRequest
+     * ) {
+     *     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>;
+    /**
+     * 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_ChannelRequest<_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_ChannelRequest<_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_OperationContext<any, T>>;
+}
+
+export { A_Channel };

package/dist/node/lib/A-Channel/A-Channel.component.js

@@ -0,0 +1,303 @@
+'use strict';
+
+var aConcept = require('@adaas/a-concept');
+var AChannel_error = require('./A-Channel.error');
+var AChannel_constants = require('./A-Channel.constants');
+var aOperation = require('@adaas/a-utils/a-operation');
+var AChannelRequest_context = require('./A-ChannelRequest.context');
+var aFrame = require('@adaas/a-frame');
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+exports.A_Channel = class A_Channel extends aConcept.A_Component {
+  /**
+   * 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() {
+    super();
+    /**
+     * Indicates whether the channel is currently processing requests.
+     * This flag is managed automatically during request/send operations.
+     * 
+     * @readonly
+     */
+    this._processing = false;
+    /**
+     * Internal cache storage for channel-specific data.
+     * Can be used by custom implementations for caching responses,
+     * connection pools, or other channel-specific state.
+     * 
+     * @protected
+     */
+    this._cache = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Indicates whether the channel is currently processing requests.
+   * 
+   * @returns {boolean} True if channel is processing, false otherwise
+   */
+  get processing() {
+    return this._processing;
+  }
+  /**
+   * 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() {
+    if (!this._initialized) {
+      this._initialized = this.connect();
+    }
+    return this._initialized;
+  }
+  async onConnect(...args) {
+  }
+  async onDisconnect(...args) {
+  }
+  async onBeforeRequest(...args) {
+  }
+  async onRequest(...args) {
+  }
+  async onAfterRequest(...args) {
+  }
+  async onError(...args) {
+  }
+  async onSend(...args) {
+  }
+  // ==========================================================
+  // ================= Public API Methods ===================
+  // ==========================================================
+  /**
+   * 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
+   */
+  async connect() {
+    await this.call(AChannel_constants.A_ChannelFeatures.onConnect);
+  }
+  /**
+   * 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
+   */
+  async disconnect() {
+    await this.call(AChannel_constants.A_ChannelFeatures.onDisconnect);
+  }
+  /**
+   * 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_ChannelRequest<_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);
+   * }
+   * ```
+   */
+  async request(params) {
+    await this.initialize;
+    this._processing = true;
+    const requestScope = new aConcept.A_Scope({
+      name: `a-channel@scope:request:${aConcept.A_IdentityHelper.generateTimeId()}`
+    }).inherit(aConcept.A_Context.scope(this));
+    const context = new AChannelRequest_context.A_ChannelRequest(params);
+    try {
+      requestScope.register(context);
+      await this.call(AChannel_constants.A_ChannelFeatures.onBeforeRequest, requestScope);
+      await this.call(AChannel_constants.A_ChannelFeatures.onRequest, requestScope);
+      await this.call(AChannel_constants.A_ChannelFeatures.onAfterRequest, requestScope);
+      this._processing = false;
+      return context;
+    } catch (error) {
+      this._processing = false;
+      const channelError = new AChannel_error.A_ChannelError(error);
+      context.fail(channelError);
+      requestScope.register(channelError);
+      await this.call(AChannel_constants.A_ChannelFeatures.onError, requestScope);
+      requestScope.destroy();
+      throw channelError;
+    }
+  }
+  /**
+   * 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!'
+   *     }
+   * });
+   * ```
+   */
+  async send(message) {
+    await this.initialize;
+    this._processing = true;
+    const requestScope = new aConcept.A_Scope({
+      name: `a-channel@scope:send:${aConcept.A_IdentityHelper.generateTimeId()}`
+    }).inherit(aConcept.A_Context.scope(this));
+    const context = new aOperation.A_OperationContext("send", message);
+    try {
+      requestScope.inherit(aConcept.A_Context.scope(this));
+      requestScope.register(context);
+      await this.call(AChannel_constants.A_ChannelFeatures.onSend, requestScope);
+      this._processing = false;
+    } catch (error) {
+      this._processing = false;
+      const channelError = new AChannel_error.A_ChannelError(error);
+      requestScope.register(channelError);
+      context.fail(channelError);
+      await this.call(AChannel_constants.A_ChannelFeatures.onError, requestScope);
+      requestScope.destroy();
+    }
+  }
+  /**
+   * @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
+   */
+  async consume() {
+    await this.initialize;
+    this._processing = true;
+    const requestScope = new aConcept.A_Scope({ name: `a-channel@scope:consume:${aConcept.A_IdentityHelper.generateTimeId()}` }).inherit(aConcept.A_Context.scope(this));
+    const context = new aOperation.A_OperationContext("consume", {});
+    try {
+      requestScope.inherit(aConcept.A_Context.scope(this));
+      requestScope.register(context);
+      await this.call(AChannel_constants.A_ChannelFeatures.onConsume, requestScope);
+      this._processing = false;
+      return context;
+    } catch (error) {
+      this._processing = false;
+      const channelError = new AChannel_error.A_ChannelError(error);
+      context.fail(channelError);
+      await this.call(AChannel_constants.A_ChannelFeatures.onError, requestScope);
+      return context;
+    }
+  }
+};
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onConnect
+  })
+], exports.A_Channel.prototype, "onConnect", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onDisconnect
+  })
+], exports.A_Channel.prototype, "onDisconnect", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onBeforeRequest
+  })
+], exports.A_Channel.prototype, "onBeforeRequest", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onRequest
+  })
+], exports.A_Channel.prototype, "onRequest", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onAfterRequest
+  })
+], exports.A_Channel.prototype, "onAfterRequest", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onError
+  })
+], exports.A_Channel.prototype, "onError", 1);
+__decorateClass([
+  aConcept.A_Feature.Extend({
+    name: AChannel_constants.A_ChannelFeatures.onSend
+  })
+], exports.A_Channel.prototype, "onSend", 1);
+exports.A_Channel = __decorateClass([
+  aFrame.A_Frame.Namespace("A-Utils"),
+  aFrame.A_Frame.Component({
+    name: "A-Channel",
+    description: "Component uses as abstract channel for communication patterns. Can be inherited and extended to implement custom channels."
+  })
+], exports.A_Channel);
+//# sourceMappingURL=A-Channel.component.js.map
+//# sourceMappingURL=A-Channel.component.js.map