<?php

declare(strict_types=1);

namespace App\Framework\StateManagement;

/**
 * State Transformer Interface
 *
 * Transforms state data before storage and after retrieval.
 * Enables composable transformation pipeline (encryption, compression, validation, etc.).
 *
 * Framework Principles:
 * - Interface-driven design
 * - Composable transformations (middleware pattern)
 * - Type-safe with SerializableState
 * - Bidirectional transformation (in/out)
 *
 * Transformation Flow:
 * - transformIn: Before storage (State → transformed data)
 * - transformOut: After retrieval (transformed data → State)
 *
 * Example Transformers:
 * - EncryptionTransformer: Encrypts/decrypts state data
 * - CompressionTransformer: Compresses/decompresses state data
 * - ValidationTransformer: Validates state integrity
 * - HashingTransformer: Adds integrity hashes
 *
 * Usage:
 * ```php
 * $stateManager->addTransformer(new EncryptionTransformer($encryptor));
 * $stateManager->addTransformer(new CompressionTransformer());
 * ```
 */
interface StateTransformer
{
    /**
     * Transform state before storage
     *
     * Called when storing state (setState, updateState).
     * Transforms SerializableState into storable format (typically string).
     *
     * Transformation order when multiple transformers:
     * State → Transformer1 → Transformer2 → Transformer3 → Storage
     *
     * @param SerializableState $state The state object to transform
     * @return mixed The transformed data (typically string for final transformer)
     * @throws \Throwable if transformation fails
     */
    public function transformIn(SerializableState $state): mixed;

    /**
     * Transform data after retrieval
     *
     * Called when retrieving state (getState, updateState).
     * Transforms stored data back into SerializableState object.
     *
     * Transformation order when multiple transformers (reverse order):
     * Storage → Transformer3 → Transformer2 → Transformer1 → State
     *
     * @param mixed $data The stored data to transform back
     * @return SerializableState The restored state object
     * @throws \Throwable if transformation fails
     */
    public function transformOut(mixed $data): SerializableState;

    /**
     * Get transformer name (for debugging/logging)
     */
    public function getName(): string;

    /**
     * Get transformer priority (higher = runs first on transformIn)
     *
     * Priority determines execution order:
     * - High priority (100): Validation transformers
     * - Medium priority (50): Encryption transformers
     * - Low priority (10): Compression transformers
     *
     * @return int Priority value (default: 50)
     */
    public function getPriority(): int;
}
