express-generator-typescript 3.0.4 → 3.1.0

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

@@ -1,19 +1,19 @@
 {
   "users": [
     {
-      "id": "2HF7W6BZV-23RYN-0GY0E-80X19N",
+      "id": "01a12230-a18b-721e-bf21-0ee836fa989d",
       "name": "Sean Maxwell",
       "email": "smaxwell@example.com",
       "created": "2024-03-22T05:14:36.252Z"
     },
     {
-      "id": "56N1CSRF5-SG3XG-M7CEY-TE5G45",
+      "id": "01a12230-a18c-7473-b1f0-845016f412d3",
       "name": "John Smith",
       "email": "john.smith@example.com",
       "created": "2024-03-22T05:20:55.079Z"
     },
     {
-      "id": "Q78BTED9D-HBPJQ-GFEYQ-3EVFJF",
+      "id": "01a12230-a18c-7473-b1f1-88ed3ea1d5ae",
       "name": "Gordan Freeman",
       "email": "nova@prospect.com",
       "created": "2024-03-22T05:42:18.895Z"

package/lib/template/src/{routes/apiRouter.ts → routers/api.router.ts}

@@ -2,7 +2,7 @@ import { Router } from 'express';
 
 import Paths from '@src/common/constants/Paths';
 
-import UserRoutes from './UserRoutes';
+import userRouter from './user.router';
 
 // ========================================================================= //
 //                                   EXEC                                    //
@@ -10,16 +10,8 @@ import UserRoutes from './UserRoutes';
 
 const apiRouter = Router();
 
-// ============================ Add `userRouter` =========================== //
-
-const userRouter = Router();
-
-userRouter.get(Paths.Users.Get.$path, UserRoutes.getAll);
-userRouter.post(Paths.Users.Add.$path, UserRoutes.addOne);
-userRouter.put(Paths.Users.Update.$path, UserRoutes.updateOne);
-userRouter.delete(Paths.Users.Delete.$path, UserRoutes.deleteOne);
-
-apiRouter.use(Paths.Users.$path, userRouter);
+// Add more routers as your app grows (e.g. `postsRouter`)
+apiRouter.use(Paths.Users.PATH, userRouter);
 
 // ========================================================================= //
 //                                  EXPORT                                   //

package/lib/template/src/{routes/UserRoutes.ts → routers/user.router.ts}

@@ -1,74 +1,65 @@
+import { Router } from 'express';
+import validate from 'express-zod-safe';
+
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
+import Paths from '@src/common/constants/Paths';
 import User from '@src/entities/User';
 import UserService from '@src/services/UserService';
 
-import type { Req, Res } from './common/express-types';
-import parseReq from './common/parseReq';
-
 // ========================================================================= //
-//                                   EXEC                                    //
+//                                 CONSTANTS                                 //
 // ========================================================================= //
 
-const validators = {
-  add: parseReq({ user: User.isInput }),
-  update: parseReq({ user: User.isComplete }),
-  delete: parseReq({ id: User.isId }),
+// Shorthand for the path strings
+const P = {
+  GET: Paths.Users.Get.PATH,
+  ADD: Paths.Users.Add.PATH,
+  UPDATE: Paths.Users.Update.PATH,
+  DELETE: Paths.Users.Delete.PATH,
+} as const;
+
+// Middlware `validators`
+const V = {
+  add: validate({ body: { user: User.Schemas.Input } }),
+  update: validate({ body: { user: User.Schemas.Main } }),
+  delete: validate({ params: { id: User.Schemas.Id } }),
 } as const;
 
 // ========================================================================= //
-//                                 FUNCTIONS                                 //
+//                                   EXEC                                    //
 // ========================================================================= //
 
-/**
- * Get all users.
- *
- * @route GET /api/users/all
- */
-async function getAll(_: Req, res: Res) {
+const router = Router();
+
+// Get all users
+router.get(P.GET, async (_, res) => {
   const users = await UserService.getAll();
   res.status(HttpStatusCodes.OK).json({ users });
-}
+});
 
-/**
- * Add one user.
- *
- * @route POST /api/users/add
- */
-async function addOne(req: Req, res: Res) {
-  const { user } = validators.add(req.body);
+// Add one user
+router.post(P.ADD, V.add, async (req, res) => {
+  const { user } = req.body;
   const created = await UserService.addOne(user);
   res.status(HttpStatusCodes.CREATED).json({ user: created });
-}
+});
 
-/**
- * Update one user.
- *
- * @route PUT /api/users/update
- */
-async function updateOne(req: Req, res: Res) {
-  const { user } = validators.update(req.body);
+// Update one user
+router.put(P.UPDATE, V.update, async (req, res) => {
+  const { user } = req.body;
   await UserService.updateOne(user);
   res.status(HttpStatusCodes.OK).end();
-}
+});
 
-/**
- * Delete one user.
- *
- * @route DELETE /api/users/delete/:id
- */
-async function deleteOne(req: Req, res: Res) {
-  const { id } = validators.delete(req.params);
+// Delete one user
+router.delete(P.DELETE, V.delete, async (req, res) => {
+  const { id } = req.params;
   await UserService.deleteOne(id);
   res.status(HttpStatusCodes.OK).end();
-}
+});
 
 // ========================================================================= //
 //                                  EXPORT                                   //
 // ========================================================================= //
 
-export default {
-  getAll,
-  addOne,
-  updateOne,
-  deleteOne,
-} as const;
+export default router;

package/lib/template/src/server.ts

@@ -11,9 +11,9 @@ import path from 'path';
 import { RouteError } from '@src/common/classes/route-errors';
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 import Paths from '@src/common/constants/Paths';
-import BaseRouter from '@src/routes/apiRouter';
+import BaseRouter from '@src/routers/api.router';
 
-import { EnvVars, NodeEnvs } from './common/constants/environment-consts';
+import { Env, NodeEnvs } from './common/constants/env.constants';
 
 // ========================================================================= //
 //                                   EXEC                                    //
@@ -28,17 +28,17 @@ app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
 // Show routes called in console during development
-if (EnvVars.NODE_ENV === NodeEnvs.DEVELOPMENT) {
+if (Env.NODE_ENV === NodeEnvs.DEVELOPMENT) {
   app.use(morgan('dev'));
 }
 
 // Security
-if (EnvVars.NODE_ENV === NodeEnvs.PRODUCTION) {
+if (Env.NODE_ENV === NodeEnvs.PRODUCTION) {
   app.use(helmet());
 }
 
 // Add APIs, must be after middleware
-app.use(Paths.$path, BaseRouter);
+app.use(Paths.PATH, BaseRouter);
 
 // Add error handler. `_next` must stay: Express only treats 4-arg middleware
 // as an error handler.
@@ -48,7 +48,20 @@ app.use((err: Error, _: Request, res: Response, _next: NextFunction) => {
       .status(err.status)
       .json({ error: err.message, errors: err.errors });
   }
-  if (EnvVars.NODE_ENV !== NodeEnvs.TEST) {
+  // Body-parser errors are client errors; don't expose the rejected body.
+  if ('type' in err) {
+    if (err.type === 'entity.parse.failed') {
+      return res
+        .status(HttpStatusCodes.BAD_REQUEST)
+        .json({ error: 'Invalid JSON' });
+    }
+    if (err.type === 'entity.too.large') {
+      return res
+        .status(HttpStatusCodes.PAYLOAD_TOO_LARGE)
+        .json({ error: 'Request body too large' });
+    }
+  }
+  if (Env.NODE_ENV !== NodeEnvs.TEST) {
     logger.err(err, true);
   }
   return res
@@ -64,7 +77,7 @@ 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.NODE_ENV === NodeEnvs.DEVELOPMENT) {
+if (Env.NODE_ENV === NodeEnvs.DEVELOPMENT) {
   const { setupLiveReload } = await import('@src/common/utils/dev-only');
   setupLiveReload(app, [staticDir, viewsDir]);
 }

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

@@ -3,6 +3,7 @@
   <!-- Head -->
   <head>
     <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Users</title>
     <link rel="stylesheet" type="text/css" href="stylesheets/users.css" />
 
@@ -50,6 +51,13 @@
       <div id="all-users-anchor"></div>
     </div>
 
+    <!-- Error Display -->
+    <aside class="users-column errors-column" aria-labelledby="errors-heading">
+      <div id="errors-heading" class="column-header">Error Messages:</div>
+      <pre id="error-display" role="status" aria-live="polite">
+No errors to display.</pre>
+    </aside>
+
     <script src="/scripts/HttpClient.js"></script>
     <script src="/scripts/renderUsers.js"></script>
     <script src="/scripts/users.js"></script>

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

@@ -0,0 +1,23 @@
+import type { Response } from 'supertest';
+
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+export type TypedRes<T> = Omit<Response, 'body'> & { body: T };
+export type TypedErrRes<T = 'string'> = TypedRes<{ error: T }>;
+
+interface ValidationError {
+  errors: { message: string }[];
+}
+
+// ========================================================================= //
+//                                  HELPERS                                  //
+// ========================================================================= //
+
+/**
+ * Get the error message from a superTest Response object.
+ */
+export function extractErrMsg(res: TypedRes<ValidationError[]>) {
+  return res.body[0].errors[0].message;
+}

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

@@ -1,28 +1,47 @@
-import jetid from 'jet-id';
-
-import { ValidationError } from '@src/common/classes/route-errors';
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 import Paths from '@src/common/constants/Paths';
 import User, { type UserEntity } from '@src/entities/User';
 import UserRepo, { UserRepoTestOnly } from '@src/repos/UserRepo';
 import UserService from '@src/services/UserService';
 
-import { compareUserArrays } from './common/comparators';
-import type { TestRes } from './common/supertest-types';
 import { agent } from './support/agent';
+import {
+  extractErrMsg,
+  type TypedErrRes,
+  type TypedRes,
+} from './support/utils';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
-// Path constants
-const PATH_USERS_GET = Paths.Users.Get();
-const PATH_USERS_ADD = Paths.Users.Add();
-const PATH_USERS_UPDATE = Paths.Users.Update();
-const PATH_USERS_DELETE = Paths.Users.Delete.$tmpl;
+// Shorthand the `Paths`
+const P = {
+  Get: {
+    CALL: Paths.Users.Get.FULL_PATH,
+    DISPLAY: Paths.Users.Get.DISPLAY,
+  },
+  Add: {
+    CALL: Paths.Users.Add.FULL_PATH,
+    DISPLAY: Paths.Users.Add.DISPLAY,
+  },
+  Update: {
+    CALL: Paths.Users.Update.FULL_PATH,
+    DISPLAY: Paths.Users.Update.DISPLAY,
+  },
+  Delete: {
+    CALL: Paths.Users.Delete.format,
+    DISPLAY: Paths.Users.Delete.DISPLAY,
+    FULL_PATH: Paths.Users.Delete.FULL_PATH,
+  },
+} as const;
 
 // Errors
-const ERR_USER_NOT_FOUND = UserService.Errors.USER_NOT_FOUND;
+const Errors = {
+  ...UserService.Errors,
+} as const;
+
+// Status codes
 const { BAD_REQUEST, CREATED, INTERNAL_SERVER_ERROR, OK, NOT_FOUND } =
   HttpStatusCodes;
 
@@ -51,15 +70,15 @@ describe('UserRouter', () => {
     vi.restoreAllMocks();
   });
 
-  // ---- `Get`
-  describe(`"GET - ${PATH_USERS_GET}"`, () => {
+  // --- `Get` ---
+  describe(P.Get.DISPLAY, () => {
     describe('on success', () => {
       it(`returns all users as JSON with status "${OK}"`, async () => {
-        const res: TestRes<{ users: UserEntity[] }> =
-          await agent.get(PATH_USERS_GET);
+        const res: TypedRes<{ users: UserEntity[] }> = await agent.get(
+          P.Get.CALL,
+        );
         expect(res.status).toBe(OK);
-        const usersMatch = compareUserArrays(res.body.users, DUMMY_USERS);
-        expect(usersMatch).toBeTruthy();
+        expect(res.body.users).toStrictEqual(DUMMY_USERS);
       });
     });
 
@@ -68,24 +87,24 @@ describe('UserRouter', () => {
         const error = new Error('boom');
         const getAllSpy = vi.spyOn(UserService, 'getAll');
         getAllSpy.mockRejectedValueOnce(error);
-        const res: TestRes = await agent.get(PATH_USERS_GET);
+        const res: TypedErrRes = await agent.get(P.Get.CALL);
         expect(res.status).toBe(INTERNAL_SERVER_ERROR);
         expect(res.body.error).toBe('Internal Server Error');
       });
     });
   });
 
-  // ---- `Add`
-  describe(`"POST - ${PATH_USERS_ADD}"`, () => {
+  // --- `Add` ---
+  describe(P.Add.DISPLAY, () => {
     describe('on success', () => {
       it(`persists the user and returns status "${CREATED}"`, async () => {
         // Same payload shape the front-end sends
         const input = { name: 'a', email: 'a@a.com' };
-        const res: TestRes<{ user: UserEntity }> = await agent
-          .post(PATH_USERS_ADD)
+        const res: TypedRes<{ user: UserEntity }> = await agent
+          .post(P.Add.CALL)
           .send({ user: input });
         expect(res.status).toBe(CREATED);
-        const isId = User.isId(res.body.user.id);
+        const isId = User.is.id(res.body.user.id);
         expect(isId).toBe(true);
         const all = await UserRepo.getAll();
         expect(all).toHaveLength(DUMMY_USERS.length + 1);
@@ -95,33 +114,63 @@ describe('UserRouter', () => {
 
     describe('when the user param is missing', () => {
       it('returns a validation error', async () => {
-        const res: TestRes = await agent
-          .post(PATH_USERS_ADD)
-          .send({ user: null });
+        const res = await agent.post(P.Add.CALL).send({ user: null });
         expect(res.status).toBe(BAD_REQUEST);
-        expect(res.body.error).toBe(ValidationError.MESSAGE);
-        expect(res.body.errors?.[0].key).toStrictEqual('user');
+        const errMsg = extractErrMsg(res);
+        expect(errMsg).toBe('Invalid input: expected object, received null');
       });
     });
 
     describe('when the name is empty', () => {
       it(`returns status "${BAD_REQUEST}"`, async () => {
-        const res: TestRes = await agent
-          .post(PATH_USERS_ADD)
+        const res = await agent
+          .post(P.Add.CALL)
           .send({ user: { name: '', email: 'a@a.com' } });
         expect(res.status).toBe(BAD_REQUEST);
+        // Verify it didn't persist in the database
         const allUsers = await UserRepo.getAll();
         expect(allUsers).toHaveLength(DUMMY_USERS.length);
       });
     });
+
+    describe('when the request body cannot be parsed', () => {
+      it('returns 400 for malformed JSON without persisting a user', async () => {
+        const res: TypedErrRes = await agent
+          .post(P.Add.CALL)
+          .set('Content-Type', 'application/json')
+          .send('{"user":');
+        expect(res.status).toBe(BAD_REQUEST);
+        expect(res.body).toStrictEqual({ error: 'Invalid JSON' });
+        expect(await UserRepo.getAll()).toStrictEqual(DUMMY_USERS);
+      });
+
+      it.each([
+        [
+          'application/json',
+          JSON.stringify({ user: { name: 'a'.repeat(110000) } }),
+        ],
+        [
+          'application/x-www-form-urlencoded',
+          `user[name]=${'a'.repeat(110000)}`,
+        ],
+      ])('returns 413 for an oversized %s body', async (contentType, body) => {
+        const res: TypedErrRes = await agent
+          .post(P.Add.CALL)
+          .set('Content-Type', contentType)
+          .send(body);
+        expect(res.status).toBe(HttpStatusCodes.PAYLOAD_TOO_LARGE);
+        expect(res.body).toStrictEqual({ error: 'Request body too large' });
+        expect(await UserRepo.getAll()).toStrictEqual(DUMMY_USERS);
+      });
+    });
   });
 
-  // ---- `Update`
-  describe(`"PUT - ${PATH_USERS_UPDATE}"`, () => {
+  // --- `Update` ---
+  describe(P.Update.DISPLAY, () => {
     describe('on success', () => {
       it(`saves the change and returns status "${OK}"`, async () => {
         const user = { ...dbUsers[0], name: 'Bill' };
-        const res = await agent.put(PATH_USERS_UPDATE).send({ user });
+        const res = await agent.put(P.Update.CALL).send({ user });
         expect(res.status).toBe(OK);
         const allUsers = await UserRepo.getAll();
         const saved = allUsers.find((u) => u.id === user.id);
@@ -138,30 +187,29 @@ describe('UserRouter', () => {
           email: 'a@a.com',
           id: '5',
         };
-        const res: TestRes = await agent.put(PATH_USERS_UPDATE).send({ user });
+        const res = await agent.put(P.Update.CALL).send({ user });
         expect(res.status).toBe(BAD_REQUEST);
-        expect(res.body.error).toBe(ValidationError.MESSAGE);
-        expect(res.body.errors?.[0].keyPath).toStrictEqual(['user', 'id']);
+        const errMsg = extractErrMsg(res);
+        expect(errMsg).toBe(errMsg);
       });
     });
 
     describe('when the user is not found', () => {
       it(`returns status "${NOT_FOUND}"`, async () => {
-        const id = jetid();
-        const user = User.create({ id, name: 'a', email: 'a@a.com' });
-        const res: TestRes = await agent.put(PATH_USERS_UPDATE).send({ user });
+        const user = User.create({ name: 'a', email: 'a@a.com' });
+        const res: TypedErrRes = await agent.put(P.Update.CALL).send({ user });
         expect(res.status).toBe(NOT_FOUND);
-        expect(res.body.error).toBe(ERR_USER_NOT_FOUND);
+        expect(res.body.error).toBe(Errors.USER_NOT_FOUND);
       });
     });
   });
 
-  // ---- `Delete`
-  describe(`"DELETE - ${PATH_USERS_DELETE}"`, () => {
+  // --- `Delete` ---
+  describe(P.Delete.DISPLAY, () => {
     describe('on success', () => {
       it(`removes the user and returns status "${OK}"`, async () => {
         const id = dbUsers[0].id;
-        const path = Paths.Users.Delete({ id });
+        const path = P.Delete.CALL(id);
         const res = await agent.delete(path);
         expect(res.status).toBe(OK);
         const persists = await UserRepo.persists(id);
@@ -171,17 +219,17 @@ describe('UserRouter', () => {
 
     describe('when the user is not found', () => {
       it(`returns status "${NOT_FOUND}"`, async () => {
-        const id = jetid();
-        const path = Paths.Users.Delete({ id });
-        const res: TestRes = await agent.delete(path);
+        const id = User.genId();
+        const path = P.Delete.CALL(id);
+        const res: TypedErrRes = await agent.delete(path);
         expect(res.status).toBe(NOT_FOUND);
-        expect(res.body.error).toBe(ERR_USER_NOT_FOUND);
+        expect(res.body.error).toBe(Errors.USER_NOT_FOUND);
       });
     });
 
     describe('when the id is invalid', () => {
       it(`returns status "${BAD_REQUEST}"`, async () => {
-        const path = Paths.Users.Delete({ id: -1 });
+        const path = P.Delete.CALL('asdf');
         const res = await agent.delete(path);
         expect(res.status).toBe(BAD_REQUEST);
       });
@@ -189,9 +237,10 @@ describe('UserRouter', () => {
 
     describe('when the id path param is missing', () => {
       it(`returns status "${BAD_REQUEST}"`, async () => {
-        const res: TestRes = await agent.delete(PATH_USERS_DELETE);
+        const res = await agent.delete(P.Delete.FULL_PATH);
         expect(res.status).toBe(BAD_REQUEST);
-        expect(res.body.errors?.[0].key).toStrictEqual('id');
+        const errMsg = extractErrMsg(res);
+        expect(errMsg).toStrictEqual('Not a valid uuid7 id');
       });
     });
   });

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "express-generator-typescript",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "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\"",
-    "commit:push": "npm run commit && git push",
     "install:clean": "rm -rf node_modules && rm -rf package-lock.json && npm i",
     "test": "node --test \"tests/**/*.test.js\"",
-    "test:e2e": "node scripts/e2e.js"
+    "test:e2e": "node scripts/e2e.js",
+    "_local:commit": "tsx --tsconfig ../my-tools/tsconfig.json ../my-tools/src/workflows/commit/run.ts",
+    "_local:commit:push": "npm run _local:commit -- -p",
+    "_local:squash-history": "tsx --tsconfig ../my-tools/tsconfig.json ../my-tools/src/workflows/squash-history/run.ts"
   },
   "main": "lib/express-generator-typescript.js",
   "bin": {
@@ -25,7 +26,7 @@
     "!lib/template/src/repos/common/database.test.json"
   ],
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.13.0 || ^24.0.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

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

@@ -1,16 +0,0 @@
-import jetPaths from 'jet-paths';
-
-// ========================================================================= //
-//                                  EXPORT                                   //
-// ========================================================================= //
-
-export default jetPaths({
-  $path: '/api',
-  Users: {
-    $path: '/users',
-    Get: '/all',
-    Add: '/add',
-    Update: '/update',
-    Delete: '/delete/:id',
-  },
-} as const);

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

@@ -1,47 +0,0 @@
-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/routes/common/express-types.ts

@@ -1,9 +0,0 @@
-import type { Request, Response } from 'express';
-
-// ========================================================================= //
-//                                   TYPES                                   //
-// ========================================================================= //
-
-// Body is `unknown` until it has been validated with `parseReq`.
-export type Req = Request<Record<string, string>, unknown, unknown>;
-export type Res = Response;

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

@@ -1,23 +0,0 @@
-import { parseObject, type Schema } from 'jet-validators/utils';
-
-import { ValidationError } from '@src/common/classes/route-errors';
-
-// ========================================================================= //
-//                                 FUNCTIONS                                 //
-// ========================================================================= //
-
-/**
- * Build a request parser for `schema` that throws a `ValidationError`
- * (400) listing every failed field.
- */
-function parseReq<U extends Schema>(schema: U) {
-  return parseObject(schema, (errors) => {
-    throw new ValidationError(errors);
-  });
-}
-
-// ========================================================================= //
-//                                  EXPORT                                   //
-// ========================================================================= //
-
-export default parseReq;