express-file-cluster 0.3.15 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-3VWD2ZED.js +60 -0
- package/dist/chunk-3VWD2ZED.js.map +1 -0
- package/dist/chunk-47K2532L.cjs +196 -0
- package/dist/chunk-47K2532L.cjs.map +1 -0
- package/dist/chunk-5PDAWMGF.js +438 -0
- package/dist/chunk-5PDAWMGF.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-ALBDM5R3.cjs +60 -0
- package/dist/chunk-ALBDM5R3.cjs.map +1 -0
- package/dist/chunk-JJJJTACK.js +196 -0
- package/dist/chunk-JJJJTACK.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-M7MUPWCE.js +116 -0
- package/dist/chunk-M7MUPWCE.js.map +1 -0
- package/dist/chunk-PMF4GMHD.js +154 -0
- package/dist/chunk-PMF4GMHD.js.map +1 -0
- package/dist/chunk-QTRGJ2EN.cjs +2635 -0
- package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
- package/dist/chunk-RSBW2B3D.cjs +126 -0
- package/dist/chunk-RSBW2B3D.cjs.map +1 -0
- package/dist/chunk-RTFJ32T5.js +2635 -0
- package/dist/chunk-RTFJ32T5.js.map +1 -0
- package/dist/chunk-SFVEQ2T5.cjs +438 -0
- package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
- package/dist/chunk-SZT36SGB.cjs +154 -0
- package/dist/chunk-SZT36SGB.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-ULQXD4YZ.cjs +116 -0
- package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
- package/dist/chunk-VYHJX54R.js +126 -0
- package/dist/chunk-VYHJX54R.js.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +323 -0
- package/dist/docs/api-reference/table.md +250 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +70 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +308 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +289 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +472 -7
- package/dist/index.d.ts +472 -7
- package/dist/index.js +283 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
- package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
- package/dist/pgboss-backend-UUJOVEYK.js +14 -0
- package/dist/pgboss-backend-UUJOVEYK.js.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-DJCPAsM4.d.cts +541 -0
- package/dist/types-DJCPAsM4.d.ts +541 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- package/dist/types-BusbSenn.d.ts +0 -162
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# EFC — Pre-Flight Lifecycle (Exact)
|
|
2
|
+
|
|
3
|
+
Source: `packages/core/src/index.ts` — `ignite()` function, worker branch.
|
|
4
|
+
|
|
5
|
+
This is the exact order of operations inside every worker process (or the single process when `cluster: false`).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Step-by-step sequence
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
ignite() called
|
|
13
|
+
│
|
|
14
|
+
├─ cluster.isPrimary && cluster enabled?
|
|
15
|
+
│ YES → runMaster() → fork workers → return undefined (master exits here)
|
|
16
|
+
│ NO → continue as worker
|
|
17
|
+
│
|
|
18
|
+
▼
|
|
19
|
+
0. configureLogger(config.logging) (runs before the primary/worker split)
|
|
20
|
+
|
|
21
|
+
1. Create Express app
|
|
22
|
+
- Wrap every request in an AsyncLocalStorage context
|
|
23
|
+
- requestLogger(): X-Request-Id → req.id / req.log / getLogger(); one log line per response
|
|
24
|
+
- requestTimeout → 408 middleware (if set)
|
|
25
|
+
- Apply CORS middleware (from config.cors — ignite() never reads CORS_ORIGINS itself)
|
|
26
|
+
- Apply express.json()
|
|
27
|
+
- Apply express.urlencoded({ extended: true })
|
|
28
|
+
- Apply cookieParser()
|
|
29
|
+
- Apply globalMiddlewares[] (from config)
|
|
30
|
+
|
|
31
|
+
2. Connect Database [database = config.database ?? scheme of databaseUrl]
|
|
32
|
+
- setDbEngine(database) → decides what defineModel compiles to (mongoose / Drizzle)
|
|
33
|
+
- mongodb: connectMongo(url) → setDbClient(mongoose.connection)
|
|
34
|
+
- postgresql: connectPostgres(url) → pg Pool (+ Drizzle) → setDbClient(pool)
|
|
35
|
+
- db proxy is now live. Models compile lazily on first use.
|
|
36
|
+
|
|
37
|
+
3. Configure Auth [if jwtSecret is set]
|
|
38
|
+
- configureAuth({ secret, strategy, expiresIn, cookieDomain? })
|
|
39
|
+
- issueToken / requireAuth / signToken are now usable
|
|
40
|
+
|
|
41
|
+
4. Scan + Register Tasks [src/tasks by convention — there is no tasksDir option]
|
|
42
|
+
- scanTasks(tasksDir)
|
|
43
|
+
- Walks tasksDir, imports each file, reads default export
|
|
44
|
+
- Calls registerTask(basename, definition) for each valid TaskDefinition
|
|
45
|
+
|
|
46
|
+
5. Start Task Queue Backend [if config.tasks is set]
|
|
47
|
+
- backend === 'bullmq' → initBullMQ({ redisUrl, concurrency, enqueueTimeout, queue })
|
|
48
|
+
- Queue(queue) with enableOfflineQueue: false; Worker(queue, processor)
|
|
49
|
+
- cron schedulers reconciled in the BACKGROUND (Redis outage can't block boot)
|
|
50
|
+
- backend === 'pg-boss' → initPgBoss({ connectionString ?? databaseUrl, ... })
|
|
51
|
+
- one pg-boss queue per task: `<queue>.<Task>`; work() + schedule() per task
|
|
52
|
+
- setEnqueueImpl(...) → enqueue() is now usable
|
|
53
|
+
|
|
54
|
+
6. Scan Routes
|
|
55
|
+
- scanDir(apiDir) → RouteEntry[]
|
|
56
|
+
- File → URL transformation (see routing-rules.md)
|
|
57
|
+
- Per-segment specificity sort
|
|
58
|
+
|
|
59
|
+
7. Mount Routes
|
|
60
|
+
- mountRoutes(app, routes)
|
|
61
|
+
- Dynamic import of each route module
|
|
62
|
+
- Register handlers on Express
|
|
63
|
+
|
|
64
|
+
8. Register error handler [onError if provided, else built-in]
|
|
65
|
+
|
|
66
|
+
9. app.listen(port)
|
|
67
|
+
- Resolves Promise<http.Server> on 'listening' event
|
|
68
|
+
- Logs: Worker <id> listening on :<port>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Key invariants
|
|
74
|
+
|
|
75
|
+
- **Steps 2–5 run BEFORE routes are mounted.** By the time a handler executes, `db` is live and `enqueue()` works.
|
|
76
|
+
- **Each worker runs all 8 steps independently.** Workers never share DB connections or task registry state.
|
|
77
|
+
- **`cluster: false` is identical** — the same 8 steps run in the single process, skipping the fork branch.
|
|
78
|
+
- **`cluster: true` + `cluster.isPrimary`** — the master process does NOTHING after `runMaster()`. It forks workers and watches `exit` events. It does not run Pre-Flight.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## `runMaster()` (cluster/index.ts)
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
runMaster({ workers, onWorkerReady, onWorkerCrash })
|
|
86
|
+
→ cluster.fork() × workers
|
|
87
|
+
→ cluster.on('online', worker => onWorkerReady?.(worker.id))
|
|
88
|
+
→ cluster.on('exit', (worker, code, signal) => {
|
|
89
|
+
if (!isShuttingDown) {
|
|
90
|
+
onWorkerCrash?.(worker.id, code ?? -1)
|
|
91
|
+
cluster.fork() // immediate respawn, no delay
|
|
92
|
+
}
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The master never calls `app.listen()`. If `ignite()` is called in the primary process, it returns `undefined` — not a server.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## `gracefulShutdown()` — shutdown path
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
SIGTERM or SIGINT received
|
|
104
|
+
│
|
|
105
|
+
├─ already shutting down? → ignore (repeat signals must not kill a draining worker)
|
|
106
|
+
│
|
|
107
|
+
├─ server is defined (worker or single-process)
|
|
108
|
+
│ → server.closeIdleConnections()
|
|
109
|
+
│ → server.close(() => closeBullMQ() + closePgBoss() → process.exit(0))
|
|
110
|
+
│ → setTimeout(force process.exit(1), timeoutMs) // default 10s
|
|
111
|
+
│
|
|
112
|
+
└─ server is undefined (primary)
|
|
113
|
+
→ shutdownMaster(): isShuttingDown = true, SIGTERM relayed to every worker
|
|
114
|
+
(docker stop / k8s only signal PID 1)
|
|
115
|
+
→ primary exits when all workers have; force-exit after timeoutMs + 2s
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Port resolution (exact precedence)
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
1. config.port (if provided and not NaN)
|
|
124
|
+
2. 3000 (hardcoded default)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`ignite()` never reads `process.env.PORT` itself — pass it explicitly (typically via `efc.config.ts`: `port: process.env.PORT ? Number(process.env.PORT) : undefined`).
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Cluster enable/disable logic (exact)
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
const clusterEnabled = config.cluster ?? (process.env['NODE_ENV'] === 'production');
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- `config.cluster` is `undefined` AND `NODE_ENV !== 'production'` → **clustering OFF** (dev default)
|
|
138
|
+
- `config.cluster` is `undefined` AND `NODE_ENV === 'production'` → **clustering ON**
|
|
139
|
+
- `config.cluster: true` → **ON** regardless of NODE_ENV
|
|
140
|
+
- `config.cluster: false` → **OFF** regardless of NODE_ENV
|
|
141
|
+
|
|
142
|
+
`efc start dev` sets `NODE_ENV=development` → clustering is automatically off in dev.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# EFC — Routing Rules (Exact)
|
|
2
|
+
|
|
3
|
+
Source: `packages/core/src/router/scan.ts` + `packages/core/src/router/mount.ts`
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## File → URL transformation (exact algorithm)
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
scan.ts: filePathToUrlPath(relativePath)
|
|
11
|
+
|
|
12
|
+
1. Strip extension (.ts | .js | .mts | .mjs | .cts | .cjs)
|
|
13
|
+
2. Strip /index (trailing /index becomes '')
|
|
14
|
+
3. Per segment:
|
|
15
|
+
[[...name]] → :name*? optional catch-all (≥0 segments)
|
|
16
|
+
[...name] → :name* catch-all (≥1 segment)
|
|
17
|
+
[[name]] → :name? optional
|
|
18
|
+
[name] → :name dynamic (also inside a segment: post-[id] → post-:id)
|
|
19
|
+
4. If result is '' → '/'
|
|
20
|
+
5. Prepend '/'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
A catch-all must be the LAST segment — `[...slug]/edit.ts` throws at startup. Catch-all
|
|
24
|
+
routes mount on a compiled RegExp (`RouteEntry.pattern`); a mapper restores named params,
|
|
25
|
+
and catch-all values arrive as `string[]` (URI-decoded; `[]` when an optional one is empty).
|
|
26
|
+
|
|
27
|
+
### Examples derived from the exact regex
|
|
28
|
+
|
|
29
|
+
| File (relative to apiDir) | URL |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `/health.ts` | `/health` |
|
|
32
|
+
| `/users/index.ts` | `/users` |
|
|
33
|
+
| `/users/[id].ts` | `/users/:id` |
|
|
34
|
+
| `/posts/[slug]/comments.ts` | `/posts/:slug/comments` |
|
|
35
|
+
| `/index.ts` | `/` |
|
|
36
|
+
| `/auth/login.ts` | `/auth/login` |
|
|
37
|
+
| `/a/[b]/[c].ts` | `/a/:b/:c` |
|
|
38
|
+
| `/users/[[id]].ts` | `/users/:id?` (matches `/users` and `/users/7`) |
|
|
39
|
+
| `/docs/[...slug].ts` | `/docs/:slug*` (`/docs/a/b` → `slug: ['a','b']`; not `/docs`) |
|
|
40
|
+
| `/docs/[[...slug]].ts` | `/docs/:slug*?` (also `/docs` → `slug: []`) |
|
|
41
|
+
|
|
42
|
+
**Edge case:** `/users/index.ts` → strips extension → `/users/index` → strips `/index` → `/users`. NOT `/users/`. There is no trailing slash.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Sorting: per-segment specificity
|
|
47
|
+
|
|
48
|
+
Each segment gets a rank — static 0, `[id]` 1, `[[id]]` 2, `[...slug]` 3, `[[...slug]]` 4 — and
|
|
49
|
+
routes are compared rank-by-rank from the first segment; ties sort alphabetically by URL.
|
|
50
|
+
So `/users/me` beats `/users/:id`, which beats `/users/:id?`, then `/users/:rest*`.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Method dispatching (mount.ts)
|
|
55
|
+
|
|
56
|
+
Recognised method names (exact — case-sensitive uppercase):
|
|
57
|
+
```
|
|
58
|
+
GET POST PUT PATCH DELETE HEAD OPTIONS
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
For each route module:
|
|
62
|
+
1. Import the module dynamically.
|
|
63
|
+
2. Read `mod.middlewares` (must be an array, else ignored), `mod.schema`, `mod.meta`.
|
|
64
|
+
3. For each of the 7 method names, check `typeof mod[METHOD] === 'function'`.
|
|
65
|
+
4. Register: `app[method](pattern ?? urlPath, ...paramMapper?, ...middlewares, validate?, asyncWrap(handler))`.
|
|
66
|
+
`validate` exists when `schema` has an entry for that method (method key wins over file-wide
|
|
67
|
+
`{ params, query, body }`). It runs AFTER middlewares; failure → 400 with `issues`.
|
|
68
|
+
5. If **any** methods are implemented and **any** are unimplemented: register `app.all(urlPath, ...)` that returns 405 with `Allow: <implemented>` for the missing methods.
|
|
69
|
+
|
|
70
|
+
**asyncWrap**: `Promise.resolve(handler(req, res, next)).catch(next)` — all route errors auto-forwarded.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## `middlewares` export rules
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
export const middlewares = [mw1, mw2]; // ✅ valid — applied to all methods
|
|
78
|
+
export const middlewares = mw1; // ❌ ignored — must be an array
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The check in mount.ts: `Array.isArray(mod['middlewares'])`.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Route file extensions accepted
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
.ts .js .mts .mjs .cts .cjs
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Regex: `/\.(ts|js|mts|mjs|cts|cjs)$/`
|
|
92
|
+
|
|
93
|
+
Files that do NOT match this pattern are silently ignored by `scanDir`.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## What scanDir does NOT do
|
|
98
|
+
|
|
99
|
+
- Does NOT follow symlinks (uses `fs.readdirSync` with `withFileTypes`).
|
|
100
|
+
- Does NOT skip files named `index.ts` specially during scan — they are treated as routes whose URL resolves to the parent directory path.
|
|
101
|
+
- Does NOT support nested `index` files as catch-alls — only the exact directory name maps to the URL.
|
|
102
|
+
- Does NOT allow a catch-all anywhere but the last segment.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 405 response format
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{ "error": "Method Not Allowed" }
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Header: `Allow: GET, POST` (only the implemented methods).
|
|
113
|
+
|
|
114
|
+
**Only sent when at least one method IS implemented.** A file that exports no HTTP methods gets no 405 handler — Express would return 404.
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# EFC — Task System Internals (Exact)
|
|
2
|
+
|
|
3
|
+
Source: `packages/core/src/tasks/`
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Task naming rule
|
|
8
|
+
|
|
9
|
+
**The task name is the file's basename without extension.** This is the only rule. No path, no directory, no subdirectory.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
tasksDir/SendEmail.ts → name: "SendEmail"
|
|
13
|
+
tasksDir/ResizeImage.ts → name: "ResizeImage"
|
|
14
|
+
tasksDir/jobs/DoWork.ts → ERROR — scanTasks only reads top-level files
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`scanTasks` uses `fs.readdirSync(tasksDir)` (non-recursive). **Sub-directories in `tasksDir` are not scanned.**
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## `defineTask` — exact overloads
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
// Overload 1: handler only
|
|
25
|
+
defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
26
|
+
|
|
27
|
+
// Overload 2: options + handler
|
|
28
|
+
defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The returned `TaskDefinition` has `name: ''` — the name is set later by `registerTask()` when `scanTasks` processes the file.
|
|
32
|
+
|
|
33
|
+
**The `default` export must be a `TaskDefinition`**, not a plain function. `export default async (payload) => {}` will be rejected by `scanTasks` — it requires `def.handler` to be a function.
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// ✅ correct
|
|
37
|
+
export default defineTask<Payload>(async (payload) => { ... });
|
|
38
|
+
|
|
39
|
+
// ❌ wrong — scanTasks will warn and skip this file
|
|
40
|
+
export default async function(payload: Payload) { ... }
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Task registration flow
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
scanTasks(tasksDir)
|
|
49
|
+
→ fs.readdirSync(tasksDir).filter(f => /\.(ts|js|mts|mjs)$/.test(f))
|
|
50
|
+
→ for each file:
|
|
51
|
+
mod = await import(filePath)
|
|
52
|
+
def = mod.default as TaskDefinition
|
|
53
|
+
if (!def || typeof def.handler !== 'function') → warn + skip
|
|
54
|
+
registerTask(basename_without_ext, { ...def, filePath })
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`registerTask` stores to `taskRegistry: Map<string, TaskDefinition>`.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## `enqueue(name, payload)` — what it checks
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
async function enqueue<T>(name: string, payload: T): Promise<void> {
|
|
65
|
+
if (!_impl) throw Error('[EFC] Task queue not initialised...')
|
|
66
|
+
return _impl(name, payload)
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`_impl` is set by `setEnqueueImpl()` called inside `initBullMQ()` or `initPgBoss()`. If `tasks` is not configured in `ignite()`, `_impl` is null and `enqueue()` always throws.
|
|
71
|
+
|
|
72
|
+
The BullMQ `_impl` also validates the name:
|
|
73
|
+
```ts
|
|
74
|
+
const def = taskRegistry.get(name)
|
|
75
|
+
if (!def) throw Error(`[EFC] Cannot enqueue unknown task: "${name}"...`)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
So `enqueue` throws for both "no backend" and "unknown task name".
|
|
79
|
+
|
|
80
|
+
It also rejects when Redis is unreachable: the Queue's ioredis connection has `enableOfflineQueue: false`, and `waitUntilReady()` + `queue.add()` is raced against `tasks.enqueueTimeout` (default 5000 ms). Message: `[EFC] Cannot enqueue task "X": Redis at host:port did not respond within Nms`. A rejected job is never queued later.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## BullMQ queue name
|
|
85
|
+
|
|
86
|
+
The queue is named `'efc'` (hardcoded). All tasks share a single queue. The job `name` field is the task name (file basename).
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## `thread: true` execution path
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
enqueue('ResizeImage', payload)
|
|
94
|
+
→ BullMQ picks up the job
|
|
95
|
+
→ processor: def = taskRegistry.get(job.name)
|
|
96
|
+
→ def.options.thread && def.filePath
|
|
97
|
+
YES → runInThread(def.filePath, job.data)
|
|
98
|
+
NO → def.handler(job.data)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`runInThread` in `thread-runner.ts`:
|
|
102
|
+
- Spawns `new Worker(thread-runner.js, { workerData: { handlerPath, payload } })`
|
|
103
|
+
- Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`
|
|
104
|
+
- Resolves on `{ ok: true }`, rejects on `{ ok: false, error }`
|
|
105
|
+
|
|
106
|
+
`thread: true` requires `def.filePath` to be set. This is only guaranteed when the task was registered via `scanTasks` (which stores the file path). If you call `registerTask` manually without `filePath`, `thread: true` will silently fall through to the event loop (the `&&` short-circuits).
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Retry/backoff wiring (BullMQ)
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
queue.add(name, payload, {
|
|
114
|
+
attempts: (def.options.retries ?? 3) + 1, // retries = re-runs; attempts counts the first run
|
|
115
|
+
backoff: {
|
|
116
|
+
type: def.options.backoff ?? 'exponential',
|
|
117
|
+
delay: 1000,
|
|
118
|
+
},
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`backoff.delay: 1000` is hardcoded (1 second base delay). Exponential: 1s, 2s, 4s, ...
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Redis URL parsing
|
|
127
|
+
|
|
128
|
+
Built-in `parseRedisUrl` in `bullmq-backend.ts`:
|
|
129
|
+
```ts
|
|
130
|
+
// Parses: redis[s]://[user:password@]host[:port][/db]
|
|
131
|
+
{ host, port, username?, password?, db?, tls? } // tls: {} for rediss://
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Defaults: `host: 'localhost'`, `port: 6379`. User/password are URI-decoded.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## What `tasks` in `ignite()` does NOT do
|
|
139
|
+
|
|
140
|
+
- Does NOT start a dedicated task-runner process — tasks run inside each worker process.
|
|
141
|
+
- Does NOT auto-retry on `enqueue` failure — `enqueue` itself doesn't retry; the backend handles job-level retries.
|
|
142
|
+
- On `gracefulShutdown()`, the HTTP server closes first, then `closeBullMQ()` / `closePgBoss()` drain in-flight jobs before exit.
|
|
143
|
+
- Does NOT provide a dead-letter web UI — use `efc tasks failed | retry | purge` (or Bull Board).
|
|
144
|
+
- Does NOT support sub-directories in `tasksDir`.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Cron schedules
|
|
149
|
+
|
|
150
|
+
`defineTask({ schedule: '<cron>', timezone?: '<IANA>' }, handler)`. Reconciled on every boot:
|
|
151
|
+
|
|
152
|
+
- **BullMQ**: `queue.upsertJobScheduler('efc-cron:<Task>', { pattern, tz }, { name, data: {}, opts })` — idempotent,
|
|
153
|
+
so every cluster worker can run it. Schedulers with the `efc-cron:` prefix whose task lost its schedule are
|
|
154
|
+
removed. Sync is not awaited (`whenSchedulesSynced()` exposes it for tests). 6-field patterns (seconds) work.
|
|
155
|
+
- **pg-boss**: `boss.schedule('<queue>.<Task>', cron, {}, { tz, retry… })`; stale `<queue>.*` schedules are
|
|
156
|
+
`unschedule`d. One-minute resolution.
|
|
157
|
+
- Scheduled runs always receive `{}` as payload.
|
|
158
|
+
|
|
159
|
+
## pg-boss backend (`tasks/pgboss-backend.ts`)
|
|
160
|
+
|
|
161
|
+
- `new PgBoss({ connectionString: tasks.connectionString ?? databaseUrl, schema? })`, `start()`.
|
|
162
|
+
- One pg-boss queue per task, named `<tasks.queue>.<TaskName>` (default prefix `efc`); `createQueue` is idempotent.
|
|
163
|
+
- `retryLimit = retries` (pg-boss counts re-runs, like EFC), `retryDelay: 1`, `retryBackoff` for exponential.
|
|
164
|
+
- Non-object payloads are boxed as `{ __efcValue: payload }` and unboxed for the handler.
|
|
165
|
+
- `enqueue` = `boss.send(...)` raced against `enqueueTimeout`.
|
|
166
|
+
|
|
167
|
+
## Dead letters (`tasks/admin.ts`, CLI `efc tasks failed|retry|purge`)
|
|
168
|
+
|
|
169
|
+
`TaskAdmin` = `counts()`, `listFailed({ limit, name })`, `retry(ids)`, `purge(ids)` (empty ids = all).
|
|
170
|
+
BullMQ: `queue.getFailed`, `job.retry('failed')`, `job.remove()`. pg-boss: reads `pgboss.job WHERE state='failed'`,
|
|
171
|
+
then `boss.retry` / `boss.deleteJob`. A retried job gets exactly one more attempt on both backends.
|
|
172
|
+
CLI picks BullMQ when `REDIS_URL` is set, else pg-boss for a `postgres` `DATABASE_URL`; `--backend/--queue` override.
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
# EFC — What Does NOT Exist
|
|
2
|
+
|
|
3
|
+
This module is the anti-hallucination guard. Before suggesting, generating, or writing EFC code, check this list. If something appears here, **it does not exist in the codebase** — do not generate it, reference it, or imply it works.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Import paths that do NOT exist
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// ❌ DOES NOT EXIST
|
|
11
|
+
import { ... } from 'express-file-cluster/db'
|
|
12
|
+
import { ... } from 'express-file-cluster/router'
|
|
13
|
+
import { ... } from 'express-file-cluster/cluster'
|
|
14
|
+
import { ... } from 'express-file-cluster/middleware'
|
|
15
|
+
import { ... } from 'express-file-cluster/errors'
|
|
16
|
+
import { ... } from 'express-file-cluster/config'
|
|
17
|
+
import { ... } from 'express-file-cluster/models'
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Only three sub-paths exist: (no suffix), `/auth`, `/tasks`.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Functions that do NOT exist
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// ❌ NOT exported from any EFC path
|
|
28
|
+
createApp()
|
|
29
|
+
createServer()
|
|
30
|
+
useMiddleware()
|
|
31
|
+
addRoute()
|
|
32
|
+
registerRoute()
|
|
33
|
+
mountRoute()
|
|
34
|
+
defineRoute()
|
|
35
|
+
defineMiddleware()
|
|
36
|
+
defineModel() // ← WAIT — this DOES exist, from main path
|
|
37
|
+
createModel() // ← does NOT exist (it's defineModel, not createModel)
|
|
38
|
+
defineTable() // ← EXISTS (PostgreSQL-only, Prisma-style) — see api-surface.md
|
|
39
|
+
defineCollection() // ← NOT YET — planned (MongoDB-native API, prisma-parity-plan M5)
|
|
40
|
+
Model.findMany() / findUnique() / groupBy() // ← only on defineTable, NOT on defineModel
|
|
41
|
+
Table.find() / findById() / $gt / $inc // ← defineModel vocabulary, NOT on defineTable
|
|
42
|
+
Table.findMany({ include }) // ← relations/include NOT YET (M3)
|
|
43
|
+
defineModel(..., { type: 'integer' | 'bigint' | 'decimal' | 'uuid' | 'json' }) // ← defineTable-only types
|
|
44
|
+
Model.updateOne(f, u, { upsert: true }) // ← no options arg; use Model.upsert(filter, create, update)
|
|
45
|
+
getModel() // ← does NOT exist as a public export
|
|
46
|
+
useDatabase()
|
|
47
|
+
connectDatabase()
|
|
48
|
+
createTask() // ← does NOT exist (it's defineTask)
|
|
49
|
+
addTask()
|
|
50
|
+
scheduleTask() // ← does NOT exist — use defineTask({ schedule: '<cron>' }, handler)
|
|
51
|
+
validate() / useSchema() // ← does NOT exist — use `export const schema` in the route file
|
|
52
|
+
createLogger() // ← does NOT exist — use logger / getLogger() from the main path
|
|
53
|
+
withTransaction() // ← does NOT exist — it's transaction(fn) from the main path
|
|
54
|
+
withAuth() // ← does NOT exist
|
|
55
|
+
protect() // ← does NOT exist
|
|
56
|
+
authenticate() // ← does NOT exist (it's requireAuth)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Configuration patterns that do NOT exist
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
// ❌ No automatic efc.config.ts loading — ignite() does NOT read efc.config.ts
|
|
65
|
+
// The config file is informational only. You must import it yourself and pass it:
|
|
66
|
+
import config from './efc.config';
|
|
67
|
+
ignite(config); // you wire this yourself
|
|
68
|
+
|
|
69
|
+
// ❌ No global middleware file (middlewares.ts or similar)
|
|
70
|
+
// Middleware is only wired via ignite({ globalMiddlewares }) or route exports
|
|
71
|
+
|
|
72
|
+
// ❌ No src/middleware/ auto-scanning
|
|
73
|
+
// EFC does NOT automatically scan a middlewares directory
|
|
74
|
+
|
|
75
|
+
// ❌ No plugins system yet (Phase 3)
|
|
76
|
+
ignite({ plugins: [...] }) // does NOT exist
|
|
77
|
+
|
|
78
|
+
// ❌ No apiDir / tasksDir / migrationsDir options — all are conventions:
|
|
79
|
+
// src/api, src/tasks (non-recursive), src/migrations, src/seeds
|
|
80
|
+
|
|
81
|
+
// ✅ Request context DOES exist now (added 2026-07-19) — every request run through
|
|
82
|
+
// ignite() is wrapped in an AsyncLocalStorage context (packages/core/src/context.ts),
|
|
83
|
+
// and requireAuth populates it with the verified JWT payload:
|
|
84
|
+
import { getCurrentUser } from 'express-file-cluster/auth';
|
|
85
|
+
getCurrentUser() // Record<string, unknown> | undefined — the auth payload, or
|
|
86
|
+
// undefined outside a request / on a route without requireAuth
|
|
87
|
+
|
|
88
|
+
// ❌ There is no general-purpose ctx object beyond the user payload — no
|
|
89
|
+
// import { ctx } from 'express-file-cluster', and no way to stash arbitrary
|
|
90
|
+
// per-request values yourself. getCurrentUser() is the only thing exposed.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Route file features that do NOT exist
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
// ✅ Special exports: HTTP methods, `middlewares`, `schema` (validation), `meta` (dashboard docs).
|
|
99
|
+
// ❌ Everything else is ignored:
|
|
100
|
+
export const config = { ... } // ignored
|
|
101
|
+
export const description = '...' // ignored
|
|
102
|
+
|
|
103
|
+
// ❌ Default export is NOT used by the router
|
|
104
|
+
export default async function(req, res) { ... } // NOT called as a route handler
|
|
105
|
+
|
|
106
|
+
// ✅ Catch-all / optional segments DO exist: [...slug] (≥1 segment, req.params.slug is string[]),
|
|
107
|
+
// [[...slug]] (≥0), [[id]] (optional). A catch-all must be the LAST segment:
|
|
108
|
+
// src/api/[...slug]/edit.ts → rejected at startup
|
|
109
|
+
|
|
110
|
+
// ❌ schema validators are not auto-detected from TypeScript types — export real validators
|
|
111
|
+
// (zod/valibot/arktype or anything with safeParse). EFC does not depend on zod.
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Task features that do NOT exist
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
// ❌ Task sub-directories not scanned
|
|
120
|
+
// src/tasks/email/SendEmail.ts → NOT registered (only top-level files)
|
|
121
|
+
|
|
122
|
+
// ✅ Cron DOES exist: defineTask({ schedule: '0 * * * *', timezone: 'UTC' }, handler) — payload is {}
|
|
123
|
+
// ✅ pg-boss DOES exist: ignite({ tasks: { backend: 'pg-boss' } }) — uses databaseUrl
|
|
124
|
+
// ❌ No per-run payload for scheduled runs (always {}) and no "every N ms" interval option
|
|
125
|
+
// ❌ No built-in parent/child job tracking or job progress API
|
|
126
|
+
// ❌ No dead-letter web UI — use `efc tasks failed | retry | purge`
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## CLI commands that do NOT exist
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
efc lint # NOT IMPLEMENTED
|
|
135
|
+
efc deploy # NOT IMPLEMENTED
|
|
136
|
+
efc db generate # NOT IMPLEMENTED — no schema-diff migration generator; write migrations
|
|
137
|
+
# by hand (efc generate migration <name>) and call Model.sync()
|
|
138
|
+
efc db reset / fresh # NOT IMPLEMENTED
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Implemented commands: `start dev|prod`, `build prod`, `run tests`, `generate route|task|middleware|migration|seed`, `db migrate|rollback|status|seed|studio`, `routes`, `tasks` (+ `failed|retry|purge`), `doctor`, `--version`.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Database features that do NOT exist
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
// ✅ PostgreSQL DOES exist (Drizzle) — same defineModel API. ids are UUIDs there.
|
|
149
|
+
// ✅ transaction(fn) DOES exist (main path). MongoDB needs a replica set.
|
|
150
|
+
// ✅ Tables are created and reconciled automatically on first use (autoSync, default on):
|
|
151
|
+
// add column, change type (with cast), drop stale NOT NULL, rebuild enum CHECK,
|
|
152
|
+
// create/drop EFC-named indexes. `efc db sync --dry-run` prints the SQL.
|
|
153
|
+
// ❌ Sync never DROPS or RENAMES columns and never deletes rows — renames, splits and
|
|
154
|
+
// backfills need a hand-written migration (db.query()).
|
|
155
|
+
// ❌ No `efc db generate` that writes migration files from model diffs.
|
|
156
|
+
// ❌ No joins in the model API — populate does a second query; for SQL joins use
|
|
157
|
+
// Drizzle via Model.raw() or db.query().
|
|
158
|
+
// ❌ aggregate() is MongoDB-only (rejects on PostgreSQL).
|
|
159
|
+
// ❌ TTL indexes (expireAfterSeconds) are MongoDB-only.
|
|
160
|
+
// ❌ Filter operators beyond $eq $ne $gt $gte $lt $lte $in $nin $exists $regex $and $or
|
|
161
|
+
// are rejected on PostgreSQL (they pass through to mongoose on MongoDB).
|
|
162
|
+
// ❌ Update operators beyond $set $unset $inc $push $pull likewise.
|
|
163
|
+
|
|
164
|
+
// db is the native client: mongoose Connection on MongoDB, pg Pool on PostgreSQL.
|
|
165
|
+
// db.query() exists only on PostgreSQL; db.model() only on MongoDB.
|
|
166
|
+
|
|
167
|
+
// ❌ '$increment' is NOT a `default` operator code, and never will be —
|
|
168
|
+
// mongoose resolves `default` synchronously, but an auto-increment needs an
|
|
169
|
+
// async read-modify-write against a counters collection. That functionality
|
|
170
|
+
// DOES exist (added 2026-07-19), just under a different field property:
|
|
171
|
+
{ orderNumber: { type: 'number', sequence: true, required: true } }
|
|
172
|
+
// FieldDefinition.default supports:
|
|
173
|
+
// '$now' | '$uuid' | '$objectId' | '$timestamp' | '$shortId'
|
|
174
|
+
// | '$currentUser' | `$currentUser.${string}`
|
|
175
|
+
// (see db/schema.ts STATIC_DEFAULT_OPERATORS / resolveDefault)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## Auth features that do NOT exist
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
// ✅ requireAuth('admin') DOES exist — it's an overload, not a separate function.
|
|
184
|
+
// Bare `requireAuth` just verifies the JWT. Called with role names it returns a
|
|
185
|
+
// middleware that also checks payload.role. Both forms use the same export.
|
|
186
|
+
|
|
187
|
+
// ❌ No refresh token mechanism in the framework itself
|
|
188
|
+
// (the create-efc-app scaffolder generates an app-level /auth/refresh route
|
|
189
|
+
// that stores a rotating refresh token in the DB — that's app code, not core)
|
|
190
|
+
refreshToken() // does NOT exist as a core export
|
|
191
|
+
|
|
192
|
+
// ✅ Token revocation DOES exist — but only with ignite({ cache }):
|
|
193
|
+
// await revokeSession(req, res) — this token
|
|
194
|
+
// await revokeAllSessions(userId) — every token issued to the user before now
|
|
195
|
+
// revokeToken(res) still ONLY clears the cookie.
|
|
196
|
+
// ❌ No refresh-token rotation or session listing ("show my active devices") in core
|
|
197
|
+
|
|
198
|
+
// ❌ No per-route strategy override
|
|
199
|
+
// authStrategy is global — set once in ignite()
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Environment variables that EFC does NOT read automatically
|
|
205
|
+
|
|
206
|
+
`ignite()` reads app config only from the `EFCConfig` object it's given — it does not grab any of the following from `process.env` itself. Read them yourself (typically in `efc.config.ts`) and pass them in:
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
PORT — NOT read by ignite(); pass config.port explicitly
|
|
210
|
+
(or: port: process.env.PORT ? Number(process.env.PORT) : undefined)
|
|
211
|
+
DATABASE_URL — NOT read by ignite(); pass config.databaseUrl explicitly
|
|
212
|
+
(or: databaseUrl: process.env.DATABASE_URL)
|
|
213
|
+
JWT_SECRET — NOT read by ignite(); pass config.jwtSecret explicitly
|
|
214
|
+
(or: jwtSecret: process.env.JWT_SECRET)
|
|
215
|
+
JWT_EXPIRES_IN — NOT read by ignite(); pass config.jwtExpiresIn explicitly
|
|
216
|
+
(or: jwtExpiresIn: process.env.JWT_EXPIRES_IN)
|
|
217
|
+
COOKIE_DOMAIN — NOT read by ignite(); pass config.cookieDomain explicitly
|
|
218
|
+
(or: cookieDomain: process.env.COOKIE_DOMAIN)
|
|
219
|
+
CORS_ORIGINS — NOT read by ignite(); pass config.cors.origin explicitly
|
|
220
|
+
(or: cors: { origin: process.env.CORS_ORIGINS?.split(',') } )
|
|
221
|
+
REDIS_URL — NOT read by ignite(); pass tasks.redisUrl explicitly
|
|
222
|
+
(or read it yourself: tasks: { redisUrl: process.env.REDIS_URL })
|
|
223
|
+
|
|
224
|
+
(The standalone CLI commands — efc db, efc tasks failed, efc doctor — DO read
|
|
225
|
+
DATABASE_URL / REDIS_URL from the environment or .env themselves.)
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
`NODE_ENV` is the one env var the framework *does* still read directly (cluster-in-production default, dev-only dashboard toggle, auth cookie `Secure` flag) — see `pre-flight.md`.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Common wrong patterns
|
|
233
|
+
|
|
234
|
+
```ts
|
|
235
|
+
// ❌ Calling enqueue without configuring tasks in ignite()
|
|
236
|
+
ignite({ port: 3000 }) // no tasks config
|
|
237
|
+
await enqueue('SendEmail', payload) // throws: Task queue not initialised
|
|
238
|
+
|
|
239
|
+
// ❌ Calling requireAuth before ignite() / configureAuth()
|
|
240
|
+
// In tests that mount handlers without calling ignite(), requireAuth will throw
|
|
241
|
+
|
|
242
|
+
// ❌ Accessing db before Pre-Flight completes
|
|
243
|
+
// In module-level or import-time code:
|
|
244
|
+
const conn = db.model('User') // throws: db not ready
|
|
245
|
+
|
|
246
|
+
// ❌ Passing apiDir at all — it is not an option; src/api is found by convention
|
|
247
|
+
// (dev: src/api via tsx; prod: dist/src/api, emitted by `efc build prod`)
|
|
248
|
+
|
|
249
|
+
// ❌ With autoSync: false, using a model before `efc db sync` / a migration created its table
|
|
250
|
+
// → "[EFC] <Model>: table "<t>" does not exist — autoSync is off…"
|
|
251
|
+
```
|