exp-node-server 2.0.0 → 2.1.0

package/README.md

@@ -25,6 +25,26 @@ This tool helps developers quickly scaffold `clean`, `modular` `Express` APIs wi
 - 🔄 Add modules anytime
 - 📦 Zero boilerplate setup
 
+## 📋 Requirements
+
+- Node.js **20.17+** to run the CLI; generated projects need Node.js **22.12+**
+- Docker (or your own database): PostgreSQL for Prisma, MongoDB for Mongoose
+
+## 📥 Installation
+
+No install needed: `npx` always runs the latest version (recommended).
+
+```bash
+npx exp-node-server --help
+```
+
+Or install it globally to use `exp-node-server` directly:
+
+```bash
+npm install -g exp-node-server
+exp-node-server --version
+```
+
 ## 📦 Quick Start
 
 Run directly using npx (recommended):
@@ -44,7 +64,38 @@ Then:
 ```bash
 cd my-api
 npm install
-npm run dev
+cp .env.example .env     # fill in the secrets (openssl rand -hex 32)
+docker compose up -d     # starts PostgreSQL / MongoDB
+npm run db:migrate       # Prisma only
+npm run dev              # http://localhost:5000, docs at /docs
+npm test
+```
+
+### What you get
+
+```text
+my-api/
+├── src/
+│   ├── app.ts                 # express app: helmet, cors, rate limit, routes
+│   ├── server.ts              # connects the database, starts queues, graceful shutdown
+│   ├── routes.ts              # module routers (generated modules are added here)
+│   ├── swaggerOptions.ts      # API docs (generated modules are added here)
+│   └── app/
+│       ├── configs/           # env vars, validated with zod on startup
+│       ├── middlewares/       # auth, validation, rate limiting, uploads, errors
+│       ├── modules/
+│       │   ├── account/       # sign up/in, OTP, refresh tokens, password reset
+│       │   └── profile/       # profile + photo upload (Cloudinary)
+│       ├── passport-js/       # social login (Google, Facebook, GitHub, X, LinkedIn, Discord)
+│       ├── queues/            # background email jobs (pg-boss / Agenda, no Redis)
+│       ├── templates/         # email templates
+│       └── utils/
+├── tests/
+│   ├── routes/                # supertest suites, one per module
+│   └── helpers/
+├── prisma/schema/             # Prisma only: one .prisma file per model
+├── docker-compose.yml
+└── .env.example
 ```
 
 ## 🧩 Generate a Module
@@ -83,7 +134,22 @@ including the 404s, and passes as generated:
 npm test -- tests/routes/order.test.ts
 ```
 
-When you add fields, fill in `createPayload` / `updatePayload` at the top of the test.
+Generated modules start with an example `name` field, from the validation to the
+database schema and the tests, so data flows end to end right away. Rename it or add
+your fields in the same places, and update `createPayload` / `updatePayload` at the
+top of the test. These are starter tests: extend them with your business rules.
+
+### Protected routes
+
+Generated routes are **public** by default. To require a signed-in user on every
+route:
+
+```bash
+npx exp-node-server -g order --auth
+```
+
+The generated test then also checks that anonymous requests get a 401. To limit a
+route to admins, change `auth()` to `auth('ADMIN')` in `order.route.ts`.
 Mongoose tests run against an in-memory MongoDB; Prisma tests use the Prisma mock in
 `tests/helpers/prisma.ts`. Module names whose path is already taken (e.g. `auth`) are
 refused.
@@ -92,7 +158,7 @@ refused.
 
 ```text
 npx exp-node-server create <project-name> [--template <mongoose|prisma>]
-npx exp-node-server generate <module-name> [--force]
+npx exp-node-server generate <module-name> [--auth] [--force]
 
 Commands
   create, -c <name>      Create a new project from a template
@@ -100,6 +166,7 @@ Commands
 
 Options
   -t, --template <name>  Template to use with create (mongoose | prisma)
+  -a, --auth             Generated routes require a signed-in user (default: public)
   -f, --force            Overwrite an existing module when generating
   -h, --help             Show help
   -v, --version          Show version
@@ -108,6 +175,19 @@ Options
 - Project names are lowercased and spaces become dashes (`My API` → `my-api`).
 - Module names are lowercased and spaces/dashes become underscores (`order-item` → `order_item`).
 
+### Safety
+
+- **All or nothing:** a module is generated in one step. If anything fails (e.g. a
+  file can't be written), the project is left exactly as it was.
+- **`--force` keeps backups:** files it overwrites are copied first to
+  `.exp-node-server/backups/<timestamp>/` (ignored by git, ESLint and Prettier).
+  Files that wouldn't change are left alone.
+- **No clashes:** a module name whose URL is already used by another router (e.g.
+  `auth`) is refused.
+- **Validated input only:** generated services receive `req.body` after
+  `RequestValidator` parsed it with the module's zod schema, so unknown fields are
+  dropped. Payload types come from that schema (`z.infer`).
+
 ## 📁 Generated Module Structure
 
 Each module follows a clean structure: