express-file-cluster 0.3.15 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -33
- package/dist/auth/index.cjs +12 -2
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +13 -2
- package/dist/auth/index.d.ts +13 -2
- package/dist/auth/index.js +12 -2
- package/dist/chunk-277BSYVH.js +127 -0
- package/dist/chunk-277BSYVH.js.map +1 -0
- package/dist/chunk-6OGOVV57.js +3847 -0
- package/dist/chunk-6OGOVV57.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-AZYXQU3Z.cjs +3847 -0
- package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
- package/dist/chunk-BUBXO7WU.js +170 -0
- package/dist/chunk-BUBXO7WU.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-MGH4VDV3.cjs +170 -0
- package/dist/chunk-MGH4VDV3.cjs.map +1 -0
- package/dist/chunk-R34R7QPD.cjs +116 -0
- package/dist/chunk-R34R7QPD.cjs.map +1 -0
- package/dist/chunk-RS4MXCPW.js +116 -0
- package/dist/chunk-RS4MXCPW.js.map +1 -0
- package/dist/chunk-T4OHFU5T.cjs +154 -0
- package/dist/chunk-T4OHFU5T.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-TRC4DUZB.js +438 -0
- package/dist/chunk-TRC4DUZB.js.map +1 -0
- package/dist/chunk-TYR2GZZE.cjs +196 -0
- package/dist/chunk-TYR2GZZE.cjs.map +1 -0
- package/dist/chunk-UBQYQPBU.js +154 -0
- package/dist/chunk-UBQYQPBU.js.map +1 -0
- package/dist/chunk-UTM4PEVG.js +196 -0
- package/dist/chunk-UTM4PEVG.js.map +1 -0
- package/dist/chunk-YL37D6KM.cjs +127 -0
- package/dist/chunk-YL37D6KM.cjs.map +1 -0
- package/dist/chunk-ZDM5JHVK.cjs +438 -0
- package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
- package/dist/cli/db-runner.cjs +497 -0
- package/dist/cli/db-runner.cjs.map +1 -0
- package/dist/cli/db-runner.d.cts +2 -0
- package/dist/cli/db-runner.d.ts +2 -0
- package/dist/cli/db-runner.js +497 -0
- package/dist/cli/db-runner.js.map +1 -0
- package/dist/cli/index.cjs +447 -69
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +473 -95
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +232 -0
- package/dist/docs/api-reference/compose.md +78 -0
- package/dist/docs/api-reference/db.md +351 -0
- package/dist/docs/api-reference/http-error.md +109 -0
- package/dist/docs/api-reference/ignite.md +326 -0
- package/dist/docs/api-reference/table.md +458 -0
- package/dist/docs/api-reference/tasks.md +140 -0
- package/dist/docs/cli/db.md +38 -0
- package/dist/docs/cli/diagnostics.md +145 -0
- package/dist/docs/cli/generate.md +120 -0
- package/dist/docs/cli/index.md +48 -0
- package/dist/docs/cli/start.md +112 -0
- package/dist/docs/contributing/index.md +139 -0
- package/dist/docs/core-concepts/background-tasks.md +228 -0
- package/dist/docs/core-concepts/clustering.md +114 -0
- package/dist/docs/core-concepts/file-based-routing.md +235 -0
- package/dist/docs/core-concepts/index.md +79 -0
- package/dist/docs/core-concepts/middleware.md +144 -0
- package/dist/docs/getting-started/index.md +91 -0
- package/dist/docs/getting-started/project-structure.md +154 -0
- package/dist/docs/guides/ai-agents.md +48 -0
- package/dist/docs/guides/authentication.md +196 -0
- package/dist/docs/guides/caching.md +124 -0
- package/dist/docs/guides/database.md +217 -0
- package/dist/docs/guides/deployment.md +171 -0
- package/dist/docs/guides/environment-variables.md +106 -0
- package/dist/docs/guides/error-handling.md +172 -0
- package/dist/docs/guides/generated-portals.md +115 -0
- package/dist/docs/guides/logging.md +108 -0
- package/dist/docs/guides/mailer.md +166 -0
- package/dist/docs/guides/migrations.md +106 -0
- package/dist/docs/guides/rbac.md +89 -0
- package/dist/docs/guides/validation.md +95 -0
- package/dist/docs/index.md +93 -0
- package/dist/docs/skills/SKILL.md +44 -0
- package/dist/docs/skills/api-surface.md +309 -0
- package/dist/docs/skills/auth-internals.md +141 -0
- package/dist/docs/skills/pre-flight.md +142 -0
- package/dist/docs/skills/routing-rules.md +114 -0
- package/dist/docs/skills/tasks-internals.md +172 -0
- package/dist/docs/skills/what-not-to-invent.md +251 -0
- package/dist/index.cjs +264 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +699 -7
- package/dist/index.d.ts +699 -7
- package/dist/index.js +258 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
- package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
- package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/types-B6lVw4bj.d.cts +588 -0
- package/dist/types-B6lVw4bj.d.ts +588 -0
- package/package.json +28 -5
- package/dist/chunk-6522HS2J.cjs +0 -99
- package/dist/chunk-6522HS2J.cjs.map +0 -1
- package/dist/chunk-DGVOJNR6.cjs +0 -55
- package/dist/chunk-DGVOJNR6.cjs.map +0 -1
- package/dist/chunk-KOHLLUN7.js +0 -55
- package/dist/chunk-KOHLLUN7.js.map +0 -1
- package/dist/chunk-VIP3PFWZ.js +0 -99
- package/dist/chunk-VIP3PFWZ.js.map +0 -1
- package/dist/types-BusbSenn.d.cts +0 -162
- package/dist/types-BusbSenn.d.ts +0 -162
|
@@ -0,0 +1,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
|
+
```
|