Clean up worker docs

1 files changed, 69 insertions, 65 deletions

diff --git a/docs/api/workers.md b/docs/api/workers.md
index 79a230714..f68bf9450 100644
--- a/docs/api/workers.md
+++ b/docs/api/workers.md
@@ -1,15 +1,21 @@
-[`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) lets you start and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread. You can use TypeScript, CommonJS, ESM, JSX, etc in your workers. `Worker` support was added in Bun v0.6.15.
+{% callout %}
+`Worker` support was added in Bun v0.6.15.
+{% /callout %}
 
-Bun implements a minimal version of the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) with extensions that make it work better for server-side use cases.
+[`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) lets you start and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread.
 
-## Usage
+Bun implements a minimal version of the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) with extensions that make it work better for server-side use cases. Like the rest of Bun, `Worker` in Bun support CommonJS, ES Modules, TypeScript, JSX, TSX and more out of the box. No extra build steps are necessary.
+
+## Creating a `Worker`
 
 Like in browsers, [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) is a global. Use it to create a new worker thread.
 
-Main thread:
+From the main thread:
+
+```js#Main_thread
+const workerURL = new URL("worker.ts", import.meta.url).href;
+const worker = new Worker(workerURL);
 
-```js
-const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 worker.postMessage("hello");
 worker.onmessage = event => {
   console.log(event.data);
@@ -18,18 +24,37 @@ worker.onmessage = event => {
 
 Worker thread:
 
-{% codetabs %}
-
-```ts#worker.ts
+```ts#worker.ts_(Worker_thread)
 self.onmessage = (event: MessageEvent) => {
   console.log(event.data);
   postMessage("world");
 };
 ```
 
-{% /codetabs %}
+You can use `import`/`export` syntax in your worker code. Unlike in browsers, there's no need to specify `{type: "module"}` to use ES Modules.
+
+To simplify error handling, the initial script to load is resolved at the time `new Worker(url)` is called.
+
+```js
+const worker = new Worker("/not-found.js");
+// throws an error immediately
+```
+
+The specifier passed to `Worker` is resolved relative to the project root (like typing `bun ./path/to/file.js`).
+
+### `"open"`
+
+The `"open"` event is emitted when a worker is created and ready to receive messages. This can be used to send an initial message to a worker once it's ready. (This event does not exist in browsers.)
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("open", () => {
+  console.log("worker is ready");
+});
+```
 
-### Sending & receiving messages with `postMessage`
+## Messages with `postMessage`
 
 To send messages, use [`worker.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage) and [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This leverages the [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
 
@@ -59,7 +84,7 @@ worker.addEventListener("message", = event => {
 // worker.onmessage = fn
 ```
 
-### Terminating a worker
+## Terminating a worker
 
 A `Worker` instance terminate automatically when Bun's process exits. To terminate a `Worker` sooner, call `worker.terminate()`.
 
@@ -70,16 +95,38 @@ const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 worker.terminate();
 ```
 
-### Managing lifetime with `worker.ref` and `worker.unref`
+### `process.exit()`
+
+A worker can terminate itself with `process.exit()`. This does not terminate the main process. Like in Node.js, `process.on('beforeExit', callback)` and `process.on('exit', callback)` are emitted on the worker thread (and not on the main thread).
+
+### `"close"`
+
+The `"close"` event is emitted when a worker has been terminated. It can take some time for the worker to actually terminate, so this event is emitted when the worker has been marked as terminated.
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("close", () => {
+  console.log("worker is being closed");
+});
+```
+
+This event does not exist in browsers.
+
+## Managing lifetime
+
+By default, an active `Worker` will _not_ keep the main (spawning) process alive. Once the main script finishes, the main thread will terminate, shutting down any workers it created.
+
+### `worker.ref`
 
-By default, a `Worker` will **not** keep the process alive. To keep the process alive until the `Worker` terminates, call `worker.ref()`.
+To keep the process alive until the `Worker` terminates, call `worker.ref()`. This couples the lifetime of the worker to the lifetime of the main process.
 
 ```ts
 const worker = new Worker(new URL("worker.ts", import.meta.url).href);
 worker.ref();
 ```
 
-You can also pass an `options` object to `Worker`:
+Alternatively, you can also pass an `options` object to `Worker`:
 
 ```ts
 const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
@@ -89,6 +136,8 @@ const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
 });
 ```
 
+### `worker.unref`
+
 To stop keeping the process alive, call `worker.unref()`.
 
 ```ts
@@ -100,11 +149,9 @@ worker.unref();
 
 Note: `worker.ref()` and `worker.unref()` do not exist in browsers.
 
-### Memory Usage
-
-JavaScript instances sometimes use a lot of memory.
+## Memory usage with `smol`
 
-Bun's `Worker` supports a `smol` mode that reduces memory usage, at a cost of performance. To enable `smol` mode, pass `smol: true` to the `options` object in the `Worker` constructor.
+JavaScript instances can use a lot of memory. Bun's `Worker` supports a `smol` mode that reduces memory usage, at a cost of performance. To enable `smol` mode, pass `smol: true` to the `options` object in the `Worker` constructor.
 
 ```js
 const worker = new Worker("./i-am-smol.ts", {
@@ -114,49 +161,6 @@ const worker = new Worker("./i-am-smol.ts", {
 });
 ```
 
-#### What does `smol` mode actually do?
-
-It sets ` JSC::HeapSize` to be `Small` instead of the default `Large`
-
-### Worker supports ES Modules, CommonJS, TypeScript, JSX, etc
-
-Like the rest of Bun, `Worker` in Bun support CommonJS, ES Modules, TypeScript, JSX, TSX and more out of the box. No extra build steps are necessary. You can use `import` and `export` in your worker code. This is different than browsers, where `"type": "module"` is necessary to use ES Modules.
-
-To simplify error handling, the initial script to load is resolved at the time `new Worker(url)` is called.
-
-```js
-const worker = new Worker("/not-found.js");
-// throws an error immediately
-```
-
-The specifier passed to `Worker` is resolved relative to the project root (like typing `bun ./path/to/file.js`).
-
-### `"open"` event
-
-The `"open"` event is emitted when a worker is created and ready to receive messages.
-
-```ts
-const worker = new Worker(new URL("worker.ts", import.meta.url).href);
-worker.addEventListener("open", () => {
-  console.log("worker is ready");
-});
-```
-
-This event does not exist in browsers.
-
-### `"close"` event
-
-The `"close"` event is emitted when a worker has been terminated. It can take some time for the worker to actually terminate, so this event is emitted when the worker has been marked as terminated.
-
-```ts
-const worker = new Worker(new URL("worker.ts", import.meta.url).href);
-worker.addEventListener("close", () => {
-  console.log("worker is ready");
-});
-```
-
-This event does not exist in browsers.
-
-### `process.exit()` inside a worker
-
-Calling `process.exit()` in a Worker terminates the worker, but does not terminate the main process. Like in Node.js, `process.on('beforeExit', callback)` and `process.on('exit', callback)` are emitted on the worker thread (and not on the main thread).
+{% details summary="What does `smol` mode actually do?" %}
+Setting `smol: true` sets `JSC::HeapSize` to be `Small` instead of the default `Large`.
+{% /details %}