draft: fetch primitive overhaul

[atk]

The fetch primitive does its job, but is too tightly integrated and difficult to extend; therefore it should be broken up into smaller composable parts, which then can extend the functionality of Solid's resources:

• makeRequest - creates a resource URL fetcher from RequestInfo/-Init or Accessors thereof, unwraps the response, and also returns signal to get the response object
• makeCached - wraps resource arguments so the resource will be cached, following certain rules (cache timeout, cache non-200 responses) and gives a setter for manual query invalidation; also allows to cache the data in localStorage or sessionStorage
• makeRetry- wraps resource arguments so requests will be retried a specified number of times with a configurable timeout in between (if the resource is abortable, it should be aborted while paused)
• makeAbortable - wraps resource arguments to make the resource abortable with an AbortSignal, also provides a state (boolean or reason) and an abort callback
• makeTimeout - wraps an abortable resource so it will be automatically aborted after a certain timeout

This requires a breaking change: since we now use createResource more directly, we are reliant on the first argument to return a singular value to be fed into our fetcher; so if we have both RequestInfo and RequestInit, it needs to be given as an Array. Update: that only applies to makeRequest, not to createFetch, which can still take the previous arguments, though augmented with options in order to compose the other stuff. However, I'd really like for tree shaking to work here, so I need to figure out how to make this configurable.

createFetch will continue to exist and then merely compose the whole structure from these primitives, which allows for more fine-grained tree shaking.

There are still a few finer details of the new architecture that need to be specified, so I wanted to start this as a discussion.

[atk]

The main detail that needs to be clarified is how to make this composable? Stuff like makeAbortable needs to apply inside and outside of the createResource call: we need both to wrap the arguments and the resource. In order to do so, we define a resourceContext that will extend on the resource actions and at the same time is accessible inside the wrapped arguments call, so we can wrap both the request accessor and the fetcher.

It basically looks like this:

type RequestContext = {
  abortSignal?: AbortSignal,
}

function makeAbortable<Response>(
  requestAccessor: Accessor<undefined | RequestInfo | [RequestInfo, RequestInit]>,
  requestFetcher: (RequestInfo | [RequestInfo, RequestInit]) => Promise<Response>,
  requestContext: RequestContext = {}
) => [
  wrappedRequestAccessor: Accessor<undefined | RequestInfo | [RequestInfo, RequestInit]>,
  wrappedRequestFetcher: (RequestInfo | [RequestInfo, RequestInit]) => Promise<Response>,
  requestContextWithAbortSignal: RequestContext
]

This means you can extend the return value into the arguments of the following wrapper, i.e.

const resourceContext = {}
const [resource, actions] = createResource(...makeAbortable(...makeCached(...makeRequest(urlAccessor, resourceContext))))
resourceContext.abortSignal.abort()

// or
const [accessor, fetcher, resourceContext] = makeAbortable(...makeCached(...makeRequest(urlAccessor)))
const [resource, actions] = createResource(accessor, fetcher)
resourceContext.abortSignal.abort()

Which makes it pretty easy to optionally chain the wrappers. However, chaining them will require them to be always loaded, so I would prefer to make them either optional or asynchronous, which is the next detail to be covered.

[atk]

Hitting another snag right now: every wrapper needs to run both before starting and after the resource returned. Having had a similar issue in the past, I found something close to the iterator pattern quite helpful - unfortunately the first yield does not allow for a return value, so we have to emulate an actual GeneratorFunction:

const makeAnything = function(resourceContext) {
  // do something with urlAccessor or fetcher
  const modifiedUrlAccessor = urlAccessor
  const modifiedFetcher = fetcher
  const resource = resourceContext.wrapResource()
  const modifiedResource = resource
  resourceCongtext.resource = modifiedResource
}

Update: even simpler, we add everything as part of the context. That allows us to keep it even more abstract. Using recursion to make sure all function stacks are primed.

[atk]

I'm curently considering a change of plan, but that would require a deviation from our naming scheme. A rather elegant way to ensure composition works with tree shaking is to have the functions added as part of the options, i.e.

const [resource, actions] = createFetch(urlAccessor, options, [withDebounceRequest(), withAbort(), withRetry(10), withCache(rules)]);

As you can see, I invented an external withDebounceRequest that could fit the same scheme. This way, we only import the functionality tht we actually need. Also, "with" shows that these functions are not meant as a stand-alone utility, but rather an extension to other functions.

[davedbase]

I think the with standard is acceptable. You wouldn't necessarily use those separately from fetch to make doesn't make much sense tbh. I like this direction very much. Authentication could be withAuthentication or withTokenRefresh.

Can the extra composable elements be treated as interceptors as well? I keep obsessing over Axios ability to pre and post hook values, it would be really valuable if fetch did that via these composable elements.

[atk]

Since you can both wrap the url accessor and the fetcher, you have full control of all aspects. The context allows adding stuff like an abort controller in arbitrary positions – they will be available after the initialization in any case.

[atk]

The first draft is coming along nicely; I'm currently pondering whether I should make this a breaking change by omitting withAbort from the default configuration to go for more tree-shake-ability or leaving it in. The method makes ~350 bytes of difference. I think I should leave it in. Not sure if there would be a better pattern to ensure tree-shakability.

[thetarnav]

Avoiding breaking changes shouldn't be the goal here I think. With such an API shift it would be a major version anyway — no need to be held back by the current one.
I like abort being out of the default because it seems more like an additional feature than a common baseline.

[atk]

Thanks, that makes sense. I'll expose the default modifiers, so one can easily restore the original behavior without everyone else having to add stuff they don't need.

[atk]

OK, I now have a draft PR open: #131 - I still need to figure out the most efficient caching pattern.

[atk]

After some deliberation on the issue, I also found that it would be simple to allow the creation of the request using other methods than fetch, e.g. XMLHttpRequest or axios. The question is how to expose the capability? There are basically two options:

1. force users to always add the withRequest()/withXMLHttpRequest()/withAxiosRequest(axios) themselves if they want to define the array of modifiers,
2. add another argument to the main call.

Option 1 has the risk that they'll forget to add the request manually, in which case they'll receive a helpful error message. Option 2 has the drawback of being somewhat confusing with 4 arguments to the call.

[atk]

Feature parity with react-query mostly, but you're right, I would probably not implement it in the default package, but instead document how you could add it yourself. And yes, the default would always be fetch in both cases. The question is how to replace it.

[atk]

createFetch(urlAccessor, [withAxiosRequest(axios), withAbort()])
// but we need createFetch(urlAccessor, [withRequest(), withAbort()]) for the extended default case
// or
createFetch(urlAccessor, [withAbort()], withAxiosRequest(axios))
// but with options, this becomes confusing easily.

[atk]

There's actually a third option:

createFetch.withRequest = withAxiosRequest(axios) // default with withRequest using fetch

Since we need withRequest as a fallback anyways, there's not much saved for tree-shaking, I guess.

[atk]

So basically, it boils down to

• manual definition
• overwrite through a fourth argument
• set it in a property of the main primitive

The last one is not exclusive to the other two.

[atk]

Thanks to @thetarnav, I found an even better version: use a property of our already existing options object.