pdo-document/src/Find.php

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

declare(strict_types=1);

namespace BitBadger\PDODocument;

use BitBadger\InspiredByFSharp\Option;
use BitBadger\PDODocument\Mapper\DocumentMapper;

/**
 * Functions to retrieve documents as domain objects
 */
class Find
{
    /**
     * Retrieve all documents in the given table
     *
     * @template TDoc The type of document to be retrieved
     * @param string $tableName The table from which documents should be retrieved
     * @param class-string<TDoc> $className The name of the class to be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return DocumentList<TDoc> A list of all documents from the table
     * @throws DocumentException If any is encountered
     */
    public static function all(string $tableName, string $className, array $orderBy = []): DocumentList
    {
        return Custom::list(Query::selectFromTable($tableName) . Query::orderBy($orderBy), [],
            new DocumentMapper($className));
    }

    /**
     * Retrieve a document by its ID (returns false if not found)
     *
     * @template TDoc The type of document to be retrieved
     * @param string $tableName The table from which the document should be retrieved
     * @param mixed $docId The ID of the document to retrieve
     * @param class-string<TDoc> $className The name of the class to be retrieved
     * @return Option<TDoc> A `Some` instance if the document is found, `None` otherwise
     * @throws DocumentException If any is encountered
     */
    public static function byId(string $tableName, mixed $docId, string $className): Option
    {
        return Custom::single(Query\Find::byId($tableName, $docId), Parameters::id($docId),
            new DocumentMapper($className));
    }

    /**
     * Retrieve documents via a comparison on JSON fields
     *
     * @template TDoc The type of document to be retrieved
     * @param string $tableName The table from which documents should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param class-string<TDoc> $className The name of the class to be retrieved
     * @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 DocumentList<TDoc> A list of documents matching the given field comparison
     * @throws DocumentException If any is encountered
     */
    public static function byFields(string $tableName, array $fields, string $className,
                                    ?FieldMatch $match = null, array $orderBy = []): DocumentList
    {
        Parameters::nameFields($fields);
        return Custom::list(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
            Parameters::addFields($fields, []), new DocumentMapper($className));
    }

    /**
     * Retrieve documents via a JSON containment query (`@>`; PostgreSQL only)
     *
     * @template TDoc The type of document to be retrieved
     * @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 class-string<TDoc> $className The name of the class to be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return DocumentList<TDoc> A list 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, string $className,
                                      array $orderBy = []): DocumentList
    {
        return Custom::list(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
            Parameters::json(':criteria', $criteria), new DocumentMapper($className));
    }

    /**
     * Retrieve documents via a JSON Path match query (`@?`; PostgreSQL only)
     *
     * @template TDoc The type of document to be retrieved
     * @param string $tableName The name of the table from which documents should be retrieved
     * @param string $path The JSON Path match string
     * @param class-string<TDoc> $className The name of the class to be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return DocumentList<TDoc> A list 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, string $className,
                                      array $orderBy = []): DocumentList
    {
        return Custom::list(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path],
            new DocumentMapper($className));
    }

    /**
     * Retrieve documents via a comparison on JSON fields, returning only the first result
     *
     * @template TDoc The type of document to be retrieved
     * @param string $tableName The table from which the document should be retrieved
     * @param Field[] $fields The field comparison to match
     * @param class-string<TDoc> $className The name of the class to be retrieved
     * @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 Option<TDoc> A `Some` instance with the first document if any matches are found, `None` otherwise
     * @throws DocumentException If any is encountered
     */
    public static function firstByFields(string $tableName, array $fields, string $className,
                                         ?FieldMatch $match = null, array $orderBy = []): Option
    {
        Parameters::nameFields($fields);
        return Custom::single(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
            Parameters::addFields($fields, []), new DocumentMapper($className));
    }

    /**
     * Retrieve documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only)
     *
     * @template TDoc The type of document to be retrieved
     * @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 class-string<TDoc> $className The name of the class to be retrieved
     * @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
     * @return Option<TDoc> A `Some` instance with the first document if any matches are found, `None` otherwise
     * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
     */
    public static function firstByContains(string $tableName, array|object $criteria, string $className,
                                           array $orderBy = []): Option
    {
        return Custom::single(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
            Parameters::json(':criteria', $criteria), new DocumentMapper($className));
    }

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