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,89 @@
1
+ # Role-Based Access Control (RBAC)
2
+
3
+ Role checks are built into `requireAuth` itself — call it with role names (`requireAuth('admin')`) instead of a separate middleware (see [Authentication](./authentication.md)). `create-efc-app` can also scaffold a `Role` model and role-management API for you via the **RBAC** feature option.
4
+
5
+ ---
6
+
7
+ ## Enabling it
8
+
9
+ Toggle **Role-based access control** in the features multiselect:
10
+
11
+ ```
12
+ ? Features: (space to toggle, enter to confirm)
13
+ ◉ User portal
14
+ ◉ Admin portal
15
+ ◉ Role-based access control
16
+ ```
17
+
18
+ RBAC is most useful alongside **User portal** and/or **Admin portal**, since it changes how their generated routes are protected — but it can be toggled independently.
19
+
20
+ ---
21
+
22
+ ## What gets generated
23
+
24
+ ### Route protection
25
+
26
+ Every generated route that would otherwise export `middlewares = [requireAuth]` instead exports:
27
+
28
+ ```ts
29
+ // User-facing routes
30
+ export const middlewares = [requireAuth('user', 'admin')];
31
+
32
+ // Admin-facing routes
33
+ export const middlewares = [requireAuth('admin')];
34
+ ```
35
+
36
+ `requireAuth('admin')` verifies the JWT *and* checks that `payload.role` is one of the given roles — returning `401` if the token is missing/invalid, `403` if the role doesn't match.
37
+
38
+ If RBAC is **not** enabled, admin routes fall back to an inline guard at the top of the handler instead:
39
+
40
+ ```ts
41
+ export const middlewares = [requireAuth];
42
+
43
+ export const GET = async (req, res) => {
44
+ const user = (req as any).user;
45
+ if (user?.role !== 'admin') {
46
+ return res.status(403).json({ error: 'Forbidden: Admin access required' });
47
+ }
48
+ // ...
49
+ };
50
+ ```
51
+
52
+ Both approaches produce the same 401/403 behavior — RBAC-on just centralizes the check into `requireAuth(...)` and adds the `Role` model below.
53
+
54
+ ### `Role` model
55
+
56
+ A `src/model/Role.ts` model is created (MongoDB: a real `defineModel`-backed collection; PostgreSQL: a commented-out Drizzle stub, per the current [database support status](./database.md)).
57
+
58
+ ### Admin role management routes
59
+
60
+ If **RBAC** and **Admin portal** are both enabled, a full role-management API is scaffolded:
61
+
62
+ | Method | Path |
63
+ |---|---|
64
+ | `GET` | `/admin/roles` |
65
+ | `POST` | `/admin/roles` |
66
+ | `GET` | `/admin/roles/:id` |
67
+ | `PUT` | `/admin/roles/:id` |
68
+ | `DELETE` | `/admin/roles/:id` |
69
+
70
+ See [Generated Portals](./generated-portals.md) for the complete route/model inventory.
71
+
72
+ ---
73
+
74
+ ## Using it yourself
75
+
76
+ You don't need the scaffolder to use this pattern — `requireAuth(...roles)` is exported from `express-file-cluster/auth` in every EFC project:
77
+
78
+ ```ts
79
+ // src/api/admin/dashboard.ts
80
+ import { requireAuth } from 'express-file-cluster/auth';
81
+
82
+ export const middlewares = [requireAuth('admin')];
83
+
84
+ export const GET = async (_req, res) => {
85
+ res.json({ stats: { users: 42 } });
86
+ };
87
+ ```
88
+
89
+ Pass multiple roles to allow any of them: `requireAuth('user', 'admin')`. See the [Auth API reference](../api-reference/auth.md#requireauth) for the full signature.
@@ -0,0 +1,95 @@
1
+ # Request Validation
2
+
3
+ Route files can export a `schema` that validates `params`, `query` and `body` before the handler runs. Invalid requests never reach your code; valid ones arrive already parsed.
4
+
5
+ ---
6
+
7
+ ## Any validator, no lock-in
8
+
9
+ EFC accepts any [Standard Schema](https://standardschema.dev) validator — zod 3.24+, valibot, arktype, effect/schema — plus anything exposing a zod-style `safeParse`. It never imports a validation library, so install the one you like:
10
+
11
+ ```bash
12
+ npm install zod
13
+ ```
14
+
15
+ ---
16
+
17
+ ## Per method, or for the whole file
18
+
19
+ ```ts
20
+ // src/api/products/[id].ts
21
+ import { z } from 'zod';
22
+
23
+ export const schema = {
24
+ GET: {
25
+ params: z.object({ id: z.string().uuid() }),
26
+ query: z.object({ include: z.enum(['reviews', 'stock']).optional() }),
27
+ },
28
+ PATCH: {
29
+ params: z.object({ id: z.string().uuid() }),
30
+ body: z.object({ price: z.number().positive(), title: z.string().min(2) }).partial(),
31
+ },
32
+ };
33
+
34
+ export const GET = async (req, res) => { /* ... */ };
35
+ export const PATCH = async (req, res) => { /* ... */ };
36
+ ```
37
+
38
+ When every method shares the same rules, skip the method keys:
39
+
40
+ ```ts
41
+ export const schema = { params: z.object({ id: z.coerce.number().int() }) };
42
+ ```
43
+
44
+ A method-keyed entry wins over the file-wide one; methods with no entry are not validated.
45
+
46
+ ---
47
+
48
+ ## Parsed output replaces the raw input
49
+
50
+ On success, `req.params`, `req.query` and `req.body` are replaced by the validator's **output** — coercions (`z.coerce.number()`), defaults (`.default('member')`) and transforms apply:
51
+
52
+ ```ts
53
+ export const schema = { POST: { body: z.object({ age: z.coerce.number(), role: z.string().default('member') }) } };
54
+
55
+ export const POST = async (req, res) => {
56
+ req.body; // { age: 21, role: 'member' } for an input of { age: '21' }
57
+ };
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Error response
63
+
64
+ All issues from every location are returned together with status **400**:
65
+
66
+ ```json
67
+ {
68
+ "error": "Validation failed",
69
+ "statusCode": 400,
70
+ "issues": [
71
+ { "location": "body", "path": "email", "message": "Invalid email address" },
72
+ { "location": "query", "path": "page", "message": "Expected number, received nan" }
73
+ ]
74
+ }
75
+ ```
76
+
77
+ `path` is dot-joined inside its location (`address.zip`), empty for the root.
78
+
79
+ ---
80
+
81
+ ## Ordering
82
+
83
+ The request pipeline for a route is:
84
+
85
+ ```
86
+ global middleware → file middlewares → schema validation → handler
87
+ ```
88
+
89
+ So authentication in `middlewares` still responds 401/403 before any 400 — unauthenticated callers can't probe your validation rules.
90
+
91
+ ---
92
+
93
+ ## Model-level validation is separate
94
+
95
+ `schema` validates the HTTP request. `defineModel` validates what you write to the database (types, `required`, `enum`, `min`/`max`, `match`, custom `validate`) and throws a `ModelValidationError` — also a 400 with `issues`. Use both: request schemas for the API contract, model rules for data integrity. See [Database](./database.md).
@@ -0,0 +1,93 @@
1
+ # EFC Documentation
2
+
3
+ **express-file-cluster (EFC)** is an opinionated backend framework built on Express. It removes routing ceremony, saturates every CPU core automatically, and ships a production-grade background-task subsystem — all from a single `ignite()` call.
4
+
5
+ > **Status: v0.7.0 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, and migrations are all implemented.
6
+
7
+ ---
8
+
9
+ ## What EFC solves
10
+
11
+ | Pain point | EFC's answer |
12
+ |---|---|
13
+ | Route registration boilerplate | The file tree **is** the route tree |
14
+ | Single-threaded Node under load | CPU-count auto-detection → worker processes |
15
+ | Blocking work on the request path | `enqueue()` ships it off-path with retries; `schedule` runs it on cron |
16
+ | Wiring DB, auth, and middleware by hand | `ignite()` bootstraps everything in one call |
17
+ | Different code per database | `defineModel` runs the same on MongoDB and PostgreSQL |
18
+ | Hand-rolled input checks | `export const schema` validates params, query and body |
19
+
20
+ ---
21
+
22
+ ## Documentation sections
23
+
24
+ | Section | What you'll find |
25
+ |---|---|
26
+ | [Getting Started](./getting-started/index.md) | Scaffold a project, understand the structure |
27
+ | [Core Concepts](./core-concepts/index.md) | The four pillars: routing, clustering, tasks, middleware |
28
+ | [API Reference](./api-reference/ignite.md) | Every exported function and type, fully documented |
29
+ | [Guides](./guides/authentication.md) | Deep-dives: auth, database, RBAC, mailer, error handling, deployment |
30
+ | [CLI](./cli/index.md) | All `efc` commands with flags and examples |
31
+ | [Contributing](./contributing/index.md) | Roadmap, branch conventions, PR requirements |
32
+
33
+ ### Guides
34
+
35
+ | Guide | Covers |
36
+ |---|---|
37
+ | [Authentication](./guides/authentication.md) | JWT strategies, login/logout, `requireAuth` |
38
+ | [RBAC](./guides/rbac.md) | Role-based route protection via the `requireAuth('role')` shorthand |
39
+ | [Database](./guides/database.md) | `defineModel`, queries, transactions, MongoDB vs PostgreSQL |
40
+ | [defineTable](./api-reference/table.md) | PostgreSQL-native models: Prisma-style queries, SQL types, aggregation |
41
+ | [Migrations & Seeds](./guides/migrations.md) | `efc db migrate / rollback / seed / studio` |
42
+ | [Validation](./guides/validation.md) | Route `schema` exports with zod, valibot, arktype |
43
+ | [Logging](./guides/logging.md) | pino, request IDs, `getLogger()` |
44
+ | [Caching & Sessions](./guides/caching.md) | `cache`, `cacheResponse`, revoking JWT sessions |
45
+ | [Generated Portals](./guides/generated-portals.md) | Every model and route `create-efc-app` scaffolds for the User/Admin portals |
46
+ | [Mailer](./guides/mailer.md) | Gmail (app password) and custom SMTP setup, sending email from a task |
47
+ | [Environment Variables](./guides/environment-variables.md) | Full `.env` reference |
48
+ | [Error Handling](./guides/error-handling.md) | `HttpError`, custom handlers, task failures |
49
+ | [Deployment](./guides/deployment.md) | Build, start, and ship to production |
50
+ | [AI Coding Agents](./guides/ai-agents.md) | Docs bundled in the package, `AGENTS.md`, the `express-file-cluster-mcp` server |
51
+
52
+ ### Tooling
53
+
54
+ An [MCP server](https://github.com/pr4shxnt/efc.js/tree/main/mcp) ships in this repo (`mcp/`) that exposes this documentation as tools, resources, and prompts to MCP-compatible AI assistants (Claude, Cursor, etc.) — useful if you want an assistant to scaffold routes/tasks or answer "does EFC support X?" without hallucinating. See `mcp/README.md` for setup.
55
+
56
+ ---
57
+
58
+ ## Five-minute overview
59
+
60
+ ```bash
61
+ # 1. Scaffold
62
+ npx create-efc-app my-api
63
+ cd my-api
64
+
65
+ # 2. Run in dev mode (hot-reload, single process)
66
+ npm run dev # → efc start dev
67
+
68
+ # 3. Drop a file → get a route
69
+ # src/api/users/[id].ts → GET /users/:id
70
+ ```
71
+
72
+ ```ts
73
+ // src/api/users/[id].ts
74
+ import type { Request, Response } from 'express';
75
+
76
+ export const GET = async (req: Request, res: Response) => {
77
+ res.json({ id: req.params.id });
78
+ };
79
+ ```
80
+
81
+ ```ts
82
+ // src/index.ts
83
+ import { ignite, gracefulShutdown } from 'express-file-cluster';
84
+ import config from '../efc.config.js';
85
+
86
+ // efc.config.ts reads PORT, DATABASE_URL, JWT_SECRET, CORS_ORIGINS from .env explicitly —
87
+ // ignite() itself never touches process.env for these (see Environment Variables guide)
88
+ ignite({
89
+ ...config,
90
+ }).then(gracefulShutdown).catch(console.error);
91
+ ```
92
+
93
+ The framework always scans `src/api/` on boot (this path is a fixed convention, not configurable), derives route paths from file names, forks `os.cpus().length` worker processes in production (single-process in dev — `ignite()`'s own default, don't override it with a hardcoded `cluster: true`), and handles `SIGTERM`/`SIGINT` gracefully — zero extra code required.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: efc
3
+ description: Ground-truth reference for express-file-cluster (EFC) — exact API surface, routing rules, Pre-Flight lifecycle, task internals, and a hard list of things that do NOT exist. Load before writing any EFC code to avoid hallucination.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Express File Cluster (EFC) — Skill
8
+
9
+ Use this skill whenever you're reading, writing, or debugging EFC code. It loads the exact source-derived facts about this framework so you never invent APIs, import paths, or behaviours that don't exist.
10
+
11
+ ## When to load
12
+
13
+ - Writing a new route, task, model, or middleware
14
+ - Debugging a boot failure or a missing-route issue
15
+ - Answering "does EFC support X?" questions
16
+ - Any time you're about to type an `import` from `express-file-cluster`
17
+
18
+ ## Routing table — open the module that matches the work
19
+
20
+ | Situation | Open |
21
+ |---|---|
22
+ | What is exported and from where | [api-surface.md](api-surface.md) |
23
+ | How file paths become URL paths | [routing-rules.md](routing-rules.md) |
24
+ | Worker boot sequence (Pre-Flight) | [pre-flight.md](pre-flight.md) |
25
+ | Background tasks — defineTask, enqueue, thread, cron, pg-boss, dead letters | [tasks-internals.md](tasks-internals.md) |
26
+ | Auth — issueToken, requireAuth internals | [auth-internals.md](auth-internals.md) |
27
+ | Things that do NOT exist (anti-hallucination) | [what-not-to-invent.md](what-not-to-invent.md) |
28
+
29
+ Load **only** the module the work points to. Each is self-contained.
30
+
31
+ ## Project location
32
+
33
+ ```
34
+ <repo root>/
35
+ packages/core/src/ ← framework source
36
+ packages/create-efc-app/src/ ← scaffolder
37
+ docs/ ← full documentation
38
+ ```
39
+
40
+ ## Status (v0.7.0 — Beta, Phase 2 complete + defineTable with relations)
41
+
42
+ Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only + localStorage auth, structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, PostgreSQL-native `defineTable` (Prisma-style queries, foreign keys, many-to-many, `include`, relation filters, nested writes), query logging (`logging.queries`), BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`), full CLI.
43
+
44
+ **Not yet implemented (Phase 3+):** WebSockets, plugins, OpenAPI generation, OpenTelemetry, `efc lint`, `efc deploy`, schema-diff migration generation.
@@ -0,0 +1,309 @@
1
+ # EFC — Exact API Surface
2
+
3
+ Source of truth: `packages/core/src/`. Do not invent exports, types, or sub-paths not listed here.
4
+
5
+ ---
6
+
7
+ ## Sub-path exports
8
+
9
+ Three import paths. No others exist.
10
+
11
+ ```ts
12
+ import { ... } from 'express-file-cluster' // main
13
+ import { ... } from 'express-file-cluster/auth' // auth module
14
+ import { ... } from 'express-file-cluster/tasks' // tasks module
15
+ ```
16
+
17
+ ---
18
+
19
+ ## `express-file-cluster` (main)
20
+
21
+ Source: `packages/core/src/index.ts`
22
+
23
+ ### Functions & values
24
+
25
+ ```ts
26
+ async function ignite(config: EFCConfig): Promise<http.Server | undefined> // undefined on the cluster primary
27
+ function gracefulShutdown(server: http.Server | undefined, timeoutMs?: number): void
28
+ function compose(...handlers: RequestHandler[]): RequestHandler
29
+
30
+ // Models — one API on MongoDB (mongoose) and PostgreSQL (Drizzle); engine picked at first use
31
+ // Types are INFERRED from the schema literal — no interface needed:
32
+ // const User = defineModel('User', {...}); type User = InferRecord<typeof User>;
33
+ // Explicit defineModel<T>(...) still works (v0.4 behaviour: create() takes Partial<T>).
34
+ function defineModel(name: string, schema: ModelSchema, options?: ModelOptions): ModelCRUD<Record, CreateInput>
35
+ type InferRecord<typeof Model> // record incl. id + timestamps per options (defineModel and defineTable)
36
+ type InferCreate<typeof Model> // create() input: required w/o default/sequence mandatory; dates accept string|number
37
+ async function transaction<T>(fn: () => Promise<T>): Promise<T> // model calls inside join automatically
38
+ // PostgreSQL-native (Prisma vocabulary + SQL types); MongoDB → [EFC] error at first use
39
+ function defineTable(name: string, schema: TableSchema, options?: TableOptions): TableModel<S, O>
40
+ // types: + 'integer' (number) 'bigint' (bigint) 'decimal' {precision, scale} (string, exact) 'uuid' 'json'
41
+ // 'string'+maxLength → varchar(n); { type:'array', of: scalar } → native array; enum + nativeEnum → PG ENUM
42
+ // options: id: 'uuid' | 'serial' (number ids) | 'bigserial' (bigint ids); naming: 'snake_case'; field `column`
43
+ // findMany({ where, orderBy, take (neg = backwards), skip, cursor (unique where, inclusive), distinct, select | omit })
44
+ // findFirst / findFirstOrThrow / findUnique({ where: unique }) / findUniqueOrThrow → 404 HttpError
45
+ // count({ where, select?: { _all, field } }) · aggregate({ _count, _sum, _avg, _min, _max, where, ...page })
46
+ // groupBy({ by, where, having: { f: { _sum: { gt } } }, orderBy: { _sum: { f: 'desc' } }, take, skip })
47
+ // create({ data }) · createMany({ data, skipDuplicates }) → { count } · createManyAndReturn
48
+ // update({ where: unique, data }) 404 if missing · updateMany → { count } · updateManyAndReturn
49
+ // upsert({ where: unique, create, update }) = one INSERT … ON CONFLICT · delete({ where: unique }) · deleteMany → { count }
50
+ // where: value | null | equals not in notIn lt lte gt gte · strings: contains startsWith endsWith mode:'insensitive'
51
+ // arrays: has hasEvery hasSome isEmpty · jsonb: { path: [...], equals | string_contains | array_contains | gt… }
52
+ // AND / OR / NOT · undefined ignored · undeclared fields match nothing
53
+ // data ops: { increment | decrement | multiply | divide } (numbers), { push } (arrays), { set }, null unsets
54
+ // unique where: id | unique field | all fields of a unique index. Top-level `ref` = FK, `onDelete: 'restrict'|'cascade'|'setNull'`, ref type must match target id (uuid/objectId | integer for serial | bigint for bigserial). Array of refs `{ type: 'array', of: <id type>, ref }` = many-to-many (join table, record keeps id list, list filters, set/push). `include` loads refs, m:n and `options.relations` back-relations (hasMany/hasOne + foreignKey) in one statement; typed via `interface Tables` augmentation. Relation filters `some/every/none`, `is/isNot`; nested writes `connect/create/connectOrCreate/disconnect/set/delete/deleteMany` (one transaction; not in createMany/updateMany).
55
+
56
+ class ModelValidationError extends HttpError { issues: { path: string; message: string }[] } // status 400
57
+
58
+ // Native client from Pre-Flight: mongoose Connection (MongoDB) or pg Pool (PostgreSQL)
59
+ const db: AnyClient // Proxy — throws before Pre-Flight; methods are bound to the real client
60
+ function setDbClient(client: Record<string, unknown>): void
61
+ function getDbClient(): Record<string, unknown>
62
+
63
+ // Logging (pino)
64
+ const logger: Logger // proxy for getLogger()
65
+ function getLogger(): Logger // request-scoped child (carries reqId) inside a request, root otherwise
66
+
67
+ // Cache — needs ignite({ cache }); throws "Cache not configured" otherwise.
68
+ // Redis outage → get = undefined, set/del no-ops, wrap computes (never throws).
69
+ const cache: {
70
+ get<T>(key): Promise<T | undefined>; set(key, value, { ttl?: seconds }?): Promise<void>;
71
+ has(key): Promise<boolean>; del(...keys): Promise<number>;
72
+ wrap<T>(key, ttlOrOptions, fn: () => Promise<T>): Promise<T>; // in-process stampede dedupe
73
+ clear(prefix?): Promise<number>;
74
+ }
75
+ function cacheResponse(ttl: number | { ttl; perUser?: boolean; key?: (req) => string }): RequestHandler
76
+ // GET/HEAD 200 JSON only; X-Cache: HIT|MISS; keys under 'res:' + originalUrl
77
+
78
+ function scanDir(dir: string, base?: string, maxDepth?: number): RouteEntry[]
79
+ function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
80
+ function workerCount(): number
81
+ class HttpError extends Error { readonly statusCode: number; static from(err, status?, fallback?): HttpError }
82
+ function isHttpError(value: unknown): value is HttpError
83
+ ```
84
+
85
+ ### Config types
86
+
87
+ ```ts
88
+ interface EFCConfig {
89
+ port?: number; // default 3000
90
+ basePath?: string; // default '/v1/api'
91
+ dashboard?: boolean; // dev-only route docs at '/'
92
+ database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
93
+ databaseUrl?: string;
94
+ authStrategy?: 'http-only' | 'localStorage';
95
+ jwtSecret?: string;
96
+ jwtExpiresIn?: string; // default '7d'
97
+ cookieDomain?: string;
98
+ cluster?: boolean; // default NODE_ENV === 'production'
99
+ workers?: number; // default os.cpus().length
100
+ tasks?: TaskConfig | false;
101
+ cors?: boolean | CorsConfig; // default true
102
+ requestTimeout?: number; // ms → 408
103
+ logging?: LoggingConfig | false;
104
+ autoSync?: boolean; // default true — reconcile tables/collections + indexes on first use
105
+ cache?: ({ prefix?: string; onRevocationCheckError?: 'reject' | 'allow' /* default reject → 503 */ } & (
106
+ | { backend: 'redis'; url?: string; timeout?: number }
107
+ | { backend: 'memory'; maxEntries?: number } /* lives in the cluster primary; workers use IPC */
108
+ )) | false;
109
+ globalMiddlewares?: RequestHandler[];
110
+ onWorkerReady?: (id: number) => void;
111
+ onWorkerCrash?: (id: number, code: number) => void;
112
+ onError?: ErrorRequestHandler;
113
+ }
114
+ // NOTE: there is NO apiDir / tasksDir option — src/api and src/tasks are found by convention.
115
+
116
+ interface TaskConfig {
117
+ backend: 'bullmq' | 'pg-boss';
118
+ redisUrl?: string; // BullMQ, default redis://localhost:6379
119
+ connectionString?: string; // pg-boss, default databaseUrl
120
+ schema?: string; // pg-boss, default 'pgboss'
121
+ concurrency?: number; // default 5
122
+ enqueueTimeout?: number; // default 5000 ms — enqueue() rejects instead of hanging
123
+ queue?: string; // default 'efc'
124
+ }
125
+
126
+ interface LoggingConfig {
127
+ level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'; // default 'info'
128
+ pretty?: boolean; // default: non-production TTY
129
+ requests?: boolean; // default true
130
+ queries?: boolean | { all?: boolean; slowMs?: number; nPlusOne?: number | false }; // default off; slowMs 500, nPlusOne 10
131
+ }
132
+ ```
133
+
134
+ ### Route file exports
135
+
136
+ ```ts
137
+ export const GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS = async (req, res) => {}
138
+ export const middlewares: RequestHandler[]
139
+ export const schema: RouteSchema // { params?, query?, body? } or keyed by method
140
+ export const meta: RouteMeta // dashboard docs, keyed by method
141
+
142
+ type Validator = { '~standard': { validate } } | { safeParse } // Standard Schema (zod ≥3.24, valibot, arktype)
143
+ interface RequestSchema { params?: Validator; query?: Validator; body?: Validator }
144
+ type RouteSchema = RequestSchema | Partial<Record<string, RequestSchema>>
145
+ // Failure → 400 { error: 'Validation failed', statusCode: 400, issues: [{ location, path, message }] }
146
+ // Success → parsed output replaces req.params/query/body. Runs AFTER file middlewares.
147
+ ```
148
+
149
+ `req.id` (request ID) and `req.log` (request logger) are added to Express's `Request` type.
150
+
151
+ ### Model types
152
+
153
+ ```ts
154
+ type PrimitiveFieldType = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'objectId';
155
+
156
+ interface FieldDefinition {
157
+ type: PrimitiveFieldType | 'array';
158
+ required?: boolean; unique?: boolean; index?: boolean;
159
+ default?: unknown; // literal, function, or DefaultOperator
160
+ enum?: readonly (string | number)[];
161
+ min?: number | Date; max?: number | Date; // number, date
162
+ minLength?: number; maxLength?: number; // string
163
+ match?: RegExp; // string
164
+ validate?: (v: unknown) => boolean | string | Promise<boolean | string>; // string = error message
165
+ ref?: string; // objectId / objectId arrays → populate
166
+ of?: PrimitiveFieldType | ModelSchema; // array item: primitive or embedded doc schema
167
+ fields?: ModelSchema; // typed embedded object (type: 'object')
168
+ sequence?: boolean | string; // auto-increment; Mongo efc_counters / PG SEQUENCE
169
+ }
170
+
171
+ // A field: FieldDefinition | nested ModelSchema (embedded object shorthand) | [ModelSchema] (array of embedded docs)
172
+ type SchemaField = FieldDefinition | ModelSchema | [ModelSchema] | readonly [ModelSchema];
173
+ interface ModelSchema { [field: string]: SchemaField }
174
+
175
+ type DefaultOperator = '$now' | '$uuid' | '$objectId' | '$timestamp' | '$shortId' | '$currentUser' | `$currentUser.${string}`;
176
+ // '$increment' is NOT an operator — use `sequence`.
177
+
178
+ interface ModelOptions {
179
+ timestamps?: boolean | { createdAt?: string | false; updatedAt?: string | false }; // default true
180
+ indexes?: { fields: Record<string, 1 | -1 | 'text'>; unique?: boolean; expireAfterSeconds?: number; name?: string }[];
181
+ collection?: string; // collection/table name, default lowercase plural of the model name
182
+ }
183
+
184
+ interface FindOptions { populate?: string | string[]; select?: string[]; sort?: Record<string, 1 | -1 | 'asc' | 'desc'>; limit?: number; skip?: number }
185
+
186
+ // Filter<T>: equality (array fields: contains), $eq $ne $gt $gte $lt $lte $in $nin $exists $regex,
187
+ // $and / $or, dotted paths ('address.city'), `id` for the primary key. Typed — no casts.
188
+ // Update<T>: plain fields (= $set) and/or $set (dotted ok) $inc $push ({$each}) $pull $unset.
189
+
190
+ // Inferred: record type = required/default/sequence fields non-optional, enum → literal union,
191
+ // 'date' → Date (nested too, both engines), 'objectId' → string, untyped object/array → unknown.
192
+ interface ModelCRUD<T, TCreate = Partial<T>> {
193
+ readonly name: string;
194
+ find(filter?: Filter<T>, options?: FindOptions): Promise<ModelRecord<T>[]>;
195
+ findById(id: string, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>; // malformed id → null
196
+ findOne(filter: Filter<T>, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>;
197
+ exists(filter: Filter<T>): Promise<boolean>;
198
+ distinct(field: ScalarKeys<T>, filter?: Filter<T>): Promise<T[field][]>; // non-null, sorted; arrays/objects rejected
199
+ create(data: TCreate): Promise<ModelRecord<T>>;
200
+ createMany(data: TCreate[]): Promise<ModelRecord<T>[]>;
201
+ update(id: string, data: Update<T>): Promise<ModelRecord<T> | null>; // VALIDATES changed fields
202
+ updateOne(filter: Filter<T>, data: Update<T>): Promise<ModelRecord<T> | null>; // first match, one statement
203
+ updateMany(filter: Filter<T>, data: Update<T>): Promise<number>;
204
+ upsert(filter: Filter<T>, create: TCreate, update: Update<T>): Promise<ModelRecord<T>>; // filter NOT merged into create; 409 on create retried once as update
205
+ delete(id: string): Promise<void>;
206
+ deleteOne(filter: Filter<T>): Promise<ModelRecord<T> | null>; // returns the deleted record
207
+ deleteMany(filter: Filter<T>): Promise<number>;
208
+ count(filter?: Filter<T>): Promise<number>;
209
+ aggregate<R>(pipeline: object[]): Promise<R[]>; // MongoDB only — rejects on PostgreSQL
210
+ raw(): Promise<unknown>; // mongoose Model / Drizzle pgTable
211
+ sync(opts?: { dryRun?: boolean }): Promise<string[]>; // reconcile (auto on first use); returns changes / planned SQL
212
+ drop(): Promise<void>;
213
+ }
214
+ type ModelRecord<T> = T & { id: string };
215
+ // Errors: ModelValidationError (400, issues), duplicate unique → HttpError 409.
216
+
217
+ interface MigrationContext { db: unknown; engine: 'mongodb' | 'postgresql' } // passed to up/down/seed
218
+ ```
219
+
220
+ ---
221
+
222
+ ## `express-file-cluster/auth`
223
+
224
+ Source: `packages/core/src/auth/index.ts`
225
+
226
+ ```ts
227
+ // Set cookie (http-only strategy)
228
+ async function issueToken(res: Response, payload: Record<string, unknown>): Promise<void>
229
+
230
+ // Clear cookie (http-only strategy)
231
+ function revokeToken(res: Response): void
232
+
233
+ // Return token string (localStorage strategy)
234
+ async function signToken(payload: Record<string, unknown>): Promise<string>
235
+
236
+ // Need ignite({ cache }). Every signed token carries jti + iat + efc_iat (ms).
237
+ async function revokeSession(req: Request, res?: Response): Promise<void> // denylist this token until exp
238
+ async function revokeAllSessions(userId: string | number): Promise<void> // reject tokens issued before now
239
+
240
+ // Express middleware — verifies JWT, attaches payload to req.user.
241
+ // Dual-purpose: bare it's just auth; called with role names it returns a
242
+ // middleware that also enforces payload.role (403 if it doesn't match).
243
+ interface RequireAuth {
244
+ (req: Request, res: Response, next: NextFunction): void;
245
+ (...roles: string[]): RequestHandler;
246
+ }
247
+ const requireAuth: RequireAuth
248
+
249
+ // Internal — called by ignite()
250
+ function configureAuth(config: { secret: string; strategy: AuthStrategy; expiresIn: string; cookieDomain?: string }): void
251
+
252
+ // Reads the JWT payload requireAuth attached to the in-flight request, from
253
+ // anywhere in the async call chain (backed by AsyncLocalStorage — see context.ts).
254
+ // Returns undefined outside a request, or on a route that never ran requireAuth.
255
+ // Also what powers the '$currentUser'/'$currentUser.<key>' defineModel default codes.
256
+ function getCurrentUser(): Record<string, unknown> | undefined
257
+ ```
258
+
259
+ Cookie name: `efc_token`. Algorithm: HS256. Library: `jose`.
260
+
261
+ Every request run through `ignite()` is wrapped in its own `AsyncLocalStorage` context (`packages/core/src/context.ts`) before any other middleware runs; `requireAuth` populates it with the verified JWT payload. This DOES exist now — it's no longer accurate to say EFC has no request context (see `what-not-to-invent.md`, which has been updated).
262
+
263
+ ---
264
+
265
+ ## `express-file-cluster/tasks`
266
+
267
+ Source: `packages/core/src/tasks/index.ts`
268
+
269
+ ```ts
270
+ function defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
271
+ function defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
272
+
273
+ // Rejects: backend not configured | unknown task | backend unreachable within tasks.enqueueTimeout
274
+ async function enqueue<T>(name: string, payload: T): Promise<void>
275
+
276
+ interface TaskOptions {
277
+ thread?: boolean; // run in worker_threads
278
+ retries?: number; // re-runs; up to retries + 1 attempts. Default 3
279
+ backoff?: 'fixed' | 'exponential'; // 1 s base. Default 'exponential'
280
+ concurrency?: number;
281
+ schedule?: string; // cron; scheduled runs get payload {}
282
+ timezone?: string; // IANA tz for schedule
283
+ }
284
+
285
+ // Internal
286
+ function registerTask(name: string, def: TaskDefinition): void
287
+ function setEnqueueImpl(impl: (name: string, payload: unknown) => Promise<void>): void
288
+ const taskRegistry: Map<string, TaskDefinition>
289
+ function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
290
+ ```
291
+
292
+ ---
293
+
294
+ ## `ignite()` does NOT read app config from `process.env` — `NODE_ENV` is the one exception
295
+
296
+ `ignite()` never reads `PORT`, `DATABASE_URL`, `JWT_SECRET`, `JWT_EXPIRES_IN`, `COOKIE_DOMAIN`, or `CORS_ORIGINS` itself. Each must be passed explicitly in the `EFCConfig` object — the scaffolder generates an `efc.config.ts` that reads `process.env.X` for each of these and builds that object; `src/index.ts` just spreads it into `ignite()`. See `what-not-to-invent.md` for the full "does not auto-read" list.
297
+
298
+ | Config field | Typically wired from | Fallback if unset |
299
+ |---|---|---|
300
+ | `port` | `process.env.PORT` | `3000` |
301
+ | `databaseUrl` | `process.env.DATABASE_URL` | none (no DB connects) |
302
+ | `jwtSecret` | `process.env.JWT_SECRET` | none (auth disabled) |
303
+ | `jwtExpiresIn` | `process.env.JWT_EXPIRES_IN` | `'7d'` |
304
+ | `cookieDomain` | `process.env.COOKIE_DOMAIN` | unset (host-only cookie) |
305
+ | `cors.origin` | `process.env.CORS_ORIGINS?.split(',')` | `true` (allow all) |
306
+ | `tasks.redisUrl` | `process.env.REDIS_URL` | `'redis://localhost:6379'` |
307
+ | `tasks.connectionString` (pg-boss) | — | `databaseUrl` |
308
+
309
+ `NODE_ENV` is the sole exception — a Node/Express-wide runtime-mode signal, not an app secret — and is still read directly via `process.env['NODE_ENV']` in three places: `ignite()`'s cluster-in-production default, the dev-only dashboard toggle, and the `http-only` auth strategy's cookie `Secure` flag.