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,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.
|