fix!: rename LazyProp to OptionalProp and add static helpers

Author: NeoIsRecursive

src/Http/InertiaResponse.php

@@ -10,7 +10,7 @@
 use NeoIsRecursive\Inertia\PageData;
 use NeoIsRecursive\Inertia\Props\AlwaysProp;
 use NeoIsRecursive\Inertia\Props\DeferProp;
-use NeoIsRecursive\Inertia\Props\LazyProp;
+use NeoIsRecursive\Inertia\Props\OptionalProp;
 use NeoIsRecursive\Inertia\Support\Header;
 use NeoIsRecursive\Inertia\Views\InertiaBaseView;
 use Tempest\Http\IsResponse;
@@ -105,7 +105,10 @@ private static function resolvePartialProps(Request $request, string $component,
         $headers = $request->headers;
 
         if (!static::isPartial($request, $component)) {
-            return array_filter($props, static fn($prop) => !($prop instanceof LazyProp || $prop instanceof DeferProp));
+            return array_filter(
+                $props,
+                static fn($prop) => !($prop instanceof OptionalProp || $prop instanceof DeferProp),
+            );
         }
 
         $only = array_filter(explode(

src/Inertia.php

@@ -4,9 +4,12 @@
 
 namespace NeoIsRecursive\Inertia;
 
-use Exception;
+use Closure;
 use NeoIsRecursive\Inertia\Http\InertiaResponse;
 use NeoIsRecursive\Inertia\InertiaConfig;
+use NeoIsRecursive\Inertia\Props\AlwaysProp;
+use NeoIsRecursive\Inertia\Props\DeferProp;
+use NeoIsRecursive\Inertia\Props\OptionalProp;
 use NeoIsRecursive\Inertia\Support\Header;
 use Tempest\Container\Container;
 use Tempest\Container\Singleton;
@@ -16,6 +19,8 @@
 use Tempest\Http\Responses\Redirect;
 use Tempest\Http\Session\Session;
 use Tempest\Http\Status;
+use Tempest\Reflection\FunctionReflector;
+use Tempest\Reflection\MethodReflector;
 
 #[Singleton]
 final class Inertia
@@ -36,6 +41,21 @@ public function share(string|array $key, mixed $value = null): self
         return $this;
     }
 
+    public static function optional(MethodReflector|FunctionReflector|Closure $callback): OptionalProp
+    {
+        return new OptionalProp($callback);
+    }
+
+    public static function defer(MethodReflector|FunctionReflector|Closure $callback): DeferProp
+    {
+        return new DeferProp($callback);
+    }
+
+    public static function always(mixed $value): AlwaysProp
+    {
+        return new AlwaysProp($value);
+    }
+
     public function flushShared(): self
     {
         $this->config->flushSharedProps();

src/Props/AlwaysProp.php

@@ -19,7 +19,7 @@ final class AlwaysProp implements CallableProp, MergeableProp
     use IsMergeableProp;
 
     public function __construct(
-        public readonly MethodReflector|FunctionReflector|string|Closure|array $value,
+        public readonly mixed $value,
         public private(set) bool $shouldMerge = false,
     ) {}
 

src/Props/LazyProp.php src/Props/OptionalProp.phpsrc/Props/LazyProp.php renamed to src/Props/OptionalProp.php

@@ -14,7 +14,7 @@
 
 use function Tempest\invoke;
 
-final class LazyProp implements CallableProp, MergeableProp
+final class OptionalProp implements CallableProp, MergeableProp
 {
     use IsMergeableProp;
 

tests/Fixtures/TestController.php

@@ -8,7 +8,7 @@
 use NeoIsRecursive\Inertia\Http\Middleware\EncryptHistory;
 use NeoIsRecursive\Inertia\Inertia;
 use NeoIsRecursive\Inertia\Props\AlwaysProp;
-use NeoIsRecursive\Inertia\Props\LazyProp;
+use NeoIsRecursive\Inertia\Props\OptionalProp;
 use NeoIsRecursive\Inertia\Tests\Fixtures\Requests\CreatePerson;
 use Tempest\Http\Responses\Ok;
 use Tempest\Http\Responses\Redirect;
@@ -60,7 +60,9 @@ public function testAllSortsOfProps(Inertia $inertia): InertiaResponse
         )->render(
             component: 'User/Edit',
             props: [
-                new AlwaysProp(fn() => 'baz'),
+                'always' => Inertia::always(fn() => 'always'),
+                'optional' => Inertia::optional(fn() => 'optional'),
+                'defer' => Inertia::defer(fn() => 'defer'),
             ],
         );
     }
@@ -115,7 +117,7 @@ public function testCanMergeProps(Inertia $inertia): InertiaResponse
             component: 'test',
             props: [
                 'foo' => new AlwaysProp(fn() => 'bar')->merge(),
-                'baz' => new LazyProp(fn() => 'qux')->merge(),
+                'baz' => new OptionalProp(fn() => 'qux')->merge(),
             ],
         );
     }

tests/Integration/LazyPropTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NeoIsRecursive\Inertia\Tests\Integration;
+
+use NeoIsRecursive\Inertia\Props\OptionalProp;
+use NeoIsRecursive\Inertia\Tests\TestCase;
+use Tempest\Http\Request;
+
+final class OptionalPropTest extends TestCase
+{
+    public function test_can_invoke(): void
+    {
+        $optionalProp = new OptionalProp(function (): string {
+            return 'A optional value';
+        });
+
+        static::assertSame(
+            expected: 'A optional value',
+            actual: $optionalProp(),
+        );
+    }
+
+    public function test_can_accept_scalar_values(): void
+    {
+        $optionalProp = new OptionalProp(fn() => 'A optional value');
+
+        static::assertSame(
+            expected: 'A optional value',
+            actual: $optionalProp(),
+        );
+    }
+
+    public function test_can_resolve_bindings_when_invoked(): void
+    {
+        $optionalProp = new OptionalProp(fn(Request $request) => $request);
+
+        static::assertInstanceOf(Request::class, $optionalProp());
+    }
+}

tests/Integration/OptionalPropTest.php

@@ -8,7 +8,7 @@
 use NeoIsRecursive\Inertia\PageData;
 use NeoIsRecursive\Inertia\Props\AlwaysProp;
 use NeoIsRecursive\Inertia\Props\DeferProp;
-use NeoIsRecursive\Inertia\Props\LazyProp;
+use NeoIsRecursive\Inertia\Props\OptionalProp;
 use NeoIsRecursive\Inertia\Support\Header;
 use NeoIsRecursive\Inertia\Tests\TestCase;
 use NeoIsRecursive\Inertia\Views\InertiaBaseView;
@@ -366,7 +366,7 @@ public function test_lazy_props_are_not_included_by_default(): void
     {
         $request = $this->createInertiaRequest(Method::GET, uri: '/users');
 
-        $lazyProp = new LazyProp(fn() => 'A lazy value');
+        $lazyProp = new OptionalProp(fn() => 'A lazy value');
 
         $response = new InertiaResponse(
             $request,
@@ -394,7 +394,7 @@ public function test_lazy_props_are_included_in_partial_reload(): void
             Header::PARTIAL_ONLY => 'lazy',
         ]);
 
-        $lazyProp = new LazyProp(function (): string {
+        $lazyProp = new OptionalProp(function (): string {
             return 'A lazy value';
         });
 
@@ -425,7 +425,7 @@ public function test_always_props_are_included_on_partial_reload(): void
         ]);
 
         $props = [
-            'user' => new LazyProp(function (): array {
+            'user' => new OptionalProp(function (): array {
                 return [
                     'name' => 'Jonathan Reinink',
                     'email' => 'jonathan@example.com',