package com.livingworld.data.serialization;

/**
 * Abstraction for writing save data to a persistence target.
 *
 * <p>This interface hides the underlying storage format (JSON, NBT, etc.) from
 * modules. Modules write their data through this abstraction without knowing
 * how or where it is persisted.</p>
 */
public interface PersistenceWriter {

    /**
     * Writes a string value with the given key.
     *
     * @param key   the identifier for this value (must not be null or blank)
     * @param value the string to write
     * @throws IllegalArgumentException if key is null or blank
     */
    void writeString(String key, String value);

    /**
     * Writes an integer value with the given key.
     *
     * @param key   the identifier for this value (must not be null or blank)
     * @param value the integer to write
     * @throws IllegalArgumentException if key is null or blank
     */
    void writeInt(String key, int value);

    /**
     * Writes a long value with the given key.
     *
     * @param key   the identifier for this value (must not be null or blank)
     * @param value the long to write
     * @throws IllegalArgumentException if key is null or blank
     */
    void writeLong(String key, long value);

    /**
     * Writes a double value with the given key.
     *
     * @param key   the identifier for this value (must not be null or blank)
     * @param value the double to write
     * @throws IllegalArgumentException if key is null or blank
     */
    void writeDouble(String key, double value);

    /**
     * Writes a boolean value with the given key.
     *
     * @param key   the identifier for this value (must not be null or blank)
     * @param value the boolean to write
     * @throws IllegalArgumentException if key is null or blank
     */
    void writeBoolean(String key, boolean value);
}