<?php

declare(strict_types=1);

namespace Apexl\Vault\Interfaces;

use stdClass;

/**
 * The rows a single execution produced.
 *
 * A result is deliberately separate from the builder that made it. The builder is
 * long-lived and mutable — one instance per named vault, reused for every query in
 * the process — so while it also carried the statement, two "separate" queries were
 * the same object and the second one silently retargeted the first:
 *
 *     $a = $db->select('x')->execute();
 *     $b = $db->select('y')->execute();   // $a === $b, before this split
 *     $a->fetch();                        // rows from y
 *
 * Holding the rows here instead makes that impossible to express.
 */
interface ResultInterface
{
    public function fetch(): stdClass|false;

    public function fetchColumn(int $ix = 0): mixed;

    public function fetchAll(): array|false;

    public function fetchAllAssoc(): array|false;

    public function fetchAssoc(): array|false;

    /**
     * Rows returned by a select, or rows affected by a write. Drivers that cannot
     * distinguish the two report what their native layer reports.
     */
    public function rowCount(): int;
}
