@alexmc2/create-express-api-starter 0.1.0

package/templates/js/simple/README.md.ejs

@@ -0,0 +1,182 @@
+# <%= projectName %>
+
+Express API starter generated by `@alexmc2/create-express-api-starter`.
+
+## Selected options
+
+- Language: <%= languageLabel %>
+- Module system: <%= moduleSystemLabel %>
+- Dev watcher: <%= jsDevWatcherLabel %>
+- Architecture: <%= architectureLabel %>
+- Database: <%= databaseLabel %>
+- Educational comments: <%= educationalLabel %>
+
+## Folder structure
+
+```
+.
+├── src
+│   ├── app.js
+│   ├── server.js
+│   ├── routes
+│   │   ├── health.js
+│   │   └── users.js
+│   ├── repositories
+│   │   └── usersRepository.js
+<% if (isPostgres) { %>│   ├── db
+│   │   └── pool.js
+<% } %>│   ├── errors
+│   │   └── AppError.js
+│   ├── utils
+│   │   └── getPort.js
+│   └── middleware
+│       ├── errorHandler.js
+│       └── notFound.js
+├── __tests__
+│   └── app.test.js
+<% 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
+└── 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. Create a new file in `src/routes`.
+2. Export an Express router from that file.
+3. Register it in `src/app.js` with `app.use('/your-path', yourRouter)`.
+
+## Where business logic goes
+
+Keep route handlers thin and move data access logic into `src/repositories`. This keeps the API layer easy to read and easy to test.
+
+## How errors work
+
+- `src/middleware/notFound.js` handles unknown routes with a 404 JSON response.
+- `src/middleware/errorHandler.js` returns a consistent error shape: `{ 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/js/simple/__tests__/app.test.js.ejs

@@ -0,0 +1,51 @@
+<% 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.
+<% } %><% if (isEsm) { %>import { describe, expect, test<% if (isPostgres) { %>, afterAll<% } %> } from '@jest/globals';
+import request from 'supertest';
+
+import app from '../src/app.js';
+<% if (isPostgres) { %>import pool from '../src/db/pool.js';
+<% } %><% } else { %>const request = require('supertest');
+
+const app = require('../src/app');
+<% if (isPostgres) { %>const pool = require('../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/js/simple/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/js/simple/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/js/simple/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/js/simple/jest.config.js.ejs

@@ -0,0 +1,6 @@
+<% if (isEsm) { %>export default {
+<% } else { %>module.exports = {
+<% } %>
+  testEnvironment: 'node'<% if (isPostgres) { %>,
+  setupFiles: ['dotenv/config']<% } %>
+};

package/templates/js/simple/package.json.ejs

@@ -0,0 +1,40 @@
+{
+  "name": "<%= packageName %>",
+  "version": "0.1.0",
+  "private": true,
+<% if (isEsm) { %>  "type": "module",
+<% } %>
+  "description": "Express API generated by @alexmc2/create-express-api-starter",
+  "scripts": {
+    "dev": "<%= jsDevCommand %>",
+    "start": "node src/server.js",
+    "test": "<% if (isEsm) { %>node --experimental-vm-modules ./node_modules/jest/bin/jest.js<% } else { %>jest<% } %>",
+    "lint": "eslint ."<% 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": "<%- useNodemon ? '>=20' : '>=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": {
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+<% if (useNodemon) { %>    "nodemon": "^3.1.9",
+<% } %>    "supertest": "^7.0.0"
+  }
+}

package/templates/js/simple/scripts/dbCreate.js.ejs

@@ -0,0 +1,97 @@
+<% if (educational) { %>// File overview: Creates the target PostgreSQL database if it does not already exist.
+<% } %>
+<% if (isEsm) { %>import 'dotenv/config';
+
+import { Pool } from 'pg';
+<% } else { %>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/js/simple/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/simple/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/simple/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/simple/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/simple/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;
+<% } %>