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.
- package/README.md +204 -52
- 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-3VWD2ZED.js +60 -0
- package/dist/chunk-3VWD2ZED.js.map +1 -0
- package/dist/chunk-47K2532L.cjs +196 -0
- package/dist/chunk-47K2532L.cjs.map +1 -0
- package/dist/chunk-5PDAWMGF.js +438 -0
- package/dist/chunk-5PDAWMGF.js.map +1 -0
- package/dist/chunk-7YEX4MQV.cjs +38 -0
- package/dist/chunk-7YEX4MQV.cjs.map +1 -0
- package/dist/chunk-ALBDM5R3.cjs +60 -0
- package/dist/chunk-ALBDM5R3.cjs.map +1 -0
- package/dist/chunk-JJJJTACK.js +196 -0
- package/dist/chunk-JJJJTACK.js.map +1 -0
- package/dist/chunk-LJNSJFOL.js +38 -0
- package/dist/chunk-LJNSJFOL.js.map +1 -0
- package/dist/chunk-M7MUPWCE.js +116 -0
- package/dist/chunk-M7MUPWCE.js.map +1 -0
- package/dist/chunk-PMF4GMHD.js +154 -0
- package/dist/chunk-PMF4GMHD.js.map +1 -0
- package/dist/chunk-QTRGJ2EN.cjs +2635 -0
- package/dist/chunk-QTRGJ2EN.cjs.map +1 -0
- package/dist/chunk-RSBW2B3D.cjs +126 -0
- package/dist/chunk-RSBW2B3D.cjs.map +1 -0
- package/dist/chunk-RTFJ32T5.js +2635 -0
- package/dist/chunk-RTFJ32T5.js.map +1 -0
- package/dist/chunk-SFVEQ2T5.cjs +438 -0
- package/dist/chunk-SFVEQ2T5.cjs.map +1 -0
- package/dist/chunk-SZT36SGB.cjs +154 -0
- package/dist/chunk-SZT36SGB.cjs.map +1 -0
- package/dist/chunk-TI24L4XE.cjs.map +1 -1
- package/dist/chunk-ULQXD4YZ.cjs +116 -0
- package/dist/chunk-ULQXD4YZ.cjs.map +1 -0
- package/dist/chunk-VYHJX54R.js +126 -0
- package/dist/chunk-VYHJX54R.js.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 +323 -0
- package/dist/docs/api-reference/table.md +250 -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 +70 -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 +308 -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 +289 -391
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +472 -7
- package/dist/index.d.ts +472 -7
- package/dist/index.js +283 -385
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-3E6ATY42.cjs +14 -0
- package/dist/pgboss-backend-3E6ATY42.cjs.map +1 -0
- package/dist/pgboss-backend-UUJOVEYK.js +14 -0
- package/dist/pgboss-backend-UUJOVEYK.js.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-DJCPAsM4.d.cts +541 -0
- package/dist/types-DJCPAsM4.d.ts +541 -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,140 @@
|
|
|
1
|
+
# Tasks — API Reference
|
|
2
|
+
|
|
3
|
+
Task functions are exported from the `tasks` sub-path:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { defineTask, enqueue } from 'express-file-cluster/tasks';
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## `defineTask(handler)` / `defineTask(options, handler)`
|
|
12
|
+
|
|
13
|
+
Creates a `TaskDefinition`. The file's default export must be a `TaskDefinition` for EFC to register the task.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// Overloads
|
|
17
|
+
defineTask<T>(handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
18
|
+
defineTask<T>(options: TaskOptions, handler: (payload: T) => Promise<void>): TaskDefinition<T>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Minimal task
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
25
|
+
|
|
26
|
+
export default defineTask<{ userId: string }>(async ({ userId }) => {
|
|
27
|
+
await sendWelcomeEmail(userId);
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Task with options
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { defineTask } from 'express-file-cluster/tasks';
|
|
35
|
+
|
|
36
|
+
export default defineTask<{ key: string; width: number }>(
|
|
37
|
+
{
|
|
38
|
+
thread: true, // run in worker_threads
|
|
39
|
+
retries: 5,
|
|
40
|
+
backoff: 'exponential',
|
|
41
|
+
concurrency: 2,
|
|
42
|
+
},
|
|
43
|
+
async ({ key, width }) => {
|
|
44
|
+
await resizeImage(key, width);
|
|
45
|
+
},
|
|
46
|
+
);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## `TaskOptions`
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
interface TaskOptions {
|
|
55
|
+
thread?: boolean;
|
|
56
|
+
retries?: number;
|
|
57
|
+
backoff?: 'fixed' | 'exponential';
|
|
58
|
+
concurrency?: number;
|
|
59
|
+
schedule?: string;
|
|
60
|
+
timezone?: string;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
| Option | Type | Default | Description |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| `thread` | `boolean` | `false` | Run handler in a `worker_threads` thread. Use for CPU-bound work. |
|
|
67
|
+
| `retries` | `number` | `3` | Re-runs after the first failed attempt, so a job runs at most `retries + 1` times before it is dead-lettered. |
|
|
68
|
+
| `backoff` | `'fixed' \| 'exponential'` | `'exponential'` | Retry delay strategy. Exponential starts at 1 second and doubles. |
|
|
69
|
+
| `concurrency` | `number` | `tasks.concurrency` from `ignite()` | Maximum parallel jobs of this type. |
|
|
70
|
+
| `schedule` | `string` | — | Cron pattern, e.g. `'*/15 * * * *'`. Scheduled runs receive `{}` as the payload. |
|
|
71
|
+
| `timezone` | `string` | server time | IANA timezone for `schedule`. |
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## `enqueue(name, payload)`
|
|
76
|
+
|
|
77
|
+
Adds a job to the task queue.
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
async function enqueue<T>(name: string, payload: T): Promise<void>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
| Parameter | Type | Description |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| `name` | `string` | Task name — the filename without extension (e.g. `'SendEmail'`) |
|
|
86
|
+
| `payload` | `T` | Data passed to the task handler |
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { enqueue } from 'express-file-cluster/tasks';
|
|
90
|
+
|
|
91
|
+
await enqueue('SendEmail', {
|
|
92
|
+
to: 'alice@example.com',
|
|
93
|
+
subject: 'Welcome!',
|
|
94
|
+
body: 'Thanks for signing up.',
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`enqueue` rejects if:
|
|
99
|
+
|
|
100
|
+
- **Task backend not initialised** — `tasks` was not configured in `ignite()`.
|
|
101
|
+
- **Unknown task name** — no file with that basename exists in `src/tasks/`.
|
|
102
|
+
- **The queue backend is unreachable** — Redis (BullMQ) or PostgreSQL (pg-boss) didn't accept the job within `tasks.enqueueTimeout` (default 5000 ms). It never waits indefinitely, and a rejected job is not queued later behind your back, so it is safe to retry or return a 503.
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
try {
|
|
106
|
+
await enqueue('SendEmail', payload);
|
|
107
|
+
} catch (err) {
|
|
108
|
+
throw new HttpError(503, 'Queue unavailable, try again shortly');
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## `TaskDefinition<T>`
|
|
115
|
+
|
|
116
|
+
The shape returned by `defineTask` and stored in the registry:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
interface TaskDefinition<TPayload = unknown> {
|
|
120
|
+
handler: (payload: TPayload) => Promise<void>;
|
|
121
|
+
options: TaskOptions;
|
|
122
|
+
name: string; // set by scanTasks — empty string from defineTask itself
|
|
123
|
+
filePath?: string; // set by scanTasks — used by the thread runner
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
You do not construct `TaskDefinition` directly — always use `defineTask`.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Task name resolution
|
|
132
|
+
|
|
133
|
+
The task name is the **file's basename without extension**:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
src/tasks/SendEmail.ts → "SendEmail"
|
|
137
|
+
src/tasks/ResizeImage.ts → "ResizeImage"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The name is case-sensitive. `enqueue('sendEmail', ...)` will not match `SendEmail.ts`.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# `efc db`
|
|
2
|
+
|
|
3
|
+
Database migrations, seeds and studio. Works on MongoDB and PostgreSQL — the engine follows the `DATABASE_URL` scheme. Full guide: [Migrations & Seeds](../guides/migrations.md).
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
efc db sync [--dry-run] # reconcile tables/collections + indexes with src/model(s)/
|
|
7
|
+
efc db migrate # run pending migrations (one new batch)
|
|
8
|
+
efc db rollback [--steps 2] # revert the last batch(es)
|
|
9
|
+
efc db status # applied vs pending
|
|
10
|
+
efc db seed [name] # run all seeds, or one
|
|
11
|
+
efc db studio [--port 4983] # read-only browser on 127.0.0.1 (rows + table structure)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Common options
|
|
15
|
+
|
|
16
|
+
| Option | Meaning |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `--database-url <url>` | Override `DATABASE_URL` (otherwise read from the environment, then `.env`) |
|
|
19
|
+
| `--dist` | Load compiled files from `dist/src/` even when `tsx` is installed |
|
|
20
|
+
|
|
21
|
+
## Where files load from
|
|
22
|
+
|
|
23
|
+
| Situation | Runs | From |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `tsx` installed (dev) | `tsx` | `src/migrations`, `src/seeds` |
|
|
26
|
+
| No `tsx` (production image) | `node` | `dist/src/migrations`, `dist/src/seeds` |
|
|
27
|
+
| JavaScript project | `node` | `src/` |
|
|
28
|
+
|
|
29
|
+
## Exit codes
|
|
30
|
+
|
|
31
|
+
`0` on success, `1` on any failure (connection, a throwing migration/seed, missing `down()` on rollback). Set `EFC_DEBUG=1` for stack traces.
|
|
32
|
+
|
|
33
|
+
## Scaffolding
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
efc generate migration <name> # src/migrations/<UTC timestamp>_<name>.ts
|
|
37
|
+
efc generate seed <name> # src/seeds/<name>.ts
|
|
38
|
+
```
|
|
@@ -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.
|