Merge branch 'giusepetroso-feat/inertia-defer-groups'

Author: rubenvanassche

docs/advanced-usage/use-with-inertia.md

@@ -3,7 +3,8 @@ title: Use with Inertia
 weight: 9
 ---
 
-> Inertia.js lets you quickly build modern single-page React, Vue, and Svelte apps using classic server-side routing and controllers.
+> Inertia.js lets you quickly build modern single-page React, Vue, and Svelte apps using classic server-side routing and
+> controllers.
 
 Laravel Data works excellent with [Inertia](https://inertiajs.com).
 
@@ -15,10 +16,13 @@ return Inertia::render('Song', SongsData::from($song));
 
 ## Lazy properties
 
-This package supports [lazy](https://spatie.be/docs/laravel-data/v4/as-a-resource/lazy-properties) properties, which can be manually included or excluded.
+This package supports [lazy](https://spatie.be/docs/laravel-data/v4/as-a-resource/lazy-properties) properties, which can
+be manually included or excluded.
 
-Inertia has a similar concept called [lazy data evaluation](https://inertiajs.com/partial-reloads#lazy-data-evaluation), where some properties wrapped in a closure only get evaluated and included in the response when explicitly asked.
-Inertia v2 introduced the concept of [deferred props](https://inertiajs.com/deferred-props), which allows to defer the loading of certain data until after the initial page render.
+Inertia has a similar concept called [lazy data evaluation](https://inertiajs.com/partial-reloads#lazy-data-evaluation),
+where some properties wrapped in a closure only get evaluated and included in the response when explicitly asked.
+Inertia v2 introduced the concept of [deferred props](https://inertiajs.com/deferred-props), which allows to defer the
+loading of certain data until after the initial page render.
 
 This package can output specific properties as Inertia lazy or deferred props as such:
 
@@ -57,9 +61,36 @@ router.reload((url, {
 });
 ```
 
+#### Deferred property groups
+
+It is possible to group deferred properties together, so that all grouped properties are loaded at the same time. In
+order to achieve this, you can pass a group name as the second argument to `Lazy::inertiaDeferred()`:
+
+```php
+class SongData extends Data
+{
+    public function __construct(
+        public Lazy|string $title,
+        public Lazy|string $artist,
+        public Lazy|string $lyrics,
+    ) {
+    }
+    
+    public static function fromModel(Song $song): self
+    {
+        return new self(
+            Lazy::inertiaDeferred(fn() => $song->title),
+            Lazy::inertiaDeferred(fn() => $song->artist, 'details')
+            Lazy::inertiaDeferred(fn() => $song->lyrics, 'details')
+        );
+    }
+}
+```
+
 ### Auto lazy Inertia properties
 
-We already saw earlier that the package can automatically make properties Lazy, the same can be done for Inertia properties.
+We already saw earlier that the package can automatically make properties Lazy, the same can be done for Inertia
+properties.
 
 It is possible to rewrite the previous example as follows:
 
@@ -82,7 +113,8 @@ class SongData extends Data
 }
 ```
 
-If all the properties of a class should be either Inertia or closure lazy, you can use the attributes on the class level:
+If all the properties of a class should be either Inertia or closure lazy, you can use the attributes on the class
+level:
 
 ```php
 #[AutoInertiaLazy]
@@ -95,3 +127,23 @@ class SongData extends Data
     }
 }
 ```
+
+#### Deferred property groups
+
+For the `AutoInertiaDeferred` attribute, it is also possible to specify a group name in order to group deferred
+properties together:
+
+```php
+class SongData extends Data
+{
+    public function __construct(
+        #[AutoInertiaDeferred()]
+        public Lazy|string $title,
+        #[AutoInertiaDeferred('details')]
+        public Lazy|string $artist,
+        #[AutoInertiaDeferred('details')]
+        public Lazy|string $lyrics,
+    ) {
+    }
+}
+```

src/Attributes/AutoInertiaDeferred.php

@@ -11,8 +11,13 @@
 #[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY)]
 class AutoInertiaDeferred extends AutoLazy
 {
+    public function __construct(
+        protected ?string $group = null,
+    ) {
+    }
+
     public function build(Closure $castValue, mixed $payload, DataProperty $property, mixed $value): InertiaDeferred
     {
-        return Lazy::inertiaDeferred(fn () => $castValue($value));
+        return Lazy::inertiaDeferred(fn () => $castValue($value), $this->group);
     }
 }

src/Lazy.php

@@ -38,9 +38,9 @@ public static function inertia(Closure $value): InertiaLazy
         return new InertiaLazy($value);
     }
 
-    public static function inertiaDeferred(mixed $value): InertiaDeferred
+    public static function inertiaDeferred(mixed $value, ?string $group = null): InertiaDeferred
     {
-        return new InertiaDeferred($value);
+        return new InertiaDeferred($value, $group);
     }
 
     public static function closure(Closure $closure): ClosureLazy

src/Support/Lazy/InertiaDeferred.php

@@ -6,8 +6,11 @@
 
 class InertiaDeferred extends ConditionalLazy
 {
+    private ?string $group;
+
     public function __construct(
         mixed $value,
+        ?string $group = null,
     ) {
         $callback = match (true) {
             $value instanceof DeferProp => fn () => $value(),
@@ -16,10 +19,14 @@ public function __construct(
         };
 
         parent::__construct(fn () => true, $callback);
+
+        $this->group = $value instanceof DeferProp && $value->group() !== 'default'
+            ? $value->group()
+            : $group;
     }
 
     public function resolve(): DeferProp
     {
-        return new DeferProp($this->value);
+        return new DeferProp($this->value, $this->group);
     }
 }

tests/CreationTest.php

@@ -1498,75 +1498,104 @@ public function __construct(
         ->each()->toBeInstanceOf(FakeNestedModelData::class);
 });
 
-
 it('can create a data object with inertia deferred properties', function () {
     $dataClass = new class () extends Data {
         public InertiaDeferred|string $deferred;
 
+        public InertiaDeferred|string $deferredWithGroup;
+
         public function __construct()
         {
         }
     };
 
     $data = $dataClass::from([
         "deferred" => Lazy::inertiaDeferred(Inertia::defer(fn () => 'Deferred Value')),
+        "deferredWithGroup" => Lazy::inertiaDeferred(Inertia::defer(fn () => 'Deferred Value', 'deferred-group')),
     ]);
 
     expect($data->deferred)->toBeInstanceOf(InertiaDeferred::class);
     expect($data->all()['deferred'])->toBeInstanceOf(DeferProp::class);
     expect($data->all()['deferred']())->toBe('Deferred Value');
 
+    expect($data->deferredWithGroup)->toBeInstanceOf(InertiaDeferred::class);
+    expect($data->all()['deferredWithGroup'])->toBeInstanceOf(DeferProp::class);
+    expect($data->all()['deferredWithGroup']())->toBe('Deferred Value');
+    expect($data->all()['deferredWithGroup']->group())->toBe('deferred-group');
 });
 
 it('can create a data object with inertia deferred closure', function () {
     $dataClass = new class () extends Data {
         public InertiaDeferred|string $deferred;
 
+        public InertiaDeferred|string $deferredWithGroup;
+
         public function __construct()
         {
         }
     };
 
     $data = $dataClass::from([
         "deferred" => Lazy::inertiaDeferred(fn () => 'Deferred Value'),
+        "deferredWithGroup" => Lazy::inertiaDeferred(fn () => 'Deferred Value', 'deferred-group'),
     ]);
 
     expect($data->deferred)->toBeInstanceOf(InertiaDeferred::class);
     expect($data->all()['deferred'])->toBeInstanceOf(DeferProp::class);
     expect($data->all()['deferred']())->toBe('Deferred Value');
 
+    expect($data->deferredWithGroup)->toBeInstanceOf(InertiaDeferred::class);
+    expect($data->all()['deferredWithGroup'])->toBeInstanceOf(DeferProp::class);
+    expect($data->all()['deferredWithGroup']())->toBe('Deferred Value');
+    expect($data->all()['deferredWithGroup']->group())->toBe('deferred-group');
+
 });
 
 it('can create a data object with inertia deferred value', function () {
     $dataClass = new class () extends Data {
         public InertiaDeferred|string $deferred;
 
+        public InertiaDeferred|string $deferredWithGroup;
+
         public function __construct()
         {
         }
     };
 
     $data = $dataClass::from([
         "deferred" => Lazy::inertiaDeferred('Deferred Value'),
+        "deferredWithGroup" => Lazy::inertiaDeferred('Deferred Value', 'deferred-group'),
     ]);
 
     expect($data->deferred)->toBeInstanceOf(InertiaDeferred::class);
     expect($data->all()['deferred'])->toBeInstanceOf(DeferProp::class);
     expect($data->all()['deferred']())->toBe('Deferred Value');
 
+    expect($data->deferredWithGroup)->toBeInstanceOf(InertiaDeferred::class);
+    expect($data->all()['deferredWithGroup'])->toBeInstanceOf(DeferProp::class);
+    expect($data->all()['deferredWithGroup']())->toBe('Deferred Value');
+    expect($data->all()['deferredWithGroup']->group())->toBe('deferred-group');
 });
 
 it('can use auto deferred to construct a inertia deferred property', function () {
     $dataClass = new class () extends Data {
         #[AutoInertiaDeferred]
         public InertiaDeferred|string $string;
+
+        #[AutoInertiaDeferred('deferred-group')]
+        public InertiaDeferred|string $deferredWithGroup;
     };
 
-    $data = $dataClass::from(['string' => 'Deferred Value']);
+    $data = $dataClass::from(['string' => 'Deferred Value', 'deferredWithGroup' => 'Deferred Value']);
 
     expect($data->string)->toBeInstanceOf(InertiaDeferred::class);
     expect($data->all()['string'])->toBeInstanceOf(DeferProp::class);
     expect($data->all()['string']())->toBe('Deferred Value');
+
+    expect($data->deferredWithGroup)->toBeInstanceOf(InertiaDeferred::class);
+    expect($data->all()['deferredWithGroup'])->toBeInstanceOf(DeferProp::class);
+    expect($data->all()['deferredWithGroup']())->toBe('Deferred Value');
+    expect($data->all()['deferredWithGroup']->group())->toBe('deferred-group');
 });
 
 it('can use class level auto deferred to construct a inertia deferred property', function () {
@@ -1576,16 +1605,13 @@ class AutoDeferredData extends Data
         public InertiaDeferred|string $string;
     }
 
-    ;
-
     $data = AutoDeferredData::from(['string' => 'Deferred Value']);
 
     expect($data->string)->toBeInstanceOf(InertiaDeferred::class);
     expect($data->all()['string'])->toBeInstanceOf(DeferProp::class);
     expect($data->all()['string']())->toBe('Deferred Value');
 });
 
-
 describe('property-morphable creation tests', function () {
     enum TestPropertyMorphableEnum: string
     {