Improve methods return type and docblocks

nyamsprod · nyamsprod · commit 680bf6e4c244 · 2023-03-07T20:42:11.000+01:00
diff --git a/src/Dictionary.php b/src/Dictionary.php
@@ -20,16 +20,16 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
  *
- * @implements MemberOrderedMap<string, Value|InnerList<int, Value>>
+ * @implements MemberOrderedMap<string, Value|(MemberList<int, Value>&ParameterAccess)>
  * @phpstan-import-type DataType from Value
  */
 final class Dictionary implements MemberOrderedMap
 {
-    /** @var array<string, Value|InnerList<int, Value>> */
+    /** @var array<string, Value|(MemberList<int, Value>&ParameterAccess)> */
     private array $members = [];
 
     /**
-     * @param iterable<string, InnerList<int, Value>|iterable<Value|DataType>|Value|DataType> $members
+     * @param iterable<string, (MemberList<int, Value>&ParameterAccess)|iterable<Value|DataType>|Value|DataType> $members
      */
     private function __construct(iterable $members = [])
     {
@@ -40,11 +40,14 @@ private function __construct(iterable $members = [])
 
     /**
      * @param StructuredField|iterable<Value|DataType>|DataType $member
+     *
+     * @return Value|(MemberList<int, Value>&ParameterAccess)
      */
-    private static function filterMember(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): InnerList|Value
+    private static function filterMember(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): mixed
     {
         return match (true) {
-            $member instanceof InnerList, $member instanceof Value => $member,
+            ($member instanceof MemberList && $member instanceof ParameterAccess),
+            $member instanceof Value => $member,
             is_iterable($member) => InnerList::fromList($member),
             default => Item::from($member),
         };
@@ -64,7 +67,7 @@ public static function create(): self
      * its keys represent the dictionary entry key
      * its values represent the dictionary entry value
      *
-     * @param iterable<string, InnerList<int, Value>|list<Value|DataType>|Value|DataType> $members
+     * @param iterable<string, (MemberList<int, Value>&ParameterAccess)|list<Value|DataType>|Value|DataType> $members
      */
     public static function fromAssociative(iterable $members): self
     {
@@ -78,7 +81,7 @@ public static function fromAssociative(iterable $members): self
      * the first member represents the instance entry key
      * the second member represents the instance entry value
      *
-     * @param MemberOrderedMap<string, Value|InnerList<int, Value>>|iterable<array{0:string, 1:InnerList<int, Value>|list<Value|DataType>|Value|DataType}> $pairs
+     * @param MemberOrderedMap<string, Value|(MemberList<int, Value>&ParameterAccess)>|iterable<array{0:string, 1:(MemberList<int, Value>&ParameterAccess)|list<Value|DataType>|Value|DataType}> $pairs
      */
     public static function fromPairs(iterable $pairs): self
     {
@@ -111,7 +114,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
 
     public function toHttpValue(): string
     {
-        $formatter = static fn (Value|InnerList $member, string $key): string => match (true) {
+        $formatter = static fn (StructuredField $member, string $key): string => match (true) {
             $member instanceof Value && true === $member->value() => $key.$member->parameters()->toHttpValue(),
             default => $key.'='.$member->toHttpValue(),
         };
@@ -140,15 +143,15 @@ public function hasMembers(): bool
     }
 
     /**
-     * @return Iterator<string, Value|InnerList<int, Value>>
+     * @return Iterator<string, Value|(MemberList<int, Value>&ParameterAccess)>
      */
     public function getIterator(): Iterator
     {
         yield from $this->members;
     }
 
     /**
-     * @return Iterator<array{0:string, 1:Value|InnerList<int, Value>}>
+     * @return Iterator<array{0:string, 1:Value|(MemberList<int, Value>&ParameterAccess)}>
      */
     public function toPairs(): Iterator
     {
@@ -179,8 +182,10 @@ public function has(string|int ...$keys): bool
     /**
      * @throws SyntaxError   If the key is invalid
      * @throws InvalidOffset If the key is not found
+     *
+     * @return Value|(MemberList<int, Value>&ParameterAccess)
      */
-    public function get(string|int $key): Value|InnerList
+    public function get(string|int $key): StructuredField
     {
         if (!$this->has($key)) {
             throw InvalidOffset::dueToKeyNotFound($key);
@@ -219,7 +224,7 @@ private function filterIndex(int $index): int
     /**
      * @throws InvalidOffset If the key is not found
      *
-     * @return array{0:string, 1:Value|InnerList<int, Value>}
+     * @return array{0:string, 1:Value|(MemberList<int, Value>&ParameterAccess)}
      */
     public function pair(int $index): array
     {
@@ -265,7 +270,7 @@ public function prepend(string $key, StructuredField|Token|ByteSequence|DateTime
     }
 
     /**
-     * @param iterable<string, InnerList<int, Value>|Value|DataType> ...$others
+     * @param iterable<string, (MemberList<int, Value>&ParameterAccess)|Value|DataType> ...$others
      */
     public function mergeAssociative(iterable ...$others): static
     {
@@ -278,7 +283,7 @@ public function mergeAssociative(iterable ...$others): static
     }
 
     /**
-     * @param MemberOrderedMap<string, Value|InnerList<int, Value>>|iterable<array{0:string, 1:InnerList<int, Value>|Value|DataType}> ...$others
+     * @param MemberOrderedMap<string, Value|(MemberList<int, Value>&ParameterAccess)>|iterable<array{0:string, 1:(MemberList<int, Value>&ParameterAccess)|Value|DataType}> ...$others
      */
     public function mergePairs(MemberOrderedMap|iterable ...$others): static
     {
@@ -301,9 +306,9 @@ public function offsetExists(mixed $offset): bool
     /**
      * @param string $offset
      *
-     * @return Value|InnerList<int, Value>
+     * @return Value|(MemberList<int, Value>&ParameterAccess)
      */
-    public function offsetGet(mixed $offset): InnerList|Value
+    public function offsetGet(mixed $offset): mixed
     {
         return $this->get($offset);
     }
diff --git a/src/InnerList.php b/src/InnerList.php
@@ -67,7 +67,7 @@ private static function filterMember(StructuredField|Token|ByteSequence|DateTime
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        return InnerList::fromList(...Parser::parseInnerList($httpValue));
+        return self::fromList(...Parser::parseInnerList($httpValue));
     }
 
     public function parameters(): Parameters
diff --git a/src/OuterList.php b/src/OuterList.php
@@ -19,15 +19,18 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#name-lists
  *
- * @implements MemberList<int, Value|InnerList<int, Value>>
+ * @implements MemberList<int, Value|(MemberList<int, Value>&ParameterAccess)>
  * @phpstan-import-type DataType from Value
  */
 final class OuterList implements MemberList
 {
-    /** @var list<Value|InnerList<int, Value>> */
+    /** @var list<Value|(MemberList<int, Value>&ParameterAccess)> */
     private array $members;
 
-    private function __construct(InnerList|Value ...$members)
+    /**
+     * @param Value|(MemberList<int, Value>&ParameterAccess) ...$members
+     */
+    private function __construct(MemberList|Value ...$members)
     {
         $this->members = array_values($members);
     }
@@ -41,7 +44,7 @@ public static function from(iterable|StructuredField|Token|ByteSequence|DateTime
     }
 
     /**
-     * @param iterable<InnerList<int, Value>|list<Value|DataType>|Value|DataType> $members
+     * @param iterable<(MemberList<int, Value>&ParameterAccess)|list<Value|DataType>|Value|DataType> $members
      */
     public static function fromList(iterable $members = []): self
     {
@@ -50,11 +53,14 @@ public static function fromList(iterable $members = []): self
 
     /**
      * @param StructuredField|iterable<Value|DataType>|DataType $member
+     *
+     * @return (MemberList<int, Value>&ParameterAccess)|Value
      */
-    private static function filterMember(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): InnerList|Value
+    private static function filterMember(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): mixed
     {
         return match (true) {
-            $member instanceof InnerList, $member instanceof Value => $member,
+            ($member instanceof MemberList && $member instanceof ParameterAccess),
+            $member instanceof Value => $member,
             is_iterable($member) => InnerList::fromList($member),
             default => Item::from($member),
         };
@@ -107,7 +113,7 @@ public function keys(): array
     }
 
     /**
-     * @return Iterator<int, Value|InnerList<int, Value>>
+     * @return Iterator<int, Value|(MemberList<int, Value>&ParameterAccess)>
      */
     public function getIterator(): Iterator
     {
@@ -142,7 +148,10 @@ private function filterIndex(string|int $index): int|null
         };
     }
 
-    public function get(string|int $key): Value|InnerList
+    /**
+     * @return (MemberList<int, Value>&ParameterAccess)|Value
+     */
+    public function get(string|int $key): MemberList|Value
     {
         $index = $this->filterIndex($key);
         if (null === $index) {
@@ -246,9 +255,9 @@ public function offsetExists(mixed $offset): bool
     /**
      * @param int $offset
      *
-     * @return Value|InnerList<int, Value>
+     * @return Value|(MemberList<int, Value>&ParameterAccess)
      */
-    public function offsetGet(mixed $offset): InnerList|Value
+    public function offsetGet(mixed $offset): mixed
     {
         return $this->get($offset);
     }

Original file line number	Diff line number	Diff line change
`@@ -20,16 +20,16 @@`
`20`	`20`	`/**`
`21`	`21`	`* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2`
`22`	`22`	`*`
`23`		`- * @implements MemberOrderedMap<string, Value\|InnerList<int, Value>>`
	`23`	`+ * @implements MemberOrderedMap<string, Value\|(MemberList<int, Value>&ParameterAccess)>`
`24`	`24`	`* @phpstan-import-type DataType from Value`
`25`	`25`	`*/`
`26`	`26`	`final class Dictionary implements MemberOrderedMap`
`27`	`27`	`{`
`28`		`- /** @var array<string, Value\|InnerList<int, Value>> */`
	`28`	`+ /** @var array<string, Value\|(MemberList<int, Value>&ParameterAccess)> */`
`29`	`29`	`private array $members = [];`
`30`	`30`
`31`	`31`	`/**`
`32`		`- * @param iterable<string, InnerList<int, Value>\|iterable<Value\|DataType>\|Value\|DataType> $members`
	`32`	`+ * @param iterable<string, (MemberList<int, Value>&ParameterAccess)\|iterable<Value\|DataType>\|Value\|DataType> $members`
`33`	`33`	`*/`
`34`	`34`	`private function __construct(iterable $members = [])`
`35`	`35`	`{`
`@@ -40,11 +40,14 @@ private function __construct(iterable $members = [])`
`40`	`40`
`41`	`41`	`/**`
`42`	`42`	`* @param StructuredField\|iterable<Value\|DataType>\|DataType $member`
	`43`	`+ *`
	`44`	`+ * @return Value\|(MemberList<int, Value>&ParameterAccess)`
`43`	`45`	`*/`
`44`		`- private static function filterMember(iterable\|StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): InnerList\|Value`
	`46`	`+ private static function filterMember(iterable\|StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): mixed`
`45`	`47`	`{`
`46`	`48`	`return match (true) {`
`47`		`- $member instanceof InnerList, $member instanceof Value => $member,`
	`49`	`+ ($member instanceof MemberList && $member instanceof ParameterAccess),`
	`50`	`+ $member instanceof Value => $member,`
`48`	`51`	`is_iterable($member) => InnerList::fromList($member),`
`49`	`52`	`default => Item::from($member),`
`50`	`53`	`};`
`@@ -64,7 +67,7 @@ public static function create(): self`
`64`	`67`	`* its keys represent the dictionary entry key`
`65`	`68`	`* its values represent the dictionary entry value`
`66`	`69`	`*`
`67`		`- * @param iterable<string, InnerList<int, Value>\|list<Value\|DataType>\|Value\|DataType> $members`
	`70`	`+ * @param iterable<string, (MemberList<int, Value>&ParameterAccess)\|list<Value\|DataType>\|Value\|DataType> $members`
`68`	`71`	`*/`
`69`	`72`	`public static function fromAssociative(iterable $members): self`
`70`	`73`	`{`
`@@ -78,7 +81,7 @@ public static function fromAssociative(iterable $members): self`
`78`	`81`	`* the first member represents the instance entry key`
`79`	`82`	`* the second member represents the instance entry value`
`80`	`83`	`*`
`81`		`- * @param MemberOrderedMap<string, Value\|InnerList<int, Value>>\|iterable<array{0:string, 1:InnerList<int, Value>\|list<Value\|DataType>\|Value\|DataType}> $pairs`
	`84`	`+ * @param MemberOrderedMap<string, Value\|(MemberList<int, Value>&ParameterAccess)>\|iterable<array{0:string, 1:(MemberList<int, Value>&ParameterAccess)\|list<Value\|DataType>\|Value\|DataType}> $pairs`
`82`	`85`	`*/`
`83`	`86`	`public static function fromPairs(iterable $pairs): self`
`84`	`87`	`{`
`@@ -111,7 +114,7 @@ public static function fromHttpValue(Stringable\|string $httpValue): self`
`111`	`114`
`112`	`115`	`public function toHttpValue(): string`
`113`	`116`	`{`
`114`		`- $formatter = static fn (Value\|InnerList $member, string $key): string => match (true) {`
	`117`	`+ $formatter = static fn (StructuredField $member, string $key): string => match (true) {`
`115`	`118`	`$member instanceof Value && true === $member->value() => $key.$member->parameters()->toHttpValue(),`
`116`	`119`	`default => $key.'='.$member->toHttpValue(),`
`117`	`120`	`};`
`@@ -140,15 +143,15 @@ public function hasMembers(): bool`
`140`	`143`	`}`
`141`	`144`
`142`	`145`	`/**`
`143`		`- * @return Iterator<string, Value\|InnerList<int, Value>>`
	`146`	`+ * @return Iterator<string, Value\|(MemberList<int, Value>&ParameterAccess)>`
`144`	`147`	`*/`
`145`	`148`	`public function getIterator(): Iterator`
`146`	`149`	`{`
`147`	`150`	`yield from $this->members;`
`148`	`151`	`}`
`149`	`152`
`150`	`153`	`/**`
`151`		`- * @return Iterator<array{0:string, 1:Value\|InnerList<int, Value>}>`
	`154`	`+ * @return Iterator<array{0:string, 1:Value\|(MemberList<int, Value>&ParameterAccess)}>`
`152`	`155`	`*/`
`153`	`156`	`public function toPairs(): Iterator`
`154`	`157`	`{`
`@@ -179,8 +182,10 @@ public function has(string\|int ...$keys): bool`
`179`	`182`	`/**`
`180`	`183`	`* @throws SyntaxError If the key is invalid`
`181`	`184`	`* @throws InvalidOffset If the key is not found`
	`185`	`+ *`
	`186`	`+ * @return Value\|(MemberList<int, Value>&ParameterAccess)`
`182`	`187`	`*/`
`183`		`- public function get(string\|int $key): Value\|InnerList`
	`188`	`+ public function get(string\|int $key): StructuredField`
`184`	`189`	`{`
`185`	`190`	`if (!$this->has($key)) {`
`186`	`191`	`throw InvalidOffset::dueToKeyNotFound($key);`
`@@ -219,7 +224,7 @@ private function filterIndex(int $index): int`
`219`	`224`	`/**`
`220`	`225`	`* @throws InvalidOffset If the key is not found`
`221`	`226`	`*`
`222`		`- * @return array{0:string, 1:Value\|InnerList<int, Value>}`
	`227`	`+ * @return array{0:string, 1:Value\|(MemberList<int, Value>&ParameterAccess)}`
`223`	`228`	`*/`
`224`	`229`	`public function pair(int $index): array`
`225`	`230`	`{`
`@@ -265,7 +270,7 @@ public function prepend(string $key, StructuredField\|Token\|ByteSequence\|DateTime`
`265`	`270`	`}`
`266`	`271`
`267`	`272`	`/**`
`268`		`- * @param iterable<string, InnerList<int, Value>\|Value\|DataType> ...$others`
	`273`	`+ * @param iterable<string, (MemberList<int, Value>&ParameterAccess)\|Value\|DataType> ...$others`
`269`	`274`	`*/`
`270`	`275`	`public function mergeAssociative(iterable ...$others): static`
`271`	`276`	`{`
`@@ -278,7 +283,7 @@ public function mergeAssociative(iterable ...$others): static`
`278`	`283`	`}`
`279`	`284`
`280`	`285`	`/**`
`281`		`- * @param MemberOrderedMap<string, Value\|InnerList<int, Value>>\|iterable<array{0:string, 1:InnerList<int, Value>\|Value\|DataType}> ...$others`
	`286`	`+ * @param MemberOrderedMap<string, Value\|(MemberList<int, Value>&ParameterAccess)>\|iterable<array{0:string, 1:(MemberList<int, Value>&ParameterAccess)\|Value\|DataType}> ...$others`
`282`	`287`	`*/`
`283`	`288`	`public function mergePairs(MemberOrderedMap\|iterable ...$others): static`
`284`	`289`	`{`
`@@ -301,9 +306,9 @@ public function offsetExists(mixed $offset): bool`
`301`	`306`	`/**`
`302`	`307`	`* @param string $offset`
`303`	`308`	`*`
`304`		`- * @return Value\|InnerList<int, Value>`
	`309`	`+ * @return Value\|(MemberList<int, Value>&ParameterAccess)`
`305`	`310`	`*/`
`306`		`- public function offsetGet(mixed $offset): InnerList\|Value`
	`311`	`+ public function offsetGet(mixed $offset): mixed`
`307`	`312`	`{`
`308`	`313`	`return $this->get($offset);`
`309`	`314`	`}`
Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,7 @@ private static function filterMember(StructuredField\|Token\|ByteSequence\|DateTime`
`67`	`67`	`*/`
`68`	`68`	`public static function fromHttpValue(Stringable\|string $httpValue): self`
`69`	`69`	`{`
`70`		`- return InnerList::fromList(...Parser::parseInnerList($httpValue));`
	`70`	`+ return self::fromList(...Parser::parseInnerList($httpValue));`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`public function parameters(): Parameters`
Original file line number	Diff line number	Diff line change
`@@ -19,15 +19,18 @@`
`19`	`19`	`/**`
`20`	`20`	`* @see https://www.rfc-editor.org/rfc/rfc8941.html#name-lists`
`21`	`21`	`*`
`22`		`- * @implements MemberList<int, Value\|InnerList<int, Value>>`
	`22`	`+ * @implements MemberList<int, Value\|(MemberList<int, Value>&ParameterAccess)>`
`23`	`23`	`* @phpstan-import-type DataType from Value`
`24`	`24`	`*/`
`25`	`25`	`final class OuterList implements MemberList`
`26`	`26`	`{`
`27`		`- /** @var list<Value\|InnerList<int, Value>> */`
	`27`	`+ /** @var list<Value\|(MemberList<int, Value>&ParameterAccess)> */`
`28`	`28`	`private array $members;`
`29`	`29`
`30`		`- private function __construct(InnerList\|Value ...$members)`
	`30`	`+ /**`
	`31`	`+ * @param Value\|(MemberList<int, Value>&ParameterAccess) ...$members`
	`32`	`+ */`
	`33`	`+ private function __construct(MemberList\|Value ...$members)`
`31`	`34`	`{`
`32`	`35`	`$this->members = array_values($members);`
`33`	`36`	`}`
`@@ -41,7 +44,7 @@ public static function from(iterable\|StructuredField\|Token\|ByteSequence\|DateTime`
`41`	`44`	`}`
`42`	`45`
`43`	`46`	`/**`
`44`		`- * @param iterable<InnerList<int, Value>\|list<Value\|DataType>\|Value\|DataType> $members`
	`47`	`+ * @param iterable<(MemberList<int, Value>&ParameterAccess)\|list<Value\|DataType>\|Value\|DataType> $members`
`45`	`48`	`*/`
`46`	`49`	`public static function fromList(iterable $members = []): self`
`47`	`50`	`{`
`@@ -50,11 +53,14 @@ public static function fromList(iterable $members = []): self`
`50`	`53`
`51`	`54`	`/**`
`52`	`55`	`* @param StructuredField\|iterable<Value\|DataType>\|DataType $member`
	`56`	`+ *`
	`57`	`+ * @return (MemberList<int, Value>&ParameterAccess)\|Value`
`53`	`58`	`*/`
`54`		`- private static function filterMember(iterable\|StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): InnerList\|Value`
	`59`	`+ private static function filterMember(iterable\|StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): mixed`
`55`	`60`	`{`
`56`	`61`	`return match (true) {`
`57`		`- $member instanceof InnerList, $member instanceof Value => $member,`
	`62`	`+ ($member instanceof MemberList && $member instanceof ParameterAccess),`
	`63`	`+ $member instanceof Value => $member,`
`58`	`64`	`is_iterable($member) => InnerList::fromList($member),`
`59`	`65`	`default => Item::from($member),`
`60`	`66`	`};`
`@@ -107,7 +113,7 @@ public function keys(): array`
`107`	`113`	`}`
`108`	`114`
`109`	`115`	`/**`
`110`		`- * @return Iterator<int, Value\|InnerList<int, Value>>`
	`116`	`+ * @return Iterator<int, Value\|(MemberList<int, Value>&ParameterAccess)>`
`111`	`117`	`*/`
`112`	`118`	`public function getIterator(): Iterator`
`113`	`119`	`{`
`@@ -142,7 +148,10 @@ private function filterIndex(string\|int $index): int\|null`
`142`	`148`	`};`
`143`	`149`	`}`
`144`	`150`
`145`		`- public function get(string\|int $key): Value\|InnerList`
	`151`	`+ /**`
	`152`	`+ * @return (MemberList<int, Value>&ParameterAccess)\|Value`
	`153`	`+ */`
	`154`	`+ public function get(string\|int $key): MemberList\|Value`
`146`	`155`	`{`
`147`	`156`	`$index = $this->filterIndex($key);`
`148`	`157`	`if (null === $index) {`
`@@ -246,9 +255,9 @@ public function offsetExists(mixed $offset): bool`
`246`	`255`	`/**`
`247`	`256`	`* @param int $offset`
`248`	`257`	`*`
`249`		`- * @return Value\|InnerList<int, Value>`
	`258`	`+ * @return Value\|(MemberList<int, Value>&ParameterAccess)`
`250`	`259`	`*/`
`251`		`- public function offsetGet(mixed $offset): InnerList\|Value`
	`260`	`+ public function offsetGet(mixed $offset): mixed`
`252`	`261`	`{`
`253`	`262`	`return $this->get($offset);`
`254`	`263`	`}`