refactor(entities): share nested coordinates

Author: andrepimpao

docs/air-pollution.md

@@ -1,9 +1,11 @@
 # Air Pollution
 
+Current, forecast, and historical air pollution are included in OpenWeather's
+standard free and paid subscriptions.
+
 ## Current
 
-The Current Air Pollution API is available on OpenWeather's standard free and
-paid subscriptions. See the
+See OpenWeather's
 [official Air Pollution API documentation](https://openweathermap.org/api/air-pollution)
 for the upstream endpoint contract.
 
@@ -36,6 +38,10 @@ The air quality index uses OpenWeather's native scale from 1 (good) through 5
 the fixed `µg/m³` unit documented by OpenWeather; weather unit configuration
 does not affect them.
 
+OpenWeather also documents the UK, European, US, and Mainland China scales in
+its [Air Pollution Index levels](https://openweathermap.org/api/air-pollution-index-levels)
+reference.
+
 ```php
 $components = $current->components();
 

docs/weather.md

@@ -23,12 +23,12 @@ $current = $api->weather()->current(
 
 The method returns a `Current` entity. Every response property may be
 absent or explicitly `null`; missing or `null` condition lists become empty
-arrays.
+arrays. Contextual response coordinates are grouped under `coordinates()`.
 
 ```php
 echo $current->name();
-echo $current->latitude();
-echo $current->longitude();
+echo $current->coordinates()?->latitude();
+echo $current->coordinates()?->longitude();
 echo $current->temperature();
 echo $current->feelsLikeTemperature();
 echo $current->minimumTemperature();
@@ -109,8 +109,8 @@ foreach ($forecast->periods() as $period) {
 }
 
 echo $forecast->city()?->name();
-echo $forecast->city()?->latitude();
-echo $forecast->city()?->longitude();
+echo $forecast->city()?->coordinates()?->latitude();
+echo $forecast->city()?->coordinates()?->longitude();
 echo $forecast->city()?->timezoneOffset();
 ```
 

src/Entity/AirPollution/Current.php

@@ -5,6 +5,7 @@
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;
 use ProgrammatorDev\OpenWeatherMap\Entity\AirPollution\Concern\HasAirQuality;
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinates;
 use ProgrammatorDev\OpenWeatherMap\Hydration\PayloadReader;
 
 final class Current implements EntityInterface
@@ -21,6 +22,8 @@ public static function fromArray(array $data, ?Context $context = null): static
     {
         $reader = PayloadReader::from($data, self::class);
         $coordinates = $reader->nullableArray('coord');
+
+        // The current endpoint wraps its single observation in a list.
         $observation = $reader->nullableArray('list.0') ?? [];
 
         return new self(

src/Entity/AirPollution/Forecast.php

@@ -5,6 +5,7 @@
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;
 use ProgrammatorDev\OpenWeatherMap\Entity\AirPollution\Forecast\Period;
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinates;
 use ProgrammatorDev\OpenWeatherMap\Exception\HydrationException;
 use ProgrammatorDev\OpenWeatherMap\Hydration\PayloadReader;
 

src/Entity/AirPollution/History.php

@@ -5,6 +5,7 @@
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;
 use ProgrammatorDev\OpenWeatherMap\Entity\AirPollution\History\Period;
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinates;
 use ProgrammatorDev\OpenWeatherMap\Exception\HydrationException;
 use ProgrammatorDev\OpenWeatherMap\Hydration\PayloadReader;
 

src/Entity/AirPollution/Coordinates.php src/Entity/Coordinates.phpsrc/Entity/AirPollution/Coordinates.php renamed to src/Entity/Coordinates.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace ProgrammatorDev\OpenWeatherMap\Entity\AirPollution;
+namespace ProgrammatorDev\OpenWeatherMap\Entity;
 
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;

src/Entity/Weather/Current.php

@@ -4,6 +4,7 @@
 
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinates;
 use ProgrammatorDev\OpenWeatherMap\Entity\Weather\Concern\HasWeatherMeasurements;
 use ProgrammatorDev\OpenWeatherMap\Entity\Weather\Current\Precipitation;
 use ProgrammatorDev\OpenWeatherMap\Enum\Units;
@@ -19,8 +20,7 @@ final class Current implements EntityInterface
      * @param list<Condition> $conditions
      */
     private function __construct(
-        private readonly ?float $latitude,
-        private readonly ?float $longitude,
+        private readonly ?Coordinates $coordinates,
         private readonly array $conditions,
         private readonly ?float $temperature,
         private readonly ?float $feelsLikeTemperature,
@@ -48,6 +48,7 @@ private function __construct(
     public static function fromArray(array $data, ?Context $context = null): static
     {
         $reader = PayloadReader::from($data, self::class);
+        $coordinates = $reader->nullableArray('coord');
         $conditions = [];
 
         foreach ($reader->nullableArray('weather') ?? [] as $index => $condition) {
@@ -69,8 +70,9 @@ public static function fromArray(array $data, ?Context $context = null): static
         $snow = $reader->nullableArray('snow');
 
         return new self(
-            latitude: $reader->nullableFloat('coord.lat'),
-            longitude: $reader->nullableFloat('coord.lon'),
+            coordinates: $coordinates === null
+                ? null
+                : Coordinates::fromArray($coordinates, $context),
             conditions: $conditions,
             temperature: $reader->nullableFloat('main.temp'),
             feelsLikeTemperature: $reader->nullableFloat('main.feels_like'),
@@ -96,14 +98,9 @@ public static function fromArray(array $data, ?Context $context = null): static
         );
     }
 
-    public function latitude(): ?float
+    public function coordinates(): ?Coordinates
     {
-        return $this->latitude;
-    }
-
-    public function longitude(): ?float
-    {
-        return $this->longitude;
+        return $this->coordinates;
     }
 
     /**

src/Entity/Weather/Forecast/City.php

@@ -4,15 +4,15 @@
 
 use ProgrammatorDev\Api\Context\Context;
 use ProgrammatorDev\Api\Contract\EntityInterface;
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinates;
 use ProgrammatorDev\OpenWeatherMap\Hydration\PayloadReader;
 
 final class City implements EntityInterface
 {
     private function __construct(
         private readonly ?int $id,
         private readonly ?string $name,
-        private readonly ?float $latitude,
-        private readonly ?float $longitude,
+        private readonly ?Coordinates $coordinates,
         private readonly ?string $countryCode,
         private readonly ?int $population,
         private readonly ?int $timezoneOffset,
@@ -23,12 +23,14 @@ private function __construct(
     public static function fromArray(array $data, ?Context $context = null): static
     {
         $reader = PayloadReader::from($data, self::class);
+        $coordinates = $reader->nullableArray('coord');
 
         return new self(
             id: $reader->nullableInt('id'),
             name: $reader->nullableString('name'),
-            latitude: $reader->nullableFloat('coord.lat'),
-            longitude: $reader->nullableFloat('coord.lon'),
+            coordinates: $coordinates === null
+                ? null
+                : Coordinates::fromArray($coordinates, $context),
             countryCode: $reader->nullableString('country'),
             population: $reader->nullableInt('population'),
             timezoneOffset: $reader->nullableInt('timezone'),
@@ -47,14 +49,9 @@ public function name(): ?string
         return $this->name;
     }
 
-    public function latitude(): ?float
+    public function coordinates(): ?Coordinates
     {
-        return $this->latitude;
-    }
-
-    public function longitude(): ?float
-    {
-        return $this->longitude;
+        return $this->coordinates;
     }
 
     public function countryCode(): ?string

src/Resource/AirPollution.php

@@ -57,6 +57,9 @@ public function history(
         $latitude = Assert::latitude($latitude);
         $longitude = Assert::longitude($longitude);
         Assert::chronologicalRange($start, $end);
+
+        // A non-future end also constrains the ordered start.
+        // The documented minimum is left to OpenWeather because live availability differs.
         $end = Assert::notFuture($end, 'end date');
 
         // https://openweathermap.org/api/air-pollution

tests/Unit/Entity/Weather/CurrentTest.php

@@ -21,8 +21,8 @@ public function testHydratesCapturedCurrentWeather(): void
             Fixture::json('weather/current/success.json'),
         );
 
-        self::assertSame(38.7223, $weather->latitude());
-        self::assertSame(-9.1393, $weather->longitude());
+        self::assertSame(38.7223, $weather->coordinates()?->latitude());
+        self::assertSame(-9.1393, $weather->coordinates()?->longitude());
         self::assertSame(22.55, $weather->temperature());
         self::assertSame(Unit::CELSIUS, $weather->temperatureUnit());
         self::assertSame('22.55 °C', $weather->temperatureWithUnit());
@@ -124,6 +124,7 @@ public function testRetainsUnitsFromHydrationContext(): void
 
     public function testToleratesMissingNullUnknownAndPartialFields(): void
     {
+        self::assertNull(Current::fromArray([])->coordinates());
         self::assertSame([], Current::fromArray(['weather' => null])->conditions());
 
         $weather = Current::fromArray([
@@ -142,8 +143,8 @@ public function testToleratesMissingNullUnknownAndPartialFields(): void
             'unknown' => new \stdClass(),
         ]);
 
-        self::assertNull($weather->latitude());
-        self::assertNull($weather->longitude());
+        self::assertNull($weather->coordinates()?->latitude());
+        self::assertNull($weather->coordinates()?->longitude());
         self::assertCount(1, $weather->conditions());
         self::assertNull($weather->conditions()[0]->icon());
         self::assertNull($weather->conditions()[0]->iconUrl());
@@ -185,7 +186,7 @@ public function testRejectsInvalidKnownFieldTypes(
     public static function invalidFields(): iterable
     {
         yield 'coordinates' => [['coord' => 'invalid'], 'coord', 'array', 'string'];
-        yield 'latitude' => [['coord' => ['lat' => '38.7']], 'coord.lat', 'int|float', 'string'];
+        yield 'latitude' => [['coord' => ['lat' => '38.7']], 'lat', 'int|float', 'string'];
         yield 'conditions' => [['weather' => 'Clouds'], 'weather', 'array', 'string'];
         yield 'condition member' => [['weather' => ['Clouds']], 'weather.0', 'array', 'string'];
         yield 'condition id' => [['weather' => [['id' => '802']]], 'id', 'int', 'string'];