@meghjs/mcp 0.0.0-stage → 0.7.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/LICENSE +21 -0
- package/README.md +141 -2
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +37 -0
- package/dist/docs/advanced/caching.md +72 -0
- package/dist/docs/advanced/database.md +328 -0
- package/dist/docs/advanced/events.md +169 -0
- package/dist/docs/advanced/file-uploads.md +141 -0
- package/dist/docs/advanced/health.md +81 -0
- package/dist/docs/advanced/logging.md +96 -0
- package/dist/docs/advanced/mail.md +439 -0
- package/dist/docs/advanced/orm/migrations.md +210 -0
- package/dist/docs/advanced/orm/models.md +291 -0
- package/dist/docs/advanced/orm/queries.md +169 -0
- package/dist/docs/advanced/orm/query-builder.md +120 -0
- package/dist/docs/advanced/orm/relations.md +179 -0
- package/dist/docs/advanced/orm/seeding.md +129 -0
- package/dist/docs/advanced/orm.md +145 -0
- package/dist/docs/advanced/plugins.md +90 -0
- package/dist/docs/advanced/queue.md +217 -0
- package/dist/docs/advanced/scheduler.md +253 -0
- package/dist/docs/advanced/testing.md +257 -0
- package/dist/docs/advanced/views.md +335 -0
- package/dist/docs/ai/mcp.md +162 -0
- package/dist/docs/cli/basic.md +133 -0
- package/dist/docs/cli/database.md +112 -0
- package/dist/docs/cli/generators.md +605 -0
- package/dist/docs/cli/scaffold/auth.md +172 -0
- package/dist/docs/cli/scaffold/domains.md +224 -0
- package/dist/docs/cli/scaffold/index.md +77 -0
- package/dist/docs/cli/scaffold/rbac.md +118 -0
- package/dist/docs/cli/scaffold/templates.md +235 -0
- package/dist/docs/core-concept/authentication.md +162 -0
- package/dist/docs/core-concept/configuration.md +268 -0
- package/dist/docs/core-concept/controller.md +350 -0
- package/dist/docs/core-concept/dependency-injection.md +213 -0
- package/dist/docs/core-concept/error-handling.md +185 -0
- package/dist/docs/core-concept/middleware.md +143 -0
- package/dist/docs/core-concept/request-context.md +110 -0
- package/dist/docs/core-concept/validation.md +355 -0
- package/dist/docs/getting-started/application.md +233 -0
- package/dist/docs/getting-started/installation.md +166 -0
- package/dist/docs/getting-started/introduction.md +136 -0
- package/dist/docs/getting-started/upgrading-0.4.md +125 -0
- package/dist/docs/getting-started/upgrading-0.5.md +293 -0
- package/dist/docs/getting-started/upgrading-0.6.md +251 -0
- package/dist/docs/getting-started/upgrading-0.7.md +225 -0
- package/dist/docs/getting-started/upgrading-megh.md +91 -0
- package/dist/docs/getting-started/upgrading-next.md +12 -0
- package/dist/docs/getting-started/upgrading.md +137 -0
- package/dist/docs/getting-started/usage.md +194 -0
- package/dist/docs/index.md +58 -0
- package/dist/docs/microservices/openapi.md +387 -0
- package/dist/docs/microservices/websocket.md +165 -0
- package/dist/docs/production/deployment.md +256 -0
- package/dist/docs/production/security.md +307 -0
- package/dist/docs/reference/api.md +999 -0
- package/dist/docs/reference/faq.md +227 -0
- package/dist/docs/reference/versioning.md +105 -0
- package/dist/docs.d.ts +30 -0
- package/dist/docs.js +126 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +22 -0
- package/dist/megh.d.ts +59 -0
- package/dist/megh.js +207 -0
- package/dist/prompts.d.ts +3 -0
- package/dist/prompts.js +47 -0
- package/dist/result.d.ts +18 -0
- package/dist/result.js +48 -0
- package/dist/server.d.ts +17 -0
- package/dist/server.js +40 -0
- package/dist/tools/context.d.ts +11 -0
- package/dist/tools/context.js +2 -0
- package/dist/tools/database.d.ts +8 -0
- package/dist/tools/database.js +58 -0
- package/dist/tools/docs.d.ts +3 -0
- package/dist/tools/docs.js +63 -0
- package/dist/tools/generate.d.ts +10 -0
- package/dist/tools/generate.js +177 -0
- package/dist/tools/project.d.ts +3 -0
- package/dist/tools/project.js +84 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +10 -0
- package/package.json +58 -4
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upgrading to 0.7
|
|
3
|
+
description: "What changes in Megh 0.7.0: server-rendered views, the @meghjs/mcp server for AI assistants, deny-by-default authorization, the request context API, megh new --mvc and make:view; plus stricter dependency injection, mail address and attachment checks, and rate limiting."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upgrading to 0.7
|
|
7
|
+
|
|
8
|
+
0.7.0 adds server-rendered [views](/advanced/views), an
|
|
9
|
+
[MCP server](/ai/mcp) for AI assistants, opt-in
|
|
10
|
+
[deny-by-default authorization](/core-concept/authentication#deny-by-default)
|
|
11
|
+
and a [request context](/core-concept/request-context) API.
|
|
12
|
+
|
|
13
|
+
It also makes a few checks stricter, so code that used to run with a hidden
|
|
14
|
+
problem now fails early. Most apps need no changes. Read
|
|
15
|
+
[Breaking in 0.7.0](#breaking-in-0-7-0) before upgrading: each item says how to
|
|
16
|
+
tell whether it affects you.
|
|
17
|
+
|
|
18
|
+
`@meghjs/core`, `@meghjs/cli` and the new `@meghjs/mcp` share one version
|
|
19
|
+
number. Upgrade them together:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npm i @meghjs/core@~0.7.0
|
|
23
|
+
npm i -D @meghjs/cli@~0.7.0
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
0.7.0 is the last minor release before 1.0. See the
|
|
27
|
+
[versioning policy](/reference/versioning).
|
|
28
|
+
|
|
29
|
+
## Breaking in 0.7.0
|
|
30
|
+
|
|
31
|
+
### Unresolvable constructor parameters throw
|
|
32
|
+
|
|
33
|
+
A constructor parameter typed as an interface, a union or a primitive has no
|
|
34
|
+
runtime type, so it used to be injected as `undefined`. The service then
|
|
35
|
+
failed later, far from the cause. Now the class fails when it is first built,
|
|
36
|
+
with a `ContainerError` that names the class and the parameter:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
Cannot resolve parameter 0 of OrderService: its type is an interface, union
|
|
40
|
+
or primitive (emitted as Object). Use @Inject(TOKEN) on the parameter or
|
|
41
|
+
inject(TOKEN) in a field, type it as a class, or mark it @Optional().
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Affects you if** the app now fails at boot with this error. Fix the
|
|
45
|
+
parameter it names in one of these ways:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
constructor(
|
|
49
|
+
@Inject(PAYMENT_GATEWAY) private readonly gateway: PaymentGateway, // a token
|
|
50
|
+
@Optional() private readonly tracer?: Tracer, // undefined on purpose
|
|
51
|
+
) {}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`@Inject(token, { optional: true })` injects `undefined` when the token isn't
|
|
55
|
+
registered. Overrides and inject handlers still take precedence. See
|
|
56
|
+
[Dependency Injection: Errors](/core-concept/dependency-injection#errors).
|
|
57
|
+
|
|
58
|
+
### Mail addresses must be single addresses
|
|
59
|
+
|
|
60
|
+
A string such as `'ann@example.com, bob@example.com'` used to pass as one
|
|
61
|
+
address. The HTTP mailers (SendGrid, Mailgun, Postmark and Resend) sent it on
|
|
62
|
+
as is, so it reached every address in it. If the string came from user input,
|
|
63
|
+
an attacker could add themselves.
|
|
64
|
+
|
|
65
|
+
Each address must now be a single `local@domain` with no spaces, `,`, `;`,
|
|
66
|
+
`<`, `>` or quotes. A display name that contains a comma must be quoted:
|
|
67
|
+
`'"Lee, Ann" <ann@example.com>'`.
|
|
68
|
+
|
|
69
|
+
**Affects you if** you pass several recipients in one string. Pass an array
|
|
70
|
+
instead:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
await mailer.to(['ann@example.com', 'bob@example.com']).send(new InvoiceMail());
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Attachment URLs are refused by default
|
|
77
|
+
|
|
78
|
+
Every mailer now checks attachment `path`s when the message is built. Local
|
|
79
|
+
files are allowed. `http(s)://` URLs are refused unless you turn them on,
|
|
80
|
+
because a URL built from input could fetch cloud metadata or internal
|
|
81
|
+
services and mail the response out.
|
|
82
|
+
|
|
83
|
+
**Affects you if** an attachment's `path` is a URL. Allow URLs only if every
|
|
84
|
+
URL is yours, and consider confining local files to one folder:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
app.useMail({
|
|
88
|
+
allowUrlAccess: true, // default false
|
|
89
|
+
attachmentRoot: 'storage/invoices', // optional: only read files in here
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
See [Mail: Attachment paths](/advanced/mail#attachment-paths).
|
|
94
|
+
|
|
95
|
+
### Rate limits are stricter
|
|
96
|
+
|
|
97
|
+
- **One counter per route across URI versions.** A route served at `/v1/...`
|
|
98
|
+
and `/v2/...` by `@Version(['1', '2'])` used to get a separate limit per
|
|
99
|
+
version. Now the versions share one counter.
|
|
100
|
+
- **IPv6 clients are grouped by `/64`.** A client rotating addresses within
|
|
101
|
+
its `/64` used to get a fresh counter for every address. Change the prefix
|
|
102
|
+
with `useRateLimit({ ipv6Subnet })`. IPv4-mapped IPv6 addresses count as
|
|
103
|
+
IPv4.
|
|
104
|
+
- **The memory store holds at most 100,000 keys** and drops the oldest
|
|
105
|
+
windows first, so random keys can't grow the heap without limit. Change it
|
|
106
|
+
with `new MemoryRateLimitStore({ maxKeys })`.
|
|
107
|
+
|
|
108
|
+
**Affects you if** you rely on per-version limits, or many of your users share
|
|
109
|
+
an IPv6 `/64`. See [Security: Add rate limits](/production/security#add-rate-limits).
|
|
110
|
+
|
|
111
|
+
### `transports` only accepts `'socket'`
|
|
112
|
+
|
|
113
|
+
`SocketEventDispatcher.dispatch(event, data, { transports })` accepted
|
|
114
|
+
`'kafka'` and `'rabbitmq'` but ignored them. Any value other than `'socket'`
|
|
115
|
+
now throws before the event is sent.
|
|
116
|
+
|
|
117
|
+
**Affects you if** you pass `transports`. Remove the option, or use
|
|
118
|
+
`['socket']`. See [WebSocket: Emitting to clients](/microservices/websocket#emitting-to-clients).
|
|
119
|
+
|
|
120
|
+
### `megh -v` prints only the version
|
|
121
|
+
|
|
122
|
+
`megh -v` and `megh --version` print just the number, for example `0.7.0`. In
|
|
123
|
+
0.6.5 they printed the logo and `Megh v<version>`. The logo now appears only
|
|
124
|
+
with `megh --info`, which also has a short form, `megh -i`.
|
|
125
|
+
|
|
126
|
+
**Affects you if** a script parses `megh -v`. Read the whole output as the
|
|
127
|
+
version.
|
|
128
|
+
|
|
129
|
+
## New in 0.7.0
|
|
130
|
+
|
|
131
|
+
### Views
|
|
132
|
+
|
|
133
|
+
Megh renders HTML on the server with a Blade-style template engine:
|
|
134
|
+
`{{ }}` echoes, `@if` / `@foreach`, layouts with `@extends` and `@section`,
|
|
135
|
+
`@include`, stacks, and `<x-component>` tags with slots. Templates compile to
|
|
136
|
+
JavaScript once and are cached.
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
app.useViews(); // views/**/*.megh.html
|
|
140
|
+
|
|
141
|
+
@Get('/')
|
|
142
|
+
home() {
|
|
143
|
+
return Results.View('pages.home', { user });
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- **`@react` islands** mount a React component in the browser from inside a
|
|
148
|
+
view. Compiling JSX needs `@swc/core`.
|
|
149
|
+
- **`app.useMethodOverride()`** lets HTML forms reach `PUT`, `PATCH` and
|
|
150
|
+
`DELETE` routes with `@method('DELETE')`, and parses urlencoded bodies for
|
|
151
|
+
`@Body()`.
|
|
152
|
+
|
|
153
|
+
See [Views](/advanced/views).
|
|
154
|
+
|
|
155
|
+
### MCP server for AI assistants
|
|
156
|
+
|
|
157
|
+
[`@meghjs/mcp`](/ai/mcp) is a new package: a Model Context Protocol server
|
|
158
|
+
that lets assistants such as Claude Code, Cursor and VS Code read the Megh
|
|
159
|
+
docs, inspect your project (routes, structure, migrations, type errors) and
|
|
160
|
+
run the `megh` generators. In Claude Code:
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
claude mcp add megh -- npx -y @meghjs/mcp
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
It has a `--read-only` mode, and it refuses to run migrations against a
|
|
167
|
+
production project. See [MCP Server](/ai/mcp).
|
|
168
|
+
|
|
169
|
+
### Deny-by-default authorization
|
|
170
|
+
|
|
171
|
+
A route without `@Authorized` is public, so forgetting it on one handler leaves
|
|
172
|
+
that endpoint open. You can now protect every route by default and mark the
|
|
173
|
+
open ones with `@Public()`:
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
app.useAuthorization(JwtAuthorization, { default: 'authenticated' });
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
It's off unless you set `default`, so existing apps behave as before.
|
|
180
|
+
`megh route:list` shows each route's protection in a new `AUTH` column. See
|
|
181
|
+
[Deny by default](/core-concept/authentication#deny-by-default).
|
|
182
|
+
|
|
183
|
+
### Request context
|
|
184
|
+
|
|
185
|
+
`requestContext` holds values for the current request, so code deep in a
|
|
186
|
+
service can read the current user or tenant without passing it through every
|
|
187
|
+
call:
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
import { requestContext } from '@meghjs/core';
|
|
191
|
+
|
|
192
|
+
const user = requestContext.getUser<User>();
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Authentication sets `requestContext.user`. `requestContext.run(fn, init)`
|
|
196
|
+
gives workers, scripts and tests a context of their own. See
|
|
197
|
+
[Request Context](/core-concept/request-context).
|
|
198
|
+
|
|
199
|
+
### CLI
|
|
200
|
+
|
|
201
|
+
- **`megh new <name> --mvc`** creates a server-rendered app: `useViews()` and
|
|
202
|
+
`useMethodOverride()` in `src/app.ts`, a layout, a home page, and a
|
|
203
|
+
controller that renders it. See [CLI: Application](/cli/basic#application).
|
|
204
|
+
- **`megh make:view <name>`** (`m:v`) writes `views/<name>.megh.html`. Pages
|
|
205
|
+
extend `layouts.app` when it exists; `--layout` picks another layout,
|
|
206
|
+
`--no-layout` writes a standalone page, and `-c` writes an `<x-name>`
|
|
207
|
+
component. See [Generators: View](/cli/generators#view).
|
|
208
|
+
- **A new logo** for `megh --info`, and `megh -i` as its short form.
|
|
209
|
+
|
|
210
|
+
## Fixes
|
|
211
|
+
|
|
212
|
+
- **Rate limiting warns when `trustProxy: true`.** With it, the client controls
|
|
213
|
+
`X-Forwarded-For` and can get a fresh counter on every request. Use the
|
|
214
|
+
number of proxy hops or the proxy's address instead. See
|
|
215
|
+
[Terminate HTTPS at a proxy](/production/security#terminate-https-at-a-proxy).
|
|
216
|
+
- `rateLimitIpKey()` and `MemoryRateLimitStoreOptions` are exported.
|
|
217
|
+
- `setGlobalPrefix(prefix, { exclude })` matches inline routes whose path has
|
|
218
|
+
no leading slash.
|
|
219
|
+
- In-memory queued events run in the request context they were dispatched in.
|
|
220
|
+
They used to all run in the context of the first one.
|
|
221
|
+
|
|
222
|
+
## Coming from older versions
|
|
223
|
+
|
|
224
|
+
On 0.5.x or earlier, read [Upgrading to 0.6](/getting-started/upgrading-0.6)
|
|
225
|
+
first.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Moving from Avleon to Megh
|
|
3
|
+
description: Avleon is now Megh. How to move an Avleon project to the @meghjs packages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Moving from Avleon to Megh
|
|
7
|
+
|
|
8
|
+
Avleon has been renamed to **Megh** (মেঘ, Bengali for "cloud"). The framework
|
|
9
|
+
is the same: only the names change. The `@avleon/*` packages are deprecated
|
|
10
|
+
and get no new releases; new versions are published as `@meghjs/*`.
|
|
11
|
+
|
|
12
|
+
The rename shipped in **0.5.0**: Avleon 0.4.1 is the last `@avleon/*` release,
|
|
13
|
+
and `@meghjs/*` starts at 0.5.0 with the same features.
|
|
14
|
+
|
|
15
|
+
| Before | After |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `@avleon/core` | `@meghjs/core` |
|
|
18
|
+
| `@avleon/cli` | `@meghjs/cli` |
|
|
19
|
+
| `@avleon/data` | `@meghjs/data` |
|
|
20
|
+
| github.com/avleonjs/avleon | [github.com/meghjs/megh](https://github.com/meghjs/megh) |
|
|
21
|
+
| avleonjs.github.io | [meghjs.github.io](https://meghjs.github.io) |
|
|
22
|
+
|
|
23
|
+
If you are on 0.3 or earlier, upgrade to Avleon 0.4 first
|
|
24
|
+
([Upgrading to 0.4](/getting-started/upgrading-0.4)), then follow this page.
|
|
25
|
+
|
|
26
|
+
## 1. Swap the packages
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm uninstall @avleon/core @avleon/cli @avleon/data
|
|
30
|
+
npm i @meghjs/core
|
|
31
|
+
npm i -D @meghjs/cli
|
|
32
|
+
npm i @meghjs/data # only if you used @avleon/data
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 2. Rename the imports and APIs
|
|
36
|
+
|
|
37
|
+
Every export that started with `Avleon` now starts with `Megh`, and every
|
|
38
|
+
`AVLEON_` constant starts with `MEGH_`:
|
|
39
|
+
|
|
40
|
+
| Before | After |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `Avleon.createApplication()` | `Megh.createApplication()` |
|
|
43
|
+
| `AvleonApplication`, `AvleonContainer`, `AvleonConfig`, `AvleonTest`, ... | `MeghApplication`, `MeghContainer`, `MeghConfig`, `MeghTest`, ... |
|
|
44
|
+
| `@AvleonWorker`, `AvleonEvent`, `AvleonRepository`, ... | `@MeghWorker`, `MeghEvent`, `MeghRepository`, ... |
|
|
45
|
+
| `AVLEON_KNEX_DB` | `MEGH_KNEX_DB` |
|
|
46
|
+
|
|
47
|
+
On macOS or Linux, this rewrites a typical project in one pass. Commit first,
|
|
48
|
+
then review the diff:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
grep -rlE 'avleon|Avleon|AVLEON' src test package.json tsconfig.json *.d.ts 2>/dev/null \
|
|
52
|
+
| xargs sed -i.bak -e 's#@avleon/#@meghjs/#g' -e 's/AVLEON/MEGH/g' \
|
|
53
|
+
-e 's/Avleon/Megh/g' -e 's/avleon/megh/g'
|
|
54
|
+
find . -name '*.bak' -not -path './node_modules/*' -delete
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## 3. The CLI command is `megh`
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
npx megh serve # was: npx avleon serve
|
|
61
|
+
npx megh make:controller users
|
|
62
|
+
npx megh migrate
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Update the `scripts` in `package.json` (`avleon serve` → `megh serve`, and so on).
|
|
66
|
+
|
|
67
|
+
## 4. Configuration and generated files
|
|
68
|
+
|
|
69
|
+
| Before | After |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `"avleon": { "entry", "database", "migrations" }` in `package.json` | `"megh": { ... }` |
|
|
72
|
+
| `avleon-env.d.ts` | `megh-env.d.ts`, with `@meghjs/data` in place of `@avleon/data`. Rename the file and update `tsconfig.json`'s `include`. |
|
|
73
|
+
| `AVLEON_QUEUE_DRIVER` env variable | `MEGH_QUEUE_DRIVER` |
|
|
74
|
+
| `AVLEON_SKIP_INSTALL` env variable | `MEGH_SKIP_INSTALL` |
|
|
75
|
+
|
|
76
|
+
## 5. For plugin authors
|
|
77
|
+
|
|
78
|
+
Plugins declare their entry under a `megh` key in `package.json`:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{ "megh": { "plugin": "./dist/plugin.js" } }
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Packages that still use the `avleon` key are not discovered. Rename the key
|
|
85
|
+
and import `MeghPlugin` from `@meghjs/core`.
|
|
86
|
+
|
|
87
|
+
## 6. OpenAPI
|
|
88
|
+
|
|
89
|
+
Request body metadata in the generated spec uses the `x-megh-request-body`
|
|
90
|
+
extension instead of `x-avleon-request-body`. This only matters if you
|
|
91
|
+
post-process the spec and look for that key.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upcoming changes
|
|
3
|
+
description: Changes on main since 0.7.0 that can affect existing apps. This page becomes the upgrade guide for the next release.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upcoming changes
|
|
7
|
+
|
|
8
|
+
Nothing on `main` since 0.7.0 changes how existing apps behave yet. Changes
|
|
9
|
+
for the next release are listed here as they land.
|
|
10
|
+
|
|
11
|
+
The changes that were on this page shipped in 0.7.0. See
|
|
12
|
+
[Upgrading to 0.7](/getting-started/upgrading-0.7).
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upgrading to 0.3
|
|
3
|
+
description: Breaking changes from 0.2 and known issues in 0.3.0.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upgrading to 0.3
|
|
7
|
+
|
|
8
|
+
::: info Avleon is now Megh
|
|
9
|
+
This guide predates the rename and uses the old `@avleon/*` names. After
|
|
10
|
+
upgrading, follow [Moving from Avleon to Megh](/getting-started/upgrading-megh).
|
|
11
|
+
:::
|
|
12
|
+
|
|
13
|
+
`@avleon/core` 0.3 closes several security holes and unifies APIs that were
|
|
14
|
+
inconsistent in 0.2. Most apps need a few changes, listed below.
|
|
15
|
+
|
|
16
|
+
## 1. Install the peer dependencies you use
|
|
17
|
+
|
|
18
|
+
Integrations moved from `dependencies` to optional peer dependencies. Install
|
|
19
|
+
`class-validator` and `class-transformer` in every project, plus whichever of
|
|
20
|
+
these you use:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npm i @fastify/cors # useCors
|
|
24
|
+
npm i @fastify/multipart # useMultipart, @UploadFile
|
|
25
|
+
npm i @fastify/static # useStaticFiles
|
|
26
|
+
npm i @fastify/swagger @fastify/swagger-ui # useOpenApi (Swagger UI)
|
|
27
|
+
npm i @fastify/swagger @scalar/fastify-api-reference # useOpenApi (Scalar)
|
|
28
|
+
npm i socket.io fastify-socket.io # useSocketIo
|
|
29
|
+
npm i -D pino-pretty # pretty dev logs
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The package is CommonJS only, with an `exports` map. Imports from
|
|
33
|
+
`@avleon/core/dist/...` no longer resolve; import from `@avleon/core`. The license
|
|
34
|
+
is now MIT.
|
|
35
|
+
|
|
36
|
+
## 2. Set `NODE_ENV=development` locally
|
|
37
|
+
|
|
38
|
+
`app.isDevelopment()` is now true only when `NODE_ENV=development`. An unset
|
|
39
|
+
`NODE_ENV` counts as production, which:
|
|
40
|
+
|
|
41
|
+
- turns off anything behind `if (app.isDevelopment())`, such as OpenAPI docs,
|
|
42
|
+
- hides the message and data of 5xx errors,
|
|
43
|
+
- switches logs to JSON.
|
|
44
|
+
|
|
45
|
+
## 3. Authorization denies by default
|
|
46
|
+
|
|
47
|
+
- A route with `@Authorized` returns **403** if no authorizer is registered.
|
|
48
|
+
- An authorizer that returns `false` now denies with 403. Throwing still works.
|
|
49
|
+
- `AuthorizeMiddleware`, `AppAuthorization`, `AuthHandler` and
|
|
50
|
+
`AuthReturnTypes` were removed. Write a plain class with an `authorize()`
|
|
51
|
+
method:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
// before
|
|
55
|
+
@CanAuthorize
|
|
56
|
+
class JwtAuthorization extends AuthorizeMiddleware { ... }
|
|
57
|
+
|
|
58
|
+
// after
|
|
59
|
+
@CanAuthorize
|
|
60
|
+
class JwtAuthorization {
|
|
61
|
+
async authorize(req: IRequest, options?: { roles?: string[] }) {
|
|
62
|
+
if (!req.user) return false;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
See [Authentication](/core-concept/authentication).
|
|
68
|
+
|
|
69
|
+
## 4. Validation is stricter
|
|
70
|
+
|
|
71
|
+
- Properties not declared on a `@Body()`/`@Query()` DTO are rejected with 400.
|
|
72
|
+
- The handler receives the DTO instance, not the plain object.
|
|
73
|
+
- The 400 response body changed:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
// before
|
|
77
|
+
{ "code": 400, "error": "ValidationError", "errors": [ ... ] }
|
|
78
|
+
|
|
79
|
+
// after
|
|
80
|
+
{ "code": 400, "status": "Error", "message": "msg1; msg2", "errors": [ ... ] }
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## 5. One pagination shape
|
|
84
|
+
|
|
85
|
+
Every paginator now takes `{ page, perPage }` and returns
|
|
86
|
+
`{ data, meta: { total, page, perPage, lastPage, next, prev } }`. The old shapes
|
|
87
|
+
(`{ total, totalPage, next, data }` and `{ data, total, page, limit, totalPages, hasNext, hasPrev }`)
|
|
88
|
+
are gone. `take`, `skip` and `limit` are still accepted but deprecated. See
|
|
89
|
+
[Pagination](/advanced/database#pagination).
|
|
90
|
+
|
|
91
|
+
## 6. File storage is safe by default
|
|
92
|
+
|
|
93
|
+
- Saved files get random UUID names. Use `saveAs` (formerly `as`) or
|
|
94
|
+
`preserveFilename: true` to choose the name.
|
|
95
|
+
- `overwrite` defaults to `false`.
|
|
96
|
+
- An extension allowlist and a 50 MB size limit apply.
|
|
97
|
+
- `download`, `downloadAs` and `getUploadFile` resolve paths relative to the
|
|
98
|
+
storage `baseDir` and reject anything outside it.
|
|
99
|
+
- `save` returns `{ filename, originalFilename, size, uploadPath, staticPath }`.
|
|
100
|
+
- `UploadFileFromRequest`'s `dest` is now a directory path string.
|
|
101
|
+
|
|
102
|
+
See [File Uploads](/advanced/file-uploads).
|
|
103
|
+
|
|
104
|
+
## 7. Events, queues and cache
|
|
105
|
+
|
|
106
|
+
- `EventDispatcher.dispatch` takes an `AvleonEvent` instance, not a string.
|
|
107
|
+
- Kafka and RabbitMQ broadcast throw "not implemented". Socket broadcast
|
|
108
|
+
requires `app.useSocketIo()`.
|
|
109
|
+
- `EventRegistry.getListeners` takes a class or event, and `flushOnce` was
|
|
110
|
+
removed.
|
|
111
|
+
- `@AvleonWorker` no longer starts on import. Register workers with
|
|
112
|
+
`app.useWorker([...])`.
|
|
113
|
+
- The in-memory cache enforces TTLs, and each `new CacheManager()` has its own
|
|
114
|
+
store.
|
|
115
|
+
|
|
116
|
+
## 8. Removed exports
|
|
117
|
+
|
|
118
|
+
`registerKnex`, `FEATURE_KEY`, `uuid`, `getLineNumber`, `MatchLocation`,
|
|
119
|
+
`extrctParamFromUrl`, `findDuplicates`, `isClassValidator`, `validateRequestBody`,
|
|
120
|
+
`OkOptions`, `Results.code`, `KafkaBroadcastOption`, `RabbitMqBroadcastOption`,
|
|
121
|
+
and the `ControllerOptions` fields `version`, `since` and `meta`.
|
|
122
|
+
|
|
123
|
+
`Results.Ok(x)` now serializes as `{ headers, data, statusCode }`.
|
|
124
|
+
|
|
125
|
+
## Known issues in 0.3.0
|
|
126
|
+
|
|
127
|
+
These are expected to be fixed in a patch release:
|
|
128
|
+
|
|
129
|
+
| Issue | Workaround |
|
|
130
|
+
|-------|------------|
|
|
131
|
+
| `@UseMiddleware(SomeClass)` crashes `app.run()` | Fixed in 0.5.2. On older versions, pass an instance: `@UseMiddleware(new SomeClass())` |
|
|
132
|
+
| `@Repository` and `@Queue` classes without a constructor break under DI | Add `constructor() { super(); }` |
|
|
133
|
+
| `Results.Created`/`NoContent`/`NotFound`, `HttpResponse.Created` and `@HttpCode` respond with 200 | Fixed in 0.5.5. On older versions, throw `HttpExceptions` for error statuses |
|
|
134
|
+
| `@Body()`/`@Query()` DTOs are missing from the OpenAPI document | Describe them with `@OpenApi({ requestBody, query })` |
|
|
135
|
+
| `@All()` crashes `app.run()` | Fixed in 0.5.5. On older versions, register each method separately |
|
|
136
|
+
| Upload policy violations return 500 instead of 400/413 | None |
|
|
137
|
+
| `app.run()` has no `host` option and binds to localhost | Fixed in 0.5.5: `app.run(port, { host })`, defaulting to `HOST` or `0.0.0.0` |
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Quick Start
|
|
3
|
+
description: Writing your first routes, with a controller or inline, returning responses and running the app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Quick Start
|
|
7
|
+
|
|
8
|
+
There are two ways to design your application: `Controller based` and
|
|
9
|
+
`Route method based`. They can be mixed in the same app.
|
|
10
|
+
|
|
11
|
+
## Using a controller
|
|
12
|
+
|
|
13
|
+
Controllers group related routes and can take dependencies through the
|
|
14
|
+
constructor. This is the approach the CLI scaffolds.
|
|
15
|
+
|
|
16
|
+
::: code-group
|
|
17
|
+
```ts [app.ts]
|
|
18
|
+
import { Megh } from '@meghjs/core';
|
|
19
|
+
import { WelcomeController } from './controllers/welcome.controller';
|
|
20
|
+
|
|
21
|
+
const app = Megh.createApplication();
|
|
22
|
+
app.useControllers([ WelcomeController ]);
|
|
23
|
+
|
|
24
|
+
app.run();
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```ts [controllers/welcome.controller.ts]
|
|
28
|
+
import { ApiController, Get } from '@meghjs/core';
|
|
29
|
+
|
|
30
|
+
@ApiController
|
|
31
|
+
export class WelcomeController {
|
|
32
|
+
|
|
33
|
+
@Get()
|
|
34
|
+
sayHello(){
|
|
35
|
+
return 'Hello world!.';
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
:::
|
|
40
|
+
|
|
41
|
+
See [Controller](/core-concept/controller) for parameters, REST resources and
|
|
42
|
+
error handling.
|
|
43
|
+
|
|
44
|
+
## Using inline routes
|
|
45
|
+
|
|
46
|
+
For small apps, register handlers directly on the app with `mapGet`, `mapPost`,
|
|
47
|
+
`mapPut`, `mapPatch` and `mapDelete`:
|
|
48
|
+
|
|
49
|
+
::: code-group
|
|
50
|
+
```ts [app.ts]
|
|
51
|
+
import { Megh } from '@meghjs/core';
|
|
52
|
+
|
|
53
|
+
const app = Megh.createApplication();
|
|
54
|
+
|
|
55
|
+
app.mapGet('/', () => 'Welcome to Megh.');
|
|
56
|
+
|
|
57
|
+
app.run(); // PORT from the environment, else :4000
|
|
58
|
+
```
|
|
59
|
+
:::
|
|
60
|
+
|
|
61
|
+
Handlers receive the request and response, and returning an object sends JSON:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
app.mapGet('/users/:id', (req) => ({ id: req.params.id }));
|
|
65
|
+
|
|
66
|
+
app.mapPost('/users', (req) => {
|
|
67
|
+
return { created: req.body };
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Inline routes return a chainable object for middleware, authorization and
|
|
72
|
+
OpenAPI metadata:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
app.mapGet('/secret', handler)
|
|
76
|
+
.useMiddleware([ApiKeyMiddleware]) // classes (resolved through DI) or instances
|
|
77
|
+
.authorized() // like @Authorized(); .authorized('jwt') picks a handler
|
|
78
|
+
.useOpenApi({ tags: ['internal'] });
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
They run the same pipeline as controller routes: middleware, then the
|
|
82
|
+
authentication handler (`request.user`), then `.authorized()`. Return
|
|
83
|
+
`Results.*` to set the status code; thrown errors go through the
|
|
84
|
+
[error handler](/core-concept/error-handling).
|
|
85
|
+
|
|
86
|
+
## Returning responses
|
|
87
|
+
|
|
88
|
+
Returning an object or array sends JSON; returning a string sends it as-is.
|
|
89
|
+
|
|
90
|
+
Set the status code with `@HttpCode`, or return a result that carries one:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { Post, Get, HttpCode, Results, HttpResponse } from '@meghjs/core';
|
|
94
|
+
|
|
95
|
+
@Post('/')
|
|
96
|
+
@HttpCode(201)
|
|
97
|
+
create(@Body() dto: CreateUserDto) {
|
|
98
|
+
return this.users.create(dto); // 201 with the user as JSON
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
@Get('/:id')
|
|
102
|
+
async findOne(@Param('id') id: number) {
|
|
103
|
+
const user = await this.users.find(id);
|
|
104
|
+
return user ? Results.Ok(user) // 200 { data: user }
|
|
105
|
+
: Results.NotFound('nope'); // 404 { code, status, message }
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
| Result | Status | Body |
|
|
110
|
+
|--------|--------|------|
|
|
111
|
+
| `Results.Ok(x)` | 200 | `{ data: x }` |
|
|
112
|
+
| `Results.Created(x)` | 201 | `{ data: x }` |
|
|
113
|
+
| `Results.NoContent()` | 204 | empty |
|
|
114
|
+
| `Results.NotFound(msg)` | 404 | `{ code, status, message }` |
|
|
115
|
+
| `Results.OkStream(stream, { contentType, filename })` | 200 | the stream |
|
|
116
|
+
| `HttpResponse.Created(x)` | 201 | `{ message, data }` |
|
|
117
|
+
| `HttpResponse.NoContent()` | 204 | empty |
|
|
118
|
+
| `Results.Redirect(url, status?)` | 302 (or 301, 303, 307, 308) | empty, `Location: url` |
|
|
119
|
+
|
|
120
|
+
A returned result's status wins over `@HttpCode`.
|
|
121
|
+
|
|
122
|
+
### Redirects and headers
|
|
123
|
+
|
|
124
|
+
`@Redirect(url, status?)` redirects instead of sending the return value. The
|
|
125
|
+
handler can pick another target by returning `{ url, statusCode }`:
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
import { Get, Redirect, ResponseHeader, Results } from '@meghjs/core';
|
|
129
|
+
|
|
130
|
+
@Get('/docs')
|
|
131
|
+
@Redirect('https://docs.example.com', 301)
|
|
132
|
+
docs() {}
|
|
133
|
+
|
|
134
|
+
@Get('/latest')
|
|
135
|
+
@Redirect('/releases')
|
|
136
|
+
latest() {
|
|
137
|
+
return { url: `/releases/${this.releases.latestId()}` }; // 302 there
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
@Get('/me')
|
|
141
|
+
me(@AuthUser() user?: User) {
|
|
142
|
+
return user ?? Results.Redirect('/login');
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`@ResponseHeader(name, value)` sets a header on every response from the
|
|
147
|
+
route. Stack it for several; a header a returned `Results.*` sets wins:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
@Get('/report')
|
|
151
|
+
@ResponseHeader('Cache-Control', 'no-store')
|
|
152
|
+
report() { ... }
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`@Header()` is the parameter decorator that reads a *request* header.
|
|
156
|
+
|
|
157
|
+
To send an error status, throw an HTTP exception:
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import { HttpExceptions } from '@meghjs/core';
|
|
161
|
+
|
|
162
|
+
throw HttpExceptions.notFound('User not found');
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Error responses have the shape `{ code, status: "Error", message, data? }`.
|
|
166
|
+
Outside development, 5xx responses hide the message and data. See
|
|
167
|
+
[Error Handling](/core-concept/error-handling).
|
|
168
|
+
|
|
169
|
+
Inline routes don't validate DTOs; use a controller when you need that.
|
|
170
|
+
|
|
171
|
+
## Running the app
|
|
172
|
+
|
|
173
|
+
`run` takes an optional port. Without one it uses the `PORT` environment
|
|
174
|
+
variable, else `4000`:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
app.run(); // PORT, else :4000
|
|
178
|
+
app.run(3000); // :3000
|
|
179
|
+
app.run(3000, { host: '127.0.0.1' });
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Set `NODE_ENV=development` locally to get detailed errors and pretty logs. An
|
|
183
|
+
unset `NODE_ENV` counts as production.
|
|
184
|
+
|
|
185
|
+
See [Application](/getting-started/application) for the app options, the
|
|
186
|
+
`use*` methods, what `run()` does, lifecycle hooks and shutdown.
|
|
187
|
+
|
|
188
|
+
## Next steps
|
|
189
|
+
|
|
190
|
+
- [Application](/getting-started/application) — options, lifecycle and shutdown
|
|
191
|
+
- [Controller](/core-concept/controller) — routes, parameters, REST resources
|
|
192
|
+
- [Middleware](/core-concept/middleware) — request pipeline
|
|
193
|
+
- [MeghORM](/advanced/orm) — models, queries, relations and migrations
|
|
194
|
+
- [OpenAPI](/microservices/openapi) — API documentation
|