express-file-cluster 0.3.15 → 0.5.0

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