@alexmc2/create-express-api-starter 0.1.3 → 0.1.5

package/templates/js/mvc/package.json.ejs

@@ -24,17 +24,17 @@
     "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"<% } %>
+    "cors": "^2.8.6",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "morgan": "^1.10.1"<% if (isPostgres) { %>,
+    "pg": "^8.18.0"<% } %>
   },
   "devDependencies": {
-    "eslint": "^8.57.0",
-    "jest": "^29.7.0",
-<% if (useNodemon) { %>    "nodemon": "^3.1.9",
-<% } %>    "supertest": "^7.0.0"
+    "eslint": "^8.57.1",
+    "jest": "^30.2.0",
+<% if (useNodemon) { %>    "nodemon": "^3.1.11",
+<% } %>    "supertest": "^7.2.2"
   }
 }

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

@@ -24,17 +24,17 @@
     "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"<% } %>
+    "cors": "^2.8.6",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "morgan": "^1.10.1"<% if (isPostgres) { %>,
+    "pg": "^8.18.0"<% } %>
   },
   "devDependencies": {
-    "eslint": "^8.57.0",
-    "jest": "^29.7.0",
-<% if (useNodemon) { %>    "nodemon": "^3.1.9",
-<% } %>    "supertest": "^7.0.0"
+    "eslint": "^8.57.1",
+    "jest": "^30.2.0",
+<% if (useNodemon) { %>    "nodemon": "^3.1.11",
+<% } %>    "supertest": "^7.2.2"
   }
 }

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

@@ -0,0 +1,39 @@
+module.exports = {
+  root: true,
+  env: {
+    node: true,
+    es2022: true,
+    jest: true
+  },
+  extends: ['eslint:recommended'],
+  ignorePatterns: ['dist/', 'node_modules/', 'coverage/'],
+  rules: {
+    'no-control-regex': 'off'
+  },
+  overrides: [
+    {
+      files: ['**/*.ts'],
+      parser: '@typescript-eslint/parser',
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        project: ['./tsconfig.eslint.json'],
+        tsconfigRootDir: __dirname
+      },
+      plugins: ['@typescript-eslint'],
+      extends: ['plugin:@typescript-eslint/recommended'],
+      rules: {
+        'no-undef': 'off',
+        'no-unused-vars': 'off',
+        '@typescript-eslint/await-thenable': 'error',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            argsIgnorePattern: '^_',
+            varsIgnorePattern: '^_'
+          }
+        ]
+      }
+    }
+  ]
+};

package/templates/ts/{mvc → shared}/package.json.ejs

@@ -23,29 +23,29 @@
     "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"<% } %>
+    "cors": "^2.8.6",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "morgan": "^1.10.1"<% if (isPostgres) { %>,
+    "pg": "^8.18.0"<% } %>
   },
   "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"
+    "@swc/core": "^1.15.11",
+    "@swc/jest": "^0.2.39",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^20.19.33",
+<% if (isPostgres) { %>    "@types/pg": "^8.16.0",
+<% } %>    "@types/supertest": "^6.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^8.57.1",
+    "jest": "^30.2.0",
+    "supertest": "^7.2.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   }
 }

package/templates/ts/shared/tsconfig.eslint.json.ejs

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true
+  },
+  "include": ["src", "__tests__"]
+}

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

@@ -1,27 +0,0 @@
-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/.env.example.ejs

@@ -1,7 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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

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

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

@@ -1,45 +0,0 @@
-<% 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/simple/compose.yaml.ejs

@@ -1,13 +0,0 @@
-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/simple/db/schema.sql.ejs

@@ -1,8 +0,0 @@
-<% 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/simple/db/seed.sql.ejs

@@ -1,7 +0,0 @@
-<% 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/simple/jest.config.js.ejs

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

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

@@ -1,51 +0,0 @@
-{
-  "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"
-  }
-}

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

@@ -1,93 +0,0 @@
-<% 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/simple/scripts/dbReset.js.ejs

@@ -1,40 +0,0 @@
-<% 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/simple/scripts/dbSeed.js.ejs

@@ -1,62 +0,0 @@
-<% 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/simple/scripts/dbSetup.js.ejs

@@ -1,62 +0,0 @@
-<% 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);
-});