@olane/o-node 0.7.12-alpha.39 → 0.7.12-alpha.40

package/dist/o-core/src/core/o-core.d.ts

@@ -0,0 +1,240 @@
+import { oCoreConfig } from './interfaces/o-core.config.js';
+import { NodeState } from './interfaces/state.enum.js';
+import { oAddress } from '../router/o-address.js';
+import { NodeType } from './interfaces/node-type.enum.js';
+import { oConnectionManager } from '../connection/o-connection-manager.js';
+import { oResponse } from '../connection/o-response.js';
+import { oConnection } from '../connection/o-connection.js';
+import { oMethod } from '@olane/o-protocol';
+import { oDependency } from './o-dependency.js';
+import { oObject } from './o-object.js';
+import { oMetrics } from './lib/o-metrics.js';
+import { oHierarchyManager } from './lib/o-hierarchy.manager.js';
+import { oRequestManager } from './lib/o-request.manager.js';
+import { oTransport } from '../transports/o-transport.js';
+import { oRouter } from '../router/o-router.js';
+import { oRequest } from '../connection/o-request.js';
+import { oNotificationManager } from './lib/o-notification.manager.js';
+import { oNotificationEvent, EventFilter, NotificationHandler, Subscription } from './lib/events/index.js';
+import { oConnectionConfig } from '../connection/index.js';
+import { UseOptions } from './interfaces/use-options.interface.js';
+import { UseStreamOptions } from './interfaces/use-stream-options.interface.js';
+export declare abstract class oCore extends oObject {
+    readonly config: oCoreConfig;
+    address: oAddress;
+    state: NodeState;
+    errors: Error[];
+    connectionManager: oConnectionManager;
+    hierarchyManager: oHierarchyManager;
+    metrics: oMetrics;
+    requestManager: oRequestManager;
+    router: oRouter;
+    notificationManager: oNotificationManager;
+    private heartbeatInterval?;
+    constructor(config: oCoreConfig);
+    get isLeader(): boolean;
+    get leader(): oAddress | null;
+    abstract configureTransports(): any[];
+    useStream(address: oAddress, data: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }, options: UseStreamOptions): Promise<oResponse>;
+    useDirect(address: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }): Promise<oResponse>;
+    /**
+     * Sends a request to a remote node in the O-Lane network using the specified address and optional data payload.
+     *
+     * This method handles the complete communication flow:
+     * 1. Validates the target address format
+     * 2. Resolves the routing path through the network
+     * 3. Establishes a connection to the target node
+     * 4. Sends the request payload and waits for response
+     * 5. Handles errors and throws them as oError instances
+     *
+     * @param address - The target node address in O-Lane format (must start with 'o://')
+     * @param data - Optional request data containing method, parameters, and request ID
+     * @param data.method - The method name to invoke on the target node
+     * @param data.params - Key-value pairs of parameters to pass to the method
+     * @param data.id - Unique identifier for the request (for tracking purposes)
+     * @returns Promise that resolves to an oResponse containing the result from the target node
+     * @throws {Error} When the address is invalid (doesn't pass validation)
+     * @throws {oError} When the target node returns an error response
+     *
+     * @example
+     * ```typescript
+     * // Basic usage - call a method on a remote node
+     * const response = await node.use(
+     *   new oAddress('o://calculator/add'),
+     *   {
+     *     method: 'add',
+     *     params: { a: 5, b: 3 },
+     *     id: 'calc-001'
+     *   }
+     * );
+     * console.log(response.result); // { result: 8 }
+     *
+     * // Minimal usage - just specify the address
+     * const response = await node.use(
+     *   new oAddress('o://status/health')
+     * );
+     * console.log(response.result); // { status: 'healthy' }
+     *
+     * // Error handling
+     * try {
+     *   const response = await node.use(
+     *     new oAddress('o://calculator/divide'),
+     *     { method: 'divide', params: { a: 10, b: 0 } }
+     *   );
+     * } catch (error) {
+     *   if (error instanceof oError) {
+     *     console.error(`Node error ${error.code}: ${error.message}`);
+     *   } else {
+     *     console.error('Invalid address or connection error:', error.message);
+     *   }
+     * }
+     * ```
+     */
+    use(address: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }, options?: UseOptions): Promise<oResponse>;
+    abstract execute(request: oRequest): Promise<any>;
+    /**
+     * Helper method to handle response errors
+     * @param response The response to check for errors
+     * @throws oError if the response contains an error
+     */
+    private handleResponseError;
+    /**
+     * Helper method to validate node is running
+     * @throws Error if node is not running
+     */
+    private validateRunning;
+    useSelf(data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }): Promise<oResponse>;
+    useChild(childAddress: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }, options?: {
+        isStream?: boolean;
+        onChunk?: (chunk: oResponse) => void;
+    }): Promise<oResponse>;
+    addChildNode(node: oCore): void;
+    removeChildNode(node: oCore): void;
+    abstract connect(config: oConnectionConfig): Promise<oConnection>;
+    abstract initializeRouter(): void;
+    abstract unregister(): Promise<void>;
+    abstract register(): Promise<void>;
+    protected abstract createNotificationManager(): oNotificationManager;
+    /**
+     * Emit a notification event
+     */
+    protected notify(event: oNotificationEvent): void;
+    /**
+     * Subscribe to notification events
+     */
+    protected onNotification(eventType: string, handler: NotificationHandler, filter?: EventFilter): Subscription;
+    initialize(): Promise<void>;
+    get isRunning(): boolean;
+    hookStartFinished(): Promise<void>;
+    /**
+     * Starts the node by transitioning through initialization and registration phases.
+     *
+     * This method performs the following operations in sequence:
+     * 1. Validates that the node is in STOPPED state
+     * 2. Sets state to STARTING
+     * 3. Calls initialize() to set up the node's core components
+     * 4. Attempts registration with the network (registration errors are logged but don't fail startup)
+     * 5. Sets state to RUNNING on success
+     *
+     * @throws {Error} If the node is not in STOPPED state or initialization fails
+     * @returns {Promise<void>} Resolves when the node is successfully started and running
+     *
+     * @example
+     * ```typescript
+     * const node = new oNode(config);
+     * try {
+     *   await node.start();
+     *   console.log('Node is now running');
+     * } catch (error) {
+     *   console.error('Failed to start node:', error);
+     * }
+     * ```
+     *
+     * @remarks
+     * - If the node is already running or starting, the method will log a warning and return early
+     * - Registration failures are logged but do not prevent the node from starting
+     * - On any initialization error, the node state is set to ERROR and teardown() is called
+     * - The node must be in STOPPED state before calling this method
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the node by performing cleanup and transitioning to a stopped state.
+     *
+     * This method performs the following operations in sequence:
+     * 1. Sets state to STOPPING
+     * 2. Calls teardown() to clean up node resources and connections
+     * 3. Sets state to STOPPED on successful completion
+     *
+     * @throws {Error} If teardown operations fail, the node state will be set to ERROR
+     * @returns {Promise<void>} Resolves when the node is successfully stopped
+     *
+     * @example
+     * ```typescript
+     * const node = new oNode(config);
+     * await node.start();
+     *
+     * // Later, when shutting down
+     * try {
+     *   await node.stop();
+     *   console.log('Node stopped successfully');
+     * } catch (error) {
+     *   console.error('Failed to stop node:', error);
+     * }
+     * ```
+     *
+     * @remarks
+     * - This method can be called from any node state
+     * - If teardown fails, errors are logged and the node state is set to ERROR
+     * - All cleanup operations are performed through the teardown() method
+     * - The method will attempt to stop gracefully even if the node is in an error state
+     */
+    stop(): Promise<void>;
+    teardown(): Promise<void>;
+    get dependencies(): oDependency[];
+    /**
+     * Start sending periodic heartbeats to the monitor node
+     * This is optional and only runs if MONITOR_ENABLED=true and MONITOR_ADDRESS is set
+     */
+    private startHeartbeat;
+    get methods(): {
+        [key: string]: oMethod;
+    };
+    get description(): string;
+    get staticAddress(): oAddress;
+    get type(): NodeType;
+    get transports(): oTransport[];
+    get parent(): oAddress | null;
+    get parentTransports(): oTransport[];
+    whoami(): Promise<any>;
+}
+//# sourceMappingURL=o-core.d.ts.map

package/dist/o-core/src/core/o-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-core.d.ts","sourceRoot":"","sources":["../../../../../o-core/src/core/o-core.ts"],"names":[],"mappings":"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"}