<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Persists queue-editor metadata on tracked queue rows.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface QueueMetadataRepositoryInterface {

  /**
   * Manual-order default for unsorted queue items.
   */
  public const int DEFAULT_MANUAL_ORDER = 2147483647;

  /**
   * Loads scheduling metadata keyed by queue item ID.
   *
   * @param array<int, string> $itemIds
   *   Optional queue item IDs to limit the query to.
   *
   * @return array{order: array<string, int>, priorities: array<string, int>, paused: array<string, bool>}
   *   Scheduling metadata keyed by queue item ID.
   */
  #[\NoDiscard]
  public function loadSchedulingMaps(array $itemIds = []): array;

  /**
   * Replaces the manual ordering across queued items.
   *
   * Items not present in the provided list are reset to the default order.
   *
   * @param array<int, string> $itemIds
   *   Queue item IDs in their new order.
   *
   * @return int
   *   Number of ordered queue items persisted.
   */
  public function replaceManualOrder(array $itemIds): int;

  /**
   * Updates the paused flag for a queue item.
   *
   * @return bool
   *   TRUE when the queue row was updated.
   */
  public function setPaused(string $itemId, bool $paused): bool;

  /**
   * Updates the priority for a queue item.
   *
   * @return bool
   *   TRUE when the queue row was updated.
   */
  public function setPriority(string $itemId, int $priority): bool;

  /**
   * Resets custom metadata for a queue item.
   */
  public function clearItemMetadata(string $itemId): void;

  /**
   * Loads queue rows in effective editor order.
   *
   * @param int $offset
   *   Row offset.
   * @param int $limit
   *   Maximum number of rows.
   *
   * @return array<int, object>
   *   Queue rows ordered for UI consumption.
   */
  #[\NoDiscard]
  public function loadOrderedRows(int $offset, int $limit): array;

}
