express-file-cluster 0.3.15 → 0.7.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-277BSYVH.js +127 -0
- package/dist/chunk-277BSYVH.js.map +1 -0
- package/dist/chunk-6OGOVV57.js +3847 -0
- package/dist/chunk-6OGOVV57.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-AZYXQU3Z.cjs +3847 -0
- package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
- package/dist/chunk-BUBXO7WU.js +170 -0
- package/dist/chunk-BUBXO7WU.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-MGH4VDV3.cjs +170 -0
- package/dist/chunk-MGH4VDV3.cjs.map +1 -0
- package/dist/chunk-R34R7QPD.cjs +116 -0
- package/dist/chunk-R34R7QPD.cjs.map +1 -0
- package/dist/chunk-RS4MXCPW.js +116 -0
- package/dist/chunk-RS4MXCPW.js.map +1 -0
- package/dist/chunk-T4OHFU5T.cjs +154 -0
- package/dist/chunk-T4OHFU5T.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-TRC4DUZB.js +438 -0
- package/dist/chunk-TRC4DUZB.js.map +1 -0
- package/dist/chunk-TYR2GZZE.cjs +196 -0
- package/dist/chunk-TYR2GZZE.cjs.map +1 -0
- package/dist/chunk-UBQYQPBU.js +154 -0
- package/dist/chunk-UBQYQPBU.js.map +1 -0
- package/dist/chunk-UTM4PEVG.js +196 -0
- package/dist/chunk-UTM4PEVG.js.map +1 -0
- package/dist/chunk-YL37D6KM.cjs +127 -0
- package/dist/chunk-YL37D6KM.cjs.map +1 -0
- package/dist/chunk-ZDM5JHVK.cjs +438 -0
- package/dist/chunk-ZDM5JHVK.cjs.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 +326 -0
- package/dist/docs/api-reference/table.md +458 -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 +108 -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 +309 -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 +264 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +699 -7
- package/dist/index.d.ts +699 -7
- package/dist/index.js +258 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
- package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs.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-B6lVw4bj.d.cts +588 -0
- package/dist/types-B6lVw4bj.d.ts +588 -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,172 @@
|
|
|
1
|
+
# Error Handling Guide
|
|
2
|
+
|
|
3
|
+
EFC provides a structured error model that converts exceptions into clean HTTP responses without try/catch in every handler.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## How it works
|
|
8
|
+
|
|
9
|
+
Every route handler is wrapped in `asyncWrap`, which passes any thrown error or rejected promise to Express's `next(err)`. The global error handler at the bottom of the middleware stack then inspects the error and responds.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
throw new HttpError(404, 'Not found')
|
|
13
|
+
↓
|
|
14
|
+
asyncWrap catches it → next(err)
|
|
15
|
+
↓
|
|
16
|
+
EFC global error handler
|
|
17
|
+
↓
|
|
18
|
+
HTTP 404 { "error": "Not found", "statusCode": 404 }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## `HttpError`
|
|
24
|
+
|
|
25
|
+
Throw `HttpError` to signal a specific HTTP status:
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { HttpError } from 'express-file-cluster';
|
|
29
|
+
|
|
30
|
+
export const GET = async (req, res) => {
|
|
31
|
+
const user = await User.findById(req.params.id);
|
|
32
|
+
if (!user) throw new HttpError(404, 'User not found');
|
|
33
|
+
res.json(user);
|
|
34
|
+
};
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The default response shape:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"error": "User not found",
|
|
42
|
+
"statusCode": 404
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
See the full [`HttpError` reference](../api-reference/http-error.md).
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Unhandled errors
|
|
51
|
+
|
|
52
|
+
Any `throw` that is not an `HttpError` (e.g. a database error, a null pointer, an unexpected exception) is treated as a server error:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"error": "Internal Server Error",
|
|
57
|
+
"statusCode": 500
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The original error is logged at `error` level with the request ID and stack (see [Logging](./logging.md)):
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
12:00:01 ERROR [w1] 3f9c2a1b Unhandled error
|
|
65
|
+
TypeError: Cannot read properties of null
|
|
66
|
+
at GET (src/api/users/[id].ts:8:21)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Validation and database errors
|
|
72
|
+
|
|
73
|
+
These arrive as `HttpError` subclasses, so they need no handling in route code:
|
|
74
|
+
|
|
75
|
+
| Source | Status | Body |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| Route `schema` rejects the request | `400` | `{ "error": "Validation failed", "statusCode": 400, "issues": [{ "location", "path", "message" }] }` |
|
|
78
|
+
| `defineModel` write fails validation (`ModelValidationError`) | `400` | `{ "error": "User validation failed: email: is required", "statusCode": 400, "issues": [{ "path", "message" }] }` |
|
|
79
|
+
| Duplicate value of a `unique` field | `409` | `{ "error": "User with this email already exists", "statusCode": 409 }` |
|
|
80
|
+
|
|
81
|
+
Catch `ModelValidationError` only when you want to react differently:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { ModelValidationError } from 'express-file-cluster';
|
|
85
|
+
|
|
86
|
+
try {
|
|
87
|
+
await User.create(req.body);
|
|
88
|
+
} catch (err) {
|
|
89
|
+
if (err instanceof ModelValidationError && err.issues.some((i) => i.path === 'email')) {
|
|
90
|
+
throw new HttpError(422, 'Please provide a valid email');
|
|
91
|
+
}
|
|
92
|
+
throw err;
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Custom global error handler
|
|
99
|
+
|
|
100
|
+
Override the built-in handler with `onError` in `ignite()`:
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
import { HttpError } from 'express-file-cluster';
|
|
104
|
+
import type { ErrorRequestHandler } from 'express';
|
|
105
|
+
|
|
106
|
+
const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
|
|
107
|
+
const status = err instanceof HttpError ? err.statusCode : 500;
|
|
108
|
+
const message = err instanceof HttpError ? err.message : 'Internal Server Error';
|
|
109
|
+
|
|
110
|
+
logger.error({ err, url: req.url, method: req.method });
|
|
111
|
+
|
|
112
|
+
res.status(status).json({
|
|
113
|
+
error: message,
|
|
114
|
+
path: req.path,
|
|
115
|
+
requestId: req.headers['x-request-id'],
|
|
116
|
+
});
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
ignite({ onError: errorHandler });
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Errors in middleware
|
|
125
|
+
|
|
126
|
+
Middleware errors are forwarded the same way — call `next(err)` or `throw` from an async middleware and the global handler picks it up:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
// src/middlewares/validate.ts
|
|
130
|
+
import type { RequestHandler } from 'express';
|
|
131
|
+
import { HttpError } from 'express-file-cluster';
|
|
132
|
+
import { z } from 'zod';
|
|
133
|
+
|
|
134
|
+
export function validateBody(schema: z.ZodType): RequestHandler {
|
|
135
|
+
return async (req, _res, next) => {
|
|
136
|
+
const result = schema.safeParse(req.body);
|
|
137
|
+
if (!result.success) {
|
|
138
|
+
return next(new HttpError(422, result.error.message));
|
|
139
|
+
}
|
|
140
|
+
req.body = result.data;
|
|
141
|
+
next();
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Errors in tasks
|
|
149
|
+
|
|
150
|
+
Task errors do not crash the application. The backend (BullMQ or pg-boss) catches failed jobs, retries them according to `retries` and `backoff`, and dead-letters them after the last attempt. Each failure is logged with the task, job ID and attempt:
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
12:00:01 ERROR [w2] Task SendEmail failed task=SendEmail jobId=1842 attempt=2
|
|
154
|
+
Error: SMTP connection refused
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Inspect, retry or purge dead-lettered jobs with `efc tasks failed | retry | purge` — see [Background Tasks › Dead letters](../core-concepts/background-tasks.md#dead-letters).
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Error response reference
|
|
162
|
+
|
|
163
|
+
| Scenario | Status | Body |
|
|
164
|
+
|---|---|---|
|
|
165
|
+
| `throw new HttpError(N, msg)` | `N` | `{ "error": msg, "statusCode": N }` |
|
|
166
|
+
| Any other thrown error | `500` | `{ "error": "Internal Server Error", "statusCode": 500 }` |
|
|
167
|
+
| Method not implemented | `405` | `{ "error": "Method Not Allowed" }` + `Allow` header |
|
|
168
|
+
| Route `schema` validation failed | `400` | `{ "error": "Validation failed", "statusCode": 400, "issues": [...] }` |
|
|
169
|
+
| Model validation failed | `400` | `{ "error": "...", "statusCode": 400, "issues": [...] }` |
|
|
170
|
+
| Unique constraint violated | `409` | `{ "error": "<Model> with this <field> already exists", "statusCode": 409 }` |
|
|
171
|
+
| `requestTimeout` exceeded | `408` | `{ "error": "Request Timeout", "statusCode": 408 }` |
|
|
172
|
+
| Missing/invalid auth token | `401` | `{ "error": "Unauthorized" }` |
|
|
@@ -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,108 @@
|
|
|
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
|
+
queries: false, // model operation logging — see "Query logging" below
|
|
17
|
+
},
|
|
18
|
+
});
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`logging: false` silences framework logs entirely (request IDs are still assigned).
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Request IDs
|
|
26
|
+
|
|
27
|
+
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:
|
|
28
|
+
|
|
29
|
+
- echoed back in the `X-Request-Id` response header,
|
|
30
|
+
- available as `req.id`,
|
|
31
|
+
- bound to a child logger, `req.log`, and to `getLogger()` anywhere in the request's async chain — models, helpers, anything awaited from the handler.
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { getLogger } from 'express-file-cluster';
|
|
35
|
+
|
|
36
|
+
export async function chargeCard(orderId: string) {
|
|
37
|
+
getLogger().info({ orderId }, 'charging card'); // carries the current request's reqId
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Outside a request (startup, task handlers, timers) `getLogger()` returns the root logger. `logger` is a convenience proxy for `getLogger()`.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Request lines
|
|
46
|
+
|
|
47
|
+
With `requests: true`, every completed request logs method, URL, status and duration — at `info` for < 400, `warn` for 4xx, `error` for 5xx:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
12:00:01 INFO [w2] 3f9c2a1b GET /v1/api/users 200 method=GET url=/v1/api/users status=200 durationMs=3.4
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
In production the same record is JSON:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{"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"}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`worker` is `primary` or `w<N>` for cluster worker N, so interleaved output from many workers stays attributable.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Query logging
|
|
64
|
+
|
|
65
|
+
`logging.queries` reports model operations — every `defineModel` and `defineTable` call — with the model, operation, duration, how many database statements it issued, and the request ID:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
logging: { queries: true } // every operation, plus slow-query warnings
|
|
69
|
+
logging: { queries: { slowMs: 200 } } // only operations taking ≥ 200 ms (production)
|
|
70
|
+
logging: { queries: { all: true, slowMs: 200, nPlusOne: 5 } }
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Option | Default | |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `all` | `true` with `queries: true`, else `false` | log every operation at `info` |
|
|
76
|
+
| `slowMs` | `500` | operations at least this slow log at `warn` with `slow=true` |
|
|
77
|
+
| `nPlusOne` | `10` | warn when one request runs the same `Model.operation` this many times; `false` disables |
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
12:00:01 INFO [w2] 3f9c2a1b Post.findMany 2.1ms model=Post op=findMany durationMs=2.1 statements=1
|
|
81
|
+
12:00:01 WARN [w2] 3f9c2a1b Slow query: Order.aggregate 812.4ms model=Order op=aggregate durationMs=812.4 statements=1 slow=true
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`statements` counts the SQL statements (PostgreSQL) or MongoDB commands the call sent, including nested work such as `populate`; first-use auto-sync is not counted. An operation that throws is still logged, with `error`.
|
|
85
|
+
|
|
86
|
+
### N+1 detection
|
|
87
|
+
|
|
88
|
+
Querying inside a loop is the classic N+1 problem. When one request runs the same model operation `nPlusOne` times, EFC warns once for that request, naming the line that made the call:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
12:00:01 WARN [w2] 3f9c2a1b Possible N+1: User.findById ran 10 times in one request — load them in one query instead model=User op=findById count=10 site=GET (/app/src/api/posts.ts:14:30)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Load them together instead — `User.find({ id: { $in: ids } })`, `populate`, or `findMany({ where: { id: { in: ids } } })`. Only top-level calls count (not `populate`'s), and only inside a request.
|
|
95
|
+
|
|
96
|
+
On MongoDB, query logging takes mongoose's `debug` hook (`mongoose.set('debug', …)`) to count commands, so it replaces any `debug` setting of your own while it is on.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Errors
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Shipping logs
|
|
107
|
+
|
|
108
|
+
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`.
|