@alexmc2/create-express-api-starter 0.1.0

package/templates/ts/mvc/scripts/dbCreate.js.ejs

@@ -0,0 +1,93 @@
+<% if (educational) { %>// File overview: Creates the target PostgreSQL database if it does not already exist.
+<% } %>
+require('dotenv').config();
+
+const { Pool } = require('pg');
+
+async function run() {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL is not set.');
+    console.error('Make sure you have a .env file with DATABASE_URL defined.');
+    console.error('You can copy .env.example to .env to get started.');
+    process.exit(1);
+  }
+
+<% if (educational) { %>  // Extract the database name from DATABASE_URL.
+  // This is the path segment that appears after host and port.
+<% } %>  const url = new URL(databaseUrl);
+  const dbName = url.pathname.slice(1);
+
+  if (!dbName) {
+    console.error('Error: DATABASE_URL does not contain a database name.');
+    process.exit(1);
+  }
+
+<% if (educational) { %>  // Validate the database name before interpolation.
+  // SQL identifiers cannot use parameter placeholders, so we restrict
+  // allowed characters to a safe subset.
+<% } %>  if (!/^[a-zA-Z0-9_-]+$/.test(dbName)) {
+    console.error(`Error: Database name "${dbName}" contains invalid characters.`);
+    console.error('Use only letters, numbers, hyphens, and underscores.');
+    process.exit(1);
+  }
+
+<% if (educational) { %>  // Connect to the default "postgres" database, then create the target one.
+<% } %>  url.pathname = '/postgres';
+  const pool = new Pool({ connectionString: url.toString() });
+
+  try {
+    const result = await pool.query(
+      'SELECT 1 FROM pg_database WHERE datname = $1',
+      [dbName]
+    );
+
+    if (result.rows.length > 0) {
+      console.log(`Database "${dbName}" already exists.`);
+      return;
+    }
+
+    await pool.query(`CREATE DATABASE "${dbName}"`);
+    console.log(`Database "${dbName}" created.`);
+  } finally {
+    await pool.end();
+  }
+}
+
+run().catch((error) => {
+  const message =
+    error && typeof error === 'object' && typeof error.message === 'string'
+      ? error.message
+      : typeof error === 'string'
+        ? error
+        : String(error);
+  const code =
+    error && typeof error === 'object' && typeof error.code === 'string'
+      ? error.code
+      : '';
+
+  console.error('Failed to create database:', message);
+  console.error('');
+
+  const authError = message.includes('password') || message.includes('SCRAM');
+  const connectionRefused =
+    message.includes('ECONNREFUSED') || code === 'ECONNREFUSED';
+
+  if (authError) {
+    console.error('Your DATABASE_URL is missing credentials or the password is wrong.');
+    console.error('Update DATABASE_URL in your .env file:');
+    console.error('  DATABASE_URL=postgres://USER:PASSWORD@localhost:5432/<%= databaseName %>');
+  } else if (connectionRefused) {
+    console.error('PostgreSQL is not running. Start it first:');
+    console.error('  Linux:  sudo systemctl start postgresql');
+    console.error('  macOS:  brew services start postgresql');
+  } else {
+    console.error('Common fixes:');
+    console.error('  - Make sure PostgreSQL is running');
+    console.error('  - Check that your user has permission to create databases');
+    console.error('  - Verify DATABASE_URL in your .env file is correct');
+  }
+
+  process.exit(1);
+});

package/templates/ts/mvc/scripts/dbReset.js.ejs

@@ -0,0 +1,40 @@
+<% if (educational) { %>// File overview: Executes the reset workflow by running setup and seed scripts in order.
+<% } %>
+const { spawn } = require('node:child_process');
+
+<% if (educational) { %>// Run an npm script and stream output to this terminal.
+// Wrapping spawn in a Promise lets us await each step in order.
+<% } %>function run(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      shell: true
+    });
+
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`${command} ${args.join(' ')} failed with exit code ${code}`));
+    });
+
+    child.on('error', reject);
+  });
+}
+
+async function main() {
+<% if (isDocker) { %><% if (educational) { %>  // Restart the container so reset starts from a clean database state.
+<% } %>  await run('npm', ['run', 'db:down']);
+  await run('npm', ['run', 'db:up']);
+<% } %><% if (educational) { %>  // Recreate tables first, then insert the sample data.
+<% } %>  await run('npm', ['run', 'db:setup']);
+  await run('npm', ['run', 'db:seed']);
+}
+
+main().catch((error) => {
+<% if (educational) { %>  // Child scripts print detailed logs, so this is a short summary.
+<% } %>  console.error(error.message);
+  process.exit(1);
+});

package/templates/ts/mvc/scripts/dbSeed.js.ejs

@@ -0,0 +1,62 @@
+<% if (educational) { %>// File overview: Runs db/seed.sql to insert starter rows into the database.
+<% } %>
+require('dotenv').config();
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { Pool } = require('pg');
+<% if (isDocker) { %>
+const RETRIES = 20;
+const RETRY_DELAY_MS = 1000;
+
+<% if (educational) { %>// Sleep helper used between retry attempts.
+<% } %>function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+<% if (educational) { %>// Retry a simple query until PostgreSQL is ready.
+<% } %>async function waitForDatabase(pool) {
+  for (let attempt = 1; attempt <= RETRIES; attempt += 1) {
+    try {
+      await pool.query('SELECT 1');
+      return;
+    } catch {
+      console.log('Waiting for database...');
+      await sleep(RETRY_DELAY_MS);
+    }
+  }
+
+  throw new Error('Unable to connect to database after 20 retries.');
+}
+<% } %>
+<% if (educational) { %>// Read db/seed.sql and run it to insert starter data.
+<% } %>async function run() {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL is not set.');
+    console.error('Make sure you have a .env file with DATABASE_URL defined.');
+    console.error('You can copy .env.example to .env to get started.');
+    process.exit(1);
+  }
+
+  const pool = new Pool({ connectionString: databaseUrl });
+
+  try {
+<% if (isDocker) { %><% if (educational) { %>    // Docker containers may need a few seconds before accepting connections.
+<% } %>    await waitForDatabase(pool);
+<% } %><% if (educational) { %>    // Loading SQL from a file keeps sample data updates easy to review.
+<% } %>    const seedPath = path.join(process.cwd(), 'db', 'seed.sql');
+    const seedSql = await fs.readFile(seedPath, 'utf8');
+    await pool.query(seedSql);
+    console.log('Database seed applied.');
+  } finally {
+    await pool.end();
+  }
+}
+
+run().catch((error) => {
+<% if (educational) { %>  // Exit with a non-zero status so npm reports the script as failed.
+<% } %>  console.error(error.message);
+  process.exit(1);
+});

package/templates/ts/mvc/scripts/dbSetup.js.ejs

@@ -0,0 +1,62 @@
+<% if (educational) { %>// File overview: Runs db/schema.sql to create or reset database tables.
+<% } %>
+require('dotenv').config();
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { Pool } = require('pg');
+<% if (isDocker) { %>
+const RETRIES = 20;
+const RETRY_DELAY_MS = 1000;
+
+<% if (educational) { %>// Sleep helper used between retry attempts while the container starts.
+<% } %>function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+<% if (educational) { %>// Retry a simple query until PostgreSQL is ready to accept commands.
+<% } %>async function waitForDatabase(pool) {
+  for (let attempt = 1; attempt <= RETRIES; attempt += 1) {
+    try {
+      await pool.query('SELECT 1');
+      return;
+    } catch {
+      console.log('Waiting for database...');
+      await sleep(RETRY_DELAY_MS);
+    }
+  }
+
+  throw new Error('Unable to connect to database after 20 retries.');
+}
+<% } %>
+<% if (educational) { %>// Read db/schema.sql and apply it to the configured database.
+<% } %>async function run() {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL is not set.');
+    console.error('Make sure you have a .env file with DATABASE_URL defined.');
+    console.error('You can copy .env.example to .env to get started.');
+    process.exit(1);
+  }
+
+  const pool = new Pool({ connectionString: databaseUrl });
+
+  try {
+<% if (isDocker) { %><% if (educational) { %>    // Docker containers may need a few seconds before accepting connections.
+<% } %>    await waitForDatabase(pool);
+<% } %><% if (educational) { %>    // Loading SQL from a file keeps schema changes visible in version control.
+<% } %>    const schemaPath = path.join(process.cwd(), 'db', 'schema.sql');
+    const schemaSql = await fs.readFile(schemaPath, 'utf8');
+    await pool.query(schemaSql);
+    console.log('Database schema applied.');
+  } finally {
+    await pool.end();
+  }
+}
+
+run().catch((error) => {
+<% if (educational) { %>  // Exit with a non-zero status so npm reports the script as failed.
+<% } %>  console.error(error.message);
+  process.exit(1);
+});

package/templates/ts/mvc/src/app.ts.ejs

@@ -0,0 +1,45 @@
+<% if (educational) { %>// File overview: Builds and configures the Express app (middleware, routes, and error pipeline).
+<% } %>
+import cors from 'cors';
+import express from 'express';
+import helmet from 'helmet';
+import morgan from 'morgan';
+
+import errorHandler from './middleware/errorHandler';
+import notFound from './middleware/notFound';
+import healthRouter from './routes/health';
+import usersRouter from './routes/users';
+
+const app = express();
+
+<% if (educational) { %>// Parse JSON request bodies so route handlers can read data from req.body.
+// Without this middleware, req.body is undefined for JSON requests.
+<% } %>app.use(express.json());
+<% if (educational) { %>// Enable CORS so browser clients on other origins can call this API.
+<% } %>app.use(cors());
+<% if (educational) { %>// Add common HTTP security headers.
+// Helmet applies safe defaults that reduce exposure to common web attacks.
+<% } %>app.use(helmet());
+<% if (educational) { %>// Log each request in development format to make local debugging easier.
+<% } %>app.use(morgan('dev'));
+
+<% if (educational) { %>// Provide a simple root endpoint so visiting the API URL in a browser
+// shows available routes instead of an immediate 404 response.
+<% } %>app.get('/', (_req, res) => {
+  res.json({
+    message: 'API is running',
+    endpoints: {
+      health: 'GET /health',
+      users: 'GET /api/users',
+      createUser: 'POST /api/users'
+    }
+  });
+});
+
+app.use('/health', healthRouter);
+app.use('/api/users', usersRouter);
+
+app.use(notFound);
+app.use(errorHandler);
+
+export default app;

package/templates/ts/mvc/src/controllers/usersController.ts.ejs

@@ -0,0 +1,31 @@
+<% if (educational) { %>// File overview: Handles /users HTTP requests and delegates business logic to the service layer.
+<% } %>
+import type { RequestHandler } from 'express';
+
+import usersService from '../services/usersService';
+
+<% if (educational) { %>// Controllers translate HTTP requests into service calls and convert service
+// results back into HTTP responses. Business rules remain in the service layer.
+<% } %>const listUsers: RequestHandler = async (_req, res, next) => {
+  try {
+    const users = await usersService.listUsers();
+    res.status(200).json(users);
+  } catch (error) {
+<% if (educational) { %>    // Pass errors to next(error) so the central error handler can respond.
+<% } %>    next(error);
+  }
+};
+
+const createUser: RequestHandler = async (req, res, next) => {
+  try {
+    const user = await usersService.createUser(req.body ?? {});
+    res.status(201).json(user);
+  } catch (error) {
+    next(error);
+  }
+};
+
+export default {
+  listUsers,
+  createUser
+};

package/templates/ts/mvc/src/db/pool.ts.ejs

@@ -0,0 +1,17 @@
+<% if (educational) { %>// File overview: Creates and exports a shared PostgreSQL connection pool for repository queries.
+<% } %>
+<% if (educational) { %>// Create one shared connection pool for the whole application.
+// Reusing connections is faster and avoids exhausting database limits.
+<% } %>import { Pool } from 'pg';
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required for Postgres mode.');
+}
+
+const pool = new Pool({
+  connectionString: databaseUrl
+});
+
+export default pool;

package/templates/ts/mvc/src/errors/AppError.ts.ejs

@@ -0,0 +1,14 @@
+<% if (educational) { %>// File overview: Defines an AppError class for expected API errors that include HTTP status codes.
+<% } %>
+<% if (educational) { %>// A custom error class for handling API errors. By extending JavaScript's
+// built-in Error class, we ensure that stack traces are generated correctly
+// and that the error handler can distinguish between anticipated API
+// errors and unexpected application failures.
+<% } %>export default class AppError extends Error {
+  status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}

package/templates/ts/mvc/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/mvc/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/mvc/src/repositories/usersRepository.ts.ejs

@@ -0,0 +1,87 @@
+<% if (educational) { %>// File overview: Encapsulates user data access so controllers/services stay focused on API behavior.
+<% } %>
+<% 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/mvc/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/mvc/src/routes/users.ts.ejs

@@ -0,0 +1,14 @@
+<% if (educational) { %>// File overview: Maps /api/users endpoints to controller methods in the MVC request flow.
+<% } %>
+import { Router } from 'express';
+
+import usersController from '../controllers/usersController';
+
+const router = Router();
+
+<% if (educational) { %>// Route files should map URLs to controller functions and nothing more.
+// Keeping them thin makes the API surface quick to scan and reason about.
+<% } %>router.get('/', usersController.listUsers);
+router.post('/', usersController.createUser);
+
+export default router;

package/templates/ts/mvc/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/mvc/src/services/usersService.ts.ejs

@@ -0,0 +1,35 @@
+<% if (educational) { %>// File overview: Contains user business rules and validation before calling the repository layer.
+<% } %>
+import usersRepository from '../repositories/usersRepository';
+import AppError from '../errors/AppError';
+
+interface CreateUserPayload {
+  name?: unknown;
+  email?: unknown;
+}
+
+<% if (educational) { %>// Services contain business rules and input validation. They sit between
+// controllers (HTTP concerns) and repositories (data access concerns).
+<% } %>async function listUsers() {
+  return usersRepository.getAll();
+}
+
+async function createUser(payload: CreateUserPayload) {
+  const { name, email } = payload;
+
+<% if (educational) { %>  // Validate input before calling the repository. Throwing AppError provides
+  // both the message and status code needed for a clear client response.
+<% } %>  if (!name || typeof name !== 'string') {
+    throw new AppError(400, '"name" is required.');
+  }
+
+  return usersRepository.create({
+    name: name.trim(),
+    email: typeof email === 'string' ? email.trim() : null
+  });
+}
+
+export default {
+  listUsers,
+  createUser
+};

package/templates/ts/mvc/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/mvc/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"]
+}

package/templates/ts/simple/.env.example.ejs

@@ -0,0 +1,7 @@
+PORT=3000
+NODE_ENV=development
+<% if (isPostgres) { %>
+# Update with your Postgres credentials if needed
+# Format: postgres://USER:PASSWORD@HOST:PORT/DATABASE
+DATABASE_URL=<%= databaseUrl %>
+<% } %>

package/templates/ts/simple/.eslintrc.cjs.ejs

@@ -0,0 +1,27 @@
+module.exports = {
+  root: true,
+  env: {
+    node: true,
+    es2022: true,
+    jest: true
+  },
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module'
+  },
+  plugins: ['@typescript-eslint'],
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  ignorePatterns: ['dist/', 'node_modules/', 'coverage/'],
+  rules: {
+    'no-undef': 'off',
+    'no-unused-vars': 'off',
+    '@typescript-eslint/no-unused-vars': [
+      'error',
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_'
+      }
+    ]
+  }
+};

package/templates/ts/simple/.gitignore.ejs

@@ -0,0 +1,6 @@
+node_modules
+.env
+dist
+coverage
+npm-debug.log*
+.DS_Store