<?php
/**
 * Outcome of an operation that the user may need to see.
 *
 * @package ForensixDigital
 */

declare(strict_types=1);

namespace ForensixDigital\Core;

defined( 'ABSPATH' ) || exit;

/**
 * Immutable success/failure value with a plain-language message.
 */
final class Result {

	/**
	 * Whether the operation succeeded.
	 *
	 * @var bool
	 */
	public readonly bool $ok;

	/**
	 * Machine-readable code, e.g. "missing_dependency".
	 *
	 * @var string
	 */
	public readonly string $code;

	/**
	 * Plain-language message for the user.
	 *
	 * @var string
	 */
	public readonly string $message;

	/**
	 * Extra details, e.g. the names of dependent apps.
	 *
	 * @var array<string, mixed>
	 */
	public readonly array $data;

	/**
	 * Builds a result.
	 *
	 * @param bool                 $ok      Success.
	 * @param string               $code    Machine-readable code.
	 * @param string               $message Plain-language message.
	 * @param array<string, mixed> $data    Extra details.
	 */
	private function __construct( bool $ok, string $code, string $message, array $data ) {
		$this->ok      = $ok;
		$this->code    = $code;
		$this->message = $message;
		$this->data    = $data;
	}

	/**
	 * Success.
	 *
	 * @param string               $message Plain-language message.
	 * @param array<string, mixed> $data    Extra details.
	 */
	public static function success( string $message = '', array $data = array() ): self {
		return new self( true, 'ok', $message, $data );
	}

	/**
	 * Failure.
	 *
	 * @param string               $code    Machine-readable code.
	 * @param string               $message Plain-language message.
	 * @param array<string, mixed> $data    Extra details.
	 */
	public static function failure( string $code, string $message, array $data = array() ): self {
		return new self( false, $code, $message, $data );
	}
}