express-generator-typescript 2.9.0 → 3.0.1

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]);
+}

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

@@ -2,18 +2,25 @@
 //                                   EXEC                                    //
 // ========================================================================= //
 
-// Start
 displayUsers();
+document.addEventListener('click', onDocumentClick);
 
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
 // ========================================================================= //
 
 /**
- * Call api
+ * Fetch all users and render them into the page.
+ *
+ * Used by: @EXEC
+ *   {@link addUser}
+ *   {@link submitEdit}
+ *   {@link deleteUser}
+ *
+ * @returns {void}
  */
 function displayUsers() {
-  Http.get('/api/users/all')
+  HttpClient.get('/api/users/all')
     .then(checkResponse)
     .then((resp) => resp.json())
     .then((resp) => {
@@ -23,8 +30,16 @@ function displayUsers() {
     .catch(showError);
 }
 
-// Setup event listener for button click
-document.addEventListener('click', (event) => {
+// =========================== `onDocumentClick` =========================== //
+
+/**
+ * Route clicks on the page's buttons to their handlers.
+ *
+ * @listens click
+ * @param {MouseEvent} event
+ * @returns {void}
+ */
+function onDocumentClick(event) {
   var ele = event.target;
   if (ele.matches('#add-user-btn')) {
     addUser();
@@ -37,10 +52,14 @@ document.addEventListener('click', (event) => {
   } else if (ele.matches('.delete-user-btn')) {
     deleteUser(ele);
   }
-});
+}
 
 /**
- * Add a new user.
+ * Create a user from the "Add User" form, then refresh the list.
+ *
+ * Used by: {@link onDocumentClick}
+ *
+ * @returns {void}
  */
 function addUser() {
   var nameInput = document.getElementById('name-input');
@@ -54,7 +73,7 @@ function addUser() {
       email: emailInput.value,
     },
   };
-  Http.post('/api/users/add', data)
+  HttpClient.post('/api/users/add', data)
     .then(checkResponse)
     .then(() => {
       nameInput.value = '';
@@ -65,7 +84,12 @@ function addUser() {
 }
 
 /**
- * Show edit view.
+ * Switch a user's row to its edit form.
+ *
+ * Used by: {@link onDocumentClick}
+ *
+ * @param {HTMLElement} userEle - The `.user-display-ele` wrapper for the user.
+ * @returns {void}
  */
 function showEditView(userEle) {
   var normalView = userEle.getElementsByClassName('normal-view')[0];
@@ -75,7 +99,12 @@ function showEditView(userEle) {
 }
 
 /**
- * Cancel edit.
+ * Close a user's edit form without saving.
+ *
+ * Used by: {@link onDocumentClick}
+ *
+ * @param {HTMLElement} userEle - The `.user-display-ele` wrapper for the user.
+ * @returns {void}
  */
 function cancelEdit(userEle) {
   var normalView = userEle.getElementsByClassName('normal-view')[0];
@@ -85,7 +114,13 @@ function cancelEdit(userEle) {
 }
 
 /**
- * Submit edit.
+ * Save a user's edit form, then refresh the list.
+ *
+ * Used by: {@link onDocumentClick}
+ *
+ * @param {HTMLElement} ele - The clicked "Submit" button; carries the user's
+ *   id and created date in data attributes.
+ * @returns {void}
  */
 function submitEdit(ele) {
   var userEle = ele.parentNode.parentNode;
@@ -102,25 +137,42 @@ function submitEdit(ele) {
       created: ele.getAttribute('data-user-created'),
     },
   };
-  Http.put('/api/users/update', data)
+  HttpClient.put('/api/users/update', data)
     .then(checkResponse)
     .then(() => displayUsers())
     .catch(showError);
 }
 
 /**
- * Delete a user
+ * Delete a user, then refresh the list.
+ *
+ * Used by: {@link onDocumentClick}
+ *
+ * @param {HTMLElement} ele - The clicked "Delete" button; carries the user's
+ *   id in `data-user-id`.
+ * @returns {void}
  */
 function deleteUser(ele) {
   var id = ele.getAttribute('data-user-id');
-  Http.delete('/api/users/delete?id=' + encodeURIComponent(id))
+  HttpClient.delete('/api/users/delete?id=' + encodeURIComponent(id))
     .then(checkResponse)
     .then(() => displayUsers())
     .catch(showError);
 }
 
+// ============================= Shared Helpers ============================ //
+
 /**
  * Reject non-2xx responses with the server's error message.
+ *
+ * Used by:
+ *   {@link displayUsers}
+ *   {@link addUser}
+ *   {@link submitEdit}
+ *   {@link deleteUser}
+ *
+ * @param {Response} resp
+ * @returns {Response | Promise<never>} The response when it succeeded.
  */
 function checkResponse(resp) {
   if (resp.ok) {
@@ -136,6 +188,15 @@ function checkResponse(resp) {
 
 /**
  * Surface a failed request to the user.
+ *
+ * Used by:
+ *   {@link displayUsers}
+ *   {@link addUser}
+ *   {@link submitEdit}
+ *   {@link deleteUser}
+ *
+ * @param {Error} err
+ * @returns {void}
  */
 function showError(err) {
   alert(err.message);

package/lib/template/src/repos/MockOrm.ts

@@ -2,15 +2,15 @@ import fs from 'fs/promises';
 import jsonfile from 'jsonfile';
 import path from 'path';
 
-import EnvVars, { NodeEnvs } from '@src/common/constants/env';
-import { IUser } from '@src/models/User.model';
+import { EnvVars, NodeEnvs } from '@src/common/constants/env-inv';
+import type { UserEntity } from '@src/entities/User';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
 const DATABASE_FILE_PATH = path.join(
-  __dirname,
+  import.meta.dirname,
   'common',
   EnvVars.NodeEnv === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
 );
@@ -20,7 +20,7 @@ const DATABASE_FILE_PATH = path.join(
 // ========================================================================= //
 
 type Database = {
-  users: IUser[];
+  users: UserEntity[];
 };
 
 // ========================================================================= //

package/lib/template/src/repos/UserRepo.ts

@@ -1,7 +1,7 @@
 import jetid from 'jet-id';
 
 import { getISOString } from '@src/common/utils/date-utils';
-import { IUser } from '@src/models/User.model';
+import type { UserEntity } from '@src/entities/User';
 
 import orm from './MockOrm';
 
@@ -25,7 +25,7 @@ async function persists(id: string): Promise<boolean> {
 /**
  * Get all users.
  */
-async function getAll(): Promise<IUser[]> {
+async function getAll(): Promise<UserEntity[]> {
   const db = await orm.openDb();
   return db.users;
 }
@@ -33,7 +33,7 @@ async function getAll(): Promise<IUser[]> {
 /**
  * Add one user.
  */
-async function add(user: IUser): Promise<void> {
+async function add(user: UserEntity): Promise<void> {
   const db = await orm.openDb();
   db.users.push(user);
   return orm.saveDb(db);
@@ -42,7 +42,7 @@ async function add(user: IUser): Promise<void> {
 /**
  * Update a user.
  */
-async function update(user: IUser): Promise<void> {
+async function update(user: UserEntity): Promise<void> {
   const db = await orm.openDb();
   for (let i = 0; i < db.users.length; i++) {
     if (db.users[i].id === user.id) {
@@ -89,8 +89,8 @@ async function deleteAllUsers(): Promise<void> {
  * Insert copies of `users` with fresh ids; the inputs are not modified.
  */
 async function insertMultiple(
-  users: IUser[] | readonly IUser[],
-): Promise<IUser[]> {
+  users: UserEntity[] | readonly UserEntity[],
+): Promise<UserEntity[]> {
   const db = await orm.openDb();
   const inserted = users.map((user) => ({
     ...user,

package/lib/template/src/repos/common/database.json

@@ -19,10 +19,10 @@
       "created": "2024-03-22T05:42:18.895Z"
     },
     {
-      "id": "NEQXY1EYZ-66K6S-AMGXW-BWKYAY",
+      "id": "1S0KVJXSP-A7PXE-P15HN-KKFFNM",
       "name": "asdf",
       "email": "asdf",
-      "created": "2026-09-25T22:31:30.844Z"
+      "created": "2026-09-27T01:07:01.857Z"
     }
   ]
 }

package/lib/template/src/routes/UserRoutes.ts

@@ -1,8 +1,8 @@
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
-import User from '@src/models/User.model';
+import User from '@src/entities/User';
 import UserService from '@src/services/UserService';
 
-import { Req, Res } from './common/express-types';
+import type { Req, Res } from './common/express-types';
 import parseReq from './common/parseReq';
 
 // ========================================================================= //

package/lib/template/src/routes/common/express-types.ts

@@ -1,4 +1,4 @@
-import { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/routes/common/parseReq.ts

@@ -1,6 +1,6 @@
-import { parseObject, Schema } from 'jet-validators/utils';
+import { parseObject, type Schema } from 'jet-validators/utils';
 
-import { ValidationError } from '@src/common/utils/route-errors';
+import { ValidationError } from '@src/common/classes/route-errors';
 
 // ========================================================================= //
 //                                 FUNCTIONS                                 //

package/lib/template/src/server.ts

@@ -1,4 +1,8 @@
-import express, { NextFunction, Request, Response } from 'express';
+import express, {
+  type NextFunction,
+  type Request,
+  type Response,
+} from 'express';
 import helmet from 'helmet';
 import logger from 'jet-logger';
 import morgan from 'morgan';
@@ -6,10 +10,10 @@ import path from 'path';
 
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 import Paths from '@src/common/constants/Paths';
-import { RouteError } from '@src/common/utils/route-errors';
+import { RouteError } from '@src/common/classes/route-errors';
 import BaseRouter from '@src/routes/apiRouter';
 
-import EnvVars, { NodeEnvs } from './common/constants/env';
+import { EnvVars, NodeEnvs } from './common/constants/env-inv';
 
 // ========================================================================= //
 //                                   EXEC                                    //
@@ -55,10 +59,18 @@ app.use((err: Error, _: Request, res: Response, _next: NextFunction) => {
 // =========================== Front-end Content =========================== //
 
 // Views directory (html)
-const viewsDir = path.join(__dirname, 'views');
+const viewsDir = path.join(import.meta.dirname, 'views');
 
 // Set static directory (js and css).
-const staticDir = path.join(__dirname, 'public');
+const staticDir = path.join(import.meta.dirname, 'public');
+
+// Refresh the browser on changes. Imported lazily because livereload is a
+// dev dependency and isn't installed in production.
+if (EnvVars.NodeEnv === NodeEnvs.DEV) {
+  const { setupLiveReload } = await import('@src/common/utils/dev-only');
+  setupLiveReload(app, [staticDir, viewsDir]);
+}
+
 app.use(express.static(staticDir));
 
 // Nav to users pg by default

package/lib/template/src/services/UserService.ts

@@ -1,6 +1,6 @@
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
-import { RouteError } from '@src/common/utils/route-errors';
-import User, { IUser, IUserInput } from '@src/models/User.model';
+import { RouteError } from '@src/common/classes/route-errors';
+import User, { type UserEntity, type UserInput } from '@src/entities/User';
 import UserRepo from '@src/repos/UserRepo';
 
 // ========================================================================= //
@@ -18,15 +18,15 @@ const Errors = {
 /**
  * Get all users.
  */
-function getAll(): Promise<IUser[]> {
+function getAll(): Promise<UserEntity[]> {
   return UserRepo.getAll();
 }
 
 /**
  * Create a user from client input; the id and created date are set here.
  */
-async function addOne(input: IUserInput): Promise<IUser> {
-  const user = User.new(input);
+async function addOne(input: UserInput): Promise<UserEntity> {
+  const user = User.create(input);
   await UserRepo.add(user);
   return user;
 }
@@ -34,7 +34,7 @@ async function addOne(input: IUserInput): Promise<IUser> {
 /**
  * Update one user.
  */
-async function updateOne(user: IUser): Promise<void> {
+async function updateOne(user: UserEntity): Promise<void> {
   const persists = await UserRepo.persists(user.id);
   if (!persists) {
     throw new RouteError(HttpStatusCodes.NOT_FOUND, Errors.USER_NOT_FOUND);

package/lib/template/src/views/users.html

@@ -50,7 +50,7 @@
       <div id="all-users-anchor"></div>
     </div>
 
-    <script src="/scripts/http.js"></script>
+    <script src="/scripts/HttpClient.js"></script>
     <script src="/scripts/renderUsers.js"></script>
     <script src="/scripts/users.js"></script>
   </body>

package/lib/template/tests/common/comparators.ts

@@ -1,10 +1,10 @@
-import { IUser } from '@src/models/User.model';
+import type { UserEntity } from '@src/entities/User';
 
 // ========================================================================= //
 //                                   TYPES                                   //
 // ========================================================================= //
 
-type UserArray = IUser[] | readonly IUser[];
+type UserArray = UserEntity[] | readonly UserEntity[];
 
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
@@ -31,7 +31,7 @@ export function compareUserArrays(a: UserArray, b: UserArray): boolean {
 /**
  * Sort user array by email.
  */
-function sortByEmail(arr: UserArray): IUser[] {
+function sortByEmail(arr: UserArray): UserEntity[] {
   return [...arr].sort((x, y) => {
     return x.email.localeCompare(y.email);
   });

package/lib/template/tests/common/supertest-types.ts

@@ -1,5 +1,5 @@
-import { ParseError } from 'jet-validators/utils';
-import { Response } from 'supertest';
+import type { ParseError } from 'jet-validators/utils';
+import type { Response } from 'supertest';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/tests/frontend.test.ts

@@ -20,7 +20,7 @@ describe('Front-end content', () => {
   });
 
   it.each([
-    '/scripts/http.js',
+    '/scripts/HttpClient.js',
     '/scripts/renderUsers.js',
     '/scripts/users.js',
     '/scripts/lib/bootstrap.bundle.min.js',

package/lib/template/tests/support/agent.ts

@@ -1,5 +1,5 @@
-import supertest, { Test } from 'supertest';
-import TestAgent from 'supertest/lib/agent';
+import supertest, { type Test } from 'supertest';
+import type TestAgent from 'supertest/lib/agent.js';
 import { beforeAll } from 'vitest';
 
 import MockOrm from '@src/repos/MockOrm';

package/lib/template/tests/users.test.ts

@@ -2,13 +2,13 @@ import jetid from 'jet-id';
 
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 import Paths from '@src/common/constants/Paths';
-import { ValidationError } from '@src/common/utils/route-errors';
-import User, { IUser } from '@src/models/User.model';
+import { ValidationError } from '@src/common/classes/route-errors';
+import User, { type UserEntity } from '@src/entities/User';
 import UserRepo from '@src/repos/UserRepo';
 import UserService from '@src/services/UserService';
 
 import { compareUserArrays } from './common/comparators';
-import { TestRes } from './common/supertest-types';
+import type { TestRes } from './common/supertest-types';
 import { agent } from './support/agent';
 
 // ========================================================================= //
@@ -16,9 +16,9 @@ import { agent } from './support/agent';
 // ========================================================================= //
 
 const DUMMY_USERS = [
-  User.new({ name: 'Sean Maxwell', email: 'sean.maxwell@gmail.com' }),
-  User.new({ name: 'John Smith', email: 'john.smith@gmail.com' }),
-  User.new({ name: 'Gordan Freeman', email: 'gordan.freeman@gmail.com' }),
+  User.of('Sean Maxwell', 'sean.maxwell@gmail.com'),
+  User.of('John Smith', 'john.smith@gmail.com'),
+  User.of('Gordan Freeman', 'gordan.freeman@gmail.com'),
 ] as const;
 
 const { BAD_REQUEST, CREATED, INTERNAL_SERVER_ERROR, OK, NOT_FOUND } =
@@ -32,7 +32,7 @@ const { BAD_REQUEST, CREATED, INTERNAL_SERVER_ERROR, OK, NOT_FOUND } =
 //  scenarios (i.e. a failed database connection).
 
 describe('UserRouter', () => {
-  let dbUsers: IUser[] = [];
+  let dbUsers: UserEntity[] = [];
 
   beforeEach(async () => {
     await UserRepo.deleteAllUsers();
@@ -49,7 +49,7 @@ describe('UserRouter', () => {
       'should return a JSON object with all the users and a status code of ' +
         `"${OK}" if the request was successful.`,
       async () => {
-        const res: TestRes<{ users: IUser[] }> = await agent.get(
+        const res: TestRes<{ users: UserEntity[] }> = await agent.get(
           Paths.Users.Get(),
         );
         expect(res.status).toBe(OK);
@@ -79,7 +79,7 @@ describe('UserRouter', () => {
       async () => {
         // Same payload shape the front-end sends
         const input = { name: 'a', email: 'a@a.com' };
-        const res: TestRes<{ user: IUser }> = await agent
+        const res: TestRes<{ user: UserEntity }> = await agent
           .post(Paths.Users.Add())
           .send({ user: input });
         expect(res.status).toBe(CREATED);
@@ -134,7 +134,7 @@ describe('UserRouter', () => {
       'should return a JSON object with an error message and a status code ' +
         `of "${BAD_REQUEST}" if id is not a valid id`,
       async () => {
-        const user = { ...User.new(), name: 'a', email: 'a@a.com', id: '5' };
+        const user = { ...User.create(), name: 'a', email: 'a@a.com', id: '5' };
         const res: TestRes = await agent
           .put(Paths.Users.Update())
           .send({ user });
@@ -149,7 +149,7 @@ describe('UserRouter', () => {
         `"${UserService.Errors.USER_NOT_FOUND}" and a status code of ` +
         `"${NOT_FOUND}" if the id was not found.`,
       async () => {
-        const user = User.new({ id: jetid(), name: 'a', email: 'a@a.com' }),
+        const user = User.create({ id: jetid(), name: 'a', email: 'a@a.com' }),
           res: TestRes = await agent.put(Paths.Users.Update()).send({ user });
         expect(res.status).toBe(NOT_FOUND);
         expect(res.body.error).toBe(UserService.Errors.USER_NOT_FOUND);