Modules & Project Structure

// Named exports - export specific items
export function formatDuration(ms: number): string { ... }

export interface User {
  id: string;
  name: string;
}

export const HISTORY_ON_JOIN = 5;

// Import named exports - curly braces, exact names
import { formatDuration, HISTORY_ON_JOIN } from "./config.js";
import type { User } from "./types.js";

import { ChatRoom } from "./model.js";        // a class: exists at runtime
import type { ChatClient } from "./types.js"; // an interface: gone at runtime

{
  "type": "module",
  "main": "dist/index.js",
  "bin":  { "chat-server": "dist/main.js" },
  "scripts": {
    "dev":   "tsx watch src/main.ts",
    "start": "node dist/main.js"
  }
}

// Default export - one per file, any name on import
export default class ChatServer { ... }
import ChatServer from "./server.js";     // any name works
import Banana from "./server.js";         // ...including this one

// Named export - exact names, enforced
export class ChatServer { ... }
import { ChatServer } from "./server.js";

src/
├── main.ts        ← entry point: build config, construct server, start it
├── index.ts       ← barrel: the public API. No side effects.
│
├── config.ts      ← ServerConfig, DEFAULTS, resolvePort
├── errors.ts      ← Result, ErrorCode, ChatError hierarchy, toSafeError
├── protocol.ts    ← ClientMessage, ServerMessage, decode/encode, validators
├── events.ts      ← TypedEmitter<T>, RingBuffer<T>, pluck - generic, domain-free
├── types.ts       ← the domain: ChatClient, User, Message. No behaviour.
│
├── model.ts       ← ChatRoom, ChatMessage. Know nothing of sockets.
├── state.ts       ← Registry: who is here, what rooms exist, the lookups
├── views.ts       ← projections: internal object → wire shape
├── bus.ts         ← ServerEvents map, ChatEvent, and every listener
├── handler.ts     ← MessageHandler: the chat rules. No socket anywhere.
│
├── clients.ts     ← BaseClient, TcpClient, WsClient - the two transports
├── page.ts        ← the browser client (a string)
├── http.ts        ← HttpService: parse, route, respond
└── server.ts      ← ChatServer: sockets, sniffing, the upgrade, lifecycle

events → errors → protocol → types → model → config → state → bus
       → clients → views → handler → page → http → server → index → main

import { HISTORY_ON_JOIN } from "./config.js";
import { asError, ChatError, NotFoundError, PermissionError, ... } from "./errors.js";
import { assertNever, CATALOG, COMMANDS, decodeClientMessage, ... } from "./protocol.js";
import { ChatMessage, type ChatRoom } from "./model.js";
import { isAdmin, type ChatClient } from "./types.js";
import { describeClient, describeRoom, summarize } from "./views.js";
import type { Bus } from "./bus.js";
import type { Registry } from "./state.js";

class FakeClient implements ChatClient {
  readonly outbox: ServerMessage[] = [];
  send(m: ServerMessage) { this.outbox.push(m); }
  // ...the rest of the interface
}

const registry = new Registry(configure(DEFAULTS, {}));
const handler = new MessageHandler(registry, createBus(registry));
const client = new FakeClient();

handler.welcome(client);
handler.handleLine(client, '{"type":"nick","name":"alice"}');
handler.handleLine(client, '{"type":"join","room":"general"}');
handler.handleLine(client, '{"type":"chat","text":"no socket was harmed"}');
handler.handleLine(client, '{"type":"join","room":"nowhere"}');

{"type":"welcome","id":"fake1","transport":"tcp","text":"Welcome. You are fake1. ..."}
{"type":"system","text":"You are now alice. You are an admin (level 2)."}
{"type":"joined","user":"alice","room":"general","members":1}
{"type":"history","room":"general","messages":[]}
{"type":"chat","sender":"alice","text":"no socket was harmed","room":"general","at":...}
{"type":"error","code":"unknown_room","message":"No such room \"nowhere\". Try: general, random, dev"}

const rooms = new Map<RoomName, ChatRoom>();
const clients = new Map<string, ChatClient>();
let sequence = 0;

export class MessageHandler {
  constructor(
    private readonly registry: Registry,
    private readonly bus: Bus,
  ) {}
}

// src/index.ts
export { ChatServer } from "./server.js";
export { ChatError, ErrorCode, ok, err } from "./errors.js";
export type { ClientMessage, ServerMessage } from "./protocol.js";

// The entry point. It builds a config, constructs a server, and starts it.
//
// That is all it does, and the shortness is the entire result of the chapter.
// Chapter 10's index.ts was 1,435 lines and did every job in the program. This
// file does one: it decides what to run and runs it.
//
// It is `main.ts`, not `index.ts`, and that is deliberate - see index.ts, which
// is the barrel. A file that *starts a server when you import it* cannot also be
// the file you import to get at the types.

import { configure, DEFAULTS, resolvePort } from "./config.js";
import { describeThrown } from "./errors.js";
import { ChatServer } from "./server.js";

const config = configure(DEFAULTS, { port: resolvePort(process.argv[2]) });
const server = new ChatServer(config);

// The last net, and it is worth being clear about what it is for.
//
// It is not a second error boundary. The boundary is in handler.ts, where there
// is still a client to answer and one request to abandon. By the time a throw
// gets here, nobody knows what was half-done - a room joined but not announced,
// a buffer consumed but not parsed - and a process running on state it cannot
// describe is worse than a process that stopped. So: say something useful, then
// die honestly. Restarting is somebody else's job, and they are better at it.
process.on("uncaughtException", (error: Error) => {
  console.error(`FATAL - nothing caught this: ${describeThrown(error)}`);
  process.exit(1);
});

process.on("unhandledRejection", (reason: unknown) => {
  console.error(`FATAL - a promise rejected with nobody listening: ${describeThrown(reason)}`);
  process.exit(1);
});

// Ctrl-C: stop accepting connections, hang up on everyone, then exit.
process.on("SIGINT", () => {
  server.shutdown(() => process.exit(0));
});

server.listen(() => {
  for (const line of server.banner()) {
    console.log(line);
  }
});

npm run build && npm start

nc 127.0.0.1 8080
{"type":"nick","name":"alice"}
{"type":"join","room":"general"}
{"type":"chat","text":"hello everyone"}