v1.1 (#9)

Add JSON string and output support

Reviewed-on: #9

README.md

@@ -12,7 +12,7 @@ This library allows SQLite and PostgreSQL to be treated as document databases. I
 
 ### Connection Details
 
-The static variable `Configuration::$pdoDSN` must be set to the [PDO data source name](https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters) for your database. `Configuration` also has `$username`, `$password`, and `$options` variables that will be used to construct the PDO object it will use for data access.
+The [PDO data source name](https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters) must be provided via `Configuration::useDSN()`. `Configuration` also has `$username`, `$password`, and `$options` variables that will be used to construct the PDO object it will use for data access.
 
 ### Document Identifiers
 
@@ -29,4 +29,4 @@ In all generated scenarios, if the ID value is not 0 or blank, that ID will be u
 
 ## Usage
 
-Documentation for this library is not complete (writing it is one of the goals before the “beta” tag is dropped); however, its structure is very similar to the .NET version, so [its documentation will help](https://bitbadger.solutions/open-source/relational-documents/basic-usage.html) until its project specific documentation is developed. Things like `Count.All()` become `Count::all`, and all the `byField` operations are named `byFields` and take an array of fields.
+Full documentation [is available on the project site](https://relationaldocs.bitbadger.solutions/php/).

composer.json

@@ -14,17 +14,19 @@
   "support": {
     "email": "daniel@bitbadger.solutions",
     "source": "https://git.bitbadger.solutions/bit-badger/pdo-document",
-    "rss": "https://git.bitbadger.solutions/bit-badger/pdo-document.rss"
+    "rss": "https://git.bitbadger.solutions/bit-badger/pdo-document.rss",
+    "docs": "https://bitbadger.solutions/open-source/pdo-document/"
   },
   "require": {
-    "php": ">=8.2",
+    "php": "8.2 - 8.3",
+    "bit-badger/inspired-by-fsharp": "^1",
     "netresearch/jsonmapper": "^4",
-    "ext-pdo": "*",
+    "ext-pdo": "*"
-    "phpoption/phpoption": "^1.9"
   },
   "require-dev": {
-    "phpunit/phpunit": "^11",
+    "square/pjson": "^0.5.0",
-    "square/pjson": "^0.5.0"
+    "phpstan/phpstan": "^1.12",
+    "pestphp/pest": "^3.2"
   },
   "autoload": {
     "psr-4": {
@@ -36,13 +38,17 @@
   "autoload-dev": {
     "psr-4": {
       "Test\\": "./tests",
-      "Test\\Unit\\": "./tests/unit",
+      "Test\\Integration\\": "./tests/Integration",
-      "Test\\Integration\\": "./tests/integration",
+      "Test\\Integration\\PostgreSQL\\": "./tests/Integration/PostgreSQL",
-      "Test\\Integration\\PostgreSQL\\": "./tests/integration/postgresql",
+      "Test\\Integration\\SQLite\\": "./tests/Integration/SQLite"
-      "Test\\Integration\\SQLite\\": "./tests/integration/sqlite"
     }
   },
   "archive": {
     "exclude": [ "/tests", "/.gitattributes", "/.gitignore", "/.git", "/composer.lock" ]
+  },
+  "config": {
+    "allow-plugins": {
+      "pestphp/pest-plugin": true
+    }
   }
 }

phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.3/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
+    <testsuites>
+        <testsuite name="Test Suite">
+            <directory suffix="Test.php">./tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory suffix=".php">./app</directory>
+            <directory suffix=".php">./src</directory>
+        </include>
+    </source>
+</phpunit>

src/AutoId.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 

src/Configuration.php

@@ -1,7 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use BitBadger\InspiredByFSharp\Option;
+use Exception;
 use PDO;
 
 /**
@@ -20,51 +28,78 @@ class Configuration
      */
     public static int $idStringLength = 16;
 
-    /** @var string The data source name (DSN) of the connection string */
-    public static string $pdoDSN = '';
-
     /** @var string|null The username to use to establish a data connection (use env PDO_DOC_USERNAME if possible) */
     public static ?string $username = null;
 
     /** @var string|null The password to use to establish a data connection (use env PDO_DOC_PASSWORD if possible) */
     public static ?string $password = null;
 
-    /** @var array|null Options to use for connections (driver-specific) */
+    /** @var mixed[]|null Options to use for connections (driver-specific) */
     public static ?array $options = null;
 
-    /** @var Mode|null The mode in which the library is operating (filled after first connection if not configured) */
+    /** @var Option<Mode> The mode in which the library is operating */
-    public static ?Mode $mode = null;
+    public static Option $mode;
+
+    /** @var Option<string> The data source name (DSN) of the connection string */
+    private static Option $pdoDSN;
 
     /** @var PDO|null The PDO instance to use for database commands */
-    private static ?PDO $_pdo = null;
+    private static ?PDO $pdo = null;
+
+    /**
+     * Use a Data Source Name (DSN)
+     *
+     * @param string $dsn The data source name to use (driver:[parameters])
+     * @throws DocumentException If a DSN does not start with `pgsql:` or `sqlite:`
+     */
+    public static function useDSN(string $dsn): void
+    {
+        if (empty($dsn)) {
+            self::$mode = self::$pdoDSN = Option::None();
+        } else {
+            self::$mode   = Option::Some(Mode::deriveFromDSN($dsn));
+            self::$pdoDSN = Option::Some($dsn);
+        }
+    }
 
     /**
      * Retrieve a new connection to the database
      *
      * @return PDO A new connection to the SQLite database with foreign key support enabled
-     * @throws DocumentException If this is called before a connection string is set
+     * @throws Exception If this is called before a connection string is set
      */
     public static function dbConn(): PDO
     {
-        if (is_null(self::$_pdo)) {
+        if (is_null(self::$pdo)) {
-            if (empty(self::$pdoDSN)) {
+            $dsn = self::$pdoDSN->getOrThrow(fn()
-                throw new DocumentException('Please provide a data source name (DSN) before attempting data access');
+                => new DocumentException('Please provide a data source name (DSN) before attempting data access'));
-            }
+            self::$pdo = new PDO($dsn, $_ENV['PDO_DOC_USERNAME'] ?? self::$username,
-            self::$_pdo = new PDO(self::$pdoDSN, $_ENV['PDO_DOC_USERNAME'] ?? self::$username,
                 $_ENV['PDO_DOC_PASSWORD'] ?? self::$password, self::$options);
-
-            if (is_null(self::$mode)) {
-                $driver = self::$_pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
-                self::$mode = match ($driver) {
-                    'pgsql' => Mode::PgSQL,
-                    'sqlite' => Mode::SQLite,
-                    default => throw new DocumentException(
-                        "Unsupported driver $driver: this library currently supports PostgreSQL and SQLite")
-                };
-            }
         }
 
-        return self::$_pdo;
+        return self::$pdo;
+    }
+
+    /**
+     * Retrieve the mode for the current database connection
+     *
+     * @return Mode The mode for the current database connection
+     * @throws Exception If the database mode has not been set
+     */
+    public static function mode(?string $process = null): Mode
+    {
+        return self::$mode->getOrThrow(fn()
+            => new DocumentException('Database mode not set' . (is_null($process) ? '' : "; cannot $process")));
+    }
+
+    /**
+     * You probably don't mean to be calling this; it is here for testing only
+     *
+     * @param Mode|null $mode The mode to set
+     */
+    public static function overrideMode(?Mode $mode): void
+    {
+        self::$mode = Option::of($mode);
     }
 
     /**
@@ -72,6 +107,6 @@ class Configuration
      */
     public static function resetPDO(): void
     {
-        self::$_pdo = null;
+        self::$pdo = null;
     }
 }

src/Count.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -25,23 +31,23 @@ class Count
      * Count matching documents using a comparison on JSON fields
      *
      * @param string $tableName The name of the table in which documents should be counted
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return int The count of documents matching the field comparison
      * @throws DocumentException If one is encountered
      */
     public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): int
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        return Custom::scalar(Query\Count::byFields($tableName, $namedFields, $match),
+        return Custom::scalar(Query\Count::byFields($tableName, $fields, $match), Parameters::addFields($fields, []),
-            Parameters::addFields($namedFields, []), new CountMapper());
+            new CountMapper());
     }
 
     /**
      * Count matching documents using a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be counted
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @return int The number of documents matching the JSON containment query
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */

src/Custom.php

@@ -1,12 +1,18 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
-use BitBadger\PDODocument\Mapper\Mapper;
+use BitBadger\InspiredByFSharp\Option;
+use BitBadger\PDODocument\Mapper\{Mapper, StringMapper};
 use PDO;
 use PDOException;
 use PDOStatement;
-use PhpOption\{None, Option, Some};
 
 /**
  * Functions to execute custom queries
@@ -17,7 +23,7 @@ class Custom
      * Prepare a query for execution and run it
      *
      * @param string $query The query to be run
-     * @param array $parameters The parameters for the query
+     * @param array<string, mixed> $parameters The parameters for the query
      * @return PDOStatement The result of executing the query
      * @throws DocumentException If the query execution is unsuccessful
      */
@@ -39,7 +45,7 @@ class Custom
                 is_bool($value) => PDO::PARAM_BOOL,
                 is_int($value)  => PDO::PARAM_INT,
                 is_null($value) => PDO::PARAM_NULL,
-                default         => PDO::PARAM_STR
+                default         => PDO::PARAM_STR,
             };
             $stmt->bindValue($key, $value, $dataType);
         }
@@ -61,7 +67,7 @@ class Custom
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return DocumentList<TDoc> The items matching the query
      * @throws DocumentException If any is encountered
@@ -76,7 +82,7 @@ class Custom
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return TDoc[] The items matching the query
      * @throws DocumentException If any is encountered
@@ -86,12 +92,47 @@ class Custom
         return iterator_to_array(self::list($query, $parameters, $mapper)->items());
     }
 
+    /**
+     * Execute a query that returns a JSON string of results
+     *
+     * @param string $query The query to be executed
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
+     * @return string A JSON array with the results (empty results will be `[]`)
+     * @throws DocumentException If any is encountered
+     */
+    public static function jsonArray(string $query, array $parameters): string
+    {
+        return '[' . implode(',', self::array($query, $parameters, new StringMapper('data'))) . ']';
+    }
+
+    /**
+     * Execute a query, echoing the results to the output
+     *
+     * @param string $query The query to be executed
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
+     * @throws DocumentException If any is encountered
+     */
+    public static function outputJsonArray(string $query, array $parameters): void
+    {
+        $isFirst = true;
+        echo '[';
+        foreach (self::list($query, $parameters, new StringMapper('data'))->items() as $doc) {
+            if ($isFirst) {
+                $isFirst = false;
+            } else {
+                echo ',';
+            }
+            echo $doc;
+        }
+        echo ']';
+    }
+
     /**
      * Execute a query that returns one or no results (returns false if not found)
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed (will have "LIMIT 1" appended)
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return Option<TDoc> A `Some` instance if the item is found, `None` otherwise
      * @throws DocumentException If any is encountered
@@ -100,17 +141,30 @@ class Custom
     {
         try {
             $stmt = &self::runQuery("$query LIMIT 1", $parameters);
-            return ($first = $stmt->fetch(PDO::FETCH_ASSOC)) ? Some::create($mapper->map($first)) : None::create();
+            return ($first = $stmt->fetch(PDO::FETCH_ASSOC)) ? Option::Some($mapper->map($first)) : Option::None();
         } finally {
             $stmt = null;
         }
     }
 
+    /**
+     * Execute a query that returns one or no JSON results
+     *
+     * @param string $query The query to be executed (will have "LIMIT 1" appended)
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
+     * @return string The JSON document (returns `{}` if no document is found)
+     * @throws DocumentException If any is encountered
+     */
+    public static function jsonSingle(string $query, array $parameters): string
+    {
+        return self::single($query, $parameters, new StringMapper('data'))->getOrDefault('{}');
+    }
+
     /**
      * Execute a query that does not return a value
      *
      * @param string $query The query to execute
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @throws DocumentException If any is encountered
      */
     public static function nonQuery(string $query, array $parameters): void
@@ -127,7 +181,7 @@ class Custom
      *
      * @template T The scalar type to return
      * @param string $query The query to retrieve the value
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<T> $mapper The mapper to obtain the result
      * @return mixed|false|T The scalar value if found, false if not
      * @throws DocumentException If any is encountered

src/Definition.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -24,7 +30,7 @@ class Definition
      *
      * @param string $tableName The name of the table which should be indexed
      * @param string $indexName The name of the index
-     * @param array $fields Fields which should be a part of this index
+     * @param string[] $fields Fields which should be a part of this index
      * @throws DocumentException If any is encountered
      */
     public static function ensureFieldIndex(string $tableName, string $indexName, array $fields): void

src/Delete.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -23,22 +29,21 @@ class Delete
      * Delete documents by matching a comparison on JSON fields
      *
      * @param string $tableName The table from which documents should be deleted
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
     public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): void
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        Custom::nonQuery(Query\Delete::byFields($tableName, $namedFields, $match),
+        Custom::nonQuery(Query\Delete::byFields($tableName, $fields, $match), Parameters::addFields($fields, []));
-            Parameters::addFields($namedFields, []));
     }
 
     /**
      * Delete documents matching a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table from which documents should be deleted
-     * @param array|object $criteria The JSON containment query values
+     * @param mixed[]|object $criteria The JSON containment query values
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria): void

src/Document.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -11,14 +17,14 @@ class Document
      * Insert a new document
      *
      * @param string $tableName The name of the table into which the document should be inserted
-     * @param array|object $document The document to be inserted
+     * @param mixed[]|object $document The document to be inserted
      * @throws DocumentException If any is encountered
      */
     public static function insert(string $tableName, array|object $document): void
     {
         $doInsert = fn() => Custom::nonQuery(Query::insert($tableName), Parameters::json(':data', $document));
 
-        if (Configuration::$autoId == AutoId::None) {
+        if (Configuration::$autoId === AutoId::None) {
             $doInsert();
             return;
         }
@@ -41,7 +47,7 @@ class Document
      * Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
      *
      * @param string $tableName The name of the table to which the document should be saved
-     * @param array|object $document The document to be saved
+     * @param mixed[]|object $document The document to be saved
      * @throws DocumentException If any is encountered
      */
     public static function save(string $tableName, array|object $document): void
@@ -54,7 +60,7 @@ class Document
      *
      * @param string $tableName The table in which the document should be updated
      * @param mixed $docId The ID of the document to be updated
-     * @param array|object $document The document to be updated
+     * @param mixed[]|object $document The document to be updated
      * @throws DocumentException If any is encountered
      */
     public static function update(string $tableName, mixed $docId, array|object $document): void

src/DocumentException.php

@@ -1,14 +1,21 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
 use Exception;
+use Stringable;
 use Throwable;
 
 /**
  * Exceptions occurring during document processing
  */
-class DocumentException extends Exception
+class DocumentException extends Exception implements Stringable
 {
     /**
      * Constructor

src/DocumentIndex.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 

src/DocumentList.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -15,8 +21,11 @@ use PDOStatement;
  */
 class DocumentList
 {
-    /** @var TDoc|null $_first The first item from the results  */
+    /** @var TDoc|null $first The first item from the results  */
-    private mixed $_first = null;
+    private mixed $first = null;
+
+    /** @var bool $isConsumed This is set to true once the generator has been exhausted */
+    private bool $isConsumed = false;
 
     /**
      * Constructor
@@ -26,43 +35,15 @@ class DocumentList
      */
     private function __construct(private ?PDOStatement &$result, private readonly Mapper $mapper)
     {
-        if ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
+        if (!is_null($this->result)) {
-            $this->_first = $this->mapper->map($row);
+            if ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
-        } else {
+                $this->first = $this->mapper->map($row);
-            $this->result = null;
+            } else {
+                $this->result = null;
+            }
         }
     }
 
-    /**
-     * Construct a new document list
-     *
-     * @param string $query The query to run to retrieve results
-     * @param array $parameters An associative array of parameters for the query
-     * @param Mapper<TDoc> $mapper A mapper to deserialize JSON documents
-     * @return static The document list instance
-     * @throws DocumentException If any is encountered
-     */
-    public static function create(string $query, array $parameters, Mapper $mapper): static
-    {
-        $stmt = &Custom::runQuery($query, $parameters);
-        return new static($stmt, $mapper);
-    }
-
-    /**
-     * The items from the query result
-     *
-     * @return Generator<TDoc> The items from the document list
-     */
-    public function items(): Generator
-    {
-        if (!$this->result) return;
-        yield $this->_first;
-        while ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
-            yield $this->mapper->map($row);
-        }
-        $this->result = null;
-    }
-
     /**
      * Does this list have items remaining?
      *
@@ -73,6 +54,80 @@ class DocumentList
         return !is_null($this->result);
     }
 
+    /**
+     * The items from the query result
+     *
+     * @return Generator<TDoc> The items from the document list
+     * @throws DocumentException If this is called once the generator has been consumed
+     */
+    public function items(): Generator
+    {
+        if (!$this->result) {
+            if ($this->isConsumed) {
+                throw new DocumentException('Cannot call items() multiple times');
+            }
+            $this->isConsumed = true;
+            return;
+        }
+        if (!$this->first) {
+            $this->isConsumed = true;
+            $this->result     = null;
+            return;
+        }
+        yield $this->first;
+        while ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
+            yield $this->mapper->map($row);
+        }
+        $this->isConsumed = true;
+        $this->result     = null;
+    }
+
+    /**
+     * Map items by consuming the generator
+     *
+     * @template U The type to which each item should be mapped
+     * @param callable(TDoc): U $map The mapping function
+     * @return Generator<U> The result of the mapping function
+     * @throws DocumentException If this is called once the generator has been consumed
+     */
+    public function map(callable $map): Generator
+    {
+        foreach ($this->items() as $item) {
+            yield $map($item);
+        }
+    }
+
+    /**
+     * Iterate the generator, running the given function for each item
+     *
+     * @param callable(TDoc): void $f The function to run for each item
+     * @throws DocumentException If this is called once the generator has been consumed
+     */
+    public function iter(callable $f): void
+    {
+        foreach ($this->items() as $item) {
+            $f($item);
+        }
+    }
+
+    /**
+     * Iterate the generator, extracting key/value pairs returned as an associative array
+     *
+     * @template TValue The type for the mapped value
+     * @param callable(TDoc): (int|string) $keyFunc The function to extract a key from the document
+     * @param callable(TDoc): TValue $valueFunc The function to extract a value from the document
+     * @return TValue[] An associative array of values, keyed by the extracted keys
+     * @throws DocumentException If this is called once the generator has been consumed
+     */
+    public function mapToArray(callable $keyFunc, callable $valueFunc): array
+    {
+        $results = [];
+        foreach ($this->items() as $item) {
+            $results[$keyFunc($item)] = $valueFunc($item);
+        }
+        return $results;
+    }
+
     /**
      * Ensure the statement is destroyed if the generator is not exhausted
      */
@@ -80,4 +135,19 @@ class DocumentList
     {
         if (!is_null($this->result)) $this->result = null;
     }
+
+    /**
+     * Construct a new document list
+     *
+     * @param string $query The query to run to retrieve results
+     * @param array<string, mixed> $parameters An associative array of parameters for the query
+     * @param Mapper<TDoc> $mapper A mapper to deserialize JSON documents
+     * @return self<TDoc> The document list instance
+     * @throws DocumentException If any is encountered
+     */
+    public static function create(string $query, array $parameters, Mapper $mapper): self
+    {
+        $stmt = &Custom::runQuery($query, $parameters);
+        return new self($stmt, $mapper);
+    }
 }

src/Exists.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -33,16 +39,16 @@ class Exists
      */
     public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): bool
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        return Custom::scalar(Query\Exists::byFields($tableName, $namedFields, $match),
+        return Custom::scalar(Query\Exists::byFields($tableName, $fields, $match), Parameters::addFields($fields, []),
-            Parameters::addFields($namedFields, []), new ExistsMapper());
+            new ExistsMapper());
     }
 
     /**
      * Determine if documents exist by a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The name of the table in which document existence should be determined
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @return bool True if any documents match the JSON containment query, false if not
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */

src/Field.php

@@ -1,7 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use Exception;
+
 /**
  * Criteria for a field WHERE clause
  */
@@ -19,59 +27,110 @@ class Field
      * @param string $paramName The name of the parameter to which this should be bound
      * @param string $qualifier A table qualifier for the `data` column
      */
-    public function __construct(public string $fieldName = '', public Op $op = Op::EQ, public mixed $value = '',
+    public function __construct(public string $fieldName = '', public Op $op = Op::Equal, public mixed $value = '',
                                 public string $paramName = '', public string $qualifier = '') { }
 
     /**
      * Append the parameter name and value to the given associative array
      *
-     * @param array $existing The existing parameters
+     * @param array<string, mixed> $existing The existing parameters
-     * @return array The given parameter array with this field's name and value appended
+     * @return array<string, mixed> The given parameter array with this field's name and value(s) appended
      */
     public function appendParameter(array $existing): array
     {
         switch ($this->op) {
-            case Op::EX:
+            case Op::Exists:
-            case Op::NEX:
+            case Op::NotExists:
                 break;
-            case Op::BT:
+            case Op::Between:
                 $existing["{$this->paramName}min"] = $this->value[0];
                 $existing["{$this->paramName}max"] = $this->value[1];
                 break;
+            case Op::In:
+                for ($idx = 0; $idx < count($this->value); $idx++) {
+                    $existing["{$this->paramName}_$idx"] = $this->value[$idx];
+                }
+                break;
+            case Op::InArray:
+                $mkString = Configuration::mode("Append parameters for InArray condition") === Mode::PgSQL;
+                $values   = $this->value['values'];
+                for ($idx = 0; $idx < count($values); $idx++) {
+                    $existing["{$this->paramName}_$idx"] = $mkString ? "$values[$idx]" : $values[$idx];
+                }
+                break;
             default:
                 $existing[$this->paramName] = $this->value;
         }
         return $existing;
     }
 
+    /**
+     * Derive the path for this field
+     *
+     * @param bool $asJSON Whether the field should be treated as JSON in the query (optional, default false)
+     * @return string The path for this field
+     * @throws Exception If the database mode has not been set
+     */
+    public function path(bool $asJSON = false): string
+    {
+        $extra = $asJSON ? '' : '>';
+        if (str_contains($this->fieldName, '.')) {
+            $mode = Configuration::mode('determine field path');
+            if ($mode === Mode::PgSQL) {
+                return "data#>$extra'{" . implode(',', explode('.', $this->fieldName)) . "}'";
+            }
+            if ($mode === Mode::SQLite) {
+                $parts = explode('.', $this->fieldName);
+                $last  = array_pop($parts);
+                return "data->'" . implode("'->'", $parts) . "'->$extra'$last'";
+            }
+        }
+        return "data->$extra'$this->fieldName'";
+    }
+
     /**
      * Get the WHERE clause fragment for this parameter
      *
      * @return string The WHERE clause fragment for this parameter
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception|DocumentException If the database mode has not been set
      */
     public function toWhere(): string
     {
-        $fieldName = ($this->qualifier == '' ? '' : "$this->qualifier.") . 'data' . match (true) {
+        $mode        = Configuration::mode('make field WHERE clause');
-            !str_contains($this->fieldName, '.') => "->>'$this->fieldName'",
+        $fieldName   = (empty($this->qualifier) ? '' : "$this->qualifier.") . $this->path($this->op === Op::InArray);
-            Configuration::$mode == Mode::PgSQL  => "#>>'{" . implode(',', explode('.', $this->fieldName)) . "}'",
+        $fieldPath   = match ($mode) {
-            Configuration::$mode == Mode::SQLite => "->>'" . implode("'->>'", explode('.', $this->fieldName)) . "'",
-            default => throw new DocumentException('Database mode not set; cannot make field WHERE clause')
-        };
-        $fieldPath = match (Configuration::$mode) {
             Mode::PgSQL => match (true) {
-                $this->op == Op::BT      => is_numeric($this->value[0]) ? "($fieldName)::numeric" : $fieldName,
+                $this->op === Op::Between,
-                is_numeric($this->value) => "($fieldName)::numeric",
+                $this->op === Op::In      => is_numeric($this->value[0]) ? "($fieldName)::numeric" : $fieldName,
-                default                  => $fieldName
+                is_numeric($this->value)  => "($fieldName)::numeric",
+                default                   => $fieldName,
             },
-            default => $fieldName
+            default => $fieldName,
         };
         $criteria = match ($this->op) {
-            Op::EX, Op::NEX => '',
+            Op::Exists,
-            Op::BT          => " {$this->paramName}min AND {$this->paramName}max",
+            Op::NotExists => '',
-            default         => " $this->paramName"
+            Op::Between   => " {$this->paramName}min AND {$this->paramName}max",
+            Op::In        => ' (' . $this->inParameterNames() . ')',
+            Op::InArray   => $mode === Mode::PgSQL ? ' ARRAY[' . $this->inParameterNames() . ']' : '',
+            default       => " $this->paramName",
         };
-        return $fieldPath . ' ' . $this->op->toString() . $criteria;
+        return $mode === Mode::SQLite && $this->op === Op::InArray
+            ? "EXISTS (SELECT 1 FROM json_each({$this->value['table']}.data, '\$.$this->fieldName') WHERE value IN ("
+                    . $this->inParameterNames() . '))'
+            : $fieldPath . ' ' . $this->op->toSQL() . $criteria;
+    }
+
+    /**
+     * Create parameter names for an IN clause
+     *
+     * @return string A comma-delimited string of parameter names
+     */
+    private function inParameterNames(): string
+    {
+        $values = $this->op === Op::In ? $this->value : $this->value['values'];
+        return implode(', ',
+            array_map(fn($value, $key) => "{$this->paramName}_$key", $values, range(0, count($values) - 1)));
     }
 
     /**
@@ -80,11 +139,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for which equality will be checked
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function EQ(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function equal(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::EQ, $value, $paramName);
+        return new self($fieldName, Op::Equal, $value, $paramName);
+    }
+
+    /**
+     * Create an equals (=) field criterion _(alias for `Field.equal`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for which equality will be checked
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function EQ(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::equal($fieldName, $value, $paramName);
     }
 
     /**
@@ -93,11 +165,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the greater than comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function GT(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function greater(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::GT, $value, $paramName);
+        return new self($fieldName, Op::Greater, $value, $paramName);
+    }
+
+    /**
+     * Create a greater than (>) field criterion _(alias for `Field.greater`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for the greater than comparison
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function GT(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::greater($fieldName, $value, $paramName);
     }
 
     /**
@@ -106,11 +191,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the greater than or equal to comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function GE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function greaterOrEqual(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::GE, $value, $paramName);
+        return new self($fieldName, Op::GreaterOrEqual, $value, $paramName);
+    }
+
+    /**
+     * Create a greater than or equal to (>=) field criterion _(alias for `Field.greaterOrEqual`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for the greater than or equal to comparison
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function GE(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::greaterOrEqual($fieldName, $value, $paramName);
     }
 
     /**
@@ -119,11 +217,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the less than comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function LT(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function less(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::LT, $value, $paramName);
+        return new self($fieldName, Op::Less, $value, $paramName);
+    }
+
+    /**
+     * Create a less than (<) field criterion _(alias for `Field.less`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for the less than comparison
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function LT(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::less($fieldName, $value, $paramName);
     }
 
     /**
@@ -132,11 +243,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the less than or equal to comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function LE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function lessOrEqual(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::LE, $value, $paramName);
+        return new self($fieldName, Op::LessOrEqual, $value, $paramName);
+    }
+
+    /**
+     * Create a less than or equal to (<=) field criterion _(alias for `Field.lessOrEqual`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for the less than or equal to comparison
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function LE(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::lessOrEqual($fieldName, $value, $paramName);
     }
 
     /**
@@ -145,11 +269,24 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the not equals comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function NE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function notEqual(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::NE, $value, $paramName);
+        return new self($fieldName, Op::NotEqual, $value, $paramName);
+    }
+
+    /**
+     * Create a not equals (<>) field criterion _(alias for `Field.notEqual`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $value The value for the not equals comparison
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function NE(string $fieldName, mixed $value, string $paramName = ''): self
+    {
+        return self::notEqual($fieldName, $value, $paramName);
     }
 
     /**
@@ -159,32 +296,109 @@ class Field
      * @param mixed $minValue The lower value for range
      * @param mixed $maxValue The upper value for the range
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function BT(string $fieldName, mixed $minValue, mixed $maxValue, string $paramName = ''): static
+    public static function between(string $fieldName, mixed $minValue, mixed $maxValue, string $paramName = ''): self
     {
-        return new static($fieldName, Op::BT, [$minValue, $maxValue], $paramName);
+        return new self($fieldName, Op::Between, [$minValue, $maxValue], $paramName);
+    }
+
+    /**
+     * Create a BETWEEN field criterion _(alias for `Field.between`)_
+     *
+     * @param string $fieldName The name of the field against which the value will be compared
+     * @param mixed $minValue The lower value for range
+     * @param mixed $maxValue The upper value for the range
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function BT(string $fieldName, mixed $minValue, mixed $maxValue, string $paramName = ''): self
+    {
+        return self::between($fieldName, $minValue, $maxValue, $paramName);
+    }
+
+    /**
+     * Create an IN field criterion
+     *
+     * @param string $fieldName The name of the field against which the values will be compared
+     * @param mixed[] $values The potential matching values for the field
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function in(string $fieldName, array $values, string $paramName = ''): self
+    {
+        return new self($fieldName, Op::In, $values, $paramName);
+    }
+
+    /**
+     * Create an IN ARRAY field criterion
+     *
+     * @param string $fieldName The name of the field against which the values will be compared
+     * @param string $tableName The table name where this field is located
+     * @param mixed[] $values The potential matching values for the field
+     * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
+     * @return self The field with the requested criterion
+     */
+    public static function inArray(string $fieldName, string $tableName, array $values, string $paramName = ''): self
+    {
+        return new self($fieldName, Op::InArray, ['table' => $tableName, 'values' => $values], $paramName);
     }
 
     /**
      * Create an exists (IS NOT NULL) field criterion
      *
      * @param string $fieldName The name of the field for which existence will be checked
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function EX(string $fieldName): static
+    public static function exists(string $fieldName): self
     {
-        return new static($fieldName, Op::EX, '', '');
+        return new self($fieldName, Op::Exists, '', '');
+    }
+
+    /**
+     * Create an exists (IS NOT NULL) field criterion _(alias for `Field.exists`)_
+     *
+     * @param string $fieldName The name of the field for which existence will be checked
+     * @return self The field with the requested criterion
+     */
+    public static function EX(string $fieldName): self
+    {
+        return self::exists($fieldName);
     }
 
     /**
      * Create a not exists (IS NULL) field criterion
      *
      * @param string $fieldName The name of the field for which non-existence will be checked
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function NEX(string $fieldName): static
+    public static function notExists(string $fieldName): self
     {
-        return new static($fieldName, Op::NEX, '', '');
+        return new self($fieldName, Op::NotExists, '', '');
+    }
+
+    /**
+     * Create a not exists (IS NULL) field criterion _(alias for `Field.notExists`)_
+     *
+     * @param string $fieldName The name of the field for which non-existence will be checked
+     * @return self The field with the requested criterion
+     */
+    public static function NEX(string $fieldName): self
+    {
+        return self::notExists($fieldName);
+    }
+
+    /**
+     * Create a named fields (used for creating fields for ORDER BY clauses)
+     *
+     * Prepend the field name with 'n:' to treat the field as a number; prepend the field name with 'i:' to perform
+     * a case-insensitive ordering.
+     *
+     * @param string $name The name of the field, plus any direction for the ordering
+     * @return self
+     */
+    public static function named(string $name): self
+    {
+        return new self($name, Op::Equal, '', '');
     }
 }

src/FieldMatch.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -18,11 +24,11 @@ enum FieldMatch
      *
      * @return string The SQL keyword for this enumeration value
      */
-    public function toString(): string
+    public function toSQL(): string
     {
         return match ($this) {
             FieldMatch::All => 'AND',
-            FieldMatch::Any => 'OR'
+            FieldMatch::Any => 'OR',
         };
     }
 }

src/Find.php

@@ -1,9 +1,15 @@
-<?php declare(strict_types=1);
+<?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;
-use PhpOption\Option;
 
 /**
  * Functions to find documents
@@ -16,12 +22,14 @@ class Find
      * @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): DocumentList
+    public static function all(string $tableName, string $className, array $orderBy = []): DocumentList
     {
-        return Custom::list(Query::selectFromTable($tableName), [], new DocumentMapper($className));
+        return Custom::list(Query::selectFromTable($tableName) . Query::orderBy($orderBy), [],
+            new DocumentMapper($className));
     }
 
     /**
@@ -45,18 +53,19 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The table from which documents should be retrieved
-     * @param array|Field[] $fields The field comparison to match
+     * @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): DocumentList
+                                    ?FieldMatch $match = null, array $orderBy = []): DocumentList
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        return Custom::list(Query\Find::byFields($tableName, $namedFields, $match),
+        return Custom::list(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
-            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+            Parameters::addFields($fields, []), new DocumentMapper($className));
     }
 
     /**
@@ -64,15 +73,17 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The name of the table from which documents should be retrieved
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @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): DocumentList
+    public static function byContains(string $tableName, array|object $criteria, string $className,
+                                      array $orderBy = []): DocumentList
     {
-        return Custom::list(Query\Find::byContains($tableName), Parameters::json(':criteria', $criteria),
+        return Custom::list(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
-            new DocumentMapper($className));
+            Parameters::json(':criteria', $criteria), new DocumentMapper($className));
     }
 
     /**
@@ -82,12 +93,15 @@ class Find
      * @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): DocumentList
+    public static function byJsonPath(string $tableName, string $path, string $className,
+                                      array $orderBy = []): DocumentList
     {
-        return Custom::list(Query\Find::byJsonPath($tableName), [':path' => $path], new DocumentMapper($className));
+        return Custom::list(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path],
+            new DocumentMapper($className));
     }
 
     /**
@@ -95,18 +109,19 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The table from which the document should be retrieved
-     * @param array|Field[] $fields The field comparison to match
+     * @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): Option
+                                         ?FieldMatch $match = null, array $orderBy = []): Option
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        return Custom::single(Query\Find::byFields($tableName, $namedFields, $match),
+        return Custom::single(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
-            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+            Parameters::addFields($fields, []), new DocumentMapper($className));
     }
 
     /**
@@ -114,15 +129,17 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The name of the table from which documents should be retrieved
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @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): Option
+    public static function firstByContains(string $tableName, array|object $criteria, string $className,
+                                           array $orderBy = []): Option
     {
-        return Custom::single(Query\Find::byContains($tableName), Parameters::json(':criteria', $criteria),
+        return Custom::single(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
-            new DocumentMapper($className));
+            Parameters::json(':criteria', $criteria), new DocumentMapper($className));
     }
 
     /**
@@ -132,11 +149,14 @@ class Find
      * @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): Option
+    public static function firstByJsonPath(string $tableName, string $path, string $className,
+                                           array $orderBy = []): Option
     {
-        return Custom::single(Query\Find::byJsonPath($tableName), [':path' => $path], new DocumentMapper($className));
+        return Custom::single(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path],
+            new DocumentMapper($className));
     }
 }

src/Json.php

@@ -0,0 +1,252 @@
+<?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');
+    }
+}

src/Mapper/ArrayMapper.php

@@ -1,14 +1,23 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
 /**
  * A mapper that returns the associative array from the database
+ *
+ * @implements Mapper<array<string|int, mixed>>
  */
 class ArrayMapper implements Mapper
 {
     /**
      * @inheritDoc
+     * @return array<string|int, mixed> The array given as the parameter
      */
     public function map(array $result): array
     {

src/Mapper/CountMapper.php

@@ -1,15 +1,21 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
 /**
  * A mapper that returns the integer value of the first item in the results
+ *
+ * @implements Mapper<int>
  */
 class CountMapper implements Mapper
 {
-    /**
+    /** @inheritDoc */
-     * @inheritDoc
-     */
     public function map(array $result): int
     {
         return (int) $result[0];

src/Mapper/DocumentMapper.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
@@ -20,12 +26,12 @@ class DocumentMapper implements Mapper
      * @param class-string<TDoc> $className The type of class to be returned by this mapping
      * @param string $fieldName The name of the field (optional; defaults to `data`)
      */
-    public function __construct(public string $className, public string $fieldName = 'data') { }
+    public function __construct(public string $className, public string $fieldName = 'data') {}
 
     /**
      * Map a result to a domain class instance
      *
-     * @param array $result An associative array representing a single database result
+     * @param array<string|int, mixed> $result An associative array representing a single database result
      * @return TDoc The document, deserialized from its JSON representation
      * @throws DocumentException If the JSON cannot be deserialized
      */

src/Mapper/ExistsMapper.php

@@ -1,24 +1,32 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
-use BitBadger\PDODocument\{Configuration, DocumentException, Mode};
+use BitBadger\PDODocument\{Configuration, Mode};
+use Exception;
 
 /**
  * Map an EXISTS result to a boolean value
+ *
+ * @implements Mapper<bool>
  */
 class ExistsMapper implements Mapper
 {
     /**
      * @inheritDoc
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception If the database mode has not been set
      */
     public function map(array $result): bool
     {
-        return match (Configuration::$mode) {
+        return match (Configuration::mode('map existence result')) {
             Mode::PgSQL  => (bool)$result[0],
             Mode::SQLite => (int)$result[0] > 0,
-            default      => throw new DocumentException('Database mode not set; cannot map existence result'),
         };
     }
 }

src/Mapper/Mapper.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
@@ -12,7 +18,7 @@ interface Mapper
     /**
      * Map a result to the specified type
      *
-     * @param array $result An associative array representing a single database result
+     * @param array<string|int, mixed> $result An associative array representing a single database result
      * @return T The item mapped from the given result
      */
     public function map(array $result): mixed;

src/Mapper/StringMapper.php

@@ -1,9 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Mapper;
 
 /**
- * Map a string result from the
+ * Map a string result from the named field
  *
  * @implements Mapper<string>
  */
@@ -24,7 +30,7 @@ class StringMapper implements Mapper
         return match (false) {
             key_exists($this->fieldName, $result) => null,
             is_string($result[$this->fieldName])  => "{$result[$this->fieldName]}",
-            default                               => $result[$this->fieldName]
+            default                               => $result[$this->fieldName],
         };
     }
 }

src/Mode.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -12,4 +18,19 @@ enum Mode
 
     /** Storing documents in a SQLite database */
     case SQLite;
+
+    /**
+     * Derive the mode from the Data Source Name (DSN)
+     *
+     * @return Mode The database mode based on the DSN
+     * @throws DocumentException If the DSN does not start with `pgsql:` or `sqlite:`
+     */
+    public static function deriveFromDSN(string $dsn): Mode
+    {
+        return match (true) {
+            str_starts_with($dsn, 'pgsql:')  => Mode::PgSQL,
+            str_starts_with($dsn, 'sqlite:') => Mode::SQLite,
+            default => throw new DocumentException('This library currently supports PostgreSQL and SQLite'),
+        };
+    }
 }

src/Op.php

@@ -1,48 +1,60 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
 /**
- * The types of logical operations allowed for JSON fields
+ * The types of comparison operators allowed for JSON fields
  */
 enum Op
 {
     /** Equals (=) */
-    case EQ;
+    case Equal;
     /** Greater Than (>) */
-    case GT;
+    case Greater;
     /** Greater Than or Equal To (>=) */
-    case GE;
+    case GreaterOrEqual;
     /** Less Than (<) */
-    case LT;
+    case Less;
     /** Less Than or Equal To (<=) */
-    case LE;
+    case LessOrEqual;
     /** Not Equal to (<>) */
-    case NE;
+    case NotEqual;
     /** Between (BETWEEN) */
-    case BT;
+    case Between;
+    /** In (IN) */
+    case In;
+    /** In Array (PostgreSQL - ?|, SQLite - EXISTS / json_each / IN) */
+    case InArray;
     /** Exists (IS NOT NULL) */
-    case EX;
+    case Exists;
     /** Does Not Exist (IS NULL) */
-    case NEX;
+    case NotExists;
 
     /**
-     * Get the string representation of this operator
+     * Get the SQL representation of this operator
      *
      * @return string The operator to use in SQL statements
      */
-    public function toString(): string
+    public function toSQL(): string
     {
         return match ($this) {
-            Op::EQ  => "=",
+            Op::Equal           => "=",
-            Op::GT  => ">",
+            Op::Greater         => ">",
-            Op::GE  => ">=",
+            Op::GreaterOrEqual  => ">=",
-            Op::LT  => "<",
+            Op::Less            => "<",
-            Op::LE  => "<=",
+            Op::LessOrEqual     => "<=",
-            Op::NE  => "<>",
+            Op::NotEqual        => "<>",
-            Op::BT  => "BETWEEN",
+            Op::Between         => "BETWEEN",
-            Op::EX  => "IS NOT NULL",
+            Op::In              => "IN",
-            Op::NEX => "IS NULL"
+            Op::InArray         => "??|", // The actual operator is ?|, but needs to be escaped by doubling
+            Op::Exists          => "IS NOT NULL",
+            Op::NotExists       => "IS NULL",
         };
     }
 }

src/Parameters.php

@@ -1,7 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use Exception;
+
 /**
  * Functions to create parameters for queries
  */
@@ -11,19 +19,19 @@ class Parameters
      * Create an ID parameter (name ":id", key will be treated as a string)
      *
      * @param mixed $key The key representing the ID of the document
-     * @return array|string[] An associative array with an "@id" parameter/value pair
+     * @return array<string, mixed> An associative array with an "@id" parameter/value pair
      */
     public static function id(mixed $key): array
     {
-        return [':id' => is_int($key) || is_string($key) ? $key : "$key"];
+        return [':id' => ((is_int($key) || is_string($key)) ? $key : "$key")];
     }
 
     /**
      * Create a parameter with a JSON value
      *
      * @param string $name The name of the JSON parameter
-     * @param object|array $document The value that should be passed as a JSON string
+     * @param mixed[]|object $document The value that should be passed as a JSON string
-     * @return array An associative array with the named parameter/value pair
+     * @return array<string, string> An associative array with the named parameter/value pair
      */
     public static function json(string $name, object|array $document): array
     {
@@ -34,14 +42,16 @@ class Parameters
                 $name => method_exists($document, 'toJson') ? $document->toJson($flags) : json_encode($document, $flags)
             ];
         }
-        if (empty($document)) return [$name => json_encode($document, $flags)];
 
         $key = array_key_first($document);
-        if (is_array($document[$key]) && method_exists($document[$key][array_key_first($document[$key])], 'toJson')) {
+        if (is_array($document[$key])) {
-            return [
+            if (empty($document[$key])) return [$name => json_encode($document, $flags)];
-                $name => sprintf('{%s:[%s]}', json_encode($key, $flags),
+            if (method_exists($document[$key][array_key_first($document[$key])], 'toJson')) {
-                    implode(',', array_map(fn($it) => $it->toJson($flags), $document[$key])))
+                return [
-            ];
+                    $name => sprintf('{%s:[%s]}', json_encode($key, $flags),
+                        implode(',', array_map(fn($it) => $it->toJson($flags), $document[$key])))
+                ];
+            }
         }
         return [$name => json_encode($document, $flags)];
     }
@@ -49,23 +59,21 @@ class Parameters
     /**
      * Fill in parameter names for any fields missing one
      *
-     * @param array|Field[] $fields The fields for the query
+     * @param Field[] $fields The fields for the query (entries with no names will be modified)
-     * @return array|Field[] The fields, all with non-blank parameter names
      */
-    public static function nameFields(array $fields): array
+    public static function nameFields(array &$fields): void
     {
-        for ($idx = 0; $idx < sizeof($fields); $idx++) {
+        array_walk($fields, function (Field $field, int $idx) {
-            if ($fields[$idx]->paramName == '') $fields[$idx]->paramName = ":field$idx";
+            if (empty($field->paramName)) $field->paramName =":field$idx";
-        }
+        });
-        return $fields;
     }
 
     /**
      * Add field parameters to the given set of parameters
      *
-     * @param array|Field[] $fields The fields being compared in the query
+     * @param Field[] $fields The fields being compared in the query
-     * @param array $parameters An associative array of parameters to which the fields should be added
+     * @param array<string, mixed> $parameters An associative array of parameters to which the fields should be added
-     * @return array An associative array of parameter names and values with the fields added
+     * @return array<string, mixed> An associative array of parameter names and values with the fields added
      */
     public static function addFields(array $fields, array $parameters): array
     {
@@ -76,22 +84,18 @@ class Parameters
      * Create JSON field name parameters for the given field names to the given parameter
      *
      * @param string $paramName The name of the parameter for the field names
-     * @param array|string[] $fieldNames The names of the fields for the parameter
+     * @param string[] $fieldNames The names of the fields for the parameter
-     * @return array An associative array of parameter/value pairs for the field names
+     * @return array<string, string> An associative array of parameter/value pairs for the field names
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception If the database mode has not been set
      */
     public static function fieldNames(string $paramName, array $fieldNames): array
     {
-        switch (Configuration::$mode) {
+        $mode = Configuration::mode('generate field name parameters');
-            case Mode::PgSQL:
+        return match ($mode) {
-                return [$paramName => "{" . implode(",", $fieldNames) . "}"];
+            Mode::PgSQL  => [$paramName => "{" . implode(",", $fieldNames) . "}"],
-            case Mode::SQLite:
+            Mode::SQLite => array_combine(array_map(fn($idx) => $paramName . $idx,
-                $it = [];
+                                              empty($fieldNames) ? [] : range(0, sizeof($fieldNames) - 1)),
-                $idx = 0;
+                                          array_map(fn($field) => "$.$field", $fieldNames))
-                foreach ($fieldNames as $field) $it[$paramName . $idx++] = "$.$field";
+        };
-                return $it;
-            default:
-                throw new DocumentException('Database mode not set; cannot generate field name parameters');
-        }
     }
 }

src/Patch.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -12,7 +18,7 @@ class Patch
      *
      * @param string $tableName The table in which the document should be patched
      * @param mixed $docId The ID of the document to be patched
-     * @param array|object $patch The object with which the document should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the document should be patched (will be JSON-encoded)
      * @throws DocumentException If any is encountered (database mode must be set)
      */
     public static function byId(string $tableName, mixed $docId, array|object $patch): void
@@ -25,25 +31,25 @@ class Patch
      * Patch documents using a comparison on JSON fields
      *
      * @param string $tableName The table in which documents should be patched
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
     public static function byFields(string $tableName, array $fields, array|object $patch,
                                     ?FieldMatch $match = null): void
     {
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        Custom::nonQuery(Query\Patch::byFields($tableName, $namedFields, $match),
+        Custom::nonQuery(Query\Patch::byFields($tableName, $fields, $match),
-            Parameters::addFields($namedFields, Parameters::json(':data', $patch)));
+            Parameters::addFields($fields, Parameters::json(':data', $patch)));
     }
 
     /**
      * Patch documents using a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table in which documents should be patched
-     * @param array|object $criteria The JSON containment query values to match
+     * @param mixed[]|object $criteria The JSON containment query values to match
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria, array|object $patch): void
@@ -57,7 +63,7 @@ class Patch
      *
      * @param string $tableName The table in which documents should be patched
      * @param string $path The JSON Path match string
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byJsonPath(string $tableName, string $path, array|object $patch): void

src/Query.php

@@ -1,7 +1,14 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use Exception;
 use Random\RandomException;
 
 /**
@@ -30,8 +37,7 @@ class Query
      */
     public static function whereByFields(array $fields, ?FieldMatch $match = null): string
     {
-        return implode(' ' . ($match ?? FieldMatch::All)->toString() . ' ',
+        return implode(' ' . ($match ?? FieldMatch::All)->toSQL() . ' ', array_map(fn($it) => $it->toWhere(), $fields));
-            array_map(fn($it) => $it->toWhere(), $fields));
     }
 
     /**
@@ -45,7 +51,7 @@ class Query
      */
     public static function whereById(string $paramName = ':id', mixed $docId = null): string
     {
-        return self::whereByFields([Field::EQ(Configuration::$idField, $docId ?? '', $paramName)]);
+        return self::whereByFields([Field::equal(Configuration::$idField, $docId ?? '', $paramName)]);
     }
 
     /**
@@ -53,11 +59,11 @@ class Query
      *
      * @param string $paramName The name of the parameter (optional; defaults to `:criteria`)
      * @return string The WHERE clause fragment for a JSON containment query
-     * @throws DocumentException If the database mode is not PostgreSQL
+     * @throws Exception|DocumentException If the database mode is not PostgreSQL
      */
     public static function whereDataContains(string $paramName = ':criteria'): string
     {
-        if (Configuration::$mode <> Mode::PgSQL) {
+        if (Configuration::mode() <> Mode::PgSQL) {
             throw new DocumentException('JSON containment is only supported on PostgreSQL');
         }
         return "data @> $paramName";
@@ -68,11 +74,11 @@ class Query
      *
      * @param string $paramName The name of the parameter (optional; defaults to `:path`)
      * @return string The WHERE clause fragment for a JSON Path match query
-     * @throws DocumentException If the database mode is not PostgreSQL
+     * @throws Exception|DocumentException If the database mode is not PostgreSQL
      */
     public static function whereJsonPathMatches(string $paramName = ':path'): string
     {
-        if (Configuration::$mode <> Mode::PgSQL) {
+        if (Configuration::mode() <> Mode::PgSQL) {
             throw new DocumentException('JSON Path matching is only supported on PostgreSQL');
         }
         return "jsonb_path_exists(data, $paramName::jsonpath)";
@@ -84,19 +90,19 @@ class Query
      * @param string $tableName The name of the table into which the document will be inserted
      * @param AutoId|null $autoId The version of automatic ID query to generate (optional, defaults to None)
      * @return string The `INSERT` statement to insert a document
-     * @throws DocumentException If the database mode is not set
+     * @throws Exception|DocumentException If the database mode is not set
      */
     public static function insert(string $tableName, ?AutoId $autoId = null): string
     {
         try {
-            $id = Configuration::$idField;
+            $id     = Configuration::$idField;
-            $values = match (Configuration::$mode) {
+            $values = match (Configuration::mode('generate auto-ID INSERT statement')) {
                 Mode::SQLite => match ($autoId ?? AutoId::None) {
                     AutoId::None         => ':data',
                     AutoId::Number       => "json_set(:data, '$.$id', "
                                                 . "(SELECT coalesce(max(data->>'$id'), 0) + 1 FROM $tableName))",
                     AutoId::UUID         => "json_set(:data, '$.$id', '" . AutoId::generateUUID() . "')",
-                    AutoId::RandomString => "json_set(:data, '$.$id', '" . AutoId::generateRandom() ."')"
+                    AutoId::RandomString => "json_set(:data, '$.$id', '" . AutoId::generateRandom() ."')",
                 },
                 Mode::PgSQL => match ($autoId ?? AutoId::None) {
                     AutoId::None         => ':data',
@@ -105,9 +111,7 @@ class Query
                                                     . "FROM $tableName) || '}')::jsonb",
                     AutoId::UUID         => ":data::jsonb || '{\"$id\":\"" . AutoId::generateUUID() . "\"}'",
                     AutoId::RandomString => ":data::jsonb || '{\"$id\":\"" . AutoId::generateRandom() . "\"}'",
-                },
+                }
-                default =>
-                    throw new DocumentException('Database mode not set; cannot generate auto-ID INSERT statement'),
             };
             return "INSERT INTO $tableName VALUES ($values)";
         } catch (RandomException $ex) {
@@ -138,4 +142,54 @@ class Query
     {
         return "UPDATE $tableName SET data = :data WHERE " . self::whereById();
     }
+
+    /**
+     * Transform a field to an ORDER BY clause segment
+     *
+     * @param Field $field The field by which ordering should be implemented
+     * @return string The ORDER BY fragment for the given field
+     * @throws Exception If the database mode has not been set
+     */
+    private static function mapToOrderBy(Field $field): string
+    {
+        $mode = Configuration::mode('render ORDER BY clause');
+
+        if (str_contains($field->fieldName, ' ')) {
+            $parts = explode(' ', $field->fieldName);
+            $field->fieldName = array_shift($parts);
+            $direction = ' ' . implode(' ', $parts);
+        } else {
+            $direction = '';
+        }
+
+        if (str_starts_with($field->fieldName, 'n:')) {
+            $field->fieldName = substr($field->fieldName, 2);
+            $value = match ($mode) {
+                Mode::PgSQL => '(' . $field->path() .  ')::numeric',
+                Mode::SQLite => $field->path()
+            };
+        } elseif (str_starts_with($field->fieldName, 'i:')) {
+            $field->fieldName = substr($field->fieldName, 2);
+            $value = match ($mode) {
+                Mode::PgSQL => 'LOWER(' . $field->path() . ')',
+                Mode::SQLite => $field->path() . ' COLLATE NOCASE'
+            };
+        } else {
+            $value = $field->path();
+        }
+
+        return (empty($field->qualifier) ? '' : "$field->qualifier.") . $value . $direction;
+    }
+
+    /**
+     * Create an `ORDER BY` clause ('n:' treats field as number, 'i:' does case-insensitive ordering)
+     *
+     * @param Field[] $fields The fields, named for the field plus directions (ex. 'field DESC NULLS FIRST')
+     * @return string The ORDER BY clause with the given fields
+     * @throws Exception If the database mode has not been set
+     */
+    public static function orderBy(array $fields): string
+    {
+        return empty($fields) ? "" : ' ORDER BY ' . implode(', ', array_map(self::mapToOrderBy(...), $fields));
+    }
 }

src/Query/Count.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 

src/Query/Definition.php

@@ -1,8 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 
 use BitBadger\PDODocument\{Configuration, DocumentException, DocumentIndex, Mode};
+use Exception;
 
 /**
  * Queries to define tables and indexes
@@ -14,14 +21,13 @@ class Definition
      *
      * @param string $name The name of the table (including schema, if applicable)
      * @return string The CREATE TABLE statement for the document table
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception If the database mode has not been set
      */
     public static function ensureTable(string $name): string
     {
-        $dataType = match (Configuration::$mode) {
+        $dataType = match (Configuration::mode('make create table statement')) {
             Mode::PgSQL  => 'JSONB',
             Mode::SQLite => 'TEXT',
-            default      => throw new DocumentException('Database mode not set; cannot make create table statement')
         };
         return "CREATE TABLE IF NOT EXISTS $name (data $dataType NOT NULL)";
     }
@@ -35,7 +41,7 @@ class Definition
     private static function splitSchemaAndTable(string $tableName): array
     {
         $parts = explode('.', $tableName);
-        return sizeof($parts) == 1 ? ["", $tableName] : [$parts[0], $parts[1]];
+        return sizeof($parts) === 1 ? ["", $tableName] : [$parts[0], $parts[1]];
     }
 
     /**
@@ -43,7 +49,7 @@ class Definition
      *
      * @param string $tableName The name of the table which should be indexed
      * @param string $indexName The name of the index to create
-     * @param array $fields An array of fields to be indexed; may contain direction (ex. 'salary DESC')
+     * @param string[] $fields An array of fields to be indexed; may contain direction (ex. 'salary DESC')
      * @return string The CREATE INDEX statement to ensure the index exists
      */
     public static function ensureIndexOn(string $tableName, string $indexName, array $fields): string
@@ -51,7 +57,7 @@ class Definition
         [, $tbl] = self::splitSchemaAndTable($tableName);
         $jsonFields = implode(', ', array_map(function (string $field) {
             $parts     = explode(' ', $field);
-            $fieldName = sizeof($parts) == 1 ? $field : $parts[0];
+            $fieldName = sizeof($parts) === 1 ? $field : $parts[0];
             $direction = sizeof($parts) < 2 ? "" : " $parts[1]";
             return "(data->>'$fieldName')$direction";
         }, $fields));
@@ -75,17 +81,17 @@ class Definition
      * @param string $tableName The name of the table on which the document index should be created
      * @param DocumentIndex $indexType The type of index to be created
      * @return string The SQL statement to create an index on JSON documents in the specified table
-     * @throws DocumentException If the database mode is not PostgreSQL
+     * @throws Exception|DocumentException If the database mode is not PostgreSQL
      */
     public static function ensureDocumentIndexOn(string $tableName, DocumentIndex $indexType): string
     {
-        if (Configuration::$mode <> Mode::PgSQL) {
+        if (Configuration::mode() <> Mode::PgSQL) {
             throw new DocumentException('Document indexes are only supported on PostgreSQL');
         }
         [, $tbl]  = self::splitSchemaAndTable($tableName);
         $extraOps = match ($indexType) {
-            DocumentIndex::Full => '',
+            DocumentIndex::Full      => '',
-            DocumentIndex::Optimized => ' jsonb_path_ops'
+            DocumentIndex::Optimized => ' jsonb_path_ops',
         };
         return "CREATE INDEX IF NOT EXISTS idx_{$tbl}_document ON $tableName USING GIN (data$extraOps)";
     }

src/Query/Delete.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 

src/Query/Exists.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 

src/Query/Find.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 

src/Query/Patch.php

@@ -1,8 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 
 use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode, Query};
+use Exception;
 
 /**
  * Queries to perform partial updates on documents
@@ -15,14 +22,13 @@ class Patch
      * @param string $tableName The name of the table in which documents should be patched
      * @param string $whereClause The body of the WHERE clause to use in the UPDATE statement
      * @return string The UPDATE statement to perform the patch
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception If the database mode has not been set
      */
     public static function update(string $tableName, string $whereClause): string
     {
-        $setValue = match (Configuration::$mode) {
+        $setValue = match (Configuration::mode('make patch statement')) {
             Mode::PgSQL  => 'data || :data',
             Mode::SQLite => 'json_patch(data, json(:data))',
-            default      => throw new DocumentException('Database mode not set; cannot make patch statement')
         };
         return "UPDATE $tableName SET data = $setValue WHERE $whereClause";
     }

src/Query/RemoveFields.php

@@ -1,8 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument\Query;
 
 use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode, Query};
+use Exception;
 
 /**
  * Queries to remove fields from documents
@@ -17,30 +24,26 @@ class RemoveFields
      * Create an UPDATE statement to remove fields from a JSON document
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param string $whereClause The body of the WHERE clause for the update
      * @return string The UPDATE statement to remove fields from a JSON document
-     * @throws DocumentException If the database mode has not been set
+     * @throws Exception If the database mode has not been set
      */
     public static function update(string $tableName, array $parameters, string $whereClause): string
     {
-        switch (Configuration::$mode) {
+        return match (Configuration::mode('generate field removal query')) {
-            case Mode::PgSQL:
+            Mode::PgSQL  => "UPDATE $tableName SET data = data - " . array_keys($parameters)[0]
-                return "UPDATE $tableName SET data = data - " . array_keys($parameters)[0]
+                                . "::text[] WHERE $whereClause",
-                    . "::text[] WHERE $whereClause";
+            Mode::SQLite => "UPDATE $tableName SET data = json_remove(data, " . implode(', ', array_keys($parameters))
-            case Mode::SQLite:
+                                . ") WHERE $whereClause",
-                $paramNames = implode(', ', array_keys($parameters));
+        };
-                return "UPDATE $tableName SET data = json_remove(data, $paramNames) WHERE $whereClause";
-            default:
-                throw new DocumentException('Database mode not set; cannot generate field removal query');
-        }
     }
 
     /**
      * Query to remove fields from a document by the document's ID
      *
      * @param string $tableName The name of the table in which the document should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param mixed $docId The ID of the document from which fields should be removed (optional; string ID assumed)
      * @return string The UPDATE statement to remove fields from a document by its ID
      * @throws DocumentException If the database mode has not been set
@@ -54,8 +57,8 @@ class RemoveFields
      * Query to remove fields from documents via a comparison on JSON fields within the document
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return string The UPDATE statement to remove fields from documents via field comparison
      * @throws DocumentException If the database mode has not been set
@@ -70,7 +73,7 @@ class RemoveFields
      * Query to remove fields from documents via a JSON containment query (PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @return string The UPDATE statement to remove fields from documents via a JSON containment query
      * @throws DocumentException If the database mode is not PostgreSQL
      */
@@ -83,7 +86,7 @@ class RemoveFields
      * Query to remove fields from documents via a JSON Path match query (PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @return string The UPDATE statement to remove fields from documents via a JSON Path match
      * @throws DocumentException
      */

src/RemoveFields.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
@@ -12,7 +18,7 @@ class RemoveFields
      *
      * @param string $tableName The table in which the document should have fields removed
      * @param mixed $docId The ID of the document from which fields should be removed
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If any is encountered
      */
     public static function byId(string $tableName, mixed $docId, array $fieldNames): void
@@ -26,8 +32,8 @@ class RemoveFields
      * Remove fields from documents via a comparison on a JSON field in the document
      *
      * @param string $tableName The table in which documents should have fields removed
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
@@ -35,17 +41,17 @@ class RemoveFields
                                     ?FieldMatch $match = null): void
     {
         $nameParams  = Parameters::fieldNames(':name', $fieldNames);
-        $namedFields = Parameters::nameFields($fields);
+        Parameters::nameFields($fields);
-        Custom::nonQuery(Query\RemoveFields::byFields($tableName, $namedFields, $nameParams, $match),
+        Custom::nonQuery(Query\RemoveFields::byFields($tableName, $fields, $nameParams, $match),
-            Parameters::addFields($namedFields, $nameParams));
+            Parameters::addFields($fields, $nameParams));
     }
 
     /**
      * Remove fields from documents via a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table in which documents should have fields removed
-     * @param array|object $criteria The JSON containment query values
+     * @param mixed[]|object $criteria The JSON containment query values
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria, array $fieldNames): void
@@ -60,7 +66,7 @@ class RemoveFields
      *
      * @param string $tableName The table in which documents should have fields removed
      * @param string $path The JSON Path match string
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byJsonPath(string $tableName, string $path, array $fieldNames): void

test_all.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+export PDO_DOC_PGSQL_HOST=localhost:8301
+PG_VERSIONS=('13' '14' '15' '16' 'latest')
+
+for PG_VERSION in "${PG_VERSIONS[@]}"
+do
+  echo Starting PostgreSQL:$PG_VERSION
+  docker run -d -p 8301:5432 --name pg_test -e POSTGRES_PASSWORD=postgres postgres:$PG_VERSION
+  sleep 4
+  if [ "$PG_VERSION" = "latest" ]; then
+    echo Testing SQLite and PostgreSQL...
+    ./vendor/bin/pest --testdox-text $1-tests.txt tests
+  else
+    echo Testing PostgreSQL v$PG_VERSION...
+    ./vendor/bin/pest --testdox-text $1-pg$PG_VERSION-tests.txt tests/Integration/PostgreSQL
+  fi
+  docker stop pg_test
+  sleep 2
+  docker rm pg_test
+done
+
+cd .. || exit

tests/Integration/ArrayDocument.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+/**
+ * A document with an array of values
+ */
+class ArrayDocument
+{
+    /**
+     * @param string $id The ID of the document
+     * @param string[] $values The values for the document
+     */
+    public function __construct(public string $id = '', public array $values = []) { }
+
+    /**
+     * A set of documents used for integration tests
+     *
+     * @return ArrayDocument[] Test documents for InArray tests
+     */
+    public static function testDocuments(): array
+    {
+        return [
+            new ArrayDocument('first', ['a', 'b', 'c']),
+            new ArrayDocument('second', ['c', 'd', 'e']),
+            new ArrayDocument('third', ['x', 'y', 'z'])
+        ];
+    }
+}

tests/Integration/DocumentTestCase.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Base test case class for document integration tests
+ */
+class DocumentTestCase extends TestCase
+{
+    /**
+     * Clear the output buffer
+     */
+    public function clearBuffer(): void
+    {
+        ob_clean();
+        ob_start();
+    }
+
+    /**
+     * Get the contents of the output buffer and end buffering
+     *
+     * @return string The contents of the output buffer
+     */
+    public function getBufferContents(): string {
+        $contents = ob_get_contents();
+        ob_end_clean();
+        return $contents;
+    }
+}

tests/Integration/NumDocument.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace Test\Integration;
 

tests/Integration/PgIntegrationTest.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+use BitBadger\PDODocument\{Configuration, Custom, Delete, DocumentException, Field};
+use BitBadger\PDODocument\Mapper\ExistsMapper;
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+/**
+ * Integration Test Class wrapper for PostgreSQL integration tests
+ */
+class PgIntegrationTest extends DocumentTestCase
+{
+    /** @var string Database name for throwaway database */
+    static private string $dbName = '';
+
+    public static function setUpBeforeClass(): void
+    {
+        self::$dbName = ThrowawayDb::create(false);
+    }
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        ThrowawayDb::loadData();
+    }
+
+    protected function tearDown(): void
+    {
+        Delete::byFields(ThrowawayDb::TABLE, [ Field::exists(Configuration::$idField)]);
+        parent::tearDown();
+    }
+
+    public static function tearDownAfterClass(): void
+    {
+        ThrowawayDb::destroy(self::$dbName);
+        self::$dbName = '';
+    }
+
+    /**
+     * Does the given named object exist in the database?
+     *
+     * @param string $name The name of the object whose existence should be verified
+     * @return bool True if the object exists, false if not
+     * @throws DocumentException If any is encountered
+     */
+    protected function dbObjectExists(string $name): bool
+    {
+        return Custom::scalar('SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = :name)',
+            [':name' => $name], new ExistsMapper());
+    }
+}

tests/Integration/PostgreSQL/CountTest.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Field};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::all()', function () {
+    test('counts all documents', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byFields()', function () {
+    test('counts for numeric range correctly', function () {
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::between('num_value', 10, 20)]))->toBe(3);
+    });
+    test('counts for non-numeric range correctly', function () {
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::between('value', 'aardvark', 'apple')]))->toBe(1);
+    });
+});
+
+describe('::byContains()', function () {
+    test('counts matching documents', function () {
+        expect(Count::byContains(ThrowawayDb::TABLE, ['value' => 'purple']))->toBe(2);
+    });
+    test('returns 0 for no matching documents', function () {
+        expect(Count::byContains(ThrowawayDb::TABLE, ['value' => 'magenta']))->toBe(0);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('counts matching documents', function () {
+        expect(Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 5)'))->toBe(2);
+    });
+    test('returns 0 for no matching documents', function () {
+        expect(Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)'))->toBe(0);
+    });
+});

tests/Integration/PostgreSQL/CustomTest.php

@@ -0,0 +1,135 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Custom, DocumentException, Query};
+use BitBadger\PDODocument\Mapper\{CountMapper, DocumentMapper};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::runQuery()', function () {
+    test('runs a valid query successfully', function () {
+        $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []);
+        try {
+            expect($stmt)->not->toBeNull();
+        } finally {
+            $stmt = null;
+        }
+    });
+    test('fails with an invalid query', function () {
+        $stmt = null;
+        try {
+            expect(function () use (&$stmt) { $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []); })
+                ->toThrow(DocumentException::class);
+        } finally {
+            $stmt = null;
+        }
+    });
+});
+
+describe('::list()', function () {
+    test('returns non-empty list when data found', function () {
+        $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $count = 0;
+        foreach ($list->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('returns empty list when no data found', function () {
+        expect(Custom::list(
+                Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric > :value",
+                [':value' => 100], new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::array()', function () {
+    test('returns non-empty array when data found', function () {
+        expect(Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [],
+                new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()
+            ->toHaveCount(2);
+    });
+    test('returns empty array when no data found', function () {
+        expect(Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value",
+                [':value' => 'not there'], new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()
+            ->toBeEmpty();
+    });
+});
+
+describe('::jsonArray()', function () {
+    test('returns non-empty array when data found', function () {
+        expect(Custom::jsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", []))
+            ->toContain('[{', '},{', '}]');
+    });
+    test('returns empty array when no data found', function () {
+        expect(Custom::jsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'nothing' = '7'", []))
+            ->toBe('[]');
+    });
+});
+
+describe('::outputJsonArray()', function () {
+    test('outputs non-empty array when data found', function () {
+        $this->clearBuffer();
+        Custom::outputJsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", []);
+        expect($this->getBufferContents())->toContain('[{', '},{', '}]');
+    });
+    test('outputs empty array when no data found', function () {
+        $this->clearBuffer();
+        Custom::outputJsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'nothing' = '7'", []);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::single()', function () {
+    test('returns a document when one is found', function () {
+        expect(Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id", [':id' => 'one'],
+                new DocumentMapper(TestDocument::class)))
+            ->isSome()->toBeTrue()
+            ->get()->id->toBe('one');
+    });
+    test('returns no document when one is not found', function () {
+        expect(Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+                [':id' => 'eighty'], new DocumentMapper(TestDocument::class)))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::jsonSingle()', function () {
+    test('returns a document when one is found', function () {
+        expect(Custom::jsonSingle('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+            [':id' => 'one']))
+            ->toStartWith('{"id":')->toContain('"one",')->toEndWith('}');
+    });
+    test('returns no document when one is not found', function () {
+        expect(Custom::jsonSingle('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+            [':id' => 'eighty']))
+            ->toBe('{}');
+    });
+});
+
+describe('::nonQuery()', function () {
+    test('works when documents match the WHERE clause', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(0);
+    });
+    test('works when no documents match the WHERE clause', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE (data->>'num_value')::numeric > :value",
+            [':value' => 100]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::scalar()', function () {
+    test('returns a scalar value', function () {
+        expect(Custom::scalar("SELECT 5 AS it", [], new CountMapper()))->toBe(5);
+    });
+});

tests/Integration/PostgreSQL/DefinitionTest.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Definition, DocumentIndex};
+
+pest()->group('integration', 'postgresql');
+
+describe('::ensureTable()', function () {
+    test('creates a table', function () {
+        expect($this->dbObjectExists('ensured'))->toBeFalse()
+            ->and($this->dbObjectExists('idx_ensured_key'))->toBeFalse();
+        Definition::ensureTable('ensured');
+        expect($this->dbObjectExists('ensured'))->toBeTrue()
+            ->and($this->dbObjectExists('idx_ensured_key'))->toBeTrue();
+    });
+});
+
+describe('::ensureFieldIndex()', function () {
+    test('creates an index', function () {
+        expect($this->dbObjectExists('idx_ensured_test'))->toBeFalse();
+        Definition::ensureTable('ensured');
+        Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']);
+        expect($this->dbObjectExists('idx_ensured_test'))->toBeTrue();
+    });
+});
+
+describe('::ensureDocumentIndex()', function () {
+    test('creates a full index', function () {
+        $docIdx = 'idx_doc_table_document';
+        Definition::ensureTable('doc_table');
+        expect($this->dbObjectExists($docIdx))->toBeFalse();
+        Definition::ensureDocumentIndex('doc_table', DocumentIndex::Full);
+        expect($this->dbObjectExists($docIdx))->toBeTrue();
+    });
+    test('creates an optimized index', function () {
+        $docIdx = 'idx_doc_tbl_document';
+        Definition::ensureTable('doc_tbl');
+        expect($this->dbObjectExists($docIdx))->toBeFalse();
+        Definition::ensureDocumentIndex('doc_tbl', DocumentIndex::Optimized);
+        expect($this->dbObjectExists($docIdx))->toBeTrue();
+    });
+});

tests/Integration/PostgreSQL/DeleteTest.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Delete, Field};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('deletes a document when ID is matched', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byId(ThrowawayDb::TABLE, 'four');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(4);
+    });
+    test('does not delete a document when ID is not matched', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byId(ThrowawayDb::TABLE, 'negative four');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byFields()', function () {
+    test('deletes documents when fields match', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notEqual('value', 'purple')]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(2);
+    });
+    test('does not delete documents when fields are not matched', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'crimson')]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byContains()', function () {
+    test('deletes documents when containment matches', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byContains(ThrowawayDb::TABLE, ['value' => 'purple']);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(3);
+    });
+    test('does not delete documents when containment is not matched', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byContains(ThrowawayDb::TABLE, ['target' => 'acquired']);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('deletes documents when path matches', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ <> 0)');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(1);
+    });
+    test('does not delete documents when path is not matched', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 0)');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});

tests/Integration/PostgreSQL/DocumentListTest.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, DocumentList, Query};
+use BitBadger\PDODocument\Mapper\DocumentMapper;
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::create()', function () {
+    test('creates a document list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $list = null; // free database result
+    });
+});
+
+describe('->items()', function () {
+    test('enumerates items in the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $count = 0;
+        foreach ($list->items() as $item) {
+            expect(['one', 'two', 'three', 'four', 'five'])->toContain($item->id);
+            $count++;
+        }
+        expect($count)->toBe(5);
+    });
+    test('fails when the list is exhausted', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        $ignored = iterator_to_array($list->items());
+        expect($list)->hasItems()->toBeFalse()
+            ->and(fn () => iterator_to_array($list->items()))->toThrow(DocumentException::class);
+    });
+});
+
+describe('->hasItems()', function () {
+    test('returns false when no items are in the list', function () {
+        expect(DocumentList::create(
+                Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric < 0", [],
+                new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+    test('returns true when items are in the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($list->items() as $ignored) {
+            expect($list)->hasItems()->toBeTrue();
+        }
+        expect($list)->hasItems()->toBeFalse();
+    });
+});
+
+describe('->map()', function () {
+    test('transforms the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($list->map(fn($doc) => strrev($doc->id)) as $mapped) {
+            expect(['eno', 'owt', 'eerht', 'ruof', 'evif'])->toContain($mapped);
+        }
+    });
+});
+
+describe('->iter()', function () {
+    test('walks the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        $splats = [];
+        $list->iter(function ($doc) use (&$splats) { $splats[] = str_repeat('*', strlen($doc->id)); });
+        expect(implode(' ', $splats))->toBe('*** *** ***** **** ****');
+    });
+});
+
+describe('->mapToArray()', function () {
+    test('creates an associative array', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue()
+            ->and($list->mapToArray(fn($it) => $it->id, fn($it) => $it->value))
+            ->toBe(['one' => 'FIRST!', 'two' => 'another', 'three' => '', 'four' => 'purple', 'five' => 'purple']);
+    });
+});

tests/Integration/PostgreSQL/DocumentTest.php

@@ -0,0 +1,249 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Field, Find, Query};
+use BitBadger\PDODocument\Mapper\ArrayMapper;
+use Test\Integration\{NumDocument, SubDocument, TestDocument};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::insert()', function () {
+    test('inserts an array with no automatic ID', function () {
+        Document::insert(ThrowawayDb::TABLE, ['id' => 'turkey', 'sub' => ['foo' => 'gobble', 'bar' => 'gobble']]);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
+        expect($tryDoc)
+            ->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->id->toBe('turkey')
+            ->value->toBe('')
+            ->num_value->toBe(0)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('gobble')
+            ->sub->bar->toBe('gobble');
+    });
+    test('inserts an array with auto-number ID, not provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+
+            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'new', 'num_value' => 8]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))
+                ->id->toBe(1);
+
+            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'again', 'num_value' => 7]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE " . Query::whereById(docId: 2),
+                [':id' => 2], new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))
+                ->id->toBe(2);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-number ID, provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => 7, 'value' => 'new', 'num_value' => 8]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))
+                ->id->toBe(7);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+
+    });
+    test('inserts an array with auto-UUID ID, not provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'num_value' => 5]);
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 5)], TestDocument::class);
+            expect($doc)
+                ->isSome()->toBeTrue()
+                ->and($doc->get())->id->not->toBeEmpty();
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-UUID ID, provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            $uuid = AutoId::generateUUID();
+            Document::insert(ThrowawayDb::TABLE, ['id' => $uuid, 'value' => 'uuid', 'num_value' => 12]);
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 12)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe($uuid);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-string ID, not provided', function () {
+        Configuration::$autoId         = AutoId::RandomString;
+        Configuration::$idStringLength = 6;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'value' => 'new', 'num_value' => 8]);
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 8)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toHaveLength(6);
+        } finally {
+            Configuration::$autoId         = AutoId::None;
+            Configuration::$idStringLength = 16;
+        }
+    });
+    test('inserts an array with auto-string ID, provided', function () {
+        Configuration::$autoId = AutoId::RandomString;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => 'my-key', 'value' => 'old', 'num_value' => 3]);
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 3)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe('my-key');
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with no automatic ID', function () {
+        Document::insert(ThrowawayDb::TABLE, new TestDocument('turkey', sub: new SubDocument('gobble', 'gobble')));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue();
+        $doc = $tryDoc->get();
+        expect($doc)
+            ->id->toBe('turkey')
+            ->num_value->toBe(0)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('gobble')
+            ->sub->bar->toBe('gobble')
+            ->and($doc->value)->toBe('');
+    });
+    test('inserts an object with auto-number ID, not provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'taco'));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'taco')], NumDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe(1);
+
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'burrito'));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'burrito')], NumDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe(2);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-number ID, provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(64, 'large'));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'large')], NumDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe(64);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-UUID ID, not provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument(value: 'something', num_value: 9));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::exists('value')], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->not->toBeEmpty();
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-UUID ID, provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            $uuid = AutoId::generateUUID();
+            Document::insert(ThrowawayDb::TABLE, new TestDocument($uuid, num_value: 14));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 14)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe($uuid);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-string ID, not provided', function () {
+        Configuration::$autoId         = AutoId::RandomString;
+        Configuration::$idStringLength = 40;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument(num_value: 55));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 55)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toHaveLength(40);
+        } finally {
+            Configuration::$autoId         = AutoId::None;
+            Configuration::$idStringLength = 16;
+        }
+    });
+    test('inserts an object with auto-string ID, provided', function () {
+        Configuration::$autoId = AutoId::RandomString;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument('my-key', num_value: 3));
+            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 3)], TestDocument::class);
+            expect($doc)->isSome()->toBeTrue()
+                ->and($doc->get())->id->toBe('my-key');
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('throws an exception for duplicate key', function () {
+        expect(fn () => Document::insert(ThrowawayDb::TABLE, new TestDocument('one')))
+            ->toThrow(DocumentException::class);
+    });
+});
+
+describe('::save()', function () {
+    test('inserts a new document', function () {
+        Document::save(ThrowawayDb::TABLE, new TestDocument('test', sub: new SubDocument('a', 'b')));
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))->isSome()->toBeTrue();
+    });
+    test('updates an existing document', function () {
+        Document::save(ThrowawayDb::TABLE, new TestDocument('two', num_value: 44));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->num_value->toBe(44)
+            ->sub->toBeNull();
+    });
+});
+
+describe('::update()', function () {
+    test('replaces an existing document', function () {
+        Document::update(ThrowawayDb::TABLE, 'one', new TestDocument('one', 'howdy', 8, new SubDocument('y', 'z')));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue();
+        $doc = $tryDoc->get();
+        expect($doc)
+            ->num_value->toBe(8)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('y')
+            ->sub->bar->toBe('z')
+            ->and($doc->value)->toBe('howdy');
+    });
+    test('does nothing for a non-existent document', function () {
+        Document::update(ThrowawayDb::TABLE, 'two-hundred', new TestDocument('200'));
+        expect(Find::byId(ThrowawayDb::TABLE, 'two-hundred', TestDocument::class))->isNone()->toBeTrue();
+    });
+});

tests/Integration/PostgreSQL/ExistsTest.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Exists, Field};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('returns true when a document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'three'))->toBeTrue();
+    });
+    test('returns false when a document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'seven'))->toBeFalse();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 10)]))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::less('nothing', 'none')]))->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'purple']))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'violet']))->toBeFalse();
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)'))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10.1)'))->toBeFalse();
+    });
+});

tests/Integration/PostgreSQL/FindTest.php

@@ -0,0 +1,216 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, Field, FieldMatch, Find};
+use Test\Integration\{ArrayDocument, NumDocument, TestDocument};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('sorts data ascending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id DESC')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class,
+            [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'four', 'one', 'three', 'five']);
+    });
+    test('retrieves empty results', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Find::all(ThrowawayDb::TABLE, TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byId()', function () {
+    test('retrieves a document via string ID', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->id->toBe('two');
+    });
+    test('retrieves a document via numeric ID', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absent')]);
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Find::byId(ThrowawayDb::TABLE, 18, NumDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->id->toBe(18);
+    });
+    test('returns None when a document is not found', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class))->isNone()->toBeTrue();
+    });
+});
+
+describe('::byFields()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            TestDocument::class, FieldMatch::All);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], TestDocument::class,
+            FieldMatch::All, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('retrieves documents matching a numeric IN clause', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns an empty list when no matching documents are found', function () {
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)], TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+    test('retrieves documents matching an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])],
+            ArrayDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('returns an empty list when no documents match an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])],
+                ArrayDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], TestDocument::class,
+            [Field::named('value')]);
+        expect($docs)
+            ->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['two', 'four']);
+    });
+    test('returns an empty list when no documents match', function () {
+        expect(Find::byContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('retrieves matching documents', function () {
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('retrieves ordered matching documents', function () {
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class,
+            [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('returns an empty list when no documents match', function () {
+        expect(Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['two', 'four'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class,
+                orderBy: [Field::named('n:num_value DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!'], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('one');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['four', 'five'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class,
+                [Field::named('sub.bar NULLS FIRST')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('five');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('retrieves a matching document', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['four', 'five'])->toContain($doc->get()->id);
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class,
+                [Field::named('id DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});

tests/Integration/PostgreSQL/JsonTest.php

@@ -0,0 +1,410 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, Field, FieldMatch, Json};
+use Test\Integration\ArrayDocument;
+use Test\Integration\PostgreSQL\ThrowawayDb;
+
+pest()->group('integration', 'postgresql');
+
+// NOTE: PostgreSQL's `JSONB` type stores JSON in a binary representation which is more easily indexed and stored. One
+//       side effect of this is that the document returned may not have fields in the same order as the document which
+//       was originally stored. The ID will always be first, though, so these tests check for presence of IDs, sorting
+//       by IDs, etc., instead of checking the entire JSON string that should be either returned or output.
+
+/**
+ * Expect document ordering by verifying the index of IDs against others
+ *
+ * @param string $json The JSON string to be searched
+ * @param array $ids The IDs to be verified
+ */
+function expect_doc_order(string $json, array $ids): void
+{
+    for ($idx = 0; $idx < sizeof($ids) - 1; $idx++) {
+        expect(strpos($json, '"' . $ids[$idx] . '",'))
+            ->toBeLessThan(strpos($json, '"' . $ids[$idx + 1] . '",'),
+                "ID $ids[$idx] should have occurred before ID {$ids[$idx + 1]} in JSON $json");
+    }
+}
+
+/**
+ * Expect to find one of several document IDs in the given JSON
+ * @param string $json The JSON string to be searched
+ * @param string ...$ids One or more IDs to be searched
+ */
+function expect_any(string $json, string... $ids): void
+{
+    $exists = false;
+    foreach ($ids as $it) {
+        $exists = strpos($json, '"id": "' . $it . '",') >= 0;
+        if ($exists) break;
+    }
+    expect($exists)->toBeTrue('Could not find any of IDs [' . implode(', ', $ids) . "] in $json");
+}
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        expect(Json::all(ThrowawayDb::TABLE))
+            ->toContain('{"id": "one",', '{"id": "two",', '{"id": "three",', '{"id": "four",', '{"id": "five",');
+    });
+    test('sorts data ascending', function () {
+        expect_doc_order(Json::all(ThrowawayDb::TABLE, [Field::named('id')]), ['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        expect_doc_order(Json::all(ThrowawayDb::TABLE, [Field::named('id DESC')]),
+            ['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        expect_doc_order(
+            Json::all(ThrowawayDb::TABLE, [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]),
+            ['two', 'four', 'one', 'three', 'five']);
+    });
+    test('retrieves empty results', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Json::all(ThrowawayDb::TABLE))->toBe('[]');
+    });
+});
+
+describe('::byId()', function () {
+    test('retrieves a document via string ID', function () {
+        expect(Json::byId(ThrowawayDb::TABLE, 'two'))->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('retrieves a document via numeric ID', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absent')]);
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Json::byId(ThrowawayDb::TABLE, 18))->toStartWith('{"id": 18,')->toEndWith('}');
+    });
+    test('returns "{}" when a document is not found', function () {
+        expect(Json::byId(ThrowawayDb::TABLE, 'seventy-five'))->toBe('{}');
+    });
+});
+
+describe('::byFields()', function () {
+    test('retrieves matching documents', function () {
+        expect(
+            Json::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+                FieldMatch::All))
+            ->toStartWith('[{"id": "four",')->toEndWith('}]');
+    });
+    test('retrieves ordered matching documents', function () {
+        expect_doc_order(
+            Json::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], FieldMatch::All,
+                [Field::named('id')]),
+            ['five', 'four']);
+    });
+    test('retrieves documents matching a numeric IN clause', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])]))
+            ->toStartWith('[{"id": "three",')->toEndWith('}]');
+    });
+    test('returns an empty array when no matching documents are found', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)]))->toBe('[]');
+    });
+    test('retrieves documents matching an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])]))
+            ->toStartWith('[')->toContain('{"id": "first",')->toContain('{"id": "second",')->toEndWith(']');
+    });
+    test('returns an empty array when no documents match an inArray condition', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])]))
+            ->toBe('[]');
+    });
+});
+
+describe('::byContains()', function () {
+    test('retrieves matching documents', function () {
+        expect(Json::byContains(ThrowawayDb::TABLE, ['value' => 'purple']))
+            ->toStartWith('[')->toContain('{"id": "four",', '{"id": "five",')->toEndWith(']');
+    });
+    test('retrieves ordered matching documents', function () {
+        expect_doc_order(Json::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], [Field::named('value')]),
+            ['two', 'four']);
+    });
+    test('returns an empty array when no documents match', function () {
+        expect(Json::byContains(ThrowawayDb::TABLE, ['value' => 'indigo']))->toBe('[]');
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('retrieves matching documents', function () {
+        expect(Json::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)'))
+            ->toStartWith('[')->toContain('{"id": "four",', '{"id": "five",')->toEndWith(']');
+    });
+    test('retrieves ordered matching documents', function () {
+        expect_doc_order(Json::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', [Field::named('id')]),
+            ['five', 'four']);
+    });
+    test('returns an empty array when no documents match', function () {
+        expect(Json::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)'))->toBe('[]');
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('retrieves a matching document', function () {
+        expect(Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')]))
+            ->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')]);
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'two', 'four');
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(
+            Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')],
+                orderBy: [Field::named('n:num_value DESC')]))
+            ->toStartWith('{"id": "four",')->toEndWith('}');
+    });
+    test('returns "{}" when no documents match', function () {
+        expect(Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')]))->toBe('{}');
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('retrieves a matching document', function () {
+        expect(Json::firstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!']))
+            ->toStartWith('{"id": "one",')->toEndWith('}');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Json::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple']);
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'four', 'five');
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Json::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], [Field::named('sub.bar NULLS FIRST')]))
+            ->toStartWith('{"id": "five",')->toEndWith('}');
+    });
+    test('returns "{}" when no documents match', function () {
+        expect(Json::firstByContains(ThrowawayDb::TABLE, ['value' => 'indigo']))->toBe('{}');
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('retrieves a matching document', function () {
+        expect(Json::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)'))
+            ->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('retrieves a document for multiple results', function () {
+        $doc = Json::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)');
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'four', 'five');
+    });
+    test('retrieves a document for multiple ordered results', function () {
+        expect(Json::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', [Field::named('id DESC')]))
+            ->toStartWith('{"id": "four",')->toEndWith('}');
+    });
+    test('returns "{}" when no documents match', function () {
+        expect(Json::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)'))->toBe('{}');
+    });
+});
+
+describe('::outputAll()', function () {
+    test('outputs data', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE);
+        expect($this->getBufferContents())
+            ->toContain('{"id": "one",', '{"id": "two",', '{"id": "three",', '{"id": "four",', '{"id": "five",');
+    });
+    test('sorts data ascending', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('id')]);
+        expect_doc_order($this->getBufferContents(), ['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('id DESC')]);
+        expect_doc_order($this->getBufferContents(), ['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect_doc_order($this->getBufferContents(), ['two', 'four', 'one', 'three', 'five']);
+    });
+    test('outputs empty results', function () {
+        $this->clearBuffer();
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        Json::outputAll(ThrowawayDb::TABLE);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputById()', function () {
+    test('outputs a document via string ID', function () {
+        $this->clearBuffer();
+        Json::outputById(ThrowawayDb::TABLE, 'two');
+        expect($this->getBufferContents())->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('outputs a document via numeric ID', function () {
+        $this->clearBuffer();
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absent')]);
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        Json::outputById(ThrowawayDb::TABLE, 18);
+        expect($this->getBufferContents())->toStartWith('{"id": 18,')->toEndWith('}');
+    });
+    test('outputs "{}" when a document is not found', function () {
+        $this->clearBuffer();
+        Json::outputById(ThrowawayDb::TABLE, 'seventy-five');
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});
+
+describe('::outputByFields()', function () {
+    test('outputs matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            FieldMatch::All);
+        expect($this->getBufferContents())->toStartWith('[{"id": "four",')->toEndWith('}]');
+    });
+    test('outputs ordered matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], FieldMatch::All,
+            [Field::named('id')]);
+        expect_doc_order($this->getBufferContents(), ['five', 'four']);
+    });
+    test('outputs documents matching a numeric IN clause', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])]);
+        expect($this->getBufferContents())->toStartWith('[{"id": "three",')->toEndWith('}]');
+    });
+    test('outputs an empty array when no matching documents are found', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)]);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+    test('outputs documents matching an inArray condition', function () {
+        $this->clearBuffer();
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])]);
+        expect($this->getBufferContents())
+            ->toStartWith('[')->toContain('{"id": "first",', '{"id": "second",')->toEndWith(']');
+    });
+    test('outputs an empty array when no documents match an inArray condition', function () {
+        $this->clearBuffer();
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])]);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputByContains()', function () {
+    test('outputs matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByContains(ThrowawayDb::TABLE, ['value' => 'purple']);
+        expect($this->getBufferContents())
+            ->toStartWith('[')->toContain('{"id": "four",', '{"id": "five",')->toEndWith(']');
+    });
+    test('outputs ordered matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], [Field::named('value')]);
+        expect_doc_order($this->getBufferContents(), ['two', 'four']);
+    });
+    test('outputs an empty array when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputByContains(ThrowawayDb::TABLE, ['value' => 'indigo']);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputByJsonPath()', function () {
+    test('outputs matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)');
+        expect($this->getBufferContents())
+            ->toStartWith('[')->toContain('{"id": "four",', '{"id": "five",')->toEndWith(']');
+    });
+    test('outputs ordered matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', [Field::named('id')]);
+        expect_doc_order($this->getBufferContents(), ['five', 'four']);
+    });
+    test('outputs an empty array when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)');
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputFirstByFields()', function () {
+    test('outputs a matching document', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')]);
+        expect($this->getBufferContents())->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('outputs a document for multiple results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')]);
+        $doc = $this->getBufferContents();
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'two', 'four');
+    });
+    test('outputs a document for multiple ordered results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')],
+            orderBy: [Field::named('n:num_value DESC')]);
+        expect($this->getBufferContents())->toStartWith('{"id": "four",')->toEndWith('}');
+    });
+    test('outputs "{}" when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')]);
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});
+
+describe('::outputFirstByContains()', function () {
+    test('outputs a matching document', function () {
+        $this->clearBuffer();
+        Json::outputFirstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!']);
+        expect($this->getBufferContents())->toStartWith('{"id": "one",')->toEndWith('}');
+    });
+    test('outputs a document for multiple results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByContains(ThrowawayDb::TABLE, ['value' => 'purple']);
+        $doc = $this->getBufferContents();
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'four', 'five');
+    });
+    test('outputs a document for multiple ordered results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], [Field::named('sub.bar NULLS FIRST')]);
+        expect($this->getBufferContents())->toStartWith('{"id": "five",')->toEndWith('}');
+    });
+    test('outputs "{}" when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputFirstByContains(ThrowawayDb::TABLE, ['value' => 'indigo']);
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});
+
+describe('::outputFirstByJsonPath()', function () {
+    test('outputs a matching document', function () {
+        $this->clearBuffer();
+        Json::outputFirstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)');
+        expect($this->getBufferContents())->toStartWith('{"id": "two",')->toEndWith('}');
+    });
+    test('outputs a document for multiple results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)');
+        $doc = $this->getBufferContents();
+        expect($doc)->toStartWith('{')->toEndWith('}');
+        expect_any($doc, 'four', 'five');
+    });
+    test('outputs a document for multiple ordered results', function () {
+        $this->clearBuffer();
+        Json::outputFirstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', [Field::named('id DESC')]);
+        expect($this->getBufferContents())->toStartWith('{"id": "four",')->toEndWith('}');
+    });
+    test('outputs "{}" when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputFirstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)');
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});

tests/Integration/PostgreSQL/PatchTest.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Exists, Field, Find, Patch};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->num_value->toBe(44);
+    });
+    test('does nothing when a document does not exist', function () {
+        $id = 'forty-seven';
+        expect(Exists::byId(ThrowawayDb::TABLE, $id))->toBeFalse();
+        Patch::byId(ThrowawayDb::TABLE, $id, ['foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates existing documents', function () {
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], ['num_value' => 77]);
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 77)]))->toBe(2);
+    });
+    test('does nothing when no matching documents exist', function () {
+        $fields = [Field::equal('value', 'burgundy')];
+        expect(Count::byFields(ThrowawayDb::TABLE, $fields))->toBe(0);
+        Patch::byFields(ThrowawayDb::TABLE, $fields, ['foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byContains()', function () {
+    test('updates existing documents', function () {
+        Patch::byContains(ThrowawayDb::TABLE, ['value' => 'another'], ['num_value' => 12]);
+        $tryDoc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'another'], TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->id->toBe('two')
+            ->num_value->toBe(12);
+    });
+    test('does nothing when no matching documents exist', function () {
+        $criteria = ['value' => 'updated'];
+        expect(Count::byContains(ThrowawayDb::TABLE, $criteria))->toBe(0);
+        Patch::byContains(ThrowawayDb::TABLE, $criteria, ['sub.foo' => 'green']); // no exception = pass
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('updates existing documents', function () {
+        Patch::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', ['value' => 'blue']);
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['four', 'five'])->toContain($item->id)
+                ->and($item->value)->toBe('blue');
+        }
+    });
+    test('does nothing when no matching documents exist', function () {
+        $path = '$.num_value ? (@ > 100)';
+        expect(Count::byJsonPath(ThrowawayDb::TABLE, $path))->toBe(0);
+        Patch::byJsonPath(ThrowawayDb::TABLE, $path, ['value' => 'blue']); // no exception = pass
+    });
+});

tests/Integration/PostgreSQL/RemoveFieldsTest.php

@@ -0,0 +1,91 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Exists, Field, Find, RemoveFields};
+use Test\Integration\PostgreSQL\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'postgresql');
+
+describe('::byId()', function () {
+    test('removes fields', function () {
+        RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue();
+        $doc = $tryDoc->get();
+        expect($doc)->sub->toBeNull()
+            ->and($doc->value)->toBeEmpty();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('a_field_that_does_not_exist')]))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'one', ['a_field_that_does_not_exist']); // no exception = pass
+    });
+    test('does nothing when the document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'fifty'))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'fifty', ['sub']); // no exception = pass
+    });
+});
+
+describe('::byFields()', function () {
+    test('removes fields from matching documents', function () {
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['sub']);
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], TestDocument::class))
+            ->isSome()->toBeTrue()
+            ->get()->sub->toBeNull();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('nada')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['nada']); // no exception = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')], ['value']); // no exn = pass
+    });
+});
+
+describe('::byContains()', function () {
+    test('removes fields from matching documents', function () {
+        $criteria = ['sub' => ['foo' => 'green']];
+        RemoveFields::byContains(ThrowawayDb::TABLE, $criteria, ['value']);
+        $docs = Find::byContains(ThrowawayDb::TABLE, $criteria, TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['two', 'four'])->toContain($item->id)
+                ->and($item->value)->toBeEmpty();
+        }
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('invalid_field')]))->toBeFalse();
+        RemoveFields::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], ['invalid_field']); // no exn = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'substantial']))->toBeFalse();
+        RemoveFields::byContains(ThrowawayDb::TABLE, ['value' => 'substantial'], ['num_value']); // no exception = pass
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('removes fields from matching documents', function () {
+        $path = '$.value ? (@ == "purple")';
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, $path, ['sub']);
+        $docs = Find::byJsonPath(ThrowawayDb::TABLE, $path, TestDocument::class);
+        expect($docs)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($docs->items() as $item) {
+            expect(['four', 'five'])->toContain($item->id)
+                ->and($item->sub)->toBeNull();
+        }
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('submarine')]))->toBeFalse();
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "purple")', ['submarine']); // no exception = pass
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "mauve")'))->toBeFalse();
+        RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "mauve")', ['value']); // no exception = pass
+    });
+});

tests/Integration/PostgreSQL/ThrowawayDb.php

@@ -1,8 +1,15 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
 
 namespace Test\Integration\PostgreSQL;
 
-use BitBadger\PDODocument\{AutoId, Configuration, Custom, Definition, Document, DocumentException, Mode};
+use BitBadger\PDODocument\{AutoId, Configuration, Custom, Definition, Document, DocumentException};
 use Random\RandomException;
 use Test\Integration\{SubDocument, TestDocument};
 
@@ -12,24 +19,38 @@ use Test\Integration\{SubDocument, TestDocument};
 class ThrowawayDb
 {
     /** @var string The table used for document manipulation */
-    public const TABLE = "test_table";
+    public const TABLE = 'test_table';
 
     /**
      * Configure the document library for the given database (or the main PostgreSQL connection, if the database name
      * is not provided; this is used for creating and dropping databases)
      *
      * @param string|null $dbName The name of the database to configure (optional, defaults to env or "postgres")
+     * @throws DocumentException If any is encountered
      */
     private static function configure(?string $dbName = null): void
     {
-        Configuration::$pdoDSN = sprintf("pgsql:host=%s;dbname=%s", $_ENV['PDO_DOC_PGSQL_HOST'] ?? 'localhost',
+        Configuration::useDSN(sprintf("pgsql:host=%s;dbname=%s", $_ENV['PDO_DOC_PGSQL_HOST'] ?? 'localhost',
-            $dbName ?? $_ENV['PDO_DOC_PGSQL_DB'] ?? 'postgres');
+            $dbName ?? $_ENV['PDO_DOC_PGSQL_DB'] ?? 'postgres'));
         Configuration::$username = $_ENV['PDO_DOC_PGSQL_USER'] ?? 'postgres';
         Configuration::$password = $_ENV['PDO_DOC_PGSQL_PASS'] ?? 'postgres';
-        Configuration::$mode = Mode::PgSQL;
         Configuration::resetPDO();
     }
 
+    /**
+     * Load data into the test table
+     *
+     * @throws DocumentException If any is encountered
+     */
+    public static function loadData(): void
+    {
+        Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
+        Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
+        Document::insert(self::TABLE, new TestDocument('three', '', 4));
+        Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
+        Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
+    }
+
     /**
      * Create a throwaway PostgreSQL database
      *
@@ -44,13 +65,10 @@ class ThrowawayDb
         Custom::nonQuery("CREATE DATABASE $dbName WITH OWNER " . Configuration::$username, []);
         self::configure($dbName);
 
+        Definition::ensureTable(self::TABLE);
+
         if ($withData) {
-            Definition::ensureTable(self::TABLE);
+            self::loadData();
-            Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
-            Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
-            Document::insert(self::TABLE, new TestDocument('three', '', 4));
-            Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
-            Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
         }
 
         return $dbName;
@@ -66,10 +84,9 @@ class ThrowawayDb
     {
         self::configure();
         Custom::nonQuery("DROP DATABASE IF EXISTS $dbName WITH (FORCE)", []);
-        Configuration::$pdoDSN   = '';
+        Configuration::useDSN('');
         Configuration::$username = null;
         Configuration::$password = null;
-        Configuration::$mode     = null;
         Configuration::resetPDO();
     }
 }

tests/Integration/SQLite/CountTest.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, DocumentException, Field};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::all()', function () {
+    test('counts all documents', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byFields()', function () {
+    test('counts by numeric range', function () {
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::between('num_value', 10, 20)]))->toBe(3);
+    });
+    test('counts by non-numeric range', function () {
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::between('value', 'aardvark', 'apple')]))->toBe(1);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Count::byContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Count::byJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/CustomTest.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Custom, DocumentException, Query};
+use BitBadger\PDODocument\Mapper\{CountMapper, DocumentMapper};
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::runQuery()', function () {
+    test('runs a valid query successfully', function () {
+        $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []);
+        try {
+            expect($stmt)->not->toBeNull();
+        } finally {
+            $stmt = null;
+        }
+    });
+    test('fails with an invalid query', function () {
+        $stmt = null;
+        try {
+            expect(function () use (&$stmt) { $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []); })
+                ->toThrow(DocumentException::class);
+        } finally {
+            $stmt = null;
+        }
+    });
+});
+
+describe('::list()', function () {
+    test('returns non-empty list when data is found', function () {
+        $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $count = 0;
+        foreach ($list->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('returns empty list when not data is found', function () {
+        expect(Custom::list(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'num_value' > :value",
+            [':value' => 100], new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()
+            ->hasItems()->toBeFalse();
+
+    });
+});
+
+describe('::array()', function () {
+    test('returns non-empty array when data is found', function () {
+        expect(Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [],
+                new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()->toHaveCount(2);
+    });
+    test('returns empty array when data is not found', function () {
+        expect(Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value",
+                [':value' => 'not there'], new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()->toBeEmpty();
+    });
+});
+
+describe('::jsonArray()', function () {
+    test('returns non-empty array when data found', function () {
+        expect(Custom::jsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", []))
+            ->toContain('[{', '},{', '}]');
+    });
+    test('returns empty array when no data found', function () {
+        expect(Custom::jsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'nothing' = '7'", []))
+            ->toBe('[]');
+    });
+});
+
+describe('::outputJsonArray()', function () {
+    test('outputs non-empty array when data found', function () {
+        $this->clearBuffer();
+        Custom::outputJsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", []);
+        expect($this->getBufferContents())->toContain('[{', '},{', '}]');
+    });
+    test('outputs empty array when no data found', function () {
+        $this->clearBuffer();
+        Custom::outputJsonArray(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'nothing' = '7'", []);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::single()', function () {
+    test('returns a document when one is found', function () {
+        expect(Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id", [':id' => 'one'],
+                new DocumentMapper(TestDocument::class)))
+            ->isSome()->toBeTrue()->get()->id->toBe('one');
+    });
+    test('returns no document when none is found', function () {
+        expect(Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+                [':id' => 'eighty'], new DocumentMapper(TestDocument::class)))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::jsonSingle()', function () {
+    test('returns a document when one is found', function () {
+        expect(Custom::jsonSingle('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+            [':id' => 'one']))
+            ->toStartWith('{"id":"one",')->toEndWith('}');
+    });
+    test('returns no document when one is not found', function () {
+        expect(Custom::jsonSingle('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
+            [':id' => 'eighty']))
+            ->toBe('{}');
+    });
+});
+
+describe('::nonQuery()', function () {
+    test('works when documents match the WHERE clause', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(0);
+    });
+    test('works when no documents match the WHERE clause', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE data->>'num_value' > :value", [':value' => 100]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::scalar()', function () {
+    test('returns a scalar value', function () {
+        expect(Custom::scalar("SELECT 5 AS it", [], new CountMapper()))->toBe(5);
+    });
+});

tests/Integration/SQLite/DefinitionTest.php

@@ -0,0 +1,36 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Definition, DocumentException, DocumentIndex};
+
+pest()->group('integration', 'sqlite');
+
+describe('::ensureTable()', function () {
+    test('creates table and PK index', function () {
+        expect($this->dbObjectExists('ensured'))->toBeFalse()
+            ->and($this->dbObjectExists('idx_ensured_key'))->toBeFalse();
+        Definition::ensureTable('ensured');
+        expect($this->dbObjectExists('ensured'))->toBeTrue()
+            ->and($this->dbObjectExists('idx_ensured_key'))->toBeTrue();
+    });
+});
+
+describe('::ensureFieldIndex()', function () {
+    test('creates an index', function () {
+        expect($this->dbObjectExists('idx_ensured_test'))->toBeFalse();
+        Definition::ensureTable('ensured');
+        Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']);
+        expect($this->dbObjectExists('idx_ensured_test'))->toBeTrue();
+    });
+});
+
+describe('::ensureDocumentIndex()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Definition::ensureDocumentIndex('', DocumentIndex::Full))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/DeleteTest.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, Delete, DocumentException, Field};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('deletes a document when one exists', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byId(ThrowawayDb::TABLE, 'four');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(4);
+    });
+    test('does nothing when the document does not exist', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byId(ThrowawayDb::TABLE, 'negative four');
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byFields()', function () {
+    test('deletes matching documents', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notEqual('value', 'purple')]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(2);
+    });
+    test('does nothing when no documents match', function () {
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+        Delete::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'crimson')]);
+        expect(Count::all(ThrowawayDb::TABLE))->toBe(5);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Delete::byContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Delete::byJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/DocumentListTest.php

@@ -0,0 +1,94 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, DocumentList, Query};
+use BitBadger\PDODocument\Mapper\DocumentMapper;
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::create()', function () {
+    test('creates a document list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $list = null; // free database result
+    });
+});
+
+describe('->items()', function () {
+    test('enumerates items in the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull();
+        $count = 0;
+        foreach ($list->items() as $item) {
+            expect(['one', 'two', 'three', 'four', 'five'])->toContain($item->id);
+            $count++;
+        }
+        expect($count)->toBe(5);
+    });
+    test('fails when the list is exhausted', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        $ignored = iterator_to_array($list->items());
+        expect($list)->hasItems()->toBeFalse()
+            ->and(fn () => iterator_to_array($list->items()))->toThrow(DocumentException::class);
+    });
+});
+
+describe('->hasItems()', function () {
+    test('returns true when items exist', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($list->items() as $ignored) {
+            expect($list)->hasItems()->toBeTrue();
+        }
+        expect($list)->hasItems()->toBeFalse();
+    });
+    test('returns false when no items exist', function () {
+        expect(DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'num_value' < 0", [],
+                new DocumentMapper(TestDocument::class)))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+});
+
+describe('->map()', function () {
+    test('transforms the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        foreach ($list->map(fn($doc) => strrev($doc->id)) as $mapped) {
+            expect(['eno', 'owt', 'eerht', 'ruof', 'evif'])->toContain($mapped);
+        }
+    });
+});
+
+describe('->iter()', function () {
+    test('walks the list', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue();
+        $splats = [];
+        $list->iter(function ($doc) use (&$splats) { $splats[] = str_repeat('*', strlen($doc->id)); });
+        expect(implode(' ', $splats))->toBe('*** *** ***** **** ****');
+    });
+});
+
+describe('->mapToArray()', function () {
+    test('creates an associative array', function () {
+        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
+            new DocumentMapper(TestDocument::class));
+        expect($list)->not->toBeNull()->hasItems()->toBeTrue()
+            ->and($list->mapToArray(fn($it) => $it->id, fn($it) => $it->value))
+            ->toBe(['one' => 'FIRST!', 'two' => 'another', 'three' => '', 'four' => 'purple', 'five' => 'purple']);
+    });
+});

tests/Integration/SQLite/DocumentTest.php

@@ -0,0 +1,231 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Exists, Field, Find};
+use BitBadger\PDODocument\Mapper\ArrayMapper;
+use Test\Integration\{NumDocument, SubDocument, TestDocument};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::insert()', function () {
+    test('inserts an array with no automatic ID', function () {
+        Document::insert(ThrowawayDb::TABLE, ['id' => 'turkey', 'sub' => ['foo' => 'gobble', 'bar' => 'gobble']]);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->id->toBe('turkey')
+            ->num_value->toBe(0)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('gobble')
+            ->sub->bar->toBe('gobble')
+            ->and($tryDoc->get()->value)->toBeEmpty();
+    });
+    test('inserts an array with auto-number ID, not provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+
+            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'new', 'num_value' => 8]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))->id->toBe(1);
+
+            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'again', 'num_value' => 7]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = 2", [],
+                new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))->id->toBe(2);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-number ID, provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => 7, 'value' => 'new', 'num_value' => 8]);
+            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
+            expect($doc)->isSome()->toBeTrue()
+                ->and(json_decode($doc->get()['data']))->id->toBe(7);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-UUID ID, not provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'num_value' => 5]);
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 5)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->not->toBeEmpty();
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-UUID ID, provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            $uuid = AutoId::generateUUID();
+            Document::insert(ThrowawayDb::TABLE, ['id' => $uuid, 'value' => 'uuid', 'num_value' => 12]);
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 12)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe($uuid);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an array with auto-string ID, not provided', function () {
+        Configuration::$autoId         = AutoId::RandomString;
+        Configuration::$idStringLength = 6;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'value' => 'new', 'num_value' => 8]);
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 8)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toHaveLength(6);
+        } finally {
+            Configuration::$autoId         = AutoId::None;
+            Configuration::$idStringLength = 16;
+        }
+    });
+    test('inserts an array with auto-string ID, provided', function () {
+        Configuration::$autoId = AutoId::RandomString;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, ['id' => 'my-key', 'value' => 'old', 'num_value' => 3]);
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 3)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe('my-key');
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with no automatic ID', function () {
+        Document::insert(ThrowawayDb::TABLE, new TestDocument('turkey', sub: new SubDocument('gobble', 'gobble')));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->id->toBe('turkey')
+            ->num_value->toBe(0)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('gobble')
+            ->sub->bar->toBe('gobble')
+            ->and($tryDoc->get()->value)->toBeEmpty();
+    });
+    test('inserts an object with auto-number ID, not provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'taco'));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'taco')], NumDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe(1);
+
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'burrito'));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'burrito')], NumDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe(2);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-number ID, provided', function () {
+        Configuration::$autoId = AutoId::Number;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new NumDocument(64, 'large'));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'large')], NumDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe(64);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-UUID ID, not provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument(value: 'something', num_value: 9));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::exists('value')], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->not->toBeEmpty();
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-UUID ID, provided', function () {
+        Configuration::$autoId = AutoId::UUID;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            $uuid = AutoId::generateUUID();
+            Document::insert(ThrowawayDb::TABLE, new TestDocument($uuid, num_value: 14));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 14)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe($uuid);
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('inserts an object with auto-string ID, not provided', function () {
+        Configuration::$autoId         = AutoId::RandomString;
+        Configuration::$idStringLength = 40;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument(num_value: 55));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 55)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toHaveLength(40);
+        } finally {
+            Configuration::$autoId         = AutoId::None;
+            Configuration::$idStringLength = 16;
+        }
+    });
+    test('inserts an object with auto-string ID, provided', function () {
+        Configuration::$autoId = AutoId::RandomString;
+        try {
+            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+            Document::insert(ThrowawayDb::TABLE, new TestDocument('my-key', num_value: 3));
+            expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 3)], TestDocument::class))
+                ->isSome()->toBeTrue()->get()->id->toBe('my-key');
+        } finally {
+            Configuration::$autoId = AutoId::None;
+        }
+    });
+    test('throws an exception for duplicate key', function () {
+        expect(fn () => Document::insert(ThrowawayDb::TABLE, new TestDocument('one')))
+            ->toThrow(DocumentException::class);
+    });
+});
+
+describe('::save()', function () {
+    test('inserts a new document', function () {
+        Document::save(ThrowawayDb::TABLE, new TestDocument('test', sub: new SubDocument('a', 'b')));
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))->isSome()->toBeTrue();
+    });
+    test('updates an existing document', function () {
+        Document::save(ThrowawayDb::TABLE, new TestDocument('two', num_value: 44));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->num_value->toBe(44)
+            ->sub->toBeNull();
+    });
+});
+
+describe('::update()', function () {
+    test('replaces an existing document', function () {
+        Document::update(ThrowawayDb::TABLE, 'one', new TestDocument('one', 'howdy', 8, new SubDocument('y', 'z')));
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())
+            ->num_value->toBe(8)
+            ->sub->not->toBeNull()
+            ->sub->foo->toBe('y')
+            ->sub->bar->toBe('z')
+            ->and($tryDoc->get()->value)->toBe('howdy');
+    });
+    test('does nothing for a non-existent document', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'two-hundred'))->toBeFalse();
+        Document::update(ThrowawayDb::TABLE, 'two-hundred', new TestDocument('200'));
+        expect(Find::byId(ThrowawayDb::TABLE, 'two-hundred', TestDocument::class))->isNone()->toBeTrue();
+    });
+});

tests/Integration/SQLite/ExistsTest.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Exists, Field};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('returns true when a document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'three'))->toBeTrue();
+    });
+    test('returns false when no document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'seven'))->toBeFalse();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 10)]))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::less('nothing', 'none')]))->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Exists::byContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Exists::byJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/FindTest.php

@@ -0,0 +1,151 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, DocumentException, Field, FieldMatch, Find};
+use Test\Integration\{ArrayDocument, TestDocument};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('sorts data ascending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id DESC')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class,
+            [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'four', 'one', 'three', 'five']);
+    });
+    test('returns an empty list when no data exists', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Find::all(ThrowawayDb::TABLE, TestDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byId()', function () {
+    test('returns a document when it exists', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('returns a document with a numeric ID', function () {
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Find::byId(ThrowawayDb::TABLE, 18, TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('18');
+    });
+    test('returns None when no document exists', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class))->isNone()->toBeTrue();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            TestDocument::class, FieldMatch::All);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns ordered matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], TestDocument::class,
+            FieldMatch::All, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('returns documents matching numeric IN clause', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns empty list when no documents match', function () {
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)], TestDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+    test('returns matching documents for inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])],
+            ArrayDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('returns empty list when no documents match inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])],
+                ArrayDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::byContains('', [], TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::byJsonPath('', '', TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('returns a matching document', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('returns one of several matching documents', function () {
+        $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['two', 'four'])->toContain($doc->get()->id);
+    });
+    test('returns first of ordered matching documents', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class,
+                orderBy: [Field::named('n:num_value DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::firstByContains('', [], TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::firstByJsonPath('', '', TestDocument::class))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/JsonTest.php

@@ -0,0 +1,272 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, DocumentException, Field, FieldMatch, Json};
+use Test\Integration\ArrayDocument;
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+/** JSON for document ID "one" */
+const ONE = '{"id":"one","value":"FIRST!","num_value":0,"sub":null}';
+
+/** JSON for document ID "two" */
+const TWO = '{"id":"two","value":"another","num_value":10,"sub":{"foo":"green","bar":"blue"}}';
+
+/** JSON for document ID "three" */
+const THREE = '{"id":"three","value":"","num_value":4,"sub":null}';
+
+/** JSON for document ID "four" */
+const FOUR = '{"id":"four","value":"purple","num_value":17,"sub":{"foo":"green","bar":"red"}}';
+
+/** JSON for document ID "five" */
+const FIVE = '{"id":"five","value":"purple","num_value":18,"sub":null}';
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        expect(Json::all(ThrowawayDb::TABLE))->toStartWith('[')->toContain(ONE, TWO, THREE, FOUR, FIVE)->toEndWith(']');
+    });
+    test('sorts data ascending', function () {
+        expect(Json::all(ThrowawayDb::TABLE, [Field::named('id')]))
+            ->toBe('[' . implode(',', [FIVE, FOUR, ONE, THREE, TWO]) . ']');
+    });
+    test('sorts data descending', function () {
+        expect(Json::all(ThrowawayDb::TABLE, [Field::named('id DESC')]))
+            ->toBe('[' . implode(',', [TWO, THREE, ONE, FOUR, FIVE]) . ']');
+    });
+    test('sorts data numerically', function () {
+        expect(Json::all(ThrowawayDb::TABLE, [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]))
+            ->toBe('[' . implode(',', [TWO, FOUR, ONE, THREE, FIVE]) . ']');
+    });
+    test('returns an empty array when no data exists', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Json::all(ThrowawayDb::TABLE))->toBe('[]');
+    });
+});
+
+describe('::byId()', function () {
+    test('returns a document when it exists', function () {
+        expect(Json::byId(ThrowawayDb::TABLE, 'two'))->toBe(TWO);
+    });
+    test('returns a document with a numeric ID', function () {
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Json::byId(ThrowawayDb::TABLE, 18))->toBe('{"id":18,"value":"howdy"}');
+    });
+    test('returns "{}" when no document exists', function () {
+        expect(Json::byId(ThrowawayDb::TABLE, 'seventy-five'))->toBe('{}');
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns matching documents', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            FieldMatch::All))
+            ->toBe('[' . FOUR . ']');
+    });
+    test('returns ordered matching documents', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], FieldMatch::All,
+            [Field::named('id')]))
+            ->toBe('[' . implode(',', [FIVE, FOUR]) . ']');
+    });
+    test('returns documents matching numeric IN clause', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])]))->toBe('[' . THREE . ']');
+    });
+    test('returns empty array when no documents match', function () {
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)]))->toBe('[]');
+    });
+    test('returns matching documents for inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])]))
+            ->toBe('[{"id":"first","values":["a","b","c"]},{"id":"second","values":["c","d","e"]}]');
+    });
+    test('returns empty array when no documents match inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Json::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])]))->toBe('[]');
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::byContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::byJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('returns a matching document', function () {
+        expect(Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')]))->toBe(TWO);
+    });
+    test('returns one of several matching documents', function () {
+        $doc = Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')]);
+        expect($doc == TWO || $doc == FOUR)->toBeTrue("Document should have been two or four (actual $doc)");
+    });
+    test('returns first of ordered matching documents', function () {
+        expect(Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')],
+            orderBy: [Field::named('n:num_value DESC')]))
+            ->toBe(FOUR);
+    });
+    test('returns "{}" when no documents match', function () {
+        expect(Json::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')]))->toBe('{}');
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::firstByContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::firstByJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::outputAll()', function () {
+    test('outputs data', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE);
+        expect($this->getBufferContents())->toStartWith('[')->toContain(ONE, TWO, THREE, FOUR, FIVE)->toEndWith(']');
+    });
+    test('sorts data ascending', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('id')]);
+        expect($this->getBufferContents())->toBe('[' . implode(',', [FIVE, FOUR, ONE, THREE, TWO]) . ']');
+    });
+    test('sorts data descending', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('id DESC')]);
+        expect($this->getBufferContents())->toBe('[' . implode(',', [TWO, THREE, ONE, FOUR, FIVE]) . ']');
+    });
+    test('sorts data numerically', function () {
+        $this->clearBuffer();
+        Json::outputAll(ThrowawayDb::TABLE, [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect($this->getBufferContents())->toBe('[' . implode(',', [TWO, FOUR, ONE, THREE, FIVE]) . ']');
+    });
+    test('outputs an empty array when no data exists', function () {
+        $this->clearBuffer();
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        Json::outputAll(ThrowawayDb::TABLE);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputById()', function () {
+    test('outputs a document when it exists', function () {
+        $this->clearBuffer();
+        Json::outputById(ThrowawayDb::TABLE, 'two');
+        expect($this->getBufferContents())->toBe(TWO);
+    });
+    test('outputs a document with a numeric ID', function () {
+        $this->clearBuffer();
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        Json::outputById(ThrowawayDb::TABLE, 18);
+        expect($this->getBufferContents())->toBe('{"id":18,"value":"howdy"}');
+    });
+    test('outputs "{}" when no document exists', function () {
+        $this->clearBuffer();
+        Json::outputById(ThrowawayDb::TABLE, 'seventy-five');
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});
+
+describe('::outputByFields()', function () {
+    test('outputs matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            FieldMatch::All);
+        expect($this->getBufferContents())->toBe('[' . FOUR . ']');
+    });
+    test('outputs ordered matching documents', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], FieldMatch::All,
+            [Field::named('id')]);
+        expect($this->getBufferContents())->toBe('[' . implode(',', [FIVE, FOUR]) . ']');
+    });
+    test('outputs documents matching numeric IN clause', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])]);
+        expect($this->getBufferContents())->toBe('[' . THREE . ']');
+    });
+    test('outputs empty array when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)]);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+    test('outputs matching documents for inArray comparison', function () {
+        $this->clearBuffer();
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])]);
+        expect($this->getBufferContents())
+            ->toBe('[{"id":"first","values":["a","b","c"]},{"id":"second","values":["c","d","e"]}]');
+    });
+    test('outputs empty array when no documents match inArray comparison', function () {
+        $this->clearBuffer();
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        Json::outputByFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])]);
+        expect($this->getBufferContents())->toBe('[]');
+    });
+});
+
+describe('::outputByContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::outputByContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::outputByJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::outputByJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::outputFirstByFields()', function () {
+    test('outputs a matching document', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')]);
+        expect($this->getBufferContents())->toBe(TWO);
+    });
+    test('outputs one of several matching documents', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')]);
+        $doc = $this->getBufferContents();
+        expect($doc == TWO || $doc == FOUR)->toBeTrue("Document should have been two or four (actual $doc)");
+    });
+    test('outputs first of ordered matching documents', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')],
+            orderBy: [Field::named('n:num_value DESC')]);
+        expect($this->getBufferContents())->toBe(FOUR);
+    });
+    test('outputs "{}" when no documents match', function () {
+        $this->clearBuffer();
+        Json::outputFirstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')]);
+        expect($this->getBufferContents())->toBe('{}');
+    });
+});
+
+describe('::outputFirstByContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::outputFirstByContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::outputFirstByJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Json::outputFirstByJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/PatchTest.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, DocumentException, Exists, Field, Find, Patch};
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->num_value->toBe(44);
+    });
+    test('does nothing when no document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'forty-seven'))->toBeFalse();
+        Patch::byId(ThrowawayDb::TABLE, 'forty-seven', ['foo' => 'green']);
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates matching documents', function () {
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], ['num_value' => 77]);
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 77)]))->toBe(2);
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'burgundy')]))->toBeFalse();
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'burgundy')], ['foo' => 'green']);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Patch::byContains('', [], []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Patch::byJsonPath('', '', []))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/RemoveFieldsTest.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Exists, Field, Find, RemoveFields};
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())->sub->toBeNull()
+            ->and($tryDoc->get()->value)->toBeEmpty();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('a_field_that_does_not_exist')]))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'one', ['a_field_that_does_not_exist']);
+    });
+    test('does nothing when the document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'fifty'))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'fifty', ['sub']);
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates matching documents', function () {
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['sub']);
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->sub->toBeNull();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('nada')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['nada']);
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')], ['value']);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => RemoveFields::byContains('', [], []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => RemoveFields::byJsonPath('', '', []))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/ThrowawayDb.php

@@ -1,8 +1,15 @@
 <?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
 
 namespace Test\Integration\SQLite;
 
-use BitBadger\PDODocument\{AutoId, Configuration, Definition, Document, DocumentException, Mode};
+use BitBadger\PDODocument\{AutoId, Configuration, Definition, Document, DocumentException};
 use Random\RandomException;
 use Test\Integration\{SubDocument, TestDocument};
 
@@ -12,7 +19,21 @@ use Test\Integration\{SubDocument, TestDocument};
 class ThrowawayDb
 {
     /** @var string The table used for document manipulation */
-    public const TABLE = "test_table";
+    public const TABLE = 'test_table';
+
+    /**
+     * Load data into the test table
+     *
+     * @throws DocumentException If any is encountered
+     */
+    public static function loadData(): void
+    {
+        Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
+        Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
+        Document::insert(self::TABLE, new TestDocument('three', '', 4));
+        Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
+        Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
+    }
 
     /**
      * Create a throwaway SQLite database
@@ -24,17 +45,13 @@ class ThrowawayDb
     public static function create(bool $withData = true): string
     {
         $fileName = sprintf('throwaway-%s.db', AutoId::generateRandom(10));
-        Configuration::$pdoDSN = "sqlite:./$fileName";
+        Configuration::useDSN("sqlite:./$fileName");
-        Configuration::$mode   = Mode::SQLite;
         Configuration::resetPDO();
 
+        Definition::ensureTable(self::TABLE);
+
         if ($withData) {
-            Definition::ensureTable(self::TABLE);
+            self::loadData();
-            Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
-            Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
-            Document::insert(self::TABLE, new TestDocument('three', '', 4));
-            Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
-            Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
         }
 
         return $fileName;

tests/Integration/SQLiteIntegrationTest.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+use BitBadger\PDODocument\{Configuration, Custom, Delete, DocumentException, Field};
+use BitBadger\PDODocument\Mapper\ExistsMapper;
+use Test\Integration\SQLite\ThrowawayDb;
+
+/**
+ * Integration Test Class wrapper for SQLite integration tests
+ */
+class SQLiteIntegrationTest extends DocumentTestCase
+{
+    /** @var string Database name for throwaway database */
+    static private string $dbName = '';
+
+    public static function setUpBeforeClass(): void
+    {
+        self::$dbName = ThrowawayDb::create(false);
+    }
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        ThrowawayDb::loadData();
+    }
+
+    protected function tearDown(): void
+    {
+        Delete::byFields(ThrowawayDb::TABLE, [ Field::exists(Configuration::$idField)]);
+        parent::tearDown();
+    }
+
+    public static function tearDownAfterClass(): void
+    {
+        ThrowawayDb::destroy(self::$dbName);
+        self::$dbName = '';
+    }
+
+    /**
+     * Does the given named object exist in the database?
+     *
+     * @param string $name The name of the object whose existence should be verified
+     * @return bool True if the object exists, false if not
+     * @throws DocumentException If any is encountered
+     */
+    protected function dbObjectExists(string $name): bool
+    {
+        return Custom::scalar('SELECT EXISTS (SELECT 1 FROM sqlite_master WHERE name = :name)',
+            [':name' => $name], new ExistsMapper());
+    }
+}

tests/Integration/SubDocument.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace Test\Integration;
 

tests/Integration/TestDocument.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace Test\Integration;
 

tests/Pest.php

@@ -0,0 +1,55 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| Test Case
+|--------------------------------------------------------------------------
+|
+| The closure you provide to your test functions is always bound to a specific PHPUnit test
+| case class. By default, that class is "PHPUnit\Framework\TestCase". Of course, you may
+| need to change it using the "pest()" function to bind a different classes or traits.
+|
+*/
+
+// pest()->extend(Tests\TestCase::class)->in('Feature');
+pest()->extend(Test\Integration\PgIntegrationTest::class)->in('Integration/PostgreSQL');
+pest()->extend(Test\Integration\SQLiteIntegrationTest::class)->in('Integration/SQLite');
+
+/*
+|--------------------------------------------------------------------------
+| Expectations
+|--------------------------------------------------------------------------
+|
+| When you're writing tests, you often need to check that values meet certain conditions. The
+| "expect()" function gives you access to a set of "expectations" methods that you can use
+| to assert different things. Of course, you may extend the Expectation API at any time.
+|
+*/
+
+expect()->extend('toBeOne', function () {
+    return $this->toBe(1);
+});
+
+/*
+|--------------------------------------------------------------------------
+| Functions
+|--------------------------------------------------------------------------
+|
+| While Pest is very powerful out-of-the-box, you may have some testing code specific to your
+| project that you don't want to repeat in every file. Here you can also expose helpers as
+| global functions to help you to reduce the number of lines of code in your test files.
+|
+*/
+
+/**
+ * Reset the database mode
+ */
+function reset_mode(): void
+{
+    \BitBadger\PDODocument\Configuration::overrideMode(null);
+}
+
+function something()
+{
+    // ..
+}

tests/PjsonDocument.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace Test;
 

tests/PjsonId.php

@@ -1,4 +1,10 @@
-<?php declare(strict_types=1);
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
 
 namespace Test;
 
@@ -7,7 +13,7 @@ use Square\Pjson\JsonDataSerializable;
 /**
  * A serializable ID wrapper class
  */
-class PjsonId implements JsonDataSerializable
+final class PjsonId implements JsonDataSerializable
 {
     public function __construct(protected string $value) { }
 
@@ -16,6 +22,11 @@ class PjsonId implements JsonDataSerializable
         return $this->value;
     }
 
+    /**
+     * @param mixed $jd JSON data
+     * @param mixed[]|string $path path segments
+     * @return static
+     */
     public static function fromJsonData($jd, array|string $path = []): static
     {
         return new static($jd);

tests/Unit/ConfigurationTest.php

@@ -0,0 +1,36 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{AutoId, Configuration, DocumentException};
+
+pest()->group('unit');
+
+describe('::$idField', function () {
+    test('has expected default value', function () {
+        expect(Configuration::$idField)->toBe('id');
+    });
+});
+
+describe('::$autoId', function () {
+    test('has expected default value', function () {
+        expect(Configuration::$autoId)->toBe(AutoId::None);
+    });
+});
+
+describe('::$idStringLength', function () {
+    test('has expected default value', function () {
+        expect(Configuration::$idStringLength)->toBe(16);
+    });
+});
+
+describe('::dbConn()', function () {
+    test('throws if DSN has not been set', function () {
+        Configuration::useDSN('');
+        expect(fn() => Configuration::dbConn())->toThrow(DocumentException::class);
+    });
+});

tests/Unit/DocumentExceptionTest.php

@@ -0,0 +1,40 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\DocumentException;
+
+pest()->group('unit');
+
+describe('Constructor', function () {
+    test('fills code and prior exception if provided', function () {
+        $priorEx = new Exception('Uh oh');
+        expect(new DocumentException('Test Exception', 17, $priorEx))
+            ->not->toBeNull()
+            ->getMessage()->toBe('Test Exception')
+            ->getCode()->toBe(17)
+            ->getPrevious()->toBe($priorEx);
+    });
+    test('uses expected code and prior exception if not provided', function () {
+        expect(new DocumentException('Oops'))
+            ->not->toBeNull()
+            ->getMessage()->toBe('Oops')
+            ->getCode()->toBe(0)
+            ->getPrevious()->toBeNull();
+    });
+});
+
+describe('->__toString()', function () {
+    test('excludes code if 0', function () {
+        $ex = new DocumentException('Test failure');
+        expect("$ex")->toBe("BitBadger\PDODocument\DocumentException: Test failure\n");
+    });
+    test('includes code if non-zero', function () {
+        $ex = new DocumentException('Oof', -6);
+        expect("$ex")->toBe("BitBadger\PDODocument\DocumentException: [-6] Oof\n");
+    });
+});

tests/Unit/FieldMatchTest.php

@@ -0,0 +1,20 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\FieldMatch;
+
+pest()->group('unit');
+
+describe('->toSQL()', function () {
+    test('returns AND for All', function () {
+        expect(FieldMatch::All)->toSQL()->toBe('AND');
+    });
+    test('returns OR for Any', function () {
+        expect(FieldMatch::Any)->toSQL()->toBe('OR');
+    });
+});

tests/Unit/FieldTest.php

@@ -0,0 +1,418 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, Field, Mode, Op};
+
+pest()->group('unit');
+
+describe('->appendParameter()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('appends no parameter for exists', function () {
+        expect(Field::exists('exists')->appendParameter([]))->toBeEmpty();
+    });
+    test('appends no parameter for notExists', function () {
+        expect(Field::notExists('absent')->appendParameter([]))->toBeEmpty();
+    });
+    test('appends two parameters for between', function () {
+        expect(Field::between('exists', 5, 9, '@num')->appendParameter([]))
+            ->toHaveLength(2)
+            ->toEqual(['@nummin' => 5, '@nummax' => 9]);
+    });
+    test('appends a parameter for each value for in', function () {
+        expect(Field::in('it', ['test', 'unit', 'great'], ':val')->appendParameter([]))
+            ->toHaveLength(3)
+            ->toEqual([':val_0' => 'test', ':val_1' => 'unit', ':val_2' => 'great']);
+    });
+    test('appends a parameter for each value for inArray [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::inArray('it', 'table', [2, 8, 64], ':bit')->appendParameter([]))
+            ->toHaveLength(3)
+            ->toEqual([':bit_0' => '2', ':bit_1' => '8', ':bit_2' => '64']);
+    })->group('postgresql');
+    test('appends a parameter for each value for inArray [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::inArray('it', 'table', [2, 8, 64], ':bit')->appendParameter([]))
+            ->toHaveLength(3)
+            ->toEqual([':bit_0' => 2, ':bit_1' => 8, ':bit_2' => 64]);
+    })->group('sqlite');
+    test('appends a parameter for other operators', function () {
+        expect(Field::equal('the_field', 33, ':test')->appendParameter([]))
+            ->toHaveLength(1)
+            ->toEqual([':test' => 33]);
+    });
+});
+
+describe('->path()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('returns simple SQL path [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::equal('it', 'that'))->path()->toBe("data->>'it'");
+    })->group('postgresql');
+    test('returns simple SQL path [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::equal('top', 'that'))->path()->toBe("data->>'top'");
+    })->group('sqlite');
+    test('returns nested SQL path [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::equal('parts.to.the.path', ''))->path()->toBe("data#>>'{parts,to,the,path}'");
+    })->group('postgresql');
+    test('returns nested SQL path [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::equal('one.two.three', ''))->path()->toBe("data->'one'->'two'->>'three'");
+    })->group('sqlite');
+    test('returns simple JSON path [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::equal('it', 'that'))->path(true)->toBe("data->'it'");
+    })->group('postgresql');
+    test('returns simple JSON path [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::equal('top', 'that'))->path(true)->toBe("data->'top'");
+    })->group('sqlite');
+    test('returns nested JSON path [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::equal('parts.to.the.path', ''))->path(true)->toBe("data#>'{parts,to,the,path}'");
+    })->group('postgresql');
+    test('returns nested JSON path [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::equal('one.two.three', ''))->path(true)->toBe("data->'one'->'two'->'three'");
+    })->group('sqlite');
+});
+
+describe('->toWhere()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('generates IS NOT NULL for exists w/o qualifier [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::exists('that_field'))->toWhere()->toBe("data->>'that_field' IS NOT NULL");
+    })->group('postgresql');
+    test('generates IS NOT NULL for exists w/o qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::exists('that_field'))->toWhere()->toBe("data->>'that_field' IS NOT NULL");
+    })->group('sqlite');
+    test('generates IS NULL for notExists w/o qualifier [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::notExists('a_field'))->toWhere()->toBe("data->>'a_field' IS NULL");
+    })->group('postgresql');
+    test('generates IS NULL for notExists w/o qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::notExists('a_field'))->toWhere()->toBe("data->>'a_field' IS NULL");
+    })->group('sqlite');
+    test('generates BETWEEN for between w/o qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::between('age', 13, 17, '@age'))->toWhere()->toBe("data->>'age' BETWEEN @agemin AND @agemax");
+    })->group('sqlite');
+    test('generates BETWEEN for between w/o qualifier, numeric range [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::between('age', 13, 17, '@age'))->toWhere()
+            ->toBe("(data->>'age')::numeric BETWEEN @agemin AND @agemax");
+    })->group('postgresql');
+    test('generates BETWEEN for between w/o qualifier, non-numeric range [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::between('city', 'Atlanta', 'Chicago', ':city'))->toWhere()
+            ->toBe("data->>'city' BETWEEN :citymin AND :citymax");
+    })->group('postgresql');
+    test('generates BETWEEN for between w/ qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        $field = Field::between('age', 13, 17, '@age');
+        $field->qualifier = 'me';
+        expect($field)->toWhere()->toBe("me.data->>'age' BETWEEN @agemin AND @agemax");
+    })->group('sqlite');
+    test('generates BETWEEN for between w/ qualifier, numeric range [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        $field = Field::between('age', 13, 17, '@age');
+        $field->qualifier = 'me';
+        expect($field)->toWhere()->toBe("(me.data->>'age')::numeric BETWEEN @agemin AND @agemax");
+    })->group('postgresql');
+    test('generates BETWEEN for between w/ qualifier, non-numeric range [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        $field = Field::between('city', 'Atlanta', 'Chicago', ':city');
+        $field->qualifier = 'me';
+        expect($field)->toWhere()->toBe("me.data->>'city' BETWEEN :citymin AND :citymax");
+    })->group('postgresql');
+    test('generates IN for in, non-numeric values [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::in('test', ['Atlanta', 'Chicago'], ':city'))->toWhere()
+            ->toBe("data->>'test' IN (:city_0, :city_1)");
+    })->group('postgresql');
+    test('generates IN for in, numeric values [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::in('even', [2, 4, 6], ':nbr'))->toWhere()
+            ->toBe("(data->>'even')::numeric IN (:nbr_0, :nbr_1, :nbr_2)");
+    })->group('postgresql');
+    test('generates IN for in [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::in('test', ['Atlanta', 'Chicago'], ':city'))->toWhere()
+            ->toBe("data->>'test' IN (:city_0, :city_1)");
+    })->group('sqlite');
+    test('generates clause for inArray [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::inArray('even', 'tbl', [2, 4, 6, 8], ':it'))->toWhere()
+            ->toBe("data->'even' ??| ARRAY[:it_0, :it_1, :it_2, :it_3]");
+    })->group('postgresql');
+    test('generates clause for inArray [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::inArray('test', 'tbl', ['Atlanta', 'Chicago'], ':city'))->toWhere()
+            ->toBe("EXISTS (SELECT 1 FROM json_each(tbl.data, '\$.test') WHERE value IN (:city_0, :city_1))");
+    })->group('sqlite');
+    test('generates clause for other operators w/o qualifier [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Field::equal('some_field', '', ':value'))->toWhere()->toBe("data->>'some_field' = :value");
+    })->group('postgresql');
+    test('generates clause for other operators w/o qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Field::equal('some_field', '', ':value'))->toWhere()->toBe("data->>'some_field' = :value");
+    })->group('sqlite');
+    test('generates no-parameter clause w/ qualifier [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        $field = Field::exists('no_field');
+        $field->qualifier = 'test';
+        expect($field)->toWhere()->toBe("test.data->>'no_field' IS NOT NULL");
+    })->group('postgresql');
+    test('generates no-parameter clause w/ qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        $field = Field::exists('no_field');
+        $field->qualifier = 'test';
+        expect($field)->toWhere()->toBe("test.data->>'no_field' IS NOT NULL");
+    })->group('sqlite');
+    test('generates parameter clause w/ qualifier [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        $field = Field::lessOrEqual('le_field', 18, ':it');
+        $field->qualifier = 'q';
+        expect($field)->toWhere()->toBe("(q.data->>'le_field')::numeric <= :it");
+    })->group('postgresql');
+    test('generates parameter clause w/ qualifier [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        $field = Field::lessOrEqual('le_field', 18, ':it');
+        $field->qualifier = 'q';
+        expect($field)->toWhere()->toBe("q.data->>'le_field' <= :it");
+    })->group('sqlite');
+});
+
+describe('::equal()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::equal('my_test', 9);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('my_test')
+            ->op->toBe(Op::Equal)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(9);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::equal('another_test', 'turkey', ':test');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('another_test')
+            ->op->toBe(Op::Equal)
+            ->paramName->toBe(':test')
+            ->and($field->value)->toBe('turkey');
+    });
+});
+
+describe('::greater()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::greater('your_test', 4);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('your_test')
+            ->op->toBe(Op::Greater)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(4);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::greater('more_test', 'chicken', ':value');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('more_test')
+            ->op->toBe(Op::Greater)
+            ->paramName->toBe(':value')
+            ->and($field->value)->toBe('chicken');
+    });
+});
+
+describe('::greaterOrEqual()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::greaterOrEqual('their_test', 6);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('their_test')
+            ->op->toBe(Op::GreaterOrEqual)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(6);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::greaterOrEqual('greater_test', 'poultry', ':cluck');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('greater_test')
+            ->op->toBe(Op::GreaterOrEqual)
+            ->paramName->toBe(':cluck')
+            ->and($field->value)->toBe('poultry');
+    });
+});
+
+describe('::less()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::less('z', 32);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('z')
+            ->op->toBe(Op::Less)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(32);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::less('additional_test', 'fowl', ':boo');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('additional_test')
+            ->op->toBe(Op::Less)
+            ->paramName->toBe(':boo')
+            ->and($field->value)->toBe('fowl');
+    });
+});
+
+describe('::lessOrEqual()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::lessOrEqual('g', 87);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('g')
+            ->op->toBe(Op::LessOrEqual)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(87);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::lessOrEqual('lesser_test', 'hen', ':woo');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('lesser_test')
+            ->op->toBe(Op::LessOrEqual)
+            ->paramName->toBe(':woo')
+            ->and($field->value)->toBe('hen');
+    });
+});
+
+describe('::notEqual()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::notEqual('j', 65);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('j')
+            ->op->toBe(Op::NotEqual)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBe(65);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::notEqual('unequal_test', 'egg', ':zoo');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('unequal_test')
+            ->op->toBe(Op::NotEqual)
+            ->paramName->toBe(':zoo')
+            ->and($field->value)->toBe('egg');
+    });
+});
+
+describe('::between()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::between('k', 'alpha', 'zed');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('k')
+            ->op->toBe(Op::Between)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toEqual(['alpha', 'zed']);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::between('between_test', 18, 49, ':count');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('between_test')
+            ->op->toBe(Op::Between)
+            ->paramName->toBe(':count')
+            ->and($field->value)->toEqual([18, 49]);
+    });
+});
+
+describe('::in()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::in('test', [1, 2, 3]);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('test')
+            ->op->toBe(Op::In)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toEqual([1, 2, 3]);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::in('unit', ['a', 'b'], ':inParam');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('unit')
+            ->op->toBe(Op::In)
+            ->paramName->toBe(':inParam')
+            ->and($field->value)->toEqual(['a', 'b']);
+    });
+});
+
+describe('::inArray()', function () {
+    test('creates Field w/o parameter', function () {
+        $field = Field::inArray('test', 'tbl', [1, 2, 3]);
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('test')
+            ->op->toBe(Op::InArray)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toEqual(['table' => 'tbl', 'values' => [1, 2, 3]]);
+    });
+    test('creates Field w/ parameter', function () {
+        $field = Field::inArray('unit', 'tab', ['a', 'b'], ':inAParam');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('unit')
+            ->op->toBe(Op::InArray)
+            ->paramName->toBe(':inAParam')
+            ->and($field->value)->toEqual(['table' => 'tab', 'values' => ['a', 'b']]);
+    });
+});
+
+describe('::exists()', function () {
+    test('creates Field', function () {
+        $field = Field::exists('be_there');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('be_there')
+            ->op->toBe(Op::Exists)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBeEmpty();
+    });
+});
+
+describe('::notExists()', function () {
+    test('creates Field', function () {
+        $field = Field::notExists('be_absent');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('be_absent')
+            ->op->toBe(Op::NotExists)
+            ->paramName->toBeEmpty()
+            ->and($field->value)->toBeEmpty();
+    });
+});
+
+describe('::named()', function () {
+    test('creates Field', function () {
+        $field = Field::named('the_field');
+        expect($field)
+            ->not->toBeNull()
+            ->fieldName->toBe('the_field')
+            ->op->toBe(Op::Equal)
+            ->value->toBeEmpty()
+            ->and($field->value)->toBeEmpty();
+    });
+});

tests/Unit/Mapper/ArrayMapperTest.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\Mapper\ArrayMapper;
+
+pest()->group('unit');
+
+describe('->map()', function () {
+    test('returns the given array', function () {
+        $result = ['one' => 2, 'three' => 4, 'eight' => 'five'];
+        expect((new ArrayMapper())->map($result))->toBe($result);
+    });
+});

tests/Unit/Mapper/CountMapperTest.php

@@ -0,0 +1,17 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\Mapper\CountMapper;
+
+pest()->group('unit');
+
+describe('->map()', function () {
+    test('returns item 0 in the given array', function () {
+        expect((new CountMapper())->map([5, 8, 10]))->toBe(5);
+    });
+});

tests/Unit/Mapper/DocumentMapperTest.php

@@ -0,0 +1,65 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Field};
+use BitBadger\PDODocument\Mapper\DocumentMapper;
+use Test\{PjsonDocument, PjsonId};
+
+// ** Test class hierarchy for serialization **
+
+class DocMapSubDoc
+{
+    public function __construct(public int $id = 0, public string $name = '') { }
+}
+
+class DocMapTestDoc
+{
+    public function __construct(public int $id = 0, public DocMapSubDoc $subDoc = new DocMapSubDoc()) { }
+}
+
+pest()->group('unit');
+
+describe('Constructor', function () {
+    test('uses "data" as the default field name', function () {
+        expect(new DocumentMapper(Field::class))->fieldName->toBe('data');
+    });
+    test('uses the provided field name', function () {
+        expect(new DocumentMapper(Field::class, 'json'))->fieldName->toBe('json');
+    });
+});
+
+describe('->map()', function () {
+    test('deserializes valid JSON', function () {
+        $doc = (new DocumentMapper(DocMapTestDoc::class))
+            ->map(['data' => '{"id":7,"subDoc":{"id":22,"name":"tester"}}']);
+        expect($doc)
+            ->not->toBeNull()
+            ->id->toBe(7)
+            ->and($doc->subDoc)
+            ->not->toBeNull()
+            ->id->toBe(22)
+            ->name->toBe('tester');
+    });
+    test('deserializes valid JSON [Pjson]', function () {
+        $doc = (new DocumentMapper(PjsonDocument::class))->map(['data' => '{"id":"seven","name":"bob","num_value":8}']);
+        expect($doc)
+            ->not->toBeNull()
+            ->id->toEqual(new PjsonId('seven'))
+            ->name->toBe('bob')
+            ->numValue->toBe(8)
+            ->skipped->toBeEmpty();
+    });
+    test('throws for invalid JSON', function () {
+        expect(fn() => (new DocumentMapper(DocMapTestDoc::class))->map(['data' => 'this is not valid']))
+            ->toThrow(DocumentException::class);
+    });
+    test('throws for invalid JSON [Pjson]', function () {
+        expect(fn() => (new DocumentMapper(PjsonDocument::class))->map(['data' => 'not even close']))
+            ->toThrow(DocumentException::class);
+    });
+});

tests/Unit/Mapper/ExistsMapperTest.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Mode};
+use BitBadger\PDODocument\Mapper\ExistsMapper;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('->map()', function () {
+    test('returns a boolean value from index 0 [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect((new ExistsMapper())->map([false, 'nope']))->toBeFalse();
+    });
+    test('returns a number value as boolean from index 0 [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect((new ExistsMapper())->map([1, 'yep']))->toBeTrue();
+    });
+    test('throws if mode is not set', function () {
+        expect(fn() => (new ExistsMapper())->map(['0']))->toThrow(DocumentException::class);
+    });
+});

tests/Unit/Mapper/StringMapperTest.php

@@ -0,0 +1,23 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\Mapper\StringMapper;
+
+pest()->group('unit');
+
+describe('->map()', function () {
+    test('returns existing string column value', function () {
+        expect(new StringMapper('test_field'))->map(['test_field' => 'test_value'])->toBe('test_value');
+    });
+    test('returns string value of non-string column', function () {
+        expect(new StringMapper('a_number'))->map(['a_number' => 6.7])->toBe('6.7');
+    });
+    test('returns null for a missing column', function () {
+        expect(new StringMapper('something_else'))->map([])->toBeNull();
+    });
+});

tests/Unit/ModeTest.php

@@ -0,0 +1,23 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Mode};
+
+pest()->group('unit');
+
+describe('::deriveFromDSN()', function () {
+    test('derives for PostgreSQL', function () {
+        expect(Mode::deriveFromDSN('pgsql:Host=localhost'))->toBe(Mode::PgSQL);
+    })->group('postgresql');
+    test('derives for SQLite', function () {
+        expect(Mode::deriveFromDSN('sqlite:data.db'))->toBe(Mode::SQLite);
+    })->group('sqlite');
+    test('throws for other drivers', function () {
+        expect(fn() => Mode::deriveFromDSN('mysql:Host=localhost'))->toThrow(DocumentException::class);
+    });
+});

tests/Unit/OpTest.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\Op;
+
+pest()->group('unit');
+
+describe('->toSQL()', function () {
+    test('returns "=" for Equal', function () {
+        expect(Op::Equal)->toSQL()->toBe('=');
+    });
+    test('returns ">" for Greater', function () {
+        expect(Op::Greater)->toSQL()->toBe('>');
+    });
+    test('returns ">=" for GreaterOrEqual', function () {
+        expect(Op::GreaterOrEqual)->toSQL()->toBe('>=');
+    });
+    test('returns "<" for Less', function () {
+        expect(Op::Less)->toSQL()->toBe('<');
+    });
+    test('returns "<=" for LessOrEqual', function () {
+        expect(Op::LessOrEqual)->toSQL()->toBe('<=');
+    });
+    test('returns "<>" for NotEqual', function () {
+        expect(Op::NotEqual)->toSQL()->toBe('<>');
+    });
+    test('returns "BETWEEN" for Between', function () {
+        expect(Op::Between)->toSQL()->toBe('BETWEEN');
+    });
+    test('returns "IN" for In', function () {
+        expect(Op::In)->toSQL()->toBe('IN');
+    });
+    test('returns "?|" (escaped) for InArray', function () {
+        expect(Op::InArray)->toSQL()->toBe('??|');
+    });
+    test('returns "IS NOT NULL" for Exists', function () {
+        expect(Op::Exists)->toSQL()->toBe('IS NOT NULL');
+    });
+    test('returns "IS NULL" for NotExists', function () {
+        expect(Op::NotExists)->toSQL()->toBe('IS NULL');
+    });
+});

tests/Unit/ParametersTest.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode, Parameters};
+use Test\{PjsonDocument, PjsonId};
+
+pest()->group('unit');
+
+describe('::id()', function () {
+    test('creates string ID parameter', function () {
+        expect(Parameters::id('key'))->toEqual([':id' => 'key']);
+    });
+    test('creates string from numeric ID parameter', function () {
+        expect(Parameters::id(7))->toEqual([':id' => '7']);
+    });
+});
+
+describe('::json()', function () {
+    test('serializes an array', function () {
+        expect(Parameters::json(':it', ['id' => 18, 'url' => 'https://www.unittest.com']))
+            ->toEqual([':it' => '{"id":18,"url":"https://www.unittest.com"}']);
+    });
+    test('serializes an array w/ an empty array value', function () {
+        expect(Parameters::json(':it', ['id' => 18, 'urls' => []]))->toEqual([':it' => '{"id":18,"urls":[]}']);
+    });
+    test('serializes a 1-D array w/ an empty array value', function () {
+        expect(Parameters::json(':it', ['urls' => []]))->toEqual([':it' => '{"urls":[]}']);
+    });
+    test('serializes a stdClass instance', function () {
+        $obj      = new stdClass();
+        $obj->id  = 19;
+        $obj->url = 'https://testhere.info';
+        expect(Parameters::json(':it', $obj))->toEqual([':it' => '{"id":19,"url":"https://testhere.info"}']);
+    });
+    test('serializes a Pjson class instance', function () {
+        expect(Parameters::json(':it', new PjsonDocument(new PjsonId('999'), 'a test', 98, 'nothing')))
+            ->toEqual([':it' => '{"id":"999","name":"a test","num_value":98}']);
+    });
+    test('serializes an array of Pjson class instances', function () {
+        expect(Parameters::json(':it',
+            ['pjson' => [new PjsonDocument(new PjsonId('997'), 'another test', 94, 'nothing')]]))
+            ->toEqual([':it' => '{"pjson":[{"id":"997","name":"another test","num_value":94}]}']);
+    });
+});
+
+describe('::nameFields()', function () {
+    test('provides missing parameter names', function () {
+        $named = [Field::equal('it', 17), Field::equal('also', 22, ':also'), Field::equal('other', 24)];
+        Parameters::nameFields($named);
+        expect($named)
+            ->toHaveLength(3)
+            ->sequence(
+                fn($it) => $it->paramName->toBe(':field0'),
+                fn($it) => $it->paramName->toBe(':also'),
+                fn($it) => $it->paramName->toBe(':field2'));
+    });
+});
+
+describe('::addFields()', function () {
+    test('appends to an existing parameter array', function () {
+        expect(Parameters::addFields([Field::equal('b', 'two', ':b'), Field::equal('z', 18, ':z')], [':a' => 1]))
+            ->toEqual([':a' => 1, ':b' => 'two', ':z' => 18]);
+    });
+});
+
+describe('::fieldNames()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('generates names [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Parameters::fieldNames(':names', ['one', 'two', 'seven']))->toEqual([':names' => "{one,two,seven}"]);
+    })->group('postgresql');
+    test('generates names [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Parameters::fieldNames(':it', ['test', 'unit', 'wow']))
+            ->toEqual([':it0' => '$.test', ':it1' => '$.unit', ':it2' => '$.wow']);
+    })->group('sqlite');
+    test('throws when mode is not set', function () {
+        expect(fn() => Parameters::fieldNames('', []))->toThrow(DocumentException::class);
+    });
+});

tests/Unit/Query/CountTest.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode};
+use BitBadger\PDODocument\Query\Count;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::all()', function () {
+    test('generates the correct SQL', function () {
+        expect(Count::all('a_table'))->toBe('SELECT COUNT(*) FROM a_table');
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates the correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Count::byFields('somewhere', [Field::greater('errors', 10, ':errors')]))
+            ->toBe("SELECT COUNT(*) FROM somewhere WHERE data->>'errors' > :errors");
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates the correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Count::byContains('the_table'))->toBe('SELECT COUNT(*) FROM the_table WHERE data @> :criteria');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Count::byContains(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates the correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Count::byJsonPath('a_table'))
+            ->toBe('SELECT COUNT(*) FROM a_table WHERE jsonb_path_exists(data, :path::jsonpath)');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Count::byJsonPath(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/Query/DefinitionTest.php

@@ -0,0 +1,65 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, DocumentIndex, Mode};
+use BitBadger\PDODocument\Query\Definition;
+
+pest()->group('unit');
+
+describe('::ensureTable()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Definition::ensureTable('documents'))
+            ->toBe('CREATE TABLE IF NOT EXISTS documents (data JSONB NOT NULL)');
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Definition::ensureTable('dox'))->toBe('CREATE TABLE IF NOT EXISTS dox (data TEXT NOT NULL)');
+    })->group('sqlite');
+    test('throws an exception if mode is not set', function () {
+        expect(fn () => Definition::ensureTable(''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::ensureIndexOn()', function () {
+    test('generates correct SQL for unqualified table, single ascending field', function () {
+        expect(Definition::ensureIndexOn('test', 'fields', ['details']))
+            ->toBe("CREATE INDEX IF NOT EXISTS idx_test_fields ON test ((data->>'details'))");
+    });
+    test('generates correct SQL for qualified table, multiple fields', function () {
+        expect(Definition::ensureIndexOn('sch.testing', 'json', ['group', 'sub_group DESC']))
+            ->toBe('CREATE INDEX IF NOT EXISTS idx_testing_json ON sch.testing '
+                . "((data->>'group'), (data->>'sub_group') DESC)");
+    });
+});
+
+describe('::ensureKey()', function () {
+    test('generates correct SQL', function () {
+        expect(Definition::ensureKey('tbl'))
+            ->toBe("CREATE UNIQUE INDEX IF NOT EXISTS idx_tbl_key ON tbl ((data->>'id'))");
+    });
+});
+
+describe('::ensureDocumentIndexOn()', function () {
+    afterEach(function () { Configuration::overrideMode(null); });
+    test('generates correct SQL for qualified table, full index [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Definition::ensureDocumentIndexOn('my.tbl', DocumentIndex::Full))
+            ->toBe("CREATE INDEX IF NOT EXISTS idx_tbl_document ON my.tbl USING GIN (data)");
+    })->group('postgresql');
+    test('generates correct SQL for unqualified table, optimized index [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Definition::ensureDocumentIndexOn('it', DocumentIndex::Optimized))
+            ->toBe("CREATE INDEX IF NOT EXISTS idx_it_document ON it USING GIN (data jsonb_path_ops)");
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Definition::ensureDocumentIndexOn('', DocumentIndex::Full))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/Query/DeleteTest.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode};
+use BitBadger\PDODocument\Query\Delete;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::byId()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Delete::byId('over_there'))->toBe("DELETE FROM over_there WHERE data->>'id' = :id");
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Delete::byFields('my_table',
+                [Field::less('value', 99, ':max'), Field::greaterOrEqual('value', 18, ':min')]))
+            ->toBe("DELETE FROM my_table WHERE data->>'value' < :max AND data->>'value' >= :min");
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Delete::byContains('somewhere'))->toBe('DELETE FROM somewhere WHERE data @> :criteria');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Delete::byContains(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Delete::byJsonPath('here'))->toBe('DELETE FROM here WHERE jsonb_path_exists(data, :path::jsonpath)');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Delete::byJsonPath(''))->toThrow(DocumentException::class);
+    });
+});

tests/Unit/Query/ExistsTest.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode};
+use BitBadger\PDODocument\Query\Exists;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::query()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Exists::query('abc', 'def'))->toBe('SELECT EXISTS (SELECT 1 FROM abc WHERE def)');
+    });
+});
+
+describe('::byId()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Exists::byId('dox'))->toBe("SELECT EXISTS (SELECT 1 FROM dox WHERE data->>'id' = :id)");
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Exists::byFields('box', [Field::notEqual('status', 'occupied', ':status')]))
+            ->toBe("SELECT EXISTS (SELECT 1 FROM box WHERE data->>'status' <> :status)");
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Exists::byContains('pocket'))->toBe('SELECT EXISTS (SELECT 1 FROM pocket WHERE data @> :criteria)');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Exists::byContains(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Exists::byJsonPath('lint'))
+            ->toBe('SELECT EXISTS (SELECT 1 FROM lint WHERE jsonb_path_exists(data, :path::jsonpath))');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Exists::byJsonPath(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/Query/FindTest.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode};
+use BitBadger\PDODocument\Query\Find;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::byId()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Find::byId('here'))->toBe("SELECT data FROM here WHERE data->>'id' = :id");
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates correct SQL', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Find::byFields('there', [Field::equal('active', true, ':act'), Field::equal('locked', true, ':lock')],
+                FieldMatch::Any))
+            ->toBe("SELECT data FROM there WHERE data->>'active' = :act OR data->>'locked' = :lock");
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Find::byContains('disc'))->toBe('SELECT data FROM disc WHERE data @> :criteria');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Find::byContains(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Find::byJsonPath('light'))
+            ->toBe('SELECT data FROM light WHERE jsonb_path_exists(data, :path::jsonpath)');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Find::byJsonPath(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/Query/PatchTest.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode};
+use BitBadger\PDODocument\Query\Patch;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::byId()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Patch::byId('doc_table'))->toBe("UPDATE doc_table SET data = data || :data WHERE data->>'id' = :id");
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Patch::byId('my_table'))
+            ->toBe("UPDATE my_table SET data = json_patch(data, json(:data)) WHERE data->>'id' = :id");
+    })->group('sqlite');
+    test('throws an exception [mode not set]', function () {
+        expect(fn () => Patch::byId(''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Patch::byFields('that', [Field::less('something', 17, ':some')]))
+            ->toBe("UPDATE that SET data = data || :data WHERE (data->>'something')::numeric < :some");
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(Patch::byFields('a_table', [Field::greater('something', 17, ':it')]))
+            ->toBe("UPDATE a_table SET data = json_patch(data, json(:data)) WHERE data->>'something' > :it");
+    })->group('sqlite');
+    test('throws an exception [mode not set]', function () {
+        expect(fn () => Patch::byFields('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Patch::byContains('this'))->toBe('UPDATE this SET data = data || :data WHERE data @> :criteria');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Patch::byContains(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Patch::byJsonPath('that'))
+            ->toBe('UPDATE that SET data = data || :data WHERE jsonb_path_exists(data, :path::jsonpath)');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(fn () => Patch::byJsonPath(''))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/Query/RemoveFieldsTest.php

@@ -0,0 +1,86 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode, Parameters};
+use BitBadger\PDODocument\Query\RemoveFields;
+
+pest()->group('unit');
+
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::update()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(RemoveFields::update('taco', [':names' => "{one,two}"], 'it = true'))
+            ->toBe('UPDATE taco SET data = data - :names::text[] WHERE it = true');
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(RemoveFields::update('burrito', Parameters::fieldNames(':name', ['one', 'two', 'ten']), 'a = b'))
+            ->toBe('UPDATE burrito SET data = json_remove(data, :name0, :name1, :name2) WHERE a = b');
+    })->group('sqlite');
+    test('throws an exception [mode not set]', function () {
+        expect(fn () => RemoveFields::update('', [], ''))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byId()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(RemoveFields::byId('churro', Parameters::fieldNames(':bite', ['byte'])))
+            ->toBe("UPDATE churro SET data = data - :bite::text[] WHERE data->>'id' = :id");
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(RemoveFields::byId('quesadilla', Parameters::fieldNames(':bite', ['byte'])))
+            ->toBe("UPDATE quesadilla SET data = json_remove(data, :bite0) WHERE data->>'id' = :id");
+    })->group('sqlite');
+    test('throws an exception [mode not set]', function () {
+        expect(fn () => RemoveFields::byId('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byFields()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(RemoveFields::byFields('enchilada', [Field::equal('cheese', 'jack', ':queso')],
+                Parameters::fieldNames(':sauce', ['white'])))
+            ->toBe("UPDATE enchilada SET data = data - :sauce::text[] WHERE data->>'cheese' = :queso");
+    })->group('postgresql');
+    test('generates correct SQL [SQLite]', function () {
+        Configuration::overrideMode(Mode::SQLite);
+        expect(RemoveFields::byFields('chimichanga', [Field::equal('side', 'beans', ':rice')],
+                Parameters::fieldNames(':filling', ['beef'])))
+            ->toBe("UPDATE chimichanga SET data = json_remove(data, :filling0) WHERE data->>'side' = :rice");
+    })->group('sqlite');
+    test('throws an exception [mode not set]', function () {
+        expect(fn () => RemoveFields::byFields('', [], []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byContains()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(RemoveFields::byContains('food', Parameters::fieldNames(':drink', ['a', 'b'])))
+            ->toBe('UPDATE food SET data = data - :drink::text[] WHERE data @> :criteria');
+    })->group('postgresql');
+    test('throws an exception [SQLite]', function () {
+        expect(fn () => RemoveFields::byContains('', []))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});
+
+describe('::byJsonPath()', function () {
+    test('generates correct SQL [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(RemoveFields::byJsonPath('dessert', Parameters::fieldNames(':cake', ['b', 'c'])))
+            ->toBe('UPDATE dessert SET data = data - :cake::text[] WHERE jsonb_path_exists(data, :path::jsonpath)');
+    });
+    test('throws an exception [SQLite]', function () {
+        expect(fn () => RemoveFields::byJsonPath('', []))->toThrow(DocumentException::class);
+    })->group('sqlite');
+});

tests/Unit/QueryTest.php

@@ -0,0 +1,201 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{AutoId, Configuration, DocumentException, Field, FieldMatch, Mode, Query};
+
+pest()->group('unit');
+
+beforeEach(function () { Configuration::overrideMode(Mode::SQLite); });
+afterEach(function () { Configuration::overrideMode(null); });
+
+describe('::selectFromTable()', function () {
+    test('correctly forms a query', function () {
+        expect(Query::selectFromTable('testing'))->toBe('SELECT data FROM testing');
+    });
+});
+
+describe('::whereByFields()', function () {
+    test('generates a single field correctly', function () {
+        expect(Query::whereByFields([Field::lessOrEqual('test_field', '', ':it')]))->toBe("data->>'test_field' <= :it");
+    });
+    test('generates all fields correctly', function () {
+        expect(Query::whereByFields(
+
+                [Field::lessOrEqual('test_field', '', ':it'), Field::equal('other_field', '', ':other')]))
+            ->toBe("data->>'test_field' <= :it AND data->>'other_field' = :other",);
+    });
+    test('generates any field correctly', function () {
+        expect(Query::whereByFields(
+                [Field::lessOrEqual('test_field', '', ':it'), Field::equal('other_field', '', ':other')],
+                FieldMatch::Any))
+            ->toBe("data->>'test_field' <= :it OR data->>'other_field' = :other");
+    });
+});
+
+describe('::whereById()', function () {
+    test('uses default parameter name', function () {
+        expect(Query::whereById())->toBe("data->>'id' = :id");
+    });
+    test('uses provided parameter name', function () {
+        expect(Query::whereById(':di'))->toBe("data->>'id' = :di");
+    });
+});
+
+describe('::whereDataContains()', function () {
+    test('uses default parameter [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::whereDataContains())->toBe('data @> :criteria');
+    });
+    test('uses provided parameter [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::whereDataContains(':it'))->toBe('data @> :it');
+    });
+    test('throws [SQLite]', function () {
+        expect(fn () => Query::whereDataContains())->toThrow(DocumentException::class);
+    });
+});
+
+describe('::whereJsonPathMatches()', function () {
+    test('uses default parameter [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::whereJsonPathMatches())->toBe('jsonb_path_exists(data, :path::jsonpath)');
+    });
+    test('uses provided parameter [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::whereJsonPathMatches(':road'))->toBe('jsonb_path_exists(data, :road::jsonpath)');
+    });
+    test('throws [SQLite]', function () {
+        expect(fn () => Query::whereJsonPathMatches())->toThrow(DocumentException::class);
+    });
+});
+
+describe('::insert()', function () {
+    test('generates with no auto-ID [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::insert('test_tbl'))->toBe('INSERT INTO test_tbl VALUES (:data)');
+    });
+    test('generates with no auto-ID [SQLite]', function () {
+        expect(Query::insert('test_tbl'))->toBe('INSERT INTO test_tbl VALUES (:data)');
+    });
+    test('generates with auto numeric ID [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::insert('test_tbl', AutoId::Number))
+            ->toBe("INSERT INTO test_tbl VALUES (:data::jsonb || ('{\"id\":' "
+                . "|| (SELECT COALESCE(MAX((data->>'id')::numeric), 0) + 1 FROM test_tbl) || '}')::jsonb)");
+    });
+    test('generates with auto numeric ID [SQLite]', function () {
+        expect(Query::insert('test_tbl', AutoId::Number))
+            ->toBe("INSERT INTO test_tbl VALUES (json_set(:data, '$.id', "
+                . "(SELECT coalesce(max(data->>'id'), 0) + 1 FROM test_tbl)))");
+    });
+    test('generates with auto UUID [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::insert('test_tbl', AutoId::UUID))
+            ->toStartWith("INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"")
+            ->toEndWith("\"}')");
+    });
+    test('generates with auto UUID [SQLite]', function () {
+        expect(Query::insert('test_tbl', AutoId::UUID))
+            ->toStartWith("INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '")
+            ->toEndWith("'))");
+    });
+    test('generates with auto random string [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        Configuration::$idStringLength = 8;
+        try {
+            $query = Query::insert('test_tbl', AutoId::RandomString);
+            expect($query)
+                ->toStartWith("INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"")
+                ->toEndWith("\"}')")
+                ->and(str_replace(["INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"", "\"}')"], '', $query))
+                ->toHaveLength(8);
+        } finally {
+            Configuration::$idStringLength = 16;
+        }
+    });
+    test('generates with auto random string [SQLite]', function () {
+        $query = Query::insert('test_tbl', AutoId::RandomString);
+        expect($query)
+            ->toStartWith("INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '")
+            ->toEndWith("'))")
+            ->and(str_replace(["INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '", "'))"], '', $query))
+            ->toHaveLength(16);
+    });
+    test('throws when mode not set', function () {
+        Configuration::overrideMode(null);
+        expect(fn () => Query::insert('kaboom'))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::save()', function () {
+    test('generates the correct query', function () {
+        expect(Query::save('test_tbl'))
+            ->toBe("INSERT INTO test_tbl VALUES (:data) ON CONFLICT ((data->>'id')) DO UPDATE SET data = EXCLUDED.data");
+    });
+});
+
+describe('::update()', function () {
+    test('generates the correct query', function () {
+        expect(Query::update('testing'))->toBe("UPDATE testing SET data = :data WHERE data->>'id' = :id");
+    });
+});
+
+describe('::orderBy()', function () {
+    test('returns blank for no criteria [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::orderBy([]))->toBeEmpty();
+    });
+    test('returns blank for no criteria [SQLite]', function () {
+        expect(Query::orderBy([]))->toBeEmpty();
+    });
+    test('generates one field with no direction [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::orderBy([Field::named('TestField')]))->toBe(" ORDER BY data->>'TestField'");
+    });
+    test('generates one field with no direction [SQLite]', function () {
+        expect(Query::orderBy([Field::named('TestField')]))->toBe(" ORDER BY data->>'TestField'");
+    });
+    test('generates with one qualified field [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        $field = Field::named('TestField');
+        $field->qualifier = 'qual';
+        expect(Query::orderBy([$field]))->toBe(" ORDER BY qual.data->>'TestField'");
+    });
+    test('generates with one qualified field [SQLite]', function () {
+        $field = Field::named('TestField');
+        $field->qualifier = 'qual';
+        expect(Query::orderBy([$field]))->toBe(" ORDER BY qual.data->>'TestField'");
+    });
+    test('generates with multiple fields and direction [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::orderBy(
+                [Field::named('Nested.Test.Field DESC'), Field::named('AnotherField'), Field::named('It DESC')]))
+            ->toBe(" ORDER BY data#>>'{Nested,Test,Field}' DESC, data->>'AnotherField', data->>'It' DESC");
+    });
+    test('generates with multiple fields and direction [SQLite]', function () {
+        expect(Query::orderBy(
+                [Field::named('Nested.Test.Field DESC'), Field::named('AnotherField'), Field::named('It DESC')]))
+            ->toBe(" ORDER BY data->'Nested'->'Test'->>'Field' DESC, data->>'AnotherField', data->>'It' DESC");
+    });
+    test('generates with numeric field [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::orderBy([Field::named('n:Test')]))->toBe(" ORDER BY (data->>'Test')::numeric");
+    });
+    test('generates with numeric field [SQLite]', function () {
+        expect(Query::orderBy([Field::named('n:Test')]))->toBe(" ORDER BY data->>'Test'");
+    });
+    test('generates case-insensitive ordering [PostgreSQL]', function () {
+        Configuration::overrideMode(Mode::PgSQL);
+        expect(Query::orderBy([Field::named('i:Test.Field DESC NULLS FIRST')]))
+            ->toBe(" ORDER BY LOWER(data#>>'{Test,Field}') DESC NULLS FIRST");
+    });
+    test('generates case-insensitive ordering [SQLite]', function () {
+        expect(Query::orderBy([Field::named('i:Test.Field ASC NULLS LAST')]))
+            ->toBe(" ORDER BY data->'Test'->>'Field' COLLATE NOCASE ASC NULLS LAST");
+    });
+});

tests/integration/postgresql/CountTest.php

@@ -1,73 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{Count, Field};
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-
-/**
- * PostgreSQL integration tests for the Count class
- */
-#[TestDox('Count (PostgreSQL integration)')]
-class CountTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    public function testAllSucceeds(): void
-    {
-        $count = Count::all(ThrowawayDb::TABLE);
-        $this->assertEquals(5, $count, 'There should have been 5 matching documents');
-    }
-
-    public function testByFieldsSucceedsForANumericRange(): void
-    {
-        $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('num_value', 10, 20)]);
-        $this->assertEquals(3, $count, 'There should have been 3 matching documents');
-    }
-
-    public function testByFieldsSucceedsForANonNumericRange(): void
-    {
-        $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('value', 'aardvark', 'apple')]);
-        $this->assertEquals(1, $count, 'There should have been 1 matching document');
-    }
-
-    public function testByContainsSucceedsWhenDocumentsMatch(): void
-    {
-        $this->assertEquals(2, Count::byContains(ThrowawayDb::TABLE, ['value' => 'purple']),
-            'There should have been 2 matching documents');
-    }
-
-    public function testByContainsSucceedsWhenNoDocumentsMatch(): void
-    {
-        $this->assertEquals(0, Count::byContains(ThrowawayDb::TABLE, ['value' => 'magenta']),
-            'There should have been no matching documents');
-    }
-
-    #[TestDox('By JSON Path succeeds when documents match')]
-    public function testByJsonPathSucceedsWhenDocumentsMatch(): void
-    {
-        $this->assertEquals(2, Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 5)'),
-            'There should have been 2 matching documents');
-    }
-
-    #[TestDox('By JSON Path succeeds when no documents match')]
-    public function testByJsonPathSucceedsWhenNoDocumentsMatch(): void
-    {
-        $this->assertEquals(0, Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)'),
-            'There should have been no matching documents');
-    }
-}

tests/integration/postgresql/CustomTest.php

@@ -1,121 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{Count, Custom, DocumentException, Query};
-use BitBadger\PDODocument\Mapper\{CountMapper, DocumentMapper};
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-use Test\Integration\TestDocument;
-
-/**
- * PostgreSQL integration tests for the Custom class
- */
-#[TestDox('Custom (PostgreSQL integration)')]
-class CustomTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    public function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    public function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-    }
-
-    public function testRunQuerySucceedsWithAValidQuery()
-    {
-        $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []);
-        try {
-            $this->assertNotNull($stmt, 'The statement should not have been null');
-        } finally {
-            $stmt = null;
-        }
-    }
-
-    public function testRunQueryFailsWithAnInvalidQuery()
-    {
-        $this->expectException(DocumentException::class);
-        $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []);
-        try {
-            $this->assertTrue(false, 'This code should not be reached');
-        } finally {
-            $stmt = null;
-        }
-    }
-
-    public function testListSucceedsWhenDataIsFound()
-    {
-        $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'The document list should not be null');
-        $count = 0;
-        foreach ($list->items() as $ignored) $count++;
-        $this->assertEquals(5, $count, 'There should have been 5 documents in the list');
-    }
-
-    public function testListSucceedsWhenNoDataIsFound()
-    {
-        $list = Custom::list(
-            Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric > :value",
-            [':value' => 100], new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'The document list should not be null');
-        $this->assertFalse($list->hasItems(), 'There should have been no documents in the list');
-    }
-
-    public function testArraySucceedsWhenDataIsFound()
-    {
-        $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [],
-            new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($array, 'The document array should not be null');
-        $this->assertCount(2, $array, 'There should have been 2 documents in the array');
-    }
-
-    public function testArraySucceedsWhenNoDataIsFound()
-    {
-        $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value",
-            [':value' => 'not there'], new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($array, 'The document array should not be null');
-        $this->assertCount(0, $array, 'There should have been no documents in the array');
-    }
-
-    public function testSingleSucceedsWhenARowIsFound(): void
-    {
-        $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id", [':id' => 'one'],
-            new DocumentMapper(TestDocument::class));
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-        $this->assertEquals('one', $doc->get()->id, 'The incorrect document was returned');
-    }
-
-    public function testSingleSucceedsWhenARowIsNotFound(): void
-    {
-        $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id",
-            [':id' => 'eighty'], new DocumentMapper(TestDocument::class));
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
-    }
-
-    public function testNonQuerySucceedsWhenOperatingOnData()
-    {
-        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-        $remaining = Count::all(ThrowawayDb::TABLE);
-        $this->assertEquals(0, $remaining, 'There should be no documents remaining in the table');
-    }
-
-    public function testNonQuerySucceedsWhenNoDataMatchesWhereClause()
-    {
-        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE (data->>'num_value')::numeric > :value",
-            [':value' => 100]);
-        $remaining = Count::all(ThrowawayDb::TABLE);
-        $this->assertEquals(5, $remaining, 'There should be 5 documents remaining in the table');
-    }
-
-    public function testScalarSucceeds()
-    {
-        $value = Custom::scalar("SELECT 5 AS it", [], new CountMapper());
-        $this->assertEquals(5, $value, 'The scalar value was not returned correctly');
-    }
-}

tests/integration/postgresql/DefinitionTest.php

@@ -1,78 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{Custom, Definition, DocumentException, DocumentIndex};
-use BitBadger\PDODocument\Mapper\ExistsMapper;
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-
-/**
- * PostgreSQL integration tests for the Definition class
- */
-#[TestDox('Definition (PostgreSQL integration)')]
-class DefinitionTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create(withData: false);
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    /**
-     * Does the given named object exist in the database?
-     *
-     * @param string $name The name of the object whose existence should be verified
-     * @return bool True if the object exists, false if not
-     * @throws DocumentException If any is encountered
-     */
-    private function itExists(string $name): bool
-    {
-        return Custom::scalar('SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = :name)',
-            [':name' => $name], new ExistsMapper());
-    }
-
-    public function testEnsureTableSucceeds(): void
-    {
-        $this->assertFalse($this->itExists('ensured'), 'The table should not exist already');
-        $this->assertFalse($this->itExists('idx_ensured_key'), 'The key index should not exist already');
-        Definition::ensureTable('ensured');
-        $this->assertTrue($this->itExists('ensured'), 'The table should now exist');
-        $this->assertTrue($this->itExists('idx_ensured_key'), 'The key index should now exist');
-    }
-
-    public function testEnsureFieldIndexSucceeds(): void
-    {
-        $this->assertFalse($this->itExists('idx_ensured_test'), 'The index should not exist already');
-        Definition::ensureTable('ensured');
-        Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']);
-        $this->assertTrue($this->itExists('idx_ensured_test'), 'The index should now exist');
-    }
-
-    public function testEnsureDocumentIndexSucceedsForFull(): void
-    {
-        $docIdx = 'idx_' . ThrowawayDb::TABLE . '_document';
-        Definition::ensureTable(ThrowawayDb::TABLE);
-        $this->assertFalse($this->itExists($docIdx), 'The document index should not exist');
-        Definition::ensureDocumentIndex(ThrowawayDb::TABLE, DocumentIndex::Full);
-        $this->assertTrue($this->itExists($docIdx), 'The document index should now exist');
-    }
-
-    public function testEnsureDocumentIndexSucceedsForOptimized(): void
-    {
-        $docIdx = 'idx_' . ThrowawayDb::TABLE . '_document';
-        Definition::ensureTable(ThrowawayDb::TABLE);
-        $this->assertFalse($this->itExists($docIdx), 'The document index should not exist');
-        Definition::ensureDocumentIndex(ThrowawayDb::TABLE, DocumentIndex::Optimized);
-        $this->assertTrue($this->itExists($docIdx), 'The document index should now exist');
-    }
-}

tests/integration/postgresql/DeleteTest.php

@@ -1,89 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{Count, Delete, Field};
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-
-/**
- * PostgreSQL integration tests for the Delete class
- */
-#[TestDox('Delete (PostgreSQL integration)')]
-class DeleteTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    #[TestDox('By ID succeeds when a document is deleted')]
-    public function testByIdSucceedsWhenADocumentIsDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byId(ThrowawayDb::TABLE, 'four');
-        $this->assertEquals(4, Count::all(ThrowawayDb::TABLE), 'There should have been 4 documents remaining');
-    }
-
-    #[TestDox('By ID succeeds when a document is not deleted')]
-    public function testByIdSucceedsWhenADocumentIsNotDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byId(ThrowawayDb::TABLE, 'negative four');
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining');
-    }
-
-    public function testByFieldsSucceedsWhenDocumentsAreDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byFields(ThrowawayDb::TABLE, [Field::NE('value', 'purple')]);
-        $this->assertEquals(2, Count::all(ThrowawayDb::TABLE), 'There should have been 2 documents remaining');
-    }
-
-    public function testByFieldsSucceedsWhenDocumentsAreNotDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'crimson')]);
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining');
-    }
-
-    public function testByContainsSucceedsWhenDocumentsAreDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byContains(ThrowawayDb::TABLE, ['value' => 'purple']);
-        $this->assertEquals(3, Count::all(ThrowawayDb::TABLE), 'There should have been 3 documents remaining');
-    }
-
-    public function testByContainsSucceedsWhenDocumentsAreNotDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byContains(ThrowawayDb::TABLE, ['target' => 'acquired']);
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining');
-    }
-
-    #[TestDox('By JSON Path succeeds when documents are deleted')]
-    public function testByJsonPathSucceedsWhenDocumentsAreDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ <> 0)');
-        $this->assertEquals(1, Count::all(ThrowawayDb::TABLE), 'There should have been 1 document remaining');
-    }
-
-    #[TestDox('By JSON Path succeeds when documents are not deleted')]
-    public function testByJsonPathSucceedsWhenDocumentsAreNotDeleted(): void
-    {
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start');
-        Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 0)');
-        $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining');
-    }
-}

tests/integration/postgresql/DocumentListTest.php

@@ -1,74 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{DocumentList, Query};
-use BitBadger\PDODocument\Mapper\DocumentMapper;
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-use Test\Integration\TestDocument;
-
-/**
- * PostgreSQL integration tests for the DocumentList class
- */
-#[TestDox('DocumentList (PostgreSQL integration)')]
-class DocumentListTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    public function testCreateSucceeds(): void
-    {
-        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
-            new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'There should have been a document list created');
-        $list = null;
-    }
-
-    public function testItems(): void
-    {
-        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
-            new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'There should have been a document list created');
-        $count = 0;
-        foreach ($list->items() as $item) {
-            $this->assertContains($item->id, ['one', 'two', 'three', 'four', 'five'],
-                'An unexpected document ID was returned');
-            $count++;
-        }
-        $this->assertEquals(5, $count, 'There should have been 5 documents returned');
-    }
-
-    public function testHasItemsSucceedsWithEmptyResults(): void
-    {
-        $list = DocumentList::create(
-            Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric < 0", [],
-            new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'There should have been a document list created');
-        $this->assertFalse($list->hasItems(), 'There should be no items in the list');
-    }
-
-    public function testHasItemsSucceedsWithNonEmptyResults(): void
-    {
-        $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
-            new DocumentMapper(TestDocument::class));
-        $this->assertNotNull($list, 'There should have been a document list created');
-        $this->assertTrue($list->hasItems(), 'There should be items in the list');
-        foreach ($list->items() as $ignored) {
-            $this->assertTrue($list->hasItems(), 'There should be items remaining in the list');
-        }
-        $this->assertFalse($list->hasItems(), 'There should be no remaining items in the list');
-    }
-}

tests/integration/postgresql/DocumentTest.php

@@ -1,308 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Field, Find, Query};
-use BitBadger\PDODocument\Mapper\ArrayMapper;
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-use Test\Integration\{NumDocument, SubDocument, TestDocument};
-
-/**
- * PostgreSQL integration tests for the Document class
- */
-#[TestDox('Document (PostgreSQL integration)')]
-class DocumentTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    #[TestDox('Insert succeeds for array no auto ID')]
-    public function testInsertSucceedsForArrayNoAutoId(): void
-    {
-        Document::insert(ThrowawayDb::TABLE, ['id' => 'turkey', 'sub' => ['foo' => 'gobble', 'bar' => 'gobble']]);
-        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
-        $this->assertTrue($tryDoc->isDefined(), 'There should have been a document inserted');
-        $doc = $tryDoc->get();
-        $this->assertEquals('turkey', $doc->id, 'The ID was incorrect');
-        $this->assertEquals('', $doc->value, 'The value was incorrect');
-        $this->assertEquals(0, $doc->num_value, 'The numeric value was incorrect');
-        $this->assertNotNull($doc->sub, 'The sub-document should not have been null');
-        $this->assertEquals('gobble', $doc->sub->foo, 'The sub-document foo property was incorrect');
-        $this->assertEquals('gobble', $doc->sub->bar, 'The sub-document bar property was incorrect');
-    }
-
-    #[TestDox('Insert succeeds for array with auto number ID not provided')]
-    public function testInsertSucceedsForArrayWithAutoNumberIdNotProvided(): void
-    {
-        Configuration::$autoId = AutoId::Number;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-
-            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'new', 'num_value' => 8]);
-            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $obj = json_decode($doc->get()['data']);
-            $this->assertEquals(1, $obj->id, 'The ID 1 should have been auto-generated');
-
-            Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'again', 'num_value' => 7]);
-            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE " . Query::whereById(docId: 2),
-                [':id' => 2], new ArrayMapper());
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $obj = json_decode($doc->get()['data']);
-            $this->assertEquals(2, $obj->id, 'The ID 2 should have been auto-generated');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for array with auto number ID with ID provided')]
-    public function testInsertSucceedsForArrayWithAutoNumberIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::Number;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, ['id' => 7, 'value' => 'new', 'num_value' => 8]);
-            $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper());
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $obj = json_decode($doc->get()['data']);
-            $this->assertEquals(7, $obj->id, 'The ID 7 should have been stored');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for array with auto UUID ID not provided')]
-    public function testInsertSucceedsForArrayWithAutoUuidIdNotProvided(): void
-    {
-        Configuration::$autoId = AutoId::UUID;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'num_value' => 5]);
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 5)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for array with auto UUID ID with ID provided')]
-    public function testInsertSucceedsForArrayWithAutoUuidIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::UUID;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            $uuid = AutoId::generateUUID();
-            Document::insert(ThrowawayDb::TABLE, ['id' => $uuid, 'value' => 'uuid', 'num_value' => 12]);
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 12)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals($uuid, $doc->get()->id, 'The ID should not have been changed');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for array with auto string ID not provided')]
-    public function testInsertSucceedsForArrayWithAutoStringIdNotProvided(): void
-    {
-        Configuration::$autoId         = AutoId::RandomString;
-        Configuration::$idStringLength = 6;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, ['id' => '', 'value' => 'new', 'num_value' => 8]);
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 8)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals(6, strlen($doc->get()->id),
-                'The ID should have been auto-generated and had 6 characters');
-        } finally {
-            Configuration::$autoId         = AutoId::None;
-            Configuration::$idStringLength = 16;
-        }
-    }
-
-    #[TestDox('Insert succeeds for array with auto string ID with ID provided')]
-    public function testInsertSucceedsForArrayWithAutoStringIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::RandomString;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, ['id' => 'my-key', 'value' => 'old', 'num_value' => 3]);
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 3)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals('my-key', $doc->get()->id, 'The ID should not have been changed');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object no auto ID')]
-    public function testInsertSucceedsForObjectNoAutoId(): void
-    {
-        Document::insert(ThrowawayDb::TABLE, new TestDocument('turkey', sub: new SubDocument('gobble', 'gobble')));
-        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
-        $this->assertTrue($tryDoc->isDefined(), 'There should have been a document inserted');
-        $doc = $tryDoc->get();
-        $this->assertEquals('turkey', $doc->id, 'The ID was incorrect');
-        $this->assertEquals('', $doc->value, 'The value was incorrect');
-        $this->assertEquals(0, $doc->num_value, 'The numeric value was incorrect');
-        $this->assertNotNull($doc->sub, 'The sub-document should not have been null');
-        $this->assertEquals('gobble', $doc->sub->foo, 'The sub-document foo property was incorrect');
-        $this->assertEquals('gobble', $doc->sub->bar, 'The sub-document bar property was incorrect');
-    }
-
-    #[TestDox('Insert succeeds for object with auto number ID not provided')]
-    public function testInsertSucceedsForObjectWithAutoNumberIdNotProvided(): void
-    {
-        Configuration::$autoId = AutoId::Number;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-
-            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'taco'));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'taco')], NumDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals(1, $doc->get()->id, 'The ID 1 should have been auto-generated');
-
-            Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'burrito'));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'burrito')], NumDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals(2, $doc->get()->id, 'The ID 2 should have been auto-generated');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object with auto number ID with ID provided')]
-    public function testInsertSucceedsForObjectWithAutoNumberIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::Number;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, new NumDocument(64, 'large'));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'large')], NumDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals(64, $doc->get()->id, 'The ID 64 should have been stored');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object with auto UUID ID not provided')]
-    public function testInsertSucceedsForObjectWithAutoUuidIdNotProvided(): void
-    {
-        Configuration::$autoId = AutoId::UUID;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, new TestDocument(value: 'something', num_value: 9));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EX('value')], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object with auto UUID ID with ID provided')]
-    public function testInsertSucceedsForObjectWithAutoUuidIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::UUID;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            $uuid = AutoId::generateUUID();
-            Document::insert(ThrowawayDb::TABLE, new TestDocument($uuid, num_value: 14));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 14)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals($uuid, $doc->get()->id, 'The ID should not have been changed');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object with auto string ID not provided')]
-    public function testInsertSucceedsForObjectWithAutoStringIdNotProvided(): void
-    {
-        Configuration::$autoId         = AutoId::RandomString;
-        Configuration::$idStringLength = 40;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, new TestDocument(num_value: 55));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 55)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals(40, strlen($doc->get()->id),
-                'The ID should have been auto-generated and had 40 characters');
-        } finally {
-            Configuration::$autoId         = AutoId::None;
-            Configuration::$idStringLength = 16;
-        }
-    }
-
-    #[TestDox('Insert succeeds for object with auto string ID with ID provided')]
-    public function testInsertSucceedsForObjectWithAutoStringIdWithIdProvided(): void
-    {
-        Configuration::$autoId = AutoId::RandomString;
-        try {
-            Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
-            Document::insert(ThrowawayDb::TABLE, new TestDocument('my-key', num_value: 3));
-            $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 3)], TestDocument::class);
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-            $this->assertEquals('my-key', $doc->get()->id, 'The ID should not have been changed');
-        } finally {
-            Configuration::$autoId = AutoId::None;
-        }
-    }
-
-    public function testInsertFailsForDuplicateKey(): void
-    {
-        $this->expectException(DocumentException::class);
-        Document::insert(ThrowawayDb::TABLE, new TestDocument('one'));
-    }
-
-    public function testSaveSucceedsWhenADocumentIsInserted(): void
-    {
-        Document::save(ThrowawayDb::TABLE, new TestDocument('test', sub: new SubDocument('a', 'b')));
-        $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
-    }
-
-    public function testSaveSucceedsWhenADocumentIsUpdated(): void
-    {
-        Document::save(ThrowawayDb::TABLE, new TestDocument('two', num_value: 44));
-        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
-        $this->assertTrue($tryDoc->isDefined(), 'There should have been a document returned');
-        $doc = $tryDoc->get();
-        $this->assertEquals(44, $doc->num_value, 'The numeric value was not updated');
-        $this->assertNull($doc->sub, 'The sub-document should have been null');
-    }
-
-    public function testUpdateSucceedsWhenReplacingADocument(): void
-    {
-        Document::update(ThrowawayDb::TABLE, 'one', new TestDocument('one', 'howdy', 8, new SubDocument('y', 'z')));
-        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
-        $this->assertNotFalse($tryDoc->isDefined(), 'There should have been a document returned');
-        $doc = $tryDoc->get();
-        $this->assertEquals('howdy', $doc->value, 'The value was incorrect');
-        $this->assertEquals(8, $doc->num_value, 'The numeric value was incorrect');
-        $this->assertNotNull($doc->sub, 'The sub-document should not have been null');
-        $this->assertEquals('y', $doc->sub->foo, 'The sub-document foo property was incorrect');
-        $this->assertEquals('z', $doc->sub->bar, 'The sub-document bar property was incorrect');
-    }
-
-    public function testUpdateSucceedsWhenNoDocumentIsReplaced(): void
-    {
-        Document::update(ThrowawayDb::TABLE, 'two-hundred', new TestDocument('200'));
-        $doc = Find::byId(ThrowawayDb::TABLE, 'two-hundred', TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
-    }
-}

tests/integration/postgresql/ExistsTest.php

@@ -1,80 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace Test\Integration\PostgreSQL;
-
-use BitBadger\PDODocument\{Exists, Field};
-use PHPUnit\Framework\Attributes\TestDox;
-use PHPUnit\Framework\TestCase;
-
-/**
- * PostgreSQL integration tests for the Exists class
- */
-#[TestDox('Exists (PostgreSQL integration)')]
-class ExistsTest extends TestCase
-{
-    /** @var string Database name for throwaway database */
-    private string $dbName;
-
-    protected function setUp(): void
-    {
-        parent::setUp();
-        $this->dbName = ThrowawayDb::create();
-    }
-
-    protected function tearDown(): void
-    {
-        ThrowawayDb::destroy($this->dbName);
-        parent::tearDown();
-    }
-
-    #[TestDox('By ID succeeds when a document exists')]
-    public function testByIdSucceedsWhenADocumentExists(): void
-    {
-        $this->assertTrue(Exists::byId(ThrowawayDb::TABLE, 'three'), 'There should have been an existing document');
-    }
-
-    #[TestDox('By ID succeeds when a document does not exist')]
-    public function testByIdSucceedsWhenADocumentDoesNotExist(): void
-    {
-        $this->assertFalse(Exists::byId(ThrowawayDb::TABLE, 'seven'),
-            'There should not have been an existing document');
-    }
-
-    public function testByFieldsSucceedsWhenDocumentsExist(): void
-    {
-        $this->assertTrue(Exists::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 10)]),
-            'There should have been existing documents');
-    }
-
-    public function testByFieldsSucceedsWhenNoMatchingDocumentsExist(): void
-    {
-        $this->assertFalse(Exists::byFields(ThrowawayDb::TABLE, [Field::LT('nothing', 'none')]),
-            'There should not have been any existing documents');
-    }
-
-    public function testByContainsSucceedsWhenDocumentsExist(): void
-    {
-        $this->assertTrue(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'purple']),
-            'There should have been existing documents');
-    }
-
-    public function testByContainsSucceedsWhenNoMatchingDocumentsExist(): void
-    {
-        $this->assertFalse(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'violet']),
-            'There should not have been existing documents');
-    }
-
-    #[TestDox('By JSON Path succeeds when documents exist')]
-    public function testByJsonPathSucceedsWhenDocumentsExist(): void
-    {
-        $this->assertTrue(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)'),
-            'There should have been existing documents');
-    }
-
-    #[TestDox('By JSON Path succeeds when no matching documents exist')]
-    public function testByJsonPathSucceedsWhenNoMatchingDocumentsExist(): void
-    {
-        $this->assertFalse(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10.1)'),
-            'There should have been existing documents');
-    }
-}