express-file-cluster 0.3.15 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-3VWD2ZED.js +60 -0
- package/dist/chunk-3VWD2ZED.js.map +1 -0
- package/dist/chunk-47K2532L.cjs +196 -0
- package/dist/chunk-47K2532L.cjs.map +1 -0
- package/dist/chunk-5PDAWMGF.js +438 -0
- package/dist/chunk-5PDAWMGF.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-ALBDM5R3.cjs +60 -0
- package/dist/chunk-ALBDM5R3.cjs.map +1 -0
- package/dist/chunk-JJJJTACK.js +196 -0
- package/dist/chunk-JJJJTACK.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-M7MUPWCE.js +116 -0
- package/dist/chunk-M7MUPWCE.js.map +1 -0
- package/dist/chunk-PMF4GMHD.js +154 -0
- package/dist/chunk-PMF4GMHD.js.map +1 -0
- package/dist/chunk-QTRGJ2EN.cjs +2635 -0
- package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
- package/dist/chunk-RSBW2B3D.cjs +126 -0
- package/dist/chunk-RSBW2B3D.cjs.map +1 -0
- package/dist/chunk-RTFJ32T5.js +2635 -0
- package/dist/chunk-RTFJ32T5.js.map +1 -0
- package/dist/chunk-SFVEQ2T5.cjs +438 -0
- package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
- package/dist/chunk-SZT36SGB.cjs +154 -0
- package/dist/chunk-SZT36SGB.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-ULQXD4YZ.cjs +116 -0
- package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
- package/dist/chunk-VYHJX54R.js +126 -0
- package/dist/chunk-VYHJX54R.js.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +323 -0
- package/dist/docs/api-reference/table.md +250 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +70 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +308 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +289 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +472 -7
- package/dist/index.d.ts +472 -7
- package/dist/index.js +283 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
- package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
- package/dist/pgboss-backend-UUJOVEYK.js +14 -0
- package/dist/pgboss-backend-UUJOVEYK.js.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-DJCPAsM4.d.cts +541 -0
- package/dist/types-DJCPAsM4.d.ts +541 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- package/dist/types-BusbSenn.d.ts +0 -162
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Generated Portals — User & Admin
|
|
2
|
+
|
|
3
|
+
`create-efc-app`'s **User portal** and **Admin portal** feature options scaffold a large, ready-to-run set of models and routes — everything from auth extras (2FA, sessions, password reset) to admin content management (blogs, FAQs, coupons). This page is the complete inventory, so nothing you didn't ask for shows up as a surprise, and nothing you did enable goes undocumented.
|
|
4
|
+
|
|
5
|
+
> On MongoDB, every model below is a real `defineModel`-backed collection and every route has working database logic. **On PostgreSQL, model files are commented-out Drizzle stubs and route bodies are `// TODO` placeholders** — the PostgreSQL adapter isn't implemented in the runtime yet. See [Database](./database.md).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Always generated (regardless of portal choices)
|
|
10
|
+
|
|
11
|
+
- `POST /auth/login`
|
|
12
|
+
- `POST /auth/logout`
|
|
13
|
+
- `src/model/User.ts`
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## User portal
|
|
18
|
+
|
|
19
|
+
Toggling **User portal** adds:
|
|
20
|
+
|
|
21
|
+
### Models
|
|
22
|
+
|
|
23
|
+
`User` (extended), `Session`, `Notification`, `File`, `SupportTicket`, `Subscription`, `Invoice`, `ApiKey`
|
|
24
|
+
|
|
25
|
+
### Routes
|
|
26
|
+
|
|
27
|
+
| Area | Method & Path |
|
|
28
|
+
|---|---|
|
|
29
|
+
| Auth | `POST /auth/register` |
|
|
30
|
+
| | `GET /auth/me` |
|
|
31
|
+
| | `POST /auth/refresh` |
|
|
32
|
+
| | `GET /auth/verify-email`, `POST /auth/verify-email` |
|
|
33
|
+
| | `POST /auth/forgot-password` |
|
|
34
|
+
| | `POST /auth/reset-password` |
|
|
35
|
+
| | `POST /auth/change-password` |
|
|
36
|
+
| | `GET /auth/2fa/setup`, `POST /auth/2fa/setup` |
|
|
37
|
+
| | `POST /auth/2fa/verify` |
|
|
38
|
+
| | `POST /auth/2fa/disable` |
|
|
39
|
+
| | `GET /auth/sessions`, `DELETE /auth/sessions/:id` |
|
|
40
|
+
| Profile | `GET /user/profile`, `PUT /user/profile` |
|
|
41
|
+
| | `POST /user/avatar`, `DELETE /user/avatar` |
|
|
42
|
+
| | `GET /user/settings`, `PUT /user/settings` |
|
|
43
|
+
| | `GET /user/account`, `DELETE /user/account` |
|
|
44
|
+
| | `GET /user/dashboard` |
|
|
45
|
+
| | `GET /user/activity` |
|
|
46
|
+
| Notifications | `GET /user/notifications`, `POST /user/notifications` (mark all read) |
|
|
47
|
+
| | `GET /user/notifications/:id`, `PATCH /user/notifications/:id`, `DELETE /user/notifications/:id` |
|
|
48
|
+
| Files | `GET /user/files`, `POST /user/files` |
|
|
49
|
+
| | `GET /user/files/:id`, `DELETE /user/files/:id` |
|
|
50
|
+
| Favorites / bookmarks | `GET /user/favorites`, `POST /user/favorites`, `DELETE /user/favorites/:id` |
|
|
51
|
+
| | `GET /user/bookmarks`, `POST /user/bookmarks`, `DELETE /user/bookmarks/:id` |
|
|
52
|
+
| Search | `GET /user/search` |
|
|
53
|
+
| API keys | `GET /user/api-keys`, `POST /user/api-keys`, `DELETE /user/api-keys/:id` |
|
|
54
|
+
| Billing | `GET /user/billing/plans` |
|
|
55
|
+
| | `GET /user/billing/subscription`, `POST /user/billing/subscription`, `DELETE /user/billing/subscription` |
|
|
56
|
+
| | `GET /user/billing/payment-methods`, `POST /user/billing/payment-methods`, `DELETE /user/billing/payment-methods/:id` |
|
|
57
|
+
| | `GET /user/billing/invoices`, `GET /user/billing/invoices/:id` |
|
|
58
|
+
| Support | `GET /support/tickets`, `POST /support/tickets` |
|
|
59
|
+
| | `GET /support/tickets/:id`, `PUT /support/tickets/:id` |
|
|
60
|
+
|
|
61
|
+
All protected routes export `middlewares = [requireAuth]` — or `[requireAuth('user', 'admin')]` if [RBAC](./rbac.md) is also enabled.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Admin portal
|
|
66
|
+
|
|
67
|
+
Toggling **Admin portal** adds:
|
|
68
|
+
|
|
69
|
+
### Models
|
|
70
|
+
|
|
71
|
+
`Admin`, `SupportTicket` (shared with User portal if both enabled), `AuditLog`, `Plan` (shared), `FAQ`, `Blog`, `Category`, `Coupon`
|
|
72
|
+
|
|
73
|
+
### Routes
|
|
74
|
+
|
|
75
|
+
| Area | Method & Path |
|
|
76
|
+
|---|---|
|
|
77
|
+
| Dashboard | `GET /admin/dashboard` |
|
|
78
|
+
| Users | `GET /admin/users`, `POST /admin/users` |
|
|
79
|
+
| | `GET /admin/users/:id`, `PUT /admin/users/:id`, `DELETE /admin/users/:id` |
|
|
80
|
+
| | `POST /admin/users/:id/suspend`, `POST /admin/users/:id/activate`, `POST /admin/users/:id/verify` |
|
|
81
|
+
| | `GET /admin/users/export` (CSV) |
|
|
82
|
+
| Analytics | `GET /admin/analytics`, `/users`, `/revenue`, `/traffic` |
|
|
83
|
+
| Admins | `GET /admin/admins`, `POST /admin/admins` |
|
|
84
|
+
| | `GET /admin/admins/:id`, `PUT /admin/admins/:id`, `DELETE /admin/admins/:id` |
|
|
85
|
+
| Notifications | `GET /admin/notifications`, `POST /admin/notifications` |
|
|
86
|
+
| | `POST /admin/notifications/broadcast` |
|
|
87
|
+
| Logs | `GET /admin/logs/audit`, `/activity`, `/security` |
|
|
88
|
+
| Settings | `GET /admin/settings`, `PUT /admin/settings` |
|
|
89
|
+
| System | `GET /admin/system/health` |
|
|
90
|
+
| | `DELETE /admin/system/cache` |
|
|
91
|
+
| Support | `GET /admin/tickets`, `GET /admin/tickets/:id`, `PUT /admin/tickets/:id` |
|
|
92
|
+
| Content — FAQs | `GET /admin/content/faqs`, `POST /admin/content/faqs` |
|
|
93
|
+
| | `GET/PUT/DELETE /admin/content/faqs/:id` |
|
|
94
|
+
| Content — Blog | `GET /admin/content/blogs`, `POST /admin/content/blogs` |
|
|
95
|
+
| | `GET/PUT/DELETE /admin/content/blogs/:id` |
|
|
96
|
+
| Content — Categories | `GET /admin/content/categories`, `POST /admin/content/categories` |
|
|
97
|
+
| | `GET/PUT/DELETE /admin/content/categories/:id` |
|
|
98
|
+
| Billing — Plans | `GET /admin/billing/plans`, `POST /admin/billing/plans` |
|
|
99
|
+
| | `GET/PUT/DELETE /admin/billing/plans/:id` |
|
|
100
|
+
| Billing — Coupons | `GET /admin/billing/coupons`, `POST /admin/billing/coupons` |
|
|
101
|
+
| | `GET/PUT/DELETE /admin/billing/coupons/:id` |
|
|
102
|
+
| Billing — Subscriptions | `GET /admin/billing/subscriptions` |
|
|
103
|
+
| Roles *(only if RBAC also enabled)* | `GET /admin/roles`, `POST /admin/roles` |
|
|
104
|
+
| | `GET/PUT/DELETE /admin/roles/:id` |
|
|
105
|
+
|
|
106
|
+
All admin routes export `middlewares = [requireAuth('admin')]` if [RBAC](./rbac.md) is enabled — otherwise `middlewares = [requireAuth]` and each handler inline-checks `user.role === 'admin'`.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Related
|
|
111
|
+
|
|
112
|
+
- [RBAC](./rbac.md) — how the `requireAuth('role')` shorthand and the `Role` model plug into these routes
|
|
113
|
+
- [Mailer](./mailer.md) — hook up real email for verification/reset flows
|
|
114
|
+
- [Database](./database.md) — MongoDB vs PostgreSQL implementation status
|
|
115
|
+
- [Project Structure](../getting-started/project-structure.md) — where these files land on disk
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Logging & Request IDs
|
|
2
|
+
|
|
3
|
+
EFC logs through [pino](https://getpino.io): structured JSON in production, readable one-line output in a development terminal. Every request gets an ID that follows it through every log line.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Configuration
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
ignite({
|
|
11
|
+
...config,
|
|
12
|
+
logging: {
|
|
13
|
+
level: 'info', // trace | debug | info | warn | error | fatal | silent
|
|
14
|
+
pretty: undefined, // default: true in a non-production TTY, JSON otherwise
|
|
15
|
+
requests: true, // one line per completed request
|
|
16
|
+
},
|
|
17
|
+
});
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`logging: false` silences framework logs entirely (request IDs are still assigned).
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Request IDs
|
|
25
|
+
|
|
26
|
+
Each request gets an ID — a well-formed incoming `X-Request-Id` header (e.g. from your load balancer: letters, digits, `.`, `:`, `-`, `_`, up to 128 chars) or a fresh UUID. It is:
|
|
27
|
+
|
|
28
|
+
- echoed back in the `X-Request-Id` response header,
|
|
29
|
+
- available as `req.id`,
|
|
30
|
+
- bound to a child logger, `req.log`, and to `getLogger()` anywhere in the request's async chain — models, helpers, anything awaited from the handler.
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { getLogger } from 'express-file-cluster';
|
|
34
|
+
|
|
35
|
+
export async function chargeCard(orderId: string) {
|
|
36
|
+
getLogger().info({ orderId }, 'charging card'); // carries the current request's reqId
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Outside a request (startup, task handlers, timers) `getLogger()` returns the root logger. `logger` is a convenience proxy for `getLogger()`.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Request lines
|
|
45
|
+
|
|
46
|
+
With `requests: true`, every completed request logs method, URL, status and duration — at `info` for < 400, `warn` for 4xx, `error` for 5xx:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
12:00:01 INFO [w2] 3f9c2a1b GET /v1/api/users 200 method=GET url=/v1/api/users status=200 durationMs=3.4
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
In production the same record is JSON:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{"level":30,"time":"2026-10-10T12:00:01.123Z","worker":"w2","reqId":"3f9c2a1b-…","method":"GET","url":"/v1/api/users","status":200,"durationMs":3.4,"msg":"GET /v1/api/users 200"}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`worker` is `primary` or `w<N>` for cluster worker N, so interleaved output from many workers stays attributable.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Errors
|
|
63
|
+
|
|
64
|
+
Unhandled errors are logged at `error` with the request ID and full stack (`err`) before the 500 response is sent. Task failures log the task name, job ID and attempt number.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Shipping logs
|
|
69
|
+
|
|
70
|
+
JSON lines on stdout is what log collectors (Datadog, Loki, CloudWatch, Vector) expect — no transport configuration needed. For custom pino transports, set `pretty: false` and pipe stdout.
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Mailer
|
|
2
|
+
|
|
3
|
+
`create-efc-app` can scaffold a working transactional email setup — a real `nodemailer` transport wired to environment variables, plus a `SendEmail` background task — so you never hand-write SMTP boilerplate.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Enabling it
|
|
8
|
+
|
|
9
|
+
Toggle **Mailer** in the features multiselect during scaffolding:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
? Features: (space to toggle, enter to confirm)
|
|
13
|
+
◉ Background tasks
|
|
14
|
+
...
|
|
15
|
+
◉ Mailer
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
You'll then be asked to choose a provider:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
? Email provider:
|
|
22
|
+
❯ Gmail smtp.gmail.com, preconfigured
|
|
23
|
+
Other (custom SMTP) you'll provide host + port
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- **Gmail** — the wizard hard-codes `SMTP_HOST=smtp.gmail.com` and `SMTP_PORT=465` for you. No host or port question is asked.
|
|
27
|
+
- **Other (custom SMTP)** — you're prompted for `SMTP host:` (e.g. `smtp.mailtrap.io`, `smtp.sendgrid.net`) and `SMTP port:` (default `587`).
|
|
28
|
+
|
|
29
|
+
Both paths then ask for the sending address and password:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
? Gmail address: you@example.com
|
|
33
|
+
? Gmail app password (16 characters): ****************
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Gmail requires an App Password, not your login password
|
|
39
|
+
|
|
40
|
+
Google no longer accepts a regular account password for SMTP. If you pick **Gmail**, the wizard shows a note before the password prompt:
|
|
41
|
+
|
|
42
|
+
> Google no longer accepts your regular account password for SMTP.
|
|
43
|
+
> Generate a 16-character App Password: **Google Account → Security → 2-Step Verification → App passwords**.
|
|
44
|
+
> Enter it below without spaces (not your Gmail login password).
|
|
45
|
+
|
|
46
|
+
The password prompt then **validates the input is exactly 16 characters** (after stripping whitespace) — if you paste your normal password, or the app password with spaces left in from Google's display format (`abcd efgh ijkl mnop`), the wizard rejects it and asks again. Spaces are stripped automatically before the value is written to `.env`.
|
|
47
|
+
|
|
48
|
+
2-Step Verification must be enabled on the Google account before an App Password can be generated.
|
|
49
|
+
|
|
50
|
+
For a custom SMTP provider, use whatever credential that provider issues (API key, SMTP password, etc.) — there's no length validation since providers vary.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## What gets generated
|
|
55
|
+
|
|
56
|
+
### `.env`
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
APP_URL=http://localhost:3000
|
|
60
|
+
SMTP_HOST=smtp.gmail.com
|
|
61
|
+
SMTP_PORT=465
|
|
62
|
+
SMTP_USER=you@example.com
|
|
63
|
+
SMTP_PASS=abcdefghijklmnop # Gmail App Password (16 chars) — NOT your regular Gmail password. Generate at: Google Account > Security > 2-Step Verification > App passwords
|
|
64
|
+
SMTP_FROM=you@example.com
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`APP_URL` is the base URL used to build the links inside verification/reset emails (see below) — update it to your real domain before deploying. For a custom provider, `SMTP_HOST`/`SMTP_PORT` reflect what you entered and the comment on `SMTP_PASS` is omitted.
|
|
68
|
+
|
|
69
|
+
### `.env.example`
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
APP_URL=http://localhost:3000
|
|
73
|
+
SMTP_HOST=smtp.gmail.com
|
|
74
|
+
SMTP_PORT=465
|
|
75
|
+
SMTP_USER=your@email.com
|
|
76
|
+
SMTP_PASS=your_16_char_app_password
|
|
77
|
+
SMTP_FROM=noreply@yourapp.com
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
(`your_smtp_password` instead of `your_16_char_app_password` for a custom provider.)
|
|
81
|
+
|
|
82
|
+
### `src/tasks/SendEmail.ts`
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
86
|
+
import nodemailer from 'nodemailer';
|
|
87
|
+
|
|
88
|
+
interface SendEmailPayload {
|
|
89
|
+
to: string;
|
|
90
|
+
subject: string;
|
|
91
|
+
body: string;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const transporter = nodemailer.createTransport({
|
|
95
|
+
host: process.env.SMTP_HOST,
|
|
96
|
+
port: Number(process.env.SMTP_PORT ?? 587),
|
|
97
|
+
secure: Number(process.env.SMTP_PORT) === 465,
|
|
98
|
+
auth: {
|
|
99
|
+
user: process.env.SMTP_USER,
|
|
100
|
+
pass: process.env.SMTP_PASS,
|
|
101
|
+
},
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
export default defineTask<SendEmailPayload>(async (payload) => {
|
|
105
|
+
await transporter.sendMail({
|
|
106
|
+
from: process.env.SMTP_FROM ?? process.env.SMTP_USER,
|
|
107
|
+
to: payload.to,
|
|
108
|
+
subject: payload.subject,
|
|
109
|
+
html: payload.body,
|
|
110
|
+
});
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
If you enable **Background tasks** but not **Mailer**, this same file is created as a `console.log` stub instead — swap in the transporter above later if you add email support.
|
|
115
|
+
|
|
116
|
+
`nodemailer` (and `@types/nodemailer` for TypeScript projects) is added to `package.json` automatically.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Sending an email from a route
|
|
121
|
+
|
|
122
|
+
Trigger the task with `enqueue()` — don't call the transporter directly from a request handler, since SMTP round-trips shouldn't block a response:
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
// src/api/users/index.ts
|
|
126
|
+
import { enqueue } from 'express-file-cluster/tasks';
|
|
127
|
+
import { User } from '../../model/User.js';
|
|
128
|
+
|
|
129
|
+
export const POST = async (req, res) => {
|
|
130
|
+
const user = await User.create(req.body);
|
|
131
|
+
|
|
132
|
+
await enqueue('SendEmail', {
|
|
133
|
+
to: user.email,
|
|
134
|
+
subject: 'Welcome!',
|
|
135
|
+
body: 'Thanks for signing up.',
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
res.status(202).json({ id: user.id, queued: true });
|
|
139
|
+
};
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
See [Background Tasks](../core-concepts/background-tasks.md) for retry/backoff behavior and [Environment Variables](./environment-variables.md) for the full `SMTP_*` reference.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Auth routes wired to the mailer
|
|
147
|
+
|
|
148
|
+
If **User portal** is enabled alongside **Mailer** (MongoDB only), these generated routes automatically `enqueue('SendEmail', ...)` instead of leaving a `// TODO`:
|
|
149
|
+
|
|
150
|
+
| Route | Sends |
|
|
151
|
+
|---|---|
|
|
152
|
+
| `POST /auth/register` | Verification email with a link to `${APP_URL}/auth/verify-email?token=...` |
|
|
153
|
+
| `POST /auth/verify-email` (resend) | Same verification email, with a freshly generated token |
|
|
154
|
+
| `POST /auth/forgot-password` | Reset email with a link to `${APP_URL}/auth/reset-password?token=...` |
|
|
155
|
+
|
|
156
|
+
With **User portal** but *without* **Mailer**, these routes still generate and store the token in the database — they just leave a `// TODO: email this token to the user` comment where the `enqueue()` call would go, since there's no `SendEmail` task to call.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Troubleshooting
|
|
161
|
+
|
|
162
|
+
| Symptom | Cause |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `Invalid login: 535-5.7.8 Username and Password not accepted` | You used your regular Gmail password instead of a 16-character App Password, or 2-Step Verification isn't enabled on the account. |
|
|
165
|
+
| `SMTP connection refused` (visible in task error logs) | Wrong `SMTP_HOST`/`SMTP_PORT`, or a firewall blocking outbound SMTP. |
|
|
166
|
+
| App Password option missing in Google Account settings | 2-Step Verification must be turned on first — Google hides App Passwords otherwise. |
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Migrations & Seeds
|
|
2
|
+
|
|
3
|
+
`efc db` manages your schema and fixture data on both MongoDB and PostgreSQL.
|
|
4
|
+
|
|
5
|
+
| Command | Does |
|
|
6
|
+
|---|---|
|
|
7
|
+
| `efc db migrate` | Runs pending migrations in `src/migrations/` as one new batch |
|
|
8
|
+
| `efc db rollback [--steps n]` | Reverts the last batch (or `n` batches), newest first |
|
|
9
|
+
| `efc db status` | Lists applied (with batch) and pending migrations |
|
|
10
|
+
| `efc db seed [name]` | Runs every seed in `src/seeds/`, or just one |
|
|
11
|
+
| `efc db studio [-p 4983]` | Opens a read-only database browser on `127.0.0.1` |
|
|
12
|
+
|
|
13
|
+
All of them read `DATABASE_URL` from the environment or `.env` (override with `--database-url`); the engine follows the URL scheme.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Writing a migration
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
efc generate migration add_orders
|
|
21
|
+
# → src/migrations/20261010120000_add_orders.ts
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import type { MigrationContext } from 'express-file-cluster';
|
|
26
|
+
import { Order } from '../model/Order.js';
|
|
27
|
+
|
|
28
|
+
export async function up({ db, engine }: MigrationContext): Promise<void> {
|
|
29
|
+
await Order.sync();
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export async function down({ db, engine }: MigrationContext): Promise<void> {
|
|
33
|
+
await Order.drop();
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- Files run in **filename order**; the generator's UTC timestamp prefix keeps that chronological.
|
|
38
|
+
- `db` is the native client — a mongoose `Connection` or a node-postgres `Pool` — for anything models don't cover (`db.query('ALTER TABLE …')`).
|
|
39
|
+
- `Model.sync()` reconciles the table/collection with the model (see [the schema takes care of itself](./database.md#the-schema-takes-care-of-itself)). It never drops a column or data, so it's safe to call from several migrations.
|
|
40
|
+
- `Model.drop()` removes the table/collection — for `down()`.
|
|
41
|
+
|
|
42
|
+
**Do I need migrations at all?** Not for schema shape: tables and indexes are reconciled automatically on first use. Use migrations for what sync deliberately won't do — renaming or splitting columns, backfilling data, dropping columns — and, if you run with `autoSync: false`, for every schema change. Projects created with `create-efc-app` include `src/migrations/00000000000000_init`, which syncs every generated model; running it is optional.
|
|
43
|
+
|
|
44
|
+
### `efc db sync`
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
efc db sync --dry-run # every model in src/model(s)/: what would change (SQL on PostgreSQL)
|
|
48
|
+
efc db sync # apply
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Handy in CI (fail if `--dry-run` reports pending changes) and as the deploy step when `autoSync` is off.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Batches and rollback
|
|
56
|
+
|
|
57
|
+
Applied migrations are recorded in `efc_migrations` (a table or collection) with a batch number. Everything one `migrate` run applies shares a batch, and `rollback` undoes exactly that unit:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
efc db migrate # applies 0001, 0002 → batch 1
|
|
61
|
+
efc db migrate # applies 0003 → batch 2
|
|
62
|
+
efc db rollback # reverts 0003
|
|
63
|
+
efc db rollback # reverts 0002, then 0001
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
A migration that throws stops the run with exit code 1 and is **not** recorded, so the next `migrate` retries it. Earlier migrations in the same run stay applied — make migrations idempotent where you can (`sync()` already is).
|
|
67
|
+
|
|
68
|
+
On PostgreSQL, `migrate` and `rollback` take an advisory lock, so several instances running migrations at deploy time serialise instead of racing.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Seeds
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
efc generate seed demo_users
|
|
76
|
+
# → src/seeds/demo_users.ts
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { User } from '../model/User.js';
|
|
81
|
+
|
|
82
|
+
export default async function seed() {
|
|
83
|
+
await User.createMany([{ name: 'Ada', email: 'ada@example.com', password: '…' }]);
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`efc db seed` runs all seeds in filename order; `efc db seed demo_users` runs one. Seeds aren't tracked — they run every time.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## TypeScript and production
|
|
92
|
+
|
|
93
|
+
The commands run your files in a child process: under `tsx` against `src/` when `tsx` is installed (development), otherwise with plain `node` against the compiled `dist/src/` — production images ship without devDependencies. Force the compiled files with `--dist`.
|
|
94
|
+
|
|
95
|
+
```dockerfile
|
|
96
|
+
# Run migrations as a release step, before starting the new version
|
|
97
|
+
CMD ["sh", "-c", "npx efc db migrate --dist && npx efc start prod"]
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`EFC_DEBUG=1` prints the full stack when a migration or seed fails.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Studio
|
|
105
|
+
|
|
106
|
+
`efc db studio` serves a read-only browser at `http://127.0.0.1:4983`: every table/collection with its row count, paginated rows, and expandable JSON cells. It binds to localhost only and rejects anything but `GET`.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Role-Based Access Control (RBAC)
|
|
2
|
+
|
|
3
|
+
Role checks are built into `requireAuth` itself — call it with role names (`requireAuth('admin')`) instead of a separate middleware (see [Authentication](./authentication.md)). `create-efc-app` can also scaffold a `Role` model and role-management API for you via the **RBAC** feature option.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Enabling it
|
|
8
|
+
|
|
9
|
+
Toggle **Role-based access control** in the features multiselect:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
? Features: (space to toggle, enter to confirm)
|
|
13
|
+
◉ User portal
|
|
14
|
+
◉ Admin portal
|
|
15
|
+
◉ Role-based access control
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
RBAC is most useful alongside **User portal** and/or **Admin portal**, since it changes how their generated routes are protected — but it can be toggled independently.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## What gets generated
|
|
23
|
+
|
|
24
|
+
### Route protection
|
|
25
|
+
|
|
26
|
+
Every generated route that would otherwise export `middlewares = [requireAuth]` instead exports:
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// User-facing routes
|
|
30
|
+
export const middlewares = [requireAuth('user', 'admin')];
|
|
31
|
+
|
|
32
|
+
// Admin-facing routes
|
|
33
|
+
export const middlewares = [requireAuth('admin')];
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`requireAuth('admin')` verifies the JWT *and* checks that `payload.role` is one of the given roles — returning `401` if the token is missing/invalid, `403` if the role doesn't match.
|
|
37
|
+
|
|
38
|
+
If RBAC is **not** enabled, admin routes fall back to an inline guard at the top of the handler instead:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
export const middlewares = [requireAuth];
|
|
42
|
+
|
|
43
|
+
export const GET = async (req, res) => {
|
|
44
|
+
const user = (req as any).user;
|
|
45
|
+
if (user?.role !== 'admin') {
|
|
46
|
+
return res.status(403).json({ error: 'Forbidden: Admin access required' });
|
|
47
|
+
}
|
|
48
|
+
// ...
|
|
49
|
+
};
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Both approaches produce the same 401/403 behavior — RBAC-on just centralizes the check into `requireAuth(...)` and adds the `Role` model below.
|
|
53
|
+
|
|
54
|
+
### `Role` model
|
|
55
|
+
|
|
56
|
+
A `src/model/Role.ts` model is created (MongoDB: a real `defineModel`-backed collection; PostgreSQL: a commented-out Drizzle stub, per the current [database support status](./database.md)).
|
|
57
|
+
|
|
58
|
+
### Admin role management routes
|
|
59
|
+
|
|
60
|
+
If **RBAC** and **Admin portal** are both enabled, a full role-management API is scaffolded:
|
|
61
|
+
|
|
62
|
+
| Method | Path |
|
|
63
|
+
|---|---|
|
|
64
|
+
| `GET` | `/admin/roles` |
|
|
65
|
+
| `POST` | `/admin/roles` |
|
|
66
|
+
| `GET` | `/admin/roles/:id` |
|
|
67
|
+
| `PUT` | `/admin/roles/:id` |
|
|
68
|
+
| `DELETE` | `/admin/roles/:id` |
|
|
69
|
+
|
|
70
|
+
See [Generated Portals](./generated-portals.md) for the complete route/model inventory.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Using it yourself
|
|
75
|
+
|
|
76
|
+
You don't need the scaffolder to use this pattern — `requireAuth(...roles)` is exported from `express-file-cluster/auth` in every EFC project:
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
// src/api/admin/dashboard.ts
|
|
80
|
+
import { requireAuth } from 'express-file-cluster/auth';
|
|
81
|
+
|
|
82
|
+
export const middlewares = [requireAuth('admin')];
|
|
83
|
+
|
|
84
|
+
export const GET = async (_req, res) => {
|
|
85
|
+
res.json({ stats: { users: 42 } });
|
|
86
|
+
};
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Pass multiple roles to allow any of them: `requireAuth('user', 'admin')`. See the [Auth API reference](../api-reference/auth.md#requireauth) for the full signature.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Request Validation
|
|
2
|
+
|
|
3
|
+
Route files can export a `schema` that validates `params`, `query` and `body` before the handler runs. Invalid requests never reach your code; valid ones arrive already parsed.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Any validator, no lock-in
|
|
8
|
+
|
|
9
|
+
EFC accepts any [Standard Schema](https://standardschema.dev) validator — zod 3.24+, valibot, arktype, effect/schema — plus anything exposing a zod-style `safeParse`. It never imports a validation library, so install the one you like:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install zod
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Per method, or for the whole file
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
// src/api/products/[id].ts
|
|
21
|
+
import { z } from 'zod';
|
|
22
|
+
|
|
23
|
+
export const schema = {
|
|
24
|
+
GET: {
|
|
25
|
+
params: z.object({ id: z.string().uuid() }),
|
|
26
|
+
query: z.object({ include: z.enum(['reviews', 'stock']).optional() }),
|
|
27
|
+
},
|
|
28
|
+
PATCH: {
|
|
29
|
+
params: z.object({ id: z.string().uuid() }),
|
|
30
|
+
body: z.object({ price: z.number().positive(), title: z.string().min(2) }).partial(),
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
export const GET = async (req, res) => { /* ... */ };
|
|
35
|
+
export const PATCH = async (req, res) => { /* ... */ };
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
When every method shares the same rules, skip the method keys:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
export const schema = { params: z.object({ id: z.coerce.number().int() }) };
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
A method-keyed entry wins over the file-wide one; methods with no entry are not validated.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Parsed output replaces the raw input
|
|
49
|
+
|
|
50
|
+
On success, `req.params`, `req.query` and `req.body` are replaced by the validator's **output** — coercions (`z.coerce.number()`), defaults (`.default('member')`) and transforms apply:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
export const schema = { POST: { body: z.object({ age: z.coerce.number(), role: z.string().default('member') }) } };
|
|
54
|
+
|
|
55
|
+
export const POST = async (req, res) => {
|
|
56
|
+
req.body; // { age: 21, role: 'member' } for an input of { age: '21' }
|
|
57
|
+
};
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Error response
|
|
63
|
+
|
|
64
|
+
All issues from every location are returned together with status **400**:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"error": "Validation failed",
|
|
69
|
+
"statusCode": 400,
|
|
70
|
+
"issues": [
|
|
71
|
+
{ "location": "body", "path": "email", "message": "Invalid email address" },
|
|
72
|
+
{ "location": "query", "path": "page", "message": "Expected number, received nan" }
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`path` is dot-joined inside its location (`address.zip`), empty for the root.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Ordering
|
|
82
|
+
|
|
83
|
+
The request pipeline for a route is:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
global middleware → file middlewares → schema validation → handler
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
So authentication in `middlewares` still responds 401/403 before any 400 — unauthenticated callers can't probe your validation rules.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Model-level validation is separate
|
|
94
|
+
|
|
95
|
+
`schema` validates the HTTP request. `defineModel` validates what you write to the database (types, `required`, `enum`, `min`/`max`, `match`, custom `validate`) and throws a `ModelValidationError` — also a 400 with `issues`. Use both: request schemas for the API contract, model rules for data integrity. See [Database](./database.md).
|