express-file-cluster 0.9.6 → 0.10.2

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 (233) 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 +1 -1
  4. package/dist/auth/index.d.ts +1 -1
  5. package/dist/auth/index.js +5 -5
  6. package/dist/chunk-3SWI46YK.js +74 -0
  7. package/dist/chunk-3SWI46YK.js.map +1 -0
  8. package/dist/{chunk-DCJOWFVD.cjs → chunk-4GHK27JA.cjs} +3 -3
  9. package/dist/{chunk-DCJOWFVD.cjs.map → chunk-4GHK27JA.cjs.map} +1 -1
  10. package/dist/{chunk-NI2BNGGV.js → chunk-5LPRKZPB.js} +2 -2
  11. package/dist/chunk-74BSJXWD.cjs +220 -0
  12. package/dist/chunk-74BSJXWD.cjs.map +1 -0
  13. package/dist/{chunk-6KHBJOLB.cjs → chunk-7BC3AN7R.cjs} +14 -14
  14. package/dist/{chunk-6KHBJOLB.cjs.map → chunk-7BC3AN7R.cjs.map} +1 -1
  15. package/dist/chunk-AGOYTFRO.cjs +42 -0
  16. package/dist/chunk-AGOYTFRO.cjs.map +1 -0
  17. package/dist/{chunk-HBYSKULC.js → chunk-B6MB6HEG.js} +5 -1
  18. package/dist/chunk-B6MB6HEG.js.map +1 -0
  19. package/dist/{chunk-OFA7OGN5.js → chunk-BG4A7Z32.js} +176 -7
  20. package/dist/chunk-BG4A7Z32.js.map +1 -0
  21. package/dist/{chunk-45BWAR6P.js → chunk-C2FOZ7ME.js} +4 -4
  22. package/dist/chunk-CGY7JU4Y.cjs +8 -0
  23. package/dist/chunk-CGY7JU4Y.cjs.map +1 -0
  24. package/dist/{chunk-BBSZLGZW.js → chunk-DN4TCGYB.js} +43 -14
  25. package/dist/chunk-DN4TCGYB.js.map +1 -0
  26. package/dist/{chunk-TI24L4XE.cjs → chunk-H2PVWCWC.cjs} +6 -2
  27. package/dist/chunk-H2PVWCWC.cjs.map +1 -0
  28. package/dist/{chunk-TYCYYLLM.cjs → chunk-IUZ6A7PB.cjs} +20 -53
  29. package/dist/chunk-IUZ6A7PB.cjs.map +1 -0
  30. package/dist/{chunk-DUADUR6R.cjs → chunk-JP36TLL4.cjs} +171 -14
  31. package/dist/chunk-JP36TLL4.cjs.map +1 -0
  32. package/dist/chunk-KLWL7XSC.js +220 -0
  33. package/dist/chunk-KLWL7XSC.js.map +1 -0
  34. package/dist/{chunk-QL6EWT4B.cjs → chunk-M53GODCX.cjs} +44 -15
  35. package/dist/chunk-M53GODCX.cjs.map +1 -0
  36. package/dist/{chunk-7ZESZG3J.js → chunk-MUVO7MGS.js} +4 -4
  37. package/dist/{chunk-VWSUQKCJ.cjs → chunk-R2K7AFIB.cjs} +286 -117
  38. package/dist/chunk-R2K7AFIB.cjs.map +1 -0
  39. package/dist/{chunk-ULWNHN6P.js → chunk-RETV3GKE.js} +9 -42
  40. package/dist/chunk-RETV3GKE.js.map +1 -0
  41. package/dist/{chunk-7YEX4MQV.cjs → chunk-RPL2IFWK.cjs} +46 -7
  42. package/dist/chunk-RPL2IFWK.cjs.map +1 -0
  43. package/dist/{chunk-FMA76PRH.cjs → chunk-TBIVIR6L.cjs} +15 -15
  44. package/dist/{chunk-FMA76PRH.cjs.map → chunk-TBIVIR6L.cjs.map} +1 -1
  45. package/dist/{chunk-73XJUT2S.js → chunk-V73R76I4.js} +162 -5
  46. package/dist/chunk-V73R76I4.js.map +1 -0
  47. package/dist/chunk-XPY5TQDK.js +42 -0
  48. package/dist/chunk-XPY5TQDK.js.map +1 -0
  49. package/dist/{chunk-RGT4ZVHL.cjs → chunk-Y4NKIXUL.cjs} +110 -55
  50. package/dist/chunk-Y4NKIXUL.cjs.map +1 -0
  51. package/dist/{chunk-2SETEVMO.js → chunk-Y75V5FCU.js} +100 -45
  52. package/dist/chunk-Y75V5FCU.js.map +1 -0
  53. package/dist/cli/db-runner.cjs +2059 -126
  54. package/dist/cli/db-runner.cjs.map +1 -1
  55. package/dist/cli/db-runner.js +2034 -102
  56. package/dist/cli/db-runner.js.map +1 -1
  57. package/dist/cli/index.cjs +50 -29
  58. package/dist/cli/index.cjs.map +1 -1
  59. package/dist/cli/index.js +39 -21
  60. package/dist/cli/index.js.map +1 -1
  61. package/dist/docs/api-reference/auth.md +23 -0
  62. package/dist/docs/api-reference/collection.md +44 -1
  63. package/dist/docs/api-reference/compose.md +1 -1
  64. package/dist/docs/api-reference/db.md +8 -0
  65. package/dist/docs/api-reference/ignite.md +13 -1
  66. package/dist/docs/api-reference/testing.md +26 -0
  67. package/dist/docs/api-reference/types.md +99 -0
  68. package/dist/docs/cli/add.md +2 -2
  69. package/dist/docs/cli/db.md +2 -2
  70. package/dist/docs/core-concepts/background-tasks.md +6 -3
  71. package/dist/docs/core-concepts/file-based-routing.md +2 -0
  72. package/dist/docs/core-concepts/middleware.md +2 -2
  73. package/dist/docs/getting-started/index.md +6 -1
  74. package/dist/docs/guides/authentication.md +33 -0
  75. package/dist/docs/guides/caching.md +34 -1
  76. package/dist/docs/guides/database.md +17 -0
  77. package/dist/docs/guides/environment-variables.md +6 -0
  78. package/dist/docs/guides/feature-matrix.md +58 -0
  79. package/dist/docs/guides/generated-portals.md +3 -1
  80. package/dist/docs/guides/logging.md +17 -0
  81. package/dist/docs/guides/migrations.md +26 -3
  82. package/dist/docs/guides/testing.md +31 -0
  83. package/dist/docs/guides/which-api.md +2 -2
  84. package/dist/docs/index.md +4 -1
  85. package/dist/docs/skills/SKILL.md +5 -1
  86. package/dist/docs/skills/api-surface.md +25 -4
  87. package/dist/docs/skills/auth-internals.md +14 -1
  88. package/dist/docs/skills/pre-flight.md +6 -0
  89. package/dist/docs/skills/routing-rules.md +1 -1
  90. package/dist/docs/skills/tasks-internals.md +4 -3
  91. package/dist/docs/skills/what-not-to-invent.md +13 -4
  92. package/dist/docs/versioning.md +1 -1
  93. package/dist/index.cjs +135 -255
  94. package/dist/index.cjs.map +1 -1
  95. package/dist/index.d.cts +228 -3
  96. package/dist/index.d.ts +228 -3
  97. package/dist/index.js +96 -217
  98. package/dist/index.js.map +1 -1
  99. package/dist/pgboss-backend-4X2YT4RB.js +14 -0
  100. package/dist/pgboss-backend-UXQ3O2WT.cjs +15 -0
  101. package/dist/pgboss-backend-UXQ3O2WT.cjs.map +1 -0
  102. package/dist/registry/index.json +39 -3
  103. package/dist/registry/js-mongo/account-security.json +1 -1
  104. package/dist/registry/js-mongo/admin-users.json +1 -1
  105. package/dist/registry/js-mongo/auth.json +1 -1
  106. package/dist/registry/js-mongo/auth@apple.json +1 -1
  107. package/dist/registry/js-mongo/auth@google.json +1 -1
  108. package/dist/registry/js-mongo/forgot-password.json +1 -1
  109. package/dist/registry/js-mongo/user-profile.json +1 -1
  110. package/dist/registry/js-mongo-collection/_base.json +1 -0
  111. package/dist/registry/js-mongo-collection/account-security.json +1 -0
  112. package/dist/registry/js-mongo-collection/account-settings.json +1 -0
  113. package/dist/registry/js-mongo-collection/admin-admins.json +1 -0
  114. package/dist/registry/js-mongo-collection/admin-analytics.json +1 -0
  115. package/dist/registry/js-mongo-collection/admin-billing.json +1 -0
  116. package/dist/registry/js-mongo-collection/admin-content.json +1 -0
  117. package/dist/registry/js-mongo-collection/admin-logs.json +1 -0
  118. package/dist/registry/js-mongo-collection/admin-support.json +1 -0
  119. package/dist/registry/js-mongo-collection/admin-system.json +1 -0
  120. package/dist/registry/js-mongo-collection/admin-users.json +1 -0
  121. package/dist/registry/js-mongo-collection/admin.json +1 -0
  122. package/dist/registry/js-mongo-collection/auth.json +1 -0
  123. package/dist/registry/js-mongo-collection/auth@apple.json +1 -0
  124. package/dist/registry/js-mongo-collection/auth@google.json +1 -0
  125. package/dist/registry/js-mongo-collection/billing.json +1 -0
  126. package/dist/registry/js-mongo-collection/email-client.json +1 -0
  127. package/dist/registry/js-mongo-collection/email-verification.json +1 -0
  128. package/dist/registry/js-mongo-collection/files.json +1 -0
  129. package/dist/registry/js-mongo-collection/forgot-password.json +1 -0
  130. package/dist/registry/js-mongo-collection/notifications.json +1 -0
  131. package/dist/registry/js-mongo-collection/support.json +1 -0
  132. package/dist/registry/js-mongo-collection/user-profile.json +1 -0
  133. package/dist/registry/js-pg-model/account-security.json +1 -1
  134. package/dist/registry/js-pg-model/admin-users.json +1 -1
  135. package/dist/registry/js-pg-model/auth.json +1 -1
  136. package/dist/registry/js-pg-model/auth@apple.json +1 -1
  137. package/dist/registry/js-pg-model/auth@google.json +1 -1
  138. package/dist/registry/js-pg-model/forgot-password.json +1 -1
  139. package/dist/registry/js-pg-model/user-profile.json +1 -1
  140. package/dist/registry/js-pg-table/account-security.json +1 -1
  141. package/dist/registry/js-pg-table/admin-users.json +1 -1
  142. package/dist/registry/js-pg-table/auth.json +1 -1
  143. package/dist/registry/js-pg-table/auth@apple.json +1 -1
  144. package/dist/registry/js-pg-table/auth@google.json +1 -1
  145. package/dist/registry/js-pg-table/forgot-password.json +1 -1
  146. package/dist/registry/js-pg-table/user-profile.json +1 -1
  147. package/dist/registry/ts-mongo/account-security.json +1 -1
  148. package/dist/registry/ts-mongo/admin-users.json +1 -1
  149. package/dist/registry/ts-mongo/auth.json +1 -1
  150. package/dist/registry/ts-mongo/auth@apple.json +1 -1
  151. package/dist/registry/ts-mongo/auth@google.json +1 -1
  152. package/dist/registry/ts-mongo/forgot-password.json +1 -1
  153. package/dist/registry/ts-mongo/user-profile.json +1 -1
  154. package/dist/registry/ts-mongo-collection/_base.json +1 -0
  155. package/dist/registry/ts-mongo-collection/account-security.json +1 -0
  156. package/dist/registry/ts-mongo-collection/account-settings.json +1 -0
  157. package/dist/registry/ts-mongo-collection/admin-admins.json +1 -0
  158. package/dist/registry/ts-mongo-collection/admin-analytics.json +1 -0
  159. package/dist/registry/ts-mongo-collection/admin-billing.json +1 -0
  160. package/dist/registry/ts-mongo-collection/admin-content.json +1 -0
  161. package/dist/registry/ts-mongo-collection/admin-logs.json +1 -0
  162. package/dist/registry/ts-mongo-collection/admin-support.json +1 -0
  163. package/dist/registry/ts-mongo-collection/admin-system.json +1 -0
  164. package/dist/registry/ts-mongo-collection/admin-users.json +1 -0
  165. package/dist/registry/ts-mongo-collection/admin.json +1 -0
  166. package/dist/registry/ts-mongo-collection/auth.json +1 -0
  167. package/dist/registry/ts-mongo-collection/auth@apple.json +1 -0
  168. package/dist/registry/ts-mongo-collection/auth@google.json +1 -0
  169. package/dist/registry/ts-mongo-collection/billing.json +1 -0
  170. package/dist/registry/ts-mongo-collection/email-client.json +1 -0
  171. package/dist/registry/ts-mongo-collection/email-verification.json +1 -0
  172. package/dist/registry/ts-mongo-collection/files.json +1 -0
  173. package/dist/registry/ts-mongo-collection/forgot-password.json +1 -0
  174. package/dist/registry/ts-mongo-collection/notifications.json +1 -0
  175. package/dist/registry/ts-mongo-collection/support.json +1 -0
  176. package/dist/registry/ts-mongo-collection/user-profile.json +1 -0
  177. package/dist/registry/ts-pg-model/account-security.json +1 -1
  178. package/dist/registry/ts-pg-model/admin-users.json +1 -1
  179. package/dist/registry/ts-pg-model/auth.json +1 -1
  180. package/dist/registry/ts-pg-model/auth@apple.json +1 -1
  181. package/dist/registry/ts-pg-model/auth@google.json +1 -1
  182. package/dist/registry/ts-pg-model/forgot-password.json +1 -1
  183. package/dist/registry/ts-pg-model/user-profile.json +1 -1
  184. package/dist/registry/ts-pg-table/account-security.json +1 -1
  185. package/dist/registry/ts-pg-table/admin-users.json +1 -1
  186. package/dist/registry/ts-pg-table/auth.json +1 -1
  187. package/dist/registry/ts-pg-table/auth@apple.json +1 -1
  188. package/dist/registry/ts-pg-table/auth@google.json +1 -1
  189. package/dist/registry/ts-pg-table/forgot-password.json +1 -1
  190. package/dist/registry/ts-pg-table/user-profile.json +1 -1
  191. package/dist/tasks/index.cjs +5 -2
  192. package/dist/tasks/index.cjs.map +1 -1
  193. package/dist/tasks/index.d.cts +4 -2
  194. package/dist/tasks/index.d.ts +4 -2
  195. package/dist/tasks/index.js +3 -1
  196. package/dist/testing-cjs.cjs +5 -0
  197. package/dist/testing.cjs +59 -0
  198. package/dist/testing.cjs.map +1 -0
  199. package/dist/testing.d.cts +27 -0
  200. package/dist/testing.d.ts +27 -0
  201. package/dist/testing.js +58 -0
  202. package/dist/testing.js.map +1 -0
  203. package/dist/thread-runner.cjs +9 -0
  204. package/dist/thread-runner.cjs.map +1 -0
  205. package/dist/thread-runner.d.cts +3 -0
  206. package/dist/thread-runner.d.ts +3 -0
  207. package/dist/thread-runner.js +8 -0
  208. package/dist/thread-runner.js.map +1 -0
  209. package/dist/{types-DAsBKVM-.d.ts → types-CPMFTVXm.d.cts} +15 -1
  210. package/dist/{types-DAsBKVM-.d.cts → types-CPMFTVXm.d.ts} +15 -1
  211. package/package.json +6 -1
  212. package/dist/chunk-2SETEVMO.js.map +0 -1
  213. package/dist/chunk-73XJUT2S.js.map +0 -1
  214. package/dist/chunk-7YEX4MQV.cjs.map +0 -1
  215. package/dist/chunk-BBSZLGZW.js.map +0 -1
  216. package/dist/chunk-DUADUR6R.cjs.map +0 -1
  217. package/dist/chunk-HBYSKULC.js.map +0 -1
  218. package/dist/chunk-LJNSJFOL.js +0 -38
  219. package/dist/chunk-LJNSJFOL.js.map +0 -1
  220. package/dist/chunk-OFA7OGN5.js.map +0 -1
  221. package/dist/chunk-QL6EWT4B.cjs.map +0 -1
  222. package/dist/chunk-RGT4ZVHL.cjs.map +0 -1
  223. package/dist/chunk-TI24L4XE.cjs.map +0 -1
  224. package/dist/chunk-TYCYYLLM.cjs.map +0 -1
  225. package/dist/chunk-ULWNHN6P.js.map +0 -1
  226. package/dist/chunk-VWSUQKCJ.cjs.map +0 -1
  227. package/dist/pgboss-backend-DSO3QTNK.cjs +0 -14
  228. package/dist/pgboss-backend-DSO3QTNK.cjs.map +0 -1
  229. package/dist/pgboss-backend-I6DFUNRM.js +0 -14
  230. /package/dist/{chunk-NI2BNGGV.js.map → chunk-5LPRKZPB.js.map} +0 -0
  231. /package/dist/{chunk-45BWAR6P.js.map → chunk-C2FOZ7ME.js.map} +0 -0
  232. /package/dist/{chunk-7ZESZG3J.js.map → chunk-MUVO7MGS.js.map} +0 -0
  233. /package/dist/{pgboss-backend-I6DFUNRM.js.map → pgboss-backend-4X2YT4RB.js.map} +0 -0
@@ -17,13 +17,15 @@ The user and admin portals are a set of **registry items**: ready-made models an
17
17
 
18
18
  ---
19
19
 
20
+ The route inventory includes extension points as well as implemented handlers. In `account-security`, password changes, refresh rotation and 2FA (TOTP/email OTP) work. Init asks which methods the app allows; users enroll one of them. Device-session list/revoke still return **501 Not Implemented** until you connect a device-session store. See [the 2FA flow](./authentication.md#two-factor-authentication-totp-or-email-otp). Other portal templates can also contain TODOs and need application logic before use.
21
+
20
22
  ## User portal
21
23
 
22
24
  | Item | Routes below |
23
25
  |---|---|
24
26
  | `user-profile` | Profile: `/user/profile` |
25
27
  | `forgot-password` | Auth: forgot / reset password |
26
- | `account-security` | Auth: refresh, change password, 2FA, sessions (+ `Session`) |
28
+ | `account-security` | Auth: refresh, change password, TOTP/email OTP; 501 device-session extension points (+ `Session` model) |
27
29
  | `email-verification` | Auth: verify email |
28
30
  | `account-settings` | Profile: avatar, settings, account, dashboard, activity |
29
31
  | `notifications` | Notifications (+ `Notification`) |
@@ -106,3 +106,20 @@ Unhandled errors are logged at `error` with the request ID and full stack (`err`
106
106
  ## Shipping logs
107
107
 
108
108
  JSON lines on stdout is what log collectors (Datadog, Loki, CloudWatch, Vector) expect — no transport configuration needed. For custom pino transports, set `pretty: false` and pipe stdout.
109
+
110
+ ## Query metrics
111
+
112
+ Opt in with `logging: { queries: { metrics: true } }`, or `{ metrics: { maxEntries: 500 } }`. The default limit when enabled is 1000 distinct model/operation pairs per worker process; zero disables metrics. Logging and slow/N+1 options remain independent.
113
+
114
+ ```ts
115
+ import { getQueryMetrics, resetQueryMetrics } from 'express-file-cluster';
116
+
117
+ const snapshot = getQueryMetrics();
118
+ // { enabled, since, dropped, entries: [{ model, op, calls, errors, statements,
119
+ // totalMs, minMs, maxMs, meanMs, slow }] }
120
+ resetQueryMetrics(); // optional: start a fresh window without disabling collection
121
+ ```
122
+
123
+ Snapshots are detached from internal state and contain no SQL, parameter values, error details or request IDs. Each entry aggregates completed calls, failures, inclusive statement counts and durations in milliseconds. Nested model calls retain their own entries; their statements also count toward the outer operation, so summing entries is not a global database statement total. `slow` counts calls at or above `slowMs`.
124
+
125
+ When the entry limit is reached, existing pairs keep updating; observations for new pairs increment `dropped`. Reset/reconfiguration clears entries, dropped counts and the `since` timestamp. Metrics are off by default. These are per-process counters, not a cluster-wide service or an OpenTelemetry exporter; collect from each worker/instance separately and secure any diagnostic endpoint you add.
@@ -10,8 +10,8 @@
10
10
  | `efc db status` | Lists applied (with batch) and pending migrations |
11
11
  | `efc db seed [name]` | Runs every seed in `src/seeds/`, or just one |
12
12
  | `efc db sync [--dry-run] [--exit-code]` | Brings the database in line with the models (or reports what would change) |
13
- | `efc db pull` | Writes `defineTable` models for an existing PostgreSQL database |
14
- | `efc db studio [-p 4983]` | Opens a read-only database browser on `127.0.0.1` |
13
+ | `efc db pull` | Writes `defineTable` models for an existing PostgreSQL database, `defineCollection` models for a MongoDB one |
14
+ | `efc db studio [-p 4983] [--write]` | Opens a database browser on `127.0.0.1` — read-only unless `--write` |
15
15
 
16
16
  All of them read `DATABASE_URL` from the environment or `.env` (override with `--database-url`); the engine follows the URL scheme.
17
17
 
@@ -117,7 +117,26 @@ efc db pull --out pulled # somewhere else, to compare
117
117
  - **Indexes:** unique, plain, compound and text indexes.
118
118
  - **Relations:** foreign keys become `ref`s with `onDelete`. A column like `authorId` becomes an `author` field that keeps the `authorId` column. EFC join tables become many-to-many arrays, and every target model gets back-`relations`.
119
119
 
120
- A schema EFC created pulls back to models that sync finds nothing to change in. For a schema EFC didn't create, anything that has no EFC equivalent is noted at the top of the file: expression or partial indexes, other CHECKs, composite keys, and other defaults. Existing files are kept unless you pass `--force`.
120
+ A schema EFC created pulls back to models that sync finds nothing to change in. For a schema EFC didn't create, anything that has no EFC equivalent is noted at the top of the file: expression or partial indexes, other CHECKs, composite keys, and other defaults.
121
+
122
+ Models already in the output directory keep their names: a table one of them maps (`AuditLog` → `auditlogs`) is pulled under that name, so refs to it name it too, and it's never written to a second file. Existing files are kept unless you pass `--force`, which refreshes a model in its own `<Model>.ts` but never overwrites a model defined in another file, or a file whose name differs only in case (the same file on macOS and Windows).
123
+
124
+ ## Pulling an existing database (MongoDB)
125
+
126
+ ```bash
127
+ efc db pull # → src/model/<Model>.ts + index.ts (defineCollection)
128
+ efc db pull --sample 5000 # sample more documents per collection (default 1000)
129
+ ```
130
+
131
+ MongoDB has no schema to read, so `pull` samples each collection (`$sample`) and infers one from the documents:
132
+
133
+ - **Types:** `string`, `number`, `boolean`, `date`, `objectId`, `decimal128`, `long`, `binary` and GeoJSON points (`geoPoint`); embedded objects become nested schemas, arrays of objects `[{ … }]`, other arrays `{ type: 'array', of }`.
134
+ - **Required:** only when every sampled document had a non-null value. A field with mixed types (or only nulls) becomes `{ type: 'object' }` (any value) with a note.
135
+ - **Refs:** an `objectId` field gets `ref` when its name matches another collection (`owner`, `ownerId` → `Owner`) or when every sampled id exists in exactly one other collection; otherwise a note asks you to add it.
136
+ - **Indexes:** single-field unique, plain, `text`, `2dsphere` and `hashed` indexes go on the field; compound, partial and TTL indexes into `indexes`.
137
+ - **Names and timestamps:** a model per collection (`audit_log` → `AuditLog`, with `collection: 'audit_log'` when mongoose wouldn't pick that name); `createdAt`/`updatedAt` dates map to the default `timestamps`, otherwise `timestamps: false`. Existing models in the output directory keep their names here too, as for PostgreSQL.
138
+
139
+ `_id` and `__v` are left to defineCollection. Read the generated files before using them: a sample shows what the data *has*, not what it must have.
121
140
 
122
141
  `required` and `default` live in the model, not the database. A table created by `sync` or a migration without `--tighten` has nullable columns and no defaults, so its fields pull back as optional. Generate with `--tighten` if you want `required` enforced (and pulled back).
123
142
 
@@ -215,3 +234,7 @@ CMD ["sh", "-c", "npx efc db migrate --dist && npx efc start prod"]
215
234
  ## Studio
216
235
 
217
236
  `efc db studio` serves a read-only browser at `http://127.0.0.1:4983`: every table/collection with its row count, paginated rows, and expandable JSON cells. It binds to localhost only and rejects anything but `GET`.
237
+
238
+ `efc db studio --write` adds **Insert**, **edit** (✎) and **Delete**. Writes go through your models in `src/model`, so validation, defaults, casting and timestamps apply exactly as in your app; a validation error is shown next to the editor. Tables or collections that no model stores in stay read-only. Ids, `createdAt`/`updatedAt` and `__v` are never written from the editor.
239
+
240
+ Only the studio page can write: every write must carry a random token embedded in that page, come from the studio's own origin, and be JSON — so another site open in your browser can't reach it. Writes change real data; point `DATABASE_URL` at a development database.
@@ -0,0 +1,31 @@
1
+ # Testing file-based routes
2
+
3
+ `createTestApp()` from `express-file-cluster/testing` mounts your real route files on an Express app. Use it with supertest or another HTTP test harness. It shares the production HTTP middleware, router and error handler with `ignite()`, including JSON/form/cookie parsing, request context, validation, catch-all decoding and 405 handling.
4
+
5
+ ```ts
6
+ import { createTestApp } from 'express-file-cluster/testing';
7
+ import request from 'supertest';
8
+ import path from 'node:path';
9
+
10
+ const app = await createTestApp({
11
+ apiDir: path.resolve('src/api'),
12
+ auth: { secret: 'test-only-secret', strategy: 'bearer' },
13
+ });
14
+
15
+ const response = await request(app).get('/v1/api/health');
16
+ expect(response.status).toBe(200);
17
+ ```
18
+
19
+ Install the test harness in your app (`npm i -D supertest @types/supertest`). Your test runner must be able to import the route files: Configure the runner/loader to transform dynamically imported TypeScript routes when needed; a plain Node process can point at built JavaScript or use a TypeScript loader.
20
+
21
+ `apiDir` is required and must be an existing directory. It is specific to this helper; `ignite()` still discovers `src/api` by convention and has no `apiDir` option. Creating multiple apps does not change the working directory. Each app has its own router and middleware stack.
22
+
23
+ The helper returns an Express app without calling `listen()`, forking workers, scanning tasks, initializing database/cache/queue services, or adding signal handlers. It disables CORS and logging for tests and omits the development dashboard. Supertest can open its own temporary HTTP listener when making a request. For database and queue tests, configure real service fixtures separately, or use `ignite()` to exercise the complete boot lifecycle. The helper does not provide model mocks or an `enqueue()` implementation.
24
+
25
+ Authentication and logging are process-wide in EFC. The helper disables the process logger and configures auth when `auth` is supplied; use one auth configuration per test process, and isolate suites that require different secrets/strategies. Calling the helper without `auth` does not reset an existing auth configuration. Imported route modules follow normal module caching. Global model/cache/task state is not reset between apps.
26
+
27
+ See the [API reference](../api-reference/testing.md) for all options.
28
+
29
+ The CommonJS `/testing` entry delegates to the ESM helper using native `import()`, so dynamically imported ESM routes share its authentication and request context. The Node/runner must support the route files' module format.
30
+
31
+ The ESM and CommonJS builds share process-wide auth configuration, request AsyncLocalStorage and cache state. CommonJS `requireAuth` global middleware therefore sees helper auth options, preserves `getCurrentUser()` across awaits into ESM routes, and observes the same revocations. Model/queue fixtures are still configured separately.
@@ -8,12 +8,12 @@ EFC has three ways to define a model. They share one foundation: the schema form
8
8
  | Queries | portable subset: `find(filter, { sort, limit, populate })`, `$set`, `$inc` | Prisma-style: `findMany({ where, include, orderBy, take, cursor })`, `findUnique`, `upsert`, `groupBy`, `aggregate` | mongoose-style: every query operator, `find(filter, { projection })`, `findOneAndUpdate`, `bulkWrite`, `aggregate(pipeline)`, `watch` |
9
9
  | Relations | `ref` + `populate` (a plain column on PostgreSQL) | real foreign keys, many-to-many join tables, `include` in one SQL statement, relation filters, nested writes | `ref` + `populate`, `$lookup`, embedded documents |
10
10
  | Field types | the portable set (`string`, `number`, `boolean`, `date`, `objectId`, objects, arrays) | + `integer`, `bigint`, `decimal`, `uuid`, `json`, `varchar`, native arrays and enums, `serial` ids | + `decimal128`, `long`, `geoPoint`, `binary`; `2dsphere`, `text`, `hashed` and partial indexes |
11
- | Migrations | auto-sync, `efc db generate` | auto-sync, `efc db generate`, `efc db pull`, `efc import-prisma` | auto-sync, `efc db generate` |
11
+ | Migrations | auto-sync, `efc db generate` | auto-sync, `efc db generate`, `efc db pull`, `efc import-prisma` | auto-sync, `efc db generate`, `efc db pull` |
12
12
  | Wrong engine | — | fails at first use with an `[EFC]` error naming the model | the same |
13
13
 
14
14
  ## Pick one
15
15
 
16
- - **Building on PostgreSQL:** use `defineTable`. You get foreign keys, joins and SQL types. `create-efc-app` generates `defineTable` models for PostgreSQL apps.
16
+ - **Building on PostgreSQL:** use `defineTable`. You get foreign keys, joins and SQL types. `create-efc-app` generates `defineTable` models for PostgreSQL apps (and `defineCollection` for MongoDB apps).
17
17
  - **Building on MongoDB:** use `defineCollection`. You get the full query language, geo and text search, BSON types, `bulkWrite` and change streams. It is mongoose underneath (`raw()` hands you the mongoose model).
18
18
  - **The app may switch engines, or ships to both:** use `defineModel` and stay inside the shared filter and update subset (`$eq $ne $gt $gte $lt $lte $in $nin $exists $regex $and $or`; `$set $unset $inc $push $pull`).
19
19
  - **Coming from Prisma:** use `defineTable`. `efc import-prisma` writes the models for you. See [Coming from Prisma](./coming-from-prisma.md).
@@ -2,7 +2,7 @@
2
2
 
3
3
  **express-file-cluster (EFC)** is an opinionated backend framework built on Express. It removes routing ceremony, saturates every CPU core automatically, and ships a production-grade background-task subsystem — all from a single `ignite()` call.
4
4
 
5
- > **Status: v0.9.6 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, migrations (written for you from model changes: `efc db generate`, plus `efc db pull` and `efc import-prisma`), and the `efc add` feature registry (auth, admin, billing… copied into your app as source you own) are all implemented.
5
+ > **Status: v0.10.2 — Beta.** File-based routing (incl. catch-all and optional segments), request validation, clustering, auth, structured logging, MongoDB and PostgreSQL models with types inferred from the schema, PostgreSQL-native `defineTable` (Prisma-style queries and relations: foreign keys, many-to-many, `include`, relation filters, nested writes), query logging, BullMQ and pg-boss tasks with cron and dead-letter tooling, migrations (written for you from model changes: `efc db generate`, plus `efc db pull` and `efc import-prisma`), and the `efc add` feature registry (auth, admin, billing… copied into your app as source you own) are all implemented.
6
6
 
7
7
  ---
8
8
 
@@ -39,12 +39,15 @@
39
39
  | [RBAC](./guides/rbac.md) | Role-based route protection via the `requireAuth('role')` shorthand |
40
40
  | [Database](./guides/database.md) | `defineModel`, queries, transactions, MongoDB vs PostgreSQL |
41
41
  | [Which model API?](./guides/which-api.md) | `defineModel` vs `defineTable` vs `defineCollection`, and moving between them |
42
+ | [Feature matrix](./guides/feature-matrix.md) | What each model API does on which engine, with the test that proves each row |
43
+ | [Type inference](./api-reference/types.md) | What every schema type becomes in records and inputs, ids, timestamps, typed queries |
42
44
  | [Relations](./guides/relations.md) | Foreign keys, many-to-many, `include`, relation filters, nested writes |
43
45
  | [defineTable](./api-reference/table.md) | PostgreSQL-native models: Prisma-style queries, SQL types, aggregation |
44
46
  | [defineCollection](./api-reference/collection.md) | MongoDB-native models: mongoose-style queries, BSON types, geo, bulk writes, change streams |
45
47
  | [Migrations & Seeds](./guides/migrations.md) | `efc db generate / migrate / rollback / pull / seed / studio`, drift checks |
46
48
  | [Coming from Prisma](./guides/coming-from-prisma.md) | `efc import-prisma`, schema and query mapping |
47
49
  | [Coming from mongoose](./guides/coming-from-mongoose.md) | `defineCollection` for mongoose users: schema and query mapping |
50
+ | [Testing](./guides/testing.md) | `createTestApp` for real file-based routes without service boot |
48
51
  | [Validation](./guides/validation.md) | Route `schema` exports with zod, valibot, arktype |
49
52
  | [Logging](./guides/logging.md) | pino, request IDs, `getLogger()` |
50
53
  | [Caching & Sessions](./guides/caching.md) | `cache`, `cacheResponse`, revoking JWT sessions |
@@ -37,8 +37,12 @@ Load **only** the module the work points to. Each is self-contained.
37
37
  docs/ ← full documentation
38
38
  ```
39
39
 
40
- ## Status (v0.9.6 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
40
+ ## Status (v0.10.2 — 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
44
  **Not yet implemented (Phase 3+):** WebSockets, plugins, OpenAPI generation, 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.
@@ -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
 
@@ -81,6 +87,11 @@ const cache: {
81
87
  clear(prefix?): Promise<number>;
82
88
  }
83
89
  function cacheResponse(ttl: number | { ttl; perUser?: boolean; key?: (req) => string }): RequestHandler
90
+ // Fixed window counted with cache.incr — one limit across workers (memory) / instances (redis).
91
+ // key defaults to req.ip: behind a proxy set ignite({ trustProxy }) or everyone shares one bucket.
92
+ function rateLimit(o: { window: number | '15m'; max: number; key?: (req) => string | undefined;
93
+ name?: string; message?: string; onCacheError?: 'allow' | 'reject'; headers?: boolean }): RequestHandler
94
+ // cache.incr(key, { ttl? }): Promise<number | undefined> — atomic; undefined when Redis is down
84
95
  // GET/HEAD 200 JSON only; X-Cache: HIT|MISS; keys under 'res:' + originalUrl
85
96
 
86
97
  function scanDir(dir: string, base?: string, maxDepth?: number): RouteEntry[]
@@ -99,7 +110,7 @@ interface EFCConfig {
99
110
  dashboard?: boolean; // dev-only route docs at '/'
100
111
  database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
101
112
  databaseUrl?: string;
102
- databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number }; // per worker
113
+ databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number; preparedStatements?: boolean | { max?: number } }; // per worker
103
114
  authStrategy?: 'http-only' | 'bearer'; // default 'http-only'; 'localStorage' = old name for 'bearer'; anything else = bearer + warning (error in 1.0)
104
115
  jwtSecret?: string;
105
116
  jwtExpiresIn?: string; // default '7d'
@@ -136,7 +147,7 @@ interface LoggingConfig {
136
147
  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'; // default 'info'
137
148
  pretty?: boolean; // default: non-production TTY
138
149
  requests?: boolean; // default true
139
- 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
140
151
  }
141
152
  ```
142
153
 
@@ -325,3 +336,13 @@ function listTasks(): ReadonlyArray<{ name: string; options: TaskOptions }>
325
336
  | `tasks.connectionString` (pg-boss) | — | `databaseUrl` |
326
337
 
327
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.
@@ -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,9 @@ 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.
@@ -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
 
@@ -99,9 +99,10 @@ enqueue('ResizeImage', payload)
99
99
  ```
100
100
 
101
101
  `runInThread` in `thread-runner.ts`:
102
- - Spawns `new Worker(thread-runner.js, { workerData: { handlerPath, payload } })`
103
- - Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`
104
- - Resolves on `{ ok: true }`, rejects on `{ ok: false, error }`
102
+ - Spawns `new Worker(thread-runner.js, { workerData: { efcTask: true, handlerPath, payload } })` — `dist/thread-runner.js` is its own tsup entry (loaded by path; before 0.10.0 it wasn't emitted and every thread task failed)
103
+ - Worker-side: imports `handlerPath`, reads `mod.default`, calls `def.handler(payload)`, posts `{ type: 'done', ok, error? }`
104
+ - `enqueue()` inside the thread goes through `globalThis[Symbol.for('efc.enqueueBridge')]` → `{ type: 'enqueue' }` message → main thread's real `enqueue()` → `{ type: 'enqueued', error? }`; the port is ref'd only while a call waits, so the thread still exits
105
+ - Tested against the built package: `integration/thread-tasks.test.ts`
105
106
 
106
107
  `thread: true` requires `def.filePath` to be set. This is only guaranteed when the task was registered via `scanTasks` (which stores the file path). If you call `registerTask` manually without `filePath`, `thread: true` will silently fall through to the event loop (the `&&` short-circuits).
107
108
 
@@ -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()
@@ -136,7 +137,7 @@ efc lint # NOT IMPLEMENTED
136
137
  efc deploy # NOT IMPLEMENTED
137
138
  efc db reset / fresh # NOT IMPLEMENTED
138
139
  efc db push # NOT IMPLEMENTED — that's `efc db sync` (or autoSync)
139
- efc db pull # PostgreSQL only — MongoDB is NOT supported (exits with an error)
140
+ efc db pull # PostgreSQL → defineTable; MongoDB → defineCollection inferred from sampled docs (--sample)
140
141
  efc remove <item> # NOT IMPLEMENTED — `efc add` copies files; delete them yourself
141
142
  efc add <url|@ns/x> # NOT IMPLEMENTED — only the built-in registry (efc list); no third-party registries
142
143
  ```
@@ -168,8 +169,9 @@ drift), `efc db migrate --baseline` (record as applied without running).
168
169
  // ❌ Sync never DROPS columns, never adds NOT NULL and never deletes rows — that's
169
170
  // `efc db generate <name> --allow-drop` / `--tighten` (explicit, reviewed migrations).
170
171
  // Splits and backfills still need a hand-written migration (db.query()).
171
- // ✅ `efc db generate` writes migrations from model diffs; `efc db pull` (PostgreSQL) and
172
- // `efc import-prisma` write defineTable model files.
172
+ // ✅ `efc db generate` writes migrations from model diffs; `efc db pull` writes defineTable
173
+ // (PostgreSQL) or defineCollection (MongoDB, from sampled documents) files, and
174
+ // `efc import-prisma` writes defineTable files.
173
175
  // ❌ No joins in the model API — populate does a second query; for SQL joins use
174
176
  // Drizzle via Model.raw() or db.query().
175
177
  // ❌ aggregate() is MongoDB-only (rejects on PostgreSQL).
@@ -212,6 +214,13 @@ refreshToken() // does NOT exist as a core export
212
214
  // revokeToken(res) still ONLY clears the cookie.
213
215
  // ❌ No refresh-token rotation or session listing ("show my active devices") in core
214
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
+
215
224
  // ❌ No per-route strategy override
216
225
  // authStrategy is global — set once in ignite()
217
226
  ```
@@ -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