BREAKING(http): clean up module

[lino-levan]

Closes #3655 and closes #3646

[iuioiua]

I think prepending unstable_ instead of having an unstable folder is a bit tidier. Either way, seeing the http_ prefix being dropped from these files is cool!

[iuioiua]

How come this is part of the unstable API? I'm sure I'm missing context, but the move surprises me. We use errors in SaaSKit to handle serving error responses in the REST API by throwing these HTTP errors (https://github.com/denoland/saaskit/blob/main/plugins/error_handling.ts).

[kt3k]

In my view, representing http errors as JS Error objects is an opinionated approach.

In most cases when you throw http error in your route handler or middleware, you can also directly return Response object with error status code.

For example, the below code:

throw createHttpError(status, message)

can usually be replaced by

return new Response(message, { status });

or similar. If this replacement can be applied universally, then HttpError abstraction might be just redundant.

[iuioiua]

If a request handler has a call stack size of n, using returns and finally returning an error response may require up to n conditionals. An error needs to be handled once to return an error response. I previously used the former method in SaaSKit before realising it could be done much easier once I discovered the HTTP error code in the Standard Library. It certainly made things easier to deal with.

To be clear, if we decide that HTTP errors should be unstable, fair enough. I just wanted to provide a valid counterargument.

[kt3k]

That might be a valid use case. Let's keep the discussion in an independent issue

[kt3k]

I think prepending unstable_ instead of having an unstable folder is a bit tidier.

Might be a good idea. @lino-levan What do you think?

BTW we already have unstable/ sub directory in crypto and collections

[lino-levan]

I think we're at least a little committed to the unstable folder convention, but I think unstable_x reads better. The point of unstable APIs anyways is that they're little used so it'd probably be fine to move them around one more time.

[iuioiua]

Gentle ping, @lino-levan.

[lino-levan]

I have some concerns. Following up on discord.

[lino-levan]

This should be ready to be merged now. Please review again, when you both get the chance.

[kt3k]

Looks good to me. Thanks for your contribution! @lino-levan

Let's land when Asher's point is addressed.

[lino-levan]

I believe this is ready to be merged. Please review. I would like a second pair of eyes to see if I re-exported everything properly.

[kt3k]

It looks like the below structure doesn't work for deprecating re-export.

/** @deprecated */
export { foo } from "..";

Instead, we need to create aliases and deprecate them.

import { foo as foo_ } from "..";
/** @deprecated */
export const foo = foo_;

I'll make these changes in this branch

[kt3k]

LGTM. Thank you for your contribution!

[lino-levan]

Thanks for the final push @kt3k! Good to know what the proper reexport structure is.

[iuioiua]

We should check whether other deprecated sub-modules have included the correct deprecation JSDocs.