express-generator-typescript 2.8.1 → 2.9.0

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

@@ -0,0 +1,71 @@
+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';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const DATABASE_FILE_PATH = path.join(
+  __dirname,
+  'common',
+  EnvVars.NodeEnv === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
+);
+
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+type Database = {
+  users: IUser[];
+};
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+// NOTE: Every write is a read-modify-write of one JSON file with no locking,
+// so concurrent requests can overwrite each other. Swap this module for a
+// real database before relying on it.
+
+/**
+ * Fetch the json from the file. A missing file is an empty database.
+ */
+async function openDb(): Promise<Database> {
+  let db: Partial<Database>;
+  try {
+    db = (await jsonfile.readFile(DATABASE_FILE_PATH)) as Partial<Database>;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    db = {};
+  }
+  return { users: db.users ?? [] };
+}
+
+/**
+ * Update the file, creating its folder if needed.
+ */
+async function saveDb(db: Database): Promise<void> {
+  await fs.mkdir(path.dirname(DATABASE_FILE_PATH), { recursive: true });
+  return jsonfile.writeFile(DATABASE_FILE_PATH, db, { spaces: 2 });
+}
+
+/**
+ * Empty the database
+ */
+function cleanDb(): Promise<void> {
+  return saveDb({ users: [] });
+}
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default {
+  openDb,
+  saveDb,
+  cleanDb,
+} as const;

package/lib/{project-files → template}/src/repos/UserRepo.ts

@@ -1,29 +1,18 @@
-import { getRandomInt } from '@src/common/utils/number-utils';
+import jetid from 'jet-id';
+
+import { getISOString } from '@src/common/utils/date-utils';
 import { IUser } from '@src/models/User.model';
 
 import orm from './MockOrm';
 
-/******************************************************************************
-                                Functions
-******************************************************************************/
-
-/**
- * Get one user.
- */
-async function getOne(email: string): Promise<IUser | null> {
-  const db = await orm.openDb();
-  for (const user of db.users) {
-    if (user.email === email) {
-      return user;
-    }
-  }
-  return null;
-}
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
 
 /**
  * See if a user with the given id exists.
  */
-async function persists(id: number): Promise<boolean> {
+async function persists(id: string): Promise<boolean> {
   const db = await orm.openDb();
   for (const user of db.users) {
     if (user.id === id) {
@@ -46,7 +35,6 @@ async function getAll(): Promise<IUser[]> {
  */
 async function add(user: IUser): Promise<void> {
   const db = await orm.openDb();
-  user.id = getRandomInt();
   db.users.push(user);
   return orm.saveDb(db);
 }
@@ -72,7 +60,7 @@ async function update(user: IUser): Promise<void> {
 /**
  * Delete one user.
  */
-async function delete_(id: number): Promise<void> {
+async function delete_(id: string): Promise<void> {
   const db = await orm.openDb();
   for (let i = 0; i < db.users.length; i++) {
     if (db.users[i].id === id) {
@@ -82,7 +70,7 @@ async function delete_(id: number): Promise<void> {
   }
 }
 
-// **** Unit-Tests Only **** //
+// ============================ Unit-tests Only ============================ //
 
 /**
  * @testOnly
@@ -98,29 +86,27 @@ async function deleteAllUsers(): Promise<void> {
 /**
  * @testOnly
  *
- * Insert multiple users. Can't do multiple at once cause using a plain file
- * for now.
+ * Insert copies of `users` with fresh ids; the inputs are not modified.
  */
 async function insertMultiple(
   users: IUser[] | readonly IUser[],
 ): Promise<IUser[]> {
-  const db = await orm.openDb(),
-    usersF = [...users];
-  for (const user of usersF) {
-    user.id = getRandomInt();
-    user.created = new Date();
-  }
-  db.users = [...db.users, ...users];
+  const db = await orm.openDb();
+  const inserted = users.map((user) => ({
+    ...user,
+    id: jetid(),
+    created: getISOString(),
+  }));
+  db.users = [...db.users, ...inserted];
   await orm.saveDb(db);
-  return usersF;
+  return inserted;
 }
 
-/******************************************************************************
-                                Export default
-******************************************************************************/
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
 
 export default {
-  getOne,
   persists,
   getAll,
   add,

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

@@ -0,0 +1,28 @@
+{
+  "users": [
+    {
+      "id": "2HF7W6BZV-23RYN-0GY0E-80X19N",
+      "name": "Sean Maxwell",
+      "email": "smaxwell@example.com",
+      "created": "2024-03-22T05:14:36.252Z"
+    },
+    {
+      "id": "56N1CSRF5-SG3XG-M7CEY-TE5G45",
+      "name": "John Smith",
+      "email": "john.smith@example.com",
+      "created": "2024-03-22T05:20:55.079Z"
+    },
+    {
+      "id": "Q78BTED9D-HBPJQ-GFEYQ-3EVFJF",
+      "name": "Gordan Freeman",
+      "email": "nova@prospect.com",
+      "created": "2024-03-22T05:42:18.895Z"
+    },
+    {
+      "id": "NEQXY1EYZ-66K6S-AMGXW-BWKYAY",
+      "name": "asdf",
+      "email": "asdf",
+      "created": "2026-09-25T22:31:30.844Z"
+    }
+  ]
+}

package/lib/{project-files → template}/src/routes/UserRoutes.ts

@@ -1,6 +1,3 @@
-import { isNumber } from 'jet-validators';
-import { transform } from 'jet-validators/utils';
-
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 import User from '@src/models/User.model';
 import UserService from '@src/services/UserService';
@@ -8,19 +5,19 @@ import UserService from '@src/services/UserService';
 import { Req, Res } from './common/express-types';
 import parseReq from './common/parseReq';
 
-/******************************************************************************
-                                Constants
-******************************************************************************/
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
 
 const reqValidators = {
-  add: parseReq({ user: User.isComplete }),
+  add: parseReq({ user: User.isInput }),
   update: parseReq({ user: User.isComplete }),
-  delete: parseReq({ id: transform(Number, isNumber) }),
+  delete: parseReq({ id: User.isId }),
 } as const;
 
-/******************************************************************************
-                                Functions
-******************************************************************************/
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
 
 /**
  * Get all users.
@@ -39,8 +36,8 @@ async function getAll(_: Req, res: Res) {
  */
 async function add(req: Req, res: Res) {
   const { user } = reqValidators.add(req.body);
-  await UserService.addOne(user);
-  res.status(HttpStatusCodes.CREATED).end();
+  const created = await UserService.addOne(user);
+  res.status(HttpStatusCodes.CREATED).json({ user: created });
 }
 
 /**
@@ -57,17 +54,17 @@ async function update(req: Req, res: Res) {
 /**
  * Delete one user.
  *
- * @route DELETE /api/users/delete/:id
+ * @route DELETE /api/users/delete?id=:id
  */
 async function delete_(req: Req, res: Res) {
-  const { id } = reqValidators.delete(req.params);
+  const { id } = reqValidators.delete(req.query);
   await UserService.delete(id);
   res.status(HttpStatusCodes.OK).end();
 }
 
-/******************************************************************************
-                                Export default
-******************************************************************************/
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
 
 export default {
   getAll,

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

@@ -0,0 +1,28 @@
+import { Router } from 'express';
+
+import Paths from '@src/common/constants/Paths';
+
+import UserRoutes from './UserRoutes';
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+const apiRouter = Router();
+
+// ============================ Add `userRouter` =========================== //
+
+const userRouter = Router();
+
+userRouter.get(Paths.Users.Get._, UserRoutes.getAll);
+userRouter.post(Paths.Users.Add._, UserRoutes.add);
+userRouter.put(Paths.Users.Update._, UserRoutes.update);
+userRouter.delete(Paths.Users.Delete._, UserRoutes.delete);
+
+apiRouter.use(Paths.Users._, userRouter);
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default apiRouter;

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

@@ -0,0 +1,9 @@
+import { 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

@@ -0,0 +1,23 @@
+import { parseObject, Schema } from 'jet-validators/utils';
+
+import { ValidationError } from '@src/common/utils/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;

package/lib/{project-files → template}/src/server.ts

@@ -4,19 +4,20 @@ import logger from 'jet-logger';
 import morgan from 'morgan';
 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 BaseRouter from '@src/routes/apiRouter';
 
 import EnvVars, { NodeEnvs } from './common/constants/env';
 
-/******************************************************************************
-                                Setup
-******************************************************************************/
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
 
 const app = express();
 
-// **** Middleware **** //
+// =============================== Middleware ============================== //
 
 // Basic middleware
 app.use(express.json());
@@ -35,22 +36,26 @@ if (EnvVars.NodeEnv === NodeEnvs.PRODUCTION) {
 // Add APIs, must be after middleware
 app.use(Paths._, BaseRouter);
 
-// Add error handler
-app.use((err: Error, _: Request, res: Response, next: NextFunction) => {
-  if (EnvVars.NodeEnv !== NodeEnvs.TEST.valueOf()) {
-    logger.err(err, true);
-  }
+// Add error handler. `_next` must stay: Express only treats 4-arg middleware
+// as an error handler.
+app.use((err: Error, _: Request, res: Response, _next: NextFunction) => {
   if (err instanceof RouteError) {
-    res.status(err.status).json({ error: err.message });
+    return res
+      .status(err.status)
+      .json({ error: err.message, errors: err.errors });
+  }
+  if (EnvVars.NodeEnv !== NodeEnvs.TEST) {
+    logger.err(err, true);
   }
-  return next(err);
+  return res
+    .status(HttpStatusCodes.INTERNAL_SERVER_ERROR)
+    .json({ error: 'Internal Server Error' });
 });
 
-// **** FrontEnd Content **** //
+// =========================== Front-end Content =========================== //
 
-// Set views directory (html)
+// Views directory (html)
 const viewsDir = path.join(__dirname, 'views');
-app.set('views', viewsDir);
 
 // Set static directory (js and css).
 const staticDir = path.join(__dirname, 'public');
@@ -61,13 +66,13 @@ app.get('/', (_: Request, res: Response) => {
   return res.redirect('/users');
 });
 
-// Redirect to login if not logged in.
+// Users page
 app.get('/users', (_: Request, res: Response) => {
   return res.sendFile('users.html', { root: viewsDir });
 });
 
-/******************************************************************************
-                                Export default
-******************************************************************************/
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
 
 export default app;

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

@@ -0,0 +1,66 @@
+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 UserRepo from '@src/repos/UserRepo';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const Errors = {
+  USER_NOT_FOUND: 'User not found',
+} as const;
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Get all users.
+ */
+function getAll(): Promise<IUser[]> {
+  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);
+  await UserRepo.add(user);
+  return user;
+}
+
+/**
+ * Update one user.
+ */
+async function updateOne(user: IUser): Promise<void> {
+  const persists = await UserRepo.persists(user.id);
+  if (!persists) {
+    throw new RouteError(HttpStatusCodes.NOT_FOUND, Errors.USER_NOT_FOUND);
+  }
+  return UserRepo.update(user);
+}
+
+/**
+ * Delete a user by their id.
+ */
+async function deleteOne(id: string): Promise<void> {
+  const persists = await UserRepo.persists(id);
+  if (!persists) {
+    throw new RouteError(HttpStatusCodes.NOT_FOUND, Errors.USER_NOT_FOUND);
+  }
+  return UserRepo.delete(id);
+}
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default {
+  Errors,
+  getAll,
+  addOne,
+  updateOne,
+  delete: deleteOne,
+} as const;

package/lib/{project-files → template}/src/views/users.html

@@ -7,8 +7,15 @@
     <link rel="stylesheet" type="text/css" href="stylesheets/users.css" />
 
     <!-- Bootstrap -->
-    <link href="stylesheets/lib/bootstrap.min.css" type="text/css" rel="stylesheet"/>
-    <script type="application/javascript" src="/scripts/lib/bootstrap.bundle.min.js"></script>
+    <link
+      href="stylesheets/lib/bootstrap.min.css"
+      type="text/css"
+      rel="stylesheet"
+    />
+    <script
+      type="application/javascript"
+      src="/scripts/lib/bootstrap.bundle.min.js"
+    ></script>
   </head>
 
   <!-- Body -->
@@ -42,9 +49,9 @@
       <div class="column-header">Users:</div>
       <div id="all-users-anchor"></div>
     </div>
-  </body>
 
-  <script src="/scripts/http.js"></script>
-  <script src="/scripts/render-users.js"></script>
-  <script src="/scripts/users.js"></script>
+    <script src="/scripts/http.js"></script>
+    <script src="/scripts/renderUsers.js"></script>
+    <script src="/scripts/users.js"></script>
+  </body>
 </html>

package/lib/{project-files → template}/tests/common/comparators.ts

@@ -1,14 +1,14 @@
 import { IUser } from '@src/models/User.model';
 
-/******************************************************************************
-                                Types
-******************************************************************************/
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
 
 type UserArray = IUser[] | readonly IUser[];
 
-/******************************************************************************
-                                Functions
-******************************************************************************/
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
 
 /**
  * Compare to user arrays. Order does not matter and this assumes the email

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

@@ -0,0 +1,11 @@
+import { ParseError } from 'jet-validators/utils';
+import { Response } from 'supertest';
+
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+// Use generics to add properties to 'body'
+export interface TestRes<T = object> extends Omit<Response, 'body'> {
+  body: T & { error?: string; errors?: ParseError[] };
+}

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

@@ -0,0 +1,33 @@
+import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
+
+import { agent } from './support/agent';
+
+// ========================================================================= //
+//                                   TESTS                                   //
+// ========================================================================= //
+
+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');
+  });
+
+  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/);
+  });
+
+  it.each([
+    '/scripts/http.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);
+  });
+});

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

@@ -0,0 +1,23 @@
+import supertest, { Test } from 'supertest';
+import TestAgent from 'supertest/lib/agent';
+import { beforeAll } from 'vitest';
+
+import MockOrm from '@src/repos/MockOrm';
+import app from '@src/server';
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+let agent: TestAgent<Test>;
+
+beforeAll(async () => {
+  agent = supertest.agent(app);
+  await MockOrm.cleanDb();
+});
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export { agent };