<?php

declare(strict_types=1);

namespace Drupal\flowdrop_stategraph\Reducer;

/**
 * Interface for state field reducers.
 *
 * Reducers define how state updates are applied to existing state values.
 * Each reducer implements a specific strategy for combining the current
 * state value with an incoming update.
 *
 * Available reducer implementations:
 * - AppendReducer: Appends values to arrays (for message history).
 * - ReplaceReducer: Replaces the current value entirely (default).
 * - MergeReducer: Deep merges arrays (for nested data transforms).
 *
 * @see \Drupal\flowdrop_stategraph\Reducer\AppendReducer
 * @see \Drupal\flowdrop_stategraph\Reducer\ReplaceReducer
 * @see \Drupal\flowdrop_stategraph\Reducer\MergeReducer
 *
 * @api
 */
interface ReducerInterface {

  /**
   * Gets the unique identifier for this reducer.
   *
   * @return string
   *   The reducer ID (e.g., "append", "replace", "merge").
   */
  public function getId(): string;

  /**
   * Reduces the current state value with an incoming update.
   *
   * @param mixed $currentValue
   *   The current value of the state field.
   * @param mixed $updateValue
   *   The incoming update value from a node execution.
   *
   * @return mixed
   *   The new state value after reduction.
   */
  public function reduce(mixed $currentValue, mixed $updateValue): mixed;

  /**
   * Gets the default value for this reducer's field type.
   *
   * This is used to initialize state fields before any updates.
   *
   * @return mixed
   *   The default value (e.g., [] for append, null for replace).
   */
  public function getDefaultValue(): mixed;

}
