express-file-cluster 0.3.14 → 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 +204 -52
  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,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.5.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), 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.5.0 — Beta, Phase 2 complete + defineTable)
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()`, 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,308 @@
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. No relations/include yet (M3).
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
+ }
131
+ ```
132
+
133
+ ### Route file exports
134
+
135
+ ```ts
136
+ export const GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS = async (req, res) => {}
137
+ export const middlewares: RequestHandler[]
138
+ export const schema: RouteSchema // { params?, query?, body? } or keyed by method
139
+ export const meta: RouteMeta // dashboard docs, keyed by method
140
+
141
+ type Validator = { '~standard': { validate } } | { safeParse } // Standard Schema (zod ≥3.24, valibot, arktype)
142
+ interface RequestSchema { params?: Validator; query?: Validator; body?: Validator }
143
+ type RouteSchema = RequestSchema | Partial<Record<string, RequestSchema>>
144
+ // Failure → 400 { error: 'Validation failed', statusCode: 400, issues: [{ location, path, message }] }
145
+ // Success → parsed output replaces req.params/query/body. Runs AFTER file middlewares.
146
+ ```
147
+
148
+ `req.id` (request ID) and `req.log` (request logger) are added to Express's `Request` type.
149
+
150
+ ### Model types
151
+
152
+ ```ts
153
+ type PrimitiveFieldType = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'objectId';
154
+
155
+ interface FieldDefinition {
156
+ type: PrimitiveFieldType | 'array';
157
+ required?: boolean; unique?: boolean; index?: boolean;
158
+ default?: unknown; // literal, function, or DefaultOperator
159
+ enum?: readonly (string | number)[];
160
+ min?: number | Date; max?: number | Date; // number, date
161
+ minLength?: number; maxLength?: number; // string
162
+ match?: RegExp; // string
163
+ validate?: (v: unknown) => boolean | string | Promise<boolean | string>; // string = error message
164
+ ref?: string; // objectId / objectId arrays → populate
165
+ of?: PrimitiveFieldType | ModelSchema; // array item: primitive or embedded doc schema
166
+ fields?: ModelSchema; // typed embedded object (type: 'object')
167
+ sequence?: boolean | string; // auto-increment; Mongo efc_counters / PG SEQUENCE
168
+ }
169
+
170
+ // A field: FieldDefinition | nested ModelSchema (embedded object shorthand) | [ModelSchema] (array of embedded docs)
171
+ type SchemaField = FieldDefinition | ModelSchema | [ModelSchema] | readonly [ModelSchema];
172
+ interface ModelSchema { [field: string]: SchemaField }
173
+
174
+ type DefaultOperator = '$now' | '$uuid' | '$objectId' | '$timestamp' | '$shortId' | '$currentUser' | `$currentUser.${string}`;
175
+ // '$increment' is NOT an operator — use `sequence`.
176
+
177
+ interface ModelOptions {
178
+ timestamps?: boolean | { createdAt?: string | false; updatedAt?: string | false }; // default true
179
+ indexes?: { fields: Record<string, 1 | -1 | 'text'>; unique?: boolean; expireAfterSeconds?: number; name?: string }[];
180
+ collection?: string; // collection/table name, default lowercase plural of the model name
181
+ }
182
+
183
+ interface FindOptions { populate?: string | string[]; select?: string[]; sort?: Record<string, 1 | -1 | 'asc' | 'desc'>; limit?: number; skip?: number }
184
+
185
+ // Filter<T>: equality (array fields: contains), $eq $ne $gt $gte $lt $lte $in $nin $exists $regex,
186
+ // $and / $or, dotted paths ('address.city'), `id` for the primary key. Typed — no casts.
187
+ // Update<T>: plain fields (= $set) and/or $set (dotted ok) $inc $push ({$each}) $pull $unset.
188
+
189
+ // Inferred: record type = required/default/sequence fields non-optional, enum → literal union,
190
+ // 'date' → Date (nested too, both engines), 'objectId' → string, untyped object/array → unknown.
191
+ interface ModelCRUD<T, TCreate = Partial<T>> {
192
+ readonly name: string;
193
+ find(filter?: Filter<T>, options?: FindOptions): Promise<ModelRecord<T>[]>;
194
+ findById(id: string, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>; // malformed id → null
195
+ findOne(filter: Filter<T>, options?: ModelQueryOptions): Promise<ModelRecord<T> | null>;
196
+ exists(filter: Filter<T>): Promise<boolean>;
197
+ distinct(field: ScalarKeys<T>, filter?: Filter<T>): Promise<T[field][]>; // non-null, sorted; arrays/objects rejected
198
+ create(data: TCreate): Promise<ModelRecord<T>>;
199
+ createMany(data: TCreate[]): Promise<ModelRecord<T>[]>;
200
+ update(id: string, data: Update<T>): Promise<ModelRecord<T> | null>; // VALIDATES changed fields
201
+ updateOne(filter: Filter<T>, data: Update<T>): Promise<ModelRecord<T> | null>; // first match, one statement
202
+ updateMany(filter: Filter<T>, data: Update<T>): Promise<number>;
203
+ upsert(filter: Filter<T>, create: TCreate, update: Update<T>): Promise<ModelRecord<T>>; // filter NOT merged into create; 409 on create retried once as update
204
+ delete(id: string): Promise<void>;
205
+ deleteOne(filter: Filter<T>): Promise<ModelRecord<T> | null>; // returns the deleted record
206
+ deleteMany(filter: Filter<T>): Promise<number>;
207
+ count(filter?: Filter<T>): Promise<number>;
208
+ aggregate<R>(pipeline: object[]): Promise<R[]>; // MongoDB only — rejects on PostgreSQL
209
+ raw(): Promise<unknown>; // mongoose Model / Drizzle pgTable
210
+ sync(opts?: { dryRun?: boolean }): Promise<string[]>; // reconcile (auto on first use); returns changes / planned SQL
211
+ drop(): Promise<void>;
212
+ }
213
+ type ModelRecord<T> = T & { id: string };
214
+ // Errors: ModelValidationError (400, issues), duplicate unique → HttpError 409.
215
+
216
+ interface MigrationContext { db: unknown; engine: 'mongodb' | 'postgresql' } // passed to up/down/seed
217
+ ```
218
+
219
+ ---
220
+
221
+ ## `express-file-cluster/auth`
222
+
223
+ Source: `packages/core/src/auth/index.ts`
224
+
225
+ ```ts
226
+ // Set cookie (http-only strategy)
227
+ async function issueToken(res: Response, payload: Record<string, unknown>): Promise<void>
228
+
229
+ // Clear cookie (http-only strategy)
230
+ function revokeToken(res: Response): void
231
+
232
+ // Return token string (localStorage strategy)
233
+ async function signToken(payload: Record<string, unknown>): Promise<string>
234
+
235
+ // Need ignite({ cache }). Every signed token carries jti + iat + efc_iat (ms).
236
+ async function revokeSession(req: Request, res?: Response): Promise<void> // denylist this token until exp
237
+ async function revokeAllSessions(userId: string | number): Promise<void> // reject tokens issued before now
238
+
239
+ // Express middleware — verifies JWT, attaches payload to req.user.
240
+ // Dual-purpose: bare it's just auth; called with role names it returns a
241
+ // middleware that also enforces payload.role (403 if it doesn't match).
242
+ interface RequireAuth {
243
+ (req: Request, res: Response, next: NextFunction): void;
244
+ (...roles: string[]): RequestHandler;
245
+ }
246
+ const requireAuth: RequireAuth
247
+
248
+ // Internal — called by ignite()
249
+ function configureAuth(config: { secret: string; strategy: AuthStrategy; expiresIn: string; cookieDomain?: string }): void
250
+
251
+ // Reads the JWT payload requireAuth attached to the in-flight request, from
252
+ // anywhere in the async call chain (backed by AsyncLocalStorage — see context.ts).
253
+ // Returns undefined outside a request, or on a route that never ran requireAuth.
254
+ // Also what powers the '$currentUser'/'$currentUser.<key>' defineModel default codes.
255
+ function getCurrentUser(): Record<string, unknown> | undefined
256
+ ```
257
+
258
+ Cookie name: `efc_token`. Algorithm: HS256. Library: `jose`.
259
+
260
+ 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).
261
+
262
+ ---
263
+
264
+ ## `express-file-cluster/tasks`
265
+
266
+ Source: `packages/core/src/tasks/index.ts`
267
+
268
+ ```ts
269
+ function defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
270
+ function defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
271
+
272
+ // Rejects: backend not configured | unknown task | backend unreachable within tasks.enqueueTimeout
273
+ async function enqueue<T>(name: string, payload: T): Promise<void>
274
+
275
+ interface TaskOptions {
276
+ thread?: boolean; // run in worker_threads
277
+ retries?: number; // re-runs; up to retries + 1 attempts. Default 3
278
+ backoff?: 'fixed' | 'exponential'; // 1 s base. Default 'exponential'
279
+ concurrency?: number;
280
+ schedule?: string; // cron; scheduled runs get payload {}
281
+ timezone?: string; // IANA tz for schedule
282
+ }
283
+
284
+ // Internal
285
+ function registerTask(name: string, def: TaskDefinition): void
286
+ function setEnqueueImpl(impl: (name: string, payload: unknown) => Promise<void>): void
287
+ const taskRegistry: Map<string, TaskDefinition>
288
+ function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
289
+ ```
290
+
291
+ ---
292
+
293
+ ## `ignite()` does NOT read app config from `process.env` — `NODE_ENV` is the one exception
294
+
295
+ `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.
296
+
297
+ | Config field | Typically wired from | Fallback if unset |
298
+ |---|---|---|
299
+ | `port` | `process.env.PORT` | `3000` |
300
+ | `databaseUrl` | `process.env.DATABASE_URL` | none (no DB connects) |
301
+ | `jwtSecret` | `process.env.JWT_SECRET` | none (auth disabled) |
302
+ | `jwtExpiresIn` | `process.env.JWT_EXPIRES_IN` | `'7d'` |
303
+ | `cookieDomain` | `process.env.COOKIE_DOMAIN` | unset (host-only cookie) |
304
+ | `cors.origin` | `process.env.CORS_ORIGINS?.split(',')` | `true` (allow all) |
305
+ | `tasks.redisUrl` | `process.env.REDIS_URL` | `'redis://localhost:6379'` |
306
+ | `tasks.connectionString` (pg-boss) | — | `databaseUrl` |
307
+
308
+ `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.
@@ -0,0 +1,141 @@
1
+ # EFC — Auth Internals (Exact)
2
+
3
+ Source: `packages/core/src/auth/index.ts`
4
+
5
+ ---
6
+
7
+ ## Configuration (happens in Pre-Flight)
8
+
9
+ ```ts
10
+ // Called by ignite() at Pre-Flight step 2
11
+ configureAuth({
12
+ secret: jwtSecret,
13
+ strategy: authStrategy, // 'http-only' | 'localStorage'
14
+ expiresIn: JWT_EXPIRES_IN ?? '7d',
15
+ cookieDomain: COOKIE_DOMAIN, // optional
16
+ })
17
+ ```
18
+
19
+ `_config` is a module-level singleton. All auth functions throw `'[EFC] Auth not configured — pass jwtSecret to ignite()'` if called before `configureAuth`.
20
+
21
+ ---
22
+
23
+ ## `issueToken(res, payload)`
24
+
25
+ ```ts
26
+ // Signs JWT (HS256), sets HttpOnly cookie
27
+ const token = await new SignJWT(payload)
28
+ .setProtectedHeader({ alg: 'HS256' })
29
+ .setExpirationTime(expiresIn)
30
+ .sign(new TextEncoder().encode(secret))
31
+
32
+ res.cookie('efc_token', token, {
33
+ httpOnly: true,
34
+ secure: process.env['NODE_ENV'] === 'production',
35
+ sameSite: 'strict',
36
+ ...(cookieDomain && { domain: cookieDomain }),
37
+ })
38
+ ```
39
+
40
+ Cookie name: exactly `'efc_token'` (hardcoded).
41
+ `secure` is only set in production. In dev, the cookie is sent over HTTP.
42
+ **Does NOT set `path` explicitly** — defaults to `/`.
43
+ **Does NOT set `maxAge` or `expires`** — cookie is session-scoped (expires when browser closes), but the JWT itself has an expiry enforced server-side by `jwtVerify`.
44
+
45
+ ---
46
+
47
+ ## `revokeToken(res)`
48
+
49
+ ```ts
50
+ res.clearCookie('efc_token')
51
+ ```
52
+
53
+ That's the entire implementation. Clears the cookie. The JWT itself is not invalidated — use `revokeSession` for that.
54
+
55
+ ---
56
+
57
+ ## Session revocation (`revokeSession`, `revokeAllSessions`) — needs `cache`
58
+
59
+ Every signed token now carries `jti` (randomUUID), `iat`, and `efc_iat` (ms) — via the shared `sign()` used by
60
+ both `issueToken` and `signToken`.
61
+
62
+ - `revokeSession(req, res?)`: verifies the request's token, sets cache key `sess:jti:<jti>` with TTL = `exp - now`;
63
+ clears the cookie when `res` is given and strategy is http-only. Throws if no cache / cache unreachable.
64
+ - `revokeAllSessions(userId)`: sets `sess:user:<id>` = `Date.now()` with TTL = `jwtExpiresIn` in seconds.
65
+ - `requireAuth` (only when a cache is configured): after `jwtVerify`, rejects with 401 if `sess:jti:<jti>` exists,
66
+ or if `efc_iat` (fallback `iat*1000`) < the user's cutoff. User id = `payload.sub ?? payload.id`.
67
+ If the cache read throws → `cache.onRevocationCheckError`: `'reject'` (default) → **503**
68
+ `{ error: 'Service Unavailable', statusCode: 503 }`; `'allow'` → request passes. Logged at most every 30 s.
69
+
70
+ ---
71
+
72
+ ## `signToken(payload)`
73
+
74
+ ```ts
75
+ // Signs JWT, returns string (no cookie)
76
+ return await new SignJWT(payload)
77
+ .setProtectedHeader({ alg: 'HS256' })
78
+ .setExpirationTime(expiresIn)
79
+ .sign(new TextEncoder().encode(secret))
80
+ ```
81
+
82
+ No `res` argument. Token must be sent in the response body by the route handler.
83
+
84
+ ---
85
+
86
+ ## `requireAuth` — middleware internals
87
+
88
+ `requireAuth` is dual-purpose, dispatched at runtime on the first argument:
89
+
90
+ ```ts
91
+ // Bare — Express calls it as (req, res, next). First arg is an object → auth-only path.
92
+ export const middlewares = [requireAuth];
93
+
94
+ // Role-checked — called by user code with string args first, returns a new
95
+ // RequestHandler that Express later invokes as (req, res, next).
96
+ export const middlewares = [requireAuth('admin')]; // any of these roles
97
+ export const middlewares = [requireAuth('user', 'admin')]; // multiple allowed
98
+ ```
99
+
100
+ ```ts
101
+ // Strategy 'http-only': reads req.cookies.efc_token
102
+ // Strategy 'localStorage': reads Authorization header → strips 'Bearer '
103
+
104
+ if (!token) → res.status(401).json({ error: 'Unauthorized' }); return
105
+
106
+ const { payload } = await jwtVerify(token, new TextEncoder().encode(secret))
107
+
108
+ // only when called with role names:
109
+ if (roles.length > 0 && !roles.includes(payload.role)) →
110
+ res.status(403).json({ error: 'Forbidden' }); return
111
+
112
+ (req as any).user = payload // ← attaches to req.user
113
+ next()
114
+ ```
115
+
116
+ On any auth error (expired, invalid signature, malformed, missing token): catches and returns `{ error: 'Unauthorized' }` with status 401. A role mismatch returns `{ error: 'Forbidden' }` with status 403 instead. **Does NOT call next(err)** in either case — it handles the response itself and returns.
117
+
118
+ `req.user` is typed as `unknown` in the source. Cast to your payload type or use `(req as any).user`.
119
+
120
+ ---
121
+
122
+ ## JWT library
123
+
124
+ Uses `jose` (not `jsonwebtoken`). Key is UTF-8 encoded via `new TextEncoder().encode(secret)` before every call — no pre-computed key object is cached between requests.
125
+
126
+ ---
127
+
128
+ ## Token expiry
129
+
130
+ `expiresIn` is passed into `configureAuth` as a plain string by `ignite()` (`config.jwtExpiresIn ?? '7d'`) — `configureAuth` itself never touches `process.env`. All tokens issued in the same process lifetime use the same expiry value.
131
+
132
+ Format accepted by `jose`: `'15m'`, `'1h'`, `'7d'`, `'30d'`, integer seconds, etc.
133
+
134
+ ---
135
+
136
+ ## What auth does NOT do
137
+
138
+ - No refresh tokens in the framework itself (the scaffolder can generate an app-level `/auth/refresh` route backed by a DB-stored token — that's app code, not a core export).
139
+ - No revocation without a `cache` configured (then `revokeToken` just clears the cookie and a copied token stays valid until it expires). With a cache: `revokeSession` / `revokeAllSessions`.
140
+ - No CSRF token — relies on `SameSite: Strict` for http-only strategy.
141
+ - No multi-strategy per-route override — `authStrategy` is global, set once in `ignite()`.