chore(refactor): simplify base page interface

Author: stainless-app[bot]

src/Core/Concerns/SdkModel.php

@@ -5,7 +5,6 @@
 namespace CasParser\Core\Concerns;
 
 use CasParser\Core\Contracts\BaseModel;
-use CasParser\Core\Contracts\BasePage;
 use CasParser\Core\Conversion;
 use CasParser\Core\Conversion\CoerceState;
 use CasParser\Core\Conversion\Contracts\Converter;
@@ -15,7 +14,7 @@
 /**
  * @internal
  *
- * @template-covariant Data of array<string, mixed>
+ * @template-covariant Shape of array<string, mixed>
  */
 trait SdkModel
 {
@@ -41,12 +40,12 @@ public function __serialize(): array
     /**
      * @internal
      *
-     * @param array<mixed> $data
+     * @param array<string, mixed> $data
      */
     public function __unserialize(array $data): void
     {
         foreach ($data as $key => $value) {
-            $this->offsetSet($key, value: $value);
+            $this->offsetSet($key, value: $value); // @phpstan-ignore-line
         }
     }
 
@@ -73,12 +72,14 @@ public function __toString(): string
      * a native class property, indicating an omitted value,
      * or a property overridden with an incongruent type
      *
+     * @return value-of<Shape>
+     *
      * @throws \Exception
      */
     public function __get(string $key): mixed
     {
         if (!array_key_exists($key, array: self::$converter->properties)) {
-            throw new \Exception("Property '{$key}' does not exist in {$this}::class");
+            throw new \RuntimeException("Property '{$key}' does not exist in {$this}::class");
         }
 
         // The unset property was overridden by a value with an incongruent type.
@@ -91,11 +92,11 @@ public function __get(string $key): mixed
 
         // An optional property which was unset to be omitted from serialized is being accessed.
         // Return null to match user's expectations.
-        return null;
+        return null; // @phpstan-ignore-line
     }
 
     /**
-     * @return Data
+     * @return Shape
      */
     public function toArray(): array
     {
@@ -104,6 +105,8 @@ public function toArray(): array
 
     /**
      * @internal
+     *
+     * @param key-of<Shape> $offset
      */
     public function offsetExists(mixed $offset): bool
     {
@@ -130,26 +133,32 @@ public function offsetExists(mixed $offset): bool
 
     /**
      * @internal
+     *
+     * @param key-of<Shape> $offset
+     *
+     * @return value-of<Shape>
      */
     public function &offsetGet(mixed $offset): mixed
     {
         if (!is_string($offset)) { // @phpstan-ignore-line
             throw new \InvalidArgumentException;
         }
 
-        if (!$this->offsetExists($offset)) {
-            return null;
+        if (!$this->offsetExists($offset)) { // @phpstan-ignore-line
+            return null; // @phpstan-ignore-line
         }
 
         if (array_key_exists($offset, array: $this->_data)) {
-            return $this->_data[$offset];
+            return $this->_data[$offset]; // @phpstan-ignore-line
         }
 
-        return $this->{$offset};
+        return $this->{$offset}; // @phpstan-ignore-line
     }
 
     /**
      * @internal
+     *
+     * @param key-of<Shape> $offset
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
@@ -163,9 +172,9 @@ public function offsetSet(mixed $offset, mixed $value): void
 
         $coerced = Conversion::coerce($type, value: $value, state: new CoerceState(translateNames: false));
 
-        if (property_exists($this, property: $offset)) {
+        if (property_exists($this, property: $offset)) { // @phpstan-ignore-line
             try {
-                $this->{$offset} = $coerced;
+                $this->{$offset} = $coerced; // @phpstan-ignore-line
                 unset($this->_data[$offset]);
 
                 return;
@@ -179,14 +188,16 @@ public function offsetSet(mixed $offset, mixed $value): void
 
     /**
      * @internal
+     *
+     * @param key-of<Shape> $offset
      */
     public function offsetUnset(mixed $offset): void
     {
         if (!is_string($offset)) { // @phpstan-ignore-line
             throw new \InvalidArgumentException;
         }
 
-        if (property_exists($this, property: $offset)) {
+        if (property_exists($this, property: $offset)) { // @phpstan-ignore-line
             unset($this->{$offset});
         }
 
@@ -205,7 +216,7 @@ public function jsonSerialize(): array
     /**
      * @param array<string, mixed> $data
      */
-    public static function fromArray(array $data): self
+    public static function fromArray(array $data): static
     {
         return self::converter()->from($data); // @phpstan-ignore-line
     }
@@ -249,7 +260,7 @@ private function unsetOptionalProperties(): void
      */
     private static function serialize(mixed $value): mixed
     {
-        if ($value instanceof BaseModel || $value instanceof BasePage) {
+        if ($value instanceof BaseModel) {
             return $value->toArray();
         }
 

src/Core/Concerns/SdkPage.php

@@ -100,6 +100,13 @@ public function pagingEachItem(): \Generator
         }
     }
 
+    /**
+     * @param array<string, mixed> $data
+     *
+     * @return static<Item>
+     */
+    abstract public static function fromArray(array $data): static;
+
     /**
      * @return array{normalized_request, RequestOptions}
      */

src/Core/Contracts/BasePage.php

@@ -14,10 +14,9 @@
  *
  * @template Item
  *
- * @extends \ArrayAccess<string, mixed>
  * @extends \IteratorAggregate<int, static>
  */
-interface BasePage extends \ArrayAccess, \JsonSerializable, \Stringable, \IteratorAggregate
+interface BasePage extends \IteratorAggregate
 {
     /**
      * @internal
@@ -32,16 +31,6 @@ public function __construct(
         mixed $data,
     );
 
-    /**
-     * @param array<string, mixed> $data
-     *
-     * @return static<Item>
-     */
-    public static function fromArray(array $data): self;
-
-    /** @return array<string, mixed> */
-    public function toArray(): array;
-
     public function hasNextPage(): bool;
 
     /**

src/Core/Conversion/ModelOf.php

@@ -6,7 +6,6 @@
 
 use CasParser\Core\Attributes\Api;
 use CasParser\Core\Contracts\BaseModel;
-use CasParser\Core\Contracts\BasePage;
 use CasParser\Core\Conversion;
 use CasParser\Core\Conversion\Contracts\Converter;
 
@@ -21,7 +20,7 @@ final class ModelOf implements Converter
     public readonly array $properties;
 
     /**
-     * @param \ReflectionClass<BaseModel|BasePage<mixed>> $class
+     * @param \ReflectionClass<BaseModel> $class
      */
     public function __construct(public readonly \ReflectionClass $class)
     {
@@ -89,15 +88,13 @@ public function coerce(mixed $value, CoerceState $state): mixed
             $acc[$name] = $item;
         }
 
-        return $this->from($acc);
+        return $this->from($acc); // @phpstan-ignore-line
     }
 
     /**
-     * @param array<mixed> $data
-     *
-     * @return BaseModel|BasePage<mixed>
+     * @param array<string, mixed> $data
      */
-    public function from(array $data): BaseModel|BasePage
+    public function from(array $data): BaseModel
     {
         $instance = $this->class->newInstanceWithoutConstructor();
         $instance->__unserialize($data); // @phpstan-ignore-line
@@ -107,7 +104,7 @@ public function from(array $data): BaseModel|BasePage
 
     public function dump(mixed $value, DumpState $state): mixed
     {
-        if ($value instanceof BaseModel || $value instanceof BasePage) {
+        if ($value instanceof BaseModel) {
             $value = $value->toArray();
         }