[next] More breaking changes

[lukeed]

Looking to add a couple more breaking changes to the worktop@next release cycle – and hopefully it's the last batch!

Before diving into the rundown, it's important to state why these changes are being proposed:

1. There are too many ways to start/initialize a worktop app. Yes, Cloudflare now supports 2 runtimes (Service Worker vs Module Worker), worktop kinda makes it worse by allowing the new Router to be booted up 6+ ways! This was initially done for flexibility, but the reality is that people just want to go down 1 path... 2 at the most. (more on this in the 2nd point)

   Both worktop/sw and worktop/module offer their own listen and reply exports. The listens prepare an App for the Service Worker target & the replys prepare an App for the Module Worker target. This is already 4 options to choose from. Then, worktop/module also offers define (which I do like) so that you can get a TS-aware helper for defining a full Module Worker, which may have more than just a fetch handler. Finally, there's worktop/cache which also offers its own listen and reply exports. This is now 7 offerings. Finally finally, the first two modules offer their own convert helper to go to-and-from the Module to Service Worker signatures, in the event you want/need to mount your own Worker and/or need to convert a third-party function to a different format.

   I, personally, get super confused with these converts and don't actually know which to use unless I look at the source. Granted, they're each 2-4 lines of code, but mentally, I lose track if the narrative is "if converting from sw to module, use the X conversion"... good indicator that it should be tossed I think

2. Worktop will support multiple environments in the near future. Specifically, I'll be adding Node.js support and Deno support. This brings the total to 4 environments supported, which definitely means that (1) needs to be whittled down before adding any more options.... It also means that there should be a standardized "start the App" export regardless of which environment you're targeting.

---

With these in mind, I think these are the breaking changes I want/need to make:

• rename worktop/module -> worktop/cfw

  • remove listen export
  • remove convert export
  • rename reply to start export

• worktop/sw

  • remove reply export
  • remove convert export
  • rename listen to start export

In the future, add the worktop/node and worktop/deno modules, both of which will only have a start export, too.

This creates a workflow wherein:

1. you always import Router from the root worktop module
2. you always choose a start method from a worktop/<env> module
3. it's always obvious which environment you're building for, because you chose it...
4. if desired, you can setup a build-time alias between worktop/<env> modules (rare / advanced cases)
5. worktop can always separate any environment-specific startup or type-changes within the <env> module bounds

import { Router } from 'worktop';

const API = new Router;

// build/deploy a service worker
// ~> browser OR cloudflare
import { start } from 'worktop/sw';
start(API.run);

// build/deploy a Module Worker 
import { start } from 'worktop/cfw';
export default start(API.run);
// ^ environment specific needs
//      makes it easy to document too

// build/deploy a Node.js server
import { start } from 'worktop/node';
start(API.run);

// etc...

---

Finally, unrelated to the above, the send export from within the worktop/response module annoyed me 😅 Because you have to return the Response that send builds, the "send" name makes no sense. You don't "return a send" ... you "return a reply"

I'm renaming send to reply – which is also more reason to get rid of the previous/current reply exports from the worktop/(sw|cache|module) modules, which really didn't make sense for them to be called reply in the first place!

[lukeed]

Forgot to address the worktop/cache module – it should only export a start method for the base Initializer type (aligning with the Module Workers default assumption). If you're targeting a Service Worker, then you still have access to all the other worktop/cache exports to piece together your own response handler. This is also going to be true for users targeting the Node.js and Deno environments.

TLDR; make the start export from worktop/cache be the only done-for-you solution & have it target Module Workers (Cloudflare only), which is fine since worktop still is primarily a framework for Cloudflare Workers.

[lukeed]

Also think I need to amend something – the new worktop/cfw module should probably have two primary exports:

• start – for the Module Worker format (as described above)
• listen – for the Service Worker format

This new listen would not replace the worktop/sw module. The purpose of adding the listen export is that it allows me to move all Cloudflare-specific TypeScript interfaces and/or type-mutations to a single module.

In other words, you get the type definitions for stuff like request.cf, response.webSocket, and event.passThroughOnException only if you're actually targeting Cloudflare. You/Worktop can know this because if you are deploying to Cloudflare, then you'll either be importing listen or start from the worktop/cfw module, which auto-loads all that information.

import { Router } from 'worktop';
import type { Handler } from 'worktop';

const hello: Handler = async function (req, context) {
  req.cf;
  //   ^ will ONLY be defined if `worktop/cfw` was imported
}

[lukeed]

Closed via #127

There's one additional breaking change I want to make – PR tomorrow