<?php
/**
 * Outcome of one stage batch.
 *
 * @package Postlinkly
 * @since   1.14.0
 */

declare(strict_types=1);

namespace Postlinkly\Indexing\Stage;

/**
 * What a stage did with the time it was given.
 *
 * Three outcomes the runner must tell apart: there is more to do, there is
 * nothing left, or this attempt failed. Collapsing failure into either of the
 * others would let a stage that never works look like one making progress.
 *
 * @since 1.14.0
 */
final class StageResult {

	/**
	 * @var int
	 */
	private int $cursor;

	/**
	 * @var int
	 */
	private int $processed;

	/**
	 * @var bool
	 */
	private bool $finished;

	/**
	 * @var bool
	 */
	private bool $failed;

	/**
	 * @var string
	 */
	private string $error;

	/**
	 * @param int    $cursor    Last item fully committed.
	 * @param int    $processed Items handled in this batch.
	 * @param bool   $finished  Whether the stage has no work left.
	 * @param bool   $failed    Whether this attempt failed.
	 * @param string $error     Failure reason.
	 */
	private function __construct( int $cursor, int $processed, bool $finished, bool $failed, string $error ) {
		$this->cursor    = $cursor;
		$this->processed = $processed;
		$this->finished  = $finished;
		$this->failed    = $failed;
		$this->error     = $error;
	}

	/**
	 * Work happened and more remains.
	 *
	 * @since 1.14.0
	 *
	 * @param int $cursor    Id of the last item fully committed.
	 * @param int $processed Items handled in this batch.
	 */
	public static function progress( int $cursor, int $processed ): self {
		return new self( $cursor, $processed, false, false, '' );
	}

	/**
	 * Nothing left for this stage to do.
	 *
	 * @since 1.14.0
	 *
	 * @param int $processed Items handled in this batch.
	 */
	public static function finished( int $processed ): self {
		return new self( 0, $processed, true, false, '' );
	}

	/**
	 * This attempt failed; the runner decides whether to retry.
	 *
	 * @since 1.14.0
	 *
	 * @param string $error Human-readable reason.
	 */
	public static function failed( string $error ): self {
		return new self( 0, 0, false, true, $error );
	}

	/**
	 * @since 1.14.0
	 */
	public function cursor(): int {
		return $this->cursor;
	}

	/**
	 * @since 1.14.0
	 */
	public function processed(): int {
		return $this->processed;
	}

	/**
	 * @since 1.14.0
	 */
	public function is_finished(): bool {
		return $this->finished;
	}

	/**
	 * @since 1.14.0
	 */
	public function is_failed(): bool {
		return $this->failed;
	}

	/**
	 * @since 1.14.0
	 */
	public function error(): string {
		return $this->error;
	}
}