<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\ValueObject;

/**
 * Immutable execution metadata for an output conversion run.
 */
final readonly class OutputExecutionPlan {

  /**
   * Constructs an OutputExecutionPlan object.
   *
   * @param string|null $outputDirectory
   *   Optional target directory for generated outputs.
   * @param bool $autoCleanupFailed
   *   TRUE when failed runs should cleanup partial outputs.
   * @param array<int, string> $outputKeys
   *   Qualified output keys in execution order.
   * @param int $singleOutputCount
   *   Number of non-adaptive outputs in the current run.
   * @param bool $hardwareRequired
   *   TRUE when the selected profile requires hardware acceleration.
   */
  public function __construct(
    public ?string $outputDirectory,
    public bool $autoCleanupFailed,
    public array $outputKeys,
    public int $singleOutputCount,
    public bool $hardwareRequired,
  ) {
    if ($singleOutputCount < 0) {
      throw new \InvalidArgumentException('Single output count cannot be negative.');
    }

    foreach ($outputKeys as $outputKey) {
      if ($outputKey === '') {
        throw new \InvalidArgumentException('Output keys cannot contain empty values.');
      }
    }
  }

  /**
   * Resolves the qualified output key for an indexed output definition.
   */
  #[\NoDiscard]
  public function getOutputKey(int $outputIndex, string $fallback): string {
    return $this->outputKeys[$outputIndex] ?? $fallback;
  }

}
