<?php

declare(strict_types=1);

namespace App\Framework\Queue;

use App\Framework\Queue\ValueObjects\JobPayload;

interface Queue
{
    /**
     * Push a job to the queue
     *
     * @param JobPayload $payload The job payload with priority, delay, and metadata
     */
    public function push(JobPayload $payload): void;

    /**
     * Pop the next available job from the queue
     *
     * @return JobPayload|null The next job payload or null if queue is empty
     */
    public function pop(): ?JobPayload;

    /**
     * Peek at the next job without removing it
     *
     * @return JobPayload|null The next job payload or null if queue is empty
     */
    public function peek(): ?JobPayload;

    /**
     * Get the number of jobs in the queue
     *
     * @return int Number of pending jobs
     */
    public function size(): int;

    /**
     * Clear all jobs from the queue
     *
     * @return int Number of jobs removed
     */
    public function clear(): int;

    /**
     * Get queue statistics
     *
     * @return array Statistics about the queue (size, priorities, etc.)
     */
    public function getStats(): array;
}
