<?php

declare(strict_types=1);

namespace App\Framework\Search;

/**
 * Core search engine interface
 * Provides backend-agnostic search functionality
 * Uses Value Objects to eliminate primitive obsession
 */
interface SearchEngine
{
    /**
     * Execute a search query
     */
    public function search(SearchQuery $query): SearchResult;

    /**
     * Index a document for searching
     */
    public function index(SearchDocument $document): bool;

    /**
     * Remove document from search index
     */
    public function delete(SearchDocument $document): bool;

    /**
     * Update existing document in search index
     */
    public function update(SearchDocument $document): bool;

    /**
     * Bulk index multiple documents
     *
     * @param SearchDocument[] $documents
     */
    public function bulkIndex(array $documents): BulkIndexResult;

    /**
     * Get search statistics and health
     */
    public function getStats(): SearchEngineStats;

    /**
     * Check if the search engine is available
     */
    public function isAvailable(): bool;

    /**
     * Get engine name/type
     */
    public function getName(): string;
}
