express-generator-typescript 2.9.1 → 3.0.1

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

@@ -3,14 +3,14 @@ import jsonfile from 'jsonfile';
 import path from 'path';
 
 import { EnvVars, NodeEnvs } from '@src/common/constants/env-inv';
-import { IUser } from '@src/models/User.model';
+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,7 +10,7 @@ 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-inv';
@@ -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);

package/lib/template/tsconfig.json

@@ -1,27 +1,26 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "strict": true,
+    "target": "ES2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
     "esModuleInterop": true,
+    "lib": ["ES2022"],
+    "strict": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "paths": {
       "@src/*": ["./src/*"]
     },
+    // tsx transpiles one file at a time, so type-only imports must say so
+    "verbatimModuleSyntax": true,
     "useUnknownInCatchVariables": false,
-    "types": ["vitest/globals"]
-  },
-  "ts-node": {
-    "swc": true,
-    "require": ["tsconfig-paths/register", "dotenv/config"],
+    "types": ["node", "vitest/globals"]
   },
   "include": [
     "src/**/*.ts",
     "tests/**/*.ts",
     "eslint.config.ts",
-    "vitest.config.mts"
+    "vitest.config.ts"
   ],
   "exclude": ["src/public/*"]
 }

package/lib/template/tsconfig.prod.json

@@ -1,21 +1,30 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
-    "module": "CommonJS",
-    "lib": ["ES2020"],
+    "target": "ES2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "lib": ["ES2022"],
     "strict": true,
     "rootDir": "./src",
     "outDir": "dist",
-    "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "paths": {
       "@src/*": ["./src/*"]
     },
+    "verbatimModuleSyntax": true,
     "useUnknownInCatchVariables": false,
+    "types": ["node"],
     "sourceMap": false,
     "removeComments": true
   },
+  // After tsc, tsc-alias rewrites "@src/..." imports in dist/ to relative
+  // paths and adds the ".js" extensions Node's ESM loader requires (source
+  // imports are written without extensions)
+  "tsc-alias": {
+    "resolveFullPaths": true
+  },
   "include": ["src/**/*.ts"],
   "exclude": ["src/public/"]
 }

package/lib/template/{vitest.config.mts → vitest.config.ts}

@@ -1,7 +1,11 @@
 import path from 'path';
 import { defineConfig } from 'vitest/config';
 
-const config = defineConfig({
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
@@ -15,9 +19,7 @@ const config = defineConfig({
   },
   resolve: {
     alias: {
-      '@src': path.resolve(__dirname, './src'),
+      '@src': path.resolve(import.meta.dirname, './src'),
     },
   },
 });
-
-export default config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-generator-typescript",
-  "version": "2.9.1",
+  "version": "3.0.1",
   "description": "Generate new Express applications similar to express-generate which but sets it up to use TypeScript instead",
   "scripts": {
     "commit": "git add -A && git commit -m \"dev commit\"",

package/lib/template/bs-config.js

@@ -1,8 +0,0 @@
-module.exports = {
-  proxy: "http://localhost:3000/", // The address where your Express app runs
-  open: true, // Avoid reopening the browser on every nodemon restart
-  port: 3001, // The port BrowserSync will run on
-  files: ["src/**/*.*"], // Files to watch
-  ignore: ['**/node_modules/**', '**/repos/**/*.json'],
-  reloadDelay: 500, // Wait for nodemon to restart
-};