@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.
Files changed (84) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +141 -2
  3. package/dist/bin.d.ts +2 -0
  4. package/dist/bin.js +37 -0
  5. package/dist/docs/advanced/caching.md +72 -0
  6. package/dist/docs/advanced/database.md +328 -0
  7. package/dist/docs/advanced/events.md +169 -0
  8. package/dist/docs/advanced/file-uploads.md +141 -0
  9. package/dist/docs/advanced/health.md +81 -0
  10. package/dist/docs/advanced/logging.md +96 -0
  11. package/dist/docs/advanced/mail.md +439 -0
  12. package/dist/docs/advanced/orm/migrations.md +210 -0
  13. package/dist/docs/advanced/orm/models.md +291 -0
  14. package/dist/docs/advanced/orm/queries.md +169 -0
  15. package/dist/docs/advanced/orm/query-builder.md +120 -0
  16. package/dist/docs/advanced/orm/relations.md +179 -0
  17. package/dist/docs/advanced/orm/seeding.md +129 -0
  18. package/dist/docs/advanced/orm.md +145 -0
  19. package/dist/docs/advanced/plugins.md +90 -0
  20. package/dist/docs/advanced/queue.md +217 -0
  21. package/dist/docs/advanced/scheduler.md +253 -0
  22. package/dist/docs/advanced/testing.md +257 -0
  23. package/dist/docs/advanced/views.md +335 -0
  24. package/dist/docs/ai/mcp.md +162 -0
  25. package/dist/docs/cli/basic.md +133 -0
  26. package/dist/docs/cli/database.md +112 -0
  27. package/dist/docs/cli/generators.md +605 -0
  28. package/dist/docs/cli/scaffold/auth.md +172 -0
  29. package/dist/docs/cli/scaffold/domains.md +224 -0
  30. package/dist/docs/cli/scaffold/index.md +77 -0
  31. package/dist/docs/cli/scaffold/rbac.md +118 -0
  32. package/dist/docs/cli/scaffold/templates.md +235 -0
  33. package/dist/docs/core-concept/authentication.md +162 -0
  34. package/dist/docs/core-concept/configuration.md +268 -0
  35. package/dist/docs/core-concept/controller.md +350 -0
  36. package/dist/docs/core-concept/dependency-injection.md +213 -0
  37. package/dist/docs/core-concept/error-handling.md +185 -0
  38. package/dist/docs/core-concept/middleware.md +143 -0
  39. package/dist/docs/core-concept/request-context.md +110 -0
  40. package/dist/docs/core-concept/validation.md +355 -0
  41. package/dist/docs/getting-started/application.md +233 -0
  42. package/dist/docs/getting-started/installation.md +166 -0
  43. package/dist/docs/getting-started/introduction.md +136 -0
  44. package/dist/docs/getting-started/upgrading-0.4.md +125 -0
  45. package/dist/docs/getting-started/upgrading-0.5.md +293 -0
  46. package/dist/docs/getting-started/upgrading-0.6.md +251 -0
  47. package/dist/docs/getting-started/upgrading-0.7.md +225 -0
  48. package/dist/docs/getting-started/upgrading-megh.md +91 -0
  49. package/dist/docs/getting-started/upgrading-next.md +12 -0
  50. package/dist/docs/getting-started/upgrading.md +137 -0
  51. package/dist/docs/getting-started/usage.md +194 -0
  52. package/dist/docs/index.md +58 -0
  53. package/dist/docs/microservices/openapi.md +387 -0
  54. package/dist/docs/microservices/websocket.md +165 -0
  55. package/dist/docs/production/deployment.md +256 -0
  56. package/dist/docs/production/security.md +307 -0
  57. package/dist/docs/reference/api.md +999 -0
  58. package/dist/docs/reference/faq.md +227 -0
  59. package/dist/docs/reference/versioning.md +105 -0
  60. package/dist/docs.d.ts +30 -0
  61. package/dist/docs.js +126 -0
  62. package/dist/index.d.ts +10 -0
  63. package/dist/index.js +22 -0
  64. package/dist/megh.d.ts +59 -0
  65. package/dist/megh.js +207 -0
  66. package/dist/prompts.d.ts +3 -0
  67. package/dist/prompts.js +47 -0
  68. package/dist/result.d.ts +18 -0
  69. package/dist/result.js +48 -0
  70. package/dist/server.d.ts +17 -0
  71. package/dist/server.js +40 -0
  72. package/dist/tools/context.d.ts +11 -0
  73. package/dist/tools/context.js +2 -0
  74. package/dist/tools/database.d.ts +8 -0
  75. package/dist/tools/database.js +58 -0
  76. package/dist/tools/docs.d.ts +3 -0
  77. package/dist/tools/docs.js +63 -0
  78. package/dist/tools/generate.d.ts +10 -0
  79. package/dist/tools/generate.js +177 -0
  80. package/dist/tools/project.d.ts +3 -0
  81. package/dist/tools/project.js +84 -0
  82. package/dist/version.d.ts +2 -0
  83. package/dist/version.js +10 -0
  84. 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