Re-architect Angular Query around Angular Resource before stable release

[OmerGronich]

I’d like to propose making Angular Resource part of the core implementation of injectQuery.

The Angular adapter is still experimental, and when it was created Angular did not yet have a first-party Resource API. Now Angular does, and newer Angular APIs are starting to compose around resources. Signal Forms async validation is a good example: validateAsync() is resource-based, but injectQuery() currently returns a TanStack-shaped signal object, not a resource.

That makes TanStack Query feel slightly outside Angular’s current async model. It works well with signals and templates, but it does not plug cleanly into APIs that expect a ResourceRef.

Proposal

Architect injectQuery around Angular Resource internally:

QueryObserver
  -> Angular Resource
  -> Angular Query result object

The public API could remain mostly the same:

const query = injectQuery(() => ({
  queryKey: ['user', userId()],
  queryFn: ({ signal }) => getUser(userId(), { signal }),
}))

query.data()
query.isPending()
query.isFetching()
query.refetch()

But because the implementation is resource-based, the underlying resource could also be exposed:

query.resource.value()
query.resource.status()
query.resource.error()
query.resource.reload()
query.resource.hasValue()

This would let Angular-native APIs consume TanStack Query without custom glue:

validateAsync(path.username, {
  params: field => field().value(),
  factory: username =>
    injectQuery(() => ({
      queryKey: ['username-availability', username],
      queryFn: ({ signal }) => checkUsername(username, { signal }),
    })).resource,
})

Why this should be part of the architecture

Angular signals are the reactivity primitive. Angular Resource is the async primitive. injectQuery() currently integrates with the former, but not really with the latter.

The Solid adapter is a useful comparison: it keeps the Query API, but integrates with Solid’s native async primitive under the hood. Angular now has its own equivalent async primitive, so it seems worth considering the same direction before the Angular adapter stabilizes.

The goal is not to hide TanStack Query behind Resource. TanStack Query still has important semantics that Resource does not fully capture, like stale state, background refetching, invalidation, retries, paused fetches, placeholder data, cache metadata, and separate status / fetchStatus.

So the returned object could expose both layers:

query.resource.value()
query.resource.status()
query.resource.reload()

query.data()
query.isFetching()
query.isStale()
query.fetchStatus()
query.refetch()

Open questions

• Should injectQuery() be resource-based internally?
• Should the resource be exposed as query.resource, query.asResource(), or something else?
• Should query.data() come from resource.value(), or should both come from a shared observer snapshot?
• How should TanStack Query’s status and fetchStatus map to Angular ResourceStatus?
• Should resource.reload() map to query.refetch()?
• Should resource.set() and resource.update() map to queryClient.setQueryData()?
• Should injectInfiniteQuery() follow the same model?

Since the Angular adapter is still experimental, this feels like the right time to decide whether it should be resource-first internally before the API stabilizes.

[benjavicente]

Hello 👋 I have been playing around with my fork of Angular Query, where I added proper SSR with pending tasks and hydratation support, so I think I can give input into this. I believe this can be split into 2 areas of discussion:

1. Should the Angular adapter use the resource API internally?

The resource API helps a lot to simplify async operations. The main thing that the query adapter does is not async operations, is the subscription to the query client to an specific query thought an observer. You can see that in the Solid adapter: the main usage for the async primitive it is not for handling a promise, it is for connecting the observer behaviour to Solid primitives. The 2 features those promitives provide are:

• Hydratation: Angular does not support streaming and it offers the transfer state API, so hydratation of server data in the client can be easily be done globally. It doesn't need the API for hydratation that the resource API provides.
• Waiting for request to be done (Suspense in Solid): It can use Angular's Pending Task API, allowing the proper integration with SSR and the whenStable testing APIs. Note that official adapter currently has issues with that API so it does not work as expected.

So given that it is possible to use other APIs to do the same, I don't see benefit of using the Resource API. The adapter can use specialized APIs offering the same feature set, without relying on weird workarounds (like how the Solid adapter manages the promise).

2. Should the snapshot have a resource field? How it should behave?

Even if it doesn't use the Resource API internally, it can use the Resource Interface. The injectQuery api could return a query. resource or resource.asResource() that follows that interface. It could provide the full ResourceRef interface.

My impression is that Resource looks something that could be worth looking at, and that ResourceRef is too powerful and would require a lot of glue code. It would allow you to use TS Query thought 2 APIs, thought ResourceRef and via the direct TanStack Query API, and that isn't ideal.

For how to map things, the ResourceStatus enum docs gives some indications of how the resource should behave in each of the Resource statuses, so that gives us a hint of how to map the status fields correctly.

For signal forms, a plain Resource works fine at runtime but the API expects the full ResourceRef interface. I opened a issue in Angular here angular/angular#69443 to see if that can be changed.

I uploaded my fork with a .resource Resource-like field to experiment and tested it out in this playground if anyone wants to take a look. The main remaining things I see before landing on an API would be:

• what other uses cases we expect from this? to test it out in more use cases
• if the proxy approach the adapter uses internally fine for this or if it need to be changed?
• is query.resource prefered over query.asResource()?
• if implementing just the Resource interface is fine enough?

For the last point, I added the .reload method in a custom interface that extends Resource for fully form validation compatibility, but that behaviour might need adjustments, like for example, changing it to only refetch if the data is stale.