express-generator-typescript 3.0.4 → 3.2.0

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

@@ -1,6 +1,22 @@
-import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
 
-import { agent } from './support/agent';
+import HttpStatusCodes from '#src/common/constants/HttpStatusCodes.ts';
+
+import { agent } from './support/agent.ts';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const STATIC_ASSETS = [
+  '/scripts/HttpClient.js',
+  '/scripts/renderUsers.js',
+  '/scripts/users.js',
+  '/scripts/lib/bootstrap.bundle.min.js',
+  '/stylesheets/users.css',
+  '/stylesheets/lib/bootstrap.min.css',
+] as const;
 
 // ========================================================================= //
 //                                   TESTS                                   //
@@ -9,25 +25,20 @@ import { agent } from './support/agent';
 describe('Front-end content', () => {
   it('should redirect "/" to the users page.', async () => {
     const res = await agent.get('/');
-    expect(res.status).toBe(HttpStatusCodes.FOUND);
-    expect(res.headers.location).toBe('/users');
+    assert.equal(res.status, HttpStatusCodes.FOUND);
+    assert.equal(res.headers.location, '/users');
   });
 
   it('should serve the users page.', async () => {
     const res = await agent.get('/users');
-    expect(res.status).toBe(HttpStatusCodes.OK);
-    expect(res.headers['content-type']).toMatch(/html/);
+    assert.equal(res.status, HttpStatusCodes.OK);
+    assert.match(res.headers['content-type'], /html/);
   });
 
-  it.each([
-    '/scripts/HttpClient.js',
-    '/scripts/renderUsers.js',
-    '/scripts/users.js',
-    '/scripts/lib/bootstrap.bundle.min.js',
-    '/stylesheets/users.css',
-    '/stylesheets/lib/bootstrap.min.css',
-  ])('should serve the static asset "%s".', async (asset) => {
-    const res = await agent.get(asset);
-    expect(res.status).toBe(HttpStatusCodes.OK);
-  });
+  for (const asset of STATIC_ASSETS) {
+    it(`should serve the static asset "${asset}".`, async () => {
+      const res = await agent.get(asset);
+      assert.equal(res.status, HttpStatusCodes.OK);
+    });
+  }
 });

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

@@ -1,9 +1,9 @@
+import { before } from 'node:test';
 import supertest, { type Test } from 'supertest';
 import type TestAgent from 'supertest/lib/agent.js';
-import { beforeAll } from 'vitest';
 
-import MockOrm from '@src/repos/MockOrm';
-import app from '@src/server';
+import MockOrm from '#src/repos/MockOrm.ts';
+import app from '#src/server.ts';
 
 // ========================================================================= //
 //                                   EXEC                                    //
@@ -11,7 +11,7 @@ import app from '@src/server';
 
 let agent: TestAgent<Test>;
 
-beforeAll(async () => {
+before(async () => {
   agent = supertest.agent(app);
   await MockOrm.cleanDb();
 });

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,50 @@
-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 assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+
+import HttpStatusCodes from '#src/common/constants/HttpStatusCodes.ts';
+import Paths from '#src/common/constants/Paths/index.ts';
+import User, { type UserEntity } from '#src/entities/User/index.ts';
+import UserRepo, { UserRepoTestOnly } from '#src/repos/UserRepo.ts';
+import UserService from '#src/services/UserService.ts';
+
+import { agent } from './support/agent.ts';
+import {
+  extractErrMsg,
+  type TypedErrRes,
+  type TypedRes,
+} from './support/utils.ts';
 
 // ========================================================================= //
 //                                 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;
 
@@ -47,85 +69,116 @@ describe('UserRouter', () => {
     dbUsers = await UserRepoTestOnly.insertMultiple(DUMMY_USERS);
   });
 
-  afterEach(() => {
-    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);
-        expect(res.status).toBe(OK);
-        const usersMatch = compareUserArrays(res.body.users, DUMMY_USERS);
-        expect(usersMatch).toBeTruthy();
+        const res: TypedRes<{ users: UserEntity[] }> = await agent.get(
+          P.Get.CALL,
+        );
+        assert.equal(res.status, OK);
+        assert.deepEqual(res.body.users, DUMMY_USERS);
       });
     });
 
     describe('when an unexpected error is thrown', () => {
-      it(`returns status "${INTERNAL_SERVER_ERROR}"`, async () => {
+      it(`returns status "${INTERNAL_SERVER_ERROR}"`, async (t) => {
         const error = new Error('boom');
-        const getAllSpy = vi.spyOn(UserService, 'getAll');
-        getAllSpy.mockRejectedValueOnce(error);
-        const res: TestRes = await agent.get(PATH_USERS_GET);
-        expect(res.status).toBe(INTERNAL_SERVER_ERROR);
-        expect(res.body.error).toBe('Internal Server Error');
+        // Mocks made through `t.mock` are restored when the test ends
+        t.mock.method(UserService, 'getAll', () => Promise.reject(error));
+        const res: TypedErrRes = await agent.get(P.Get.CALL);
+        assert.equal(res.status, INTERNAL_SERVER_ERROR);
+        assert.equal(res.body.error, '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);
-        expect(isId).toBe(true);
+        assert.equal(res.status, CREATED);
+        const isId = User.is.id(res.body.user.id);
+        assert.equal(isId, true);
         const all = await UserRepo.getAll();
-        expect(all).toHaveLength(DUMMY_USERS.length + 1);
-        expect(all).toContainEqual(res.body.user);
+        assert.equal(all.length, DUMMY_USERS.length + 1);
+        const saved = all.find((u) => u.id === res.body.user.id);
+        assert.deepEqual(saved, res.body.user);
       });
     });
 
     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 });
-        expect(res.status).toBe(BAD_REQUEST);
-        expect(res.body.error).toBe(ValidationError.MESSAGE);
-        expect(res.body.errors?.[0].key).toStrictEqual('user');
+        const res = await agent.post(P.Add.CALL).send({ user: null });
+        assert.equal(res.status, BAD_REQUEST);
+        const errMsg = extractErrMsg(res);
+        assert.equal(errMsg, '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);
+        assert.equal(res.status, BAD_REQUEST);
+        // Verify it didn't persist in the database
         const allUsers = await UserRepo.getAll();
-        expect(allUsers).toHaveLength(DUMMY_USERS.length);
+        assert.equal(allUsers.length, 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":');
+        assert.equal(res.status, BAD_REQUEST);
+        assert.deepEqual(res.body, { error: 'Invalid JSON' });
+        assert.deepEqual(await UserRepo.getAll(), DUMMY_USERS);
+      });
+
+      const oversizedBodies = [
+        [
+          'application/json',
+          JSON.stringify({ user: { name: 'a'.repeat(110000) } }),
+        ],
+        [
+          'application/x-www-form-urlencoded',
+          `user[name]=${'a'.repeat(110000)}`,
+        ],
+      ] as const;
+
+      for (const [contentType, body] of oversizedBodies) {
+        it(`returns 413 for an oversized ${contentType} body`, async () => {
+          const res: TypedErrRes = await agent
+            .post(P.Add.CALL)
+            .set('Content-Type', contentType)
+            .send(body);
+          assert.equal(res.status, HttpStatusCodes.PAYLOAD_TOO_LARGE);
+          assert.deepEqual(res.body, { error: 'Request body too large' });
+          assert.deepEqual(await UserRepo.getAll(), 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 });
-        expect(res.status).toBe(OK);
+        const res = await agent.put(P.Update.CALL).send({ user });
+        assert.equal(res.status, OK);
         const allUsers = await UserRepo.getAll();
         const saved = allUsers.find((u) => u.id === user.id);
-        expect(saved?.name).toBe('Bill');
+        assert.equal(saved?.name, 'Bill');
       });
     });
 
@@ -138,60 +191,60 @@ describe('UserRouter', () => {
           email: 'a@a.com',
           id: '5',
         };
-        const res: TestRes = await agent.put(PATH_USERS_UPDATE).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 res = await agent.put(P.Update.CALL).send({ user });
+        assert.equal(res.status, BAD_REQUEST);
+        const errMsg = extractErrMsg(res);
+        assert.equal(errMsg, 'Not a valid uuid7 id');
       });
     });
 
     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 });
-        expect(res.status).toBe(NOT_FOUND);
-        expect(res.body.error).toBe(ERR_USER_NOT_FOUND);
+        const user = User.create({ name: 'a', email: 'a@a.com' });
+        const res: TypedErrRes = await agent.put(P.Update.CALL).send({ user });
+        assert.equal(res.status, NOT_FOUND);
+        assert.equal(res.body.error, 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);
+        assert.equal(res.status, OK);
         const persists = await UserRepo.persists(id);
-        expect(persists).toBe(false);
+        assert.equal(persists, false);
       });
     });
 
     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);
-        expect(res.status).toBe(NOT_FOUND);
-        expect(res.body.error).toBe(ERR_USER_NOT_FOUND);
+        const id = User.genId();
+        const path = P.Delete.CALL(id);
+        const res: TypedErrRes = await agent.delete(path);
+        assert.equal(res.status, NOT_FOUND);
+        assert.equal(res.body.error, 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);
+        assert.equal(res.status, BAD_REQUEST);
       });
     });
 
     describe('when the id path param is missing', () => {
       it(`returns status "${BAD_REQUEST}"`, async () => {
-        const res: TestRes = await agent.delete(PATH_USERS_DELETE);
-        expect(res.status).toBe(BAD_REQUEST);
-        expect(res.body.errors?.[0].key).toStrictEqual('id');
+        const res = await agent.delete(P.Delete.FULL_PATH);
+        assert.equal(res.status, BAD_REQUEST);
+        const errMsg = extractErrMsg(res);
+        assert.equal(errMsg, 'Not a valid uuid7 id');
       });
     });
   });

package/lib/template/tsconfig.json

@@ -1,26 +1,23 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "esnext",
-    "moduleResolution": "bundler",
+    "module": "nodenext",
     "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
+    // Node runs the .ts files directly and tsc only typechecks, so imports
+    // name the .ts files
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    // Node strips types one file at a time, so type-only imports must say so
+    // and syntax that needs compiling (enums, namespaces...) isn't allowed
     "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
     "useUnknownInCatchVariables": false,
-    "types": ["node", "vitest/globals"]
+    "types": ["node"]
   },
-  "include": [
-    "src/**/*.ts",
-    "tests/**/*.ts",
-    "eslint.config.ts",
-    "vitest.config.ts"
-  ],
+  "include": ["src/**/*.ts", "tests/**/*.ts", "eslint.config.ts"],
   "exclude": ["src/public/*"]
 }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "express-generator-typescript",
-  "version": "3.0.4",
+  "version": "3.2.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": "node ../my-tools/src/workflows/commit/run.ts",
+    "_local:commit:push": "npm run _local:commit -- -p",
+    "_local:squash-history": "node ../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.18.0 || ^24.0.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",
@@ -53,7 +54,6 @@
     "express5",
     "server",
     "tooling",
-    "vitest",
     "eslint"
   ],
   "author": "sean maxwell",

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/UserRoutes.ts

@@ -1,74 +0,0 @@
-import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
-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                                    //
-// ========================================================================= //
-
-const validators = {
-  add: parseReq({ user: User.isInput }),
-  update: parseReq({ user: User.isComplete }),
-  delete: parseReq({ id: User.isId }),
-} as const;
-
-// ========================================================================= //
-//                                 FUNCTIONS                                 //
-// ========================================================================= //
-
-/**
- * Get all users.
- *
- * @route GET /api/users/all
- */
-async function getAll(_: Req, res: 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);
-  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);
-  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);
-  await UserService.deleteOne(id);
-  res.status(HttpStatusCodes.OK).end();
-}
-
-// ========================================================================= //
-//                                  EXPORT                                   //
-// ========================================================================= //
-
-export default {
-  getAll,
-  addOne,
-  updateOne,
-  deleteOne,
-} as const;

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;