express-generator-typescript 3.0.4 → 3.2.0

package/lib/template/src/entities/User/module.ts

@@ -1,30 +1,45 @@
-import jetid from 'jet-id';
-
-import { getISOString, type ISOString } from '@src/common/utils/date-utils';
+import { v7 as uuidv7 } from 'uuid';
+import { z } from 'zod';
 
 import {
-  isCompleteUser,
-  isUserId,
-  isUserInput,
-  parseUser,
-} from './_internal/validators';
-import type { UserEntity } from './types';
+  getISOString,
+  type ISOString,
+  ISOStringSchema,
+} from '#src/common/utils/date.utils.ts';
+
+import type { UserEntity, UserInput } from './types.ts';
 
 // ========================================================================= //
-//                                 FUNCTIONS                                 //
+//                                 CONSTANTS                                 //
 // ========================================================================= //
 
-/**
- * Get a new `UserEntity` object with default values.
- */
-function getDefaults(): UserEntity {
-  return {
-    id: jetid(),
-    name: '',
-    email: '',
-    created: getISOString(),
-  };
-}
+/** @ValueFactoryFunction */
+const UserDefaults = () => ({
+  id: genId(),
+  name: '--',
+  email: '--@example.com',
+  created: getISOString(),
+});
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+const UserIdSchema = z.uuidv7('Not a valid uuid7 id');
+
+const UserInputSchema = z.object({
+  name: z.string().min(1, 'Name cannot be empty'),
+  email: z.email('Not a valid email'),
+}) satisfies z.ZodType<UserInput>;
+
+const UserSchema = UserInputSchema.extend({
+  id: UserIdSchema,
+  created: ISOStringSchema,
+}) satisfies z.ZodType<UserEntity>;
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
 
 /**
  * Factory-function.
@@ -32,9 +47,7 @@ function getDefaults(): UserEntity {
  * Create a `UserEntity` from a partial or `undefined`
  */
 function create(user?: Partial<UserEntity>): UserEntity {
-  return parseUser({ ...getDefaults(), ...user }, (errors) => {
-    throw new Error('Setup new user failed ' + JSON.stringify(errors, null, 2));
-  });
+  return { ...UserDefaults(), ...user };
 }
 
 /**
@@ -43,13 +56,41 @@ function create(user?: Partial<UserEntity>): UserEntity {
  * Create a `UserEntity` from individual properties
  */
 function of(name: string, email?: string, created?: ISOString): UserEntity {
-  const retVal = getDefaults();
+  const retVal = UserDefaults();
   if (name) retVal.name = name;
   if (email) retVal.email = email;
   if (created) retVal.created = created;
   return retVal;
 }
 
+/**
+ * Generate a uuid7 id.
+ */
+function genId(): string {
+  return uuidv7();
+}
+
+/**
+ * Check if a valid user object
+ */
+function isUser(val: unknown): val is UserEntity {
+  return UserSchema.safeParse(val).success;
+}
+
+/**
+ * Check if a valid end users input fields are valid.
+ */
+function isUserInput(val: unknown): val is UserInput {
+  return UserInputSchema.safeParse(val).success;
+}
+
+/**
+ * Test if an id is a valid user id.
+ */
+function isUserId(val: unknown): val is string {
+  return UserIdSchema.safeParse(val).success;
+}
+
 // ========================================================================= //
 //                                  EXPORT                                   //
 // ========================================================================= //
@@ -57,7 +98,15 @@ function of(name: string, email?: string, created?: ISOString): UserEntity {
 export default {
   of,
   create,
-  isId: isUserId,
-  isComplete: isCompleteUser,
-  isInput: isUserInput,
+  genId,
+  is: {
+    id: isUserId,
+    user: isUser,
+    input: isUserInput,
+  },
+  Schemas: {
+    Main: UserSchema,
+    Input: UserInputSchema,
+    Id: UserIdSchema,
+  },
 } as const;

package/lib/template/src/entities/User/types.ts

@@ -1,4 +1,4 @@
-import type { Entity } from '@src/entities/common/entity-base-types';
+import type { Entity } from '#src/entities/common/entity-base-types.ts';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/entities/common/entity-base-types.ts

@@ -1,4 +1,4 @@
-import type { ISOString } from '@src/common/utils/date-utils';
+import type { ISOString } from '#src/common/utils/date.utils.ts';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/main.ts

@@ -1,20 +1,20 @@
 import logger from 'jet-logger';
 
-import { EnvVars } from './common/constants/environment-consts';
-import server from './server';
+import { Env } from './common/constants/env.constants.ts';
+import server from './server.ts';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
-const SERVER_START_MESSAGE = `Express server started on port: ${EnvVars.PORT}`;
+const SERVER_START_MESSAGE = `Express server started on port: ${Env.PORT}`;
 
 // ========================================================================= //
 //                                   EXEC                                    //
 // ========================================================================= //
 
 // Start the server
-server.listen(EnvVars.PORT, (err) => {
+server.listen(Env.PORT, (err) => {
   if (!!err) {
     logger.err(err.message);
   } else {

package/lib/template/src/public/scripts/lib/bootstrap.bundle.min.js

@@ -4226,4 +4226,3 @@
     }
   );
 });
-//# sourceMappingURL=bootstrap.bundle.min.js.map

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

@@ -64,9 +64,6 @@ function onDocumentClick(event) {
 function addUser() {
   var nameInput = document.getElementById('name-input');
   var emailInput = document.getElementById('email-input');
-  if (!nameInput.value || !emailInput.value) {
-    return;
-  }
   var data = {
     user: {
       name: nameInput.value,
@@ -163,7 +160,7 @@ function deleteUser(ele) {
 // ============================= Shared Helpers ============================ //
 
 /**
- * Reject non-2xx responses with the server's error message.
+ * Log failed responses and their full JSON bodies, then reject the request.
  *
  * Used by:
  *   {@link displayUsers}
@@ -175,14 +172,25 @@ function deleteUser(ele) {
  * @returns {Response | Promise<never>} The response when it succeeded.
  */
 function checkResponse(resp) {
-  if (resp.ok) {
-    return resp;
-  }
+  if (resp.ok) return resp;
   return resp
     .json()
     .catch(() => ({}))
     .then((body) => {
-      throw new Error(body.error || 'Request failed: ' + resp.status);
+      throw JSON.stringify(
+        {
+          url: resp.url,
+          status: resp.status,
+          statusText: resp.statusText,
+          ok: resp.ok,
+          redirected: resp.redirected,
+          type: resp.type,
+          headers: Object.fromEntries(resp.headers.entries()),
+          body,
+        },
+        null,
+        2,
+      );
     });
 }
 
@@ -195,9 +203,10 @@ function checkResponse(resp) {
  *   {@link submitEdit}
  *   {@link deleteUser}
  *
- * @param {Error} err
+ * @param {string | Error} err
  * @returns {void}
  */
 function showError(err) {
-  alert(err.message);
+  document.getElementById('error-display').textContent =
+    typeof err === 'string' ? err : err.stack || err.message;
 }

package/lib/template/src/public/stylesheets/lib/bootstrap.min.css

@@ -11795,4 +11795,3 @@ fieldset:disabled .btn {
     display: none !important;
   }
 }
-/*# sourceMappingURL=bootstrap.min.css.map */

package/lib/template/src/public/stylesheets/users.css

@@ -1,4 +1,7 @@
 body {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 2em;
   padding: 100px;
   font:
     14px 'Lucida Grande',
@@ -9,7 +12,6 @@ body {
 
 body .users-column {
   display: inline-block;
-  margin-right: 2em;
   vertical-align: top;
 }
 
@@ -48,3 +50,24 @@ body .users-column .user-display-ele button {
 body .users-column .user-display-ele .edit-view {
   display: none;
 }
+
+/** Error Display Column **/
+
+body .errors-column {
+  flex: 1 1 320px;
+  min-width: 0;
+  color: #a61b29;
+}
+
+body .errors-column #error-display {
+  margin: 0;
+  padding: 16px;
+  border: 1px solid #e5a4aa;
+  border-radius: 6px;
+  background-color: #fff2f3;
+  color: inherit;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  max-height: 65vh;
+  overflow-y: auto;
+}

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

@@ -1,9 +1,8 @@
 import fs from 'fs/promises';
-import jsonfile from 'jsonfile';
 import path from 'path';
 
-import { EnvVars, NodeEnvs } from '@src/common/constants/environment-consts';
-import type { UserEntity } from '@src/entities/User';
+import { Env, NodeEnvs } from '#src/common/constants/env.constants.ts';
+import type { UserEntity } from '#src/entities/User/index.ts';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -12,7 +11,7 @@ import type { UserEntity } from '@src/entities/User';
 const DATABASE_FILE_PATH = path.join(
   import.meta.dirname,
   'common',
-  EnvVars.NODE_ENV === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
+  Env.NODE_ENV === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
 );
 
 // ========================================================================= //
@@ -37,7 +36,8 @@ type Database = {
 async function openDb(): Promise<Database> {
   let db: Partial<Database>;
   try {
-    db = (await jsonfile.readFile(DATABASE_FILE_PATH)) as Partial<Database>;
+    const json = await fs.readFile(DATABASE_FILE_PATH, 'utf8');
+    db = JSON.parse(json) as Partial<Database>;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
     db = {};
@@ -50,7 +50,7 @@ async function openDb(): Promise<Database> {
  */
 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 });
+  await fs.writeFile(DATABASE_FILE_PATH, JSON.stringify(db, null, 2) + '\n');
 }
 
 /**

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

@@ -1,9 +1,6 @@
-import jetid from 'jet-id';
+import { type UserEntity } from '#src/entities/User/index.ts';
 
-import { getISOString } from '@src/common/utils/date-utils';
-import type { UserEntity } from '@src/entities/User';
-
-import orm from './MockOrm';
+import orm from './MockOrm.ts';
 
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
@@ -15,9 +12,7 @@ import orm from './MockOrm';
 async function persists(id: string): Promise<boolean> {
   const db = await orm.openDb();
   for (const user of db.users) {
-    if (user.id === id) {
-      return true;
-    }
+    if (user.id === id) return true;
   }
   return false;
 }
@@ -27,7 +22,7 @@ async function persists(id: string): Promise<boolean> {
  */
 async function getAll(): Promise<UserEntity[]> {
   const db = await orm.openDb();
-  return db.users;
+  return db.users.sort((a, b) => a.id.localeCompare(b.id));
 }
 
 /**
@@ -92,14 +87,9 @@ async function insertMultiple(
   users: UserEntity[] | readonly UserEntity[],
 ): Promise<UserEntity[]> {
   const db = await orm.openDb();
-  const inserted = users.map((user) => ({
-    ...user,
-    id: jetid(),
-    created: getISOString(),
-  }));
-  db.users = [...db.users, ...inserted];
+  db.users = [...db.users, ...users];
   await orm.saveDb(db);
-  return inserted;
+  return [...users];
 }
 
 // ========================================================================= //

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}

@@ -1,8 +1,8 @@
 import { Router } from 'express';
 
-import Paths from '@src/common/constants/Paths';
+import Paths from '#src/common/constants/Paths/index.ts';
 
-import UserRoutes from './UserRoutes';
+import userRouter from './user.router.ts';
 
 // ========================================================================= //
 //                                   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/routers/user.router.ts

@@ -0,0 +1,65 @@
+import { Router } from 'express';
+import validate from 'express-zod-safe';
+
+import HttpStatusCodes from '#src/common/constants/HttpStatusCodes.ts';
+import Paths from '#src/common/constants/Paths/index.ts';
+import User from '#src/entities/User/index.ts';
+import UserService from '#src/services/UserService.ts';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+// 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;
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+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
+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
+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
+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 router;

package/lib/template/src/server.ts

@@ -8,12 +8,12 @@ import logger from 'jet-logger';
 import morgan from 'morgan';
 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 { RouteError } from '#src/common/classes/route-errors.ts';
+import HttpStatusCodes from '#src/common/constants/HttpStatusCodes.ts';
+import Paths from '#src/common/constants/Paths/index.ts';
+import BaseRouter from '#src/routers/api.router.ts';
 
-import { EnvVars, NodeEnvs } from './common/constants/environment-consts';
+import { Env, NodeEnvs } from './common/constants/env.constants.ts';
 
 // ========================================================================= //
 //                                   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,8 +77,8 @@ 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) {
-  const { setupLiveReload } = await import('@src/common/utils/dev-only');
+if (Env.NODE_ENV === NodeEnvs.DEVELOPMENT) {
+  const { setupLiveReload } = await import('#src/common/utils/dev-only.ts');
   setupLiveReload(app, [staticDir, viewsDir]);
 }
 

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

@@ -1,6 +1,9 @@
-import { NotFoundError } from '@src/common/classes/route-errors';
-import User, { type UserEntity, type UserInput } from '@src/entities/User';
-import UserRepo from '@src/repos/UserRepo';
+import { NotFoundError } from '#src/common/classes/route-errors.ts';
+import User, {
+  type UserEntity,
+  type UserInput,
+} from '#src/entities/User/index.ts';
+import UserRepo from '#src/repos/UserRepo.ts';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //

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>