Interface TroubleModel<AdditionalData>

Represents a trouble (issue, alert, or condition) in the KOS system.

TroubleModel is the core interface for managing system issues, warnings, and alerts throughout the KOS platform. It provides a unified way to track, display, resolve, and defer various types of operational issues.

Key Features

• Priority ranking - Troubles are ranked 1-10 for severity
• Role-based visibility - Troubles can be filtered by user role
• Resolution support - Resolvable troubles can be cleared through actions
• Deferral capability - Troubles can be temporarily deferred
• Future integration - Async resolution through futures
• Type categorization - Troubles grouped by type for filtering
• Visual indicators - Color coding for UI representation

Example

// Check trouble severity
function handleTrouble(trouble: TroubleModel) {
  if (trouble.rank >= 8) {
    console.error(`Critical trouble: ${trouble.reason}`);
    notifyOperator(trouble);
  } else if (trouble.rank >= 5) {
    console.warn(`Warning: ${trouble.reason}`);
  }

  // Check if user can resolve
  if (trouble.resolvable && hasRole(trouble.role)) {
    showResolveButton(trouble);
  }
}
Copy

Example

// Resolve a trouble with proper future handling
async function resolveTrouble(trouble: TroubleModel) {
  if (!trouble.resolvable) {
    throw new Error('Trouble is not resolvable');
  }

  try {
    // Resolution returns a FutureResponse with future tracking
    const futureResponse = await trouble.resolve();
    if (futureResponse) {
      console.log(`Resolution started, future ID: ${futureResponse.id}`);

      // The trouble's future property will be updated with the resolution future
      // You can track progress through the future model
      if (trouble.future) {
        const endState = await trouble.future.waitForCompletion();
        if (endState === 'COMPLETED') {
          console.log('Trouble resolved successfully');
        } else if (endState === 'FAILED') {
          console.error('Resolution failed');
        }
      }
    }
  } catch (error) {
    console.error('Failed to initiate resolution:', error);
  }
}
Copy

Example

// Using cancellable promise utilities with trouble resolution
import { createCancellablePromise } from '@kosdev-code/kos-ui-sdk';

async function resolveTroubleWithCancel(trouble: TroubleModel) {
  const futureResponse = await trouble.resolve();

  if (futureResponse && trouble.future) {
    // Create a cancellable promise for the resolution
    const cancellableResolve = createCancellablePromise(
      trouble.future.waitForCompletion(),
      undefined,
      () => trouble.future?.cancelFuture(),
      trouble.future
    );

    // Subscribe to progress updates
    const unsubscribe = cancellableResolve.onProgressUpdate((progress, status) => {
      console.log(`Resolution progress: ${(progress * 100).toFixed(0)}% - ${status}`);
    });

    try {
      const endState = await cancellableResolve;
      console.log(`Resolution completed with state: ${endState}`);
    } catch (error) {
      if (cancellableResolve.isCancelled()) {
        console.log('Resolution was cancelled');
      } else {
        console.error('Resolution failed:', error);
      }
    } finally {
      unsubscribe();
    }
  }
}
Copy

Subcategory

Trouble Management

See

• TroubleAware - Interface for models that can have troubles
• DeferAware - Deferral capabilities
• ResolveAware - Resolution capabilities