<?php

declare(strict_types=1);

namespace Drupal\flowdrop_stategraph\Attribute;

/**
 * PHP 8 Attribute for defining reducible state fields.
 *
 * This attribute marks properties on GraphState classes as state fields
 * that can be updated via reducers during graph execution.
 *
 * Example usage:
 * @code
 * class MyState extends GraphState {
 *   #[StateField(reducer: "append")]
 *   public array $messages = [];
 *
 *   #[StateField(reducer: "replace")]
 *   public string $currentStep = "";
 *
 *   #[StateField(reducer: "merge")]
 *   public array $metadata = [];
 * }
 * @endcode
 *
 * Supported reducers:
 * - "append": Appends new values to an array (for message history).
 * - "replace": Replaces the current value (default behavior).
 * - "merge": Deep merges arrays (for nested data transforms).
 *
 * @internal This class is not part of the public API and may change without notice.
 */
#[\Attribute(\Attribute::TARGET_PROPERTY)]
final class StateField {

  /**
   * Constructs a new StateField attribute.
   *
   * @param string $reducer
   *   The reducer type to use for this field.
   *   Supported values: "append", "replace", "merge".
   * @param string $description
   *   Optional description of the field's purpose.
   * @param bool $required
   *   Whether this field is required in state updates.
   */
  public function __construct(
    public readonly string $reducer = "replace",
    public readonly string $description = "",
    public readonly bool $required = FALSE,
  ) {}

}
