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,145 @@
|
|
|
1
|
+
# Diagnostics — `efc routes` / `efc tasks` / `efc doctor`
|
|
2
|
+
|
|
3
|
+
The three diagnostic commands inspect your project without starting the server.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## `efc routes`
|
|
8
|
+
|
|
9
|
+
Prints the route table resolved from the `src/api/` directory.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
efc routes
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**Sample output:**
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Route Table
|
|
19
|
+
────────────────────────────────────────────────────────────
|
|
20
|
+
/health src/api/health.ts
|
|
21
|
+
/users src/api/users/index.ts
|
|
22
|
+
/posts/:slug/comments src/api/posts/[slug]/comments.ts
|
|
23
|
+
/users/:id src/api/users/[id].ts
|
|
24
|
+
────────────────────────────────────────────────────────────
|
|
25
|
+
|
|
26
|
+
4 route(s) found
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Static routes appear before dynamic routes (routes with `:param` segments), matching the registration order used at runtime.
|
|
30
|
+
|
|
31
|
+
**When to use:** after adding, renaming, or moving route files to verify the URL mapping is what you expect.
|
|
32
|
+
|
|
33
|
+
**Lookup order for the routes directory:** `src/api/` → `api/` → `dist/api/` (first that exists). This is a fixed convention — there is no `apiDir` config option.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## `efc tasks`
|
|
38
|
+
|
|
39
|
+
Lists the background tasks found in `src/tasks/`.
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
efc tasks
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
**Sample output:**
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
Background Tasks
|
|
49
|
+
|
|
50
|
+
SendEmail
|
|
51
|
+
ResizeImage
|
|
52
|
+
ProcessPayment
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Each name corresponds to a file basename without extension. That is the string to pass to `enqueue()`.
|
|
56
|
+
|
|
57
|
+
**Lookup order for the tasks directory:** `src/tasks/` → `tasks/` → `dist/tasks/` (first that exists). This is a fixed convention — there is no `tasksDir` config option.
|
|
58
|
+
|
|
59
|
+
### Dead-letter queue: `efc tasks failed | retry | purge`
|
|
60
|
+
|
|
61
|
+
Jobs that exhausted their retries stay in the backend's failed set. These commands connect to it directly, so they work against a running app from any shell:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
efc tasks failed # failed jobs + queue counts
|
|
65
|
+
efc tasks failed --name SendEmail -n 50
|
|
66
|
+
efc tasks failed --json # machine-readable
|
|
67
|
+
efc tasks retry 1842 1843 # re-queue (one more attempt each)
|
|
68
|
+
efc tasks retry --all
|
|
69
|
+
efc tasks purge 1842 # delete
|
|
70
|
+
efc tasks purge --all
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
Queue waiting=0 active=1 delayed=2 completed=318 failed=1
|
|
75
|
+
|
|
76
|
+
✗ SendEmail #1842 attempts=4 2026-10-10T12:00:01.000Z
|
|
77
|
+
SMTP connection refused
|
|
78
|
+
data: {"to":"ada@example.com","subject":"Welcome"}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
| Option | Meaning |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `--backend <bullmq\|pg-boss>` | Default: BullMQ if `REDIS_URL` is set, else pg-boss for a `postgres` `DATABASE_URL` |
|
|
84
|
+
| `--queue <name>` | `tasks.queue` from `ignite()` (default `efc`) |
|
|
85
|
+
| `--redis-url <url>` | BullMQ connection (default `REDIS_URL`, from the environment or `.env`) |
|
|
86
|
+
| `--database-url <url>` | pg-boss connection (default `DATABASE_URL`) |
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## `efc doctor`
|
|
91
|
+
|
|
92
|
+
Validates your project setup and reports any problems.
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
efc doctor
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Checks performed:**
|
|
99
|
+
|
|
100
|
+
| Check | What it validates |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `package.json` exists | Project root has a `package.json` |
|
|
103
|
+
| `tsconfig.json` exists | TypeScript config is present; hint: `tsc --init` |
|
|
104
|
+
| `src/api` exists | Route directory is present |
|
|
105
|
+
| `DATABASE_URL` set | `process.env.DATABASE_URL` is non-empty |
|
|
106
|
+
| `JWT_SECRET` set | `process.env.JWT_SECRET` is non-empty |
|
|
107
|
+
|
|
108
|
+
**Sample passing output:**
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
EFC Doctor
|
|
112
|
+
|
|
113
|
+
✓ package.json exists
|
|
114
|
+
✓ tsconfig.json exists
|
|
115
|
+
✓ src/api directory exists
|
|
116
|
+
✓ DATABASE_URL set
|
|
117
|
+
✓ JWT_SECRET set
|
|
118
|
+
|
|
119
|
+
All checks passed!
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
**Sample failing output:**
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
EFC Doctor
|
|
126
|
+
|
|
127
|
+
✓ package.json exists
|
|
128
|
+
✓ tsconfig.json exists
|
|
129
|
+
✓ src/api directory exists
|
|
130
|
+
✗ DATABASE_URL set
|
|
131
|
+
→ Add DATABASE_URL to .env
|
|
132
|
+
✗ JWT_SECRET set
|
|
133
|
+
→ Add JWT_SECRET to .env (generate: openssl rand -hex 64)
|
|
134
|
+
|
|
135
|
+
Some checks failed. Fix the issues above.
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Exits with code `1` if any check fails.
|
|
139
|
+
|
|
140
|
+
**Note:** `efc doctor` reads `DATABASE_URL` and `JWT_SECRET` from `process.env`. In development, source `.env` before running the command — or run it via `npm run dev` which loads `.env` automatically.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
# Quick way to run doctor with .env loaded:
|
|
144
|
+
source .env && efc doctor
|
|
145
|
+
```
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# `efc generate`
|
|
2
|
+
|
|
3
|
+
Scaffold boilerplate files without hand-writing them. All generators write TypeScript files and refuse to overwrite existing files.
|
|
4
|
+
|
|
5
|
+
The command also accepts the alias `efc g`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## `efc generate route <routePath>`
|
|
10
|
+
|
|
11
|
+
Creates a route module at `src/api/<routePath>.ts`.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
efc generate route users
|
|
15
|
+
efc generate route users/[id]
|
|
16
|
+
efc generate route posts/[slug]/comments
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The generated file exports `GET` and `POST` stubs:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// src/api/users/[id].ts (after: efc generate route users/[id])
|
|
23
|
+
import type { Request, Response } from 'express';
|
|
24
|
+
|
|
25
|
+
export const GET = async (req: Request, res: Response) => {
|
|
26
|
+
res.json({ message: 'OK' });
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
export const POST = async (req: Request, res: Response) => {
|
|
30
|
+
res.status(201).json({ message: 'Created' });
|
|
31
|
+
};
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The path argument is relative to `src/api/`. Parent directories are created automatically.
|
|
35
|
+
|
|
36
|
+
| Command | Output file | Route URL |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| `efc generate route health` | `src/api/health.ts` | `/health` |
|
|
39
|
+
| `efc generate route users/[id]` | `src/api/users/[id].ts` | `/users/:id` |
|
|
40
|
+
| `efc generate route posts/[slug]/comments` | `src/api/posts/[slug]/comments.ts` | `/posts/:slug/comments` |
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## `efc generate task <name>`
|
|
45
|
+
|
|
46
|
+
Creates a task module at `src/tasks/<name>.ts`.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
efc generate task SendEmail
|
|
50
|
+
efc generate task ResizeImage
|
|
51
|
+
efc generate task ProcessPayment
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The generated file exports a typed `defineTask` skeleton:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
// src/tasks/SendEmail.ts (after: efc generate task SendEmail)
|
|
58
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
59
|
+
|
|
60
|
+
interface SendEmailPayload {
|
|
61
|
+
// TODO: define payload fields
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export default defineTask<SendEmailPayload>(async (payload) => {
|
|
65
|
+
// TODO: implement task logic
|
|
66
|
+
console.log('[Task:SendEmail]', payload);
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The task is registered automatically when the app starts — no extra wiring required.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## `efc generate middleware <name>`
|
|
75
|
+
|
|
76
|
+
Creates a middleware module at `src/middlewares/<name>.ts`.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
efc generate middleware authorize
|
|
80
|
+
efc generate middleware validateBody
|
|
81
|
+
efc generate middleware requestLogger
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The generated file exports a plain Express `RequestHandler`:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
// src/middlewares/authorize.ts (after: efc generate middleware authorize)
|
|
88
|
+
import type { Request, Response, NextFunction } from 'express';
|
|
89
|
+
|
|
90
|
+
export function authorize(req: Request, res: Response, next: NextFunction): void {
|
|
91
|
+
// TODO: implement middleware logic
|
|
92
|
+
next();
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## `efc generate migration <name>`
|
|
99
|
+
|
|
100
|
+
Creates `src/migrations/<UTC timestamp>_<snake_name>.ts` (`.js` without a `tsconfig.json`) with `up` / `down` stubs. Run it with `efc db migrate`. See [Migrations & Seeds](../guides/migrations.md).
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
efc generate migration AddOrders # → src/migrations/20261010120000_add_orders.ts
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## `efc generate seed <name>`
|
|
109
|
+
|
|
110
|
+
Creates `src/seeds/<snake_name>.ts` exporting a default seed function. Run it with `efc db seed` or `efc db seed <snake_name>`.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Error: file already exists
|
|
115
|
+
|
|
116
|
+
If the target file already exists, the generator prints an error and exits with code 1 — it never overwrites existing files:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
File already exists: src/api/users/[id].ts
|
|
120
|
+
```
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# CLI Reference
|
|
2
|
+
|
|
3
|
+
EFC ships a single `efc` binary installed as a dev dependency when you use `create-efc-app`. The scaffolder (`npx create-efc-app`) is a separate one-time tool.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
The `efc` binary is automatically available after scaffolding. For a manual install:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install --save-dev express-file-cluster
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**Global vs project install.** `create-efc-app` also installs `efc` globally for convenience. Run inside a project, a global `efc` hands every command to the project's own `node_modules/express-file-cluster` — so commands always use the project's version, its database drivers and a single copy of the framework. Outside a project, the global install runs itself.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Command overview
|
|
20
|
+
|
|
21
|
+
| Command | Description |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `efc start dev` | Development server — hot-reload, single process |
|
|
24
|
+
| `efc start prod` | Production server — runs `dist/` with clustering |
|
|
25
|
+
| `efc build prod` | Type-check + transpile `src/` to `dist/src/` |
|
|
26
|
+
| `efc run tests` | Run tests via Vitest |
|
|
27
|
+
| `efc generate route <path>` | Scaffold a route file |
|
|
28
|
+
| `efc generate task <name>` | Scaffold a task file |
|
|
29
|
+
| `efc generate middleware <name>` | Scaffold a middleware file |
|
|
30
|
+
| `efc generate migration <name>` | Scaffold a timestamped migration |
|
|
31
|
+
| `efc generate seed <name>` | Scaffold a seed script |
|
|
32
|
+
| `efc db migrate \| rollback \| status` | Run, revert and inspect migrations |
|
|
33
|
+
| `efc db seed [name]` | Run seed scripts |
|
|
34
|
+
| `efc db studio` | Read-only database browser on 127.0.0.1 |
|
|
35
|
+
| `efc routes` | Print the resolved route table |
|
|
36
|
+
| `efc tasks` | List registered background tasks |
|
|
37
|
+
| `efc tasks failed \| retry \| purge` | Inspect and act on dead-lettered jobs |
|
|
38
|
+
| `efc doctor` | Validate config, env vars, and project setup |
|
|
39
|
+
| `efc --version` | Print the installed version |
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Detailed pages
|
|
44
|
+
|
|
45
|
+
- [start / build / run](./start.md) — Lifecycle commands
|
|
46
|
+
- [generate](./generate.md) — Code generation
|
|
47
|
+
- [db](./db.md) — migrations, seeds, studio
|
|
48
|
+
- [diagnostics](./diagnostics.md) — `routes`, `tasks` (incl. dead letters), `doctor`
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# `efc start` / `efc build` / `efc run`
|
|
2
|
+
|
|
3
|
+
## `efc start dev`
|
|
4
|
+
|
|
5
|
+
Starts the development server.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
efc start dev
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
**Behaviour:**
|
|
12
|
+
|
|
13
|
+
- Reads `.env` from the project root and injects variables into `process.env`. Variables already present in the environment take precedence.
|
|
14
|
+
- Defaults `NODE_ENV` to `'development'`. A `NODE_ENV` value in `.env` or in the parent environment overrides this default.
|
|
15
|
+
- Locates the entry point by checking these paths in order:
|
|
16
|
+
1. `src/index.ts`
|
|
17
|
+
2. `index.ts`
|
|
18
|
+
3. `src/index.js`
|
|
19
|
+
4. `index.js`
|
|
20
|
+
- Launches the entry point via `tsx watch --include src <entry>` for hot-reload on every file change inside `src/`.
|
|
21
|
+
- **Clustering is off in development** — `ignite()` defaults `cluster` to `false` when `NODE_ENV !== 'production'`. This gives fast restarts and clean stack traces.
|
|
22
|
+
|
|
23
|
+
**Requires:** `tsx` installed (either as a project dependency in `node_modules/.bin/tsx`, or globally on `PATH`).
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## `efc start prod`
|
|
28
|
+
|
|
29
|
+
Starts the production server from compiled output.
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
efc start prod
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Behaviour:**
|
|
36
|
+
|
|
37
|
+
- Looks for `dist/src/index.js` (the `efc build prod` layout), then `dist/index.js` (a custom `tsup.config`). If neither exists, prints an error instructing you to run `efc build prod` first.
|
|
38
|
+
- Sets `NODE_ENV=production`.
|
|
39
|
+
- Does **not** read `.env` — secrets must come from the platform's environment.
|
|
40
|
+
- Spawns `node dist/src/index.js`.
|
|
41
|
+
- Forwards `SIGTERM`/`SIGINT` to the server so `gracefulShutdown()` runs, and exits with the server's exit code.
|
|
42
|
+
- With `NODE_ENV=production`, `ignite()` defaults `cluster` to `true` and forks `os.cpus().length` workers. When the primary receives `SIGTERM` it relays it to every worker, waits for them to drain, then exits.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## `efc build prod`
|
|
47
|
+
|
|
48
|
+
Compiles the project to JavaScript in `dist/`.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
efc build prod
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Behaviour:**
|
|
55
|
+
|
|
56
|
+
- Type-checks with `tsc --noEmit` when a `tsconfig.json` exists (skipped for JavaScript projects).
|
|
57
|
+
- Transpiles **every** file under `src/` plus `efc.config.ts` with `tsup`, one output file per source file, keeping the directory tree:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
src/index.ts → dist/src/index.js
|
|
61
|
+
src/api/users/[id].ts → dist/src/api/users/[id].js
|
|
62
|
+
src/tasks/SendEmail.ts → dist/src/tasks/SendEmail.js
|
|
63
|
+
efc.config.ts → dist/efc.config.js
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Files are not bundled: routes and tasks are discovered by scanning the filesystem at runtime, so each one must exist in `dist/` as its own file. Test files (`*.test.*`, `__tests__/`) are skipped.
|
|
67
|
+
- Output format follows `package.json` `"type"` — ESM for `"module"`, CommonJS otherwise.
|
|
68
|
+
- If the project has its own `tsup.config.*`, that config is used instead.
|
|
69
|
+
|
|
70
|
+
**Requires:** `tsup` installed as a dev dependency.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## `efc run tests`
|
|
75
|
+
|
|
76
|
+
Runs the test suite.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
efc run tests
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Behaviour:**
|
|
83
|
+
|
|
84
|
+
- Invokes Vitest.
|
|
85
|
+
- Pass Vitest flags through directly:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
efc run tests --watch
|
|
89
|
+
efc run tests --coverage
|
|
90
|
+
efc run tests --reporter=verbose
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**Requires:** `vitest` installed as a dev dependency.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## `package.json` lifecycle scripts
|
|
98
|
+
|
|
99
|
+
The scaffolder wires these scripts automatically:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"scripts": {
|
|
104
|
+
"dev": "efc start dev",
|
|
105
|
+
"build": "efc build prod",
|
|
106
|
+
"start": "efc start prod",
|
|
107
|
+
"test": "efc run tests"
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Use `npm run dev`, `npm run build`, `npm start`, and `npm test` as shorthand.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Repository layout
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
packages/
|
|
7
|
+
core/ → express-file-cluster (the framework)
|
|
8
|
+
create-efc-app/ → interactive scaffolder CLI
|
|
9
|
+
client/ → marketing site (static HTML/JS)
|
|
10
|
+
Skills/efc/ → reference cards for the /efc assistant skill
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Getting started
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
git clone https://github.com/your-org/efc.js.git
|
|
19
|
+
cd efc.js
|
|
20
|
+
|
|
21
|
+
# Install all workspace dependencies
|
|
22
|
+
npm install
|
|
23
|
+
|
|
24
|
+
# Build all packages
|
|
25
|
+
npm run build
|
|
26
|
+
|
|
27
|
+
# Run the test suite
|
|
28
|
+
npm test
|
|
29
|
+
|
|
30
|
+
# Type-check
|
|
31
|
+
npm run typecheck
|
|
32
|
+
|
|
33
|
+
# Lint
|
|
34
|
+
npm run lint
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Integration and end-to-end tests
|
|
40
|
+
|
|
41
|
+
Integration tests skip themselves when a service isn't reachable, so `npm test` works with nothing running — but for full coverage start MongoDB (plus a single-node replica set for transactions), Redis and PostgreSQL, and point the tests at them:
|
|
42
|
+
|
|
43
|
+
| Variable | Default |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `EFC_TEST_MONGO_URL` | `mongodb://127.0.0.1:27017/...` |
|
|
46
|
+
| `EFC_TEST_MONGO_RS_URL` | `mongodb://127.0.0.1:27018/...?replicaSet=rs0&directConnection=true` |
|
|
47
|
+
| `EFC_TEST_REDIS_URL` | `redis://127.0.0.1:6379/15` |
|
|
48
|
+
| `EFC_TEST_PG_URL` | `postgres://postgres@127.0.0.1:5433/efc_test` |
|
|
49
|
+
|
|
50
|
+
The cluster and CLI tests run the built `dist/`, so `npm run build` first.
|
|
51
|
+
|
|
52
|
+
The scaffolder end-to-end suite generates real projects (MongoDB + BullMQ, PostgreSQL + pg-boss, and a JavaScript project), installs them against a packed tarball of `packages/core`, then migrates, runs the dev server, builds, boots and exercises auth over HTTP:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm run build
|
|
56
|
+
EFC_E2E=1 npx vitest run --project create-efc-app e2e
|
|
57
|
+
EFC_E2E=1 EFC_E2E_KEEP=1 npx vitest run --project create-efc-app e2e # keep the generated apps to inspect
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Branch naming
|
|
63
|
+
|
|
64
|
+
| Type | Pattern | Example |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| Feature | `feat/<topic>` | `feat/postgresql-adapter` |
|
|
67
|
+
| Bug fix | `fix/<topic>` | `fix/route-sort-order` |
|
|
68
|
+
| Documentation | `docs/<topic>` | `docs/task-guide` |
|
|
69
|
+
| Chore | `chore/<topic>` | `chore/bump-bullmq` |
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Commit messages
|
|
74
|
+
|
|
75
|
+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
feat(router): support catch-all wildcard routes
|
|
79
|
+
fix(cluster): prevent infinite respawn loop on startup crash
|
|
80
|
+
docs(auth): add localStorage strategy example
|
|
81
|
+
chore(deps): upgrade jose to v5
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Pull requests
|
|
87
|
+
|
|
88
|
+
Every PR must:
|
|
89
|
+
|
|
90
|
+
- Include tests for changed behaviour (unit or integration via Vitest).
|
|
91
|
+
- Pass `npm test`, `npm run lint`, and `npm run typecheck` in CI.
|
|
92
|
+
- Include a changelog entry under `Unreleased` in `CHANGELOG.md`.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Package architecture
|
|
97
|
+
|
|
98
|
+
### `packages/core`
|
|
99
|
+
|
|
100
|
+
The framework package published as `express-file-cluster`. Sub-path exports:
|
|
101
|
+
|
|
102
|
+
| Import | Source |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `express-file-cluster` | `src/index.ts` — `ignite`, `gracefulShutdown`, `HttpError`, `compose`, `db`, `defineModel` |
|
|
105
|
+
| `express-file-cluster/auth` | `src/auth/index.ts` — `issueToken`, `revokeToken`, `revokeSession`, `revokeAllSessions`, `signToken`, `requireAuth`, `getCurrentUser` |
|
|
106
|
+
| `express-file-cluster/tasks` | `src/tasks/index.ts` — `defineTask`, `enqueue` |
|
|
107
|
+
| `express-file-cluster/cli` | `src/cli/index.ts` — the `efc` binary |
|
|
108
|
+
|
|
109
|
+
### `packages/create-efc-app`
|
|
110
|
+
|
|
111
|
+
Interactive scaffolder published as `create-efc-app`. Invoked with `npx create-efc-app <name>`. Prompts the user and writes the project tree using the templates in `src/scaffold.ts`.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Roadmap
|
|
116
|
+
|
|
117
|
+
| Phase | Target | Focus |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| **1** | Done | Core MVP — router, clustering, auth, DB, tasks, CLI |
|
|
120
|
+
| **2** | Done | Beta — PostgreSQL, pg-boss, request validation, structured logging, cron tasks, catch-all routes, migrations, `defineModel` upgrades |
|
|
121
|
+
| **3** | Q1 2027 | Stable v1.0 — plugins, WebSockets, OpenAPI, OpenTelemetry, testing utilities |
|
|
122
|
+
| **4** | 2027+ | Edge/serverless, gRPC, GraphQL |
|
|
123
|
+
|
|
124
|
+
### Bug fix SLA
|
|
125
|
+
|
|
126
|
+
| Severity | SLA | Example |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| **P0 — Critical** | Patch within 48 h | Data loss, auth bypass, crash on startup |
|
|
129
|
+
| **P1 — High** | Patch within 1 week | Route not resolving, worker not respawning, task silently dropped |
|
|
130
|
+
| **P2 — Medium** | Next minor release | Wrong TypeScript types, misleading error message |
|
|
131
|
+
| **P3 — Low** | Best effort | Cosmetic CLI issues, doc typos |
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Influencing the roadmap
|
|
136
|
+
|
|
137
|
+
1. **Open a GitHub Discussion** — propose a feature or share a use case.
|
|
138
|
+
2. **Upvote issues** — 👍 reactions influence prioritisation.
|
|
139
|
+
3. **Submit a PR** — the fastest path from idea to shipping.
|