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.
Files changed (2) hide show
  1. package/README.md +163 -49
  2. 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.10 (Beta).** The router, clustering, auth, MongoDB adapter, and BullMQ task queue backend are all implemented.
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
- │ ├── models/ # Engine-agnostic models
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 '../../models/User';
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 '../../models/User';
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 for recurring tasks |
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
- ```ts
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
- const __dirname = path.dirname(fileURLToPath(import.meta.url));
331
+ ```ts
332
+ // efc.config.ts
333
+ import type { EFCConfig } from 'express-file-cluster';
229
334
 
230
- ignite({
231
- port: Number(process.env.PORT) || 3000,
232
- apiDir: path.join(__dirname, 'api'),
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
- database: 'mongodb',
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
- cluster: true, // false → single process (auto-disabled in dev)
242
- workers: 4, // defaults to os.cpus().length
348
+ export default config;
349
+ ```
243
350
 
244
- tasks: {
245
- backend: 'bullmq',
246
- redisUrl: process.env.REDIS_URL,
247
- concurrency: 5,
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
- globalMiddlewares: [],
251
- onWorkerReady: (id) => console.log(`Worker ${id} ready`),
252
- onWorkerCrash: (id, code) => console.error(`Worker ${id} crashed (${code})`),
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
- | `apiDir` | `string` | — | Path to route modules |
262
- | `tasksDir` | `string` | — | Path to task modules |
263
- | `database` | `'mongodb' \| 'postgresql'` | — | Database engine |
264
- | `databaseUrl` | `string` | `DATABASE_URL` | Connection string |
265
- | `authStrategy` | `'http-only' \| 'localStorage'` | — | Token delivery |
266
- | `jwtSecret` | `string` | `JWT_SECRET` | JWT signing secret |
267
- | `cluster` | `boolean` | `true` | Enable multi-core clustering |
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 — origins driven by `CORS_ORIGINS` env var |
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, source maps, pretty logs
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 config, env vars, DB connectivity
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 DB
428
+ 1. Connect database
316
429
  2. Configure auth
317
- 3. Scan apiDir → route map
318
- 4. Register tasks
319
- 5. Mount routes on Express
320
- 6. Listen (OS round-robins connections)
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` | Yes | MongoDB or PostgreSQL connection string |
359
- | `JWT_SECRET` | Yes | JWT signing key — auto-generated by scaffolder |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "express-file-cluster",
3
- "version": "0.3.14",
3
+ "version": "0.3.15",
4
4
  "description": "Enterprise-grade, zero-boilerplate backend framework with file-based routing and multi-core clustering",
5
5
  "license": "MIT",
6
6
  "type": "module",