<?php

declare(strict_types=1);

namespace Drupal\flowdrop_job\Constants;

/**
 * Status constants for the FlowDrop Job entity.
 *
 * Job status lifecycle:
 * - IDLE: Initial state when job is created (not yet ready to run).
 * - PENDING: Job is ready to run (all dependencies met).
 * - RUNNING: Job is currently executing.
 * - COMPLETED: Job finished successfully.
 * - FAILED: Job execution failed.
 * - CANCELLED: Job was explicitly cancelled.
 * - SKIPPED: Job was not executed because the workflow completed/failed
 *   before this job became ready to run.
 * - INTERRUPTED: Job requires human input (human-in-the-loop). The job
 *   will be re-executed when the interrupt is resolved.
 *
 * @internal
 */
final class JobStatus {

  public const IDLE = 'idle';

  public const PENDING = 'pending';

  public const RUNNING = 'running';

  public const COMPLETED = 'completed';

  public const FAILED = 'failed';

  public const CANCELLED = 'cancelled';

  public const SKIPPED = 'skipped';

  public const INTERRUPTED = 'interrupted';

  /**
   * Returns all allowed values keyed by machine name.
   *
   * Suitable for use in Drupal base field 'allowed_values' settings.
   *
   * @return array<string, string>
   *   Map of machine name to human-readable label.
   */
  public static function allowedValues(): array {
    return [
      self::IDLE => 'Idle',
      self::PENDING => 'Pending',
      self::RUNNING => 'Running',
      self::COMPLETED => 'Completed',
      self::FAILED => 'Failed',
      self::CANCELLED => 'Cancelled',
      self::SKIPPED => 'Skipped',
      self::INTERRUPTED => 'Interrupted',
    ];
  }

  /**
   * Returns the non-terminal (active) statuses.
   *
   * Jobs in these states are considered "unfinished" and block pipeline
   * completion.
   *
   * @return string[]
   *   Array of non-terminal status values.
   */
  public static function activeStatuses(): array {
    return [
      self::IDLE,
      self::PENDING,
      self::RUNNING,
      self::INTERRUPTED,
    ];
  }

}
