Update option/result library

- Restore getOrThrow() calls

composer.json

@@ -17,11 +17,12 @@
     "rss": "https://git.bitbadger.solutions/bit-badger/pdo-document.rss",
     "docs": "https://bitbadger.solutions/open-source/pdo-document/"
   },
+  "minimum-stability": "beta",
   "require": {
     "php": ">=8.2",
+    "bit-badger/inspired-by-fsharp": "^1",
     "netresearch/jsonmapper": "^4",
-    "ext-pdo": "*",
+    "ext-pdo": "*"
-    "phpoption/phpoption": "^1.9"
   },
   "require-dev": {
     "phpunit/phpunit": "^11",

composer.lock

@@ -4,8 +4,53 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "dc897c0ab21d662a65b3818331edd2f2",
+    "content-hash": "f3351c794dd1261ee4bf18380f58463d",
     "packages": [
+        {
+            "name": "bit-badger/inspired-by-fsharp",
+            "version": "v1.0.0-beta2",
+            "source": {
+                "type": "git",
+                "url": "https://git.bitbadger.solutions/bit-badger/inspired-by-fsharp",
+                "reference": "fad428a4e40b606987499b17bb2d5b7d4b04502d"
+            },
+            "require": {
+                "php": "^8.2"
+            },
+            "require-dev": {
+                "phpoption/phpoption": "^1",
+                "phpunit/phpunit": "^11"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "BitBadger\\InspiredByFSharp\\": "./src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Daniel J. Summers",
+                    "email": "daniel@bitbadger.solutions",
+                    "homepage": "https://bitbadger.solutions",
+                    "role": "Developer"
+                }
+            ],
+            "description": "PHP utility classes whose functionality is inspired by their F# counterparts",
+            "keywords": [
+                "option",
+                "result"
+            ],
+            "support": {
+                "email": "daniel@bitbadger.solutions",
+                "rss": "https://git.bitbadger.solutions/bit-badger/inspired-by-fsharp.rss",
+                "source": "https://git.bitbadger.solutions/bit-badger/inspired-by-fsharp"
+            },
+            "time": "2024-07-29T17:58:33+00:00"
+        },
         {
             "name": "netresearch/jsonmapper",
             "version": "v4.4.1",
@@ -56,81 +101,6 @@
                 "source": "https://github.com/cweiske/jsonmapper/tree/v4.4.1"
             },
             "time": "2024-01-31T06:18:54+00:00"
-        },
-        {
-            "name": "phpoption/phpoption",
-            "version": "1.9.3",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/schmittjoh/php-option.git",
-                "reference": "e3fac8b24f56113f7cb96af14958c0dd16330f54"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/schmittjoh/php-option/zipball/e3fac8b24f56113f7cb96af14958c0dd16330f54",
-                "reference": "e3fac8b24f56113f7cb96af14958c0dd16330f54",
-                "shasum": ""
-            },
-            "require": {
-                "php": "^7.2.5 || ^8.0"
-            },
-            "require-dev": {
-                "bamarni/composer-bin-plugin": "^1.8.2",
-                "phpunit/phpunit": "^8.5.39 || ^9.6.20 || ^10.5.28"
-            },
-            "type": "library",
-            "extra": {
-                "bamarni-bin": {
-                    "bin-links": true,
-                    "forward-command": false
-                },
-                "branch-alias": {
-                    "dev-master": "1.9-dev"
-                }
-            },
-            "autoload": {
-                "psr-4": {
-                    "PhpOption\\": "src/PhpOption/"
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "Apache-2.0"
-            ],
-            "authors": [
-                {
-                    "name": "Johannes M. Schmitt",
-                    "email": "schmittjoh@gmail.com",
-                    "homepage": "https://github.com/schmittjoh"
-                },
-                {
-                    "name": "Graham Campbell",
-                    "email": "hello@gjcampbell.co.uk",
-                    "homepage": "https://github.com/GrahamCampbell"
-                }
-            ],
-            "description": "Option Type for PHP",
-            "keywords": [
-                "language",
-                "option",
-                "php",
-                "type"
-            ],
-            "support": {
-                "issues": "https://github.com/schmittjoh/php-option/issues",
-                "source": "https://github.com/schmittjoh/php-option/tree/1.9.3"
-            },
-            "funding": [
-                {
-                    "url": "https://github.com/GrahamCampbell",
-                    "type": "github"
-                },
-                {
-                    "url": "https://tidelift.com/funding/github/packagist/phpoption/phpoption",
-                    "type": "tidelift"
-                }
-            ],
-            "time": "2024-07-20T21:41:07+00:00"
         }
     ],
     "packages-dev": [
@@ -1816,7 +1786,7 @@
         }
     ],
     "aliases": [],
-    "minimum-stability": "stable",
+    "minimum-stability": "beta",
     "stability-flags": [],
     "prefer-stable": false,
     "prefer-lowest": false,

src/Configuration.php

@@ -8,9 +8,9 @@ declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use BitBadger\InspiredByFSharp\Option;
 use Exception;
 use PDO;
-use PhpOption\{None, Option, Some};
 
 /**
  * Common configuration for the document library
@@ -55,10 +55,10 @@ class Configuration
     public static function useDSN(string $dsn): void
     {
         if (empty($dsn)) {
-            self::$mode = self::$pdoDSN = None::create();
+            self::$mode = self::$pdoDSN = Option::None();
         } else {
-            self::$mode   = Some::create(Mode::deriveFromDSN($dsn));
+            self::$mode   = Option::Some(Mode::deriveFromDSN($dsn));
-            self::$pdoDSN = Some::create($dsn);
+            self::$pdoDSN = Option::Some($dsn);
         }
     }
 
@@ -71,8 +71,8 @@ class Configuration
     public static function dbConn(): PDO
     {
         if (is_null(self::$pdo)) {
-            $dsn = (self::$pdoDSN ?? None::create())->getOrThrow(
+            $dsn = self::$pdoDSN->getOrThrow(fn()
-                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,
                 $_ENV['PDO_DOC_PASSWORD'] ?? self::$password, self::$options);
         }
@@ -88,8 +88,8 @@ class Configuration
      */
     public static function mode(?string $process = null): Mode
     {
-        return self::$mode->getOrThrow(
+        return self::$mode->getOrThrow(fn()
-            new DocumentException('Database mode not set' . (is_null($process) ? '' : "; cannot $process")));
+            => new DocumentException('Database mode not set' . (is_null($process) ? '' : "; cannot $process")));
     }
 
     /**
@@ -99,7 +99,7 @@ class Configuration
      */
     public static function overrideMode(?Mode $mode): void
     {
-        self::$mode = Option::fromValue($mode);
+        self::$mode = Option::of($mode);
     }
 
     /**

src/Custom.php

@@ -8,11 +8,11 @@ declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use BitBadger\InspiredByFSharp\Option;
 use BitBadger\PDODocument\Mapper\Mapper;
 use PDO;
 use PDOException;
 use PDOStatement;
-use PhpOption\{None, Option, Some};
 
 /**
  * Functions to execute custom queries
@@ -106,7 +106,7 @@ 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;
         }

src/DocumentList.php

@@ -24,6 +24,9 @@ class DocumentList
     /** @var TDoc|null $first The first item from the results  */
     private mixed $first = null;
 
+    /** @var bool $isConsumed This is set to true once the generator has been exhausted */
+    private bool $isConsumed = false;
+
     /**
      * Constructor
      *
@@ -39,6 +42,93 @@ class DocumentList
         }
     }
 
+    /**
+     * Does this list have items remaining?
+     *
+     * @return bool True if there are items still to be retrieved from the list, false if not
+     */
+    public function hasItems(): bool
+    {
+        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;
+        }
+        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
+     */
+    public function __destruct()
+    {
+        if (!is_null($this->result)) $this->result = null;
+    }
+
     /**
      * Construct a new document list
      *
@@ -53,37 +143,4 @@ class DocumentList
         $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?
-     *
-     * @return bool True if there are items still to be retrieved from the list, false if not
-     */
-    public function hasItems(): bool
-    {
-        return !is_null($this->result);
-    }
-
-    /**
-     * Ensure the statement is destroyed if the generator is not exhausted
-     */
-    public function __destruct()
-    {
-        if (!is_null($this->result)) $this->result = null;
-    }
 }

src/Find.php

@@ -8,8 +8,8 @@ declare(strict_types=1);
 
 namespace BitBadger\PDODocument;
 
+use BitBadger\InspiredByFSharp\Option;
 use BitBadger\PDODocument\Mapper\DocumentMapper;
-use PhpOption\Option;
 
 /**
  * Functions to find documents

src/Parameters.php

@@ -59,21 +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
-     * @return array|Field[] The fields, all with non-blank parameter names
+     * @return Field[] The fields, all with non-blank parameter names
      */
     public static function nameFields(array $fields): array
     {
-        for ($idx = 0; $idx < sizeof($fields); $idx++) {
+        array_walk($fields, function (Field $field, int $idx) {
-            if (empty($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
      * @return array An associative array of parameter names and values with the fields added
      */
@@ -86,20 +86,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
      * @throws Exception If the database mode has not been set
      */
     public static function fieldNames(string $paramName, array $fieldNames): array
     {
         $mode = Configuration::mode('generate field name parameters');
-
+        return match ($mode) {
-        if ($mode === Mode::PgSQL) return [$paramName => "{" . implode(",", $fieldNames) . "}"];
+            Mode::PgSQL  => [$paramName => "{" . implode(",", $fieldNames) . "}"],
-
+            Mode::SQLite => array_combine(array_map(fn($idx) => $paramName . $idx,
-        // else SQLite
+                                              empty($fieldNames) ? [] : range(0, sizeof($fieldNames) - 1)),
-        $it = [];
+                                          array_map(fn($field) => "$.$field", $fieldNames))
-        $idx = 0;
+        };
-        foreach ($fieldNames as $field) $it[$paramName . $idx++] = "$.$field";
-        return $it;
     }
 }

tests/integration/postgresql/CustomTest.php

@@ -93,7 +93,7 @@ class CustomTest extends TestCase
     {
         $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->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('one', $doc->get()->id, 'The incorrect document was returned');
     }
 
@@ -101,7 +101,7 @@ class CustomTest extends TestCase
     {
         $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');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testNonQuerySucceedsWhenOperatingOnData()

tests/integration/postgresql/DocumentListTest.php

@@ -8,7 +8,7 @@ declare(strict_types=1);
 
 namespace Test\Integration\PostgreSQL;
 
-use BitBadger\PDODocument\{DocumentList, Query};
+use BitBadger\PDODocument\{DocumentException, DocumentList, Query};
 use BitBadger\PDODocument\Mapper\DocumentMapper;
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\TestCase;
@@ -43,7 +43,7 @@ class DocumentListTest extends TestCase
         $list = null;
     }
 
-    public function testItems(): void
+    public function testItemsSucceeds(): void
     {
         $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
             new DocumentMapper(TestDocument::class));
@@ -57,6 +57,18 @@ class DocumentListTest extends TestCase
         $this->assertEquals(5, $count, 'There should have been 5 documents returned');
     }
 
+    public function testItemsFailsWhenAlreadyConsumed(): 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');
+        $ignored = iterator_to_array($list->items());
+        $this->assertFalse($list->hasItems(), 'The list should no longer have items');
+        $this->expectException(DocumentException::class);
+        iterator_to_array($list->items());
+    }
+
     public function testHasItemsSucceedsWithEmptyResults(): void
     {
         $list = DocumentList::create(
@@ -77,4 +89,39 @@ class DocumentListTest extends TestCase
         }
         $this->assertFalse($list->hasItems(), 'There should be no remaining items in the list');
     }
+
+    public function testMapSucceeds(): 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->map(fn($doc) => strrev($doc->id)) as $mapped) {
+            $this->assertContains($mapped, ['eno', 'owt', 'eerht', 'ruof', 'evif'],
+                'An unexpected mapped value was returned');
+        }
+    }
+
+    public function testIterSucceeds(): 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');
+        $splats = [];
+        $list->iter(function ($doc) use (&$splats) { $splats[] = str_repeat('*', strlen($doc->id)); });
+        $this->assertEquals('*** *** ***** **** ****', implode(' ', $splats),
+            'Iteration did not have the expected result');
+    }
+
+    public function testMapToArraySucceeds(): 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');
+        $lookup   = $list->mapToArray(fn($it) => $it->id, fn($it) => $it->value);
+        $expected = ['one' => 'FIRST!', 'two' => 'another', 'three' => '', 'four' => 'purple', 'five' => 'purple'];
+        $this->assertEquals($expected, $lookup, 'The array was not mapped correctly');
+    }
 }

tests/integration/postgresql/DocumentTest.php

@@ -40,7 +40,7 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -59,14 +59,14 @@ class DocumentTest extends TestCase
 
             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');
+            $this->assertTrue($doc->isSome(), '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');
+            $this->assertTrue($doc->isSome(), '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 {
@@ -82,7 +82,7 @@ class DocumentTest extends TestCase
             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');
+            $this->assertTrue($doc->isSome(), '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 {
@@ -98,7 +98,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), 'There should have been a document returned');
             $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
         } finally {
             Configuration::$autoId = AutoId::None;
@@ -114,7 +114,7 @@ class DocumentTest extends TestCase
             $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->assertTrue($doc->isSome(), '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;
@@ -130,7 +130,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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 {
@@ -147,7 +147,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -159,7 +159,7 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -178,12 +178,12 @@ class DocumentTest extends TestCase
 
             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->assertTrue($doc->isSome(), '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->assertTrue($doc->isSome(), '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;
@@ -198,7 +198,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -213,7 +213,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), 'There should have been a document returned');
             $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
         } finally {
             Configuration::$autoId = AutoId::None;
@@ -229,7 +229,7 @@ class DocumentTest extends TestCase
             $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->assertTrue($doc->isSome(), '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;
@@ -245,7 +245,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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 {
@@ -262,7 +262,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -279,14 +279,14 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($doc->isSome(), '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');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -296,7 +296,7 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertNotFalse($tryDoc->isSome(), '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');
@@ -309,6 +309,6 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 }

tests/integration/postgresql/FindTest.php

@@ -55,7 +55,7 @@ class FindTest extends TestCase
     public function testByIdSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('two', $doc->get()->id, 'An incorrect document was returned');
     }
 
@@ -65,7 +65,7 @@ class FindTest extends TestCase
         Delete::byFields(ThrowawayDb::TABLE, [Field::NEX('absent')]);
         Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
         $doc = Find::byId(ThrowawayDb::TABLE, 18, NumDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals(18, $doc->get()->id, 'An incorrect document was returned');
     }
 
@@ -73,7 +73,7 @@ class FindTest extends TestCase
     public function testByIdSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testByFieldsSucceedsWhenDocumentsAreFound(): void
@@ -129,48 +129,48 @@ class FindTest extends TestCase
     public function testFirstByFieldsSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'another')], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('two', $doc->get()->id, 'The incorrect document was returned');
     }
 
     public function testFirstByFieldsSucceedsWhenMultipleDocumentsAreFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('sub.foo', 'green')], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertContains($doc->get()->id, ['two', 'four'], 'An incorrect document was returned');
     }
 
     public function testFirstByFieldsSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'absent')], TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testFirstByContainsSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!'], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('one', $doc->get()->id, 'The incorrect document was returned');
     }
 
     public function testFirstByContainsSucceedsWhenMultipleDocumentsAreFound(): void
     {
         $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertContains($doc->get()->id, ['four', 'five'], 'An incorrect document was returned');
     }
 
     public function testFirstByContainsSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     #[TestDox('First by JSON Path succeeds when a document is found')]
     public function testFirstByJsonPathSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('two', $doc->get()->id, 'The incorrect document was returned');
     }
 
@@ -178,7 +178,7 @@ class FindTest extends TestCase
     public function testFirstByJsonPathSucceedsWhenMultipleDocumentsAreFound(): void
     {
         $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertContains($doc->get()->id, ['four', 'five'], 'An incorrect document was returned');
     }
 
@@ -186,6 +186,6 @@ class FindTest extends TestCase
     public function testFirstByJsonPathSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 }

tests/integration/postgresql/PatchTest.php

@@ -39,7 +39,7 @@ class PatchTest extends TestCase
     {
         Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
         $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals(44, $doc->get()->num_value, 'The updated document is not correct');
     }
 
@@ -71,7 +71,7 @@ class PatchTest extends TestCase
     {
         Patch::byContains(ThrowawayDb::TABLE, ['value' => 'another'], ['num_value' => 12]);
         $tryDoc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'another'], TestDocument::class);
-        $this->assertNotFalse($tryDoc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($tryDoc->isSome(), 'There should have been a document returned');
         $doc = $tryDoc->get();
         $this->assertEquals('two', $doc->id, 'An incorrect document was returned');
         $this->assertEquals(12, $doc->num_value, 'The document was not patched');

tests/integration/postgresql/RemoveFieldsTest.php

@@ -39,7 +39,7 @@ class RemoveFieldsTest extends TestCase
     {
         RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
         $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
-        $this->assertNotFalse($tryDoc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($tryDoc->isSome(), 'There should have been a document returned');
         $doc = $tryDoc->get();
         $this->assertEquals('', $doc->value, 'Value should have been blank (its default value)');
         $this->assertNull($doc->sub, 'Sub-document should have been null');
@@ -63,7 +63,7 @@ class RemoveFieldsTest extends TestCase
     {
         RemoveFields::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], ['sub']);
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertNull($doc->get()->sub, 'Sub-document should have been null');
     }
 

tests/integration/sqlite/CustomTest.php

@@ -92,7 +92,7 @@ class CustomTest extends TestCase
     {
         $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->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('one', $doc->get()->id, 'The incorrect document was returned');
     }
 
@@ -100,7 +100,7 @@ class CustomTest extends TestCase
     {
         $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');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testNonQuerySucceedsWhenOperatingOnData()

tests/integration/sqlite/DocumentListTest.php

@@ -8,7 +8,7 @@ declare(strict_types=1);
 
 namespace Test\Integration\SQLite;
 
-use BitBadger\PDODocument\{DocumentList, Query};
+use BitBadger\PDODocument\{DocumentException, DocumentList, Query};
 use BitBadger\PDODocument\Mapper\DocumentMapper;
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\TestCase;
@@ -43,7 +43,7 @@ class DocumentListTest extends TestCase
         $list = null;
     }
 
-    public function testItems(): void
+    public function testItemsSucceeds(): void
     {
         $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [],
             new DocumentMapper(TestDocument::class));
@@ -57,6 +57,18 @@ class DocumentListTest extends TestCase
         $this->assertEquals(5, $count, 'There should have been 5 documents returned');
     }
 
+    public function testItemsFailsWhenAlreadyConsumed(): 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');
+        $ignored = iterator_to_array($list->items());
+        $this->assertFalse($list->hasItems(), 'The list should no longer have items');
+        $this->expectException(DocumentException::class);
+        iterator_to_array($list->items());
+    }
+
     public function testHasItemsSucceedsWithEmptyResults(): void
     {
         $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'num_value' < 0", [],
@@ -76,4 +88,38 @@ class DocumentListTest extends TestCase
         }
         $this->assertFalse($list->hasItems(), 'There should be no remaining items in the list');
     }
+    public function testMapSucceeds(): 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->map(fn($doc) => strrev($doc->id)) as $mapped) {
+            $this->assertContains($mapped, ['eno', 'owt', 'eerht', 'ruof', 'evif'],
+                'An unexpected mapped value was returned');
+        }
+    }
+
+    public function testIterSucceeds(): 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');
+        $splats = [];
+        $list->iter(function ($doc) use (&$splats) { $splats[] = str_repeat('*', strlen($doc->id)); });
+        $this->assertEquals('*** *** ***** **** ****', implode(' ', $splats),
+            'Iteration did not have the expected result');
+    }
+
+    public function testMapToArraySucceeds(): 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');
+        $lookup   = $list->mapToArray(fn($it) => $it->id, fn($it) => $it->value);
+        $expected = ['one' => 'FIRST!', 'two' => 'another', 'three' => '', 'four' => 'purple', 'five' => 'purple'];
+        $this->assertEquals($expected, $lookup, 'The array was not mapped correctly');
+    }
 }

tests/integration/sqlite/DocumentTest.php

@@ -40,7 +40,7 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -59,14 +59,14 @@ class DocumentTest extends TestCase
 
             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');
+            $this->assertTrue($doc->isSome(), '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 data->>'id' = 2", [],
                 new ArrayMapper());
-            $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+            $this->assertTrue($doc->isSome(), '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 {
@@ -82,7 +82,7 @@ class DocumentTest extends TestCase
             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');
+            $this->assertTrue($doc->isSome(), '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 {
@@ -98,7 +98,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), 'There should have been a document returned');
             $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
         } finally {
             Configuration::$autoId = AutoId::None;
@@ -114,7 +114,7 @@ class DocumentTest extends TestCase
             $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->assertTrue($doc->isSome(), '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;
@@ -130,7 +130,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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 {
@@ -147,7 +147,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -159,7 +159,7 @@ class DocumentTest extends TestCase
     {
         Document::insert(ThrowawayDb::TABLE, new TestDocument('turkey', sub: new SubDocument('gobble', 'gobble')));
         $tryDoc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class);
-        $this->assertNotFalse($tryDoc->isDefined(), 'There should have been a document inserted');
+        $this->assertNotFalse($tryDoc->isSome(), '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');
@@ -178,12 +178,12 @@ class DocumentTest extends TestCase
 
             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->assertTrue($doc->isSome(), '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->assertTrue($doc->isSome(), '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;
@@ -198,7 +198,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -213,7 +213,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), 'There should have been a document returned');
             $this->assertNotEmpty($doc->get()->id, 'The ID should have been auto-generated');
         } finally {
             Configuration::$autoId = AutoId::None;
@@ -229,7 +229,7 @@ class DocumentTest extends TestCase
             $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->assertTrue($doc->isSome(), '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;
@@ -245,7 +245,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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 {
@@ -262,7 +262,7 @@ class DocumentTest extends TestCase
             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->assertTrue($doc->isSome(), '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;
@@ -279,14 +279,14 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($doc->isSome(), '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');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -296,7 +296,7 @@ class DocumentTest extends TestCase
     {
         Document::update(ThrowawayDb::TABLE, 'one', new TestDocument('one', 'howdy', 8, new SubDocument('y', 'z')));
         $tryDoc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
-        $this->assertTrue($tryDoc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($tryDoc->isSome(), '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');
@@ -309,6 +309,6 @@ class DocumentTest extends TestCase
     {
         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');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 }

tests/integration/sqlite/FindTest.php

@@ -55,7 +55,7 @@ class FindTest extends TestCase
     public function testByIdSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('two', $doc->get()->id, 'An incorrect document was returned');
     }
 
@@ -64,7 +64,7 @@ class FindTest extends TestCase
     {
         Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
         $doc = Find::byId(ThrowawayDb::TABLE, 18, TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('18', $doc->get()->id, 'An incorrect document was returned');
     }
 
@@ -72,7 +72,7 @@ class FindTest extends TestCase
     public function testByIdSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testByFieldsSucceedsWhenDocumentsAreFound(): void
@@ -107,21 +107,21 @@ class FindTest extends TestCase
     public function testFirstByFieldsSucceedsWhenADocumentIsFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'another')], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals('two', $doc->get()->id, 'The incorrect document was returned');
     }
 
     public function testFirstByFieldsSucceedsWhenMultipleDocumentsAreFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('sub.foo', 'green')], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertContains($doc->get()->id, ['two', 'four'], 'An incorrect document was returned');
     }
 
     public function testFirstByFieldsSucceedsWhenADocumentIsNotFound(): void
     {
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'absent')], TestDocument::class);
-        $this->assertTrue($doc->isEmpty(), 'There should not have been a document returned');
+        $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
     public function testFirstByContainsFails(): void

tests/integration/sqlite/PatchTest.php

@@ -39,7 +39,7 @@ class PatchTest extends TestCase
     {
         Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
         $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertEquals(44, $doc->get()->num_value, 'The updated document is not correct');
     }
 

tests/integration/sqlite/RemoveFieldsTest.php

@@ -39,7 +39,7 @@ class RemoveFieldsTest extends TestCase
     {
         RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
         $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
-        $this->assertTrue($tryDoc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($tryDoc->isSome(), 'There should have been a document returned');
         $doc = $tryDoc->get();
         $this->assertEquals('', $doc->value, 'Value should have been blank (its default value)');
         $this->assertNull($doc->sub, 'Sub-document should have been null');
@@ -63,7 +63,7 @@ class RemoveFieldsTest extends TestCase
     {
         RemoveFields::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], ['sub']);
         $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], TestDocument::class);
-        $this->assertTrue($doc->isDefined(), 'There should have been a document returned');
+        $this->assertTrue($doc->isSome(), 'There should have been a document returned');
         $this->assertNull($doc->get()->sub, 'Sub-document should have been null');
     }