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.
Files changed (116) hide show
  1. package/README.md +71 -33
  2. package/dist/auth/index.cjs +12 -2
  3. package/dist/auth/index.cjs.map +1 -1
  4. package/dist/auth/index.d.cts +13 -2
  5. package/dist/auth/index.d.ts +13 -2
  6. package/dist/auth/index.js +12 -2
  7. package/dist/chunk-3VWD2ZED.js +60 -0
  8. package/dist/chunk-3VWD2ZED.js.map +1 -0
  9. package/dist/chunk-47K2532L.cjs +196 -0
  10. package/dist/chunk-47K2532L.cjs.map +1 -0
  11. package/dist/chunk-5PDAWMGF.js +438 -0
  12. package/dist/chunk-5PDAWMGF.js.map +1 -0
  13. package/dist/chunk-7YEX4MQV.cjs +38 -0
  14. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  15. package/dist/chunk-ALBDM5R3.cjs +60 -0
  16. package/dist/chunk-ALBDM5R3.cjs.map +1 -0
  17. package/dist/chunk-JJJJTACK.js +196 -0
  18. package/dist/chunk-JJJJTACK.js.map +1 -0
  19. package/dist/chunk-LJNSJFOL.js +38 -0
  20. package/dist/chunk-LJNSJFOL.js.map +1 -0
  21. package/dist/chunk-M7MUPWCE.js +116 -0
  22. package/dist/chunk-M7MUPWCE.js.map +1 -0
  23. package/dist/chunk-PMF4GMHD.js +154 -0
  24. package/dist/chunk-PMF4GMHD.js.map +1 -0
  25. package/dist/chunk-QTRGJ2EN.cjs +2635 -0
  26. package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
  27. package/dist/chunk-RSBW2B3D.cjs +126 -0
  28. package/dist/chunk-RSBW2B3D.cjs.map +1 -0
  29. package/dist/chunk-RTFJ32T5.js +2635 -0
  30. package/dist/chunk-RTFJ32T5.js.map +1 -0
  31. package/dist/chunk-SFVEQ2T5.cjs +438 -0
  32. package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
  33. package/dist/chunk-SZT36SGB.cjs +154 -0
  34. package/dist/chunk-SZT36SGB.cjs.map +1 -0
  35. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  36. package/dist/chunk-ULQXD4YZ.cjs +116 -0
  37. package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
  38. package/dist/chunk-VYHJX54R.js +126 -0
  39. package/dist/chunk-VYHJX54R.js.map +1 -0
  40. package/dist/cli/db-runner.cjs +497 -0
  41. package/dist/cli/db-runner.cjs.map +1 -0
  42. package/dist/cli/db-runner.d.cts +2 -0
  43. package/dist/cli/db-runner.d.ts +2 -0
  44. package/dist/cli/db-runner.js +497 -0
  45. package/dist/cli/db-runner.js.map +1 -0
  46. package/dist/cli/index.cjs +447 -69
  47. package/dist/cli/index.cjs.map +1 -1
  48. package/dist/cli/index.js +473 -95
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/docs/api-reference/auth.md +232 -0
  51. package/dist/docs/api-reference/compose.md +78 -0
  52. package/dist/docs/api-reference/db.md +351 -0
  53. package/dist/docs/api-reference/http-error.md +109 -0
  54. package/dist/docs/api-reference/ignite.md +323 -0
  55. package/dist/docs/api-reference/table.md +250 -0
  56. package/dist/docs/api-reference/tasks.md +140 -0
  57. package/dist/docs/cli/db.md +38 -0
  58. package/dist/docs/cli/diagnostics.md +145 -0
  59. package/dist/docs/cli/generate.md +120 -0
  60. package/dist/docs/cli/index.md +48 -0
  61. package/dist/docs/cli/start.md +112 -0
  62. package/dist/docs/contributing/index.md +139 -0
  63. package/dist/docs/core-concepts/background-tasks.md +228 -0
  64. package/dist/docs/core-concepts/clustering.md +114 -0
  65. package/dist/docs/core-concepts/file-based-routing.md +235 -0
  66. package/dist/docs/core-concepts/index.md +79 -0
  67. package/dist/docs/core-concepts/middleware.md +144 -0
  68. package/dist/docs/getting-started/index.md +91 -0
  69. package/dist/docs/getting-started/project-structure.md +154 -0
  70. package/dist/docs/guides/ai-agents.md +48 -0
  71. package/dist/docs/guides/authentication.md +196 -0
  72. package/dist/docs/guides/caching.md +124 -0
  73. package/dist/docs/guides/database.md +217 -0
  74. package/dist/docs/guides/deployment.md +171 -0
  75. package/dist/docs/guides/environment-variables.md +106 -0
  76. package/dist/docs/guides/error-handling.md +172 -0
  77. package/dist/docs/guides/generated-portals.md +115 -0
  78. package/dist/docs/guides/logging.md +70 -0
  79. package/dist/docs/guides/mailer.md +166 -0
  80. package/dist/docs/guides/migrations.md +106 -0
  81. package/dist/docs/guides/rbac.md +89 -0
  82. package/dist/docs/guides/validation.md +95 -0
  83. package/dist/docs/index.md +93 -0
  84. package/dist/docs/skills/SKILL.md +44 -0
  85. package/dist/docs/skills/api-surface.md +308 -0
  86. package/dist/docs/skills/auth-internals.md +141 -0
  87. package/dist/docs/skills/pre-flight.md +142 -0
  88. package/dist/docs/skills/routing-rules.md +114 -0
  89. package/dist/docs/skills/tasks-internals.md +172 -0
  90. package/dist/docs/skills/what-not-to-invent.md +251 -0
  91. package/dist/index.cjs +289 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +472 -7
  94. package/dist/index.d.ts +472 -7
  95. package/dist/index.js +283 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
  98. package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
  99. package/dist/pgboss-backend-UUJOVEYK.js +14 -0
  100. package/dist/pgboss-backend-UUJOVEYK.js.map +1 -0
  101. package/dist/tasks/index.cjs.map +1 -1
  102. package/dist/tasks/index.d.cts +1 -1
  103. package/dist/tasks/index.d.ts +1 -1
  104. package/dist/types-DJCPAsM4.d.cts +541 -0
  105. package/dist/types-DJCPAsM4.d.ts +541 -0
  106. package/package.json +28 -5
  107. package/dist/chunk-6522HS2J.cjs +0 -99
  108. package/dist/chunk-6522HS2J.cjs.map +0 -1
  109. package/dist/chunk-DGVOJNR6.cjs +0 -55
  110. package/dist/chunk-DGVOJNR6.cjs.map +0 -1
  111. package/dist/chunk-KOHLLUN7.js +0 -55
  112. package/dist/chunk-KOHLLUN7.js.map +0 -1
  113. package/dist/chunk-VIP3PFWZ.js +0 -99
  114. package/dist/chunk-VIP3PFWZ.js.map +0 -1
  115. package/dist/types-BusbSenn.d.cts +0 -162
  116. 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).