@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/browser/types/interfaces/services/core/managers/event.d.ts

@@ -1,328 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview Core Event Manager Interface Definitions
- *
- * This module defines interfaces for managing events throughout the execution lifecycle
- * of core services. It provides type-safe event handling, lifecycle management, and
- * state transitions for command execution contexts.
- *
- * @module CoreEventManager
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { EventEmitter } from "events";
-import { CoreCommand, CoreState, CoreUpdate, CoreContext } from "../context/index.js";
-/**
- * Configuration options for EventManager lifecycle callbacks.
- *
- * This interface defines optional callback functions that are invoked during
- * different phases of command execution, providing hooks for custom logic
- * and state management throughout the execution lifecycle.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @example
- * ```typescript
- * const eventOptions: EventManagerOptions<MyCommand, MyState, MyUpdate> = {
- *   onStart: async (context) => {
- *     console.log('Execution started for context:', context.contextId);
- *     return initialState;
- *   },
- *   onUpdate: async (current, update) => {
- *     console.log('Processing update:', update);
- *     return { ...current, lastUpdate: update };
- *   },
- *   onComplete: async (finalState) => {
- *     console.log('Execution completed successfully');
- *   }
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface EventManagerOptions<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    /**
-     * Called when execution starts for a new context.
-     *
-     * This callback is invoked at the beginning of command execution,
-     * allowing for initialization of state and setup of execution context.
-     *
-     * @param context - The execution context containing command and environment data
-     * @returns Promise resolving to the initial state for this execution
-     *
-     * @example
-     * ```typescript
-     * onStart: async (context) => {
-     *   const userId = context.command.metadata?.userId;
-     *   return {
-     *     userId,
-     *     startTime: new Date(),
-     *     status: 'initializing'
-     *   };
-     * }
-     * ```
-     */
-    readonly onStart?: (context: CoreContext<TCommand, TState, TUpdate>) => Promise<TState>;
-    /**
-     * Called when execution is cancelled.
-     *
-     * This callback handles cleanup and state updates when an execution
-     * is cancelled before completion, ensuring proper resource cleanup.
-     *
-     * @param current - The current state at the time of cancellation
-     * @param update - The update that triggered the cancellation
-     * @returns Promise that resolves when cancellation handling is complete
-     *
-     * @example
-     * ```typescript
-     * onCancel: async (current, update) => {
-     *   await cleanupResources(current.resourceIds);
-     *   await logCancellation(current.userId, update.reason);
-     * }
-     * ```
-     */
-    readonly onCancel?: (current: TState, update: TUpdate) => Promise<void>;
-    /**
-     * Called for each update during execution.
-     *
-     * This is the primary callback for processing updates and evolving state
-     * throughout the execution lifecycle. It receives the current state and
-     * an update, returning the new state.
-     *
-     * @param current - The current state before applying the update
-     * @param update - The update to be processed
-     * @returns Promise resolving to the new state after applying the update
-     *
-     * @example
-     * ```typescript
-     * onUpdate: async (current, update) => {
-     *   switch (update.type) {
-     *     case 'progress':
-     *       return { ...current, progress: update.progress };
-     *     case 'data':
-     *       return { ...current, data: [...current.data, update.data] };
-     *     default:
-     *       return current;
-     *   }
-     * }
-     * ```
-     */
-    readonly onUpdate?: (current: TState, update: TUpdate) => Promise<TState>;
-    /**
-     * Called when an error occurs during execution.
-     *
-     * This callback handles error scenarios, allowing for custom error processing,
-     * logging, and recovery strategies.
-     *
-     * @param current - The current state when the error occurred
-     * @param error - The error that occurred (can be any type)
-     * @returns Promise that resolves when error handling is complete
-     *
-     * @example
-     * ```typescript
-     * onError: async (current, error) => {
-     *   console.error('Execution error:', error);
-     *   await notifyAdministrators(error, current);
-     *   await saveErrorLog(current.contextId, error);
-     * }
-     * ```
-     */
-    readonly onError?: (current: TState, error: any) => Promise<void>;
-    /**
-     * Called when execution completes successfully.
-     *
-     * This callback is invoked upon successful completion of command execution,
-     * allowing for cleanup, final state processing, and completion notifications.
-     *
-     * @param current - The final state after successful completion
-     * @returns Promise that resolves when completion handling is done
-     *
-     * @example
-     * ```typescript
-     * onComplete: async (finalState) => {
-     *   await saveResults(finalState.results);
-     *   await notifyCompletion(finalState.userId);
-     *   await cleanupTemporaryResources();
-     * }
-     * ```
-     */
-    readonly onComplete?: (current: TState) => Promise<void>;
-    /**
-     * Optional state getter function.
-     *
-     * @deprecated This property may be removed in future versions.
-     * Use the EventManagerInterface.getState method instead.
-     *
-     * @returns The current state
-     */
-    readonly getState?: () => TState;
-}
-/**
- * Event map defining the structure of events emitted by EventManager.
- *
- * This interface maps event names to their corresponding argument tuples,
- * providing type safety for event emission and subscription.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @example
- * ```typescript
- * // Event manager will emit these events with the specified argument types
- * eventManager.on('start', (command: TCommand, state: TState) => {
- *   console.log('Execution started');
- * });
- *
- * eventManager.on('update', (state: TState, update: TUpdate) => {
- *   console.log('State updated');
- * });
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface EventManagerMap<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    /** Emitted when execution starts - [command, initialState] */
-    start: [TCommand, TState];
-    /** Emitted when execution is cancelled - [cancelUpdate] */
-    cancel: [TUpdate];
-    /** Emitted when state is updated - [currentState, update] */
-    update: [TState, TUpdate];
-    /** Emitted when an error occurs - [error, currentState] */
-    error: [any, TState];
-    /** Emitted when execution completes - [finalState] */
-    complete: [TState];
-}
-/**
- * Main interface for EventManager implementations.
- *
- * This interface extends EventEmitter to provide typed event handling
- * and defines the contract for managing execution lifecycle events.
- * Implementations must handle state transitions, error scenarios, and
- * provide access to current execution state.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @example
- * ```typescript
- * class MyEventManager implements EventManagerInterface<MyCommand, MyState, MyUpdate> {
- *   constructor(
- *     public readonly contextId: string,
- *     private options: EventManagerOptions<MyCommand, MyState, MyUpdate>
- *   ) {
- *     super();
- *   }
- *
- *   async onUpdate(update: MyUpdate): Promise<MyState> {
- *     const current = this.getState();
- *     const newState = await this.options.onUpdate?.(current, update) ?? current;
- *     this.emit('update', newState, update);
- *     return newState;
- *   }
- *
- *   // ... other method implementations
- * }
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface EventManagerInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> extends EventEmitter<EventManagerMap<TCommand, TState, TUpdate>> {
-    /**
-     * Unique identifier for this execution context.
-     *
-     * This ID is used to track and manage the specific execution instance
-     * throughout its lifecycle.
-     */
-    readonly contextId: string;
-    /**
-     * Optional callback for handling execution start.
-     *
-     * When present, this function is called to initialize state for a new execution.
-     *
-     * @param context - The execution context
-     * @returns Promise resolving to initial state
-     */
-    readonly onStart?: (context: CoreContext<TCommand, TState, TUpdate>) => Promise<TState>;
-    /**
-     * Handles execution cancellation.
-     *
-     * This method processes cancellation requests and performs necessary cleanup.
-     *
-     * @param update - The update that triggered cancellation
-     * @returns Promise that resolves when cancellation is complete
-     *
-     * @example
-     * ```typescript
-     * await eventManager.onCancel(cancellationUpdate);
-     * ```
-     */
-    readonly onCancel: (update: TUpdate) => Promise<void>;
-    /**
-     * Processes state updates during execution.
-     *
-     * This is the primary method for handling state evolution throughout
-     * the execution lifecycle.
-     *
-     * @param update - The update to process
-     * @returns Promise resolving to the new state
-     *
-     * @example
-     * ```typescript
-     * const newState = await eventManager.onUpdate(progressUpdate);
-     * ```
-     */
-    readonly onUpdate: (update: TUpdate) => Promise<TState>;
-    /**
-     * Handles errors that occur during execution.
-     *
-     * This method processes error scenarios and performs error recovery logic.
-     *
-     * @param error - The error that occurred
-     * @returns Promise that resolves when error handling is complete
-     *
-     * @example
-     * ```typescript
-     * await eventManager.onError(new Error('Something went wrong'));
-     * ```
-     */
-    readonly onError: (error: any) => Promise<void>;
-    /**
-     * Handles successful completion of execution.
-     *
-     * This method is called when execution completes successfully and
-     * performs final cleanup and notification tasks.
-     *
-     * @returns Promise that resolves when completion handling is done
-     *
-     * @example
-     * ```typescript
-     * await eventManager.onComplete();
-     * ```
-     */
-    onComplete: () => Promise<void>;
-    /**
-     * Gets the current execution state.
-     *
-     * @deprecated This method may be removed in future versions.
-     * Consider using state management through the context instead.
-     *
-     * @returns The current state
-     *
-     * @example
-     * ```typescript
-     * const currentState = eventManager.getState();
-     * ```
-     */
-    readonly getState: () => TState;
-}

package/dist/browser/types/interfaces/services/core/managers/event.js

@@ -1,5 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export {};

package/dist/browser/types/interfaces/services/core/managers/index.d.ts

@@ -1,6 +0,0 @@
-export * from "./cancellation.js";
-export * from "./connection.js";
-export * from "./context.js";
-export * from "./event.js";
-export * from "./stream.js";
-export * from "./task.js";

package/dist/browser/types/interfaces/services/core/managers/index.js

@@ -1,6 +0,0 @@
-export * from "./cancellation.js";
-export * from "./connection.js";
-export * from "./context.js";
-export * from "./event.js";
-export * from "./stream.js";
-export * from "./task.js";

package/dist/browser/types/interfaces/services/core/managers/stream.d.ts

@@ -1,217 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview Core Stream Manager Interface Definition
- *
- * This module defines the interface for managing execution streams in the core service
- * framework. It provides functionality for handling async execution, update collection,
- * and streaming results from execution engines to consumers.
- *
- * @module CoreStreamManager
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { CoreCommand, CoreState, CoreUpdate } from "../../../../index.js";
-import { CoreContext } from "../context/index.js";
-import { ExecutionEngine } from "../execution/index.js";
-import { ServiceInterface } from "../service.js";
-/**
- * Interface for managing execution streams and update collection.
- *
- * The StreamManager is responsible for coordinating the execution of commands
- * through execution engines, collecting updates as they are produced, and
- * providing a streaming interface for consumers to receive real-time updates.
- *
- * This interface supports both push-based update collection and pull-based
- * streaming, making it suitable for various execution patterns including
- * long-running tasks, batch operations, and real-time processing.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @example
- * ```typescript
- * class MyStreamManager implements StreamManagerInterface<MyCommand, MyState, MyUpdate> {
- *   private updates: MyUpdate[] = [];
- *   private completed = false;
- *
- *   constructor(
- *     private contextId: string,
- *     private context: CoreContext<MyCommand, MyState, MyUpdate>
- *   ) {}
- *
- *   async *stream(engine: ExecutionEngine<MyCommand, MyState, MyUpdate>) {
- *     for await (const update of engine(this.context)) {
- *       this.addUpdate(update);
- *       yield update;
- *     }
- *     this.setCompleted();
- *   }
- *
- *   // ... implement other interface methods
- * }
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export interface StreamManagerInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    /**
-     * Gets the unique identifier for the execution context.
-     *
-     * This ID is used to track and correlate updates with their specific
-     * execution instance across the system.
-     *
-     * @returns The context ID string
-     *
-     * @example
-     * ```typescript
-     * const contextId = streamManager.getContextId();
-     * console.log(`Processing execution: ${contextId}`);
-     * ```
-     */
-    getContextId(): string;
-    /**
-     * Adds an update to the internal update collection.
-     *
-     * This method is typically called by execution engines or other
-     * components to record updates as they occur during execution.
-     * Updates are stored in order and can be retrieved later.
-     *
-     * @param update - The update to add to the collection
-     *
-     * @example
-     * ```typescript
-     * const progressUpdate: MyUpdate = {
-     *   type: 'progress',
-     *   progress: 0.5,
-     *   message: 'Halfway complete'
-     * };
-     * streamManager.addUpdate(progressUpdate);
-     * ```
-     */
-    addUpdate(update: TUpdate): void;
-    /**
-     * Retrieves all updates that have been collected so far.
-     *
-     * Returns a copy of the internal update collection, providing
-     * access to the complete execution history up to this point.
-     *
-     * @returns Array of all collected updates in chronological order
-     *
-     * @example
-     * ```typescript
-     * const allUpdates = streamManager.getUpdates();
-     * console.log(`Collected ${allUpdates.length} updates so far`);
-     *
-     * // Process updates
-     * for (const update of allUpdates) {
-     *   processUpdate(update);
-     * }
-     * ```
-     */
-    getUpdates(): TUpdate[];
-    /**
-     * Checks whether the execution has completed.
-     *
-     * This flag indicates whether the execution engine has finished
-     * processing and no more updates will be produced.
-     *
-     * @returns True if execution is complete, false if still running
-     *
-     * @example
-     * ```typescript
-     * if (streamManager.isCompleted()) {
-     *   console.log('Execution finished');
-     *   finalizeResults(streamManager.getUpdates());
-     * } else {
-     *   console.log('Execution still in progress...');
-     * }
-     * ```
-     */
-    isCompleted(): boolean;
-    /**
-     * Marks the execution as completed.
-     *
-     * This method is called when the execution engine has finished
-     * processing, indicating that no more updates will be produced.
-     * It triggers any completion-related cleanup or finalization.
-     *
-     * @example
-     * ```typescript
-     * // Called by execution engine when done
-     * await executeTask();
-     * streamManager.setCompleted();
-     * ```
-     */
-    setCompleted(): void;
-    /**
-     * Gets the current execution context.
-     *
-     * Returns the context object that contains command, state, and
-     * execution environment information for this stream.
-     *
-     * @returns The execution context
-     *
-     * @example
-     * ```typescript
-     * const context = streamManager.getExecutionContext();
-     * const command = context.command;
-     * const currentState = context.State();
-     * ```
-     */
-    getExecutionContext(): CoreContext<TCommand, TState, TUpdate>;
-    /**
-     * Sets or updates the execution context.
-     *
-     * This method allows updating the context during execution,
-     * which may be necessary for dynamic execution scenarios.
-     *
-     * @param executionContext - The new execution context to set
-     *
-     * @example
-     * ```typescript
-     * const updatedContext = createNewContext(command, newState);
-     * streamManager.setExecutionContext(updatedContext);
-     * ```
-     */
-    setExecutionContext(executionContext: CoreContext<TCommand, TState, TUpdate>): void;
-    /**
-     * Creates an async generator stream for real-time update consumption.
-     *
-     * This is the primary method for executing commands and streaming results.
-     * It runs the provided execution engine with the current context and
-     * yields updates as they are produced, providing a real-time stream
-     * of execution progress.
-     *
-     * @param engine - The execution engine to run
-     * @param service - Optional service interface for additional functionality
-     * @returns AsyncGenerator that yields updates as they occur
-     *
-     * @example
-     * ```typescript
-     * // Basic streaming
-     * for await (const update of streamManager.stream(myEngine)) {
-     *   console.log('Received update:', update);
-     *   await processUpdate(update);
-     * }
-     *
-     * // With service integration
-     * const service = createMyService();
-     * for await (const update of streamManager.stream(myEngine, service)) {
-     *   await service.handleUpdate(update);
-     *   yield update; // Re-yield to downstream consumers
-     * }
-     * ```
-     *
-     * @remarks
-     * The stream will continue yielding updates until the execution engine
-     * completes. The StreamManager automatically handles update collection
-     * and completion status during streaming.
-     */
-    stream(engine: ExecutionEngine<TCommand, TState, TUpdate>, service?: ServiceInterface<TCommand, TState, TUpdate>): AsyncGenerator<TUpdate>;
-}

package/dist/browser/types/interfaces/services/core/managers/stream.js

@@ -1,5 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export {};

package/dist/browser/types/interfaces/services/core/managers/task.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export interface TaskManagerInterface<TaskType extends {} = {}> {
-    getState(id: string): Promise<TaskType | undefined> | TaskType | undefined;
-    setState(id: string, data: TaskType): Promise<void> | void;
-    getStates(): Promise<string[]> | string[];
-}

package/dist/browser/types/interfaces/services/core/service.d.ts

@@ -1,115 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview Core Service Interface Definition
- *
- * This module defines the fundamental service interface that all core services
- * must implement. It provides the contract for executing commands through
- * execution engines and managing service lifecycle.
- *
- * @module CoreService
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { CoreContext, CoreCommand, CoreState, CoreUpdate } from "./context/index.js";
-import { ExecutionEngine } from "./execution/index.js";
-/**
- * Core service interface defining the contract for all service implementations.
- *
- * Services are responsible for orchestrating command execution through execution
- * engines, managing the execution lifecycle, and providing a consistent interface
- * for starting and stopping operations. This interface serves as the foundation
- * for all service types in the core framework.
- *
- * The service acts as a coordinator between execution engines and the broader
- * system, handling concerns like resource management, execution tracking, and
- * graceful shutdown while delegating the actual command processing to engines.
- *
- * @public
- * @since 0.5.6
- */
-export interface ServiceInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    /**
-     * Executes a command using the provided execution engine and context.
-     *
-     * This is the primary method for processing commands. The service receives
-     * an execution engine (which defines how to process the command) and a
-     * context (which contains the command, state, and execution environment).
-     *
-     * The service is responsible for:
-     * - Coordinating the execution process
-     * - Managing resources during execution
-     * - Handling the stream of updates from the engine
-     * - Ensuring proper cleanup on completion or failure
-     *
-     * @param engine - The execution engine that will process the command
-     * @param context - The execution context containing command and environment
-     * @returns Promise that resolves when execution is complete
-     *
-     * @throws Should handle and wrap any execution errors appropriately
-     *
-     * @example
-     * ```typescript
-     * // Basic execution
-     * await service.execute(myEngine, executionContext);
-     *
-     * // With error handling
-     * try {
-     *   await service.execute(myEngine, executionContext);
-     * } catch (error) {
-     *   console.error('Execution failed:', error);
-     *   await handleExecutionError(error, executionContext);
-     * }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Service implementation with update handling
-     * async execute(engine, context) {
-     *   const updates: TUpdate[] = [];
-     *
-     *   try {
-     *     for await (const update of engine(context)) {
-     *       updates.push(update);
-     *       await this.notifySubscribers(update);
-     *
-     *       if (context.isCancelled()) {
-     *         console.log('Execution cancelled');
-     *         break;
-     *       }
-     *     }
-     *   } catch (error) {
-     *     await this.handleExecutionError(error, context);
-     *     throw error;
-     *   }
-     *
-     *   console.log(`Execution completed with ${updates.length} updates`);
-     * }
-     * ```
-     */
-    execute: (engine: ExecutionEngine<TCommand, TState, TUpdate>, context: CoreContext<TCommand, TState, TUpdate>) => Promise<void>;
-    /**
-     * Stops the service and performs cleanup operations.
-     *
-     * This method is called to gracefully shut down the service, ensuring that
-     * all active executions are properly terminated and resources are cleaned up.
-     * Implementation should handle stopping active executions, releasing resources,
-     * and preparing for service shutdown.
-     *
-     * The stop method should be idempotent - calling it multiple times should
-     * not cause errors or unexpected behavior.
-     *
-     * @returns Promise that resolves when the service has been stopped and cleaned up
-     *
-     * @example
-     * ```typescript
-     * // Graceful shutdown
-     * await service.stop();
-     * console.log('Service stopped successfully');
-     * ```
-     */
-    stop: () => Promise<void>;
-}