<?php
/**
 * BookiFlex Core
 *
 * @package    BookiFlex
 * @subpackage Core
 * @author     BookiFlex
 * @copyright  Copyright (c) 2025 BookiFlex
 * @license    GPL-2.0-or-later
 *
 * @link       https://bookiflex.com
 */

declare(strict_types=1);

namespace BookiFlex\Core\Contract\Queue;

defined( 'ABSPATH' ) || exit;

/**
 * Queue interface for asynchronous task processing
 */
interface QueueInterface
{
    /**
     * Enqueue a task for asynchronous execution as soon as possible
     *
     * @param string $hook Unique hook identifier for the task
     * @param array $args Arguments to pass to the task handler
     * @param int $priority Task priority (lower number = higher priority)
     * @return void
     */
    public function enqueue(string $hook, array $args = [], int $priority = 10): void;

    /**
     * Schedule a task for execution at a specific time
     *
     * @param string $hook Unique hook identifier for the task
     * @param array $args Arguments to pass to the task handler
     * @param \DateTimeInterface $when When to execute the task
     * @param int $priority Task priority (lower number = higher priority)
     * @return void
     */
    public function schedule(string $hook, array $args, \DateTimeInterface $when, int $priority = 10): void;

    /**
     * Cancel a specific queued task
     *
     * @param string $hook Hook identifier
     * @param array $args Arguments to match (empty array matches all args)
     * @return void
     */
    public function cancel(string $hook, array $args = []): void;

    /**
     * Cancel all queued tasks with the specified hook
     *
     * @param string $hook Hook identifier
     * @return void
     */
    public function cancelAll(string $hook): void;

    /**
     * Schedule a recurring task that executes repeatedly at a specified interval
     *
     * @param string $hook Unique hook identifier for the task
     * @param array $args Arguments to pass to the task handler
     * @param int $intervalSeconds Interval in seconds between task executions
     * @param \DateTimeInterface|null $startAt When to run the first occurrence (null = immediately)
     * @param int $priority Task priority (lower number = higher priority)
     * @return void
     */
    public function scheduleRecurring(string $hook, array $args, int $intervalSeconds, ?\DateTimeInterface $startAt = null, int $priority = 10): void;
}
