Improve named constructors for List containers

Author: nyamsprod

CHANGELOG.md

@@ -8,10 +8,14 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 - `Item::fromTimestamp`, `Item::fromDateFormat` to improve item instantiation with dates.
 - `ParameterAccess::parameter` to ease parameter members value access.
-- **[BC Break]**  `ParameterAccess::withoutAllParameters` is renamed `ParameterAccess::withoutAnyParameters`.
+- `InnerList::fromAssociativeParameters`
+- `InnerList::fromPairParameters`
+- **[BC Break]** `ParameterAccess::withoutAllParameters` is renamed `ParameterAccess::withoutAnyParameter`.
 - **[BC Break]** `OrderedList` is renamed `OuterList`.
 - **[BC Break]** `MemberContainer::remove` methods get added to the interface.
 - **[BC Break]** `MemberContainer::keys` method added to the interface.
+- **[BC Break]** `InnerList::from` is renamed `InnerList::fromMembers`.
+- **[BC Break]** `OuterList::from` is renamed `OuterList::fromMembers`.
 
 ### Fixed
 
@@ -31,9 +35,11 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[BC Break]** `OrderedList` is removed, use `OuterList` instead.
 - **[BC Break]**  `ParameterAccess::withoutAllParameters` is removed, use `ParameterAccess::withoutAnyParameters` instead.
 - **[BC Break]**  remove the `$parameters` argument from all `Item` named constuctore except from `Item::from`.
-- **[BC Break]**  remove the `InnerList::fromList`, use `InnerList::from` instead.
-- **[BC Break]**  remove the `OuterList::fromList`, use `OuterList::from` instead.
-
+- **[BC Break]**  remove `InnerList::fromList`, use `InnerList::from` instead.
+- **[BC Break]**  remove `OuterList::fromList`, use `OuterList::from` instead.
+- **[BC Break]**  remove `InnerList::from` use `InnerList::fromMembers`.
+- **[BC Break]**  remove `OuterList::from` use `OuterList::fromMembers`.
+- 
 ## [0.7.0] - 2023-02-06
 
 ### Added

README.md

@@ -100,9 +100,11 @@ $newResponse = $response->headers->set('foo', $bar);
 The library provides all five (5) structured defined in the RFC inside the `Bakame\Http\StructuredFields`
 namespace.
 
-- `Item`;
-- `Dictionary` and `Parameters` as 2 Ordered map Containers;
-- `OuterList` and `InnerList` as 2 list Containers ;
+- `Item`
+- `Parameters`
+- `Dictionary`
+- `OuterList`
+- `InnerList`
 
 They all implement the `StructuredField` interface and expose a `fromHttpValue` named constructor:
 
@@ -178,7 +180,7 @@ Conversely, changes can be applied to `OuterList` and `InnerList` with adapted m
 use Bakame\Http\StructuredFields\InnerList;
 use Bakame\Http\StructuredFields\Item;
 
-$list = InnerList::from()
+$list = InnerList::fromMembers()
     ->unshift('42')
     ->push(42)
     ->insert(1, 42.0)
@@ -206,7 +208,7 @@ $field->addParameter($key, $value): static;
 $field->appendParameter($key, $value): static;
 $field->prependParameter($key, $value): static;
 $field->withoutParameters(...$keys): static;
-$field->withoutAllParameters($): static;
+$field->withoutAnyParameter(): static;
 $field->withParameters(Parameters $parameters): static;
 ```
 
@@ -291,7 +293,7 @@ so they all expect an associative iterable to represents the parameters.
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Value;
 
-//@type DataType ByteSequence|Token|DateTimeInterface|Stringable|string|int|float|bool
+//@type DataType Value|ByteSequence|Token|DateTimeInterface|Stringable|string|int|float|bool
 
 Item::from(DataType $value, iterable<string, Value> $associativeParameters = []): self;
 Item::fromPair(array{0:DataType, 1:iterable<array{0:string, 1:DataType}>} $pair): self;
@@ -305,16 +307,29 @@ Item::fromDateString(string $datetime, DateTimeZone|string|null $timezone): self
 
 ### Accessing members of Structured Fields Containers.
 
-`Item` are accessible using three (3) methods:
+`Item` properties are accessible using the following methods:
 
 ```php
 use Bakame\Http\StructuredFields\Item;
 
 $item = Item::from(CarbonImmutable::parse('today'));
 $item->type();         // return Type::Date;
 $item->value()         // return CarbonImmutable::parse('today') (because it extends DateTimeImmutable)
-$item->parameters();   // returns a Parameters container
-$item->parameter('z'); // returns the Bare Item value or null if the key does not exists
+```
+
+You can attach, read and update the associated `Parameters` instance using the
+following:
+
+```php
+use Bakame\Http\StructuredFields\Parameters;
+
+$item->parameter($key): mixed|null;
+$item->addParameter($key, $value): static;
+$item->appendParameter($key, $value): static;
+$item->prependParameter($key, $value): static;
+$item->withoutParameters(...$keys): static;
+$item->withoutAnyParameter(): static;
+$item->withParameters(Parameters $parameters): static;
 ```
 
 All containers implement PHP `IteratorAggregate`, `Countable` and `ArrayAccess` interfaces for easy usage in your codebase.
@@ -326,7 +341,7 @@ $container->has(string|int ...$offsets): bool;
 $container->get(string|int $offset): bool;
 $container->remove(string|int ...$offsets): bool;
 $container->hasMembers(): bool;
-$container->hasNotMembers(): bool;
+$container->hasNoMembers(): bool;
 ```
 
 To avoid invalid states, the modifying methods from PHP `ArrayAccess` will throw a `ForbiddenOperation` if you try to

src/Dictionary.php

@@ -48,7 +48,7 @@ private static function filterMember(iterable|StructuredField|Token|ByteSequence
         return match (true) {
             ($member instanceof MemberList && $member instanceof ParameterAccess),
             $member instanceof Value => $member,
-            is_iterable($member) => InnerList::from(...$member),
+            is_iterable($member) => InnerList::fromMembers(...$member),
             default => Item::from($member),
         };
     }
@@ -107,7 +107,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
     {
         return new self((function (iterable $pairs) {
             foreach ($pairs as $key => $value) {
-                yield $key => is_array($value) ? InnerList::from(...$value[0])->withParameters(Parameters::fromAssociative($value[1])) : $value;
+                yield $key => is_array($value) ? InnerList::fromMembers(...$value[0])->withParameters(Parameters::fromAssociative($value[1])) : $value;
             }
         })(Parser::parseDictionary($httpValue)));
     }

src/InnerList.php

@@ -24,7 +24,7 @@
 final class InnerList implements MemberList, ParameterAccess
 {
     /** @var list<Value> */
-    private array $members;
+    private readonly array $members;
 
     /**
      * @param iterable<Value|DataType> $members
@@ -37,11 +37,31 @@ private function __construct(private readonly Parameters $parameters, iterable $
     /**
      * Returns a new instance.
      */
-    public static function from(Value|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): static
+    public static function fromMembers(Value|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): static
     {
         return new self(Parameters::create(), $members);
     }
 
+    /**
+     * Returns a new instance with an iter.
+     *
+     * @param iterable<string,Value|DataType> $parameters
+     */
+    public static function fromAssociativeParameters(iterable $parameters, Value|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): static
+    {
+        return new self(Parameters::fromAssociative($parameters), $members);
+    }
+
+    /**
+     * Returns a new instance.
+     *
+     * @param MemberOrderedMap<string, Value>|iterable<array{0:string, 1:Value|DataType}> $parameters
+     */
+    public static function fromPairParameters(iterable $parameters, Value|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): static
+    {
+        return new self(Parameters::fromPairs($parameters), $members);
+    }
+
     private static function filterMember(StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): Value
     {
         return match (true) {
@@ -60,7 +80,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
     {
         [$members, $parameters] = [...Parser::parseInnerList($httpValue)];
 
-        return self::from(...$members)
+        return self::fromMembers(...$members)
             ->withParameters(Parameters::fromAssociative($parameters));
     }
 

src/InnerListTest.php

@@ -16,7 +16,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
         $stringItem = Item::from('helloWorld');
         $booleanItem = Item::from(true);
         $arrayParams = [$stringItem, $booleanItem];
-        $instance = InnerList::from(...$arrayParams)
+        $instance = InnerList::fromMembers(...$arrayParams)
             ->withParameters(Parameters::fromAssociative(['test' => Item::from(42)]));
 
         self::assertSame($stringItem, $instance->get(0));
@@ -31,7 +31,7 @@ public function it_can_add_or_remove_members(): void
     {
         $stringItem = Item::from('helloWorld');
         $booleanItem = Item::from(true);
-        $instance = InnerList::from($stringItem, $booleanItem);
+        $instance = InnerList::fromMembers($stringItem, $booleanItem);
 
         self::assertCount(2, $instance);
         self::assertTrue($instance->has(1));
@@ -61,7 +61,7 @@ public function it_can_add_or_remove_members(): void
     #[Test]
     public function it_can_unshift_insert_and_replace(): void
     {
-        $container = InnerList::from()
+        $container = InnerList::fromMembers()
             ->unshift('42')
             ->push(42)
             ->insert(1, 42.0)
@@ -76,7 +76,7 @@ public function it_can_unshift_insert_and_replace(): void
     #[Test]
     public function it_returns_the_same_object_if_nothing_is_changed(): void
     {
-        $container = InnerList::from(42, 'forty-two');
+        $container = InnerList::fromMembers(42, 'forty-two');
 
         $sameContainer = $container
             ->unshift()
@@ -91,21 +91,21 @@ public function it_fails_to_replace_invalid_index(): void
     {
         $this->expectException(InvalidOffset::class);
 
-        InnerList::from()->replace(0, ByteSequence::fromDecoded('Hello World'));
+        InnerList::fromMembers()->replace(0, ByteSequence::fromDecoded('Hello World'));
     }
 
     #[Test]
     public function it_fails_to_insert_at_an_invalid_index(): void
     {
         $this->expectException(InvalidOffset::class);
 
-        InnerList::from()->insert(3, ByteSequence::fromDecoded('Hello World'));
+        InnerList::fromMembers()->insert(3, ByteSequence::fromDecoded('Hello World'));
     }
 
     #[Test]
     public function it_fails_to_return_an_member_with_invalid_index(): void
     {
-        $instance = InnerList::from();
+        $instance = InnerList::fromMembers();
 
         self::assertFalse($instance->has(3));
 
@@ -117,7 +117,7 @@ public function it_fails_to_return_an_member_with_invalid_index(): void
     #[Test]
     public function it_can_access_its_parameter_values(): void
     {
-        $instance = InnerList::from(false)->addParameter('foo', 'bar');
+        $instance = InnerList::fromAssociativeParameters(['foo' => 'bar'], false);
 
         self::assertSame('bar', $instance->parameters()->get('foo')->value());
         self::assertSame('bar', $instance->parameter('foo'));
@@ -128,7 +128,7 @@ public function it_fails_to_access_unknown_parameter_values(): void
     {
         $this->expectException(StructuredFieldError::class);
 
-        InnerList::from(false)->parameters()->get('bar')->value();
+        InnerList::fromMembers(false)->parameters()->get('bar')->value();
     }
 
     #[Test]
@@ -159,29 +159,29 @@ public function it_fails_to_insert_unknown_index_via_the_array_access_interface(
     {
         $this->expectException(StructuredFieldError::class);
 
-        InnerList::from()->insert(0, Item::from(42.0));
+        InnerList::fromMembers()->insert(0, Item::from(42.0));
     }
 
     #[Test]
     public function it_returns_the_same_object_if_no_member_is_removed(): void
     {
-        self::assertCount(0, InnerList::from()->remove(0));
+        self::assertCount(0, InnerList::fromMembers()->remove(0));
     }
 
     #[Test]
     public function it_fails_to_fetch_an_value_using_an_integer(): void
     {
         $this->expectException(InvalidOffset::class);
 
-        InnerList::from()->get('zero');
+        InnerList::fromMembers()->get('zero');
     }
 
     #[Test]
     public function it_can_access_the_item_value(): void
     {
         $token = Token::fromString('token');
         $input = ['foobar', 0, false, $token];
-        $structuredField = InnerList::from(...$input);
+        $structuredField = InnerList::fromMembers(...$input);
 
         self::assertFalse($structuredField->get(2)->value());
         self::assertEquals($token, $structuredField->get(-1)->value());
@@ -190,7 +190,7 @@ public function it_can_access_the_item_value(): void
     #[Test]
     public function it_can_create_via_with_parameters_method_a_new_object(): void
     {
-        $instance1 = InnerList::from(Token::fromString('babayaga'), 'a', true)->addParameter('a', true);
+        $instance1 = InnerList::fromPairParameters([['a', true]], Token::fromString('babayaga'), 'a', true);
         $instance2 = $instance1->withParameters(Parameters::fromAssociative(['a' => true]));
         $instance3 = $instance1->withParameters(Parameters::fromAssociative(['a' => false]));
 
@@ -202,7 +202,7 @@ public function it_can_create_via_with_parameters_method_a_new_object(): void
     #[Test]
     public function it_can_create_via_parameters_access_methods_a_new_object(): void
     {
-        $instance1 = InnerList::from(Token::fromString('babayaga'), 'a', true)->withParameters(Parameters::fromAssociative(['a' => true]));
+        $instance1 = InnerList::fromMembers(Token::fromString('babayaga'), 'a', true)->withParameters(Parameters::fromAssociative(['a' => true]));
         $instance2 = $instance1->appendParameter('a', true);
         $instance7 = $instance1->addParameter('a', true);
         $instance3 = $instance1->prependParameter('a', false);
@@ -224,7 +224,7 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
     #[Test]
     public function it_implements_the_array_access_interface(): void
     {
-        $structuredField = InnerList::from('foobar', 'foobar', 'zero', 0);
+        $structuredField = InnerList::fromMembers('foobar', 'foobar', 'zero', 0);
 
         self::assertInstanceOf(Item::class, $structuredField->get(0));
         self::assertInstanceOf(Item::class, $structuredField[0]);
@@ -237,22 +237,22 @@ public function it_forbids_removing_members_using_the_array_access_interface():
     {
         $this->expectException(LogicException::class);
 
-        unset(InnerList::from('foobar', 'foobar', 'zero', 0)[0]);
+        unset(InnerList::fromMembers('foobar', 'foobar', 'zero', 0)[0]);
     }
 
     #[Test]
     public function it_forbids_adding_members_using_the_array_access_interface(): void
     {
         $this->expectException(LogicException::class);
 
-        InnerList::from('foobar', 'foobar', 'zero', 0)[0] = Item::from(false);
+        InnerList::fromMembers('foobar', 'foobar', 'zero', 0)[0] = Item::from(false);
     }
 
 
     #[Test]
     public function it_can_returns_the_container_member_keys(): void
     {
-        $instance = InnerList::from();
+        $instance = InnerList::fromMembers();
 
         self::assertSame([], $instance->keys());
 
@@ -261,7 +261,7 @@ public function it_can_returns_the_container_member_keys(): void
 
         self::assertSame([0, 1], $newInstance->keys());
 
-        $container = InnerList::from()
+        $container = InnerList::fromMembers()
             ->unshift('42')
             ->push(42)
             ->insert(1, 42.0)

src/OuterList.php

@@ -25,7 +25,7 @@
 final class OuterList implements MemberList
 {
     /** @var list<Value|(MemberList<int, Value>&ParameterAccess)> */
-    private array $members;
+    private readonly array $members;
 
     /**
      * @param Value|(MemberList<int, Value>&ParameterAccess) ...$members
@@ -38,7 +38,7 @@ private function __construct(MemberList|Value ...$members)
     /**
      * @param StructuredField|iterable<Value|DataType>|DataType ...$members
      */
-    public static function from(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
+    public static function fromMembers(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
     {
         return new self(...array_map(self::filterMember(...), $members));
     }
@@ -53,7 +53,7 @@ private static function filterMember(iterable|StructuredField|Token|ByteSequence
         return match (true) {
             ($member instanceof MemberList && $member instanceof ParameterAccess),
             $member instanceof Value => $member,
-            is_iterable($member) => InnerList::from(...$member),
+            is_iterable($member) => InnerList::fromMembers(...$member),
             default => Item::from($member),
         };
     }
@@ -65,8 +65,8 @@ private static function filterMember(iterable|StructuredField|Token|ByteSequence
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        return self::from(...array_map(
-            fn (mixed $value) => is_array($value) ? InnerList::from(...$value[0])->withParameters(Parameters::fromAssociative($value[1])) : $value,
+        return self::fromMembers(...array_map(
+            fn (mixed $value) => is_array($value) ? InnerList::fromMembers(...$value[0])->withParameters(Parameters::fromAssociative($value[1])) : $value,
             Parser::parseList($httpValue)
         ));
     }