express-generator-typescript 3.0.4 → 3.1.0

package/README.md

@@ -30,7 +30,7 @@ A command-line tool that generates production-ready Express projects with TypeSc
 
 ## 📦 Installation
 
-Requires Node.js 22.12 or newer.
+Requires Node.js 22.13+ (22.x), 24.x, or 26+.
 
 ```bash
 npx express-generator-typescript

package/bin/cli.js

@@ -3,14 +3,13 @@ const path = require('path');
 const { parseArgs } = require('util');
 
 const expressGenTs = require('../lib/express-generator-typescript');
-const { version, engines } = require('../package.json');
+const { version } = require('../package.json');
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
 const DEFAULT_DEST = 'express-gen-ts';
-const MIN_NODE = engines.node.replace(/^>=/, '');
 
 const HELP = `Usage: express-generator-typescript [project-name] [options]
 
@@ -62,7 +61,6 @@ async function main() {
   if (positionals.length > 1) {
     throw new Error('Expected at most one project name.\n\n' + HELP);
   }
-  assertNodeVersion();
 
   // ---- Run "express-generator-typescript"
   const dest = path.resolve(process.cwd(), positionals[0] ?? DEFAULT_DEST);
@@ -73,20 +71,3 @@ async function main() {
   });
   console.log('Project setup complete!');
 }
-
-/**
- * The generated project's tooling (vitest, eslint) requires a recent Node, so
- * fail fast instead of producing a project that can't run.
- *
- * @returns {void}
- */
-function assertNodeVersion() {
-  const toParts = (v) => v.split('.').map(Number);
-  const [maj, min] = toParts(process.versions.node);
-  const [reqMaj, reqMin] = toParts(MIN_NODE);
-  if (maj < reqMaj || (maj === reqMaj && min < reqMin)) {
-    throw new Error(
-      `Node ${MIN_NODE} or newer is required (found ${process.versions.node}).`,
-    );
-  }
-}

package/lib/template/README.md

@@ -1,6 +1,6 @@
 ## About
 
-This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.12 or newer.
+This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.13+ (22.x), 24.x, or 26+.
 
 The original template follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
 
@@ -52,7 +52,8 @@ Delete `node_modules/` and `package-lock.json`, then reinstall all dependencies.
 - **Logging**
   - **Request logging**: [morgan](https://github.com/expressjs/morgan) (development only)
   - **General logging**: [jet-logger](https://github.com/seanpmaxwell/jet-logger)
-- **Validation**: [jet-validators](https://github.com/seanpmaxwell/jet-validators)
+- **Validation**: [zod](https://github.com/colinhacks/zod)
+  - **Middleware Validation**: [express-zod-safe](https://github.com/AngaBlue/express-zod-safe)
 - **Environment variables**: [dotenv](https://github.com/motdotla/dotenv) loads `config/.env.*`
 - **Reloading**: [tsx](https://tsx.hirok.io) (`tsx watch` restarts the server) and [livereload](https://github.com/napcs/node-livereload) + [connect-livereload](https://github.com/intesso/connect-livereload) (refreshes the browser)
 - **Testing**: [Vitest](https://vitest.dev) + [Supertest](https://github.com/ladjs/supertest)

package/lib/template/package.json

@@ -14,19 +14,19 @@
     "typecheck": "tsc -b --noEmit"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.13.0 || ^24.0.0 || >=26.0.0"
   },
   "dependencies": {
     "cross-env": "^10.1.0",
     "dotenv": "^18.0.4",
     "express": "^5.2.1",
+    "express-zod-safe": "^3.2.1",
     "helmet": "^8.3.0",
-    "jet-id": "^1.3.1",
     "jet-logger": "3.0.0",
-    "jet-paths": "^4.1.3",
-    "jet-validators": "^2.3.1",
     "jsonfile": "^6.2.1",
-    "morgan": "^1.12.1"
+    "morgan": "^1.12.1",
+    "uuid": "^14.0.2",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/lib/template/src/common/classes/route-errors.ts

@@ -1,5 +1,3 @@
-import type { ParseError } from 'jet-validators/utils';
-
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 
 // ========================================================================= //
@@ -33,14 +31,3 @@ export class NotFoundError extends RouteError {
     super(HttpStatusCodes.NOT_FOUND, message);
   }
 }
-
-/**
- * Request data failed schema validation.
- */
-export class ValidationError extends RouteError {
-  public static MESSAGE = 'Request validation failed.';
-
-  public constructor(errors: ParseError[]) {
-    super(HttpStatusCodes.BAD_REQUEST, ValidationError.MESSAGE, errors);
-  }
-}

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

@@ -0,0 +1,29 @@
+import { ep, pp } from './helpers';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const BASE = '/api';
+const USERS_BASE = '/users';
+const USERS = BASE + USERS_BASE;
+
+const Paths = {
+  PATH: BASE,
+  Users: {
+    PATH: USERS_BASE,
+    Get: ep(USERS, '/all', 'GET'),
+    Add: ep(USERS, '/add', 'POST'),
+    Update: ep(USERS, '/update', 'PUT'),
+    Delete: {
+      ...ep(USERS, `/delete/:id`, 'DELETE'),
+      format: (id: string) => `${USERS}/delete/${pp(id)}`,
+    },
+  },
+} as const;
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default Paths;

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

@@ -0,0 +1,29 @@
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * `ep` stands for "Endpoint"
+ */
+export function ep<V extends HttpVerb>(base: string, path: string, verb: V) {
+  const template = `${base}${path}`;
+  return {
+    PATH: path,
+    FULL_PATH: template,
+    VERB: verb,
+    DISPLAY: `<${verb}>${template}`,
+  } as const;
+}
+
+/**
+ * `pp` stands for path params
+ */
+export function pp(param: string | number | boolean): string {
+  return encodeURIComponent(param);
+}

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

@@ -0,0 +1 @@
+export { default as default } from './Paths';

package/lib/template/src/common/constants/{environment-consts.ts → env.constants.ts}

@@ -1,7 +1,6 @@
 /* eslint-disable no-process-env */
 import logger from 'jet-logger';
-
-import { isNumber, isValueOf, type ValueOf } from '../utils/validators';
+import { z } from 'zod';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -13,9 +12,9 @@ export const NodeEnvs = {
   TEST: 'test',
   PRODUCTION: 'production',
 } as const;
-export type NodeEnvs = ValueOf<typeof NodeEnvs>;
+export type NodeEnvs = z.infer<typeof NodeEnvsEnum>;
 
-export const EnvVars = {
+export const Env = {
   NODE_ENV: process.env.NODE_ENV?.toLowerCase(),
   PORT: Number(process.env.PORT),
 } as const;
@@ -24,19 +23,18 @@ export const EnvVars = {
 //                                   EXEC                                    //
 // ========================================================================= //
 
-// ---- Validation
-// Validate the "environment variables"
+const NodeEnvsEnum = z.enum(NodeEnvs, 'Not a valid node environment');
+
+const EnvSchema = z.object({
+  NODE_ENV: NodeEnvsEnum,
+  PORT: z.uint32('Express port must be a positive integer'),
+});
+
+// ===================== Validate Environment Variables ==================== //
+
 {
   try {
-    const isNodeEnv = isValueOf(NodeEnvs);
-    if (!isNodeEnv(EnvVars.NODE_ENV)) {
-      throw new Error(
-        'process.env.NODE_ENV must be "development", "test", or "production"',
-      );
-    }
-    if (!isNumber(EnvVars.PORT)) {
-      throw new Error('process.env.PORT must be a valid number');
-    }
+    EnvSchema.parse(Env);
   } catch (err) {
     logger.err(err);
     throw err;

package/lib/template/src/common/utils/{date-utils.ts → date.utils.ts}

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 // ========================================================================= //
 //                                   TYPES                                   //
 // ========================================================================= //
@@ -5,6 +7,14 @@
 export type ISOString =
   `${number}-${number}-${number}T${number}:${number}:${number}${string}`;
 
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+export const ISOStringSchema = z.iso
+  .datetime()
+  .transform((value) => value as ISOString);
+
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
 // ========================================================================= //
@@ -15,15 +25,3 @@ export type ISOString =
 export function getISOString(date = new Date()): ISOString {
   return date.toISOString() as ISOString;
 }
-
-/**
- * Validate an ISOString.
- */
-export function isISOString(value: unknown): value is ISOString {
-  try {
-    const date = new Date(value as string);
-    return !isNaN(date.getTime()) && date.toISOString() === value;
-  } catch {
-    return false;
-  }
-}

package/lib/template/src/common/utils/validators.ts

@@ -3,26 +3,3 @@
 // ========================================================================= //
 
 export type ValueOf<T> = T[keyof T];
-type Table = Record<string, string> | Record<string, number>;
-
-// ========================================================================= //
-//                                   EXEC                                    //
-// ========================================================================= //
-
-/**
- * Check if an `unknown` is a number type.
- */
-export function isNumber<T>(val: T): val is Extract<T, number> {
-  return typeof val === 'number' && !isNaN(val);
-}
-
-/**
- * Check if an `unknown` is a value of an object.
- */
-export function isValueOf<T extends Table>(
-  table: T,
-): (v: unknown) => v is ValueOf<T> {
-  const vals = Object.values(table);
-  const set = new Set(vals);
-  return (val: unknown): val is ValueOf<T> => set.has(val);
-}

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';
+
+import type { UserEntity, UserInput } from './types';
 
 // ========================================================================= //
-//                                 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/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';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/main.ts

@@ -1,20 +1,20 @@
 import logger from 'jet-logger';
 
-import { EnvVars } from './common/constants/environment-consts';
+import { Env } from './common/constants/env.constants';
 import server from './server';
 
 // ========================================================================= //
 //                                 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

@@ -2,7 +2,7 @@ import fs from 'fs/promises';
 import jsonfile from 'jsonfile';
 import path from 'path';
 
-import { EnvVars, NodeEnvs } from '@src/common/constants/environment-consts';
+import { Env, NodeEnvs } from '@src/common/constants/env.constants';
 import type { UserEntity } from '@src/entities/User';
 
 // ========================================================================= //
@@ -12,7 +12,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',
 );
 
 // ========================================================================= //

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

@@ -1,7 +1,4 @@
-import jetid from 'jet-id';
-
-import { getISOString } from '@src/common/utils/date-utils';
-import type { UserEntity } from '@src/entities/User';
+import { type UserEntity } from '@src/entities/User';
 
 import orm from './MockOrm';
 
@@ -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];
 }
 
 // ========================================================================= //