<?php
/**
 * @author Daniel J. Summers <daniel@bitbadger.solutions>
 * @license MIT
 */

declare(strict_types=1);

namespace BitBadger\PDODocument;

/**
 * Functions to retrieve and output documents as JSON
 */
class Json
{
    /**
     * Retrieve all JSON documents in the given table
     *
     * @param string $tableName The table from which documents should be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string A JSON array of all documents from the table
     * @throws DocumentException If any is encountered
     */
    public static function all(string $tableName, array $orderBy = []): string
    {
        return Custom::jsonArray(Query::selectFromTable($tableName) . Query::orderBy($orderBy), []);
    }

    /**
     * Retrieve a JSON document by its ID
     *
     * @param string $tableName The table from which the document should be retrieved
     * @param mixed $docId The ID of the document to retrieve
     * @return string The JSON document if found, `{}` otherwise
     * @throws DocumentException If any is encountered
     */
    public static function byId(string $tableName, mixed $docId): string
    {
        return Custom::jsonSingle(Query\Find::byId($tableName, $docId), Parameters::id($docId));
    }

    /**
     * Retrieve JSON documents via a comparison on JSON fields
     *
     * @param string $tableName The table from which documents should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string A JSON array of documents matching the given field comparison
     * @throws DocumentException If any is encountered
     */
    public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null,
                                    array $orderBy = []): string
    {
        Parameters::nameFields($fields);
        return Custom::jsonArray(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
            Parameters::addFields($fields, []));
    }

    /**
     * Retrieve JSON documents via a JSON containment query (`@>`; PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param mixed[]|object $criteria The criteria for the JSON containment query
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string A JSON array of documents matching the JSON containment query
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function byContains(string $tableName, array|object $criteria, array $orderBy = []): string
    {
        return Custom::jsonArray(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
            Parameters::json(':criteria', $criteria));
    }

    /**
     * Retrieve JSON documents via a JSON Path match query (`@?`; PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param string $path The JSON Path match string
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string A JSON array of documents matching the JSON Path
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function byJsonPath(string $tableName, string $path, array $orderBy = []): string
    {
        return Custom::jsonArray(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
    }

    /**
     * Retrieve JSON documents via a comparison on JSON fields, returning only the first result
     *
     * @param string $tableName The table from which the document should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string The first JSON document if any matches are found, `{}` otherwise
     * @throws DocumentException If any is encountered
     */
    public static function firstByFields(string $tableName, array $fields, ?FieldMatch $match = null,
                                         array $orderBy = []): string
    {
        Parameters::nameFields($fields);
        return Custom::jsonSingle(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
            Parameters::addFields($fields, []));
    }

    /**
     * Retrieve JSON documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param mixed[]|object $criteria The criteria for the JSON containment query
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string The first JSON document if any matches are found, `{}` otherwise
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function firstByContains(string $tableName, array|object $criteria, array $orderBy = []): string
    {
        return Custom::jsonSingle(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
            Parameters::json(':criteria', $criteria));
    }

    /**
     * Retrieve JSON documents via a JSON Path match query (`@?`), returning only the first result (PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param string $path The JSON Path match string
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return string The first JSON document if any matches are found, `{}` otherwise
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function firstByJsonPath(string $tableName, string $path, array $orderBy = []): string
    {
        return Custom::jsonSingle(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
    }

    /**
     * Output all JSON documents in the given table
     *
     * @param string $tableName The table from which documents should be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If any is encountered
     */
    public static function outputAll(string $tableName, array $orderBy = []): void
    {
        Custom::outputJsonArray(Query::selectFromTable($tableName) . Query::orderBy($orderBy), []);
    }

    /**
     * Output a JSON document by its ID
     *
     * @param string $tableName The table from which the document should be retrieved
     * @param mixed $docId The ID of the document to retrieve
     * @throws DocumentException If any is encountered
     */
    public static function outputById(string $tableName, mixed $docId): void
    {
        echo self::byId($tableName, $docId);
    }

    /**
     * Output JSON documents via a comparison on JSON fields
     *
     * @param string $tableName The table from which documents should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If any is encountered
     */
    public static function outputByFields(string $tableName, array $fields, ?FieldMatch $match = null,
                                          array $orderBy = []): void
    {
        Parameters::nameFields($fields);
        Custom::outputJsonArray(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
            Parameters::addFields($fields, []));
    }

    /**
     * Output JSON documents via a JSON containment query (`@>`; PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param mixed[]|object $criteria The criteria for the JSON containment query
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function outputByContains(string $tableName, array|object $criteria, array $orderBy = []): void
    {
        Custom::outputJsonArray(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
            Parameters::json(':criteria', $criteria));
    }

    /**
     * Output JSON documents via a JSON Path match query (`@?`; PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param string $path The JSON Path match string
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function outputByJsonPath(string $tableName, string $path, array $orderBy = []): void
    {
        Custom::outputJsonArray(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
    }

    /**
     * Output JSON documents via a comparison on JSON fields, returning only the first result
     *
     * @param string $tableName The table from which the document should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If any is encountered
     */
    public static function outputFirstByFields(string $tableName, array $fields, ?FieldMatch $match = null,
                                               array $orderBy = []): void
    {
        echo self::firstByFields($tableName, $fields, $match, $orderBy);
    }

    /**
     * Output JSON documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param mixed[]|object $criteria The criteria for the JSON containment query
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function outputFirstByContains(string $tableName, array|object $criteria, array $orderBy = []): void
    {
        echo self::firstByContains($tableName, $criteria, $orderBy);
    }

    /**
     * Output JSON documents via a JSON Path match query (`@?`), returning only the first result (PostgreSQL only)
     *
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param string $path The JSON Path match string
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function outputFirstByJsonPath(string $tableName, string $path, array $orderBy = []): void
    {
        echo self::firstByJsonPath($tableName, $path, $orderBy);
    }

    /**
     * Set the content type of this page's output to JSON
     */
    public static function setContentType(): void
    {
        header('Content-Type: application/json; charset=UTF-8');
    }
}