Improve public API

Author: nyamsprod

CHANGELOG.md

@@ -6,6 +6,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
+- `Byte` class replace the `ByteSequence` class.
 - `Ietf` enum.
 - methods `fromRFC9651`, `fromRfc8941`, `toRFC9651`, `toRfc8941`, to ease parsing/serializing Structured Fields.
 - method `equals` to allow comparison of Structured Fields values.
@@ -44,6 +45,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `InnerList:remove` replaced by `InnerList:removeByIndices`
 - `::hasNoMember` and `::hasMembers` methods have been replaced by `isEmpty` and `isNotEmpty` on containers
 - `Dictionary::toPairs` and `Parameters::toPairs`
+- `ByteSequence` class replaced by `Byte` class
 
 ## [1.3.0](https://github.com/bakame-php/http-structured-fields/compare/1.2.2...1.3.0) - 2024-01-05
 

docs/03-value-types.md

@@ -73,13 +73,13 @@ PHP default type system, for them, we have defined three classes `Token`,
 `ByteSequence` and `DisplayString` to help with their representation.
 
 ```php
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\DisplayString;
 use Bakame\Http\StructuredFields\Token;
 
 Token::fromString(string|Stringable $value): Token
-ByteSequence::fromDecoded(string|Stringable $value): ByteSequence;
-ByteSequence::fromEncoded(string|Stringable $value): ByteSequence;
+Byte::fromDecoded(string|Stringable $value): ByteSequence;
+Byte::fromEncoded(string|Stringable $value): ByteSequence;
 DisplayString::fromDecoded(string|Stringable $value): DisplayString;
 DisplayString::fromEncoded(string|Stringable $value): DisplayString;
 ```
@@ -89,7 +89,7 @@ instantiated. To access their value, they expose the following API:
 
 ```php
 use Bakame\Http\StructuredFields\Token;
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\DisplayString;
 
 $token = Token::fromString('application/text+xml');
@@ -99,13 +99,13 @@ $displayString = DisplayString::fromDecoded('füü');
 $displayString->decoded(); // returns 'füü'
 $displayString->encoded(); // returns 'f%c3%bc%c3%bc'
 
-$byte = ByteSequence::fromDecoded('Hello world!');
+$byte = Byte::fromDecoded('Hello world!');
 $byte->decoded(); // returns 'Hello world!'
 $byte->encoded(); // returns 'SGVsbG8gd29ybGQh'
 
 $token->equals($byte); // will return false;
 $displayString->equals($byte); // will return false;
-$byte->equals(ByteSequence::fromEncoded('SGVsbG8gd29ybGQh')); // will return true
+$byte->equals(Byte::fromEncoded('SGVsbG8gd29ybGQh')); // will return true
 $displayString->equals(DisplayString::fromEncoded('f%c3%bc%c3%bc')); // will return true
 
 $token->type();         // returns Type::Token

docs/04-item.md

@@ -24,7 +24,7 @@ The `Item` value object exposes the following named constructors to instantiate
 bare items (ie: item without parameters attached to them).
 
 ```php
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 

docs/05-containers.md

@@ -5,7 +5,7 @@ order: 6
 
 # Containers
 
-While building or updating a Bare Item is straightforward, doing the same with the structured field
+While building or updating a Bare Item is straightforward, doing the same with the structured field containers
 requires a bit more logic. In the following sections we will explore how we can access, build and update
 containers.
 
@@ -274,10 +274,10 @@ which takes a single variadic parameter `$members`:
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 
 $list = InnerList::new(
-    ByteSequence::fromDecoded('Hello World'),
+    Byte::fromDecoded('Hello World'),
     42.0,
     42
 );
@@ -300,14 +300,14 @@ $list->removeByIndices(int ...$index): static;
 as shown below
 
 ```php
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\InnerList;
 
 $list = InnerList::new()
     ->unshift('42')
     ->push(42)
     ->insert(1, 42.0)
-    ->replace(0, ByteSequence::fromDecoded('Hello World'));
+    ->replace(0, Byte::fromDecoded('Hello World'));
 
 echo $list->toHttpValue(); //'(:SGVsbG8gV29ybGQ=: 42.0 42)'
 echo $list;                //'(:SGVsbG8gV29ybGQ=: 42.0 42)'
@@ -347,7 +347,7 @@ To ease working with instances that have a `Parameters` object attached to, the
 methods are added:
 
 ```php
-use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\InnerList;
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;

src/ByteSequence.php renamed to src/Byte.php

@@ -14,7 +14,7 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.3.5
  */
-final class ByteSequence
+final class Byte
 {
     private function __construct(
         private readonly string $value

src/Dictionary.php

@@ -12,6 +12,7 @@
 use Iterator;
 use IteratorAggregate;
 use Stringable;
+use Throwable;
 
 use function array_key_exists;
 use function array_keys;
@@ -80,7 +81,7 @@ public static function new(): self
     /**
      * Returns a new instance from an associative iterable construct.
      *
-     * its keys represent the dictionary entry key
+     * its keys represent the dictionary entry name
      * its values represent the dictionary entry value
      *
      * @param StructuredFieldProvider|iterable<string, InnerList|Item|SfMemberInput> $members
@@ -102,12 +103,12 @@ public static function fromAssociative(StructuredFieldProvider|iterable $members
      * Returns a new instance from a pair iterable construct.
      *
      * Each member is composed of an array with two elements
-     * the first member represents the instance entry key
+     * the first member represents the instance entry name
      * the second member represents the instance entry value
      *
      * @param StructuredFieldProvider|Dictionary|Parameters|iterable<array{0:string, 1?:InnerList|Item|SfMemberInput}> $pairs
      */
-    public static function fromPairs(StructuredFieldProvider|iterable $pairs): self
+    public static function fromPairs(StructuredFieldProvider|Dictionary|Parameters|iterable $pairs): self
     {
         if ($pairs instanceof StructuredFieldProvider) {
             $pairs = $pairs->toStructuredField();
@@ -163,7 +164,7 @@ public static function fromPairs(StructuredFieldProvider|iterable $pairs): self
      *
      * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.2
      *
-     * @throws SyntaxError If the string is not a valid
+     * @throws StructuredFieldError|Throwable
      */
     public static function fromRfc9651(Stringable|string $httpValue): self
     {
@@ -175,7 +176,7 @@ public static function fromRfc9651(Stringable|string $httpValue): self
      *
      * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
      *
-     * @throws SyntaxError If the string is not a valid
+     * @throws StructuredFieldError|Throwable
      */
     public static function fromRfc8941(Stringable|string $httpValue): self
     {
@@ -187,7 +188,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
      *
      * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.2
      *
-     * @throws SyntaxError If the string is not a valid
+     * @throws StructuredFieldError|Throwable If the string is not a valid
      */
     public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
     {
@@ -380,7 +381,7 @@ private function filterIndex(int $index, int|null $max = null): int|null
     }
 
     /**
-     * Returns the item or the inner-list and its key as attached to the given
+     * Returns the item or the inner-list and its name as attached to the given
      * collection according to their index position otherwise throw.
      *
      * @param ?callable(Item|InnerList, string): (bool|string) $validate
@@ -418,7 +419,7 @@ public function getByIndex(int $index, ?callable $validate = null): array
     }
 
     /**
-     * Returns the key associated with the given index or null otherwise.
+     * Returns the name associated with the given index or null otherwise.
      */
     public function indexByName(string $name): ?int
     {
@@ -451,7 +452,7 @@ public function nameByIndex(int $index): ?string
     }
 
     /**
-     * Returns the first member whether it is an item or an inner-list and its key as attached to the given
+     * Returns the first member whether it is an item or an inner-list and its name as attached to the given
      * collection according to their index position otherwise returns an empty array.
      *
      * @return array{0:string, 1:InnerList|Item}|array{}
@@ -460,13 +461,13 @@ public function first(): array
     {
         try {
             return $this->getByIndex(0);
-        } catch (InvalidOffset) {
+        } catch (StructuredFieldError) {
             return [];
         }
     }
 
     /**
-     * Returns the first member whether it is an item or an inner-list and its key as attached to the given
+     * Returns the first member whether it is an item or an inner-list and its name as attached to the given
      * collection according to their index position otherwise returns an empty array.
      *
      * @return array{0:string, 1:InnerList|Item}|array{}
@@ -475,24 +476,24 @@ public function last(): array
     {
         try {
             return $this->getByIndex(-1);
-        } catch (InvalidOffset) {
+        } catch (StructuredFieldError) {
             return [];
         }
     }
 
     /**
-     * Adds a member at the end of the instance otherwise updates the value associated with the key if already present.
+     * Adds a member at the end of the instance otherwise updates the value associated with the name if already present.
      *
      * This method MUST retain the state of the current instance, and return
      * an instance that contains the specified changes.
      *
      * @param InnerList|Item|SfMemberInput|null $member
      *
-     * @throws SyntaxError If the string key is not a valid
+     * @throws SyntaxError If the string name is not a valid
      */
     public function add(
         string $name,
-        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|ByteSequence|DisplayString|DateTimeInterface|string|int|float|bool|null $member
+        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|Byte|DisplayString|DateTimeInterface|string|int|float|bool|null $member
     ): self {
         if (null === $member) {
             return $this;
@@ -561,7 +562,7 @@ public function removeByIndices(int ...$indices): self
     }
 
     /**
-     * Deletes members associated with the list using the member key.
+     * Deletes members associated with the list using the member name.
      *
      * This method MUST retain the state of the current instance, and return
      * an instance that contains the specified changes.
@@ -572,17 +573,17 @@ public function removeByNames(string ...$names): self
     }
 
     /**
-     * Adds a member at the end of the instance and deletes any previous reference to the key if present.
+     * Adds a member at the end of the instance and deletes any previous reference to the name if present.
      *
      * This method MUST retain the state of the current instance, and return
      * an instance that contains the specified changes.
      *
      * @param InnerList|Item|SfMemberInput|null $member
-     * @throws SyntaxError If the string key is not a valid
+     * @throws SyntaxError If the string name is not a valid
      */
     public function append(
         string $name,
-        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|ByteSequence|DisplayString|DateTimeInterface|string|int|float|bool|null $member
+        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|Byte|DisplayString|DateTimeInterface|string|int|float|bool|null $member
     ): self {
         if (null === $member) {
             return $this;
@@ -594,18 +595,18 @@ public function append(
     }
 
     /**
-     * Adds a member at the beginning of the instance and deletes any previous reference to the key if present.
+     * Adds a member at the beginning of the instance and deletes any previous reference to the name if present.
      *
      * This method MUST retain the state of the current instance, and return
      * an instance that contains the specified changes.
      *
      * @param InnerList|Item|SfMemberInput|null $member
      *
-     * @throws SyntaxError If the string key is not a valid
+     * @throws SyntaxError If the string name is not a valid
      */
     public function prepend(
         string $name,
-        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|ByteSequence|DisplayString|DateTimeInterface|string|int|float|bool|null $member
+        iterable|StructuredFieldProvider|OuterList|Dictionary|InnerList|Parameters|Item|Token|Byte|DisplayString|DateTimeInterface|string|int|float|bool|null $member
     ): self {
         if (null === $member) {
             return $this;
@@ -763,6 +764,8 @@ public function offsetExists(mixed $offset): bool
 
     /**
      * @param string $offset
+     *
+     * @throws StructuredFieldError
      */
     public function offsetGet(mixed $offset): InnerList|Item
     {
@@ -790,7 +793,7 @@ public function offsetSet(mixed $offset, mixed $value): void
      */
     public function map(callable $callback): Iterator
     {
-        foreach ($this->getIterator() as $offset => $member) {
+        foreach ($this as $offset => $member) {
             yield ($callback)($member, $offset);
         }
     }
@@ -805,7 +808,7 @@ public function map(callable $callback): Iterator
      */
     public function reduce(callable $callback, mixed $initial = null): mixed
     {
-        foreach ($this->getIterator() as $offset => $pair) {
+        foreach ($this as $offset => $pair) {
             $initial = $callback($initial, $pair, $offset);
         }
 
@@ -819,7 +822,7 @@ public function reduce(callable $callback, mixed $initial = null): mixed
      */
     public function filter(callable $callback): self
     {
-        return self::fromPairs(new CallbackFilterIterator($this->getIterator(), $callback));
+        return self::fromPairs(new CallbackFilterIterator($this, $callback));
     }
 
     /**
@@ -829,7 +832,7 @@ public function filter(callable $callback): self
      */
     public function sort(callable $callback): self
     {
-        $members = iterator_to_array($this->getIterator());
+        $members = iterator_to_array($this);
         usort($members, $callback);
 
         return self::fromPairs($members);

src/Ietf.php

@@ -22,18 +22,20 @@ public function uri(): string
 
     public function publishedAt(): DateTimeImmutable
     {
-        return match ($this) {
-            self::Rfc9651 => new DateTimeImmutable('2024-09-01', new DateTimeZone('UTC')),
-            self::Rfc8941 => new DateTimeImmutable('2021-02-01', new DateTimeZone('UTC')),
-        };
+        return new DateTimeImmutable(match ($this) {
+            self::Rfc9651 => '2024-09-01',
+            self::Rfc8941 => '2021-02-01',
+        }, new DateTimeZone('UTC'));
+    }
+
+    public function isActive(): bool
+    {
+        return self::Rfc9651 === $this;
     }
 
     public function isObsolete(): bool
     {
-        return match ($this) {
-            self::Rfc9651 => false,
-            default => true,
-        };
+        return !$this->isActive();
     }
 
     public function supports(mixed $value): bool