Support for API Resources

[ace-of-aces]

Hey, first of all congrats on the beta release of Ranger and Surveyor. The upcoming version of Wayfinder looks really promising!🔥

I dabbled with the dev-next version of Wayfinder for a little now and noticed that it can't generate types for Laravel's API Resources. Found that's because those aren't (yet) part of what Ranger collects.

Considering how commonly this feature is used, especially (but not exclusively) in projects with TypeScript frontends that are not using Inertia but would like to adopt Wayfinder anyways, I think this would be nice to support.

Of course, that would require changes in Wayfinder itself too, and perhaps in Surveyor as well.

So, if this is welcomed/planned, I could work on a PR :)

[joetannenbaum]

Thanks! Excited to finally have this out and into testing.

If you return an API resource as a controller response, does Ranger not interpret the response correctly in the controller response type? This would be part of what comes back from the Route collector under the hood.

[ace-of-aces]

Essentially yes, Wayfinder doesn't generate proper type declarations if an API resource is used in a controller's response.

I tested that in a starter kit app with Wayfinder@dev-next:

---

The resource

// ProfileResource.php
class ProfileResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'email_verified_at' => $this->email_verified_at,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
            'foo' => 'bar',
        ];
    }
}

returned as part of ProfileController@edit:

class ProfileController extends Controller
{
    /**
     * Show the user's profile settings page.
     */
    public function edit(Request $request): Response
    {
        return Inertia::render('settings/Profile', [
            'profile' => ProfileResource::make($request->user()),
            'mustVerifyEmail' => $request->user() instanceof MustVerifyEmail,
            'status' => (string) $request->session()->get('status'),
        ]);
    }
    // ...
}

and consumed in Profile.vue, where it's just any:

looking into types.d.ts, I can see that the profile field of the controller response is correctly assigned to the App.Http.Resources.ProfileResource namespace, but that doesn't get generated, so it's unresolved, turning it into any:

---

If an API resource is the only thing being returned from the controller, the response type only contains the fields from Inertia's shared data and none of the resource.

I could also provide a minimal reproduction repo if that would help :)

So I suspect the underlying issue could be that Ranger doesn't analyze Resources yet, and in turn Wayfinder can't generate type declarations for them (but that's only an educated guess).

Would it be good to have an issue for this in the Wayfinder repo?🤔

[joetannenbaum]

Yeah I think you're right, we should also be consuming Jsonable and Arrayable classes as JSON, if you want to take a crack at a PR before I get to it be my guest! Otherwise I can tackle it this week at some point. I think it's here we have to focus:

src/Collectors/Response.php

[moisish]

I'm also hitting this with classes implementing Arrayable (not just API Resources).

// Table class implements Arrayable
return Inertia::render('schedules/index', Table::make());

This throws:

InertiaComponents::addComponent(): Argument #2 ($data) must be of type ArrayType|ArrayShapeType, ClassType given

Same root cause - any Arrayable implementation gets identified as ClassType instead of being recognized as array-like.

[jornicornelese]

Not to be hasty, but is there any progress being made on this issue?
Otherwise, I could try to get my hands on this as well.

Other thing I noticed as well is that when using a {Model}Resource::collection() it just returns an AnonymousCollection, which is right, but this just means we have to create for example a ProductResource as well as a ProductCollection just to get it typed right.

One more nice to have (and should probably be it's own issue in Surveyor I think):
Reading all the withs and appends that has been called on a given model to automatically generate the correct TS types when used in conjunction with whenAppended / whenLoaded / whenCounted / whenAggregated, but this might be a stretch.

[ace-of-aces]

@jornicornelese Hey, fyi: I worked on a PR for this at some point, but wasn't quite satisfied so I didn't deem it to be worthy of a review. Mainly because I only focused on JSONResource classes, not on all Arrayable classes that Joe mentioned.

I probably won't find time for this in the near future..
But I'd be happy if you wanna give it a shot! :)

[jornicornelese]

@ace-of-aces Well yeah, same here. Managed to finish it, but there are just too many caveats.
I had to make changes in all 3 (ranger/surveyor/wayfinder) repositories to make it work.

Managed to also fix Resource wrapping, pagination in the JsonResource.
Also got model appended Attributes in a working state that they return their toArray values instead of Casts\Attribute when using the same syntax.

Maybe I'll just make a PR and we can check together what to improve, because currently I don't feel like I'm following the standards this package was going for.

All code is on the main branch in my repositories, maybe take a look?

Example code is with: JsonResource::withoutWrapping(); within boot() method, but wrapping with data works as well.

Example of output:

// example controller
public function index(Request $request): Response
    {
        return Inertia::render('products/Index', [
            'products' => ProductResource::collection(Product::with(['inventory', 'discount'])
                ->paginate($request->integer('per_page', 15))
            ),
            'productcollection' => ProductResource::collection(Product::all()),
            'productcollection2' => Product::all()->toResourceCollection(ProductResource::class),

            'singleProduct' => ProductResource::make(Product::find(1)),
            'singleProduct2' => new ProductResource(Product::find(1)),
            'singleProduct3' => Product::find(1)->toResource(ProductResource::class),
        ]);
    }

// Example resource:
/** @mixin Product */
class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'description' => $this->description,
            'price' => $this->price,
            'countOfPriceHistory' => $this->whenCounted('priceHistory'),
            'category' => $this->category,
            'stockLevel' => $this->whenLoaded('inventory', fn (): int => $this->inventory->stock_level, 0),
            'isLowStock' => $this->whenLoaded('inventory', fn (): bool => $this->inventory->is_low_stock, true),
            'discount' => ProductDiscountResource::make($this->whenLoaded('discount')),
            'priceHistory' => PriceHistoryPointResource::collection($this->whenLoaded('priceHistory'))
        ];
    }
}

// Example of price attribute:
public function price(): Attribute
    {
        return Attribute::make(
            get: fn (): Money => new Money($this->price_amount, $this->price_currency)
        );
    }

Results in:

// Controller Index returns:
export type Index = Inertia.SharedData & {
  products: {
    data: App.Http.Resources.Cqrs.ProductResource[];
    links: {
      first: string | null;
      last: string | null;
      prev: string | null;
      next: string | null;
    };
    meta: {
      current_page: number;
      from: number | null;
      last_page: number;
      links: {
        url: string | null;
        label: string;
        page: number | null;
        active: boolean;
      }[];
      path: string;
      per_page: number;
      to: number | null;
      total: number;
    };
  };
  productcollection: App.Http.Resources.Cqrs.ProductResource[];
  productcollection2: App.Http.Resources.Cqrs.ProductResource[];
  singleProduct: App.Http.Resources.Cqrs.ProductResource;
  singleProduct2: App.Http.Resources.Cqrs.ProductResource;
  singleProduct3: unknown;
};

// ProductResource
export type ProductResource = {
  id: string;
  name: string;
  description: string;
  price: { amount: number; currency: string; formatted: string };
  countOfPriceHistory?: unknown;
  category: string;
  stockLevel: number;
  isLowStock: boolean | true;
  discount: App.Http.Resources.ProductDiscountResource;
  priceHistory: App.Http.Resources.PriceHistoryPointResource[];
};

@joetannenbaum are there any conventions in this package that we should adhere to?

[ace-of-aces]

@jornicornelese Awesome that you made it work!

Funny, when I was tinkering with this I also realized in order to get the resource's property types from the underlying model, the resource has to have a hint that via @mixin or similar (which I think is your approach here?) 😄

Haven't dug into your code yet, but I think some documented approach to determine the model would be smart here.
Maybe sth like @mixin tag -> Model name guessed by resource naming convention -> fallback to unknown?

[jornicornelese]

@ace-of-aces well yeah, that's what I found out as well. But I'd rather check the first argument of the resource together with the with/append methods on the model instead of the mixin.

Together with whenAppended/loaded/counted you could just fully type out each individual route instead of making all attributes optional on the TS model.

I don't know if I figured that out yet, but the generator was already getting pretty heavy with only 4 models/resources. So idk if this is the way to go.

As I said, this would also require changes on surveyor, so at the end all packages need updates to make this work.

[Lukasss93]

Any updates on this?