/**
 * Copyright 2022-2025 Theai, Inc. dba Inworld AI
 */

#pragma once

#include "Graph/InworldData.h"

/**
 * @class FInworldInputStreamTransformer
 * @brief Base class for transforming input text streams.
 *
 * This class provides a base interface for implementing transformations on
 * input text streams.
 *
 * Derived classes must override the transform method to define the
 * transformation logic. This class also includes utility methods to
 * wrap transformed data streams for further processing.
 *
 */
class INWORLDRUNTIME_API FInworldInputStreamTransformer
{
public:
	FInworldInputStreamTransformer() = default;
	virtual ~FInworldInputStreamTransformer() = default;

	/**
	 * @brief Transforms the input string into a desired format or representation.
	 *
	 * This pure virtual function must be implemented by derived classes.
	 * The function processes the input string and applies a transformation
	 * based on custom logic defined in the derived class.
	 *
	 * @param Input The input string to be transformed.
	 * @return The transformed string after processing.
	 */
	virtual std::string transform(const std::string& Input) = 0;

	/**
	 * @brief Wraps the transformed data stream for further processing.
	 *
	 * This static utility function applies a transformation to the provided
	 * input data stream using the provided InputStreamTransformer instance.
	 * The resulting transformed data is wrapped into a new data stream.
	 *
	 * @warning The InputStreamTransformer object will be cleaned up automatically after transformation is complete.
	 *
	 * @param Input The input data stream to be transformed.
	 * @param InputStreamTransformer The transformer object implementing the transformation logic.
	 * @return A new data stream containing the transformed data.
	 */
	static FInworldData_DataStream_String WrapDataStream(
		const FInworldData_DataStream_String& Input, FInworldInputStreamTransformer* InputStreamTransformer);

private:
	/**
	 * @brief Internal callback function for executing transformation operations.
	 *
	 * This static callback function is invoked by the native runtime system to
	 * perform the actual transformation of data. It bridges between the native
	 * system and the Unreal Engine transformer implementation.
	 *
	 * @param opaque_this Opaque pointer to the transformer instance
	 * @param execution_id Unique identifier for the current execution context
	 */
	static void transformCallback(void* opaque_this, int execution_id);

	/**
	 * @brief Internal callback function for cleanup when the transformer is destroyed.
	 *
	 * This static callback function is invoked by the native runtime system to
	 * perform cleanup operations when the transformer object is being destroyed.
	 * It ensures proper resource management and prevents memory leaks.
	 *
	 * @param opaque_this Opaque pointer to the transformer instance being destroyed
	 */
	static void destructorCallback(void* opaque_this);
};
