Add support for Psl\Type\nullish() in shape types

Nullish wraps a type as T|null while keeping the key required,
unlike optional() which makes the key absent. Supports both
standalone nullish(T) and combined optional(nullish(T)).

Author: veewee

extension.neon

@@ -1,6 +1,8 @@
 parameters:
 	stubFiles:
 		- stubs/Option.stub
+		- stubs/nullish.stub
+		- stubs/NullishType.stub
 		- stubs/optional.stub
 		- stubs/OptionalType.stub
 		- stubs/Type.stub

src/Type/TypeShapeReturnTypeExtension.php

@@ -12,6 +12,7 @@
 use PHPStan\Type\Generic\GenericObjectType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
+use Psl\Type\Internal\NullishType;
 use Psl\Type\Internal\OptionalType;
 use Psl\Type\TypeInterface;
 use function count;
@@ -55,14 +56,29 @@ private function createResult(ConstantArrayType $arrayType): Type
 		$builder = ConstantArrayTypeBuilder::createEmpty();
 		foreach ($arrayType->getKeyTypes() as $key) {
 			$valueType = $arrayType->getOffsetValueType($key);
-			[$type, $optional] = $this->extractOptional($valueType->getTemplateType(TypeInterface::class, 'T'));
+			$templateType = $valueType->getTemplateType(TypeInterface::class, 'T');
+			[$type, $optional] = $this->extractOptional($templateType);
+			[$type] = $this->extractNullish($type);
 
 			$builder->setOffsetValueType($key, $type, $optional);
 		}
 
 		return $builder->getArray();
 	}
 
+	/**
+	 * @return array{Type, bool}
+	 */
+	private function extractNullish(Type $type): array
+	{
+		$nullishType = $type->getTemplateType(NullishType::class, 'T');
+		if ($nullishType instanceof ErrorType) {
+			return [$type, false];
+		}
+
+		return [TypeCombinator::addNull($nullishType), false];
+	}
+
 	/**
 	 * @return array{Type, bool}
 	 */

stubs/NullishType.stub

@@ -0,0 +1,17 @@
+<?php
+
+namespace Psl\Type\Internal;
+
+use Psl\Type;
+
+/**
+ * @template T
+ *
+ * @extends Type\Type<T>
+ *
+ * @internal
+ */
+final class NullishType extends Type\Type
+{
+
+}

stubs/nullish.stub

@@ -0,0 +1,17 @@
+<?php
+
+namespace Psl\Type;
+
+use Psl\Type\Internal\NullishType;
+
+/**
+ * @template T
+ *
+ * @param TypeInterface<T> $inner_type
+ *
+ * @return TypeInterface<NullishType<T>>
+ */
+function nullish(TypeInterface $inner_type): TypeInterface
+{
+
+}

tests/Type/data/assert.php

@@ -29,6 +29,37 @@ public function assertShape(array $a): void
 		assertType('array{name: string, age: int, location?: array{city: string, state: string, country: string}}', $b);
 	}
 
+	/**
+	 * @param array<mixed> $a
+	 */
+	public function assertNullishShape(array $a): void
+	{
+		$specification = Type\shape([
+			'name' => Type\string(),
+			'bio' => Type\nullish(Type\string()),
+		]);
+
+		$b = $specification->assert($a);
+
+		assertType('array{name: string, bio: string|null}', $a);
+		assertType('array{name: string, bio: string|null}', $b);
+	}
+
+	/**
+	 * @param array<mixed> $a
+	 */
+	public function assertOptionalNullishShape(array $a): void
+	{
+		$specification = Type\shape([
+			'bio' => Type\optional(Type\nullish(Type\string())),
+		]);
+
+		$b = $specification->assert($a);
+
+		assertType('array{bio?: string|null}', $a);
+		assertType('array{bio?: string|null}', $b);
+	}
+
 	public function assertInt($i): void
 	{
 		$spec = Type\int();

tests/Type/data/coerce.php

@@ -29,6 +29,35 @@ public function coerceShape(array $input): void
         assertType('array<mixed>', $input);
     }
 
+    /**
+     * @param array<mixed> $input
+     */
+    public function coerceNullishShape(array $input): void
+    {
+        $specification = Type\shape([
+            'name' => Type\string(),
+            'bio' => Type\nullish(Type\string()),
+        ]);
+
+        $output = $specification->coerce($input);
+
+        assertType('array{name: string, bio: string|null}', $output);
+    }
+
+    /**
+     * @param array<mixed> $input
+     */
+    public function coerceOptionalNullishShape(array $input): void
+    {
+        $specification = Type\shape([
+            'bio' => Type\optional(Type\nullish(Type\string())),
+        ]);
+
+        $output = $specification->coerce($input);
+
+        assertType('array{bio?: string|null}', $output);
+    }
+
 	public function coerceInt($i): void
 	{
 		$spec = Type\int();

tests/Type/data/matches.php

@@ -30,6 +30,39 @@ public function matchesShape(array $a): void
 		}
 	}
 
+	/**
+	 * @param array<mixed> $a
+	 */
+	public function matchesNullishShape(array $a): void
+	{
+		$specification = Type\shape([
+			'name' => Type\string(),
+			'bio' => Type\nullish(Type\string()),
+		]);
+
+		if ($specification->matches($a)) {
+			assertType('array{name: string, bio: string|null}', $a);
+		} else {
+			assertType('array<mixed>', $a);
+		}
+	}
+
+	/**
+	 * @param array<mixed> $a
+	 */
+	public function matchesOptionalNullishShape(array $a): void
+	{
+		$specification = Type\shape([
+			'bio' => Type\optional(Type\nullish(Type\string())),
+		]);
+
+		if ($specification->matches($a)) {
+			assertType('array{bio?: string|null}', $a);
+		} else {
+			assertType('non-empty-array<mixed>', $a);
+		}
+	}
+
 	public function matchesInt($i): void
 	{
 		$spec = Type\int();