Improve public API

Author: nyamsprod

docs/03-value-types.md

@@ -17,7 +17,7 @@ or provides a class based alternative. The table below summarizes the value type
 | String        | `string`                  | `Type::String`        | `string`           | RFC8941          |
 | Boolean       | `bool`                    | `Type::Boolean`       | `boolean`          | RFC8941          |
 | Token         | class `Token`             | `Type::Token`         | `token`            | RFC8941          |
-| Byte Sequence | class `ByteSequence`      | `Type::ByteSequence`  | `binary`           | RFC8941          |
+| Byte Sequence | class `Byte`              | `Type::Byte`          | `binary`           | RFC8941          |
 | Date          | class `DateTimeImmutable` | `Type::Date`          | `date`             | RFC9651          |
 | DisplayString | class `DisplayString`     | `Type::DisplayString` | `displaystring`    | RFC9651          |
 
@@ -70,16 +70,16 @@ Type::fromVariable(42)->isOneOf(Type::Token, Type::Integer); //return true
 
 The RFC defines three (3) specific data types that can not be represented by
 PHP default type system, for them, we have defined three classes `Token`,
-`ByteSequence` and `DisplayString` to help with their representation.
+`Byte` and `DisplayString` to help with their representation.
 
 ```php
 use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\DisplayString;
 use Bakame\Http\StructuredFields\Token;
 
 Token::fromString(string|Stringable $value): Token
-Byte::fromDecoded(string|Stringable $value): ByteSequence;
-Byte::fromEncoded(string|Stringable $value): ByteSequence;
+Byte::fromDecoded(string|Stringable $value): Byte;
+Byte::fromEncoded(string|Stringable $value): Byte;
 DisplayString::fromDecoded(string|Stringable $value): DisplayString;
 DisplayString::fromEncoded(string|Stringable $value): DisplayString;
 ```
@@ -109,7 +109,7 @@ $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
-$byte->type();          // returns Type::ByteSequence
+$byte->type();          // returns Type::Byte
 $displayString->type(); // returns Type::DisplayString
 ```
 

docs/04-item.md

@@ -28,7 +28,7 @@ use Bakame\Http\StructuredFields\Byte;
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 
-Item:new(DateTimeInterface|ByteSequence|Token|DisplayString|string|int|array|float|bool $value): self
+Item:new(DateTimeInterface|Byte|Token|DisplayString|string|int|array|float|bool $value): self
 Item:tryNew(mixed $value): ?self
 Item::fromDecodedByteSequence(Stringable|string $value): self;
 Item::fromEncodedDisplayString(Stringable|string $value): self;
@@ -51,7 +51,7 @@ To update the `Item` instance value, use the `withValue` method:
 ```php
 use Bakame\Http\StructuredFields\Item;
 
-Item::withValue(DateTimeInterface|ByteSequence|Token|DisplayString|string|int|float|bool $value): static
+Item::withValue(DateTimeInterface|Byte|Token|DisplayString|string|int|float|bool $value): static
 ```
 
 ## Item Parameters

docs/05-containers.md

@@ -352,7 +352,7 @@ use Bakame\Http\StructuredFields\InnerList;
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 
-//@type SfItemInput ByteSequence|Token|DateTimeInterface|string|int|float|bool
+//@type SfItemInput Byte|Token|DateTimeInterface|string|int|float|bool
 
 Item::fromAssociative(SfItemInput $value, Parameters|iterable<string, SfItemInput> $parameters): self;
 Item::fromPair(array{0:SfItemInput, 1:Parameters|iterable<array{0:string, 1:SfItemInput}>} $pair): self;

docs/06-validation.md

@@ -133,7 +133,7 @@ $value = $member
 
 > [!NOTE]
 > we used `mixed` as parameter type for convenience but the effective parameter type should be
-> `ByteSequence|Token|DisplayString|DateTimeImmutable|string|int|float|bool`
+> `Byte|Token|DisplayString|DateTimeImmutable|string|int|float|bool`
 
 ### Validating the Item parameters.
 

docs/07-extensions.md

@@ -12,7 +12,7 @@ which expects a string or a stringable object when adding or updating
 HTTP field values.
 
 ```php
-$container = InnerList::new(ByteSequence::fromDecoded('Hello World'), 42.0, 42);
+$container = InnerList::new(Byte::fromDecoded('Hello World'), 42.0, 42);
 
 $container->toHttpValue(); // returns '(:SGVsbG8gV29ybGQ=: 42.0 42)'
 echo $container;           // returns '(:SGVsbG8gV29ybGQ=: 42.0 42)' 

src/Dictionary.php

@@ -433,7 +433,7 @@ public function indexByName(string $name): ?int
     }
 
     /**
-     * Returns the index associated with the given key or null otherwise.
+     * Returns the index associated with the given name or null otherwise.
      */
     public function nameByIndex(int $index): ?string
     {

src/Validation/ParametersValidator.php

@@ -14,7 +14,7 @@
  *
  * @phpstan-import-type SfType from StructuredFieldProvider
  *
- * @phpstan-type SfParameterKeyRule array{validate?:callable(SfType): (bool|string), required?:bool|string, default?:SfType|null}
+ * @phpstan-type SfParameterNameRule array{validate?:callable(SfType): (bool|string), required?:bool|string, default?:SfType|null}
  * @phpstan-type SfParameterIndexRule array{validate?:callable(SfType, string): (bool|string), required?:bool|string, default?:array{0:string, 1:SfType}|array{}}
  */
 final class ParametersValidator
@@ -25,12 +25,12 @@ final class ParametersValidator
     /** @var ?callable(Parameters): (string|bool) */
     private mixed $criteria;
     private int $type;
-    /** @var array<string, SfParameterKeyRule>|array<int, SfParameterIndexRule> */
+    /** @var array<string, SfParameterNameRule>|array<int, SfParameterIndexRule> */
     private array $filterConstraints;
 
     /**
      * @param ?callable(Parameters): (string|bool) $criteria
-     * @param array<string, SfParameterKeyRule>|array<int, SfParameterIndexRule> $filterConstraints
+     * @param array<string, SfParameterNameRule>|array<int, SfParameterIndexRule> $filterConstraints
      */
     private function __construct(
         ?callable $criteria = null,
@@ -65,9 +65,9 @@ public function filterByCriteria(?callable $criteria, int $type = self::USE_KEYS
      * On success populate the result item property
      * On failure populates the result errors property
      *
-     * @param array<string, SfParameterKeyRule> $constraints
+     * @param array<string, SfParameterNameRule> $constraints
      */
-    public function filterByKeys(array $constraints): self
+    public function filterByNames(array $constraints): self
     {
         return new self($this->criteria, self::USE_KEYS, $constraints);
     }
@@ -175,7 +175,7 @@ private function validateByNames(Parameters $parameters): Result /* @phpstan-ign
         $violations = new ViolationList();
         /**
          * @var string $name
-         * @var SfParameterKeyRule $rule
+         * @var SfParameterNameRule $rule
          */
         foreach ($this->filterConstraints as $name => $rule) {
             try {

tests/Validation/ItemValidatorTest.php

@@ -107,7 +107,7 @@ public function it_will_fail_validating_parameters_by_keys(): void
     {
         $parametersValidator = ParametersValidator::new()
             ->filterByCriteria(fn (Parameters $parameters) => $parameters->allowedNames(['foo', 'bar']), ParametersValidator::USE_INDICES)
-            ->filterByKeys([
+            ->filterByNames([
                 'foo' => ['validate' => fn (mixed $value): bool => false],
                 'bar' => ['validate' => fn (mixed $value): bool => true],
             ]);