<?php
/**
 * Rows of MazeGraph's part of the shared options table.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Support;

defined('ABSPATH') || exit;

/**
 * Small, bounded data that needs no table of its own (decision 047): stored definitions, notes, usage roll-ups.
 * A row is addressed by a name and a reference number (a user id, or 0) and carries a type. The adapter is
 * `FrameworkOptionRows` (the framework's `illuminate_maze_options` table); tests use an in-memory copy.
 *
 * @since 0.1.0
 */
interface OptionRows
{
    /**
     * @since 0.1.0
     */
    public function get(string $name, int $ref = 0, mixed $default = null): mixed;

    /**
     * Insert or replace one row.
     *
     * @since 0.1.0
     */
    public function put(string $name, mixed $value, string $type, int $ref = 0): bool;

    /**
     * @since 0.1.0
     */
    public function delete(string $name, int $ref = 0): bool;

    /**
     * Every row of a type, ordered by name then reference.
     *
     * @since 0.1.0
     * @return list<array{name: string, ref: int, value: mixed}>
     */
    public function ofType(string $type): array;
}