@alexmc2/create-express-api-starter 0.1.0

package/templates/ts/simple/src/middleware/errorHandler.ts.ejs

@@ -0,0 +1,49 @@
+<% if (educational) { %>// File overview: Converts thrown errors into consistent JSON HTTP responses for clients.
+<% } %>
+import type { ErrorRequestHandler } from 'express';
+
+interface HttpError extends Error {
+  status?: number;
+  code?: string;
+  detail?: string;
+}
+
+<% if (educational) { %>// Express treats middleware with four parameters as an error handler.
+// Any error passed to next(error) in the app is routed to this function.
+<% } %>const errorHandler: ErrorRequestHandler = (error: HttpError, _req, res, _next) => {
+<% if (educational) { %>  // PostgreSQL error code 23505 means a UNIQUE constraint was violated.
+  // Returning HTTP 409 tells clients that the request conflicts with existing data.
+<% } %>  if (error?.code === '23505') {
+    const detail = typeof error?.detail === 'string' ? error.detail : '';
+    const message = detail.includes('email')
+      ? 'A user with this email already exists.'
+      : 'A record with this value already exists.';
+
+    return res.status(409).json({
+      status: 409,
+      message
+    });
+  }
+
+  const status = Number.isInteger(error?.status) ? (error.status as number) : 500;
+  const message = typeof error?.message === 'string' ? error.message : 'Internal server error.';
+
+  const payload: {
+    status: number;
+    message: string;
+    stack?: string;
+  } = {
+    status,
+    message
+  };
+
+<% if (educational) { %>  // Include stack traces in development to speed up debugging.
+  // Omit them in production so internal implementation details stay private.
+<% } %>  if (process.env.NODE_ENV === 'development' && typeof error?.stack === 'string') {
+    payload.stack = error.stack;
+  }
+
+  res.status(status).json(payload);
+};
+
+export default errorHandler;

package/templates/ts/simple/src/middleware/notFound.ts.ejs

@@ -0,0 +1,13 @@
+<% if (educational) { %>// File overview: Handles unmatched routes by forwarding a 404 error to the central error handler.
+<% } %>
+import type { RequestHandler } from 'express';
+
+import AppError from '../errors/AppError';
+
+<% if (educational) { %>// This middleware runs only when no route matched the request.
+// It forwards a 404 error to the central error handler for a uniform response.
+<% } %>const notFound: RequestHandler = (_req, _res, next) => {
+  next(new AppError(404, 'Route not found.'));
+};
+
+export default notFound;

package/templates/ts/simple/src/repositories/usersRepository.ts.ejs

@@ -0,0 +1,87 @@
+<% if (educational) { %>// File overview: Encapsulates user data access so route code stays focused on HTTP concerns.
+<% } %>
+<% if (isPostgres) { %><% if (educational) { %>// Keep SQL statements in the repository so HTTP layers stay focused on requests
+// and responses. This separation makes the code easier to test and maintain.
+<% } %>import pool from '../db/pool';
+
+interface UserRow {
+  id: number;
+  name: string;
+  email: string | null;
+}
+
+interface CreateUserInput {
+  name: string;
+  email: string | null;
+}
+
+async function getAll(): Promise<UserRow[]> {
+  const result = await pool.query<UserRow>('SELECT id, name, email FROM users ORDER BY id ASC');
+  return result.rows;
+}
+
+async function create({ name, email }: CreateUserInput): Promise<UserRow> {
+<% if (educational) { %>  // Use parameter placeholders ($1, $2) so pg binds values safely.
+<% } %>  const result = await pool.query<UserRow>(
+    'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id, name, email',
+    [name, email]
+  );
+
+  return result.rows[0];
+}
+
+export default {
+  getAll,
+  create
+};
+<% } else { %><% if (educational) { %>// Keep data access in one place so the rest of the app does not depend on
+// storage details. This in-memory version can be replaced later with a real
+// database by changing this file only.
+<% } %>export interface User {
+  id: number;
+  name: string;
+  email: string | null;
+}
+
+interface CreateUserInput {
+  name: string;
+  email: string | null;
+}
+
+const users: User[] = [
+  {
+    id: 1,
+    name: 'Ada Lovelace',
+    email: 'ada@example.com'
+  },
+  {
+    id: 2,
+    name: 'Grace Hopper',
+    email: 'grace@example.com'
+  }
+];
+
+let nextId = users.length + 1;
+
+async function getAll(): Promise<User[]> {
+  return users;
+}
+
+async function create({ name, email }: CreateUserInput): Promise<User> {
+  const user: User = {
+    id: nextId,
+    name,
+    email
+  };
+
+  nextId += 1;
+  users.push(user);
+
+  return user;
+}
+
+export default {
+  getAll,
+  create
+};
+<% } %>

package/templates/ts/simple/src/routes/health.ts.ejs

@@ -0,0 +1,13 @@
+<% if (educational) { %>// File overview: Registers the health-check route used to confirm the API process is running.
+<% } %>
+import { Router } from 'express';
+
+const router = Router();
+
+<% if (educational) { %>// Health-check endpoint used by monitors, load balancers, and container
+// platforms to verify that the API process is running.
+<% } %>router.get('/', (_req, res) => {
+  res.status(200).json({ ok: true });
+});
+
+export default router;

package/templates/ts/simple/src/routes/users.ts.ejs

@@ -0,0 +1,43 @@
+<% if (educational) { %>// File overview: Defines /api/users routes, including request validation and repository calls.
+<% } %>
+import { Router } from 'express';
+
+import usersRepository from '../repositories/usersRepository';
+import AppError from '../errors/AppError';
+
+const router = Router();
+
+<% if (educational) { %>// Async route handlers should pass failures to next(error) so the
+// centralized error handler can return a consistent HTTP response.
+<% } %>router.get('/', async (_req, res, next) => {
+  try {
+    const users = await usersRepository.getAll();
+    res.status(200).json(users);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post('/', async (req, res, next) => {
+  try {
+<% if (educational) { %>    // Validate input at the API boundary before storing data.
+    // Calling next(error) skips the rest of the handler and moves control
+    // to the central error middleware, which formats the HTTP response.
+<% } %>    const { name, email } = req.body ?? {};
+
+    if (!name || typeof name !== 'string') {
+      return next(new AppError(400, '"name" is required.'));
+    }
+
+    const user = await usersRepository.create({
+      name: name.trim(),
+      email: typeof email === 'string' ? email.trim() : null
+    });
+
+    return res.status(201).json(user);
+  } catch (error) {
+    return next(error);
+  }
+});
+
+export default router;

package/templates/ts/simple/src/server.ts.ejs

@@ -0,0 +1,15 @@
+<% if (educational) { %>// File overview: Application entry point that loads environment variables and starts the HTTP server.
+<% } %>
+<% if (educational) { %>// Load variables from .env before other modules read process.env values.
+<% } %>import 'dotenv/config';
+
+import app from './app';
+import { getPort } from './utils/getPort';
+
+<% if (educational) { %>// Read the server port from PORT, defaulting to 3000 for local development.
+<% } %>const port = getPort(process.env.PORT, 3000);
+
+<% if (educational) { %>// Start the HTTP server and listen for incoming requests.
+<% } %>app.listen(port, () => {
+  console.log(`Server listening on port ${port}`);
+});

package/templates/ts/simple/src/utils/getPort.ts.ejs

@@ -0,0 +1,12 @@
+<% if (educational) { %>// File overview: Parses PORT into a usable integer with a safe fallback.
+<% } %>
+<% if (educational) { %>// Keep this helper small and pure so entrypoint code stays easy to scan.
+<% } %>export function getPort(value: string | undefined, fallback = 3000): number {
+  const parsed = Number(value);
+
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+
+  return fallback;
+}

package/templates/ts/simple/tsconfig.json.ejs

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "strict": true,
+    "target": "ES2022",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}