express-file-cluster 0.7.1 → 0.9.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/README.md +3 -1
- package/dist/auth/index.cjs +3 -3
- package/dist/auth/index.d.cts +1 -1
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +2 -2
- package/dist/{chunk-ZDM5JHVK.cjs → chunk-2J3HHQKP.cjs} +3 -3
- package/dist/{chunk-ZDM5JHVK.cjs.map → chunk-2J3HHQKP.cjs.map} +1 -1
- package/dist/chunk-2PBMLMO4.js +1386 -0
- package/dist/chunk-2PBMLMO4.js.map +1 -0
- package/dist/chunk-66R7S7J3.cjs +1386 -0
- package/dist/chunk-66R7S7J3.cjs.map +1 -0
- package/dist/{chunk-6OGOVV57.js → chunk-6QNLN6AI.js} +118 -1266
- package/dist/chunk-6QNLN6AI.js.map +1 -0
- package/dist/chunk-BBSZLGZW.js +113 -0
- package/dist/chunk-BBSZLGZW.js.map +1 -0
- package/dist/{chunk-BUBXO7WU.js → chunk-HXV543HZ.js} +10 -3
- package/dist/chunk-HXV543HZ.js.map +1 -0
- package/dist/chunk-QL6EWT4B.cjs +113 -0
- package/dist/chunk-QL6EWT4B.cjs.map +1 -0
- package/dist/{chunk-AZYXQU3Z.cjs → chunk-RGTENTDN.cjs} +239 -1387
- package/dist/chunk-RGTENTDN.cjs.map +1 -0
- package/dist/{chunk-TRC4DUZB.js → chunk-RSZB7VAO.js} +2 -2
- package/dist/{chunk-MGH4VDV3.cjs → chunk-VQSWSYK6.cjs} +10 -3
- package/dist/chunk-VQSWSYK6.cjs.map +1 -0
- package/dist/cli/db-runner.cjs +613 -28
- package/dist/cli/db-runner.cjs.map +1 -1
- package/dist/cli/db-runner.js +611 -26
- package/dist/cli/db-runner.js.map +1 -1
- package/dist/cli/index.cjs +1210 -12
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +1221 -23
- package/dist/cli/index.js.map +1 -1
- package/dist/docs/api-reference/db.md +1 -0
- package/dist/docs/api-reference/ignite.md +19 -0
- package/dist/docs/api-reference/table.md +3 -0
- package/dist/docs/cli/add.md +136 -0
- package/dist/docs/cli/db.md +25 -2
- package/dist/docs/cli/index.md +10 -1
- package/dist/docs/core-concepts/middleware.md +1 -1
- package/dist/docs/getting-started/index.md +25 -18
- package/dist/docs/getting-started/project-structure.md +6 -7
- package/dist/docs/guides/authentication.md +3 -1
- package/dist/docs/guides/coming-from-prisma.md +75 -0
- package/dist/docs/guides/database.md +5 -2
- package/dist/docs/guides/generated-portals.md +36 -19
- package/dist/docs/guides/mailer.md +7 -10
- package/dist/docs/guides/migrations.md +114 -3
- package/dist/docs/guides/oauth.md +94 -0
- package/dist/docs/guides/rbac.md +5 -40
- package/dist/docs/guides/relations.md +147 -0
- package/dist/docs/guides/which-api.md +50 -0
- package/dist/docs/index.md +7 -3
- package/dist/docs/skills/SKILL.md +3 -3
- package/dist/docs/skills/api-surface.md +1 -0
- package/dist/docs/skills/what-not-to-invent.md +22 -6
- package/dist/index.cjs +20 -18
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +12 -10
- package/dist/index.js.map +1 -1
- package/dist/registry/index.json +506 -0
- package/dist/registry/js-mongo/_base.json +1 -0
- package/dist/registry/js-mongo/account-security.json +1 -0
- package/dist/registry/js-mongo/account-settings.json +1 -0
- package/dist/registry/js-mongo/admin-admins.json +1 -0
- package/dist/registry/js-mongo/admin-analytics.json +1 -0
- package/dist/registry/js-mongo/admin-billing.json +1 -0
- package/dist/registry/js-mongo/admin-content.json +1 -0
- package/dist/registry/js-mongo/admin-logs.json +1 -0
- package/dist/registry/js-mongo/admin-support.json +1 -0
- package/dist/registry/js-mongo/admin-system.json +1 -0
- package/dist/registry/js-mongo/admin-users.json +1 -0
- package/dist/registry/js-mongo/admin.json +1 -0
- package/dist/registry/js-mongo/auth.json +1 -0
- package/dist/registry/js-mongo/auth@apple.json +1 -0
- package/dist/registry/js-mongo/auth@google.json +1 -0
- package/dist/registry/js-mongo/billing.json +1 -0
- package/dist/registry/js-mongo/email-client.json +1 -0
- package/dist/registry/js-mongo/email-verification.json +1 -0
- package/dist/registry/js-mongo/files.json +1 -0
- package/dist/registry/js-mongo/forgot-password.json +1 -0
- package/dist/registry/js-mongo/notifications.json +1 -0
- package/dist/registry/js-mongo/support.json +1 -0
- package/dist/registry/js-mongo/user-profile.json +1 -0
- package/dist/registry/js-pg-model/_base.json +1 -0
- package/dist/registry/js-pg-model/account-security.json +1 -0
- package/dist/registry/js-pg-model/account-settings.json +1 -0
- package/dist/registry/js-pg-model/admin-admins.json +1 -0
- package/dist/registry/js-pg-model/admin-analytics.json +1 -0
- package/dist/registry/js-pg-model/admin-billing.json +1 -0
- package/dist/registry/js-pg-model/admin-content.json +1 -0
- package/dist/registry/js-pg-model/admin-logs.json +1 -0
- package/dist/registry/js-pg-model/admin-support.json +1 -0
- package/dist/registry/js-pg-model/admin-system.json +1 -0
- package/dist/registry/js-pg-model/admin-users.json +1 -0
- package/dist/registry/js-pg-model/admin.json +1 -0
- package/dist/registry/js-pg-model/auth.json +1 -0
- package/dist/registry/js-pg-model/auth@apple.json +1 -0
- package/dist/registry/js-pg-model/auth@google.json +1 -0
- package/dist/registry/js-pg-model/billing.json +1 -0
- package/dist/registry/js-pg-model/email-client.json +1 -0
- package/dist/registry/js-pg-model/email-verification.json +1 -0
- package/dist/registry/js-pg-model/files.json +1 -0
- package/dist/registry/js-pg-model/forgot-password.json +1 -0
- package/dist/registry/js-pg-model/notifications.json +1 -0
- package/dist/registry/js-pg-model/support.json +1 -0
- package/dist/registry/js-pg-model/user-profile.json +1 -0
- package/dist/registry/js-pg-table/_base.json +1 -0
- package/dist/registry/js-pg-table/account-security.json +1 -0
- package/dist/registry/js-pg-table/account-settings.json +1 -0
- package/dist/registry/js-pg-table/admin-admins.json +1 -0
- package/dist/registry/js-pg-table/admin-analytics.json +1 -0
- package/dist/registry/js-pg-table/admin-billing.json +1 -0
- package/dist/registry/js-pg-table/admin-content.json +1 -0
- package/dist/registry/js-pg-table/admin-logs.json +1 -0
- package/dist/registry/js-pg-table/admin-support.json +1 -0
- package/dist/registry/js-pg-table/admin-system.json +1 -0
- package/dist/registry/js-pg-table/admin-users.json +1 -0
- package/dist/registry/js-pg-table/admin.json +1 -0
- package/dist/registry/js-pg-table/auth.json +1 -0
- package/dist/registry/js-pg-table/auth@apple.json +1 -0
- package/dist/registry/js-pg-table/auth@google.json +1 -0
- package/dist/registry/js-pg-table/billing.json +1 -0
- package/dist/registry/js-pg-table/email-client.json +1 -0
- package/dist/registry/js-pg-table/email-verification.json +1 -0
- package/dist/registry/js-pg-table/files.json +1 -0
- package/dist/registry/js-pg-table/forgot-password.json +1 -0
- package/dist/registry/js-pg-table/notifications.json +1 -0
- package/dist/registry/js-pg-table/support.json +1 -0
- package/dist/registry/js-pg-table/user-profile.json +1 -0
- package/dist/registry/ts-mongo/_base.json +1 -0
- package/dist/registry/ts-mongo/account-security.json +1 -0
- package/dist/registry/ts-mongo/account-settings.json +1 -0
- package/dist/registry/ts-mongo/admin-admins.json +1 -0
- package/dist/registry/ts-mongo/admin-analytics.json +1 -0
- package/dist/registry/ts-mongo/admin-billing.json +1 -0
- package/dist/registry/ts-mongo/admin-content.json +1 -0
- package/dist/registry/ts-mongo/admin-logs.json +1 -0
- package/dist/registry/ts-mongo/admin-support.json +1 -0
- package/dist/registry/ts-mongo/admin-system.json +1 -0
- package/dist/registry/ts-mongo/admin-users.json +1 -0
- package/dist/registry/ts-mongo/admin.json +1 -0
- package/dist/registry/ts-mongo/auth.json +1 -0
- package/dist/registry/ts-mongo/auth@apple.json +1 -0
- package/dist/registry/ts-mongo/auth@google.json +1 -0
- package/dist/registry/ts-mongo/billing.json +1 -0
- package/dist/registry/ts-mongo/email-client.json +1 -0
- package/dist/registry/ts-mongo/email-verification.json +1 -0
- package/dist/registry/ts-mongo/files.json +1 -0
- package/dist/registry/ts-mongo/forgot-password.json +1 -0
- package/dist/registry/ts-mongo/notifications.json +1 -0
- package/dist/registry/ts-mongo/support.json +1 -0
- package/dist/registry/ts-mongo/user-profile.json +1 -0
- package/dist/registry/ts-pg-model/_base.json +1 -0
- package/dist/registry/ts-pg-model/account-security.json +1 -0
- package/dist/registry/ts-pg-model/account-settings.json +1 -0
- package/dist/registry/ts-pg-model/admin-admins.json +1 -0
- package/dist/registry/ts-pg-model/admin-analytics.json +1 -0
- package/dist/registry/ts-pg-model/admin-billing.json +1 -0
- package/dist/registry/ts-pg-model/admin-content.json +1 -0
- package/dist/registry/ts-pg-model/admin-logs.json +1 -0
- package/dist/registry/ts-pg-model/admin-support.json +1 -0
- package/dist/registry/ts-pg-model/admin-system.json +1 -0
- package/dist/registry/ts-pg-model/admin-users.json +1 -0
- package/dist/registry/ts-pg-model/admin.json +1 -0
- package/dist/registry/ts-pg-model/auth.json +1 -0
- package/dist/registry/ts-pg-model/auth@apple.json +1 -0
- package/dist/registry/ts-pg-model/auth@google.json +1 -0
- package/dist/registry/ts-pg-model/billing.json +1 -0
- package/dist/registry/ts-pg-model/email-client.json +1 -0
- package/dist/registry/ts-pg-model/email-verification.json +1 -0
- package/dist/registry/ts-pg-model/files.json +1 -0
- package/dist/registry/ts-pg-model/forgot-password.json +1 -0
- package/dist/registry/ts-pg-model/notifications.json +1 -0
- package/dist/registry/ts-pg-model/support.json +1 -0
- package/dist/registry/ts-pg-model/user-profile.json +1 -0
- package/dist/registry/ts-pg-table/_base.json +1 -0
- package/dist/registry/ts-pg-table/account-security.json +1 -0
- package/dist/registry/ts-pg-table/account-settings.json +1 -0
- package/dist/registry/ts-pg-table/admin-admins.json +1 -0
- package/dist/registry/ts-pg-table/admin-analytics.json +1 -0
- package/dist/registry/ts-pg-table/admin-billing.json +1 -0
- package/dist/registry/ts-pg-table/admin-content.json +1 -0
- package/dist/registry/ts-pg-table/admin-logs.json +1 -0
- package/dist/registry/ts-pg-table/admin-support.json +1 -0
- package/dist/registry/ts-pg-table/admin-system.json +1 -0
- package/dist/registry/ts-pg-table/admin-users.json +1 -0
- package/dist/registry/ts-pg-table/admin.json +1 -0
- package/dist/registry/ts-pg-table/auth.json +1 -0
- package/dist/registry/ts-pg-table/auth@apple.json +1 -0
- package/dist/registry/ts-pg-table/auth@google.json +1 -0
- package/dist/registry/ts-pg-table/billing.json +1 -0
- package/dist/registry/ts-pg-table/email-client.json +1 -0
- package/dist/registry/ts-pg-table/email-verification.json +1 -0
- package/dist/registry/ts-pg-table/files.json +1 -0
- package/dist/registry/ts-pg-table/forgot-password.json +1 -0
- package/dist/registry/ts-pg-table/notifications.json +1 -0
- package/dist/registry/ts-pg-table/support.json +1 -0
- package/dist/registry/ts-pg-table/user-profile.json +1 -0
- package/dist/tasks/index.d.cts +1 -1
- package/dist/tasks/index.d.ts +1 -1
- package/dist/{types-B6lVw4bj.d.ts → types-gyvA7BtO.d.cts} +18 -1
- package/dist/{types-B6lVw4bj.d.cts → types-gyvA7BtO.d.ts} +18 -1
- package/package.json +11 -2
- package/dist/chunk-6OGOVV57.js.map +0 -1
- package/dist/chunk-AZYXQU3Z.cjs.map +0 -1
- package/dist/chunk-BUBXO7WU.js.map +0 -1
- package/dist/chunk-MGH4VDV3.cjs.map +0 -1
- /package/dist/{chunk-TRC4DUZB.js.map → chunk-RSZB7VAO.js.map} +0 -0
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# efc add — the feature registry
|
|
2
|
+
|
|
3
|
+
EFC apps start small and grow one feature at a time, the way [shadcn/ui](https://ui.shadcn.com) works for components. `create-efc-app` writes the **base** app: the server, `src/api`, `src/tasks` and the database. `efc add` copies ready-made **features** into it: auth (email/password, Google, Apple), a user portal, an admin portal, billing, an email client and more.
|
|
4
|
+
|
|
5
|
+
The copied files are ordinary source in your app. You read them, change them and commit them. Nothing about a feature is hidden in a package.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
efc list # what can be added
|
|
9
|
+
efc add auth forgot-password # copy features in (dependencies come along)
|
|
10
|
+
efc add email-client # asks for your SMTP settings
|
|
11
|
+
efc add auth@google auth@apple # asks for the OAuth credentials
|
|
12
|
+
efc view billing # read an item's files before adding it
|
|
13
|
+
efc diff # compare installed features with the registry
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Commands
|
|
19
|
+
|
|
20
|
+
| Command | What it does |
|
|
21
|
+
|---|---|
|
|
22
|
+
| `efc add <item...>` | Shows the plan (files, packages, env vars), asks to confirm, asks the items' [questions](#questions) (SMTP settings, OAuth credentials…), then writes the files, adds the packages to `package.json`, runs your package manager, and writes the answers to `.env` (placeholders to `.env.example`) |
|
|
23
|
+
| `efc list` | Lists every item by group; installed ones are ticked |
|
|
24
|
+
| `efc view <item> [--json]` | Prints an item's files as they'd be written for *this* app (language + database) |
|
|
25
|
+
| `efc diff [item]` | For installed items, shows each file that was changed in the app or has a newer registry version, with a line diff |
|
|
26
|
+
| `efc init [--force]` | Writes `efc.json` for an existing app (detects language, database, model API and task backend). `efc add` does this itself when there's no `efc.json` yet |
|
|
27
|
+
|
|
28
|
+
`efc add` options:
|
|
29
|
+
|
|
30
|
+
| Flag | |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `-y, --yes` | Skip the confirmation. Required when not in a terminal (CI, agents) |
|
|
33
|
+
| `--dry-run` | Print the plan and stop |
|
|
34
|
+
| `--overwrite` | Replace files you've changed with the registry version |
|
|
35
|
+
| `--no-install` | Don't run `npm install` / `pnpm install` / … afterwards |
|
|
36
|
+
| `--no-prompt` | Don't ask the items' questions — write placeholders to `.env` instead |
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Items
|
|
41
|
+
|
|
42
|
+
| Item | Adds | Needs |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `auth` | `User` + `Admin` models; `POST /auth/register`, `/auth/login`, `/auth/logout`, `GET /auth/me` | — |
|
|
45
|
+
| `auth@google` | Sign in with Google: `GET /auth/google` → Google → `GET /auth/google/callback` (+ `OAuthAccount` model). Asks for the client ID / secret | auth |
|
|
46
|
+
| `auth@apple` | Sign in with Apple: `GET /auth/apple` → Apple → `POST /auth/apple/callback` (+ `OAuthAccount`). Asks for Services ID, Team ID, Key ID and the `.p8` key | auth |
|
|
47
|
+
| `user-profile` | `GET/PUT /user/profile` | auth |
|
|
48
|
+
| `forgot-password` | `/auth/forgot-password`, `/auth/reset-password` | auth |
|
|
49
|
+
| `account-security` | change password, 2FA, sessions, token refresh + `Session` model | auth |
|
|
50
|
+
| `email-verification` | `/auth/verify-email`, resend | auth |
|
|
51
|
+
| `account-settings` | avatar, settings, account, dashboard, activity | auth |
|
|
52
|
+
| `notifications` | `Notification` model + `/user/notifications` | auth |
|
|
53
|
+
| `files` | `File` model + files, favorites, bookmarks, search | auth |
|
|
54
|
+
| `billing` | `Plan`, `Subscription`, `Invoice`, `ApiKey` + user billing & API-key routes | auth |
|
|
55
|
+
| `support` | `SupportTicket` model + `/support/tickets` | auth |
|
|
56
|
+
| `admin` | `GET /admin/dashboard` (stats), behind `requireAuth('admin')` | auth |
|
|
57
|
+
| `admin-users` | list / create / suspend / verify / export users | admin |
|
|
58
|
+
| `admin-admins` | manage admins + `Role` model | admin |
|
|
59
|
+
| `admin-analytics` | users, revenue, traffic | admin |
|
|
60
|
+
| `admin-content` | `FAQ`, `Blog`, `Category` + admin CRUD | admin |
|
|
61
|
+
| `admin-billing` | `Plan`, `Coupon` + plans, coupons, subscriptions | admin |
|
|
62
|
+
| `admin-support` | `SupportTicket` + view & respond to tickets | admin |
|
|
63
|
+
| `admin-logs` | `AuditLog`, `Notification` + broadcast, audit/activity/security logs | admin |
|
|
64
|
+
| `admin-system` | settings, health, cache | admin |
|
|
65
|
+
| `email-client` (alias `mailer`) | replaces the `SendEmail` stub with a real SMTP sender (nodemailer). Asks for Gmail or a custom SMTP server and its credentials | — |
|
|
66
|
+
|
|
67
|
+
The full route list is in [Generated Portals](../guides/generated-portals.md); OAuth setup is in [Sign in with Google & Apple](../guides/oauth.md).
|
|
68
|
+
|
|
69
|
+
A few things hold for every item:
|
|
70
|
+
|
|
71
|
+
- **Dependencies come along.** `efc add admin-users` also installs `auth` and `admin` if they're missing.
|
|
72
|
+
- **Routes that send email** (`auth`, `forgot-password`, `email-verification`) enqueue the `SendEmail` task. The base app has a stub that logs the message. `efc add email-client` swaps in real SMTP. These items need a task backend (`tasks` in `efc.config`); the base app always has one.
|
|
73
|
+
- **Models shared by two items** (`Plan`, `SupportTicket`, `Notification`) are identical in both. The second item skips the file that's already there.
|
|
74
|
+
- **On PostgreSQL with `defineTable`**, references are real foreign keys, and `efc add` registers new models in `src/model/index.ts` (the export plus the `Tables` entry). Models declare no back-relations. Add `relations: { … }` to a model when you want `include`. See [defineTable](../api-reference/table.md).
|
|
75
|
+
- **Tables and collections** are created on first use (`autoSync`). With `autoSync: false`, run `efc db sync` or write a migration.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Questions
|
|
80
|
+
|
|
81
|
+
Some items need settings only you have. `efc add` asks for them in the terminal, and so does `create-efc-app` when you pick the feature there. The answers go straight into `.env` (gitignored); `.env.example` only ever gets placeholders.
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
$ efc add email-client
|
|
85
|
+
|
|
86
|
+
Configuration (saved to .env)
|
|
87
|
+
|
|
88
|
+
Email provider:
|
|
89
|
+
1) Gmail smtp.gmail.com, preconfigured
|
|
90
|
+
2) Other (custom SMTP) you'll provide host + port
|
|
91
|
+
Choose 1-2 (1): 1
|
|
92
|
+
Gmail address: you@gmail.com
|
|
93
|
+
Gmail app password (16 characters): ← hidden
|
|
94
|
+
From address: (you@gmail.com)
|
|
95
|
+
App URL (used in email links): (http://localhost:3000)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
| Item | Asks for |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `email-client` | Gmail or custom SMTP; host + port (custom); user; password (Gmail: a 16-character App Password); from address; app URL |
|
|
101
|
+
| `auth@google` | `GOOGLE_CLIENT_ID` (checked: `….apps.googleusercontent.com`), `GOOGLE_CLIENT_SECRET` (hidden), redirect URI, where to send the browser after sign-in |
|
|
102
|
+
| `auth@apple` | Services ID, Team ID and Key ID (10 characters each), the path to your `.p8` key (its contents are stored in `APPLE_PRIVATE_KEY`, newlines as `\n`), return URL (must be https), where to send the browser after sign-in |
|
|
103
|
+
|
|
104
|
+
Wrong answers are asked again. A question is only asked for a variable the app doesn't have yet, so re-adding an item never overwrites your settings. Without a terminal (CI, coding agents), or with `--no-prompt`, nothing is asked: the variables get placeholders and `efc add` lists the ones to fill in.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## efc.json
|
|
109
|
+
|
|
110
|
+
`create-efc-app` writes `efc.json` at the project root. Commit it.
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"registry": "0.9.0",
|
|
115
|
+
"language": "typescript",
|
|
116
|
+
"database": "postgresql",
|
|
117
|
+
"modelApi": "defineTable",
|
|
118
|
+
"tasks": "pg-boss",
|
|
119
|
+
"items": ["auth", "billing"],
|
|
120
|
+
"files": {
|
|
121
|
+
"src/api/auth/login.ts": "9f2c…",
|
|
122
|
+
"src/model/User.ts": "41ab…"
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
- `language`, `database` and `modelApi` pick the variant of each item: TypeScript or JavaScript, and MongoDB, PostgreSQL `defineModel` or PostgreSQL `defineTable`.
|
|
128
|
+
- `files` is the sha256 of every file as efc last wrote it. This is how `efc add` tells a file you haven't touched (safe to update) from one you've changed (left alone unless `--overwrite`). For example, `efc add email-client` replaces the base `SendEmail` stub only if you haven't edited it.
|
|
129
|
+
|
|
130
|
+
Apps created before 0.8 have no `efc.json`. `efc add` detects the variant from `package.json` and `src/`, then creates the file. Files that already exist count as yours: if they differ from the registry, they show up as conflicts and are never overwritten silently.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Where the registry comes from
|
|
135
|
+
|
|
136
|
+
The registry ships inside `express-file-cluster` (`node_modules/express-file-cluster/dist/registry`), rendered from the same templates `create-efc-app` uses. Items therefore always match the framework version you have installed, and `efc add` works offline. After upgrading `express-file-cluster`, `efc diff` shows what changed in the features you installed, and `efc add <item>` updates the files you haven't touched.
|
package/dist/docs/cli/db.md
CHANGED
|
@@ -3,8 +3,12 @@
|
|
|
3
3
|
Database migrations, seeds and studio. Works on MongoDB and PostgreSQL — the engine follows the `DATABASE_URL` scheme. Full guide: [Migrations & Seeds](../guides/migrations.md).
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
|
+
efc db generate <name> # write a migration: models vs. what src/migrations produce
|
|
7
|
+
efc db generate --verify # fail if the migrations miss anything the models declare
|
|
6
8
|
efc db sync [--dry-run] # reconcile tables/collections + indexes with src/model(s)/
|
|
7
|
-
efc db
|
|
9
|
+
efc db sync --dry-run --exit-code # exit 2 when the database has drifted from the models
|
|
10
|
+
efc db migrate [--baseline] # run pending migrations (one new batch); --baseline only records them
|
|
11
|
+
efc db pull [--out src/model] # write defineTable models for the database (PostgreSQL)
|
|
8
12
|
efc db rollback [--steps 2] # revert the last batch(es)
|
|
9
13
|
efc db status # applied vs pending
|
|
10
14
|
efc db seed [name] # run all seeds, or one
|
|
@@ -26,9 +30,28 @@ efc db studio [--port 4983] # read-only browser on 127.0.0.1 (rows + table st
|
|
|
26
30
|
| No `tsx` (production image) | `node` | `dist/src/migrations`, `dist/src/seeds` |
|
|
27
31
|
| JavaScript project | `node` | `src/` |
|
|
28
32
|
|
|
33
|
+
## `efc db generate` options
|
|
34
|
+
|
|
35
|
+
| Option | Meaning |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `[name]` | Write the migration as `src/migrations/<UTC timestamp>_<name>.(ts\|js)`; without it, print the plan |
|
|
38
|
+
| `--allow-drop` | Also drop columns the models no longer declare |
|
|
39
|
+
| `--tighten` | Add `NOT NULL` for required fields and validate enum checks, each behind a row check |
|
|
40
|
+
| `--verify` | Replay every migration into a throwaway schema and exit `1` if the models need more |
|
|
41
|
+
|
|
42
|
+
`generate` connects to `DATABASE_URL`'s server but works in a temporary schema (PostgreSQL) or database (MongoDB), dropped afterwards; your data isn't read or changed.
|
|
43
|
+
|
|
44
|
+
## `efc import-prisma`
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
efc import-prisma [prisma/schema.prisma] [--out src/model] [--force]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Writes `defineTable` models from a Prisma schema (PostgreSQL). See [Coming from Prisma](../guides/coming-from-prisma.md).
|
|
51
|
+
|
|
29
52
|
## Exit codes
|
|
30
53
|
|
|
31
|
-
`0` on success, `1` on any failure (connection, a throwing migration/seed, missing `down()` on rollback). Set `EFC_DEBUG=1` for stack traces.
|
|
54
|
+
`0` on success, `1` on any failure (connection, a throwing migration/seed, missing `down()` on rollback, `generate --verify` finding missing steps). `efc db sync --dry-run --exit-code` exits `2` when there are pending changes. Set `EFC_DEBUG=1` for stack traces.
|
|
32
55
|
|
|
33
56
|
## Scaffolding
|
|
34
57
|
|
package/dist/docs/cli/index.md
CHANGED
|
@@ -24,12 +24,20 @@ npm install --save-dev express-file-cluster
|
|
|
24
24
|
| `efc start prod` | Production server — runs `dist/` with clustering |
|
|
25
25
|
| `efc build prod` | Type-check + transpile `src/` to `dist/src/` |
|
|
26
26
|
| `efc run tests` | Run tests via Vitest |
|
|
27
|
+
| `efc add <item...>` | Copy features (auth, portals, billing, mailer…) into the app from the registry |
|
|
28
|
+
| `efc list` / `efc view <item>` | List registry items / print an item's files |
|
|
29
|
+
| `efc diff [item]` | Compare installed features with the registry |
|
|
30
|
+
| `efc init` | Write `efc.json` for an app made before 0.8 |
|
|
27
31
|
| `efc generate route <path>` | Scaffold a route file |
|
|
28
32
|
| `efc generate task <name>` | Scaffold a task file |
|
|
29
33
|
| `efc generate middleware <name>` | Scaffold a middleware file |
|
|
30
34
|
| `efc generate migration <name>` | Scaffold a timestamped migration |
|
|
31
35
|
| `efc generate seed <name>` | Scaffold a seed script |
|
|
32
|
-
| `efc db
|
|
36
|
+
| `efc db generate [name] [--allow-drop] [--tighten] [--verify]` | Write a migration from the models (or verify the migrations match them) |
|
|
37
|
+
| `efc db migrate [--baseline] \| rollback \| status` | Run, revert and inspect migrations |
|
|
38
|
+
| `efc db sync [--dry-run] [--exit-code]` | Bring the database in line with the models; `--exit-code` exits 2 on drift |
|
|
39
|
+
| `efc db pull [--out dir] [--force]` | Write `defineTable` models for an existing PostgreSQL database |
|
|
40
|
+
| `efc import-prisma [schema.prisma] [--out dir]` | Write `defineTable` models from a Prisma schema |
|
|
33
41
|
| `efc db seed [name]` | Run seed scripts |
|
|
34
42
|
| `efc db studio` | Read-only database browser on 127.0.0.1 |
|
|
35
43
|
| `efc routes` | Print the resolved route table |
|
|
@@ -43,6 +51,7 @@ npm install --save-dev express-file-cluster
|
|
|
43
51
|
## Detailed pages
|
|
44
52
|
|
|
45
53
|
- [start / build / run](./start.md) — Lifecycle commands
|
|
54
|
+
- [add](./add.md) — the feature registry: `add`, `list`, `view`, `diff`, `init`
|
|
46
55
|
- [generate](./generate.md) — Code generation
|
|
47
56
|
- [db](./db.md) — migrations, seeds, studio
|
|
48
57
|
- [diagnostics](./diagnostics.md) — `routes`, `tasks` (incl. dead letters), `doctor`
|
|
@@ -141,4 +141,4 @@ efc generate middleware authorize
|
|
|
141
141
|
# → src/middlewares/authorize.ts
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
-
> Route-level role protection doesn't need a custom middleware like `authorize` above — `requireAuth` itself accepts role names: `requireAuth('admin')`. `
|
|
144
|
+
> Route-level role protection doesn't need a custom middleware like `authorize` above — `requireAuth` itself accepts role names: `requireAuth('admin')`. The routes `efc add` generates use this shorthand, and `efc add admin-admins` adds a `Role` model. See [RBAC](../guides/rbac.md).
|
|
@@ -14,32 +14,38 @@
|
|
|
14
14
|
npx create-efc-app my-api
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
The interactive wizard
|
|
17
|
+
The interactive wizard asks for the **base** app, then offers features:
|
|
18
18
|
|
|
19
19
|
```
|
|
20
20
|
? Project name: my-api
|
|
21
21
|
? Language: TypeScript | JavaScript
|
|
22
22
|
? Database: MongoDB | PostgreSQL
|
|
23
23
|
? Models: defineTable | defineModel (PostgreSQL only)
|
|
24
|
-
?
|
|
25
|
-
?
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
◉ Role-based access control
|
|
32
|
-
◯ Mailer
|
|
24
|
+
? Task queue backend: pg-boss | BullMQ (BullMQ on MongoDB)
|
|
25
|
+
? Multi-core clustering? Yes
|
|
26
|
+
? Add features now? (none by default — or add any later with `efc add`)
|
|
27
|
+
Auth ◯ Authentication ◯ Sign in with Google ◯ Sign in with Apple
|
|
28
|
+
User portal ◯ Profile ◯ Forgot / reset password ◯ Account security …
|
|
29
|
+
Admin portal ◯ Admin portal ◯ User management ◯ Analytics …
|
|
30
|
+
Integrations ◯ Email client
|
|
33
31
|
```
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
The base app is the server, `src/api` (with a `/health` route), `src/tasks` (with a `SendEmail` task stub) and the database connection. Everything else is a **feature** from the registry. You can pick features here or add them at any time with [`efc add`](../cli/add.md), which copies the same files in:
|
|
36
34
|
|
|
37
|
-
|
|
35
|
+
```bash
|
|
36
|
+
efc add auth forgot-password admin-users
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
On **PostgreSQL**, models default to [`defineTable`](../api-reference/table.md): PostgreSQL-native, with real foreign keys between the feature models (a user's sessions, invoices, tickets…) and Prisma-style queries in the generated routes. Pick **defineModel** instead for the portable API. On **MongoDB**, models are `defineModel`, which compiles to mongoose. See [Database](../guides/database.md).
|
|
40
|
+
|
|
41
|
+
Depending on what you pick, you'll see follow-up questions:
|
|
42
|
+
|
|
43
|
+
- **Task queue backend.** `pg-boss` stores jobs in your PostgreSQL, so there's no Redis to run. `BullMQ` uses Redis (`REDIS_URL` in `.env`).
|
|
44
|
+
- **Authentication** (or any feature that needs it) → pick a strategy: `http-only` (cookie) or `localStorage` (Bearer token).
|
|
45
|
+
- **Sign in with Google / Apple** → the OAuth client credentials (Apple: Services ID, Team ID, Key ID and the path to your `.p8` key). See [Sign in with Google & Apple](../guides/oauth.md).
|
|
46
|
+
- **Email client** → pick an email provider: `Gmail` (preconfigured `smtp.gmail.com`, no host or port to type) or `Other (custom SMTP)` (asks for host + port). Either way you're then asked for the sending email address and password. **For Gmail this must be a 16-character App Password, not your normal Gmail password.** The prompt rejects anything that isn't 16 characters. See [Mailer](../guides/mailer.md) for the full walkthrough, including how to generate an App Password.
|
|
38
47
|
|
|
39
|
-
|
|
40
|
-
- **Mailer** → pick an email provider: `Gmail` (preconfigured `smtp.gmail.com`, no host/port to type) or `Other (custom SMTP)` (asks for host + port). Either way you're then asked for the sending email address and password. **For Gmail this must be a 16-character App Password, not your normal Gmail password** — the prompt validates the length and rejects anything that isn't 16 characters. See [Mailer](../guides/mailer.md) for the full walkthrough, including how to generate an App Password.
|
|
41
|
-
- **User portal / Admin portal** → scaffold a large set of ready-made models and routes (auth, profile, billing, support tickets, admin dashboard, content management, etc.). See [Generated Portals](../guides/generated-portals.md) for the complete list.
|
|
42
|
-
- **Role-based access control** → generates a `Role` model and swaps every protected route's `middlewares` export to use the `requireAuth('role')` shorthand instead of an inline guard. See [RBAC](../guides/rbac.md).
|
|
48
|
+
Protected routes use `requireAuth('role')` (see [RBAC](../guides/rbac.md)). [Generated Portals](../guides/generated-portals.md) lists every route the features add.
|
|
43
49
|
|
|
44
50
|
After confirmation it:
|
|
45
51
|
|
|
@@ -48,8 +54,9 @@ After confirmation it:
|
|
|
48
54
|
3. Generates `.env` (gitignored, `JWT_SECRET` pre-filled with `openssl rand -hex 64`, plus `SMTP_*` vars if you enabled the mailer) and `.env.example` (committed, documented placeholders).
|
|
49
55
|
4. Adds `.env` to `.gitignore`.
|
|
50
56
|
5. Writes `package.json` lifecycle scripts (`dev`, `build`, `start`, `test`, `db:migrate`, `db:rollback`, `db:seed`, `db:studio`).
|
|
51
|
-
6. With
|
|
52
|
-
7.
|
|
57
|
+
6. With features that have models, writes `src/migrations/00000000000000_init`, which creates every model's table/collection and indexes.
|
|
58
|
+
7. Writes `efc.json`: the app's variant, its features, and a hash of each file, which [`efc add`](../cli/add.md) uses later.
|
|
59
|
+
8. Runs `npm install` with the dependencies for your selections, then installs the `efc` CLI globally.
|
|
53
60
|
|
|
54
61
|
---
|
|
55
62
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Project Structure
|
|
2
2
|
|
|
3
|
-
A scaffolded EFC project looks like this:
|
|
3
|
+
A scaffolded EFC project with the `auth` feature looks like this. The base app alone has just `api/health.ts`, `tasks/SendEmail.ts` and the config files:
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
my-api/
|
|
@@ -10,20 +10,19 @@ my-api/
|
|
|
10
10
|
│ │ ├── auth/
|
|
11
11
|
│ │ │ ├── login.ts # POST /auth/login
|
|
12
12
|
│ │ │ ├── logout.ts # POST /auth/logout
|
|
13
|
-
│ │ │
|
|
14
|
-
│ │ └──
|
|
15
|
-
│ │ ├── index.ts # GET /users • POST /users
|
|
16
|
-
│ │ └── [id].ts # GET /users/:id • DELETE /users/:id
|
|
13
|
+
│ │ │ ├── me.ts # GET /auth/me
|
|
14
|
+
│ │ │ └── register.ts # POST /auth/register
|
|
17
15
|
│ ├── tasks/ # Background jobs (scanned non-recursively)
|
|
18
16
|
│ │ └── SendEmail.ts # task name: "SendEmail"
|
|
19
17
|
│ ├── model/ # Engine-agnostic data models
|
|
20
18
|
│ │ ├── User.ts
|
|
21
|
-
│ │ └──
|
|
19
|
+
│ │ └── Admin.ts
|
|
22
20
|
│ ├── migrations/ # efc db migrate — run in filename order
|
|
23
21
|
│ │ └── 00000000000000_init.ts # syncs every generated model
|
|
24
22
|
│ ├── seeds/ # efc db seed (create with efc generate seed)
|
|
25
23
|
│ └── index.ts # Framework entry point
|
|
26
24
|
├── efc.config.ts # Structural configuration
|
|
25
|
+
├── efc.json # Variant + installed features, for efc add
|
|
27
26
|
├── .env # Real secrets — gitignored
|
|
28
27
|
├── .env.example # Documented template — safe to commit
|
|
29
28
|
├── .gitignore
|
|
@@ -31,7 +30,7 @@ my-api/
|
|
|
31
30
|
└── tsconfig.json
|
|
32
31
|
```
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
Each feature you add (at creation or later with [`efc add`](../cli/add.md)) fills out `src/model/`, `src/api/` and `src/tasks/`. See [Generated Portals](../guides/generated-portals.md) for the full list of models and routes, [RBAC](../guides/rbac.md) for the `requireAuth('role')` shorthand, and [Mailer](../guides/mailer.md) for the SMTP setup.
|
|
35
34
|
|
|
36
35
|
---
|
|
37
36
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
EFC ships a complete JWT authentication system. Choose between two delivery strategies depending on your frontend architecture.
|
|
4
4
|
|
|
5
|
+
> Ready-made routes: `efc add auth` (register / login / logout / me) and `efc add auth@google` / `auth@apple` ([Sign in with Google & Apple](./oauth.md)). See [efc add](../cli/add.md).
|
|
6
|
+
|
|
5
7
|
---
|
|
6
8
|
|
|
7
9
|
## Choosing a strategy
|
|
@@ -169,7 +171,7 @@ JWT_EXPIRES_IN=7d # default
|
|
|
169
171
|
JWT_EXPIRES_IN=30d
|
|
170
172
|
```
|
|
171
173
|
|
|
172
|
-
There is currently no refresh-token mechanism built into the framework itself. For long-lived sessions with short-lived tokens, implement a `/auth/refresh` route that issues a new token using the existing one as a credential —
|
|
174
|
+
There is currently no refresh-token mechanism built into the framework itself. For long-lived sessions with short-lived tokens, implement a `/auth/refresh` route that issues a new token using the existing one as a credential — the `account-security` feature (`efc add account-security`) generates a working `POST /auth/refresh` route: it stores a rotating long-lived refresh token in the database and reads it from an `efc_refresh_token` cookie or the `refreshToken` body field (see [Generated Portals](./generated-portals.md)).
|
|
173
175
|
|
|
174
176
|
---
|
|
175
177
|
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Coming from Prisma
|
|
2
|
+
|
|
3
|
+
`defineTable` speaks Prisma's query language on PostgreSQL, with the schema written in TypeScript instead of a `.prisma` file and no generate step. This guide moves a Prisma app over.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Import the schema
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx efc import-prisma prisma/schema.prisma
|
|
11
|
+
# → src/model/User.ts, Post.ts, … and src/model/index.ts
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`import-prisma` writes one `defineTable` model per Prisma model, over the **same tables and columns**:
|
|
15
|
+
|
|
16
|
+
| Prisma | EFC |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `model Post { … }` (table `Post`) / `@@map("posts")` | `defineTable('Post', …, { collection: 'Post' })`, or nothing when the name already matches EFC's default (`posts`) |
|
|
19
|
+
| `id String @id @default(uuid())` | the default `uuid` id |
|
|
20
|
+
| `id Int @id @default(autoincrement())` / `BigInt` | `{ id: 'serial' }` / `{ id: 'bigserial' }` |
|
|
21
|
+
| `String`, `Int`, `BigInt`, `Float`, `Decimal`, `Boolean`, `DateTime`, `Json` | `string`, `integer`, `bigint`, `number`, `decimal`, `boolean`, `date`, `json` |
|
|
22
|
+
| `@db.VarChar(80)`, `@db.Decimal(10, 2)`, `@db.Uuid` | `maxLength: 80`, `precision: 10, scale: 2`, `uuid` |
|
|
23
|
+
| `String[]` | `{ type: 'array', of: 'string' }` (a native `text[]`) |
|
|
24
|
+
| `enum Role { USER ADMIN }` | `{ type: 'string', enum: ['USER', 'ADMIN'], nativeEnum: true }` |
|
|
25
|
+
| required (no `?`) | `required: true` |
|
|
26
|
+
| `@unique`, `@@unique([a, b])`, `@@index([a, b(sort: Desc)])` | `unique: true`, `indexes: [{ fields: { a: 1, b: -1 }, unique? }]` |
|
|
27
|
+
| `@default(now())`, `uuid()`/`cuid()`, literals, `autoincrement()` | `'$now'`, `'$uuid'`, the literal, `sequence: true` |
|
|
28
|
+
| `@map("col")` | `column: 'col'` |
|
|
29
|
+
| `createdAt @default(now())` + `updatedAt @updatedAt` | EFC timestamps (the default) |
|
|
30
|
+
| `author User @relation(fields: [authorId], references: [id], onDelete: Cascade)` + `authorId Int` | `author: { type: 'integer', ref: 'User', required: true, column: 'authorId', onDelete: 'cascade' }`: one field, a real foreign key |
|
|
31
|
+
| `posts Post[]` (the other side) | `relations: { posts: { hasMany: 'Post', foreignKey: 'author' } }` |
|
|
32
|
+
| `profile Profile?` (the other side of a unique FK) | `relations: { profile: { hasOne: 'Profile', foreignKey: 'user' } }` |
|
|
33
|
+
| implicit many-to-many `categories Category[]` ↔ `posts Post[]` | an array of refs on one side (`{ type: 'array', of: 'integer', ref: 'Post' }`), a `hasMany` relation on the other |
|
|
34
|
+
|
|
35
|
+
Whatever doesn't carry over is listed as a comment at the top of the model. That includes composite ids and foreign keys, `Bytes` and `Unsupported(...)` types, `dbgenerated()` defaults, and `onDelete: SetDefault`. MongoDB Prisma schemas are refused: `defineTable` is PostgreSQL-only.
|
|
36
|
+
|
|
37
|
+
**One naming difference.** Prisma keeps a relation (`author`) and its foreign-key scalar (`authorId`) as two fields. EFC has one field, `author`, holding the id. It's stored in the `authorId` column, and `include: { author: true }` swaps the id for the record. Write `{ author: userId }` where Prisma wrote `{ authorId: userId }`.
|
|
38
|
+
|
|
39
|
+
## 2. Point EFC at the database
|
|
40
|
+
|
|
41
|
+
Two routes:
|
|
42
|
+
|
|
43
|
+
- **A new database:**
|
|
44
|
+
```bash
|
|
45
|
+
efc db generate init --tighten # a migration for the whole schema, with NOT NULLs
|
|
46
|
+
efc db migrate
|
|
47
|
+
```
|
|
48
|
+
- **The database Prisma already manages:** try it on a copy first.
|
|
49
|
+
```bash
|
|
50
|
+
efc db sync --dry-run # what EFC would change on the live tables
|
|
51
|
+
```
|
|
52
|
+
Expect EFC's own names for constraints and indexes it adds, `timestamptz` for `DateTime` columns, and a `<table>_<column>_enum` type per enum column. Prisma's `_AToB` join tables aren't read: copy their rows into EFC's join table (`<table>_<field>`: `owner_id`, `ref_id`, `position`) once it exists. The model comment says which table to copy from.
|
|
53
|
+
|
|
54
|
+
From then on, `efc db generate <name>` writes migrations from model changes. See [Migrations](./migrations.md).
|
|
55
|
+
|
|
56
|
+
## 3. Port the queries
|
|
57
|
+
|
|
58
|
+
Most Prisma Client calls keep their shape. Swap `prisma.post` for the `Post` model:
|
|
59
|
+
|
|
60
|
+
| Prisma Client | EFC |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `prisma.post.findMany({ where, orderBy, take, skip, cursor, select, include, distinct })` | `Post.findMany({ … })`, same keys |
|
|
63
|
+
| `findUnique`, `findUniqueOrThrow`, `findFirst`, `findFirstOrThrow`, `count`, `aggregate`, `groupBy` | same names |
|
|
64
|
+
| `create`, `createMany({ skipDuplicates })`, `createManyAndReturn` | same |
|
|
65
|
+
| `update`, `updateMany`, `updateManyAndReturn`, `upsert`, `delete`, `deleteMany` | same |
|
|
66
|
+
| filters: `equals`, `in`, `lt`…, `contains`/`startsWith` + `mode: 'insensitive'`, `AND`/`OR`/`NOT`, `some`/`every`/`none`, `is`/`isNot`, `has` | same |
|
|
67
|
+
| updates: `{ increment: 1 }`, `set`, `push` | same |
|
|
68
|
+
| nested writes: `connect`, `create`, `connectOrCreate`, `disconnect`, `set`, `delete`, `deleteMany` | same (in `create`, `update`, `upsert`) |
|
|
69
|
+
| `prisma.$transaction(async (tx) => { tx.post… })` | `transaction(async () => { Post… })`: no `tx` to pass, calls inside join it |
|
|
70
|
+
| `prisma.$queryRaw` | `db.query(sql, params)` (the `pg` Pool) |
|
|
71
|
+
| generated types (`Prisma.PostGetPayload<…>`) | inferred from the schema: `InferRecord<typeof Post>`, `InferCreate<typeof Post>` |
|
|
72
|
+
|
|
73
|
+
What you gain: validation in the model (`ModelValidationError` → 400 with `issues`), 409 on unique conflicts, and no `prisma generate` step. You also get a schema that keeps itself in step on first use (`autoSync`), or migrations written for you.
|
|
74
|
+
|
|
75
|
+
See [`defineTable`](../api-reference/table.md) for the full reference.
|
|
@@ -33,6 +33,8 @@ const config: EFCConfig = {
|
|
|
33
33
|
};
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
Not sure whether to use `defineModel` or the PostgreSQL-native `defineTable`? See [Which model API?](./which-api.md).
|
|
37
|
+
|
|
36
38
|
Each worker process connects once during Pre-Flight, before routes mount — no cold connection on the first request.
|
|
37
39
|
|
|
38
40
|
---
|
|
@@ -71,6 +73,7 @@ Editing a model later works the same on both engines:
|
|
|
71
73
|
|---|---|---|
|
|
72
74
|
| Add a field | new documents have it | `ADD COLUMN` |
|
|
73
75
|
| Remove a field | old documents keep it, it's ignored | the column stays (no data loss), it's ignored |
|
|
76
|
+
| Rename a field (`renamedFrom: 'old'`) | old documents keep the old name until a migration (`efc db generate`) moves it | `RENAME COLUMN` — the data comes along |
|
|
74
77
|
| Make a field optional / drop `required` | works | relaxes any `NOT NULL` |
|
|
75
78
|
| Add or remove `enum` values | works | rebuilds the enum `CHECK` (existing rows aren't re-checked) |
|
|
76
79
|
| Change a field's `type` | new writes use it | `ALTER COLUMN … TYPE … USING <cast>` — fails clearly if existing data can't convert |
|
|
@@ -78,7 +81,7 @@ Editing a model later works the same on both engines:
|
|
|
78
81
|
|
|
79
82
|
On MongoDB the first query also waits for the collection's indexes, so `unique` is enforced from the very first write. If an index can't be built (e.g. duplicates are already stored) EFC logs a warning and the model keeps working without it — fix the data and run `efc db sync`.
|
|
80
83
|
|
|
81
|
-
Required fields, enums, bounds and custom validators are enforced by the model on writes, as on MongoDB. Columns and rows are never dropped by sync.
|
|
84
|
+
Required fields, enums, bounds and custom validators are enforced by the model on writes, as on MongoDB. Columns and rows are never dropped by sync. To drop columns, or to enforce `NOT NULL` in the database too, generate a migration: `efc db generate <name> --allow-drop --tighten`.
|
|
82
85
|
|
|
83
86
|
Fields the model doesn't declare behave like mongoose's defaults on both engines: ignored on writes, treated as absent in filters (`{ legacy: null }` and `{ legacy: { $exists: false } }` match), ignored in `sort`/`select`.
|
|
84
87
|
|
|
@@ -90,7 +93,7 @@ efc db sync # apply it now
|
|
|
90
93
|
efc db studio # browse rows and each table's structure
|
|
91
94
|
```
|
|
92
95
|
|
|
93
|
-
Prefer every schema change to go through review? Set `autoSync: false` in `ignite()`
|
|
96
|
+
Prefer every schema change to go through review? Set `autoSync: false` in `ignite()`. Then `efc db generate <name>` writes each change as a migration, and `efc db generate --verify` in CI checks that none is missing. See [Migrations & Seeds](./migrations.md).
|
|
94
97
|
|
|
95
98
|
---
|
|
96
99
|
|
|
@@ -1,26 +1,35 @@
|
|
|
1
1
|
# Generated Portals — User & Admin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The user and admin portals are a set of **registry items**: ready-made models and routes you pick in `create-efc-app` or add later with [`efc add`](../cli/add.md), anything from auth extras (2FA, sessions, password reset) to admin content management (blogs, FAQs, coupons). This page lists every route each item adds, so nothing you didn't ask for shows up as a surprise, and nothing you did add goes undocumented.
|
|
4
4
|
|
|
5
|
-
> Every model below is real on both databases. On MongoDB they're `defineModel` collections. On PostgreSQL they're [`defineTable`](../api-reference/table.md) models (or `defineModel`, if you picked it) linked by foreign keys
|
|
5
|
+
> Every model below is real on both databases. On MongoDB they're `defineModel` collections. On PostgreSQL they're [`defineTable`](../api-reference/table.md) models (or `defineModel`, if you picked it) linked by foreign keys. `Session`, `Notification`, `File`, `SupportTicket`, `Subscription`, `Invoice` and `ApiKey` reference `User` and are deleted with it. `Subscription` references `Plan`, and `Invoice` references its `Subscription`. `AuditLog`, `Blog` and assigned tickets reference an `Admin`, which is cleared when the admin is deleted. `Category` references its parent. Models carry no back-relations, so each feature stays self-contained. Add `relations` to a model when you want `include` (e.g. `user.sessions`). See [Database](./database.md).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## auth
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
- `POST /auth/logout`
|
|
13
|
-
- `src/model/User.ts`
|
|
11
|
+
`efc add auth` (every other item depends on it):
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
- `src/model/User.ts`, `src/model/Admin.ts`
|
|
14
|
+
- `POST /auth/register`, `POST /auth/login` (users and admins), `POST /auth/logout`, `GET /auth/me`
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
`efc add auth@google` / `auth@apple` add OAuth sign-in for users (`GET /auth/google` + `/auth/google/callback`, `GET /auth/apple` + `POST /auth/apple/callback`, `OAuthAccount` model). See [Sign in with Google & Apple](./oauth.md).
|
|
18
17
|
|
|
19
|
-
|
|
18
|
+
---
|
|
20
19
|
|
|
21
|
-
|
|
20
|
+
## User portal
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
| Item | Routes below |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `user-profile` | Profile: `/user/profile` |
|
|
25
|
+
| `forgot-password` | Auth: forgot / reset password |
|
|
26
|
+
| `account-security` | Auth: refresh, change password, 2FA, sessions (+ `Session`) |
|
|
27
|
+
| `email-verification` | Auth: verify email |
|
|
28
|
+
| `account-settings` | Profile: avatar, settings, account, dashboard, activity |
|
|
29
|
+
| `notifications` | Notifications (+ `Notification`) |
|
|
30
|
+
| `files` | Files, favorites / bookmarks, search (+ `File`) |
|
|
31
|
+
| `billing` | API keys, billing (+ `Plan`, `Subscription`, `Invoice`, `ApiKey`) |
|
|
32
|
+
| `support` | Support (+ `SupportTicket`) |
|
|
24
33
|
|
|
25
34
|
### Routes
|
|
26
35
|
|
|
@@ -58,17 +67,25 @@ Toggling **User portal** adds:
|
|
|
58
67
|
| Support | `GET /support/tickets`, `POST /support/tickets` |
|
|
59
68
|
| | `GET /support/tickets/:id`, `PUT /support/tickets/:id` |
|
|
60
69
|
|
|
61
|
-
|
|
70
|
+
Protected routes export `middlewares = [requireAuth('user', 'admin')]` (see [RBAC](./rbac.md)).
|
|
62
71
|
|
|
63
72
|
---
|
|
64
73
|
|
|
65
74
|
## Admin portal
|
|
66
75
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
76
|
+
| Item | Routes below |
|
|
77
|
+
|---|---|
|
|
78
|
+
| `admin` | Dashboard |
|
|
79
|
+
| `admin-users` | Users |
|
|
80
|
+
| `admin-admins` | Admins, Roles (+ `Role`) |
|
|
81
|
+
| `admin-analytics` | Analytics |
|
|
82
|
+
| `admin-content` | Content (+ `FAQ`, `Blog`, `Category`) |
|
|
83
|
+
| `admin-billing` | Billing (+ `Plan`, `Coupon`) |
|
|
84
|
+
| `admin-support` | Support (+ `SupportTicket`) |
|
|
85
|
+
| `admin-logs` | Notifications, Logs (+ `AuditLog`, `Notification`) |
|
|
86
|
+
| `admin-system` | Settings, System |
|
|
87
|
+
|
|
88
|
+
`Plan`, `SupportTicket` and `Notification` are shared with the user-portal items: both write the same file, and the second add skips it.
|
|
72
89
|
|
|
73
90
|
### Routes
|
|
74
91
|
|
|
@@ -100,10 +117,10 @@ Toggling **Admin portal** adds:
|
|
|
100
117
|
| Billing — Coupons | `GET /admin/billing/coupons`, `POST /admin/billing/coupons` |
|
|
101
118
|
| | `GET/PUT/DELETE /admin/billing/coupons/:id` |
|
|
102
119
|
| Billing — Subscriptions | `GET /admin/billing/subscriptions` |
|
|
103
|
-
| Roles
|
|
120
|
+
| Roles | `GET /admin/roles`, `POST /admin/roles` |
|
|
104
121
|
| | `GET/PUT/DELETE /admin/roles/:id` |
|
|
105
122
|
|
|
106
|
-
All admin routes export `middlewares = [requireAuth('admin')]`
|
|
123
|
+
All admin routes export `middlewares = [requireAuth('admin')]` (see [RBAC](./rbac.md)).
|
|
107
124
|
|
|
108
125
|
---
|
|
109
126
|
|
|
@@ -1,21 +1,18 @@
|
|
|
1
1
|
# Mailer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Every EFC app has a `SendEmail` background task. In the base app it's a stub that logs the message. The **email client** feature (`email-client`, alias `mailer`) replaces it with a real `nodemailer` transport wired to environment variables, so you never hand-write SMTP boilerplate.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
## Enabling it
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Pick **Email client** under *Integrations* when `create-efc-app` asks which features to add, or add it to an existing app:
|
|
10
10
|
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
◉ Background tasks
|
|
14
|
-
...
|
|
15
|
-
◉ Mailer
|
|
11
|
+
```bash
|
|
12
|
+
efc add email-client # replaces the SendEmail stub, adds nodemailer, asks for your SMTP settings
|
|
16
13
|
```
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
Both ask the same questions and write the answers to `.env`. (Without a terminal, or with `--no-prompt`, `efc add` writes placeholders instead.)
|
|
19
16
|
|
|
20
17
|
```
|
|
21
18
|
? Email provider:
|
|
@@ -145,7 +142,7 @@ See [Background Tasks](../core-concepts/background-tasks.md) for retry/backoff b
|
|
|
145
142
|
|
|
146
143
|
## Auth routes wired to the mailer
|
|
147
144
|
|
|
148
|
-
|
|
145
|
+
These generated routes always `enqueue('SendEmail', ...)`:
|
|
149
146
|
|
|
150
147
|
| Route | Sends |
|
|
151
148
|
|---|---|
|
|
@@ -153,7 +150,7 @@ If **User portal** is enabled alongside **Mailer** (MongoDB only), these generat
|
|
|
153
150
|
| `POST /auth/verify-email` (resend) | Same verification email, with a freshly generated token |
|
|
154
151
|
| `POST /auth/forgot-password` | Reset email with a link to `${APP_URL}/auth/reset-password?token=...` |
|
|
155
152
|
|
|
156
|
-
|
|
153
|
+
Without the mailer, the base `SendEmail` stub just logs each message (recipient and subject), so registration and password reset work in development without SMTP. Run `efc add email-client` when you want real email.
|
|
157
154
|
|
|
158
155
|
---
|
|
159
156
|
|