express-file-cluster 0.3.14 → 0.3.15
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 +163 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
EFC is an opinionated backend framework built on Express. Drop files in `src/api/` and they become routes. Every CPU core serves traffic automatically. Heavy work goes to a queue-backed task subsystem so requests stay fast.
|
|
6
6
|
|
|
7
|
-
> **Status: v0.3.
|
|
7
|
+
> **Status: v0.3.14 (Beta).** The router, clustering, auth, MongoDB adapter, and BullMQ task queue backend are all implemented.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -18,6 +18,8 @@ Most Express apps grow the same way: a working prototype, then a maze of `router
|
|
|
18
18
|
| Single-threaded Node under load | Auto-detected CPU count → worker processes |
|
|
19
19
|
| Blocking work on the request path | `enqueue()` ships it to a queue; respond immediately |
|
|
20
20
|
| Wiring auth, DB, and middleware by hand | `ignite()` — one call bootstraps everything |
|
|
21
|
+
| Scattered model definitions | `defineModel()` — typed CRUD with zero ORM ceremony |
|
|
22
|
+
| Per-request user context in nested calls | `AsyncLocalStorage`-backed `getCurrentUser()` |
|
|
21
23
|
|
|
22
24
|
---
|
|
23
25
|
|
|
@@ -49,7 +51,7 @@ my-api/
|
|
|
49
51
|
│ ├── tasks/ # Background jobs
|
|
50
52
|
│ │ ├── SendEmail.ts
|
|
51
53
|
│ │ └── ResizeImage.ts
|
|
52
|
-
│ ├──
|
|
54
|
+
│ ├── model/ # Engine-agnostic models
|
|
53
55
|
│ │ └── User.ts
|
|
54
56
|
│ └── index.ts # Framework entry point
|
|
55
57
|
├── efc.config.ts
|
|
@@ -57,6 +59,8 @@ my-api/
|
|
|
57
59
|
└── .env.example
|
|
58
60
|
```
|
|
59
61
|
|
|
62
|
+
`src/api` and `src/tasks` are resolved by convention — they are **not** `ignite()` options. EFC probes `src/api`/`src/tasks`, then `<cwd>/api`/`<cwd>/tasks`, then `dist/api`/`dist/tasks`. You only need a different layout if you're doing something unusual.
|
|
63
|
+
|
|
60
64
|
Routing rules:
|
|
61
65
|
|
|
62
66
|
| File | URL |
|
|
@@ -75,7 +79,7 @@ Export uppercase HTTP method names. Anything not exported returns **405 Method N
|
|
|
75
79
|
```ts
|
|
76
80
|
// src/api/users/index.ts
|
|
77
81
|
import type { Request, Response } from 'express';
|
|
78
|
-
import { User } from '../../
|
|
82
|
+
import { User } from '../../model/User.js';
|
|
79
83
|
|
|
80
84
|
export const GET = async (req: Request, res: Response) => {
|
|
81
85
|
const users = await User.find();
|
|
@@ -91,7 +95,7 @@ export const POST = async (req: Request, res: Response) => {
|
|
|
91
95
|
```ts
|
|
92
96
|
// src/api/users/[id].ts
|
|
93
97
|
import type { Request, Response } from 'express';
|
|
94
|
-
import { User } from '../../
|
|
98
|
+
import { User } from '../../model/User.js';
|
|
95
99
|
import { HttpError } from 'express-file-cluster';
|
|
96
100
|
|
|
97
101
|
export const GET = async (req: Request, res: Response) => {
|
|
@@ -114,7 +118,6 @@ Three tiers, each with a clear scope:
|
|
|
114
118
|
|
|
115
119
|
```ts
|
|
116
120
|
// 1. Global — applies to every request
|
|
117
|
-
// CORS is built-in — configure it via CORS_ORIGINS in .env, not a separate package
|
|
118
121
|
ignite({ globalMiddlewares: [rateLimiter()] });
|
|
119
122
|
|
|
120
123
|
// 2. Route-level — applies to every handler in this file
|
|
@@ -131,6 +134,94 @@ export const POST = compose(
|
|
|
131
134
|
|
|
132
135
|
---
|
|
133
136
|
|
|
137
|
+
## Database
|
|
138
|
+
|
|
139
|
+
### `defineModel(name, schema, options?)`
|
|
140
|
+
|
|
141
|
+
Declare a typed model with a schema. EFC compiles it to a Mongoose model and wraps it in a clean CRUD surface.
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
// src/model/User.ts
|
|
145
|
+
import { defineModel } from 'express-file-cluster';
|
|
146
|
+
|
|
147
|
+
interface UserDocument {
|
|
148
|
+
name: string;
|
|
149
|
+
email: string;
|
|
150
|
+
role: 'admin' | 'user';
|
|
151
|
+
verifyToken: string;
|
|
152
|
+
createdAt?: Date;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export const User = defineModel<UserDocument>('User', {
|
|
156
|
+
name: { type: 'string', required: true },
|
|
157
|
+
email: { type: 'string', required: true, unique: true },
|
|
158
|
+
role: { type: 'string', enum: ['admin', 'user'], default: 'user' },
|
|
159
|
+
verifyToken: { type: 'string', default: '$uuid' }, // fresh UUID per document
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Schema default operator codes
|
|
164
|
+
|
|
165
|
+
Instead of a literal or a raw function, `default` also accepts a sentinel string — resolved to a fresh per-document value at schema-compile time, never baked in once:
|
|
166
|
+
|
|
167
|
+
| Code | Resolves to |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `'$now'` | `new Date()` |
|
|
170
|
+
| `'$uuid'` | `crypto.randomUUID()` |
|
|
171
|
+
| `'$objectId'` | fresh Mongoose `ObjectId` |
|
|
172
|
+
| `'$timestamp'` | `Date.now()` (number) |
|
|
173
|
+
| `'$shortId'` | random 16-char base64url string |
|
|
174
|
+
| `'$currentUser'` | full JWT payload from the in-flight request |
|
|
175
|
+
| `'$currentUser.<key>'` | single field from that payload (e.g. `'$currentUser.id'`) |
|
|
176
|
+
|
|
177
|
+
Any other value is used as-is — only these exact strings are special-cased.
|
|
178
|
+
|
|
179
|
+
### Auto-increment (`sequence`)
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
export const Order = defineModel<OrderDocument>('Order', {
|
|
183
|
+
orderNumber: { type: 'number', sequence: true, required: true },
|
|
184
|
+
// sequence: 'global.orders' — explicit key to share a counter across models
|
|
185
|
+
});
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
`sequence` is a field option, not a `default` code — an auto-increment needs an async read-modify-write against a counters collection, but `default` resolves synchronously. It's assigned atomically in a `pre('validate')` hook, before `required` validation runs, so the field can be both `required: true` and auto-filled. Top-level fields only.
|
|
189
|
+
|
|
190
|
+
### Timestamps control
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
// Disable Mongoose's automatic createdAt/updatedAt (default: on)
|
|
194
|
+
export const Role = defineModel<RoleDocument>('Role', schema, {
|
|
195
|
+
timestamps: false,
|
|
196
|
+
});
|
|
197
|
+
|
|
198
|
+
// Or rename them
|
|
199
|
+
export const Audit = defineModel<AuditDocument>('Audit', schema, {
|
|
200
|
+
timestamps: { createdAt: 'created_at', updatedAt: false },
|
|
201
|
+
});
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### CRUD surface
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
await User.find({ role: 'admin' }); // find all matching
|
|
208
|
+
await User.findById('66a1...'); // by _id
|
|
209
|
+
await User.findOne({ email: 'a@b.com' }); // first match
|
|
210
|
+
await User.create({ name: 'Alice', ... }); // insert
|
|
211
|
+
await User.update('66a1...', { name: 'Bob' }); // findOneAndUpdate
|
|
212
|
+
await User.delete('66a1...'); // remove
|
|
213
|
+
await User.count({ role: 'user' }); // count matching
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Populate references:
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
await Post.find({}, { populate: 'author' });
|
|
220
|
+
await Post.findById(id, { populate: ['author', 'comments.user'] });
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
134
225
|
## Background Tasks
|
|
135
226
|
|
|
136
227
|
Tasks run off the request path — respond immediately, let the queue handle the work.
|
|
@@ -178,7 +269,9 @@ Task options:
|
|
|
178
269
|
| `retries` | `3` | Retry attempts before dead-lettering |
|
|
179
270
|
| `backoff` | `'exponential'` | Delay strategy between retries |
|
|
180
271
|
| `concurrency` | `tasks.concurrency` | Parallel jobs for this task |
|
|
181
|
-
| `schedule` | — | Cron expression
|
|
272
|
+
| `schedule` | — | Cron expression (accepted, not executed yet — planned) |
|
|
273
|
+
|
|
274
|
+
> `enqueue()` fails fast on an unknown task name, but currently has no timeout of its own if the queue backend (Redis) is unreachable — wrap it yourself if you need one.
|
|
182
275
|
|
|
183
276
|
---
|
|
184
277
|
|
|
@@ -215,60 +308,80 @@ export const POST = async (req, res) => {
|
|
|
215
308
|
};
|
|
216
309
|
```
|
|
217
310
|
|
|
311
|
+
### Role-gating and request context
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
// Role-gated route
|
|
315
|
+
export const middlewares = [requireAuth('admin')];
|
|
316
|
+
|
|
317
|
+
// getCurrentUser() reads the same verified JWT payload from anywhere in the
|
|
318
|
+
// async call chain — not just where `req` is in scope. This is also what
|
|
319
|
+
// powers the '$currentUser' / '$currentUser.<key>' defineModel default codes.
|
|
320
|
+
import { getCurrentUser } from 'express-file-cluster/auth';
|
|
321
|
+
|
|
322
|
+
const user = getCurrentUser(); // Record<string, unknown> | undefined
|
|
323
|
+
```
|
|
324
|
+
|
|
218
325
|
---
|
|
219
326
|
|
|
220
327
|
## Bootstrapper
|
|
221
328
|
|
|
222
|
-
|
|
223
|
-
// src/index.ts
|
|
224
|
-
import { ignite } from 'express-file-cluster';
|
|
225
|
-
import path from 'path';
|
|
226
|
-
import { fileURLToPath } from 'url';
|
|
329
|
+
Every runtime value (`PORT`, `DATABASE_URL`, `JWT_SECRET`, `CORS_ORIGINS`, ...) is read from `process.env` explicitly, once, in `efc.config.ts` — `ignite()` itself never touches `process.env` (`NODE_ENV` is the sole exception).
|
|
227
330
|
|
|
228
|
-
|
|
331
|
+
```ts
|
|
332
|
+
// efc.config.ts
|
|
333
|
+
import type { EFCConfig } from 'express-file-cluster';
|
|
229
334
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
tasksDir: path.join(__dirname, 'tasks'),
|
|
335
|
+
const corsOrigins = process.env.CORS_ORIGINS
|
|
336
|
+
? process.env.CORS_ORIGINS.split(',').map((o) => o.trim()).filter(Boolean)
|
|
337
|
+
: undefined;
|
|
234
338
|
|
|
235
|
-
|
|
339
|
+
const config: EFCConfig = {
|
|
340
|
+
port: process.env.PORT ? Number(process.env.PORT) : undefined,
|
|
236
341
|
databaseUrl: process.env.DATABASE_URL,
|
|
237
|
-
|
|
238
|
-
authStrategy: 'http-only',
|
|
239
342
|
jwtSecret: process.env.JWT_SECRET,
|
|
343
|
+
cors: corsOrigins ? { origin: corsOrigins } : true,
|
|
344
|
+
authStrategy: 'http-only',
|
|
345
|
+
tasks: { backend: 'bullmq', concurrency: 5, redisUrl: process.env.REDIS_URL },
|
|
346
|
+
};
|
|
240
347
|
|
|
241
|
-
|
|
242
|
-
|
|
348
|
+
export default config;
|
|
349
|
+
```
|
|
243
350
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
},
|
|
351
|
+
```ts
|
|
352
|
+
// src/index.ts
|
|
353
|
+
import { ignite, gracefulShutdown } from 'express-file-cluster';
|
|
354
|
+
import config from '../efc.config.js';
|
|
249
355
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
});
|
|
356
|
+
ignite({
|
|
357
|
+
...config,
|
|
358
|
+
}).then(gracefulShutdown).catch(console.error);
|
|
254
359
|
```
|
|
255
360
|
|
|
361
|
+
> Don't hardcode `cluster: true` here. `ignite()`'s own default (`NODE_ENV === 'production'`)
|
|
362
|
+
> already gives clustering in prod and a single process in dev — an explicit boolean always
|
|
363
|
+
> wins over that default, so `cluster: true` would cluster in dev too. Only pass `cluster`
|
|
364
|
+
> to force one way regardless of `NODE_ENV`.
|
|
365
|
+
|
|
256
366
|
### `ignite()` options
|
|
257
367
|
|
|
258
368
|
| Option | Type | Default | Description |
|
|
259
369
|
|---|---|---|---|
|
|
260
370
|
| `port` | `number` | `3000` | HTTP listen port |
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
371
|
+
| `basePath` | `string` | `'/v1/api'` | URL prefix for all routes |
|
|
372
|
+
| `database` | `'mongodb' \| 'postgresql'` | auto-detected from `databaseUrl` | Database engine |
|
|
373
|
+
| `databaseUrl` | `string` | — | Connection string — not read from env automatically, pass it explicitly |
|
|
374
|
+
| `authStrategy` | `'http-only' \| 'localStorage'` | `'http-only'` | Token delivery |
|
|
375
|
+
| `jwtSecret` | `string` | — | JWT signing secret — not read from env automatically, pass it explicitly |
|
|
376
|
+
| `jwtExpiresIn` | `string` | `'7d'` | Token lifetime |
|
|
377
|
+
| `cookieDomain` | `string` | — | Cookie domain (`http-only` only) |
|
|
378
|
+
| `cluster` | `boolean` | `true` in prod, `false` in dev | Enable multi-core clustering |
|
|
268
379
|
| `workers` | `number` | `os.cpus().length` | Worker count override |
|
|
269
380
|
| `tasks` | `TaskConfig \| false` | `false` | Background task runtime |
|
|
270
|
-
| `cors` | `boolean \| CorsConfig` | `true` | CORS —
|
|
381
|
+
| `cors` | `boolean \| CorsConfig` | `true` | CORS — pass `origin` explicitly, not auto-read from env |
|
|
382
|
+
| `requestTimeout` | `number` | — | Request timeout in ms (408 on exceed) |
|
|
271
383
|
| `globalMiddlewares` | `RequestHandler[]` | `[]` | Applied to every route |
|
|
384
|
+
| `dashboard` | `boolean` | `true` in dev | Dev route dashboard at `/` |
|
|
272
385
|
| `onWorkerReady` | `(id) => void` | — | Called when a worker boots |
|
|
273
386
|
| `onWorkerCrash` | `(id, code) => void` | — | Called before respawn |
|
|
274
387
|
| `onError` | `ErrorRequestHandler` | built-in | Override global error handler |
|
|
@@ -279,7 +392,7 @@ ignite({
|
|
|
279
392
|
|
|
280
393
|
```bash
|
|
281
394
|
# Development
|
|
282
|
-
efc start dev # Hot-reload single process
|
|
395
|
+
efc start dev # Hot-reload single process (tsx --watch), .env re-read on every restart
|
|
283
396
|
|
|
284
397
|
# Production
|
|
285
398
|
efc build prod # Type-check + compile to dist/ (tsup, dual CJS/ESM)
|
|
@@ -296,7 +409,7 @@ efc generate middleware authorize # → src/middlewares/authorize.ts
|
|
|
296
409
|
# Diagnostics
|
|
297
410
|
efc routes # Print resolved route table (path → file → methods)
|
|
298
411
|
efc tasks # List registered background tasks
|
|
299
|
-
efc doctor # Validate
|
|
412
|
+
efc doctor # Validate project setup, package.json/tsconfig, .env vars
|
|
300
413
|
```
|
|
301
414
|
|
|
302
415
|
---
|
|
@@ -312,12 +425,13 @@ efc doctor # Validate config, env vars, DB connectivity
|
|
|
312
425
|
│ │ │
|
|
313
426
|
Worker 1 Worker 2 Worker N
|
|
314
427
|
Pre-Flight lifecycle per worker:
|
|
315
|
-
1. Connect
|
|
428
|
+
1. Connect database
|
|
316
429
|
2. Configure auth
|
|
317
|
-
3. Scan
|
|
318
|
-
4.
|
|
319
|
-
5.
|
|
320
|
-
6.
|
|
430
|
+
3. Scan tasksDir → register tasks
|
|
431
|
+
4. Start BullMQ backend
|
|
432
|
+
5. Scan apiDir → build route map
|
|
433
|
+
6. Mount routes on Express
|
|
434
|
+
7. Listen (OS round-robins connections)
|
|
321
435
|
```
|
|
322
436
|
|
|
323
437
|
CPU-bound tasks fan out further into `worker_threads` — the request loop stays unblocked at every layer.
|
|
@@ -349,14 +463,14 @@ ignite({
|
|
|
349
463
|
|
|
350
464
|
## Environment Variables
|
|
351
465
|
|
|
352
|
-
`create-efc-app` generates `.env` (gitignored, `JWT_SECRET` pre-filled) and `.env.example` (committed, documented).
|
|
466
|
+
`create-efc-app` generates `.env` (gitignored, `JWT_SECRET` pre-filled) and `.env.example` (committed, documented). EFC **does not** auto-load any of these — read them yourself in `efc.config.ts` and pass them to `ignite()`.
|
|
353
467
|
|
|
354
468
|
| Variable | Required | Description |
|
|
355
469
|
|---|---|---|
|
|
356
470
|
| `PORT` | No (default `3000`) | HTTP listen port |
|
|
357
|
-
| `NODE_ENV` | No | `development \| production \| test` |
|
|
358
|
-
| `DATABASE_URL` |
|
|
359
|
-
| `JWT_SECRET` |
|
|
471
|
+
| `NODE_ENV` | No | `development \| production \| test` — the only env var EFC reads directly |
|
|
472
|
+
| `DATABASE_URL` | If using a database | MongoDB or PostgreSQL connection string |
|
|
473
|
+
| `JWT_SECRET` | If using auth | JWT signing key — auto-generated by scaffolder |
|
|
360
474
|
| `JWT_EXPIRES_IN` | No (default `7d`) | Token lifetime |
|
|
361
475
|
| `COOKIE_DOMAIN` | No | Cookie domain for `http-only` auth |
|
|
362
476
|
| `REDIS_URL` | If using BullMQ | Redis connection for the task queue |
|
package/package.json
CHANGED