express-file-cluster 0.9.3 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/auth/index.cjs +6 -7
- package/dist/auth/index.cjs.map +1 -1
- package/dist/auth/index.d.cts +7 -2
- package/dist/auth/index.d.ts +7 -2
- package/dist/auth/index.js +5 -6
- package/dist/{chunk-QL6EWT4B.cjs → chunk-4DOHQU6I.cjs} +9 -7
- package/dist/chunk-4DOHQU6I.cjs.map +1 -0
- package/dist/chunk-73XJUT2S.js +366 -0
- package/dist/chunk-73XJUT2S.js.map +1 -0
- package/dist/{chunk-ATL4GYFU.js → chunk-7KC2H76D.js} +50 -8
- package/dist/chunk-7KC2H76D.js.map +1 -0
- package/dist/{chunk-TYR2GZZE.cjs → chunk-7KO4DJRJ.cjs} +19 -14
- package/dist/chunk-7KO4DJRJ.cjs.map +1 -0
- package/dist/{chunk-UBQYQPBU.js → chunk-ATVD2HGC.js} +4 -4
- package/dist/{chunk-R34R7QPD.cjs → chunk-DCJOWFVD.cjs} +3 -3
- package/dist/{chunk-R34R7QPD.cjs.map → chunk-DCJOWFVD.cjs.map} +1 -1
- package/dist/chunk-DUADUR6R.cjs +366 -0
- package/dist/chunk-DUADUR6R.cjs.map +1 -0
- package/dist/{chunk-BBSZLGZW.js → chunk-EGSSZUVO.js} +8 -6
- package/dist/chunk-EGSSZUVO.js.map +1 -0
- package/dist/{chunk-TI24L4XE.cjs → chunk-GBI77W5T.cjs} +6 -2
- package/dist/chunk-GBI77W5T.cjs.map +1 -0
- package/dist/{chunk-RTF7PHS2.cjs → chunk-HBCY7ILD.cjs} +306 -119
- package/dist/chunk-HBCY7ILD.cjs.map +1 -0
- package/dist/{chunk-ANUSWEAP.cjs → chunk-KFVFP2Q7.cjs} +59 -17
- package/dist/chunk-KFVFP2Q7.cjs.map +1 -0
- package/dist/{chunk-RS4MXCPW.js → chunk-NI2BNGGV.js} +2 -2
- package/dist/{chunk-X2US4RAM.cjs → chunk-NKLOE4AK.cjs} +11 -13
- package/dist/chunk-NKLOE4AK.cjs.map +1 -0
- package/dist/{chunk-RRQ2RK5M.js → chunk-PGJQK36V.js} +195 -8
- package/dist/chunk-PGJQK36V.js.map +1 -0
- package/dist/{chunk-QKQZF573.js → chunk-QDEDOHP7.js} +4 -6
- package/dist/chunk-QDEDOHP7.js.map +1 -0
- package/dist/{chunk-UTM4PEVG.js → chunk-R4XO4SVM.js} +10 -5
- package/dist/chunk-R4XO4SVM.js.map +1 -0
- package/dist/chunk-R52CUEGT.js +74 -0
- package/dist/chunk-R52CUEGT.js.map +1 -0
- package/dist/{chunk-HBYSKULC.js → chunk-RAB44UGX.js} +5 -1
- package/dist/chunk-RAB44UGX.js.map +1 -0
- package/dist/{chunk-7YEX4MQV.cjs → chunk-WBLUGOAG.cjs} +42 -6
- package/dist/chunk-WBLUGOAG.cjs.map +1 -0
- package/dist/{chunk-T4OHFU5T.cjs → chunk-YK4ZM3CA.cjs} +15 -15
- package/dist/{chunk-T4OHFU5T.cjs.map → chunk-YK4ZM3CA.cjs.map} +1 -1
- package/dist/cli/db-runner.cjs +2012 -120
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +1989 -97
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +101 -43
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +80 -22
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/auth.md +10 -8
- package/dist/docs/api-reference/collection.md +44 -1
- package/dist/docs/api-reference/ignite.md +22 -3
- package/dist/docs/api-reference/types.md +99 -0
- package/dist/docs/cli/add.md +1 -1
- package/dist/docs/cli/db.md +2 -2
- package/dist/docs/contributing/index.md +1 -1
- package/dist/docs/core-concepts/background-tasks.md +6 -3
- package/dist/docs/getting-started/index.md +3 -2
- package/dist/docs/guides/authentication.md +34 -24
- package/dist/docs/guides/caching.md +32 -1
- package/dist/docs/guides/database.md +14 -0
- package/dist/docs/guides/feature-matrix.md +58 -0
- package/dist/docs/guides/migrations.md +23 -2
- package/dist/docs/guides/oauth.md +15 -1
- package/dist/docs/guides/which-api.md +2 -2
- package/dist/docs/index.md +4 -1
- package/dist/docs/skills/SKILL.md +2 -2
- package/dist/docs/skills/api-surface.md +10 -4
- package/dist/docs/skills/auth-internals.md +3 -3
- package/dist/docs/skills/tasks-internals.md +4 -3
- package/dist/docs/skills/what-not-to-invent.md +4 -3
- package/dist/docs/versioning.md +42 -0
- package/dist/index.cjs +144 -51
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +204 -3
- package/dist/index.d.ts +204 -3
- package/dist/index.js +107 -14
- package/dist/index.js.map +1 -1
- package/dist/pgboss-backend-FW42SBSM.js +14 -0
- package/dist/pgboss-backend-RVHUBJTU.cjs +14 -0
- package/dist/{pgboss-backend-TCHI7CHM.cjs.map → pgboss-backend-RVHUBJTU.cjs.map} +1 -1
- package/dist/registry/index.json +34 -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/email-verification.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/email-verification.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/email-verification.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/email-verification.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/email-verification.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/email-verification.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 +4 -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/thread-runner.cjs +8 -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-BY-ObnZH.d.ts → types-Bnxvj3l0.d.cts} +14 -2
- package/dist/{types-BY-ObnZH.d.cts → types-Bnxvj3l0.d.ts} +14 -2
- package/package.json +1 -1
- package/dist/chunk-277BSYVH.js +0 -127
- package/dist/chunk-277BSYVH.js.map +0 -1
- package/dist/chunk-7YEX4MQV.cjs.map +0 -1
- package/dist/chunk-ANUSWEAP.cjs.map +0 -1
- package/dist/chunk-ATL4GYFU.js.map +0 -1
- package/dist/chunk-BBSZLGZW.js.map +0 -1
- package/dist/chunk-HBYSKULC.js.map +0 -1
- package/dist/chunk-HXV543HZ.js +0 -177
- package/dist/chunk-HXV543HZ.js.map +0 -1
- package/dist/chunk-LJNSJFOL.js +0 -38
- package/dist/chunk-LJNSJFOL.js.map +0 -1
- package/dist/chunk-QKQZF573.js.map +0 -1
- package/dist/chunk-QL6EWT4B.cjs.map +0 -1
- package/dist/chunk-RRQ2RK5M.js.map +0 -1
- package/dist/chunk-RTF7PHS2.cjs.map +0 -1
- package/dist/chunk-TI24L4XE.cjs.map +0 -1
- package/dist/chunk-TYR2GZZE.cjs.map +0 -1
- package/dist/chunk-UTM4PEVG.js.map +0 -1
- package/dist/chunk-VQSWSYK6.cjs +0 -177
- package/dist/chunk-VQSWSYK6.cjs.map +0 -1
- package/dist/chunk-X2US4RAM.cjs.map +0 -1
- package/dist/chunk-YL37D6KM.cjs +0 -127
- package/dist/chunk-YL37D6KM.cjs.map +0 -1
- package/dist/pgboss-backend-QKBXVJ6B.js +0 -14
- package/dist/pgboss-backend-TCHI7CHM.cjs +0 -14
- /package/dist/{chunk-UBQYQPBU.js.map → chunk-ATVD2HGC.js.map} +0 -0
- /package/dist/{chunk-RS4MXCPW.js.map → chunk-NI2BNGGV.js.map} +0 -0
- /package/dist/{pgboss-backend-QKBXVJ6B.js.map → pgboss-backend-FW42SBSM.js.map} +0 -0
|
@@ -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
|
|
|
@@ -119,6 +119,23 @@ efc db pull --out pulled # somewhere else, to compare
|
|
|
119
119
|
|
|
120
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`.
|
|
121
121
|
|
|
122
|
+
## Pulling an existing database (MongoDB)
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
efc db pull # → src/model/<Model>.ts + index.ts (defineCollection)
|
|
126
|
+
efc db pull --sample 5000 # sample more documents per collection (default 1000)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
MongoDB has no schema to read, so `pull` samples each collection (`$sample`) and infers one from the documents:
|
|
130
|
+
|
|
131
|
+
- **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 }`.
|
|
132
|
+
- **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.
|
|
133
|
+
- **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.
|
|
134
|
+
- **Indexes:** single-field unique, plain, `text`, `2dsphere` and `hashed` indexes go on the field; compound, partial and TTL indexes into `indexes`.
|
|
135
|
+
- **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`.
|
|
136
|
+
|
|
137
|
+
`_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.
|
|
138
|
+
|
|
122
139
|
`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
140
|
|
|
124
141
|
Coming from Prisma? See [Coming from Prisma](./coming-from-prisma.md).
|
|
@@ -215,3 +232,7 @@ CMD ["sh", "-c", "npx efc db migrate --dist && npx efc start prod"]
|
|
|
215
232
|
## Studio
|
|
216
233
|
|
|
217
234
|
`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`.
|
|
235
|
+
|
|
236
|
+
`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.
|
|
237
|
+
|
|
238
|
+
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.
|
|
@@ -61,7 +61,21 @@ Send the browser (not `fetch`) to the start route:
|
|
|
61
61
|
|
|
62
62
|
After the provider sends the user back, the callback sets the usual `efc_token` cookie (the same one `/auth/login` sets) and redirects to `OAUTH_SUCCESS_REDIRECT`. From there, requests with credentials work as after a password login, and `GET /auth/me` returns the user.
|
|
63
63
|
|
|
64
|
-
>
|
|
64
|
+
> With `authStrategy: 'http-only'` the callbacks set the session cookie and redirect to `OAUTH_SUCCESS_REDIRECT`. With `'bearer'` they redirect to `OAUTH_SUCCESS_REDIRECT#code=<code>` instead — a one-time code, never the JWT itself (URLs end up in history, logs and screenshots).
|
|
65
|
+
|
|
66
|
+
### Bearer apps (mobile / desktop)
|
|
67
|
+
|
|
68
|
+
The app proves it's the one that started the sign-in with PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)), so another app that registers the same `myapp://` link and catches the redirect can't use the code:
|
|
69
|
+
|
|
70
|
+
1. Make a random `code_verifier` (43–128 characters, e.g. 32 random bytes as base64url) and keep it in memory.
|
|
71
|
+
2. Open `/auth/google?code_challenge=<base64url(SHA-256(code_verifier))>` (or `/auth/apple?…`) in the system browser (`ASWebAuthenticationSession`, Custom Tabs).
|
|
72
|
+
3. `OAUTH_SUCCESS_REDIRECT` (e.g. `myapp://signed-in`) receives `#code=<code>`. Trade it within 60 seconds:
|
|
73
|
+
|
|
74
|
+
```http
|
|
75
|
+
POST /auth/oauth/exchange { "code": "<code>", "code_verifier": "<code_verifier>" } → 200 { "token": "<jwt>" }
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The code works once — a second use, even a simultaneous one, gets 400. A wrong verifier gets 400 without using the code up. Without a `code_challenge`, bearer sign-in stops with 400 at the callback. The code lives in `cache`: with several instances, use Redis (`REDIS_URL`).
|
|
65
79
|
|
|
66
80
|
---
|
|
67
81
|
|
|
@@ -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.0 — 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
|
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
| [Guides](./guides/authentication.md) | Deep-dives: auth, OAuth, database, RBAC, mailer, error handling, deployment |
|
|
30
30
|
| [CLI](./cli/index.md) | All `efc` commands with flags and examples |
|
|
31
31
|
| [Contributing](./contributing/index.md) | Roadmap, branch conventions, PR requirements |
|
|
32
|
+
| [Versioning & support](./versioning.md) | What patch/minor/major may contain, LTS from 1.0, supported Node versions, security reports |
|
|
32
33
|
|
|
33
34
|
### Guides
|
|
34
35
|
|
|
@@ -38,6 +39,8 @@
|
|
|
38
39
|
| [RBAC](./guides/rbac.md) | Role-based route protection via the `requireAuth('role')` shorthand |
|
|
39
40
|
| [Database](./guides/database.md) | `defineModel`, queries, transactions, MongoDB vs PostgreSQL |
|
|
40
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 |
|
|
41
44
|
| [Relations](./guides/relations.md) | Foreign keys, many-to-many, `include`, relation filters, nested writes |
|
|
42
45
|
| [defineTable](./api-reference/table.md) | PostgreSQL-native models: Prisma-style queries, SQL types, aggregation |
|
|
43
46
|
| [defineCollection](./api-reference/collection.md) | MongoDB-native models: mongoose-style queries, BSON types, geo, bulk writes, change streams |
|
|
@@ -37,8 +37,8 @@ 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.0 — Beta, Phase 2 complete + defineTable with relations + generated migrations + `efc add` registry)
|
|
41
41
|
|
|
42
|
-
Implemented: file-based router (incl. `[[id]]`, `[...slug]`, `[[...slug]]`), request validation (`export const schema`, Standard Schema), multi-core clustering with graceful shutdown, http-only +
|
|
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`.
|
|
@@ -81,6 +81,11 @@ const cache: {
|
|
|
81
81
|
clear(prefix?): Promise<number>;
|
|
82
82
|
}
|
|
83
83
|
function cacheResponse(ttl: number | { ttl; perUser?: boolean; key?: (req) => string }): RequestHandler
|
|
84
|
+
// Fixed window counted with cache.incr — one limit across workers (memory) / instances (redis).
|
|
85
|
+
// key defaults to req.ip: behind a proxy set ignite({ trustProxy }) or everyone shares one bucket.
|
|
86
|
+
function rateLimit(o: { window: number | '15m'; max: number; key?: (req) => string | undefined;
|
|
87
|
+
name?: string; message?: string; onCacheError?: 'allow' | 'reject'; headers?: boolean }): RequestHandler
|
|
88
|
+
// cache.incr(key, { ttl? }): Promise<number | undefined> — atomic; undefined when Redis is down
|
|
84
89
|
// GET/HEAD 200 JSON only; X-Cache: HIT|MISS; keys under 'res:' + originalUrl
|
|
85
90
|
|
|
86
91
|
function scanDir(dir: string, base?: string, maxDepth?: number): RouteEntry[]
|
|
@@ -100,7 +105,7 @@ interface EFCConfig {
|
|
|
100
105
|
database?: 'mongodb' | 'postgresql'; // default: inferred from databaseUrl scheme
|
|
101
106
|
databaseUrl?: string;
|
|
102
107
|
databasePool?: { max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number }; // per worker
|
|
103
|
-
authStrategy?: 'http-only' | 'localStorage';
|
|
108
|
+
authStrategy?: 'http-only' | 'bearer'; // default 'http-only'; 'localStorage' = old name for 'bearer'; anything else = bearer + warning (error in 1.0)
|
|
104
109
|
jwtSecret?: string;
|
|
105
110
|
jwtExpiresIn?: string; // default '7d'
|
|
106
111
|
cookieDomain?: string;
|
|
@@ -233,13 +238,14 @@ interface MigrationContext { db: unknown; engine: 'mongodb' | 'postgresql' } //
|
|
|
233
238
|
Source: `packages/core/src/auth/index.ts`
|
|
234
239
|
|
|
235
240
|
```ts
|
|
236
|
-
//
|
|
237
|
-
|
|
241
|
+
// http-only: sets the efc_token cookie, resolves undefined. bearer: no cookie, resolves the token.
|
|
242
|
+
// One route for both: const token = await issueToken(res, p); res.json({ ...(token ? { token } : {}) })
|
|
243
|
+
async function issueToken(res: Response, payload: Record<string, unknown>): Promise<string | undefined>
|
|
238
244
|
|
|
239
245
|
// Clear cookie (http-only strategy)
|
|
240
246
|
function revokeToken(res: Response): void
|
|
241
247
|
|
|
242
|
-
//
|
|
248
|
+
// Always returns the token string, no cookie (any strategy)
|
|
243
249
|
async function signToken(payload: Record<string, unknown>): Promise<string>
|
|
244
250
|
|
|
245
251
|
// Need ignite({ cache }). Every signed token carries jti + iat + efc_iat (ms).
|
|
@@ -10,7 +10,7 @@ Source: `packages/core/src/auth/index.ts`
|
|
|
10
10
|
// Called by ignite() at Pre-Flight step 2
|
|
11
11
|
configureAuth({
|
|
12
12
|
secret: jwtSecret,
|
|
13
|
-
strategy: authStrategy, // 'http-only' | 'localStorage'
|
|
13
|
+
strategy: authStrategy, // 'http-only' | 'bearer' ('localStorage' = old name); anything else = bearer + startup warning (error in 1.0)
|
|
14
14
|
expiresIn: JWT_EXPIRES_IN ?? '7d',
|
|
15
15
|
cookieDomain: COOKIE_DOMAIN, // optional
|
|
16
16
|
})
|
|
@@ -23,7 +23,7 @@ configureAuth({
|
|
|
23
23
|
## `issueToken(res, payload)`
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
|
-
// Signs JWT (HS256)
|
|
26
|
+
// Signs JWT (HS256). bearer → `return token` (no cookie). http-only → sets the cookie, returns undefined
|
|
27
27
|
const token = await new SignJWT(payload)
|
|
28
28
|
.setProtectedHeader({ alg: 'HS256' })
|
|
29
29
|
.setExpirationTime(expiresIn)
|
|
@@ -99,7 +99,7 @@ export const middlewares = [requireAuth('user', 'admin')]; // multiple allowed
|
|
|
99
99
|
|
|
100
100
|
```ts
|
|
101
101
|
// Strategy 'http-only': reads req.cookies.efc_token
|
|
102
|
-
// Strategy 'localStorage': reads Authorization header → strips 'Bearer '
|
|
102
|
+
// Strategy 'bearer' / 'localStorage': reads Authorization header → strips 'Bearer '
|
|
103
103
|
|
|
104
104
|
if (!token) → res.status(401).json({ error: 'Unauthorized' }); return
|
|
105
105
|
|
|
@@ -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
|
|
|
@@ -136,7 +136,7 @@ efc lint # NOT IMPLEMENTED
|
|
|
136
136
|
efc deploy # NOT IMPLEMENTED
|
|
137
137
|
efc db reset / fresh # NOT IMPLEMENTED
|
|
138
138
|
efc db push # NOT IMPLEMENTED — that's `efc db sync` (or autoSync)
|
|
139
|
-
efc db pull # PostgreSQL
|
|
139
|
+
efc db pull # PostgreSQL → defineTable; MongoDB → defineCollection inferred from sampled docs (--sample)
|
|
140
140
|
efc remove <item> # NOT IMPLEMENTED — `efc add` copies files; delete them yourself
|
|
141
141
|
efc add <url|@ns/x> # NOT IMPLEMENTED — only the built-in registry (efc list); no third-party registries
|
|
142
142
|
```
|
|
@@ -168,8 +168,9 @@ drift), `efc db migrate --baseline` (record as applied without running).
|
|
|
168
168
|
// ❌ Sync never DROPS columns, never adds NOT NULL and never deletes rows — that's
|
|
169
169
|
// `efc db generate <name> --allow-drop` / `--tighten` (explicit, reviewed migrations).
|
|
170
170
|
// Splits and backfills still need a hand-written migration (db.query()).
|
|
171
|
-
// ✅ `efc db generate` writes migrations from model diffs; `efc db pull`
|
|
172
|
-
//
|
|
171
|
+
// ✅ `efc db generate` writes migrations from model diffs; `efc db pull` writes defineTable
|
|
172
|
+
// (PostgreSQL) or defineCollection (MongoDB, from sampled documents) files, and
|
|
173
|
+
// `efc import-prisma` writes defineTable files.
|
|
173
174
|
// ❌ No joins in the model API — populate does a second query; for SQL joins use
|
|
174
175
|
// Drizzle via Model.raw() or db.query().
|
|
175
176
|
// ❌ aggregate() is MongoDB-only (rejects on PostgreSQL).
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Versioning & Support Policy
|
|
2
|
+
|
|
3
|
+
`express-file-cluster`, `create-efc-app` and `express-file-cluster-mcp` are released together under one version number, following [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## Before 1.0 (now: 0.x)
|
|
6
|
+
|
|
7
|
+
| Bump | Example | What it may contain |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| **Patch** | 0.9.4 → 0.9.5 | Bug fixes, security fixes, clearer errors, docs. No new public API. A fix can change behaviour that was wrong (e.g. a route that leaked data); the changelog says so and gives upgrade steps. |
|
|
10
|
+
| **Minor** | 0.9.x → 0.10.0 | New features and APIs. May include breaking changes — each one is listed in [`CHANGELOG.md`](https://github.com/pr4shxnt/efc.js/blob/main/CHANGELOG.md) with upgrade steps. |
|
|
11
|
+
|
|
12
|
+
Pin a minor range (`~0.9.5`) if you want fixes without features; `^0.9.5` behaves the same way on 0.x (npm treats the minor as the breaking digit).
|
|
13
|
+
|
|
14
|
+
Deprecations are announced at least one minor release before removal, with a startup warning where possible (e.g. an unknown `authStrategy` warns in 0.9.x and becomes an error in 1.0).
|
|
15
|
+
|
|
16
|
+
## From 1.0
|
|
17
|
+
|
|
18
|
+
- **Major** (1.x → 2.0): breaking changes only, each with upgrade steps.
|
|
19
|
+
- **Minor** (1.1 → 1.2): new features, backwards compatible.
|
|
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.
|
|
22
|
+
|
|
23
|
+
## Long-term support (from 1.0)
|
|
24
|
+
|
|
25
|
+
| Line | Gets | For |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| **Current** major | Features, fixes, security fixes | Until the next major |
|
|
28
|
+
| **Previous** major | Security fixes and critical bug fixes | 12 months after the next major ships |
|
|
29
|
+
|
|
30
|
+
Before 1.0 only the latest 0.x minor gets fixes — upgrade to it to get them.
|
|
31
|
+
|
|
32
|
+
## Node.js
|
|
33
|
+
|
|
34
|
+
EFC supports the Node.js versions in **active or maintenance LTS** and is tested on **Node 22 and 24** in CI. A Node version that reaches end-of-life stops being supported in the next minor release. (`engines` still says `>=18`; it will be raised to the supported range at 1.0. Node 18 and 20 are end-of-life and untested — scaffolded apps' email client already needs Node 20+.)
|
|
35
|
+
|
|
36
|
+
## Generated code
|
|
37
|
+
|
|
38
|
+
`create-efc-app` and `efc add` copy source files into your app; after that the code is yours, and upgrading the framework doesn't change it. When a release fixes generated code, the changelog says which files and how — re-add an untouched file with `efc add <item>`, or a changed one with `efc add <item> --overwrite` (then reapply your edits), or apply the shown change by hand.
|
|
39
|
+
|
|
40
|
+
## Security
|
|
41
|
+
|
|
42
|
+
See [`SECURITY.md`](https://github.com/pr4shxnt/efc.js/blob/main/SECURITY.md) for how to report a vulnerability. Security fixes ship as patch releases and are marked **Security** in the changelog.
|