Rename handle's render parameter to resolve

[benmccann]

I was a bit confused by the name render because it had a heavy page connotation in my mind (another user stated the same), so I wasn't sure if you'd be calling it for endpoints as well. Rich had suggested respond could be a more neutral alternative. I like that name, so wanted to raise the question of renaming it here

[ignatiusmb]

It runs on both pages and endpoints, so it describes the action better than render

[Conduitry]

I dunno, respond doesn't feel right to me, and for what seems like a more serious reason than render. The function constructs the response, but nothing's returned from the server until you return a value from handle. This function in question renders the default response but doesn't respond with it.

[Rich-Harris]

@benmccann suggested in discord that we change the signature to

export function respond({ request, handle }) {
  return handle(request);
}

I think calling the hook itself respond is fine. I'm not wild about handle as the argument name, it feels overly generic and suffers from the same problem as respond which is that it's a do-something verb rather than a get-something verb. The initial choice of render does have the correct connotation in that regard, though it seems people don't love that.

[benmccann]

How about execute? Some other options: perform, fulfill, do, operate, serve, run, satisfy

[Rich-Harris]

Those are all do-something verbs! They suggest that the function has an effect, rather than returning a value. A get-something verb is something like transform or map, though obviously neither works in this context. I still can't come up with something better than render

[elliott-with-the-longest-name-on-github]

Maybe this is too far outside the box and I'm just not correctly conceptualizing the dataflow here, but Hooks in general really feel more like middleware to me than anything. Data flow is:

incoming request => handle
                         |_endpoints
                         |_getSession => anywhere session is used

As in, data flows into your application, through your hooks, and down to your loads/endpoints, which then (in the case of endpoints), respond to requests. The way I think about it, when I make a request to an endpoint from a .svelte file, I'm making a request through handle to the endpoint, which then responds to me.

If that's correct, the language around the hooks would make more sense if it sounded like a middleman:

export function handle({ request, continue }) {
  return continue(request);
}

// or 
export function handle({ request, forward }) {
  return forward(request);
}

I think that may shift the question to what handle should be called, though, as handle doesn't seem to fit that mental model as well. Maybe intercept?

[nitroboy720]

What about getResponse ?

[DhyeyMoliya]

handle & renderer

Or

render and handler

Adding 'er' will make it more clear.

We are returning response handled by a handler.

Or we are returning response rendered by a renderer.

[quentin-fox]

I think the handle name for the hook is slightly problematic since it doesn't clearly indicate that it's essentially a middleware function. It's also not really a traditional middleware, since it doesn't just have access to the request before it goes to the end route handler, but it has access to the handler itself.

Likewise, render seems much too front-end-y, and keeping the distinction between frontend and backend code in a framework where the two are located quite close to each other seems pretty important for clarity's sake.

With that in mind, thoughts on the name intercept for the hook, and instead of the render parameter, it could be changed to handler? So the snippet from the docs would look like:

export async function intercept({ request, handler }) {
	request.locals.user = await getUserInformation(request.headers.cookie);

	const response = await handler(request);

	return {
		...response,
		headers: {
			...response.headers,
			'x-custom-header': 'potato'
		}
	};
}

The idea of intercept or an interceptor is also in Nest.js where it is responsible for a similar roles as the handle hook, in that it is responsible for data flow before and after the end route handler is called.

Renaming render to handler also indicates that it's a route handler function that can be called with the request in order to obtain a response - I could be wrong, but I think that handler is a pretty conventional name for that sort of function.

[ignatiusmb]

That's a nice reference, I like the idea of intercept more as this is sort of like a middleware but not really one, and to just say that this intercept(s) the request before returning a response, feels better somehow.

Still conflicted on the handler part.

[quentin-fox]

How do you feel about process instead of handler? Servers tend to process requests, so the language kinda tracks, although once again it's just another do-verb.

EDIT: I take it back, if this runs on the server, that might shadow the process variable if someone does import process from 'process'.

[elliott-with-the-longest-name-on-github]

Personally, I also like the idea of intercept. My vote for render is continue or forward:

export function intercept({ request, forward }) {
  return forward(request);
  // or return continue(request);
}

I'm flipflopping a bit on which I like better, but I think "continue" probably makes the most sense in my head.

[quentin-fox]

I'm not so keen on forward, it doesn't really convey that you can receive the result of the request, kinda like next that's used in a lot of middleware patterns, which is just responsible for moving the request to the next handler. That train of thought is making me like continue a bit better as well.

[ignatiusmb]

Please keep in mind of ES reserved keywords, words like do or continue can't be used.

[benmccann]

After discussion with the other maintainers, I will rename to resolve

async function handle({ request, resolve }) {

}