@artinet/sdk 0.5.16 → 0.5.18

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

@@ -0,0 +1,106 @@
+/**
+ * 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/browser/types/interfaces/services/core/execution/engine.js

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

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

@@ -0,0 +1,11 @@
+/**
+ * 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/browser/types/interfaces/services/core/execution/environment.js

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

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

@@ -0,0 +1,7 @@
+/**
+ * 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/browser/types/interfaces/services/core/execution/execute.js

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,9 @@
+/**
+ * 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/browser/types/interfaces/services/core/managers/cancellation.js

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

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

@@ -0,0 +1,9 @@
+/**
+ * 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/browser/types/interfaces/services/core/managers/connection.js

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

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

@@ -0,0 +1,17 @@
+/**
+ * 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/browser/types/interfaces/services/core/managers/context.js

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

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

@@ -0,0 +1,328 @@
+/**
+ * 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

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

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

@@ -0,0 +1,6 @@
+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

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