express-generator-typescript 3.0.3 → 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
@@ -72,7 +72,9 @@ npm run dev
 
 The generated project is a small CRUD app for a `User` record. It shows how to structure models, services, and routes in Express + TypeScript. Linting, formatting, building, and hot reloading are all set up for you.
 
-### Available `package.json` Scripts
+---
+
+#### Available `package.json` scripts
 
 - `npm run dev` – Run the server in development with live reload and browser refresh.
 - `npm test` – Run the tests with Vitest.
@@ -84,7 +86,9 @@ The generated project is a small CRUD app for a `User` record. It shows how to s
 - `npm run typecheck` – Check for TypeScript errors without building.
 - `npm run install:clean` – Delete `node_modules` and the lockfile, then reinstall.
 
-### Architecture
+---
+
+#### Architecture
 
 The app uses a **layered** architecture, which suits a small CRUD app. If you plan to grow it, consider switching to a **domain-based** layout. The [Typescript Best Practices README](https://github.com/seanpmaxwell/Typescript-Best-Practices/tree/main?tab=readme-ov-file#architecture) explains both patterns.
 

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,8 +52,9 @@ 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)
-- **Environment variables**: [dotenv](https://github.com/motdotla/dotenv) loads `config/.env.*`, and [jet-env](https://github.com/seanpmaxwell/jet-env) validates them
+- **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)
 - **Linting**: [ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io/packages/typescript-eslint) and [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)

package/lib/template/package.json

@@ -14,20 +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-env": "^1.1.6",
-    "jet-id": "^1.3.1",
     "jet-logger": "3.0.0",
-    "jet-paths": "^4.0.2",
-    "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",
@@ -53,5 +52,8 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.2"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
   }
 }

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';
 
 // ========================================================================= //
@@ -26,12 +24,10 @@ export class RouteError extends Error {
 }
 
 /**
- * Request data failed schema validation.
+ * Don't have to manually pass `HttpStatusCodes.NOT_FOUND` each time.
  */
-export class ValidationError extends RouteError {
-  public static MESSAGE = 'Request validation failed.';
-
-  public constructor(errors: ParseError[]) {
-    super(HttpStatusCodes.BAD_REQUEST, ValidationError.MESSAGE, errors);
+export class NotFoundError extends RouteError {
+  public constructor(message: string) {
+    super(HttpStatusCodes.NOT_FOUND, message);
   }
 }

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

@@ -1,4 +1,4 @@
-import type { ValueOf } from '../types/utility-types';
+import type { ValueOf } from '../utils/validators';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -385,14 +385,9 @@ const HttpStatusCodes = {
   NETWORK_AUTHENTICATION_REQUIRED: 511,
 } as const;
 
-// ========================================================================= //
-//                                   TYPES                                   //
-// ========================================================================= //
-
-type HttpStatusCodes = ValueOf<typeof HttpStatusCodes>;
-
 // ========================================================================= //
 //                                  EXPORT                                   //
 // ========================================================================= //
 
+type HttpStatusCodes = ValueOf<typeof HttpStatusCodes>;
 export default HttpStatusCodes;

package/lib/template/src/common/constants/{Paths.ts → Paths/Paths.ts}

@@ -1,19 +1,26 @@
-import jetPaths from 'jet-paths';
+import { ep, pp } from './helpers';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
-const Paths = jetPaths({
-  _: '/api',
+const BASE = '/api';
+const USERS_BASE = '/users';
+const USERS = BASE + USERS_BASE;
+
+const Paths = {
+  PATH: BASE,
   Users: {
-    _: '/users',
-    Get: '/all',
-    Add: '/add',
-    Update: '/update',
-    Delete: '/delete',
+    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);
+} as const;
 
 // ========================================================================= //
 //                                  EXPORT                                   //

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/env.constants.ts

@@ -0,0 +1,42 @@
+/* eslint-disable no-process-env */
+import logger from 'jet-logger';
+import { z } from 'zod';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+// NOTE: These need to match the names of your ".env" files
+export const NodeEnvs = {
+  DEVELOPMENT: 'development',
+  TEST: 'test',
+  PRODUCTION: 'production',
+} as const;
+export type NodeEnvs = z.infer<typeof NodeEnvsEnum>;
+
+export const Env = {
+  NODE_ENV: process.env.NODE_ENV?.toLowerCase(),
+  PORT: Number(process.env.PORT),
+} as const;
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+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 {
+    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/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/User/types.ts

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

package/lib/template/src/entities/common/{types.ts → 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,21 +1,20 @@
 import logger from 'jet-logger';
 
-import { EnvVars } from './common/constants/env-inv';
+import { Env } from './common/constants/env.constants';
 import server from './server';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
-const SERVER_START_MESSAGE =
-  'Express server started on port: ' + EnvVars.Port.toString();
+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,
@@ -154,7 +151,7 @@ function submitEdit(ele) {
  */
 function deleteUser(ele) {
   var id = ele.getAttribute('data-user-id');
-  HttpClient.delete('/api/users/delete?id=' + encodeURIComponent(id))
+  HttpClient.delete('/api/users/delete/' + encodeURIComponent(id))
     .then(checkResponse)
     .then(() => displayUsers())
     .catch(showError);
@@ -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/env-inv';
+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.NodeEnv === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
+  Env.NODE_ENV === NodeEnvs.TEST ? 'database.test.json' : 'database.json',
 );
 
 // ========================================================================= //