package com.livingworld.core.services;

import com.livingworld.regions.Region;
import com.livingworld.regions.RegionCoordinate;

import java.util.Optional;

/**
 * Service interface for region persistence operations.
 *
 * <p>This service handles marking regions as dirty, saving and loading regions,
 * and flushing all pending changes to storage.</p>
 */
public interface PersistenceService {

    /**
     * Marks a region as dirty, indicating it has unsaved changes.
     *
     * @param region the region to mark as dirty (must not be null)
     * @throws IllegalArgumentException if region is null
     */
    void markRegionDirty(Region region);

    /**
     * Saves all regions that have been marked as dirty.
     */
    void saveDirtyRegions();

    /**
     * Loads a region from storage by its coordinate.
     *
     * @param coordinate the region coordinate (must not be null)
     * @return an Optional containing the loaded region if it exists, or empty if not found
     * @throws IllegalArgumentException if coordinate is null
     */
    Optional<Region> loadRegion(RegionCoordinate coordinate);

    /**
     * Saves a region to storage.
     *
     * @param region the region to save (must not be null)
     * @throws IllegalArgumentException if region is null
     */
    void saveRegion(Region region);

    /**
     * Flushes all pending changes to storage, ensuring data integrity.
     */
    void flushAll();
}