<?php
/**
 * A REST response whose body was already built.
 *
 * @package Shiftora\Api\Endpoints
 */

declare(strict_types=1);

namespace Shiftora\Api\Endpoints;

use WP_REST_Response;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Serves a body assembled incrementally, so the endpoint never holds the batch and a
 * second copy. get_data() decodes on demand; that cost is the caller's.
 */
final class FileBatchBodyResponse extends WP_REST_Response {

	/** @param string[] $fragments Body pieces in order, each already JSON-encoded. */
	public function __construct( private readonly array $fragments ) {
		// Left empty: decoding would join and parse every fragment, the copy this class avoids.
		// which is the double copy this class avoids. get_data() decodes on demand.
		parent::__construct( [] );
	}

	/** Separate from `$data` because `{"files":[]}` is a real, empty answer. */
	private ?array $decoded = null;

	/** @return array<string, mixed> */
	public function get_data() {
		if ( null !== $this->decoded ) {
			return $this->data;
		}

		$decoded = json_decode( $this->get_body(), true );

		$this->data    = is_array( $decoded ) ? $decoded : [];
		$this->decoded = $this->data;

		return $this->data;
	}

	/** @return string JSON. */
	public function get_body(): string {
		return implode( '', $this->fragments );
	}

	/** @return \Generator<int, string> JSON fragments, in order. */
	public function stream_body(): \Generator {
		foreach ( $this->fragments as $fragment ) {
			// One large file can be a single fragment, so it is subdivided.
			$length = strlen( $fragment );

			for ( $offset = 0; $offset < $length; $offset += self::FRAGMENT_BYTES ) {
				$take = substr( $fragment, $offset, self::FRAGMENT_BYTES );

				yield $take;
			}

			unset( $fragment );
		}
	}

	/** Large enough that flushing isn't the bottleneck, small enough to stay a minor share of the memory limit. */
	private const FRAGMENT_BYTES = 262_144;
}