Improve Schema API and DateField API

Author: nyamsprod

src/Buffer.php

@@ -229,7 +229,7 @@ public function schema(?Inspector $inspector = null, array $header = []): Schema
         return ($inspector ?? Inspector::default())->schema($this, $header);
     }
 
-    public function getTypedRecords(?Inspector $inspector = null, array $header = []): Iterator
+    public function getInterpretedRecords(?Inspector $inspector = null, array $header = []): Iterator
     {
         return $this->schema($inspector)->parse($this, $header);
     }

src/Reader.php

@@ -423,7 +423,7 @@ public function schema(?Inspector $inspector = null, array $header = []): Schema
         return ($inspector ?? Inspector::default())->schema($this, $header);
     }
 
-    public function getTypedRecords(?Inspector $inspector = null, array $header = []): Iterator
+    public function getInterpretedRecords(?Inspector $inspector = null, array $header = []): Iterator
     {
         return $this->schema($inspector)->parse($this, $header);
     }

src/ResultSet.php

@@ -213,7 +213,7 @@ public function schema(?Inspector $inspector = null, array $header = []): Schema
         return ($inspector ?? Inspector::default())->schema($this, $header);
     }
 
-    public function getTypedRecords(?Inspector $inspector = null, array $header = []): Iterator
+    public function getInterpretedRecords(?Inspector $inspector = null, array $header = []): Iterator
     {
         return $this->schema($inspector)->parse($this, $header);
     }

src/Schema/DateField.php

@@ -15,6 +15,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Exception;
 use ValueError;
 
@@ -24,14 +25,34 @@
 final class DateField extends AbstractField
 {
     public readonly string $format;
+    public readonly ?DateTimeZone $timeZone;
 
-    public function __construct(string $format, float $confidenceThreshold = 0.8)
+    public function __construct(string $format, DateTimeZone|string|null $timeZone = null, float $confidenceThreshold = 0.8)
     {
         $format = trim($format);
-        '' !== $format || throw new ValueError('The date field strategy format can not be empty.');
+        '' !== $format || throw new ValueError('The date field format can not be empty.');
+        $timeZone = self::filterTimezone($timeZone);
 
         parent::__construct($confidenceThreshold);
         $this->format = $format;
+        $this->timeZone = $timeZone;
+    }
+
+    private static function filterTimezone(DateTimeZone|string|null $timeZone): ?DateTimeZone
+    {
+        if (null === $timeZone) {
+            return null;
+        }
+
+        if ($timeZone instanceof DateTimeZone) {
+            return $timeZone;
+        }
+
+        try {
+            return new DateTimeZone($timeZone);
+        } catch (Exception $exception) {
+            throw new ValueError('The date field timezone value `'.$timeZone.'` is invalid.', previous: $exception);
+        }
     }
 
     public function type(): FieldType
@@ -44,11 +65,6 @@ public function name(): string
         return FieldType::Date->value;
     }
 
-    public function format(): string
-    {
-        return $this->format;
-    }
-
     public function parse(mixed $value): ?DateTimeImmutable
     {
         if ($value instanceof DateTimeInterface) {
@@ -65,10 +81,21 @@ public function parse(mixed $value): ?DateTimeImmutable
         }
 
         try {
-            $value = DateTimeImmutable::createFromFormat($this->format, $value);
-
-            return false === $value ? null : $value;
-        } catch (Exception) {
+            $value = DateTimeImmutable::createFromFormat($this->format, $value, $this->timeZone);
+            if (false === $value) {
+                return null;
+            }
+
+            $errors = DateTimeImmutable::getLastErrors();
+            if (
+                (isset($errors['warning_count']) && 0 < $errors['warning_count']) ||
+                (isset($errors['error_count']) && 0 < $errors['error_count'])
+            ) {
+                return null;
+            }
+
+            return $value;
+        } catch (ValueError) {
             return null;
         }
     }
@@ -77,6 +104,7 @@ public function metadata(): Metadata
     {
         return new Metadata([
             'format' => $this->format,
+            'timezone' => $this->timeZone?->getName(),
         ]);
     }
 }

src/Schema/InspectorTest.php

@@ -75,7 +75,7 @@ public function testDefaultFactory(): void
         $inspector = Inspector::default(20);
 
         self::assertSame(20, $inspector->sampleLimit);
-        self::assertCount(5, $inspector->fieldList);
+        self::assertCount(7, $inspector->fieldList);
     }
 
     public function testSchemaFallsBackToStringFieldWhenNoMatch(): void

src/Schema/RegexpField.php

@@ -82,11 +82,6 @@ public function parse(mixed $value): ?string
         return ('' === $value || 1 !== preg_match($this->pattern, $value)) ? null : $value;
     }
 
-    public function pattern(): string
-    {
-        return $this->pattern;
-    }
-
     public function metadata(): Metadata
     {
         return new Metadata([