@alexmc2/create-express-api-starter 0.1.0

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

@@ -0,0 +1,42 @@
+<% if (educational) { %>// File overview: Executes the reset workflow by running setup and seed scripts in order.
+<% } %>
+<% if (isEsm) { %>import { spawn } from 'node:child_process';
+<% } else { %>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/js/mvc/scripts/dbSeed.js.ejs

@@ -0,0 +1,69 @@
+<% if (educational) { %>// File overview: Runs db/seed.sql to insert starter rows into the database.
+<% } %>
+<% if (isEsm) { %>import 'dotenv/config';
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { Pool } from 'pg';
+<% } else { %>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/js/mvc/scripts/dbSetup.js.ejs

@@ -0,0 +1,69 @@
+<% if (educational) { %>// File overview: Runs db/schema.sql to create or reset database tables.
+<% } %>
+<% if (isEsm) { %>import 'dotenv/config';
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { Pool } from 'pg';
+<% } else { %>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/js/mvc/src/app.js.ejs

@@ -0,0 +1,57 @@
+<% if (educational) { %>// File overview: Builds and configures the Express app (middleware, routes, and error pipeline).
+<% } %>
+<% if (isEsm) { %>import cors from 'cors';
+import express from 'express';
+import helmet from 'helmet';
+import morgan from 'morgan';
+
+import errorHandler from './middleware/errorHandler.js';
+import notFound from './middleware/notFound.js';
+import healthRouter from './routes/health.js';
+import usersRouter from './routes/users.js';
+<% } else { %>const express = require('express');
+const cors = require('cors');
+const helmet = require('helmet');
+const morgan = require('morgan');
+
+const healthRouter = require('./routes/health');
+const usersRouter = require('./routes/users');
+const notFound = require('./middleware/notFound');
+const errorHandler = require('./middleware/errorHandler');
+<% } %>
+
+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);
+
+<% if (isEsm) { %>export default app;
+<% } else { %>module.exports = app;
+<% } %>

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

@@ -0,0 +1,32 @@
+<% if (educational) { %>// File overview: Handles /users HTTP requests and delegates business logic to the service layer.
+<% } %>
+<% if (isEsm) { %>import usersService from '../services/usersService.js';
+<% } else { %>const usersService = require('../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.
+<% } %>async function listUsers(_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);
+  }
+}
+
+async function createUser(req, res, next) {
+  try {
+    const user = await usersService.createUser(req.body ?? {});
+    res.status(201).json(user);
+  } catch (error) {
+    next(error);
+  }
+}
+
+<% if (isEsm) { %>export default {
+<% } else { %>module.exports = {
+<% } %>  listUsers,
+  createUser
+};

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

@@ -0,0 +1,19 @@
+<% 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.
+<% } %><% if (isEsm) { %>import { Pool } from 'pg';
+<% } else { %>const { Pool } = require('pg');
+<% } %>
+
+if (!process.env.DATABASE_URL) {
+  throw new Error('DATABASE_URL is required for Postgres mode.');
+}
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL
+});
+
+<% if (isEsm) { %>export default pool;
+<% } else { %>module.exports = pool;
+<% } %>

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

@@ -0,0 +1,16 @@
+<% 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.
+<% } %>class AppError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+<% if (isEsm) { %>export default AppError;
+<% } else { %>module.exports = AppError;
+<% } %>

package/templates/js/mvc/src/middleware/errorHandler.js.ejs

@@ -0,0 +1,39 @@
+<% if (educational) { %>// File overview: Converts thrown errors into consistent JSON HTTP responses for clients.
+<% } %>
+<% 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.
+<% } %>function errorHandler(error, _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 : 500;
+  const message = typeof error?.message === 'string' ? error.message : 'Internal server error.';
+
+  const payload = {
+    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);
+}
+
+<% if (isEsm) { %>export default errorHandler;
+<% } else { %>module.exports = errorHandler;
+<% } %>

package/templates/js/mvc/src/middleware/notFound.js.ejs

@@ -0,0 +1,15 @@
+<% if (educational) { %>// File overview: Handles unmatched routes by forwarding a 404 error to the central error handler.
+<% } %>
+<% if (isEsm) { %>import AppError from '../errors/AppError.js';
+<% } else { %>const AppError = require('../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.
+<% } %>function notFound(_req, _res, next) {
+  next(new AppError(404, 'Route not found.'));
+}
+
+<% if (isEsm) { %>export default notFound;
+<% } else { %>module.exports = notFound;
+<% } %>

package/templates/js/mvc/src/repositories/usersRepository.js.ejs

@@ -0,0 +1,69 @@
+<% 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.
+<% } %><% if (isEsm) { %>import pool from '../db/pool.js';
+<% } else { %>const pool = require('../db/pool');
+<% } %>
+
+async function getAll() {
+  const result = await pool.query('SELECT id, name, email FROM users ORDER BY id ASC');
+  return result.rows;
+}
+
+async function create({ name, email }) {
+<% if (educational) { %>  // Use parameter placeholders ($1, $2) so pg binds values safely.
+<% } %>  const result = await pool.query(
+    'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id, name, email',
+    [name, email]
+  );
+
+  return result.rows[0];
+}
+
+<% if (isEsm) { %>export default {
+<% } else { %>module.exports = {
+<% } %>  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.
+<% } %>const users = [
+  {
+    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() {
+  return users;
+}
+
+async function create({ name, email }) {
+  const user = {
+    id: nextId,
+    name,
+    email
+  };
+
+  nextId += 1;
+  users.push(user);
+
+  return user;
+}
+
+<% if (isEsm) { %>export default {
+<% } else { %>module.exports = {
+<% } %>  getAll,
+  create
+};
+<% } %>

package/templates/js/mvc/src/routes/health.js.ejs

@@ -0,0 +1,19 @@
+<% if (educational) { %>// File overview: Registers the health-check route used to confirm the API process is running.
+<% } %>
+<% if (isEsm) { %>import { Router } from 'express';
+<% } else { %>const express = require('express');
+<% } %>
+
+<% if (isEsm) { %>const router = Router();
+<% } else { %>const router = express.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 });
+});
+
+<% if (isEsm) { %>export default router;
+<% } else { %>module.exports = router;
+<% } %>

package/templates/js/mvc/src/routes/users.js.ejs

@@ -0,0 +1,22 @@
+<% if (educational) { %>// File overview: Maps /api/users endpoints to controller methods in the MVC request flow.
+<% } %>
+<% if (isEsm) { %>import { Router } from 'express';
+
+import usersController from '../controllers/usersController.js';
+<% } else { %>const express = require('express');
+
+const usersController = require('../controllers/usersController');
+<% } %>
+
+<% if (isEsm) { %>const router = Router();
+<% } else { %>const router = express.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);
+
+<% if (isEsm) { %>export default router;
+<% } else { %>module.exports = router;
+<% } %>

package/templates/js/mvc/src/server.js.ejs

@@ -0,0 +1,21 @@
+<% if (educational) { %>// File overview: Application entry point that loads environment variables and starts the HTTP server.
+<% } %>
+<% if (isEsm) { %><% if (educational) { %>// Load variables from .env before other modules read process.env values.
+<% } %>import 'dotenv/config';
+
+import app from './app.js';
+import { getPort } from './utils/getPort.js';
+<% } else { %><% if (educational) { %>// Load variables from .env before other modules read process.env values.
+<% } %>require('dotenv').config();
+
+const app = require('./app');
+const { getPort } = require('./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/js/mvc/src/services/usersService.js.ejs

@@ -0,0 +1,34 @@
+<% if (educational) { %>// File overview: Contains user business rules and validation before calling the repository layer.
+<% } %>
+<% if (isEsm) { %>import AppError from '../errors/AppError.js';
+import usersRepository from '../repositories/usersRepository.js';
+<% } else { %>const usersRepository = require('../repositories/usersRepository');
+const AppError = require('../errors/AppError');
+<% } %>
+
+<% 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) {
+  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
+  });
+}
+
+<% if (isEsm) { %>export default {
+<% } else { %>module.exports = {
+<% } %>  listUsers,
+  createUser
+};

package/templates/js/mvc/src/utils/getPort.js.ejs

@@ -0,0 +1,18 @@
+<% 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.
+<% } %>function getPort(value, fallback = 3000) {
+  const parsed = Number(value);
+
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+
+  return fallback;
+}
+
+<% if (isEsm) { %>export { getPort };
+<% } else { %>module.exports = {
+  getPort
+};
+<% } %>

package/templates/js/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/js/simple/.eslintrc.cjs.ejs

@@ -0,0 +1,24 @@
+module.exports = {
+  root: true,
+  env: {
+    node: true,
+    es2022: true,
+    jest: true
+  },
+  extends: ['eslint:recommended'],
+  parserOptions: {
+    ecmaVersion: 'latest',
+<% if (isEsm) { %>    sourceType: 'module'
+<% } else { %>    sourceType: 'script'
+<% } %>  },
+  ignorePatterns: ['dist/', 'node_modules/', 'coverage/'],
+  rules: {
+    'no-unused-vars': [
+      'error',
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_'
+      }
+    ]
+  }
+};

package/templates/js/simple/.gitignore.ejs

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