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.
- package/dist/auth/index.cjs +7 -6
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +1 -1
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +5 -5
- package/dist/chunk-3SWI46YK.js +74 -0
- package/dist/chunk-3SWI46YK.js.map +1 -0
- package/dist/{chunk-DCJOWFVD.cjs → chunk-4GHK27JA.cjs} +3 -3
- package/dist/{chunk-DCJOWFVD.cjs.map → chunk-4GHK27JA.cjs.map} +1 -1
- package/dist/{chunk-NI2BNGGV.js → chunk-5LPRKZPB.js} +2 -2
- package/dist/chunk-74BSJXWD.cjs +220 -0
- package/dist/chunk-74BSJXWD.cjs.map +1 -0
- package/dist/{chunk-6KHBJOLB.cjs → chunk-7BC3AN7R.cjs} +14 -14
- package/dist/{chunk-6KHBJOLB.cjs.map → chunk-7BC3AN7R.cjs.map} +1 -1
- package/dist/chunk-AGOYTFRO.cjs +42 -0
- package/dist/chunk-AGOYTFRO.cjs.map +1 -0
- package/dist/{chunk-HBYSKULC.js → chunk-B6MB6HEG.js} +5 -1
- package/dist/chunk-B6MB6HEG.js.map +1 -0
- package/dist/{chunk-OFA7OGN5.js → chunk-BG4A7Z32.js} +176 -7
- package/dist/chunk-BG4A7Z32.js.map +1 -0
- package/dist/{chunk-45BWAR6P.js → chunk-C2FOZ7ME.js} +4 -4
- package/dist/chunk-CGY7JU4Y.cjs +8 -0
- package/dist/chunk-CGY7JU4Y.cjs.map +1 -0
- package/dist/{chunk-BBSZLGZW.js → chunk-DN4TCGYB.js} +43 -14
- package/dist/chunk-DN4TCGYB.js.map +1 -0
- package/dist/{chunk-TI24L4XE.cjs → chunk-H2PVWCWC.cjs} +6 -2
- package/dist/chunk-H2PVWCWC.cjs.map +1 -0
- package/dist/{chunk-TYCYYLLM.cjs → chunk-IUZ6A7PB.cjs} +20 -53
- package/dist/chunk-IUZ6A7PB.cjs.map +1 -0
- package/dist/{chunk-DUADUR6R.cjs → chunk-JP36TLL4.cjs} +171 -14
- package/dist/chunk-JP36TLL4.cjs.map +1 -0
- package/dist/chunk-KLWL7XSC.js +220 -0
- package/dist/chunk-KLWL7XSC.js.map +1 -0
- package/dist/{chunk-QL6EWT4B.cjs → chunk-M53GODCX.cjs} +44 -15
- package/dist/chunk-M53GODCX.cjs.map +1 -0
- package/dist/{chunk-7ZESZG3J.js → chunk-MUVO7MGS.js} +4 -4
- package/dist/{chunk-VWSUQKCJ.cjs → chunk-R2K7AFIB.cjs} +286 -117
- package/dist/chunk-R2K7AFIB.cjs.map +1 -0
- package/dist/{chunk-ULWNHN6P.js → chunk-RETV3GKE.js} +9 -42
- package/dist/chunk-RETV3GKE.js.map +1 -0
- package/dist/{chunk-7YEX4MQV.cjs → chunk-RPL2IFWK.cjs} +46 -7
- package/dist/chunk-RPL2IFWK.cjs.map +1 -0
- package/dist/{chunk-FMA76PRH.cjs → chunk-TBIVIR6L.cjs} +15 -15
- package/dist/{chunk-FMA76PRH.cjs.map → chunk-TBIVIR6L.cjs.map} +1 -1
- package/dist/{chunk-73XJUT2S.js → chunk-V73R76I4.js} +162 -5
- package/dist/chunk-V73R76I4.js.map +1 -0
- package/dist/chunk-XPY5TQDK.js +42 -0
- package/dist/chunk-XPY5TQDK.js.map +1 -0
- package/dist/{chunk-RGT4ZVHL.cjs → chunk-Y4NKIXUL.cjs} +110 -55
- package/dist/chunk-Y4NKIXUL.cjs.map +1 -0
- package/dist/{chunk-2SETEVMO.js → chunk-Y75V5FCU.js} +100 -45
- package/dist/chunk-Y75V5FCU.js.map +1 -0
- package/dist/cli/db-runner.cjs +2059 -126
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +2034 -102
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +50 -29
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +39 -21
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +23 -0
- package/dist/docs/api-reference/collection.md +44 -1
- package/dist/docs/api-reference/compose.md +1 -1
- package/dist/docs/api-reference/db.md +8 -0
- package/dist/docs/api-reference/ignite.md +13 -1
- package/dist/docs/api-reference/testing.md +26 -0
- package/dist/docs/api-reference/types.md +99 -0
- package/dist/docs/cli/add.md +2 -2
- package/dist/docs/cli/db.md +2 -2
- package/dist/docs/core-concepts/background-tasks.md +6 -3
- package/dist/docs/core-concepts/file-based-routing.md +2 -0
- package/dist/docs/core-concepts/middleware.md +2 -2
- package/dist/docs/getting-started/index.md +6 -1
- package/dist/docs/guides/authentication.md +33 -0
- package/dist/docs/guides/caching.md +34 -1
- package/dist/docs/guides/database.md +17 -0
- package/dist/docs/guides/environment-variables.md +6 -0
- package/dist/docs/guides/feature-matrix.md +58 -0
- package/dist/docs/guides/generated-portals.md +3 -1
- package/dist/docs/guides/logging.md +17 -0
- package/dist/docs/guides/migrations.md +26 -3
- package/dist/docs/guides/testing.md +31 -0
- package/dist/docs/guides/which-api.md +2 -2
- package/dist/docs/index.md +4 -1
- package/dist/docs/skills/SKILL.md +5 -1
- package/dist/docs/skills/api-surface.md +25 -4
- package/dist/docs/skills/auth-internals.md +14 -1
- package/dist/docs/skills/pre-flight.md +6 -0
- package/dist/docs/skills/routing-rules.md +1 -1
- package/dist/docs/skills/tasks-internals.md +4 -3
- package/dist/docs/skills/what-not-to-invent.md +13 -4
- package/dist/docs/versioning.md +1 -1
- package/dist/index.cjs +135 -255
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +228 -3
- package/dist/index.d.ts +228 -3
- package/dist/index.js +96 -217
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-4X2YT4RB.js +14 -0
- package/dist/pgboss-backend-UXQ3O2WT.cjs +15 -0
- package/dist/pgboss-backend-UXQ3O2WT.cjs.map +1 -0
- package/dist/registry/index.json +39 -3
- package/dist/registry/js-mongo/account-security.json +1 -1
- package/dist/registry/js-mongo/admin-users.json +1 -1
- package/dist/registry/js-mongo/auth.json +1 -1
- package/dist/registry/js-mongo/auth@apple.json +1 -1
- package/dist/registry/js-mongo/auth@google.json +1 -1
- package/dist/registry/js-mongo/forgot-password.json +1 -1
- package/dist/registry/js-mongo/user-profile.json +1 -1
- package/dist/registry/js-mongo-collection/_base.json +1 -0
- package/dist/registry/js-mongo-collection/account-security.json +1 -0
- package/dist/registry/js-mongo-collection/account-settings.json +1 -0
- package/dist/registry/js-mongo-collection/admin-admins.json +1 -0
- package/dist/registry/js-mongo-collection/admin-analytics.json +1 -0
- package/dist/registry/js-mongo-collection/admin-billing.json +1 -0
- package/dist/registry/js-mongo-collection/admin-content.json +1 -0
- package/dist/registry/js-mongo-collection/admin-logs.json +1 -0
- package/dist/registry/js-mongo-collection/admin-support.json +1 -0
- package/dist/registry/js-mongo-collection/admin-system.json +1 -0
- package/dist/registry/js-mongo-collection/admin-users.json +1 -0
- package/dist/registry/js-mongo-collection/admin.json +1 -0
- package/dist/registry/js-mongo-collection/auth.json +1 -0
- package/dist/registry/js-mongo-collection/auth@apple.json +1 -0
- package/dist/registry/js-mongo-collection/auth@google.json +1 -0
- package/dist/registry/js-mongo-collection/billing.json +1 -0
- package/dist/registry/js-mongo-collection/email-client.json +1 -0
- package/dist/registry/js-mongo-collection/email-verification.json +1 -0
- package/dist/registry/js-mongo-collection/files.json +1 -0
- package/dist/registry/js-mongo-collection/forgot-password.json +1 -0
- package/dist/registry/js-mongo-collection/notifications.json +1 -0
- package/dist/registry/js-mongo-collection/support.json +1 -0
- package/dist/registry/js-mongo-collection/user-profile.json +1 -0
- package/dist/registry/js-pg-model/account-security.json +1 -1
- package/dist/registry/js-pg-model/admin-users.json +1 -1
- package/dist/registry/js-pg-model/auth.json +1 -1
- package/dist/registry/js-pg-model/auth@apple.json +1 -1
- package/dist/registry/js-pg-model/auth@google.json +1 -1
- package/dist/registry/js-pg-model/forgot-password.json +1 -1
- package/dist/registry/js-pg-model/user-profile.json +1 -1
- package/dist/registry/js-pg-table/account-security.json +1 -1
- package/dist/registry/js-pg-table/admin-users.json +1 -1
- package/dist/registry/js-pg-table/auth.json +1 -1
- package/dist/registry/js-pg-table/auth@apple.json +1 -1
- package/dist/registry/js-pg-table/auth@google.json +1 -1
- package/dist/registry/js-pg-table/forgot-password.json +1 -1
- package/dist/registry/js-pg-table/user-profile.json +1 -1
- package/dist/registry/ts-mongo/account-security.json +1 -1
- package/dist/registry/ts-mongo/admin-users.json +1 -1
- package/dist/registry/ts-mongo/auth.json +1 -1
- package/dist/registry/ts-mongo/auth@apple.json +1 -1
- package/dist/registry/ts-mongo/auth@google.json +1 -1
- package/dist/registry/ts-mongo/forgot-password.json +1 -1
- package/dist/registry/ts-mongo/user-profile.json +1 -1
- package/dist/registry/ts-mongo-collection/_base.json +1 -0
- package/dist/registry/ts-mongo-collection/account-security.json +1 -0
- package/dist/registry/ts-mongo-collection/account-settings.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-admins.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-analytics.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-billing.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-content.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-logs.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-support.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-system.json +1 -0
- package/dist/registry/ts-mongo-collection/admin-users.json +1 -0
- package/dist/registry/ts-mongo-collection/admin.json +1 -0
- package/dist/registry/ts-mongo-collection/auth.json +1 -0
- package/dist/registry/ts-mongo-collection/auth@apple.json +1 -0
- package/dist/registry/ts-mongo-collection/auth@google.json +1 -0
- package/dist/registry/ts-mongo-collection/billing.json +1 -0
- package/dist/registry/ts-mongo-collection/email-client.json +1 -0
- package/dist/registry/ts-mongo-collection/email-verification.json +1 -0
- package/dist/registry/ts-mongo-collection/files.json +1 -0
- package/dist/registry/ts-mongo-collection/forgot-password.json +1 -0
- package/dist/registry/ts-mongo-collection/notifications.json +1 -0
- package/dist/registry/ts-mongo-collection/support.json +1 -0
- package/dist/registry/ts-mongo-collection/user-profile.json +1 -0
- package/dist/registry/ts-pg-model/account-security.json +1 -1
- package/dist/registry/ts-pg-model/admin-users.json +1 -1
- package/dist/registry/ts-pg-model/auth.json +1 -1
- package/dist/registry/ts-pg-model/auth@apple.json +1 -1
- package/dist/registry/ts-pg-model/auth@google.json +1 -1
- package/dist/registry/ts-pg-model/forgot-password.json +1 -1
- package/dist/registry/ts-pg-model/user-profile.json +1 -1
- package/dist/registry/ts-pg-table/account-security.json +1 -1
- package/dist/registry/ts-pg-table/admin-users.json +1 -1
- package/dist/registry/ts-pg-table/auth.json +1 -1
- package/dist/registry/ts-pg-table/auth@apple.json +1 -1
- package/dist/registry/ts-pg-table/auth@google.json +1 -1
- package/dist/registry/ts-pg-table/forgot-password.json +1 -1
- package/dist/registry/ts-pg-table/user-profile.json +1 -1
- package/dist/tasks/index.cjs +5 -2
- package/dist/tasks/index.cjs.map +1 -1
- package/dist/tasks/index.d.cts +4 -2
- package/dist/tasks/index.d.ts +4 -2
- package/dist/tasks/index.js +3 -1
- package/dist/testing-cjs.cjs +5 -0
- package/dist/testing.cjs +59 -0
- package/dist/testing.cjs.map +1 -0
- package/dist/testing.d.cts +27 -0
- package/dist/testing.d.ts +27 -0
- package/dist/testing.js +58 -0
- package/dist/testing.js.map +1 -0
- package/dist/thread-runner.cjs +9 -0
- package/dist/thread-runner.cjs.map +1 -0
- package/dist/thread-runner.d.cts +3 -0
- package/dist/thread-runner.d.ts +3 -0
- package/dist/thread-runner.js +8 -0
- package/dist/thread-runner.js.map +1 -0
- package/dist/{types-DAsBKVM-.d.ts → types-CPMFTVXm.d.cts} +15 -1
- package/dist/{types-DAsBKVM-.d.cts → types-CPMFTVXm.d.ts} +15 -1
- package/package.json +6 -1
- package/dist/chunk-2SETEVMO.js.map +0 -1
- package/dist/chunk-73XJUT2S.js.map +0 -1
- package/dist/chunk-7YEX4MQV.cjs.map +0 -1
- package/dist/chunk-BBSZLGZW.js.map +0 -1
- package/dist/chunk-DUADUR6R.cjs.map +0 -1
- package/dist/chunk-HBYSKULC.js.map +0 -1
- package/dist/chunk-LJNSJFOL.js +0 -38
- package/dist/chunk-LJNSJFOL.js.map +0 -1
- package/dist/chunk-OFA7OGN5.js.map +0 -1
- package/dist/chunk-QL6EWT4B.cjs.map +0 -1
- package/dist/chunk-RGT4ZVHL.cjs.map +0 -1
- package/dist/chunk-TI24L4XE.cjs.map +0 -1
- package/dist/chunk-TYCYYLLM.cjs.map +0 -1
- package/dist/chunk-ULWNHN6P.js.map +0 -1
- package/dist/chunk-VWSUQKCJ.cjs.map +0 -1
- package/dist/pgboss-backend-DSO3QTNK.cjs +0 -14
- package/dist/pgboss-backend-DSO3QTNK.cjs.map +0 -1
- package/dist/pgboss-backend-I6DFUNRM.js +0 -14
- /package/dist/{chunk-NI2BNGGV.js.map → chunk-5LPRKZPB.js.map} +0 -0
- /package/dist/{chunk-45BWAR6P.js.map → chunk-C2FOZ7ME.js.map} +0 -0
- /package/dist/{chunk-7ZESZG3J.js.map → chunk-MUVO7MGS.js.map} +0 -0
- /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,
|
|
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
|
|
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.
|
|
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).
|
package/dist/docs/index.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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[]` (
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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`
|
|
172
|
-
//
|
|
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
|
```
|
package/dist/docs/versioning.md
CHANGED
|
@@ -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
|
|
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
|
|