@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/types/interfaces/services/core/execution/engine.d.ts

@@ -1,106 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * @fileoverview Core Execution Engine Type Definition
- *
- * This module defines the fundamental execution engine type that serves as the
- * foundation for all command processing in the core service framework. Execution
- * engines are responsible for transforming commands into streams of updates.
- *
- * @module CoreExecutionEngine
- * @version 0.5.7
- * @since 0.5.6
- * @author The Artinet Project
- */
-import { CoreCommand, CoreContext, CoreState, CoreUpdate } from "../context/index.js";
-/**
- * Core execution engine function signature.
- *
- * An ExecutionEngine is a function that accepts a CoreContext and returns an
- * AsyncGenerator yielding updates. This pattern enables streaming execution
- * where commands can produce multiple updates over time, supporting both
- * real-time processing and long-running operations.
- *
- * The engine receives a complete execution context containing the command to
- * execute, current state, event management, and cancellation signals. It
- * processes the command and yields updates as execution progresses, allowing
- * consumers to receive real-time feedback about execution status.
- *
- * @template TCommand - The command type, must extend CoreCommand
- * @template TState - The state type, must extend CoreState
- * @template TUpdate - The update type, must extend CoreUpdate
- *
- * @param context - The execution context containing command, state, and environment
- * @returns AsyncGenerator that yields updates during execution
- *
- * @example
- * ```typescript
- * // Simple execution engine that processes a command
- * const simpleEngine: ExecutionEngine<MyCommand, MyState, MyUpdate> = async function* (context) {
- *   const { command, State } = context;
- *
- *   // Yield progress update
- *   yield {
- *     type: 'progress',
- *     message: 'Starting execution...',
- *     progress: 0
- *   };
- *
- *   // Process command
- *   const result = await processCommand(command);
- *
- *   // Yield intermediate results
- *   yield {
- *     type: 'data',
- *     data: result.intermediateData,
- *     progress: 0.5
- *   };
- *
- *   // Complete processing
- *   const finalResult = await finalizeResult(result);
- *
- *   // Yield final update
- *   yield {
- *     type: 'complete',
- *     data: finalResult,
- *     progress: 1.0
- *   };
- * };
- * ```
- *
- * @example
- * ```typescript
- * // Execution engine with error handling and cancellation
- * const robustEngine: ExecutionEngine = async function* (context) {
- *   const { command, signal, isCancelled } = context;
- *
- *   try {
- *     for (let i = 0; i < command.steps.length; i++) {
- *       // Check for cancellation
- *       if (isCancelled() || signal.aborted) {
- *         yield { type: 'cancelled', step: i };
- *         return;
- *       }
- *
- *       // Process step
- *       const stepResult = await processStep(command.steps[i]);
- *
- *       yield {
- *         type: 'step-complete',
- *         step: i,
- *         result: stepResult,
- *         progress: (i + 1) / command.steps.length
- *       };
- *     }
- *   } catch (error) {
- *     yield { type: 'error', error: error.message };
- *   }
- * };
- * ```
- *
- * @public
- * @since 0.5.6
- */
-export type ExecutionEngine<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> = (context: CoreContext<TCommand, TState, TUpdate>) => AsyncGenerator<TUpdate, void, unknown>;

package/dist/types/interfaces/services/core/execution/engine.js

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

package/dist/types/interfaces/services/core/execution/environment.d.ts

@@ -1,11 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { CoreCommand, CoreState, CoreUpdate } from "../context/index.js";
-import { ServiceInterface } from "../service.js";
-import { ExecutionEngine } from "./engine.js";
-export interface ExecutionEnvironment<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    service: ServiceInterface<TCommand, TState, TUpdate>;
-    engine?: ExecutionEngine<TCommand, TState, TUpdate>;
-}

package/dist/types/interfaces/services/core/execution/environment.js

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

package/dist/types/interfaces/services/core/execution/execute.d.ts

@@ -1,7 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { CoreContext, CoreCommand, CoreState, CoreUpdate } from "../context/index.js";
-import { ExecutionEngine } from "./engine.js";
-export type ExecuteFunction<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> = (engine: ExecutionEngine<TCommand, TState, TUpdate>, context: CoreContext<TCommand, TState, TUpdate>) => Promise<void>;

package/dist/types/interfaces/services/core/execution/execute.js

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

package/dist/types/interfaces/services/core/execution/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./engine.js";
-export * from "./environment.js";
-export * from "./execute.js";

package/dist/types/interfaces/services/core/execution/index.js

@@ -1,3 +0,0 @@
-export * from "./engine.js";
-export * from "./environment.js";
-export * from "./execute.js";

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

@@ -1,4 +0,0 @@
-export * from "./context/index.js";
-export * from "./execution/index.js";
-export * from "./managers/index.js";
-export * from "./service.js";

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

@@ -1,4 +0,0 @@
-export * from "./context/index.js";
-export * from "./execution/index.js";
-export * from "./managers/index.js";
-export * from "./service.js";

package/dist/types/interfaces/services/core/managers/cancellation.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export interface CancellationManagerInterface {
-    addCancellation(id: string): void;
-    removeCancellation(id: string): void;
-    isCancelled(id: string): boolean;
-}

package/dist/types/interfaces/services/core/managers/cancellation.js

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

package/dist/types/interfaces/services/core/managers/connection.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-export interface ConnectionManagerInterface {
-    addConnection(id: string): void;
-    removeConnection(id: string): void;
-    isConnected(id: string): boolean;
-}

package/dist/types/interfaces/services/core/managers/connection.js

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

package/dist/types/interfaces/services/core/managers/context.d.ts

@@ -1,17 +0,0 @@
-/**
- * Copyright 2025 The Artinet Project
- * SPDX-License-Identifier: Apache-2.0
- */
-import { CoreCommand, CoreState, CoreContext, CoreUpdate } from "../context/index.js";
-/**
- * @description The context manager interface.
- * @type {ContextManagerInterface<TCommand, TState>}
- * @note This will become an increasingly important part of the system as Context Engineering becomes more important.
- * currently it is used to store & retrieve contexts from storage but greater degrees of control may be needed.
- * ex. forking/merging contexts, forwarding contexts to other services, nesting contexts, etc.
- */
-export interface ContextManagerInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
-    getContext: (id: string) => CoreContext<TCommand, TState, TUpdate> | undefined;
-    setContext: (id: string, context: CoreContext<TCommand, TState, TUpdate>) => void;
-    deleteContext: (id: string) => void;
-}

package/dist/types/interfaces/services/core/managers/context.js

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

package/dist/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/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/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/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";