package com.livingworld.data.serialization;

/**
 * Abstraction for reading save data from a persistence source.
 *
 * <p>This interface hides the underlying storage format (JSON, NBT, etc.) from
 * modules. Modules read their data through this abstraction without knowing
 * how or where it is stored.</p>
 */
public interface PersistenceReader {

    /**
     * Reads a string value for the given key.
     *
     * @param key          the identifier for this value (must not be null or blank)
     * @param defaultValue the default value to return if the key is missing
     * @return the string value, or defaultValue if the key is missing
     * @throws IllegalArgumentException if key is null or blank
     */
    String readString(String key, String defaultValue);

    /**
     * Reads an integer value for the given key.
     *
     * @param key          the identifier for this value (must not be null or blank)
     * @param defaultValue the default value to return if the key is missing
     * @return the integer value, or defaultValue if the key is missing
     * @throws IllegalArgumentException if key is null or blank
     */
    int readInt(String key, int defaultValue);

    /**
     * Reads a long value for the given key.
     *
     * @param key          the identifier for this value (must not be null or blank)
     * @param defaultValue the default value to return if the key is missing
     * @return the long value, or defaultValue if the key is missing
     * @throws IllegalArgumentException if key is null or blank
     */
    long readLong(String key, long defaultValue);

    /**
     * Reads a double value for the given key.
     *
     * @param key          the identifier for this value (must not be null or blank)
     * @param defaultValue the default value to return if the key is missing
     * @return the double value, or defaultValue if the key is missing
     * @throws IllegalArgumentException if key is null or blank
     */
    double readDouble(String key, double defaultValue);

    /**
     * Reads a boolean value for the given key.
     *
     * @param key          the identifier for this value (must not be null or blank)
     * @param defaultValue the default value to return if the key is missing
     * @return the boolean value, or defaultValue if the key is missing
     * @throws IllegalArgumentException if key is null or blank
     */
    boolean readBoolean(String key, boolean defaultValue);
}