@alexmc2/create-express-api-starter 0.1.0

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

@@ -0,0 +1,69 @@
+<% 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.
+<% } %><% 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/simple/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/simple/src/routes/users.js.ejs

@@ -0,0 +1,52 @@
+<% if (educational) { %>// File overview: Defines /api/users routes, including request validation and repository calls.
+<% } %>
+<% if (isEsm) { %>import { Router } from 'express';
+
+import AppError from '../errors/AppError.js';
+import usersRepository from '../repositories/usersRepository.js';
+<% } else { %>const express = require('express');
+
+const usersRepository = require('../repositories/usersRepository');
+const AppError = require('../errors/AppError');
+<% } %>
+
+<% if (isEsm) { %>const router = Router();
+<% } else { %>const router = express.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);
+  }
+});
+
+<% if (isEsm) { %>export default router;
+<% } else { %>module.exports = router;
+<% } %>

package/templates/js/simple/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/simple/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/ts/mvc/.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/mvc/.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/mvc/.gitignore.ejs

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

package/templates/ts/mvc/README.md.ejs

@@ -0,0 +1,188 @@
+# <%= projectName %>
+
+Express API starter generated by `@alexmc2/create-express-api-starter`.
+
+## Selected options
+
+- Language: <%= languageLabel %>
+- Dev watcher: tsx watch
+- Architecture: <%= architectureLabel %>
+- Database: <%= databaseLabel %>
+- Educational comments: <%= educationalLabel %>
+
+## Folder structure
+
+```
+.
+├── src
+│   ├── app.ts
+│   ├── server.ts
+│   ├── routes
+│   │   ├── health.ts
+│   │   └── users.ts
+│   ├── controllers
+│   │   └── usersController.ts
+│   ├── services
+│   │   └── usersService.ts
+│   ├── repositories
+│   │   └── usersRepository.ts
+<% if (isPostgres) { %>│   ├── db
+│   │   └── pool.ts
+<% } %>│   ├── errors
+│   │   └── AppError.ts
+│   ├── utils
+│   │   └── getPort.ts
+│   └── middleware
+│       ├── errorHandler.ts
+│       └── notFound.ts
+├── __tests__
+│   └── app.test.ts
+<% if (isPostgres) { %>├── db
+│   ├── schema.sql
+│   └── seed.sql
+<% } %><% if (isPostgres) { %>├── scripts
+<% if (isPsql) { %>│   ├── dbCreate.js
+<% } %>│   ├── dbSetup.js
+│   ├── dbSeed.js
+│   └── dbReset.js
+<% } %><% if (isDocker) { %>├── compose.yaml
+<% } %>├── .env.example
+├── .gitignore
+├── .eslintrc.cjs
+├── package.json
+├── tsconfig.json
+└── jest.config.js
+```
+
+<% if (isPsql) { %>
+## Prerequisites
+
+This project uses a local PostgreSQL database. Follow the steps for your OS below.
+
+### 1. Install PostgreSQL
+
+**macOS** (using [Homebrew](https://brew.sh)):
+
+```sh
+brew install postgresql@17
+brew services start postgresql@17
+```
+
+**Ubuntu / Debian**:
+
+```sh
+sudo apt update && sudo apt install postgresql postgresql-contrib
+sudo systemctl start postgresql && sudo systemctl enable postgresql
+```
+
+**Windows**: Download the installer from https://www.postgresql.org/download/windows/ and follow the prompts. Remember the password you set — you'll need it in step 2.
+
+### 2. Set up your database role
+
+Your `.env` file connects as `<%= osUsername %>` with password `postgres`. You need a matching PostgreSQL role.
+
+**Linux** (run once):
+
+```sh
+sudo -u postgres createuser --createdb "$USER"
+sudo -u postgres psql -c "ALTER USER \"$USER\" WITH PASSWORD 'postgres';"
+```
+
+**macOS**: Homebrew already created a role for you. Run the commands above only if you get an auth error.
+
+**Windows**: The installer created a `postgres` role. Edit `DATABASE_URL` in your `.env` to use it:
+
+```
+DATABASE_URL=postgres://postgres:YOUR_INSTALL_PASSWORD@localhost:5432/<%= databaseName %>
+```
+
+### 3. Verify
+
+```sh
+pg_isready
+```
+
+You should see `accepting connections`.
+<% } %>
+<% if (isDocker) { %>
+## Prerequisites
+
+This project uses PostgreSQL in a Docker container. Install [Docker Desktop](https://docs.docker.com/get-docker/) and make sure it's running before continuing.
+<% } %>
+
+## Run the app
+
+```sh
+npm install
+cp .env.example .env
+<% if (isPsql) { %>npm run db:create
+npm run db:setup
+npm run db:seed
+<% } else if (isDocker) { %>npm run db:up
+npm run db:setup
+npm run db:seed
+<% } %>npm run dev
+```
+
+Run `npm run lint` to check the code with ESLint.
+
+## Add a new route
+
+1. Add a router in `src/routes`.
+2. Call controller functions from that route.
+3. Put business rules in `src/services`.
+4. Put data access code in `src/repositories`.
+5. Register the route in `src/app.ts`.
+
+## Where business logic goes
+
+Use `src/services` for business logic. Controllers translate HTTP requests/responses, and repositories handle persistence.
+
+## How errors work
+
+- `src/middleware/notFound.ts` handles unknown routes with a 404 JSON response.
+- `src/middleware/errorHandler.ts` returns `{ status, message }` and includes `stack` only in development.
+
+<% if (isPsql) { %>
+## Database commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run db:create` | Creates the database (safe to re-run) |
+| `npm run db:setup` | Applies the schema (creates tables) |
+| `npm run db:seed` | Inserts sample data |
+| `npm run db:reset` | Drops and re-creates tables + sample data |
+
+## Troubleshooting
+
+**"connection refused"** — PostgreSQL isn't running.
+
+```sh
+# Linux
+sudo systemctl start postgresql
+# macOS
+brew services start postgresql@17
+```
+
+**"role does not exist"** — Create a Postgres role for your OS user:
+
+```sh
+sudo -u postgres createuser --createdb "$USER"
+sudo -u postgres psql -c "ALTER USER \"$USER\" WITH PASSWORD 'postgres';"
+```
+
+**"password authentication failed" / "client password must be a string"** — The credentials in `DATABASE_URL` are wrong or missing. Run the role setup commands in [Prerequisites](#prerequisites) and make sure `DATABASE_URL` in `.env` matches.
+
+**"database does not exist"** — Run `npm run db:create`.
+<% } %>
+<% if (isDocker) { %>
+## Database commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run db:up` | Starts the Postgres Docker container |
+| `npm run db:down` | Stops the container |
+| `npm run db:setup` | Applies the schema (creates tables) |
+| `npm run db:seed` | Inserts sample data |
+| `npm run db:reset` | Stops container, restarts, re-applies schema + seed |
+<% } %>

package/templates/ts/mvc/__tests__/app.test.ts.ejs

@@ -0,0 +1,45 @@
+<% if (educational) { %>// File overview: Basic endpoint tests that verify the API responds with expected status codes and payloads.
+<% } %>
+<% if (educational) { %>// Supertest sends HTTP requests directly to the Express app instance.
+// This keeps tests fast and isolated because no network port is opened.
+<% } %>import request from 'supertest';
+
+import app from '../src/app';
+<% if (isPostgres) { %>import pool from '../src/db/pool';
+<% } %>
+<% if (isPostgres) { %>afterAll(async () => {
+  await pool.end();
+});
+
+<% } %>describe('API', () => {
+  test('GET / returns API info', async () => {
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    expect(response.body.message).toBe('API is running');
+    expect(response.body.endpoints).toBeDefined();
+  });
+
+  test('GET /health returns { ok: true }', async () => {
+    const response = await request(app).get('/health');
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ ok: true });
+  });
+
+  test('GET /api/users returns an array', async () => {
+    const response = await request(app).get('/api/users');
+
+    expect(response.status).toBe(200);
+    expect(Array.isArray(response.body)).toBe(true);
+  });
+
+  test('POST /api/users with missing name returns 400', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com' });
+
+    expect(response.status).toBe(400);
+    expect(response.body.message).toBeDefined();
+  });
+});

package/templates/ts/mvc/compose.yaml.ejs

@@ -0,0 +1,13 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: <%= databaseName %>
+    ports:
+      - '5433:5432'
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+volumes:
+  postgres_data:

package/templates/ts/mvc/db/schema.sql.ejs

@@ -0,0 +1,8 @@
+<% if (educational) { %>-- File overview: Creates the tables and constraints required by this starter API.
+<% } %>
+DROP TABLE IF EXISTS users;
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT UNIQUE
+);

package/templates/ts/mvc/db/seed.sql.ejs

@@ -0,0 +1,7 @@
+<% if (educational) { %>-- File overview: Inserts starter rows so the API has sample data on first run.
+<% } %>
+INSERT INTO users (name, email)
+VALUES
+  ('Ada Lovelace', 'ada@example.com'),
+  ('Grace Hopper', 'grace@example.com'),
+  ('Margaret Hamilton', 'margaret@example.com');

package/templates/ts/mvc/jest.config.js.ejs

@@ -0,0 +1,7 @@
+module.exports = {
+  transform: {
+    '^.+\\.tsx?$': ['@swc/jest']
+  },
+  testEnvironment: 'node'<% if (isPostgres) { %>,
+  setupFiles: ['dotenv/config']<% } %>
+};

package/templates/ts/mvc/package.json.ejs

@@ -0,0 +1,51 @@
+{
+  "name": "<%= packageName %>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Express API generated by @alexmc2/create-express-api-starter",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "jest",
+    "lint": "eslint . --ext .ts"<% if (isPsql) { %>,
+    "db:create": "node scripts/dbCreate.js",
+    "db:setup": "node scripts/dbSetup.js",
+    "db:seed": "node scripts/dbSeed.js",
+    "db:reset": "node scripts/dbReset.js"<% } %><% if (isDocker) { %>,
+    "db:up": "docker compose up -d",
+    "db:down": "docker compose down -v",
+    "db:setup": "node scripts/dbSetup.js",
+    "db:seed": "node scripts/dbSeed.js",
+    "db:reset": "node scripts/dbReset.js"<% } %>
+  },
+  "engines": {
+    "node": ">=20.13"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.1",
+    "helmet": "^8.0.0",
+    "morgan": "^1.10.0"<% if (isPostgres) { %>,
+    "pg": "^8.13.1"<% } %>
+  },
+  "devDependencies": {
+    "@swc/core": "^1.7.26",
+    "@swc/jest": "^0.2.36",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.13",
+    "@types/morgan": "^1.9.9",
+    "@types/node": "^20.16.11",
+<% if (isPostgres) { %>    "@types/pg": "^8.11.10",
+<% } %>    "@types/supertest": "^6.0.2",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}