express-generator-typescript 2.9.1 → 3.0.2

package/README.md

@@ -8,23 +8,23 @@
 [![npm downloads](https://img.shields.io/npm/dm/express-generator-typescript?color=orange)](https://www.npmjs.com/package/express-generator-typescript)
 [![License](https://img.shields.io/npm/l/express-generator-typescript)](https://github.com/seanpmaxwell/express-generator-typescript/blob/main/LICENSE)
 
-Command line tool which generates production-ready express templates with TypeScript baked in. Spin up a web server in seconds that follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices/blob/main/README.md).
+A command-line tool that generates production-ready Express projects with TypeScript built in. Spin up a web server in seconds that follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
 
 <p align="center">· · ·</p>
 
 ## 🧭 Overview 
 
-`express-generator-typescript` creates a new Express application similar to the classic `express-generator` package, but the generated project is fully wired for TypeScript. You get strict typing, linting, hot reloading, production builds, testing utilities, and sane defaults that focus on APIs (no view engine or opinionated ORM). Path aliases are preconfigured through `tsconfig-paths` and `_moduleAliases`, so referencing modules stays clean even as the app grows.
+`express-generator-typescript` works like the classic `express-generator` package, but the project it creates is fully set up for TypeScript. You get strict typing, linting, hot reloading, testing, and production builds, with defaults aimed at APIs. The project is an ES module and comes with an `@src/*` import alias, so imports stay clean as the app grows.
 
 <p align="center">· · ·</p>
 
 ## ✨ Features
 
-- **TypeScript-first** – strict compiler settings, linting, and sensible tsconfig defaults ready to go.
-- **API-centric** – no view engine or extra dependencies; ideal for SPAs, mobile backends, or services.
-- **Productivity tooling** – includes nodemon, ts-node, hot reload scripts, Vitest, ESLint, and production builds.
-- **Path aliases** – `@src/*` aliases configured in `tsconfig.json` (and `_moduleAliases` in `package.json` for production) so you can import modules cleanly.
-- **Keeps dependencies lean** – no bundled ORM or UI layers; only the essentials for Express + TS development.
+- **TypeScript-first** – strict compiler settings, linting, and sensible tsconfig defaults, ready to go.
+- **Built for APIs** – ideal for SPAs, mobile backends, or services.
+- **Fast development** – runs TypeScript directly with tsx (no build step), restarts the server when you change it, and refreshes the browser when you change front-end files. Vitest, ESLint, and production builds are included.
+- **Path aliases** – import from `@src/*` anywhere. It works in development, tests, and production builds.
+- **Lean dependencies** – no view engine, ORM, or UI layer; only the essentials for Express + TypeScript.
 
 <p align="center">· · ·</p>
 
@@ -52,65 +52,71 @@ cd my-api
 npm run dev
 ```
 
-Use `--use-yarn` if you prefer Yarn over npm. If you omit the project name, the generator creates `express-gen-ts`.
-
 <p align="center">· · ·</p>
 
 ## 🖥️ CLI Options
 
-| Option            | Description                                                                 |
-| ----------------- | --------------------------------------------------------------------------- |
-| `project name`    | Folder to create. Defaults to `express-gen-ts` if omitted.                  |
-| `--use-yarn`      | Installs dependencies with Yarn instead of npm.                             |
-| `--force`         | Writes into the target folder even if it is not empty (existing files with the same names are overwritten). |
-| `-h`, `--help`    | Shows usage.                                                                |
-| `-v`, `--version` | Shows the generator version.                                                |
+| Option            | Description                                                        |
+| ----------------- | ------------------------------------------------------------------ |
+| `project name`    | Folder to create. Defaults to `express-gen-ts`.                    |
+| `--use-yarn`      | Install dependencies with Yarn instead of npm.                     |
+| `--force`         | Write into a folder that isn't empty. Files with the same name are overwritten. |
+| `-h`, `--help`    | Show usage.                                                        |
+| `-v`, `--version` | Show the generator version.                                        |
 
-> The generator refuses to write into a folder that already has files in it, so it can't overwrite your work by accident.
+> Without `--force`, the generator won't write into a folder that already has files in it, so it can't overwrite your work by accident.
 
 <p align="center">· · ·</p>
 
 ## 🧩 Generated Template
 
-The generated template is a CRUD app for the `User` record to demonstrate model, services, and routing patterns in Express + TypeScript. Commands for linting, transpiling, formatting, and hot-reloading are all configured for you.
+The generated project is a small CRUD app for a `User` record. It shows how to structure models, services, and routes in Express + TypeScript. Linting, formatting, building, and hot reloading are all set up for you.
 
 ### Available `package.json` Scripts
 
-- `npm run dev` – Run the server in dev mode with live reload and browser refresh.
-- `npm run test` - Run tests with vitest.
-- `npm run test -- users.test.ts` – Target a single test file.
-- `npm run lint` – Run ESLint checks.
-- `npm run format` - Run prettier.
-- `npm run build` – Compile the project for production.
-- `npm start` – Serve the built project.
-- `npm run typecheck` – Run the TypeScript compiler without emitting files.
+- `npm run dev` – Run the server in development with live reload and browser refresh.
+- `npm test` – Run the tests with Vitest.
+- `npm test -- users.test.ts` – Run a single test file.
+- `npm run lint` – Check the code with ESLint.
+- `npm run format` – Format the code with Prettier.
+- `npm run build` – Build the project for production.
+- `npm start` – Run the production build.
+- `npm run typecheck` – Check for TypeScript errors without building.
 - `npm run install:clean` – Delete `node_modules` and the lockfile, then reinstall.
 
 ### Architecture
 
-Because this is a small CRUD app, **layered** is the architectural pattern of choice. However, you should consider switching to a **domain-based** layout if you plan on scaling. There is a good tutorial [here](https://github.com/seanpmaxwell/Typescript-Best-Practices/tree/main?tab=readme-ov-file#architecture) in the _Typescript Best Practices README_ about architectural patterns with TypeScript.
+The app uses a **layered** architecture, which suits a small CRUD app. If you plan to grow it, consider switching to a **domain-based** layout. The [Typescript Best Practices README](https://github.com/seanpmaxwell/Typescript-Best-Practices/tree/main?tab=readme-ov-file#architecture) explains both patterns.
 
 Layers explained:
-```yml
-- src/ <-- source code
-  - common/
+```md
+- config/         → .env files for each environment
+- src/            → Source code
+  - common/       → Shared code
+    - classes/    → Shared classes (e.g. route errors)
     - constants/
-      - Paths.ts <-- Single source of truth for all API routes
-  - routes/ <-- extracting and validating values from express Request/Response objects
-  - services/ <-- Business logic (where everything comes together)
-  - repos/ <-- Talking to the database layer
-  - models/ <-- For describing/handling objects representing database records
-- tests/ <-- unit-tests
+      - Paths.ts  → Single source of truth for all API routes
+    - types/      → Shared types
+    - utils/      → Shared helper functions
+  - entities/     → Describe and handle database records (one folder per entity)
+  - routes/       → Read and validate values from Express requests; send responses
+  - services/     → Business logic (where everything comes together)
+  - repos/        → Talk to the database
+  - public/       → Front-end scripts and styles
+  - views/        → HTML pages
+  - main.ts       → Starts the server
+  - server.ts     → Sets up the Express app
+- tests/          → Tests
 ```
 
 <p align="center">· · ·</p>
 
-## Notes for VSCode users
+## Notes for VS Code users
 
 <details>
 <summary>Format on save</summary>
 
-The generated template uses `eslint`+`prettier`, so if you want features like _formatting on save_, you need to make sure to install the prettier extension for VSCode and set it as your default formatter in `.vscode/setting.json`:
+The generated project uses ESLint for linting and Prettier for formatting. To format on save, install the Prettier extension for VS Code and set it as the default formatter in `.vscode/settings.json`:
 
 ```json
 // .vscode/settings.json
@@ -160,7 +166,7 @@ The generated template uses `eslint`+`prettier`, so if you want features like _f
 <details>
 <summary>Debugging</summary>
 
-If you want to debug in VSCode with breakpoints you need to start the processes through `.vscode/launch.json`:
+To debug with breakpoints in VS Code, start the app or tests from `.vscode/launch.json`:
 
 ```json
 // .vscode/launch.json
@@ -168,7 +174,7 @@ If you want to debug in VSCode with breakpoints you need to start the processes
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Dev - ts-node",
+      "name": "Dev",
       "type": "node",
       "request": "launch",
       "runtimeExecutable": "npm",

package/lib/template/README.md

@@ -2,32 +2,29 @@
 
 This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.12 or newer.
 
-<p align="center">· · ·</p>
+The original template follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
 
+<p align="center">· · ·</p>
 
 ## Available Scripts
 
-### `npm run install:clean`
-
-Remove the existing `node_modules/` folder, `package-lock.json`, and reinstall all library modules.
-
-### `npm run dev` 
+### `npm run dev`
 
-Run the server in development with hot reloading and browser refresh (see `package.json` for all `npm run dev` variations)<br/>
+Run the server in development at http://localhost:3000. The server restarts when you change server code, and the browser refreshes when you change server code or anything in `src/public` or `src/views`.
 
-**IMPORTANT** development mode uses `swc` for performance reasons which DOES NOT check for typescript errors. Run `npm run typecheck` to check for type errors. NOTE: you should use your IDE to prevent most type errors.
+> **Note:** development mode runs your `.ts` files directly with `tsx`, which doesn't check for TypeScript errors. Run `npm run typecheck` to check for them, and let your editor catch most of them as you work.
 
 ### `npm test`
 
-Run unit-tests with <a href="https://vitest.dev/guide/">vitest</a>.
+Run the tests with [Vitest](https://vitest.dev/guide/).
 
 ### `npm run lint`
 
-Check for linting errors.
+Check the code with ESLint.
 
 ### `npm run format`
 
-Format `src/` and `tests/` with prettier.
+Format `src/` and `tests/` with Prettier.
 
 ### `npm run build`
 
@@ -35,16 +32,37 @@ Build the project for production.
 
 ### `npm start`
 
-Run the production build (Must be built first).
+Run the production build. Run `npm run build` first.
 
 ### `npm run typecheck`
 
-Check for typescript errors.
+Check for TypeScript errors without building.
+
+### `npm run install:clean`
+
+Delete `node_modules/` and `package-lock.json`, then reinstall all dependencies.
 
 <p align="center">· · ·</p>
 
+## Tech Stack
+
+- **Language**: [TypeScript](https://www.typescriptlang.org/) (strict mode, ES modules)
+- **Web server framework**: [Express](https://expressjs.com/en/) (v5)
+- **Security headers**: [helmet](https://helmet.js.org/) (production only)
+- **Logging**
+  - **Request logging**: [morgan](https://github.com/expressjs/morgan) (development only)
+  - **General logging**: [jet-logger](https://github.com/seanpmaxwell/jet-logger)
+- **Validation**: [jet-validators](https://github.com/seanpmaxwell/jet-validators)
+- **Environment variables**: [dotenv](https://github.com/motdotla/dotenv) loads `config/.env.*`, and [jet-env](https://github.com/seanpmaxwell/jet-env) validates them
+- **Reloading**: [tsx](https://tsx.hirok.io) (`tsx watch` restarts the server) and [livereload](https://github.com/napcs/node-livereload) + [connect-livereload](https://github.com/intesso/connect-livereload) (refreshes the browser)
+- **Testing**: [Vitest](https://vitest.dev) + [Supertest](https://github.com/ladjs/supertest)
+- **Linting**: [ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io/packages/typescript-eslint) and [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)
+- **Formatting**: [Prettier](https://prettier.io) with [@trivago/prettier-plugin-sort-imports](https://github.com/trivago/prettier-plugin-sort-imports)
+- **Building**: `tsc` + [tsc-alias](https://github.com/justkey007/tsc-alias) (rewrites `@src/*` imports in `dist/`)
+
+<p align="center">· · ·</p>
 
 ## Additional Notes
 
-- `config/.env.production` is listed in `.gitignore` so production secrets don't get committed. Keep it out of version control and provide its values through your deployment tooling.
-- The database is a JSON file (`src/repos/common/database.json`, or `dist/repos/common/database.json` in production) meant only for the demo. It's created automatically if missing and isn't safe for concurrent writes, so replace `src/repos/MockOrm.ts` with a real database before going to production.
+- `config/.env.production` is in `.gitignore` so production secrets don't get committed. Keep it out of version control and supply its values through your deployment tooling.
+- The database is a JSON file meant only for the demo: `src/repos/common/database.json` in development, or `dist/repos/common/database.json` in production. It's created automatically if missing, but it isn't safe for simultaneous writes. Replace `src/repos/MockOrm.ts` with a real database before going to production.

package/lib/template/package.json

@@ -1,26 +1,21 @@
 {
   "name": "express-typescript-example",
-  "version": "0.1.0",
+  "version": "1.0.0",
+  "type": "module",
   "scripts": {
-    "build": "shx rm -rf dist && npm run lint && tsc --project tsconfig.prod.json && npm run build:copy-static",
+    "build": "shx rm -rf dist && npm run lint && tsc --project tsconfig.prod.json && tsc-alias -p tsconfig.prod.json && npm run build:copy-static",
     "build:copy-static": "shx mkdir -p dist/public dist/views && shx cp -r src/public/* dist/public && shx cp -r src/views/* dist/views",
     "install:clean": "shx rm -rf ./node_modules package-lock.json && npm i",
-    "dev:basic": "cross-env DOTENV_CONFIG_PATH=./config/.env.development ts-node ./src/main",
-    "dev:watch": "nodemon --exec \"npm run dev:basic\" --watch ./src --ext .ts",
-    "dev": "concurrently \"npm run dev:watch\" \"npm run sync\"",
+    "dev": "cross-env DOTENV_CONFIG_PATH=./config/.env.development tsx watch --import dotenv/config ./src/main.ts",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "start": "cross-env DOTENV_CONFIG_PATH=./config/.env.production node -r dotenv/config -r module-alias/register ./dist/main.js",
-    "sync": "delay 1s && browser-sync start --config bs-config.js",
+    "start": "cross-env DOTENV_CONFIG_PATH=./config/.env.production node --import dotenv/config ./dist/main.js",
     "test": "cross-env NODE_ENV=test vitest",
     "typecheck": "tsc -b --noEmit"
   },
   "engines": {
     "node": ">=22.12.0"
   },
-  "_moduleAliases": {
-    "@src": "dist"
-  },
   "dependencies": {
     "cross-env": "^10.1.0",
     "dotenv": "^18.0.4",
@@ -32,36 +27,31 @@
     "jet-paths": "^4.0.2",
     "jet-validators": "^2.3.1",
     "jsonfile": "^6.2.1",
-    "module-alias": "^2.3.4",
     "morgan": "^1.12.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@swc/core": "^1.16.2",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/connect-livereload": "^0.6.3",
     "@types/express": "^5.0.6",
     "@types/jsonfile": "^6.1.4",
+    "@types/livereload": "^0.9.5",
     "@types/morgan": "^1.9.10",
     "@types/node": "^26.6.2",
     "@types/supertest": "^7.2.1",
-    "browser-sync": "^3.0.4",
-    "concurrently": "^10.0.5",
-    "delay-cli": "^3.0.0",
+    "connect-livereload": "^0.6.1",
     "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^18.3.0",
     "jiti": "^2.7.0",
-    "nodemon": "^3.1.14",
+    "livereload": "^0.10.3",
     "prettier": "^3.9.9",
     "shx": "^0.4.0",
     "supertest": "^7.3.0",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
+    "tsc-alias": "^1.9.5",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.2"
-  },
-  "allowScripts": {
-    "@swc/core@1.16.2": true
   }
 }

package/lib/template/src/common/{utils → classes}/route-errors.ts

@@ -1,4 +1,4 @@
-import { ParseError } from 'jet-validators/utils';
+import type { ParseError } from 'jet-validators/utils';
 
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 

package/lib/template/src/common/constants/HttpStatusCodes.ts

@@ -1,4 +1,4 @@
-import { ValueOf } from '../types/utility-types';
+import type { ValueOf } from '../types/utility-types';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //

package/lib/template/src/common/constants/env-inv.ts

@@ -1,5 +1,6 @@
 import jetEnv, { num } from 'jet-env';
-import { ValueOf } from '../types/utility-types';
+
+import type { ValueOf } from '../types/utility-types';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //

package/lib/template/src/common/utils/dev-only.ts

@@ -0,0 +1,25 @@
+import connectLiveReload from 'connect-livereload';
+import type { Express } from 'express';
+import livereload from 'livereload';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Development only: refresh the browser when front-end files change, and
+ * after `tsx watch` restarts the server for a TypeScript change.
+ *
+ * Must be registered before the routes that serve html so the reload script
+ * gets injected into those pages.
+ */
+export function setupLiveReload(app: Express, watchDirs: string[]): void {
+  const server = livereload.createServer();
+  server.watch(watchDirs);
+  // A new process means the backend just restarted; reload once the browser
+  // reconnects so it picks up the new server code.
+  server.server.once('connection', () => {
+    setTimeout(() => server.refresh('/'), 100);
+  });
+  app.use(connectLiveReload());
+}

package/lib/template/src/entities/User/_internal/validators.ts

@@ -0,0 +1,47 @@
+import jetid from 'jet-id';
+import { isNonEmptyString, isString } from 'jet-validators';
+import { parseObject, type Schema, testObject } from 'jet-validators/utils';
+
+import { isISOString } from '@src/common/utils/date-utils';
+
+import type { UserEntity, UserInput } from '../types';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+const schema: Schema<UserEntity> = {
+  id: isUserId,
+  name: isString,
+  email: isString,
+  created: isISOString,
+};
+
+/**
+ * Validate the `User` schema.
+ */
+export const parseUser = parseObject<UserEntity>(schema);
+
+/**
+ * For the APIs make sure the right fields are complete
+ */
+export const isCompleteUser = testObject<UserEntity>({
+  ...schema,
+  name: isNonEmptyString,
+  email: isNonEmptyString,
+});
+
+/**
+ * Validate the fields a client sends to create a user.
+ */
+export const isUserInput = testObject<UserInput>({
+  name: isNonEmptyString,
+  email: isNonEmptyString,
+});
+
+/**
+ * Test if an id is a valid user id.
+ */
+export function isUserId(val: unknown): val is string {
+  return jetid.test(val);
+}

package/lib/template/src/entities/User/index.ts

@@ -0,0 +1,2 @@
+export { default as default } from './module';
+export type { UserEntity, UserInput } from './types';

package/lib/template/src/entities/User/module.ts

@@ -0,0 +1,63 @@
+import jetid from 'jet-id';
+
+import { getISOString, type ISOString } from '@src/common/utils/date-utils';
+
+import {
+  isCompleteUser,
+  isUserId,
+  isUserInput,
+  parseUser,
+} from './_internal/validators';
+import type { UserEntity } from './types';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Get a new `UserEntity` object with default values.
+ */
+function getDefaults(): UserEntity {
+  return {
+    id: jetid(),
+    name: '',
+    email: '',
+    created: getISOString(),
+  };
+}
+
+/**
+ * Factory-function.
+ *
+ * Create a `UserEntity` from a partial or `undefined`
+ */
+function create(user?: Partial<UserEntity>): UserEntity {
+  return parseUser({ ...getDefaults(), ...user }, (errors) => {
+    throw new Error('Setup new user failed ' + JSON.stringify(errors, null, 2));
+  });
+}
+
+/**
+ * Factory-function.
+ *
+ * Create a `UserEntity` from individual properties
+ */
+function of(name: string, email?: string, created?: ISOString): UserEntity {
+  const retVal = getDefaults();
+  if (name) retVal.name = name;
+  if (email) retVal.email = email;
+  if (created) retVal.created = created;
+  return retVal;
+}
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default {
+  of,
+  create,
+  isId: isUserId,
+  isComplete: isCompleteUser,
+  isInput: isUserInput,
+} as const;

package/lib/template/src/entities/User/types.ts

@@ -0,0 +1,18 @@
+import type { Entity } from '@src/entities/common/types';
+
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+/**
+ * @entity `users`
+ */
+export interface UserEntity extends Entity {
+  name: string;
+  email: string;
+}
+
+/**
+ * Fields a client supplies when creating a user; the server sets the rest.
+ */
+export type UserInput = Pick<UserEntity, 'name' | 'email'>;

package/lib/template/src/{models → entities}/common/types.ts

@@ -1,4 +1,4 @@
-import { ISOString } from "@src/common/utils/date-utils";
+import type { ISOString } from '@src/common/utils/date-utils';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/public/scripts/HttpClient.js

@@ -0,0 +1,59 @@
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+/**
+ * Thin wrapper around `fetch` for calling the JSON API. Each method sends and
+ * accepts JSON and resolves with the raw `Response`.
+ *
+ * @typedef {object} HttpClient
+ * @property {(path: string) => Promise<Response>} get
+ * @property {(path: string, data: unknown) => Promise<Response>} post - `data`
+ *   is sent as the JSON request body.
+ * @property {(path: string, data: unknown) => Promise<Response>} put - `data`
+ *   is sent as the JSON request body.
+ * @property {(path: string) => Promise<Response>} delete
+ */
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+/** @type {HttpClient} */
+var HttpClient = (() => {
+  /**
+   * Build `fetch` options for a JSON request.
+   *
+   * Used by:
+   *   {@link HttpClient.get}
+   *   {@link HttpClient.post}
+   *   {@link HttpClient.put}
+   *   {@link HttpClient.delete}
+   *
+   * @param {string} verb - HTTP method, e.g. "GET".
+   * @param {unknown} [data] - Request body; serialized to JSON when present.
+   * @returns {RequestInit}
+   */
+  var getOptions = (verb, data) => {
+    var options = {
+      dataType: 'json',
+      method: verb,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+    };
+    if (!!data) {
+      options.body = JSON.stringify(data);
+    }
+    return options;
+  };
+
+  // Set HttpClient methods
+  return {
+    get: (path) => fetch(path, getOptions('GET')),
+    post: (path, data) => fetch(path, getOptions('POST', data)),
+    put: (path, data) => fetch(path, getOptions('PUT', data)),
+    delete: (path) => fetch(path, getOptions('DELETE')),
+  };
+})();

package/lib/template/src/public/scripts/renderUsers.js

@@ -8,8 +8,6 @@ const DateFormatter = new Intl.DateTimeFormat('en-US', {
   day: '2-digit',
 });
 
-const formatDate = (date) => DateFormatter.format(new Date(date));
-
 const HTML_ESCAPES = {
   '&': '&',
   '<': '&lt;',
@@ -18,15 +16,29 @@ const HTML_ESCAPES = {
   "'": '&#39;',
 };
 
-// User data is untrusted, so escape it before it goes into innerHTML
-const esc = (val) => String(val).replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch]);
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+/**
+ * A user record as returned by the API.
+ *
+ * @typedef {object} User
+ * @property {string} id
+ * @property {string} name
+ * @property {string} email
+ * @property {string} created - ISO 8601 date string.
+ */
 
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
 // ========================================================================= //
 
 /**
- * Render users
+ * Build the HTML for the users list, including each user's edit form.
+ *
+ * @param {User[]} users
+ * @returns {string} HTML to assign to `innerHTML`.
  */
 function renderUsers(users) {
   return users
@@ -88,3 +100,29 @@ function renderUsers(users) {
     })
     .join('');
 }
+
+// ================================ Helpers ================================ //
+
+/**
+ * Format a date as MM/DD/YYYY.
+ *
+ * Used by: {@link renderUsers}
+ *
+ * @param {string | number | Date} date - Anything `new Date()` accepts.
+ * @returns {string}
+ */
+function formatDate(date) {
+  return DateFormatter.format(new Date(date));
+}
+
+/**
+ * User data is untrusted, so escape it before it goes into innerHTML.
+ *
+ * Used by: {@link renderUsers}
+ *
+ * @param {unknown} val - Converted to a string before escaping.
+ * @returns {string}
+ */
+function esc(val) {
+  return String(val).replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch]);
+}