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.
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-277BSYVH.js +127 -0
  8. package/dist/chunk-277BSYVH.js.map +1 -0
  9. package/dist/chunk-6OGOVV57.js +3847 -0
  10. package/dist/chunk-6OGOVV57.js.map +1 -0
  11. package/dist/chunk-7YEX4MQV.cjs +38 -0
  12. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  13. package/dist/chunk-AZYXQU3Z.cjs +3847 -0
  14. package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
  15. package/dist/chunk-BUBXO7WU.js +170 -0
  16. package/dist/chunk-BUBXO7WU.js.map +1 -0
  17. package/dist/chunk-LJNSJFOL.js +38 -0
  18. package/dist/chunk-LJNSJFOL.js.map +1 -0
  19. package/dist/chunk-MGH4VDV3.cjs +170 -0
  20. package/dist/chunk-MGH4VDV3.cjs.map +1 -0
  21. package/dist/chunk-R34R7QPD.cjs +116 -0
  22. package/dist/chunk-R34R7QPD.cjs.map +1 -0
  23. package/dist/chunk-RS4MXCPW.js +116 -0
  24. package/dist/chunk-RS4MXCPW.js.map +1 -0
  25. package/dist/chunk-T4OHFU5T.cjs +154 -0
  26. package/dist/chunk-T4OHFU5T.cjs.map +1 -0
  27. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  28. package/dist/chunk-TRC4DUZB.js +438 -0
  29. package/dist/chunk-TRC4DUZB.js.map +1 -0
  30. package/dist/chunk-TYR2GZZE.cjs +196 -0
  31. package/dist/chunk-TYR2GZZE.cjs.map +1 -0
  32. package/dist/chunk-UBQYQPBU.js +154 -0
  33. package/dist/chunk-UBQYQPBU.js.map +1 -0
  34. package/dist/chunk-UTM4PEVG.js +196 -0
  35. package/dist/chunk-UTM4PEVG.js.map +1 -0
  36. package/dist/chunk-YL37D6KM.cjs +127 -0
  37. package/dist/chunk-YL37D6KM.cjs.map +1 -0
  38. package/dist/chunk-ZDM5JHVK.cjs +438 -0
  39. package/dist/chunk-ZDM5JHVK.cjs.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 +326 -0
  55. package/dist/docs/api-reference/table.md +458 -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 +108 -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 +309 -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 +264 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +699 -7
  94. package/dist/index.d.ts +699 -7
  95. package/dist/index.js +258 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
  98. package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
  99. package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
  100. package/dist/pgboss-backend-TCHI7CHM.cjs.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-B6lVw4bj.d.cts +588 -0
  105. package/dist/types-B6lVw4bj.d.ts +588 -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,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`.