express-file-cluster 0.10.0 → 0.11.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 (194) hide show
  1. package/dist/auth/index.cjs +7 -6
  2. package/dist/auth/index.cjs.map +1 -1
  3. package/dist/auth/index.d.cts +3 -1
  4. package/dist/auth/index.d.ts +3 -1
  5. package/dist/auth/index.js +5 -5
  6. package/dist/{chunk-73XJUT2S.js → chunk-2IDRC7RK.js} +163 -5
  7. package/dist/chunk-2IDRC7RK.js.map +1 -0
  8. package/dist/{chunk-QDEDOHP7.js → chunk-336IU55W.js} +9 -42
  9. package/dist/chunk-336IU55W.js.map +1 -0
  10. package/dist/{chunk-R52CUEGT.js → chunk-3SWI46YK.js} +2 -2
  11. package/dist/{chunk-7KO4DJRJ.cjs → chunk-6WTMRZS7.cjs} +14 -14
  12. package/dist/{chunk-7KO4DJRJ.cjs.map → chunk-6WTMRZS7.cjs.map} +1 -1
  13. package/dist/chunk-AGOYTFRO.cjs +42 -0
  14. package/dist/chunk-AGOYTFRO.cjs.map +1 -0
  15. package/dist/{chunk-RAB44UGX.js → chunk-B6MB6HEG.js} +1 -1
  16. package/dist/chunk-CGY7JU4Y.cjs +8 -0
  17. package/dist/chunk-CGY7JU4Y.cjs.map +1 -0
  18. package/dist/chunk-DGYPIIJE.cjs +845 -0
  19. package/dist/chunk-DGYPIIJE.cjs.map +1 -0
  20. package/dist/{chunk-EGSSZUVO.js → chunk-DN4TCGYB.js} +38 -11
  21. package/dist/chunk-DN4TCGYB.js.map +1 -0
  22. package/dist/{chunk-YK4ZM3CA.cjs → chunk-DTMDJGRW.cjs} +15 -15
  23. package/dist/{chunk-YK4ZM3CA.cjs.map → chunk-DTMDJGRW.cjs.map} +1 -1
  24. package/dist/{chunk-R4XO4SVM.js → chunk-EJDZZ4KX.js} +4 -4
  25. package/dist/{chunk-NKLOE4AK.cjs → chunk-GWMW6XY7.cjs} +20 -53
  26. package/dist/chunk-GWMW6XY7.cjs.map +1 -0
  27. package/dist/{chunk-GBI77W5T.cjs → chunk-H2PVWCWC.cjs} +1 -1
  28. package/dist/{chunk-GBI77W5T.cjs.map → chunk-H2PVWCWC.cjs.map} +1 -1
  29. package/dist/{chunk-KFVFP2Q7.cjs → chunk-IEF6AEK3.cjs} +70 -55
  30. package/dist/chunk-IEF6AEK3.cjs.map +1 -0
  31. package/dist/{chunk-PGJQK36V.js → chunk-JBOMTZT5.js} +7 -5
  32. package/dist/{chunk-PGJQK36V.js.map → chunk-JBOMTZT5.js.map} +1 -1
  33. package/dist/chunk-LECHRAU3.js +845 -0
  34. package/dist/chunk-LECHRAU3.js.map +1 -0
  35. package/dist/{chunk-4DOHQU6I.cjs → chunk-M53GODCX.cjs} +39 -12
  36. package/dist/chunk-M53GODCX.cjs.map +1 -0
  37. package/dist/{chunk-NI2BNGGV.js → chunk-O2E7H2XA.js} +2 -2
  38. package/dist/{chunk-ATVD2HGC.js → chunk-OM2XJJWX.js} +4 -4
  39. package/dist/{chunk-DUADUR6R.cjs → chunk-QSIP7YLW.cjs} +172 -14
  40. package/dist/chunk-QSIP7YLW.cjs.map +1 -0
  41. package/dist/{chunk-7KC2H76D.js → chunk-R6GPQZLI.js} +62 -47
  42. package/dist/chunk-R6GPQZLI.js.map +1 -0
  43. package/dist/{chunk-WBLUGOAG.cjs → chunk-RPL2IFWK.cjs} +8 -5
  44. package/dist/chunk-RPL2IFWK.cjs.map +1 -0
  45. package/dist/{chunk-HBCY7ILD.cjs → chunk-SOU3PBJC.cjs} +97 -95
  46. package/dist/chunk-SOU3PBJC.cjs.map +1 -0
  47. package/dist/{chunk-DCJOWFVD.cjs → chunk-WHBSVYUY.cjs} +3 -3
  48. package/dist/{chunk-DCJOWFVD.cjs.map → chunk-WHBSVYUY.cjs.map} +1 -1
  49. package/dist/chunk-XPY5TQDK.js +42 -0
  50. package/dist/chunk-XPY5TQDK.js.map +1 -0
  51. package/dist/cli/db-runner.cjs +81 -42
  52. package/dist/cli/db-runner.cjs.map +1 -1
  53. package/dist/cli/db-runner.js +54 -16
  54. package/dist/cli/db-runner.js.map +1 -1
  55. package/dist/cli/index.cjs +23 -25
  56. package/dist/cli/index.cjs.map +1 -1
  57. package/dist/cli/index.js +12 -17
  58. package/dist/cli/index.js.map +1 -1
  59. package/dist/docs/api-reference/auth.md +23 -0
  60. package/dist/docs/api-reference/compose.md +1 -1
  61. package/dist/docs/api-reference/db.md +8 -0
  62. package/dist/docs/api-reference/ignite.md +8 -1
  63. package/dist/docs/api-reference/openapi.md +36 -0
  64. package/dist/docs/api-reference/testing.md +28 -0
  65. package/dist/docs/api-reference/websockets.md +23 -0
  66. package/dist/docs/cli/add.md +2 -2
  67. package/dist/docs/core-concepts/clustering.md +2 -0
  68. package/dist/docs/core-concepts/file-based-routing.md +4 -0
  69. package/dist/docs/core-concepts/middleware.md +2 -2
  70. package/dist/docs/getting-started/index.md +4 -0
  71. package/dist/docs/guides/authentication.md +33 -0
  72. package/dist/docs/guides/caching.md +2 -0
  73. package/dist/docs/guides/database.md +15 -0
  74. package/dist/docs/guides/environment-variables.md +6 -0
  75. package/dist/docs/guides/feature-matrix.md +9 -0
  76. package/dist/docs/guides/generated-portals.md +3 -1
  77. package/dist/docs/guides/logging.md +17 -0
  78. package/dist/docs/guides/migrations.md +4 -2
  79. package/dist/docs/guides/openapi.md +57 -0
  80. package/dist/docs/guides/testing.md +31 -0
  81. package/dist/docs/guides/validation.md +2 -0
  82. package/dist/docs/guides/websockets.md +60 -0
  83. package/dist/docs/index.md +4 -1
  84. package/dist/docs/skills/SKILL.md +8 -2
  85. package/dist/docs/skills/api-surface.md +30 -4
  86. package/dist/docs/skills/auth-internals.md +14 -1
  87. package/dist/docs/skills/pre-flight.md +8 -0
  88. package/dist/docs/skills/routing-rules.md +5 -1
  89. package/dist/docs/skills/what-not-to-invent.md +11 -1
  90. package/dist/docs/versioning.md +1 -1
  91. package/dist/index.cjs +100 -267
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +28 -3
  94. package/dist/index.d.ts +28 -3
  95. package/dist/index.js +52 -221
  96. package/dist/index.js.map +1 -1
  97. package/dist/openapi-cjs.cjs +5 -0
  98. package/dist/pgboss-backend-PQW6I3VF.js +14 -0
  99. package/dist/pgboss-backend-QVXISTLP.cjs +15 -0
  100. package/dist/pgboss-backend-QVXISTLP.cjs.map +1 -0
  101. package/dist/registry/index.json +27 -3
  102. package/dist/registry/js-mongo/account-security.json +1 -1
  103. package/dist/registry/js-mongo/admin-users.json +1 -1
  104. package/dist/registry/js-mongo/auth.json +1 -1
  105. package/dist/registry/js-mongo/auth@apple.json +1 -1
  106. package/dist/registry/js-mongo/auth@google.json +1 -1
  107. package/dist/registry/js-mongo/forgot-password.json +1 -1
  108. package/dist/registry/js-mongo/user-profile.json +1 -1
  109. package/dist/registry/js-mongo-collection/account-security.json +1 -1
  110. package/dist/registry/js-mongo-collection/admin-users.json +1 -1
  111. package/dist/registry/js-mongo-collection/auth.json +1 -1
  112. package/dist/registry/js-mongo-collection/auth@apple.json +1 -1
  113. package/dist/registry/js-mongo-collection/auth@google.json +1 -1
  114. package/dist/registry/js-mongo-collection/forgot-password.json +1 -1
  115. package/dist/registry/js-mongo-collection/user-profile.json +1 -1
  116. package/dist/registry/js-pg-model/account-security.json +1 -1
  117. package/dist/registry/js-pg-model/admin-users.json +1 -1
  118. package/dist/registry/js-pg-model/auth.json +1 -1
  119. package/dist/registry/js-pg-model/auth@apple.json +1 -1
  120. package/dist/registry/js-pg-model/auth@google.json +1 -1
  121. package/dist/registry/js-pg-model/forgot-password.json +1 -1
  122. package/dist/registry/js-pg-model/user-profile.json +1 -1
  123. package/dist/registry/js-pg-table/account-security.json +1 -1
  124. package/dist/registry/js-pg-table/admin-users.json +1 -1
  125. package/dist/registry/js-pg-table/auth.json +1 -1
  126. package/dist/registry/js-pg-table/auth@apple.json +1 -1
  127. package/dist/registry/js-pg-table/auth@google.json +1 -1
  128. package/dist/registry/js-pg-table/forgot-password.json +1 -1
  129. package/dist/registry/js-pg-table/user-profile.json +1 -1
  130. package/dist/registry/ts-mongo/account-security.json +1 -1
  131. package/dist/registry/ts-mongo/admin-users.json +1 -1
  132. package/dist/registry/ts-mongo/auth.json +1 -1
  133. package/dist/registry/ts-mongo/auth@apple.json +1 -1
  134. package/dist/registry/ts-mongo/auth@google.json +1 -1
  135. package/dist/registry/ts-mongo/forgot-password.json +1 -1
  136. package/dist/registry/ts-mongo/user-profile.json +1 -1
  137. package/dist/registry/ts-mongo-collection/account-security.json +1 -1
  138. package/dist/registry/ts-mongo-collection/admin-users.json +1 -1
  139. package/dist/registry/ts-mongo-collection/auth.json +1 -1
  140. package/dist/registry/ts-mongo-collection/auth@apple.json +1 -1
  141. package/dist/registry/ts-mongo-collection/auth@google.json +1 -1
  142. package/dist/registry/ts-mongo-collection/forgot-password.json +1 -1
  143. package/dist/registry/ts-mongo-collection/user-profile.json +1 -1
  144. package/dist/registry/ts-pg-model/account-security.json +1 -1
  145. package/dist/registry/ts-pg-model/admin-users.json +1 -1
  146. package/dist/registry/ts-pg-model/auth.json +1 -1
  147. package/dist/registry/ts-pg-model/auth@apple.json +1 -1
  148. package/dist/registry/ts-pg-model/auth@google.json +1 -1
  149. package/dist/registry/ts-pg-model/forgot-password.json +1 -1
  150. package/dist/registry/ts-pg-model/user-profile.json +1 -1
  151. package/dist/registry/ts-pg-table/account-security.json +1 -1
  152. package/dist/registry/ts-pg-table/admin-users.json +1 -1
  153. package/dist/registry/ts-pg-table/auth.json +1 -1
  154. package/dist/registry/ts-pg-table/auth@apple.json +1 -1
  155. package/dist/registry/ts-pg-table/auth@google.json +1 -1
  156. package/dist/registry/ts-pg-table/forgot-password.json +1 -1
  157. package/dist/registry/ts-pg-table/user-profile.json +1 -1
  158. package/dist/tasks/index.cjs +3 -2
  159. package/dist/tasks/index.cjs.map +1 -1
  160. package/dist/tasks/index.d.cts +3 -1
  161. package/dist/tasks/index.d.ts +3 -1
  162. package/dist/tasks/index.js +1 -1
  163. package/dist/testing-cjs.cjs +5 -0
  164. package/dist/testing.cjs +65 -0
  165. package/dist/testing.cjs.map +1 -0
  166. package/dist/testing.d.cts +30 -0
  167. package/dist/testing.d.ts +30 -0
  168. package/dist/testing.js +64 -0
  169. package/dist/testing.js.map +1 -0
  170. package/dist/thread-runner.cjs +4 -3
  171. package/dist/thread-runner.cjs.map +1 -1
  172. package/dist/thread-runner.js +2 -2
  173. package/dist/{types-Bnxvj3l0.d.ts → types-D3QmZgeX.d.cts} +88 -2
  174. package/dist/{types-Bnxvj3l0.d.cts → types-D3QmZgeX.d.ts} +88 -2
  175. package/package.json +11 -4
  176. package/dist/chunk-4DOHQU6I.cjs.map +0 -1
  177. package/dist/chunk-73XJUT2S.js.map +0 -1
  178. package/dist/chunk-7KC2H76D.js.map +0 -1
  179. package/dist/chunk-DUADUR6R.cjs.map +0 -1
  180. package/dist/chunk-EGSSZUVO.js.map +0 -1
  181. package/dist/chunk-HBCY7ILD.cjs.map +0 -1
  182. package/dist/chunk-KFVFP2Q7.cjs.map +0 -1
  183. package/dist/chunk-NKLOE4AK.cjs.map +0 -1
  184. package/dist/chunk-QDEDOHP7.js.map +0 -1
  185. package/dist/chunk-WBLUGOAG.cjs.map +0 -1
  186. package/dist/pgboss-backend-FW42SBSM.js +0 -14
  187. package/dist/pgboss-backend-RVHUBJTU.cjs +0 -14
  188. package/dist/pgboss-backend-RVHUBJTU.cjs.map +0 -1
  189. /package/dist/{chunk-R52CUEGT.js.map → chunk-3SWI46YK.js.map} +0 -0
  190. /package/dist/{chunk-RAB44UGX.js.map → chunk-B6MB6HEG.js.map} +0 -0
  191. /package/dist/{chunk-R4XO4SVM.js.map → chunk-EJDZZ4KX.js.map} +0 -0
  192. /package/dist/{chunk-NI2BNGGV.js.map → chunk-O2E7H2XA.js.map} +0 -0
  193. /package/dist/{chunk-ATVD2HGC.js.map → chunk-OM2XJJWX.js.map} +0 -0
  194. /package/dist/{pgboss-backend-FW42SBSM.js.map → pgboss-backend-PQW6I3VF.js.map} +0 -0
@@ -37,8 +37,14 @@ Load **only** the module the work points to. Each is self-contained.
37
37
  docs/ ← full documentation
38
38
  ```
39
39
 
40
- ## Status (v0.10.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
40
+ ## Status (v0.11.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
41
41
 
42
42
  Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only cookie + Bearer token auth (scrypt password hashing built in), structured logging (pino, request IDs), `defineModel` on MongoDB (mongoose) **and** PostgreSQL (Drizzle) with validation, query options, bulk ops, transactions, `sync()`/`drop()`, PostgreSQL-native `defineTable` (Prisma-style queries, foreign keys, many-to-many, `include`, relation filters, nested writes), MongoDB-native `defineCollection` (mongoose vocabulary, BSON types, geo/text, `bulkWrite`, change streams), query logging (`logging.queries`), BullMQ **and** pg-boss task backends with cron schedules and dead-letter CLI, worker_threads for CPU-bound tasks, migrations/seeds/studio (`efc db`) incl. migrations generated from model diffs (`efc db generate`), `efc db pull` and `efc import-prisma`, full CLI.
43
43
 
44
- **Not yet implemented (Phase 3+):** WebSockets, plugins, OpenAPI generation, OpenTelemetry, `efc lint`, `efc deploy`.
44
+ **Not yet implemented (Phase 3+):** plugins, OpenTelemetry, `efc lint`, `efc deploy`.
45
+
46
+ Phase 3 testing utilities: `createTestApp` from `express-file-cluster/testing` mounts a real route tree without service boot or a listener. Read `docs/guides/testing.md` and `docs/api-reference/testing.md`; see process-wide auth/logging isolation limits.
47
+
48
+ M6 completed 2026-10-30: query logging + bounded opt-in query metrics, editable studio, pool settings + bounded prepared statements, and a strict 10% nightly benchmark gate. See `bench/results/m6-validation.md` for measured evidence. OpenTelemetry is a separate Phase 3 task.
49
+
50
+ Since 0.11.0: OpenAPI 3.1 generation (`generateOpenAPI`, `ignite({ openapi })`) and file `WS` exports with HTTP middleware/auth, origin/payload limits, heartbeat and drain. Read `docs/guides/openapi.md`, `docs/api-reference/openapi.md`, `docs/guides/websockets.md`, `docs/api-reference/websockets.md`. These APIs are available since 0.11.0.
@@ -6,12 +6,13 @@ Source of truth: `packages/core/src/`. Do not invent exports, types, or sub-path
6
6
 
7
7
  ## Sub-path exports
8
8
 
9
- Three import paths. No others exist.
9
+ Four import paths. No others exist.
10
10
 
11
11
  ```ts
12
12
  import { ... } from 'express-file-cluster' // main
13
13
  import { ... } from 'express-file-cluster/auth' // auth module
14
14
  import { ... } from 'express-file-cluster/tasks' // tasks module
15
+ import { createTestApp } from 'express-file-cluster/testing' // test helper
15
16
  ```
16
17
 
17
18
  ---
@@ -25,7 +26,7 @@ Source: `packages/core/src/index.ts`
25
26
  ```ts
26
27
  async function ignite(config: EFCConfig): Promise<http.Server | undefined> // undefined on the cluster primary
27
28
  function gracefulShutdown(server: http.Server | undefined, timeoutMs?: number): void
28
- function compose(...handlers: RequestHandler[]): RequestHandler
29
+ function compose(...handlers: RequestHandler[]): RequestHandler // next(err) stops + forwards; next('route'|'router') passes to Express
29
30
 
30
31
  // Models — one API on MongoDB (mongoose) and PostgreSQL (Drizzle); engine picked at first use
31
32
  // Types are INFERRED from the schema literal — no interface needed:
@@ -69,6 +70,11 @@ function setDbClient(client: Record<string, unknown>): void
69
70
  function getDbClient(): Record<string, unknown>
70
71
 
71
72
  // Logging (pino)
73
+ function getQueryMetrics(): QueryMetricsSnapshot // per-process bounded aggregates, opt-in logging.queries.metrics
74
+ function resetQueryMetrics(): void // clears window without disabling collection
75
+ // QueryMetricsSnapshot: { enabled; since (epoch ms); dropped; entries: ReadonlyArray<QueryMetric> }
76
+ // QueryMetric: { model; op; calls; errors; statements; totalMs; minMs; maxMs; meanMs; slow }
77
+ // QueryMetric and QueryMetricsSnapshot are exported types. No SQL/params/error strings in snapshots.
72
78
  const logger: Logger // proxy for getLogger()
73
79
  function getLogger(): Logger // request-scoped child (carries reqId) inside a request, root otherwise
74
80
 
@@ -104,7 +110,7 @@ interface EFCConfig {
104
110
  dashboard?: boolean; // dev-only route docs at '/'
105
111
  database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
106
112
  databaseUrl?: string;
107
- databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number }; // per worker
113
+ databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number; preparedStatements?: boolean | { max?: number } }; // per worker
108
114
  authStrategy?: 'http-only' | 'bearer'; // default 'http-only'; 'localStorage' = old name for 'bearer'; anything else = bearer + warning (error in 1.0)
109
115
  jwtSecret?: string;
110
116
  jwtExpiresIn?: string; // default '7d'
@@ -141,7 +147,7 @@ interface LoggingConfig {
141
147
  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'; // default 'info'
142
148
  pretty?: boolean; // default: non-production TTY
143
149
  requests?: boolean; // default true
144
- queries?: boolean | { all?: boolean; slowMs?: number; nPlusOne?: number | false }; // default off; slowMs 500, nPlusOne 10
150
+ queries?: boolean | { all?: boolean; slowMs?: number; nPlusOne?: number | false; metrics?: boolean | { maxEntries?: number } }; // default off; slowMs 500, nPlusOne 10
145
151
  }
146
152
  ```
147
153
 
@@ -330,3 +336,23 @@ function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
330
336
  | `tasks.connectionString` (pg-boss) | — | `databaseUrl` |
331
337
 
332
338
  `NODE_ENV` is the sole exception — a Node/Express-wide runtime-mode signal, not an app secret — and is still read directly via `process.env['NODE_ENV']` in three places: `ignite()`'s cluster-in-production default, the dev-only dashboard toggle, and the `http-only` auth strategy's cookie `Secure` flag.
339
+
340
+ Generated app 2FA (not core exports): TOTP/email OTP enrollment, password+code login, disable. Init asks allowed methods (`TWO_FACTOR_METHOD`); each account chooses one. See `auth-internals.md` for endpoints, encrypted secrets, replay protection and OAuth limitations.
341
+
342
+ ## `express-file-cluster/testing` (Phase 3)
343
+
344
+ `async createTestApp(options: TestAppOptions): Promise<express.Express>`. Required `apiDir: string` (existing directory); optional `basePath` (default `/v1/api`), `globalMiddlewares`, `auth: { secret, strategy?, expiresIn?, cookieDomain? }` (defaults http-only/1h), `requestTimeout`, `trustProxy`, `onError`. Exports `TestAppOptions`. Real scanner/router/validation + shared production HTTP stack; no listen/cluster/services/tasks/signals/cwd mutation, CORS/logging/dashboard disabled. Auth/logging and module/model/cache/task state remain process-wide. `apiDir` is NOT an ignite option. See `api-reference/testing.md` and `guides/testing.md`.
345
+
346
+ Auth payloads may include `efc_auth_at` (epoch milliseconds from before credentials are read): revocation checks it conservatively against the account cutoff, capped at the server's issue time. Generated login/refresh routes set it. `/testing` supports CommonJS callers through an async bridge to its ESM implementation.
347
+
348
+ ESM/CJS auth configuration, request context and cache state are shared within the process, including mixed-module middleware in `/testing`. Generated reset-password uses atomic unexpired-token consumption and clears refresh credentials; custom auth logout propagates revocation failure.
349
+
350
+ ## 0.11.0 — OpenAPI and WebSockets
351
+
352
+ Main exports: `generateOpenAPI(routes: MountedRoute[] | string, options?: OpenAPIOptions & { basePath?: string }): Promise<OpenAPIDocument>`, `attachWebSockets(server: http.Server, app: express.Express, options?: WebSocketOptions): ws.WebSocketServer`, `closeWebSockets(server: http.Server, timeoutMs = 1000): Promise<void>`. Types: `JSONSchema`, `OpenAPIOptions`, `OpenAPIDocument`, `WebSocketHandler`, `WebSocketOptions`. No new import paths.
353
+
354
+ `EFCConfig.openapi?: boolean | OpenAPIOptions` (off; default path `/openapi.json`); `EFCConfig.websocket?: false | WebSocketOptions` (auto-attach for WS exports). `TestAppOptions.openapi` matches. `MountedRoute` includes optional `schema` and `websocket`. `RouteMethodMeta` adds `summary`, `tags`, `operationId`, `openapi` operation overrides (`hidden` omits). OpenAPI uses Standard JSON Schema input or explicit `schemaToJSONSchema`, not validator source inspection. WS signature `(socket, request) => void | Promise<void>`; file/global middleware and `schema.WS` apply before upgrade. See the API references for defaults and lifecycle.
355
+
356
+ 0.11.0 review fixes: WS payload/timer options are bounded to signed int32 (payload/handshake ≥1, heartbeat ≥0). Drain destroys pending upgrades immediately; pipelined upgrades behind active HTTP responses close safely. OpenAPI URL collision checks include hidden GET/HEAD and actual Express matches. Object query fields use deepObject; object unions/intersections retain fields/requirements and `x-efc-query-schema` preserves the whole query contract. Non-object parameter shapes need explicit operation parameters. Equivalent optional paths keep the first parameter binding; conflicting templates across routes throw.
357
+
358
+ OpenAPI follow-up: array query wire names use brackets (`tags[]`, form/explode) to preserve single items; Express still exposes `req.query.tags`. External field refs are kept without fetching; local type hints or explicit parameters control their serialization. Body requiredness checks converted-schema acceptance of Express’s missing-body `{}` without calling validators; unknown refs remain required and explicit requestBody metadata overrides it.
@@ -16,7 +16,7 @@ configureAuth({
16
16
  })
17
17
  ```
18
18
 
19
- `_config` is a module-level singleton. All auth functions throw `'[EFC] Auth not configured — pass jwtSecret to ignite()'` if called before `configureAuth`.
19
+ Auth configuration is a process-wide singleton shared by the ESM and CommonJS builds. All auth functions throw `'[EFC] Auth not configured — pass jwtSecret to ignite()'` if called before `configureAuth`.
20
20
 
21
21
  ---
22
22
 
@@ -54,6 +54,14 @@ That's the entire implementation. Clears the cookie. The JWT itself is not inval
54
54
 
55
55
  ---
56
56
 
57
+ ## Generated account-security routes
58
+
59
+ `change-password` checks nonempty string inputs and the authenticated account's current password, hashes and persists the replacement, clears its stored refresh token and expiry, then calls `revokeAllSessions`. Both User and Admin accounts are supported. Success signs out existing access and refresh tokens, including the current access token; revocation errors propagate rather than reporting success. This is generated app code, not a new core auth API.
60
+
61
+ Generated 2FA is app code (`src/lib/two-factor` + routes), not a new core API. Init / `efc add account-security` asks `TWO_FACTOR_METHOD=totp|email|both`; init adds email-client/SMTP prompts for email/both. Users and admins enroll one allowed method. `POST /auth/2fa/setup` with `{ password, method }` starts enrollment (TOTP returns a Base32 secret + otpauthUrl, email returns 202 and queues a code); `{ password, method, code }` confirms. GET returns status/allowed methods only. Confirmation clears refresh credentials and calls `revokeAllSessions`. TOTP: RFC 6238 SHA-1, six digits, 30s ±1, atomic last-step comparison. Email: random six digits, 5m expiry, HMAC digest bound to purpose/account/address, atomic consume. Active/pending TOTP secrets use AES-256-GCM with account identity as AAD and independent 64-hex `TWO_FACTOR_KEY`. Strip active/pending secret, email hash/expiry/purpose and last-step fields from records.
62
+
63
+ Login and `/auth/2fa/verify` share the full password+factor flow and one account rate-limit bucket (10/15m, cache errors reject). No tokens until the factor succeeds; email without code sends only after password verification. Disable needs authentication + password + a fresh code (email without code requests a disable code), erases secrets, and revokes access/refresh tokens. Refresh rotation compare-and-sets old token + enabled state. OAuth rejects 2FA-enabled accounts (use password+code); password reset preserves 2FA. No recovery codes. Device-session list/revoke remain authenticated **501** extension points.
64
+
57
65
  ## Session revocation (`revokeSession`, `revokeAllSessions`) — needs `cache`
58
66
 
59
67
  Every signed token now carries `jti` (randomUUID), `iat`, and `efc_iat` (ms) — via the shared `sign()` used by
@@ -139,3 +147,8 @@ Format accepted by `jose`: `'15m'`, `'1h'`, `'7d'`, `'30d'`, integer seconds, et
139
147
  - No revocation without a `cache` configured (then `revokeToken` just clears the cookie and a copied token stays valid until it expires). With a cache: `revokeSession` / `revokeAllSessions`.
140
148
  - No CSRF token — relies on `SameSite: Strict` for http-only strategy.
141
149
  - No multi-strategy per-route override — `authStrategy` is global, set once in `ignite()`.
150
+
151
+
152
+ Generated User/Admin logout requires authentication, compare-and-sets the account's stored refresh token to empty (including bearer logout with no refresh cookie/body), then revokes the current access token and clears cookies. Login persists refresh credentials only while the password hash still matches its verified snapshot. Generated login/refresh tokens carry `efc_auth_at`, captured before credential reads; revocation rejects a token whose authentication started at or before the cutoff, even if it was signed afterwards. Custom token issuers may include this numeric epoch-millisecond claim for the same protection; it can only restrict access, never override a later server-issued time. Existing generated apps must update their owned auth routes as well as the framework to receive these fixes.
153
+
154
+ Password reset atomically consumes the matching, still-unexpired reset token while replacing the password and clearing stored refresh credentials and pending 2FA challenges. Concurrent use has one winner; expiry is rechecked in the database after hashing. Active 2FA enrollment remains enabled. Password changes also invalidate outstanding reset links. Custom auth-entity logout propagates revocation-store failures instead of returning a false success. Existing apps must update their owned reset-password, change-password, two-factor helper and custom logout files.
@@ -140,3 +140,11 @@ const clusterEnabled = config.cluster ?? (process.env['NODE_ENV'] === 'productio
140
140
  - `config.cluster: false` → **OFF** regardless of NODE_ENV
141
141
 
142
142
  `efc start dev` sets `NODE_ENV=development` → clustering is automatically off in dev.
143
+
144
+ ## PostgreSQL prepared statements (M6)
145
+
146
+ `databasePool.preparedStatements?: boolean | { max?: number }` defaults true/100 names per physical connection; false or max 0 disables (Mongo ignores). A private Pool/client proxy is passed to Drizzle, preserving Pool identity and transaction-client release; exported native `db` is unchanged. Object query configs for single SELECT/INSERT/UPDATE/DELETE/WITH statements get a SQL-shape hash name; parameters/types/rowMode are untouched, explicit names/control/DDL/multi-statements unchanged. Lifetime budget bounds server names, with unnamed fallback (no eviction/DEALLOCATE). Schema sync/drop bumps generation; connection budgets never reset. External DDL requires reconnecting, and incompatible poolers require opting out. `prepared-statements.integration.test.ts` proves reuse, transactions, budget/disable and schema invalidation.
147
+
148
+ `logging.queries.metrics: true | { maxEntries }` enables bounded per-process model/op aggregates (default off; enabled default 1000, zero disables). Main exports `getQueryMetrics`, `resetQueryMetrics`, `QueryMetric`, `QueryMetricsSnapshot`. Snapshots contain counters/latency summaries, since and dropped observations; no SQL/params/error details. Nested statement counts inclusive; reset/reconfigure starts a new window. Not distributed tracing.
149
+
150
+ Since 0.11.0: after route mounting metadata is loaded, optional OpenAPI is generated/served before attaching the API router. The HTTP server is explicitly created, WS upgrades attach when a WS export exists, then it listens. Graceful shutdown drains WS sockets before completing backend shutdown. Origin policy is separate from CORS; middleware/auth runs during upgrade.
@@ -22,7 +22,7 @@ scan.ts: filePathToUrlPath(relativePath)
22
22
 
23
23
  A catch-all must be the LAST segment — `[...slug]/edit.ts` throws at startup. Catch-all
24
24
  routes mount on a compiled RegExp (`RouteEntry.pattern`); a mapper restores named params,
25
- and catch-all values arrive as `string[]` (URI-decoded; `[]` when an optional one is empty).
25
+ and catch-all values arrive as `string[]` (`[]` when an optional one is empty). Split the raw path captures before decoding each segment once: `%2F` stays inside one array item, `%252F` becomes `%2F`, and `%25` becomes `%`. Never decode Express's already-decoded `req.params` again.
26
26
 
27
27
  ### Examples derived from the exact regex
28
28
 
@@ -112,3 +112,7 @@ Files that do NOT match this pattern are silently ignored by `scanDir`.
112
112
  Header: `Allow: GET, POST` (only the implemented methods).
113
113
 
114
114
  **Only sent when at least one method IS implemented.** A file that exports no HTTP methods gets no 405 handler — Express would return 404.
115
+
116
+ Since 0.11.0, `WS` exports mount upgrade-only handlers on the same paths; HTTP methods skip upgrade requests. File/global middleware and named params apply, then `schema.WS` validation, then the connection handler. OpenAPI documents HTTP exports only; optional path segments expand into separate required-path variants.
117
+
118
+ OpenAPI optional variants deduplicate equivalent template shapes using greedy earlier-parameter bindings; conflicting names across separate routes fail generation. Document URL collision checks use actual Express GET/HEAD matchers, including hidden routes. Query object combinators retain fields and requirements; object query fields serialize as deepObject. WS drain destroys pending handshakes; pipelined upgrades behind an active HTTP response close safely.
@@ -17,7 +17,7 @@ import { ... } from 'express-file-cluster/config'
17
17
  import { ... } from 'express-file-cluster/models'
18
18
  ```
19
19
 
20
- Only three sub-paths exist: (no suffix), `/auth`, `/tasks`.
20
+ Four import paths exist: (no suffix), `/auth`, `/tasks`, `/testing`. `/testing` exports `createTestApp` and `TestAppOptions`; it does not boot services or mock databases/tasks.
21
21
 
22
22
  ---
23
23
 
@@ -26,6 +26,7 @@ Only three sub-paths exist: (no suffix), `/auth`, `/tasks`.
26
26
  ```ts
27
27
  // ❌ NOT exported from any EFC path
28
28
  createApp()
29
+ createTestApp() // ← EXISTS only from express-file-cluster/testing; apiDir is test-only
29
30
  createServer()
30
31
  useMiddleware()
31
32
  addRoute()
@@ -213,6 +214,13 @@ refreshToken() // does NOT exist as a core export
213
214
  // revokeToken(res) still ONLY clears the cookie.
214
215
  // ❌ No refresh-token rotation or session listing ("show my active devices") in core
215
216
 
217
+ // ✅ Generated 2FA supports TOTP/email OTP (init asks totp|email|both; each account chooses one).
218
+ // Enrollment/disable require current password; login verifies password + factor before tokens.
219
+ // Independent TWO_FACTOR_KEY encrypts secrets; codes are atomically consumed. This is app
220
+ // code, not a new core auth export. No recovery codes or automated lost-device recovery.
221
+ // ❌ Device-session list/revoke routes still return 501. Password changes DO verify
222
+ // the old password, persist a hash, and revoke access/refresh tokens.
223
+
216
224
  // ❌ No per-route strategy override
217
225
  // authStrategy is global — set once in ignite()
218
226
  ```
@@ -267,3 +275,5 @@ const conn = db.model('User') // throws: db not ready
267
275
  // ❌ With autoSync: false, using a model before `efc db sync` / a migration created its table
268
276
  // → "[EFC] <Model>: table "<t>" does not exist — autoSync is off…"
269
277
  ```
278
+
279
+ Since 0.11.0, WebSockets and OpenAPI are implemented. Read the new guides/API references before using them. Use `WS` file exports and `ignite({openapi})`/`generateOpenAPI`, with the four existing import paths only. No Socket.IO protocol, cross-worker broadcast bus, message-schema validator, Swagger UI, or automatic auth-policy inference is provided.
@@ -18,7 +18,7 @@ Deprecations are announced at least one minor release before removal, with a sta
18
18
  - **Major** (1.x → 2.0): breaking changes only, each with upgrade steps.
19
19
  - **Minor** (1.1 → 1.2): new features, backwards compatible.
20
20
  - **Patch** (1.1.0 → 1.1.1): fixes and security fixes only.
21
- - The three import paths (`express-file-cluster`, `/auth`, `/tasks`) and everything they export are the public API. Anything else — internal modules, generated file layouts, log message wording — can change in a minor.
21
+ - The four import paths (`express-file-cluster`, `/auth`, `/tasks`, `/testing`) and everything they export are the public API. Anything else — internal modules, generated file layouts, log message wording — can change in a minor.
22
22
 
23
23
  ## Long-term support (from 1.0)
24
24