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.
Files changed (116) hide show
  1. package/README.md +71 -33
  2. package/dist/auth/index.cjs +12 -2
  3. package/dist/auth/index.cjs.map +1 -1
  4. package/dist/auth/index.d.cts +13 -2
  5. package/dist/auth/index.d.ts +13 -2
  6. package/dist/auth/index.js +12 -2
  7. package/dist/chunk-277BSYVH.js +127 -0
  8. package/dist/chunk-277BSYVH.js.map +1 -0
  9. package/dist/chunk-6OGOVV57.js +3847 -0
  10. package/dist/chunk-6OGOVV57.js.map +1 -0
  11. package/dist/chunk-7YEX4MQV.cjs +38 -0
  12. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  13. package/dist/chunk-AZYXQU3Z.cjs +3847 -0
  14. package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
  15. package/dist/chunk-BUBXO7WU.js +170 -0
  16. package/dist/chunk-BUBXO7WU.js.map +1 -0
  17. package/dist/chunk-LJNSJFOL.js +38 -0
  18. package/dist/chunk-LJNSJFOL.js.map +1 -0
  19. package/dist/chunk-MGH4VDV3.cjs +170 -0
  20. package/dist/chunk-MGH4VDV3.cjs.map +1 -0
  21. package/dist/chunk-R34R7QPD.cjs +116 -0
  22. package/dist/chunk-R34R7QPD.cjs.map +1 -0
  23. package/dist/chunk-RS4MXCPW.js +116 -0
  24. package/dist/chunk-RS4MXCPW.js.map +1 -0
  25. package/dist/chunk-T4OHFU5T.cjs +154 -0
  26. package/dist/chunk-T4OHFU5T.cjs.map +1 -0
  27. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  28. package/dist/chunk-TRC4DUZB.js +438 -0
  29. package/dist/chunk-TRC4DUZB.js.map +1 -0
  30. package/dist/chunk-TYR2GZZE.cjs +196 -0
  31. package/dist/chunk-TYR2GZZE.cjs.map +1 -0
  32. package/dist/chunk-UBQYQPBU.js +154 -0
  33. package/dist/chunk-UBQYQPBU.js.map +1 -0
  34. package/dist/chunk-UTM4PEVG.js +196 -0
  35. package/dist/chunk-UTM4PEVG.js.map +1 -0
  36. package/dist/chunk-YL37D6KM.cjs +127 -0
  37. package/dist/chunk-YL37D6KM.cjs.map +1 -0
  38. package/dist/chunk-ZDM5JHVK.cjs +438 -0
  39. package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
  40. package/dist/cli/db-runner.cjs +497 -0
  41. package/dist/cli/db-runner.cjs.map +1 -0
  42. package/dist/cli/db-runner.d.cts +2 -0
  43. package/dist/cli/db-runner.d.ts +2 -0
  44. package/dist/cli/db-runner.js +497 -0
  45. package/dist/cli/db-runner.js.map +1 -0
  46. package/dist/cli/index.cjs +447 -69
  47. package/dist/cli/index.cjs.map +1 -1
  48. package/dist/cli/index.js +473 -95
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/docs/api-reference/auth.md +232 -0
  51. package/dist/docs/api-reference/compose.md +78 -0
  52. package/dist/docs/api-reference/db.md +351 -0
  53. package/dist/docs/api-reference/http-error.md +109 -0
  54. package/dist/docs/api-reference/ignite.md +326 -0
  55. package/dist/docs/api-reference/table.md +458 -0
  56. package/dist/docs/api-reference/tasks.md +140 -0
  57. package/dist/docs/cli/db.md +38 -0
  58. package/dist/docs/cli/diagnostics.md +145 -0
  59. package/dist/docs/cli/generate.md +120 -0
  60. package/dist/docs/cli/index.md +48 -0
  61. package/dist/docs/cli/start.md +112 -0
  62. package/dist/docs/contributing/index.md +139 -0
  63. package/dist/docs/core-concepts/background-tasks.md +228 -0
  64. package/dist/docs/core-concepts/clustering.md +114 -0
  65. package/dist/docs/core-concepts/file-based-routing.md +235 -0
  66. package/dist/docs/core-concepts/index.md +79 -0
  67. package/dist/docs/core-concepts/middleware.md +144 -0
  68. package/dist/docs/getting-started/index.md +91 -0
  69. package/dist/docs/getting-started/project-structure.md +154 -0
  70. package/dist/docs/guides/ai-agents.md +48 -0
  71. package/dist/docs/guides/authentication.md +196 -0
  72. package/dist/docs/guides/caching.md +124 -0
  73. package/dist/docs/guides/database.md +217 -0
  74. package/dist/docs/guides/deployment.md +171 -0
  75. package/dist/docs/guides/environment-variables.md +106 -0
  76. package/dist/docs/guides/error-handling.md +172 -0
  77. package/dist/docs/guides/generated-portals.md +115 -0
  78. package/dist/docs/guides/logging.md +108 -0
  79. package/dist/docs/guides/mailer.md +166 -0
  80. package/dist/docs/guides/migrations.md +106 -0
  81. package/dist/docs/guides/rbac.md +89 -0
  82. package/dist/docs/guides/validation.md +95 -0
  83. package/dist/docs/index.md +93 -0
  84. package/dist/docs/skills/SKILL.md +44 -0
  85. package/dist/docs/skills/api-surface.md +309 -0
  86. package/dist/docs/skills/auth-internals.md +141 -0
  87. package/dist/docs/skills/pre-flight.md +142 -0
  88. package/dist/docs/skills/routing-rules.md +114 -0
  89. package/dist/docs/skills/tasks-internals.md +172 -0
  90. package/dist/docs/skills/what-not-to-invent.md +251 -0
  91. package/dist/index.cjs +264 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +699 -7
  94. package/dist/index.d.ts +699 -7
  95. package/dist/index.js +258 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
  98. package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
  99. package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
  100. package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
  101. package/dist/tasks/index.cjs.map +1 -1
  102. package/dist/tasks/index.d.cts +1 -1
  103. package/dist/tasks/index.d.ts +1 -1
  104. package/dist/types-B6lVw4bj.d.cts +588 -0
  105. package/dist/types-B6lVw4bj.d.ts +588 -0
  106. package/package.json +28 -5
  107. package/dist/chunk-6522HS2J.cjs +0 -99
  108. package/dist/chunk-6522HS2J.cjs.map +0 -1
  109. package/dist/chunk-DGVOJNR6.cjs +0 -55
  110. package/dist/chunk-DGVOJNR6.cjs.map +0 -1
  111. package/dist/chunk-KOHLLUN7.js +0 -55
  112. package/dist/chunk-KOHLLUN7.js.map +0 -1
  113. package/dist/chunk-VIP3PFWZ.js +0 -99
  114. package/dist/chunk-VIP3PFWZ.js.map +0 -1
  115. package/dist/types-BusbSenn.d.cts +0 -162
  116. package/dist/types-BusbSenn.d.ts +0 -162
@@ -0,0 +1,326 @@
1
+ # `ignite(config)` — API Reference
2
+
3
+ `ignite()` is the single entry point that boots the framework. It handles clustering, database, auth, tasks, and routing in the correct order.
4
+
5
+ ```ts
6
+ import { ignite } from 'express-file-cluster';
7
+
8
+ const server = await ignite(config);
9
+ ```
10
+
11
+ **Returns:** `Promise<http.Server | undefined>`
12
+
13
+ - Returns `http.Server` in a worker process (or in single-process mode).
14
+ - Returns `undefined` in the master process (clustering enabled, primary fork).
15
+
16
+ ---
17
+
18
+ ## `EFCConfig` reference
19
+
20
+ ```ts
21
+ interface EFCConfig {
22
+ // Routing
23
+ basePath?: string;
24
+
25
+ // Clustering
26
+ cluster?: boolean;
27
+ workers?: number;
28
+ onWorkerReady?: (id: number) => void;
29
+ onWorkerCrash?: (id: number, code: number) => void;
30
+
31
+ // Database
32
+ database?: 'mongodb' | 'postgresql';
33
+ databaseUrl?: string;
34
+
35
+ // Auth
36
+ authStrategy?: 'http-only' | 'localStorage';
37
+ jwtSecret?: string;
38
+ jwtExpiresIn?: string;
39
+ cookieDomain?: string;
40
+
41
+ // Background tasks
42
+ tasks?: TaskConfig | false;
43
+
44
+ // HTTP
45
+ port?: number;
46
+ cors?: boolean | CorsConfig;
47
+ requestTimeout?: number;
48
+ globalMiddlewares?: RequestHandler[];
49
+ onError?: ErrorRequestHandler;
50
+
51
+ // Logging
52
+ logging?: LoggingConfig | false;
53
+
54
+ // Reconcile tables/collections + indexes on first use (default true)
55
+ autoSync?: boolean;
56
+
57
+ // Cache + session revocation store
58
+ cache?: CacheConfig | false;
59
+
60
+ // Developer tools
61
+ dashboard?: boolean;
62
+ }
63
+ ```
64
+
65
+ ---
66
+
67
+ ## Option details
68
+
69
+ ### `basePath`
70
+
71
+ URL prefix prepended to every route. Default: `'/v1/api'`.
72
+
73
+ ```ts
74
+ ignite({ basePath: '/api' });
75
+ // routes: /api/health, /api/users/:id, ...
76
+ ```
77
+
78
+ Set to `'/'` to mount routes directly at the root with no prefix.
79
+
80
+ ---
81
+
82
+ ### `dashboard`
83
+
84
+ When `true`, EFC mounts a live API documentation page at `GET /` (or `GET <basePath>/`) that is only active in development (`NODE_ENV === 'development'`). The page lists every registered route with its method, path, description, and request/response examples derived from each file's `meta` export.
85
+
86
+ ```ts
87
+ ignite({ dashboard: true });
88
+ ```
89
+
90
+ ---
91
+
92
+ ### `port`
93
+
94
+ HTTP listen port. Default: `3000`. `ignite()` never reads `PORT` from the environment itself — pass it explicitly, typically by reading `process.env.PORT` in `efc.config.ts` (see [Environment Variables](../guides/environment-variables.md)).
95
+
96
+ ```ts
97
+ ignite({ port: 8080 });
98
+ // or, in efc.config.ts: port: process.env.PORT ? Number(process.env.PORT) : undefined
99
+ ```
100
+
101
+ ---
102
+
103
+ ### `cluster`
104
+
105
+ Enable multi-core clustering. When `true`, the primary process forks `workers` child processes and returns `undefined`. Each worker runs the full Pre-Flight lifecycle independently.
106
+
107
+ Default: `true` when `NODE_ENV === 'production'`, `false` otherwise.
108
+
109
+ ```ts
110
+ ignite({ cluster: true, workers: 4 });
111
+ ```
112
+
113
+ ---
114
+
115
+ ### `workers`
116
+
117
+ Number of worker processes to fork. Default: `os.cpus().length`.
118
+
119
+ ---
120
+
121
+ ### `onWorkerReady`
122
+
123
+ Called by the primary process when a worker emits the `'online'` event.
124
+
125
+ ```ts
126
+ onWorkerReady: (id) => logger.info(`Worker ${id} is live`),
127
+ ```
128
+
129
+ ---
130
+
131
+ ### `onWorkerCrash`
132
+
133
+ Called by the primary process when a worker exits unexpectedly, before a replacement is forked. The `code` is the exit code (or `-1` if the worker was killed by a signal).
134
+
135
+ ```ts
136
+ onWorkerCrash: (id, code) => alerting.send(`Worker ${id} crashed with code ${code}`),
137
+ ```
138
+
139
+ ---
140
+
141
+ ### `database`
142
+
143
+ Database engine to connect. When omitted, EFC detects it from the `databaseUrl` scheme (`mongodb://…` / `mongodb+srv://…` → `'mongodb'`, `postgres://…` / `postgresql://…` → `'postgresql'`). The engine also decides what [`defineModel`](./db.md) compiles to: a mongoose model or a Drizzle table. MongoDB needs `mongoose` installed; PostgreSQL needs `pg` and `drizzle-orm`.
144
+
145
+ ---
146
+
147
+ ### `databaseUrl`
148
+
149
+ Connection string for the database. `ignite()` never reads `DATABASE_URL` from the environment itself — pass it explicitly (typically `databaseUrl: process.env.DATABASE_URL` in `efc.config.ts`).
150
+
151
+ ---
152
+
153
+ ### `authStrategy`
154
+
155
+ How JWTs are delivered to clients:
156
+
157
+ | Value | Mechanism |
158
+ |---|---|
159
+ | `'http-only'` | `HttpOnly + Secure + SameSite=Strict` cookie named `efc_token` |
160
+ | `'localStorage'` | Token returned in response body; client attaches `Authorization: Bearer <token>` |
161
+
162
+ Default: `'http-only'`.
163
+
164
+ ---
165
+
166
+ ### `jwtSecret`
167
+
168
+ Secret used to sign and verify JWTs (HS256). `ignite()` never reads `JWT_SECRET` from the environment itself — pass it explicitly (typically `jwtSecret: process.env.JWT_SECRET` in `efc.config.ts`). Must be at least 32 random bytes for production use.
169
+
170
+ ---
171
+
172
+ ### `jwtExpiresIn`
173
+
174
+ Token lifetime, e.g. `'15m'`, `'1h'`, `'7d'`, `'30d'`. Default: `'7d'`. Pass explicitly (typically `jwtExpiresIn: process.env.JWT_EXPIRES_IN`); no environment fallback.
175
+
176
+ ---
177
+
178
+ ### `cookieDomain`
179
+
180
+ Cookie domain used by the `'http-only'` auth strategy. Default: unset (host-only cookie, correct for `localhost`). Pass explicitly (typically `cookieDomain: process.env.COOKIE_DOMAIN`); no environment fallback.
181
+
182
+ ---
183
+
184
+ ### `tasks`
185
+
186
+ Background task runtime configuration. Set to `false` (or omit) to disable the task system.
187
+
188
+ ```ts
189
+ interface TaskConfig {
190
+ backend: 'bullmq' | 'pg-boss';
191
+ redisUrl?: string; // BullMQ — default redis://localhost:6379
192
+ connectionString?: string; // pg-boss — default: databaseUrl
193
+ schema?: string; // pg-boss — Postgres schema for its tables, default 'pgboss'
194
+ concurrency?: number; // jobs processed in parallel per worker — default 5
195
+ enqueueTimeout?: number; // max ms enqueue() waits for the backend before rejecting — default 5000
196
+ queue?: string; // queue name; apps sharing a Redis DB / Postgres need distinct ones — default 'efc'
197
+ }
198
+ ```
199
+
200
+ See [Background Tasks](../core-concepts/background-tasks.md).
201
+
202
+ ---
203
+
204
+ ### `logging`
205
+
206
+ ```ts
207
+ interface LoggingConfig {
208
+ level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'; // default 'info'
209
+ pretty?: boolean; // default: true in a non-production TTY, JSON otherwise
210
+ requests?: boolean; // one line per completed request — default true
211
+ // Model operation logging (model, op, duration, statements, reqId) — default off.
212
+ // true = every operation; { slowMs } = only slow ones (unless all: true)
213
+ queries?: boolean | { all?: boolean; slowMs?: number /* 500 */; nPlusOne?: number | false /* 10 */ };
214
+ }
215
+ ```
216
+
217
+ `false` silences framework logs. Every request still gets an `X-Request-Id`. See [Logging](../guides/logging.md).
218
+
219
+ ---
220
+
221
+ ### `cors`
222
+
223
+ CORS configuration. Default: `true` (allow all origins). `ignite()` never reads `CORS_ORIGINS` from the environment itself — pass `cors.origin` explicitly.
224
+
225
+ ```ts
226
+ ignite({
227
+ cors: {
228
+ // typically built from `process.env.CORS_ORIGINS?.split(',').map(o => o.trim())`
229
+ // in efc.config.ts — pass an array (not a bare string) so per-request Origin
230
+ // validation actually happens instead of a single static header value
231
+ origin: ['https://app.example.com', 'https://admin.example.com'],
232
+ credentials: true,
233
+ maxAge: 86400,
234
+ },
235
+ });
236
+ ```
237
+
238
+ Set `cors: false` to skip CORS headers entirely.
239
+
240
+ ```ts
241
+ interface CorsConfig {
242
+ origin?: string | string[] | boolean;
243
+ methods?: string | string[];
244
+ allowedHeaders?: string | string[];
245
+ credentials?: boolean;
246
+ maxAge?: number;
247
+ }
248
+ ```
249
+
250
+ ---
251
+
252
+ ### `cache`
253
+
254
+ ```ts
255
+ type CacheConfig = { prefix?: string; onRevocationCheckError?: 'reject' | 'allow' } & (
256
+ | { backend: 'redis'; url?: string; timeout?: number }
257
+ | { backend: 'memory'; maxEntries?: number } // shared by this machine's cluster workers via the primary
258
+ );
259
+ ```
260
+
261
+ `onRevocationCheckError` (default `'reject'`): when the cache can't be reached for a revocation check, `requireAuth` answers 503 (`'reject'`) or lets the request through (`'allow'`).
262
+
263
+ Enables `cache`, `cacheResponse()` and session revocation (`revokeSession`, `revokeAllSessions`). Connected during Pre-Flight, after the database. See [Caching & Sessions](../guides/caching.md).
264
+
265
+ ---
266
+
267
+ ### `autoSync`
268
+
269
+ Default `true`: the first time each model is used in a process, its table (PostgreSQL) or collection and indexes (MongoDB) are reconciled with the definition — see [Database](../guides/database.md#the-schema-takes-care-of-itself). Set `false` to change the schema only through `efc db sync` / migrations; on MongoDB this also turns off mongoose's `autoIndex` / `autoCreate`.
270
+
271
+ ---
272
+
273
+ ### `requestTimeout`
274
+
275
+ Milliseconds a request may take before EFC answers **408** `{ "error": "Request Timeout", "statusCode": 408 }`. A handler that keeps running and replies later is ignored (logged at `warn`) instead of crashing. Default: no timeout.
276
+
277
+ ---
278
+
279
+ ### `globalMiddlewares`
280
+
281
+ Array of Express `RequestHandler` functions applied to every route, in order, before route-level middleware.
282
+
283
+ ```ts
284
+ ignite({
285
+ globalMiddlewares: [requestLogger, rateLimiter],
286
+ });
287
+ ```
288
+
289
+ ---
290
+
291
+ ### `onError`
292
+
293
+ Override the built-in global error handler. Receives `(err, req, res, next)`. If not provided, EFC responds with:
294
+
295
+ - `{ error: err.message, statusCode: err.statusCode }` for `HttpError` instances.
296
+ - `{ error: 'Internal Server Error', statusCode: 500 }` for all other errors.
297
+
298
+ ```ts
299
+ ignite({
300
+ onError: (err, req, res, _next) => {
301
+ logger.error({ err, url: req.url });
302
+ const status = (err as any).statusCode ?? 500;
303
+ res.status(status).json({ error: err.message });
304
+ },
305
+ });
306
+ ```
307
+
308
+ ---
309
+
310
+ ## `gracefulShutdown(server, timeoutMs?)`
311
+
312
+ Registers `SIGTERM` and `SIGINT` handlers for clean shutdown. Pass the `http.Server` returned by `ignite()`.
313
+
314
+ ```ts
315
+ ignite({ port: 3000 })
316
+ .then(gracefulShutdown);
317
+ // or with a custom timeout:
318
+ .then((server) => gracefulShutdown(server, 30_000));
319
+ ```
320
+
321
+ | Parameter | Type | Default | Description |
322
+ |---|---|---|---|
323
+ | `server` | `http.Server \| undefined` | — | Server to close (undefined for the master process) |
324
+ | `timeoutMs` | `number` | `10_000` | Force-exit after this many milliseconds if `server.close()` hasn't finished |
325
+
326
+ On a worker, the signal closes the HTTP server (in-flight requests finish), drains running task jobs, then exits. On the cluster primary it relays `SIGTERM` to every worker — so `docker stop` / Kubernetes, which signal only PID 1, still shut down gracefully — and force-exits after `timeoutMs + 2s` if a worker hangs. Repeated signals are ignored rather than killing a worker mid-drain.