feat: handle interface constructor registration

By default, the mapper cannot instantiate an interface, as it does not
know which implementation to use. To do so, the `MapperBuilder::infer()`
method can be used, but it is cumbersome in most cases.

It is now also possible to register a constructor for an interface, in
the same way as for a class.

Because the mapper cannot automatically guess which implementation can
be used for an interface, it is not possible to use the `Constructor`
attribute, the `MapperBuilder::registerConstructor()` method must be
used instead.

In the example below, the mapper is taught how to instantiate an
implementation of `UuidInterface` from package `ramsey/uuid`:

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->registerConstructor(
        // The static method below has return type `UuidInterface`;
        // therefore, the mapper will build an instance of `Uuid` when
        // it needs to instantiate an implementation of `UuidInterface`.
        Ramsey\Uuid\Uuid::fromString(...)
    )
    ->mapper()
    ->map(
        Ramsey\Uuid\UuidInterface::class,
        '663bafbf-c3b5-4336-b27f-1796be8554e0'
    );
```

docs/pages/how-to/infer-interfaces.md

@@ -1,8 +1,10 @@
 # Inferring interfaces
 
 When the mapper meets an interface, it needs to understand which implementation
-(a class that implements this interface) will be used — this information must be
-provided in the mapper builder, using the method `infer()`.
+will be used. This can be done by [registering a constructor for the interface],
+but it can have limitations. A more powerful way to handle this is to infer the
+implementation based on the data provided to the mapper. This can be done using
+the `infer()` method.
 
 The callback given to this method must return the name of a class that
 implements the interface. Any arguments can be required by the callback; they
@@ -124,3 +126,5 @@ assert($result->foo === 'foo');
 assert($result->bar === 'bar');
 assert($result->baz === 'baz');
 ```
+
+[registering a constructor for the interface]: use-custom-object-constructors.md#interface-implementation-constructor

docs/pages/how-to/use-custom-object-constructors.md

@@ -130,6 +130,37 @@ final class Color
 }
 ```
 
+## Interface implementation constructor
+
+By default, the mapper cannot instantiate an interface, as it does not know
+which implementation to use. To do so, it is possible to register a constructor
+for an interface, in the same way as for a class.
+
+!!! note
+
+    Because the mapper cannot automatically guess which implementation can be
+    used for an interface, it is not possible to use the `Constructor`
+    attribute, the `MapperBuilder::registerConstructor()` method must be used
+    instead.
+
+In the example below, the mapper is taught how to instantiate an implementation
+of `UuidInterface` from package [`ramsey/uuid`](https://github.com/ramsey/uuid):
+
+```php
+(new \CuyZ\Valinor\MapperBuilder())
+    ->registerConstructor(
+        // The static method below has return type `UuidInterface`; therefore,
+        // the mapper will build an instance of `Uuid` when it needs to 
+        // instantiate an implementation of `UuidInterface`.
+        Ramsey\Uuid\Uuid::fromString(...)
+    )
+    ->mapper()
+    ->map(
+        Ramsey\Uuid\UuidInterface::class,
+        '663bafbf-c3b5-4336-b27f-1796be8554e0'
+    );
+```
+
 ## Custom enum constructor
 
 Registering a constructor for an enum works the same way as for a class, as

src/Definition/ClassDefinition.php

@@ -4,15 +4,15 @@
 
 namespace CuyZ\Valinor\Definition;
 
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 
 /** @internal */
 final class ClassDefinition
 {
     public function __construct(
         /** @var class-string */
         public readonly string $name,
-        public readonly ClassType $type,
+        public readonly ObjectType $type,
         public readonly Attributes $attributes,
         public readonly Properties $properties,
         public readonly Methods $methods,

src/Definition/Exception/InvalidTypeAliasImportClass.php

@@ -4,13 +4,13 @@
 
 namespace CuyZ\Valinor\Definition\Exception;
 
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use LogicException;
 
 /** @internal */
 final class InvalidTypeAliasImportClass extends LogicException
 {
-    public function __construct(ClassType $type, string $className)
+    public function __construct(ObjectType $type, string $className)
     {
         parent::__construct(
             "Cannot import a type alias from unknown class `$className` in class `{$type->className()}`.",

src/Definition/Exception/InvalidTypeAliasImportClassType.php

@@ -4,14 +4,14 @@
 
 namespace CuyZ\Valinor\Definition\Exception;
 
+use CuyZ\Valinor\Type\ObjectType;
 use CuyZ\Valinor\Type\Type;
-use CuyZ\Valinor\Type\ClassType;
 use LogicException;
 
 /** @internal */
 final class InvalidTypeAliasImportClassType extends LogicException
 {
-    public function __construct(ClassType $classType, Type $type)
+    public function __construct(ObjectType $classType, Type $type)
     {
         parent::__construct(
             "Importing a type alias can only be done with classes, `{$type->toString()}` was given in class `{$classType->className()}`.",

src/Definition/Exception/UnknownTypeAliasImport.php

@@ -4,7 +4,7 @@
 
 namespace CuyZ\Valinor\Definition\Exception;
 
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use LogicException;
 
 /** @internal */
@@ -13,7 +13,7 @@ final class UnknownTypeAliasImport extends LogicException
     /**
      * @param class-string $importClassName
      */
-    public function __construct(ClassType $type, string $importClassName, string $alias)
+    public function __construct(ObjectType $type, string $importClassName, string $alias)
     {
         parent::__construct(
             "Type alias `$alias` imported in `{$type->className()}` could not be found in `$importClassName`",

src/Definition/Repository/Cache/CacheClassDefinitionRepository.php

@@ -6,7 +6,7 @@
 
 use CuyZ\Valinor\Definition\ClassDefinition;
 use CuyZ\Valinor\Definition\Repository\ClassDefinitionRepository;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use Psr\SimpleCache\CacheInterface;
 
 use function sha1;
@@ -20,7 +20,7 @@ public function __construct(
         private CacheInterface $cache
     ) {}
 
-    public function for(ClassType $type): ClassDefinition
+    public function for(ObjectType $type): ClassDefinition
     {
         // @infection-ignore-all
         $key = 'class-definition' . sha1($type->toString());

src/Definition/Repository/ClassDefinitionRepository.php

@@ -5,10 +5,10 @@
 namespace CuyZ\Valinor\Definition\Repository;
 
 use CuyZ\Valinor\Definition\ClassDefinition;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 
 /** @internal */
 interface ClassDefinitionRepository
 {
-    public function for(ClassType $type): ClassDefinition;
+    public function for(ObjectType $type): ClassDefinition;
 }

src/Definition/Repository/Reflection/ReflectionClassDefinitionRepository.php

@@ -21,7 +21,6 @@
 use CuyZ\Valinor\Definition\PropertyDefinition;
 use CuyZ\Valinor\Definition\Repository\AttributesRepository;
 use CuyZ\Valinor\Definition\Repository\ClassDefinitionRepository;
-use CuyZ\Valinor\Type\ClassType;
 use CuyZ\Valinor\Type\GenericType;
 use CuyZ\Valinor\Type\ObjectType;
 use CuyZ\Valinor\Type\Parser\Exception\InvalidType;
@@ -67,7 +66,7 @@ public function __construct(TypeParserFactory $typeParserFactory)
         $this->methodBuilder = new ReflectionMethodDefinitionBuilder($this->attributesRepository);
     }
 
-    public function for(ClassType $type): ClassDefinition
+    public function for(ObjectType $type): ClassDefinition
     {
         $reflection = Reflection::class($type->className());
 
@@ -97,7 +96,7 @@ private function attributes(ReflectionClass $reflection): array
     /**
      * @return list<PropertyDefinition>
      */
-    private function properties(ClassType $type): array
+    private function properties(ObjectType $type): array
     {
         return array_map(
             function (ReflectionProperty $property) use ($type) {
@@ -112,7 +111,7 @@ function (ReflectionProperty $property) use ($type) {
     /**
      * @return list<MethodDefinition>
      */
-    private function methods(ClassType $type): array
+    private function methods(ObjectType $type): array
     {
         $reflection = Reflection::class($type->className());
         $methods = $reflection->getMethods();
@@ -134,7 +133,7 @@ private function methods(ClassType $type): array
     /**
      * @param ReflectionClass<object> $target
      */
-    private function typeResolver(ClassType $type, ReflectionClass $target): ReflectionTypeResolver
+    private function typeResolver(ObjectType $type, ReflectionClass $target): ReflectionTypeResolver
     {
         $typeKey = $target->isInterface()
             ? "{$type->toString()}/{$type->className()}"
@@ -209,7 +208,7 @@ private function localTypeAliases(ObjectType $type): array
     /**
      * @return array<string, Type>
      */
-    private function importedTypeAliases(ClassType $type): array
+    private function importedTypeAliases(ObjectType $type): array
     {
         $reflection = Reflection::class($type->className());
         $importedTypesRaw = DocParser::importedTypeAliases($reflection);
@@ -258,7 +257,7 @@ private function typeParser(ObjectType $type): TypeParser
         return $this->typeParserFactory->get(...$specs);
     }
 
-    private function parentType(ClassType $type): NativeClassType
+    private function parentType(ObjectType $type): NativeClassType
     {
         $reflection = Reflection::class($type->className());
 

src/Library/Container.php

@@ -37,7 +37,7 @@
 use CuyZ\Valinor\Mapper\Tree\Builder\NodeBuilder;
 use CuyZ\Valinor\Mapper\Tree\Builder\NullNodeBuilder;
 use CuyZ\Valinor\Mapper\Tree\Builder\ObjectImplementations;
-use CuyZ\Valinor\Mapper\Tree\Builder\ObjectNodeBuilder;
+use CuyZ\Valinor\Mapper\Tree\Builder\FilteredObjectNodeBuilder;
 use CuyZ\Valinor\Mapper\Tree\Builder\RootNodeBuilder;
 use CuyZ\Valinor\Mapper\Tree\Builder\ScalarNodeBuilder;
 use CuyZ\Valinor\Mapper\Tree\Builder\ShapedArrayNodeBuilder;
@@ -54,7 +54,7 @@
 use CuyZ\Valinor\Normalizer\Transformer\KeyTransformersHandler;
 use CuyZ\Valinor\Normalizer\Transformer\RecursiveTransformer;
 use CuyZ\Valinor\Normalizer\Transformer\ValueTransformersHandler;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use CuyZ\Valinor\Type\Parser\Factory\LexingTypeParserFactory;
 use CuyZ\Valinor\Type\Parser\Factory\TypeParserFactory;
 use CuyZ\Valinor\Type\Parser\TypeParser;
@@ -111,10 +111,10 @@ public function __construct(Settings $settings)
                     ShapedArrayType::class => new ShapedArrayNodeBuilder($settings->allowSuperfluousKeys),
                     ScalarType::class => new ScalarNodeBuilder($settings->enableFlexibleCasting),
                     NullType::class => new NullNodeBuilder(),
-                    ClassType::class => new NativeClassNodeBuilder(
+                    ObjectType::class => new NativeClassNodeBuilder(
                         $this->get(ClassDefinitionRepository::class),
                         $this->get(ObjectBuilderFactory::class),
-                        $this->get(ObjectNodeBuilder::class),
+                        $this->get(FilteredObjectNodeBuilder::class),
                         $settings->enableFlexibleCasting,
                     ),
                 ]);
@@ -126,7 +126,11 @@ public function __construct(Settings $settings)
                     $this->get(ObjectImplementations::class),
                     $this->get(ClassDefinitionRepository::class),
                     $this->get(ObjectBuilderFactory::class),
-                    $this->get(ObjectNodeBuilder::class),
+                    $this->get(FilteredObjectNodeBuilder::class),
+                    new FunctionsContainer(
+                        $this->get(FunctionDefinitionRepository::class),
+                        $settings->customConstructors
+                    ),
                     $settings->enableFlexibleCasting,
                     $settings->allowSuperfluousKeys,
                 );
@@ -149,7 +153,7 @@ public function __construct(Settings $settings)
                 return new ErrorCatcherNodeBuilder($builder, $settings->exceptionFilter);
             },
 
-            ObjectNodeBuilder::class => fn () => new ObjectNodeBuilder($settings->allowSuperfluousKeys),
+            FilteredObjectNodeBuilder::class => fn () => new FilteredObjectNodeBuilder($settings->allowSuperfluousKeys),
 
             ObjectImplementations::class => fn () => new ObjectImplementations(
                 new FunctionsContainer(

src/Mapper/Object/Factory/ConstructorObjectBuilderFactory.php

@@ -131,7 +131,7 @@ private function builders(ClassDefinition $class): array
         return array_values($builders);
     }
 
-    private function constructorMatches(FunctionObject $function, ClassType $classType): bool
+    private function constructorMatches(FunctionObject $function, ObjectType $classType): bool
     {
         $definition = $function->definition;
 

src/Mapper/Object/Factory/DateTimeObjectBuilderFactory.php

@@ -12,7 +12,7 @@
 use CuyZ\Valinor\Mapper\Object\FunctionObjectBuilder;
 use CuyZ\Valinor\Mapper\Object\NativeConstructorObjectBuilder;
 use CuyZ\Valinor\Mapper\Object\ObjectBuilder;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use DateTime;
 use DateTimeImmutable;
 
@@ -51,7 +51,7 @@ public function for(ClassDefinition $class): array
         return $builders;
     }
 
-    private function internalDateTimeBuilder(ClassType $type): FunctionObjectBuilder
+    private function internalDateTimeBuilder(ObjectType $type): FunctionObjectBuilder
     {
         $constructor = new DateTimeFormatConstructor(...$this->supportedDateFormats);
         $function = new FunctionObject($this->functionDefinitionRepository->for($constructor), $constructor);

src/Mapper/Object/Factory/DateTimeZoneObjectBuilderFactory.php

@@ -11,7 +11,7 @@
 use CuyZ\Valinor\Mapper\Object\NativeConstructorObjectBuilder;
 use CuyZ\Valinor\Mapper\Object\ObjectBuilder;
 use CuyZ\Valinor\Mapper\Tree\Message\MessageBuilder;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use DateTimeZone;
 use Exception;
 
@@ -60,7 +60,7 @@ public function for(ClassDefinition $class): array
         return $builders;
     }
 
-    private function defaultBuilder(ClassType $type): FunctionObjectBuilder
+    private function defaultBuilder(ObjectType $type): FunctionObjectBuilder
     {
         $constructor = function (string $timezone) {
             try {

src/Mapper/Object/FunctionObjectBuilder.php

@@ -7,7 +7,7 @@
 use CuyZ\Valinor\Definition\FunctionObject;
 use CuyZ\Valinor\Definition\ParameterDefinition;
 use CuyZ\Valinor\Mapper\Tree\Message\UserlandError;
-use CuyZ\Valinor\Type\ClassType;
+use CuyZ\Valinor\Type\ObjectType;
 use Exception;
 
 use function array_map;
@@ -24,7 +24,7 @@ final class FunctionObjectBuilder implements ObjectBuilder
 
     private bool $isDynamicConstructor;
 
-    public function __construct(FunctionObject $function, ClassType $type)
+    public function __construct(FunctionObject $function, ObjectType $type)
     {
         $definition = $function->definition;
 

src/Mapper/Tree/Builder/ObjectNodeBuilder.php → src/Mapper/Tree/Builder/FilteredObjectNodeBuilder.php

@@ -12,7 +12,7 @@
 use function count;
 
 /** @internal */
-final class ObjectNodeBuilder
+final class FilteredObjectNodeBuilder
 {
     public function __construct(private bool $allowSuperfluousKeys) {}