<?php

namespace CloudXM\SDK\Contracts;

/**
 * Base Repository Interface
 *
 * Defines the contract for repository classes that handle data access operations.
 * Repositories provide a clean abstraction over data access, allowing services to
 * work with domain objects without knowing the underlying persistence mechanism.
 *
 * @package CloudXM\SDK\Contracts
 */
interface RepositoryInterface
{
    /**
     * Find entity by ID
     *
     * @param int $id
     * @return array|null Entity data or null if not found
     */
    public function find(int $id): ?array;

    /**
     * Find all entities with optional pagination and filtering
     *
     * @param array $conditions Filter conditions
     * @param int $limit Maximum number of results
     * @param int $offset Results offset for pagination
     * @return array Array of entities
     */
    public function findAll(array $conditions = [], int $limit = 50, int $offset = 0): array;

    /**
     * Find single entity by conditions
     *
     * @param array $conditions Filter conditions
     * @return array|null Entity data or null if not found
     */
    public function findOneBy(array $conditions): ?array;

    /**
     * Save new entity
     *
     * @param array $data Entity data
     * @return int New entity ID
     */
    public function save(array $data): int;

    /**
     * Update existing entity
     *
     * @param int $id Entity ID
     * @param array $data Updated entity data
     * @return bool True on success
     */
    public function update(int $id, array $data): bool;

    /**
     * Delete entity by ID
     *
     * @param int $id Entity ID
     * @return bool True on success
     */
    public function delete(int $id): bool;

    /**
     * Count entities matching conditions
     *
     * @param array $conditions Filter conditions
     * @return int Number of matching entities
     */
    public function count(array $conditions = []): int;
}