@adaas/a-utils 0.2.8 → 0.3.1

package/dist/browser/A-StateMachineTransition.context-BINjcsgq.d.mts

@@ -0,0 +1,221 @@
+import { A_Component } from '@adaas/a-concept';
+import { A_Operation_Storage, A_OperationContext } from './a-operation.mjs';
+
+declare enum A_StateMachineFeatures {
+    /**
+     * Allows to extend error handling logic and behavior
+     */
+    onError = "_A_StateMachine_onError",
+    /**
+     * Allows to extend initialization logic and behavior
+     */
+    onInitialize = "_A_StateMachine_onInitialize",
+    /**
+     * Allows to extend transition validation logic and behavior
+     */
+    onBeforeTransition = "_A_StateMachine_onBeforeTransition",
+    /**
+     * Allows to extend post-transition logic and behavior
+     */
+    onAfterTransition = "_A_StateMachine_onAfterTransition"
+}
+
+/**
+ * A_StateMachine is a powerful state machine implementation that allows you to define and manage
+ * complex state transitions with validation, hooks, and error handling.
+ *
+ * @template T - A record type defining the state transitions and their associated data types.
+ *               Each key represents a state name, and the value represents the data type for that state.
+ *
+ * @example
+ * ```typescript
+ * interface OrderStates {
+ *   pending: { orderId: string };
+ *   processing: { orderId: string; processedBy: string };
+ *   completed: { orderId: string; completedAt: Date };
+ *   cancelled: { orderId: string; reason: string };
+ * }
+ *
+ * class OrderStateMachine extends A_StateMachine<OrderStates> {
+ *   // Define custom transition logic
+ *   async pending_processing(scope: A_Scope) {
+ *     const operation = scope.resolve(A_StateMachineTransition)!;
+ *     const { orderId } = operation.props;
+ *     // Custom validation and business logic
+ *   }
+ * }
+ * ```
+ */
+declare class A_StateMachine<T extends Record<string, any> = Record<string, any>> extends A_Component {
+    /**
+     * Internal promise that tracks the initialization state of the state machine.
+     * Used to ensure the state machine is properly initialized before allowing transitions.
+     */
+    protected _initialized?: Promise<void>;
+    /**
+     * Gets a promise that resolves when the state machine is fully initialized and ready for transitions.
+     * This ensures that all initialization hooks have been executed before allowing state transitions.
+     *
+     * @returns Promise<void> that resolves when initialization is complete
+     *
+     * @example
+     * ```typescript
+     * const stateMachine = new MyStateMachine();
+     * await stateMachine.ready; // Wait for initialization
+     * await stateMachine.transition('idle', 'running');
+     * ```
+     */
+    get ready(): Promise<void>;
+    /**
+     * Initialization hook that runs when the state machine is first created.
+     * This method can be extended to add custom initialization logic.
+     *
+     * @param args - Variable arguments passed during initialization
+     * @returns Promise<void>
+     *
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onInitialize]() {
+     *     // Custom initialization logic
+     *     console.log('State machine initialized');
+     *   }
+     * }
+     * ```
+     */
+    [A_StateMachineFeatures.onInitialize](...args: any[]): Promise<void>;
+    /**
+     * Hook that runs before any state transition occurs.
+     * Use this to add validation, logging, or preparation logic that should run for all transitions.
+     *
+     * @param args - Variable arguments, typically includes the transition scope
+     * @returns Promise<void>
+     *
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onBeforeTransition](scope: A_Scope) {
+     *     const operation = scope.resolve(A_StateMachineTransition)!;
+     *     console.log(`Transitioning from ${operation.props.from} to ${operation.props.to}`);
+     *   }
+     * }
+     * ```
+     */
+    [A_StateMachineFeatures.onBeforeTransition](...args: any[]): Promise<void>;
+    /**
+     * Hook that runs after a successful state transition.
+     * Use this to add cleanup, logging, or post-transition logic that should run for all transitions.
+     *
+     * @param args - Variable arguments, typically includes the transition scope
+     * @returns Promise<void>
+     *
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onAfterTransition](scope: A_Scope) {
+     *     const operation = scope.resolve(A_StateMachineTransition)!;
+     *     console.log(`Successfully transitioned to ${operation.props.to}`);
+     *   }
+     * }
+     * ```
+     */
+    [A_StateMachineFeatures.onAfterTransition](...args: any[]): Promise<void>;
+    /**
+     * Error handling hook that runs when a transition fails.
+     * Use this to add custom error handling, logging, or recovery logic.
+     *
+     * @param args - Variable arguments, typically includes the error scope
+     * @returns Promise<void>
+     *
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onError](scope: A_Scope) {
+     *     const error = scope.resolve(A_StateMachineError);
+     *     console.error('Transition failed:', error?.message);
+     *   }
+     * }
+     * ```
+     */
+    [A_StateMachineFeatures.onError](...args: any[]): Promise<void>;
+    /**
+     * Executes a state transition from one state to another.
+     * This is the core method of the state machine that handles the complete transition lifecycle.
+     *
+     * @param from - The state to transition from (must be a key of T)
+     * @param to - The state to transition to (must be a key of T)
+     * @param props - Optional properties to pass to the transition context (should match T[keyof T])
+     * @returns Promise<void> that resolves when the transition is complete
+     *
+     * @throws {A_StateMachineError} When the transition fails for any reason
+     *
+     * @example
+     * ```typescript
+     * interface OrderStates {
+     *   pending: { orderId: string };
+     *   processing: { orderId: string; processedBy: string };
+     * }
+     *
+     * const orderMachine = new A_StateMachine<OrderStates>();
+     *
+     * // Transition with props
+     * await orderMachine.transition('pending', 'processing', {
+     *   orderId: '12345',
+     *   processedBy: 'user-456'
+     * });
+     * ```
+     *
+     * The transition process follows this lifecycle:
+     * 1. Wait for state machine initialization (ready)
+     * 2. Create transition name in camelCase format (e.g., "pending_processing")
+     * 3. Create operation context with transition data
+     * 4. Create isolated scope for the transition
+     * 5. Call onBeforeTransition hook
+     * 6. Execute the specific transition method (if defined)
+     * 7. Call onAfterTransition hook
+     * 8. Clean up scope and return result
+     *
+     * If any step fails, the onError hook is called and a wrapped error is thrown.
+     */
+    transition(
+    /**
+     * The state to transition from
+     */
+    from: keyof T, 
+    /**
+     * The state to transition to
+     */
+    to: keyof T, 
+    /**
+     * Optional properties to pass to the transition context
+     */
+    props?: T[keyof T]): Promise<void>;
+}
+
+type A_StateMachineTransitionParams<T = any> = {
+    from: string;
+    to: string;
+    props?: T;
+};
+type A_StateMachineTransitionStorage<_ResultType extends any = any, _ParamsType extends any = any> = {
+    from: string;
+    to: string;
+} & A_Operation_Storage<_ResultType, A_StateMachineTransitionParams<_ParamsType>>;
+
+declare class A_StateMachineTransition<_ParamsType = any, _ResultType = any> extends A_OperationContext<'a-state-machine-transition', A_StateMachineTransitionParams<_ParamsType>, _ResultType, A_StateMachineTransitionStorage<_ResultType, _ParamsType>> {
+    constructor(params: A_StateMachineTransitionParams<_ParamsType>);
+    /**
+     * The state to transition from
+     */
+    get from(): string;
+    /**
+     * The state to transition to
+     */
+    get to(): string;
+}
+
+export { A_StateMachine as A, A_StateMachineFeatures as a, A_StateMachineTransition as b, type A_StateMachineTransitionParams as c, type A_StateMachineTransitionStorage as d };

package/dist/browser/a-channel.d.mts

@@ -0,0 +1,456 @@
+import { A_Component, A_Error } from '@adaas/a-concept';
+import { A_OperationContext } from './a-operation.mjs';
+import './a-execution.mjs';
+
+declare enum A_ChannelFeatures {
+    /**
+     * Allows to extend timeout logic and behavior
+     */
+    onTimeout = "_A_Channel_onTimeout",
+    /**
+     * Allows to extend retry logic and behavior
+     */
+    onRetry = "_A_Channel_onRetry",
+    /**
+     * Allows to extend circuit breaker logic and behavior
+     */
+    onCircuitBreakerOpen = "_A_Channel_onCircuitBreakerOpen",
+    /**
+     * Allows to extend cache logic and behavior
+     */
+    onCache = "_A_Channel_onCache",
+    /**
+     * Allows to extend connection logic and behavior
+     */
+    onConnect = "_A_Channel_onConnect",
+    /**
+     * Allows to extend disconnection logic and behavior
+     */
+    onDisconnect = "_A_Channel_onDisconnect",
+    /**
+     * Allows to extend request preparation logic and behavior
+     */
+    onBeforeRequest = "_A_Channel_onBeforeRequest",
+    /**
+     * Allows to extend request sending logic and behavior
+     */
+    onRequest = "_A_Channel_onRequest",
+    /**
+     * Allows to extend request post-processing logic and behavior
+     */
+    onAfterRequest = "_A_Channel_onAfterRequest",
+    /**
+     * Allows to extend error handling logic and behavior
+     *
+     * [!] The same approach uses for ALL errors within the channel
+     */
+    onError = "_A_Channel_onError",
+    /**
+     * Allows to extend send logic and behavior
+     */
+    onSend = "_A_Channel_onSend",
+    /**
+     * Allows to extend consume logic and behavior
+     */
+    onConsume = "_A_Channel_onConsume"
+}
+declare enum A_ChannelRequestStatuses {
+    /**
+     * Request is pending
+     */
+    PENDING = "PENDING",
+    /***
+     * Request was successful
+     */
+    SUCCESS = "SUCCESS",
+    /**
+     * Request failed
+     */
+    FAILED = "FAILED"
+}
+
+declare class A_ChannelRequest<_ParamsType extends Record<string, any> = Record<string, any>, _ResultType extends Record<string, any> = Record<string, any>> extends A_OperationContext<'request', _ParamsType, {
+    data?: _ResultType;
+    status?: A_ChannelRequestStatuses;
+}> {
+    constructor(params?: _ParamsType);
+    get status(): A_ChannelRequestStatuses | undefined;
+    get data(): _ResultType | undefined;
+    succeed(result: _ResultType): void;
+}
+
+/**
+ * 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>>;
+}
+
+declare class A_ChannelError extends A_Error {
+    static readonly MethodNotImplemented = "A-Channel Method Not Implemented";
+    protected _context?: A_OperationContext;
+    /**
+     * 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_OperationContext | string);
+    /***
+     * Returns Context of the error
+     */
+    get context(): A_OperationContext | undefined;
+}
+
+export { A_Channel, A_ChannelError, A_ChannelFeatures, A_ChannelRequest, A_ChannelRequestStatuses };