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,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 }) // ← EXISTS; so do relation filters `{ posts: { some } }` and nested writes `{ connect }` (defineTable only)
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
+ ```