@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,293 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upgrading to 0.5.5
|
|
3
|
+
description: "What changes in Megh 0.5.1 to 0.5.5: Megh's own validation decorators, exception filters, health checks and request IDs, one pipeline order, scaffolding from templates, auth and RBAC, seeders and factories, typed OpenAPI responses, SQL Server fixes, useMeghORM and Megh's own DI container."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upgrading to 0.5.5
|
|
7
|
+
|
|
8
|
+
0.5.1 to 0.5.4 need no code changes: apps written for 0.5.0 keep working.
|
|
9
|
+
0.5.1 brings Megh's own ORM setup and DI container, and deprecates
|
|
10
|
+
`app.useDatabase()`. 0.5.2 is a bug-fix release. 0.5.3 adds seeders,
|
|
11
|
+
factories and documented responses, and fixes the ORM on SQL Server. 0.5.4
|
|
12
|
+
adds scaffolding to the CLI and documents `@Query()` parameters.
|
|
13
|
+
|
|
14
|
+
0.5.5 adds Megh's own validation decorators, exception filters, health
|
|
15
|
+
checks and request IDs, and fixes a batch of runtime bugs. Most apps need no
|
|
16
|
+
code changes, but read [Breaking in 0.5.5](#breaking-in-0-5-5) first: the
|
|
17
|
+
middleware order changed, and some routes now send the status they declare.
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm i @meghjs/core@^0.5.5
|
|
21
|
+
npm i -D @meghjs/cli@^0.5.5
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Breaking in 0.5.5
|
|
25
|
+
|
|
26
|
+
- **`@UseMiddleware` runs before authentication.** The pipeline is now
|
|
27
|
+
middleware → authentication → `@Authorized` → validation → handler, for
|
|
28
|
+
global, controller and route middleware alike. Before, `@UseMiddleware`
|
|
29
|
+
ran after `@Authorized` and could read `request.user`. Move logic that
|
|
30
|
+
needs the user into the authorization handler or the route, or read the
|
|
31
|
+
user in a later middleware of your own. See
|
|
32
|
+
[Pipeline order](/core-concept/middleware#pipeline-order).
|
|
33
|
+
- **`app.run()` listens on `0.0.0.0` by default** instead of localhost, so
|
|
34
|
+
the app is reachable inside containers. Keep local-only with
|
|
35
|
+
`app.run(port, { host: '127.0.0.1' })` or `HOST=127.0.0.1`.
|
|
36
|
+
- **Status codes are honoured.** `@HttpCode`, `Results.Created`,
|
|
37
|
+
`Results.NoContent`, `Results.NotFound` and `HttpResponse.Created` now send
|
|
38
|
+
their status instead of 200. Clients that checked for 200 on these routes
|
|
39
|
+
need updating.
|
|
40
|
+
- **Unknown routes** answer `{ code: 404, status: "Error", message }`
|
|
41
|
+
instead of Fastify's default 404 body.
|
|
42
|
+
- **`MeghTest`** uses the production error handler, so tests see redacted
|
|
43
|
+
5xx responses (`Internal Server Error`) unless `NODE_ENV=development`.
|
|
44
|
+
|
|
45
|
+
## New in 0.5.5
|
|
46
|
+
|
|
47
|
+
- [Validation decorators](/core-concept/validation) in `@meghjs/core`:
|
|
48
|
+
`IsString`, `MinLength`, `ValidateNested`, `Type`, `Transform` and more,
|
|
49
|
+
with class-validator's names, options and messages. Each DTO is compiled
|
|
50
|
+
once, so validating a request is several times faster. Switching a DTO is a
|
|
51
|
+
change of import; class-validator DTOs keep working. Also `validateDto()`.
|
|
52
|
+
- `experimental.compiledValidation` (or `MEGH_COMPILED_VALIDATION=1`)
|
|
53
|
+
speeds up class-validator DTOs with the same results.
|
|
54
|
+
- `validator` is an optional peer dependency, needed only for `@IsUUID`,
|
|
55
|
+
`@IsUrl` and `@IsEmail` with options.
|
|
56
|
+
- [Error handling](/core-concept/error-handling): exception filters,
|
|
57
|
+
`@Catch`, `@UseFilters`, `app.useErrorHandler()`, `app.useErrorLogger()`
|
|
58
|
+
and more HTTP exception classes.
|
|
59
|
+
- Inline routes get `mapPatch`, the authentication handler, and
|
|
60
|
+
`.authorized()`, and they send `Results` with their status.
|
|
61
|
+
- `app.run(port, { host, onListen, shutdownTimeout })`.
|
|
62
|
+
- `MEGH_DOTENV=false` skips loading `.env` on import.
|
|
63
|
+
- [Health checks](/advanced/health): `app.useHealth()` serves `/health` and
|
|
64
|
+
`/ready`; Megh ORM registers a `database` check.
|
|
65
|
+
- [Request IDs](/advanced/logging#request-ids): an `x-request-id` on every
|
|
66
|
+
response, `reqId` on every log line, and `getRequestId()`.
|
|
67
|
+
|
|
68
|
+
## Fixes in 0.5.5
|
|
69
|
+
|
|
70
|
+
- `useScheduler({ path })` no longer crashes `run()`.
|
|
71
|
+
- `@UploadFile` and `@UploadFiles` receive the saved files.
|
|
72
|
+
- `@All()` registers every method instead of crashing.
|
|
73
|
+
- Framework errors keep their status (400 bad JSON, 413, 415, 429).
|
|
74
|
+
- A failing socket listener is logged instead of crashing the process.
|
|
75
|
+
- Two controllers with the same class name no longer share route metadata.
|
|
76
|
+
- Shutdown closes the cache, exits with code 1 on failure, and gives up
|
|
77
|
+
after `shutdownTimeout`.
|
|
78
|
+
- `.env` is parsed once instead of on every `Environment.get()`.
|
|
79
|
+
- Inline route middleware classes are called with `this` bound.
|
|
80
|
+
|
|
81
|
+
## New in 0.5.4
|
|
82
|
+
|
|
83
|
+
- **Tables and models from templates.** `npx megh make:model Product --template ecommerce/product`
|
|
84
|
+
(or `make:resource`) writes the create-table migration and the model (or
|
|
85
|
+
the whole REST resource). Tables its foreign keys point to are created
|
|
86
|
+
too. `--fields "title,price:money,status:in(draft|live)"` describes a
|
|
87
|
+
table on the command line, with presets such as `slug`, `price` and
|
|
88
|
+
`address`. See [Templates and Fields](/cli/scaffold/templates).
|
|
89
|
+
- **Business domains.** `npx megh scaffold:domain ecommerce` (`sc:domain`)
|
|
90
|
+
scaffolds a domain's tables at once. There are 11 domains: common,
|
|
91
|
+
e-commerce, POS, medical, construction, marketing, real estate, HR, CRM,
|
|
92
|
+
education and logistics. Add your own in `.megh/templates/`. See
|
|
93
|
+
[Domains](/cli/scaffold/domains).
|
|
94
|
+
- **Auth.** `npx megh scaffold:auth` (`sc:auth`) adds sign-up and sign-in
|
|
95
|
+
with JWTs, API keys or both, and optionally roles and permissions: the
|
|
96
|
+
tables, password hashing, `AppAuthentication`, `AppAuthorization`, an
|
|
97
|
+
`AuthController` and a roles seeder, registered in `src/app.ts`. See
|
|
98
|
+
[Auth](/cli/scaffold/auth).
|
|
99
|
+
- **RBAC.** `npx megh scaffold:rbac` (`sc:rbac`) adds roles (one or many per
|
|
100
|
+
user) and permissions, checked with `@Authorized({ roles })` and
|
|
101
|
+
`@Authorized({ permissions })`. See [RBAC](/cli/scaffold/rbac).
|
|
102
|
+
- **`megh template:list`** (`templates`) lists the templates.
|
|
103
|
+
- **SQL Server-safe foreign keys.** On SQL Server, scaffolded migrations
|
|
104
|
+
avoid the "may cause cycles or multiple cascade paths" error and write
|
|
105
|
+
`restrict` as `NO ACTION`. See [SQL Server](/cli/scaffold/templates#sql-server).
|
|
106
|
+
|
|
107
|
+
## Fixes in 0.5.4
|
|
108
|
+
|
|
109
|
+
- **`@Query()` parameters are documented.** A `@Query()` DTO and
|
|
110
|
+
`@Query('key')` parameters were missing from the OpenAPI document. Each DTO
|
|
111
|
+
property and each key is now a query parameter, with its type and
|
|
112
|
+
constraints. See [Query parameters](/microservices/openapi#query-parameters).
|
|
113
|
+
|
|
114
|
+
## New in 0.5.3
|
|
115
|
+
|
|
116
|
+
- **Seeders.** `npx megh make:seeder users` writes a seeder, and
|
|
117
|
+
`npx megh db:seed` (or `megh migrate --seed`) runs them in one transaction,
|
|
118
|
+
so a failing seeder saves nothing. See
|
|
119
|
+
[Seeding and Factories](/advanced/orm/seeding).
|
|
120
|
+
- **Factories with Faker.** `defineFactory(User, ({ faker }) => ({ … }))`
|
|
121
|
+
builds rows with fake values, and `npx megh make:factory user` writes one
|
|
122
|
+
from the model's columns. Install Faker to use them:
|
|
123
|
+
`npm i -D @faker-js/faker`. See [Factories](/advanced/orm/seeding#factories).
|
|
124
|
+
- **`megh update:model`.** After an alter-table migration, it brings a model's
|
|
125
|
+
column fields up to date and keeps relations and methods. See
|
|
126
|
+
[Updating a model](/cli/generators#updating-a-model).
|
|
127
|
+
- **Relation fields typed with the model.** Write
|
|
128
|
+
`@BelongsTo(() => Role) role?: Role | null` and `posts?: Post[]` instead of
|
|
129
|
+
`BelongsTo<Role>` and `HasMany<Post>`, which still work. See
|
|
130
|
+
[Relations](/advanced/orm/relations).
|
|
131
|
+
- **Documented responses.** `@ApiResponse(200, User)` documents a response
|
|
132
|
+
with a model or DTO, `Paginated(User)` a page, and Megh adds the `400`,
|
|
133
|
+
`401` and `403` a route can return. `make:resource` writes them. See
|
|
134
|
+
[Responses](/microservices/openapi#responses).
|
|
135
|
+
- **Typed OpenAPI options.** `OpenApiUiOptions` types every option, including
|
|
136
|
+
Swagger UI's settings, and `auth: 'bearer'` marks `@Authorized` routes. See
|
|
137
|
+
[Securing routes](/microservices/openapi#securing-routes).
|
|
138
|
+
|
|
139
|
+
## Fixes in 0.5.3
|
|
140
|
+
|
|
141
|
+
- **Creating rows works on SQL Server.** `create()`, `save()` and
|
|
142
|
+
`insertGetId()` saved the row, then failed with `Validation failed for
|
|
143
|
+
parameter '1'. Invalid number.` They now return the row with
|
|
144
|
+
`OUTPUT inserted.*`.
|
|
145
|
+
- **SQL Server shows the real error.** A failing migration or transaction
|
|
146
|
+
could report `The ROLLBACK TRANSACTION request has no corresponding BEGIN
|
|
147
|
+
TRANSACTION` instead of what went wrong, for example a foreign key to a
|
|
148
|
+
table that doesn't exist.
|
|
149
|
+
- **`dropColumn()` works on SQL Server** for columns with a default.
|
|
150
|
+
- **Optional relation fields are relations.** A field such as
|
|
151
|
+
`role?: BelongsTo<Role>` was treated as a column, so `create()` accepted it
|
|
152
|
+
and `with('role')` didn't type-check.
|
|
153
|
+
- **The route decorators' `openapi` option is read.**
|
|
154
|
+
`@Get('/', { openapi: { … } })` was ignored.
|
|
155
|
+
|
|
156
|
+
## Changes to note in 0.5.3
|
|
157
|
+
|
|
158
|
+
- `make:model` writes the column type on nullable columns
|
|
159
|
+
(`@Column({ nullable: true, type: "string" })`), so OpenAPI can document
|
|
160
|
+
them. Running `update:model` adds it to fields it generated before.
|
|
161
|
+
- Migrations' `table.string("name", 20)` is read as `varchar(20)`, so
|
|
162
|
+
`make:resource` DTOs now get `@MaxLength(20)`.
|
|
163
|
+
- `OpenApiResponse()` is deprecated: it documents a `{ code, status, data }`
|
|
164
|
+
wrapper that Megh doesn't send. Use `@ApiResponse()`.
|
|
165
|
+
- Code that passed a relation to `create()` or `fill()` through an optional
|
|
166
|
+
marker field now fails to compile, as it should.
|
|
167
|
+
|
|
168
|
+
## Fixes in 0.5.2
|
|
169
|
+
|
|
170
|
+
- **`@UseMiddleware(SomeClass)` works.** Passing a middleware class to
|
|
171
|
+
`@UseMiddleware` on a controller or route crashed `app.run()` with
|
|
172
|
+
`Function is not registered`. Classes are now resolved through the DI
|
|
173
|
+
container, so they can use constructor injection. The
|
|
174
|
+
`@UseMiddleware(new SomeClass())` workaround still works. See
|
|
175
|
+
[Middleware](/core-concept/middleware#controller-scoped).
|
|
176
|
+
- **Paging works on SQL Server.** `limit()`, `offset()`, `first()`, `find()`,
|
|
177
|
+
`exists()`, `paginate()`, `simplePaginate()` and `forPage()` failed with
|
|
178
|
+
`Incorrect syntax near 'limit'`. Queries now use `top(n)` and
|
|
179
|
+
`offset … fetch next … rows only` on SQL Server. See
|
|
180
|
+
[Paging on SQL Server](/advanced/orm/queries#paging-on-sql-server).
|
|
181
|
+
|
|
182
|
+
## Changes in 0.5.1
|
|
183
|
+
|
|
184
|
+
### Connect with `useMeghORM()`
|
|
185
|
+
|
|
186
|
+
Megh now creates the database connection itself. Kysely ships with
|
|
187
|
+
`@meghjs/core`, so an app only installs the driver for its database.
|
|
188
|
+
|
|
189
|
+
```ts [src/app.ts]
|
|
190
|
+
// Before (0.5.0)
|
|
191
|
+
import { db } from "./database/connection";
|
|
192
|
+
app.useDatabase(db);
|
|
193
|
+
|
|
194
|
+
// After (0.5.1+)
|
|
195
|
+
app.useMeghORM(); // reads DATABASE_URL, or pass { dialect, host, ... }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
1. Put the connection in `.env`, for example
|
|
199
|
+
`DATABASE_URL=postgres://app:secret@localhost:5432/app`.
|
|
200
|
+
[Connecting](/advanced/orm#connecting) lists every option and variable.
|
|
201
|
+
2. Replace `app.useDatabase(db)` with `app.useMeghORM()`.
|
|
202
|
+
3. Delete `src/database/connection.ts`, and a `"database"` path under `"megh"`
|
|
203
|
+
in `package.json` if you set one. While that file exists, `megh migrate`
|
|
204
|
+
keeps using it; once it's gone, migrations connect from `DATABASE_URL` too.
|
|
205
|
+
4. Uninstall `kysely` unless your own code imports it.
|
|
206
|
+
|
|
207
|
+
`app.useDatabase(db)` still works in 0.5.x and logs a deprecation warning.
|
|
208
|
+
|
|
209
|
+
### Models with decorators
|
|
210
|
+
|
|
211
|
+
Models can describe their table with decorators. Models written with
|
|
212
|
+
`static table` and `hasMany(() => Post)` keep working, so move them over
|
|
213
|
+
when it suits you.
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
@Table("users")
|
|
217
|
+
export class User extends Model {
|
|
218
|
+
@PrimaryKey() @AutoIncrement() id?: number;
|
|
219
|
+
@Column({ unique: true }) email!: string;
|
|
220
|
+
@Column({ name: "display_name" }) displayName!: string;
|
|
221
|
+
@CreatedAt() createdAt?: Date;
|
|
222
|
+
|
|
223
|
+
@HasMany(() => Post) posts!: HasMany<Post>;
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
- Fields marked `?` are optional in `create()`.
|
|
228
|
+
- `@Column({ name })`, or `useMeghORM({ naming: 'snake_case' })`, maps
|
|
229
|
+
camelCase properties to other column names. See
|
|
230
|
+
[Column names](/advanced/orm/models#column-names).
|
|
231
|
+
- `npx megh make:model` now writes decorator models.
|
|
232
|
+
|
|
233
|
+
### Migrations with the schema builder
|
|
234
|
+
|
|
235
|
+
`npx megh make:migration` now writes migrations with Megh's schema builder,
|
|
236
|
+
which picks the right SQL type for each database:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
export default defineMigration({
|
|
240
|
+
async up(schema) {
|
|
241
|
+
await schema.create("users", (table) => {
|
|
242
|
+
table.id();
|
|
243
|
+
table.string("email").unique();
|
|
244
|
+
table.timestamps();
|
|
245
|
+
});
|
|
246
|
+
},
|
|
247
|
+
async down(schema) {
|
|
248
|
+
await schema.dropIfExists("users");
|
|
249
|
+
},
|
|
250
|
+
});
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Existing Kysely migrations (`export async function up(db)`) still run, in
|
|
254
|
+
order with the new ones.
|
|
255
|
+
|
|
256
|
+
### The `DB` query builder
|
|
257
|
+
|
|
258
|
+
For queries that don't need a model:
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
import { DB } from "@meghjs/core";
|
|
262
|
+
|
|
263
|
+
const ids = await DB.table("users").where("active", true).pluck("id");
|
|
264
|
+
await DB.transaction(async () => {
|
|
265
|
+
/* ... */
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
See [Query builder](/advanced/orm/query-builder).
|
|
270
|
+
|
|
271
|
+
### Megh's own DI container
|
|
272
|
+
|
|
273
|
+
`typedi` is no longer a dependency. `MeghContainer`, `@Injectable()`, `Token`
|
|
274
|
+
and `inject()` keep their API, and `inject()` now also works in field
|
|
275
|
+
initializers:
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
@Injectable()
|
|
279
|
+
class UserService {
|
|
280
|
+
private readonly users = inject(UserRepository);
|
|
281
|
+
private readonly mailer = inject(Mailer, { optional: true });
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
If your app imported `typedi` directly, switch to `MeghContainer` or add
|
|
286
|
+
`typedi` to your own dependencies. Missing services and dependency cycles now
|
|
287
|
+
fail with the full constructor chain in the error. See
|
|
288
|
+
[Dependency Injection](/core-concept/dependency-injection).
|
|
289
|
+
|
|
290
|
+
### `megh new`
|
|
291
|
+
|
|
292
|
+
New projects can include the ORM: pick **MeghORM** from the features, or pass
|
|
293
|
+
`--database postgres|mysql|sqlite|mssql`.
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Upgrading to 0.6
|
|
3
|
+
description: "What changes in Megh 0.6: removed no-op APIs, run() reading PORT, framework logs through the logger and a safer scaffolded .env in 0.6.0; mail, security headers and rate limiting in 0.6.1; module-first generators, event, queue and task generators and change review in 0.6.3; generated tests, make:test, make:class, make:model --orm/--typeorm, compression, versioning and env schemas in 0.6.5."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Upgrading to 0.6
|
|
7
|
+
|
|
8
|
+
0.6.0 removes APIs that did nothing, makes `app.run()` read `PORT`, and sends
|
|
9
|
+
framework messages through the logger. Most apps only need to delete a call
|
|
10
|
+
or two. Read [Breaking in 0.6.0](#breaking-in-0-6-0) before upgrading.
|
|
11
|
+
|
|
12
|
+
0.6.1 and 0.6.3 add features and fixes with no breaking changes. See
|
|
13
|
+
[New in 0.6.3](#new-in-0-6-3) and [New in 0.6.1](#new-in-0-6-1). 0.6.2 was
|
|
14
|
+
tagged but never published to npm; its changes ship in 0.6.3.
|
|
15
|
+
|
|
16
|
+
0.6.5 adds features and fixes, and changes some CLI generator flags
|
|
17
|
+
(`make:model` writes a plain class unless you pass `--orm`). Apps don't
|
|
18
|
+
need code changes. See [New in 0.6.5](#new-in-0-6-5).
|
|
19
|
+
|
|
20
|
+
A `0.x` minor release can contain breaking changes; patch releases such as
|
|
21
|
+
0.6.1 don't. See the [versioning policy](/reference/versioning).
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npm i @meghjs/core@^0.6.5
|
|
25
|
+
npm i -D @meghjs/cli@^0.6.5
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## New in 0.6.5
|
|
29
|
+
|
|
30
|
+
There is no 0.6.4: the changes on `main` after 0.6.3 ship in 0.6.5.
|
|
31
|
+
|
|
32
|
+
### Changes to the CLI generators
|
|
33
|
+
|
|
34
|
+
0.6.5 changes what some generator flags mean. Your app's code is not
|
|
35
|
+
affected, only what the `make:*` commands write from now on. Check any
|
|
36
|
+
scripts that run them:
|
|
37
|
+
|
|
38
|
+
- **`make:model` writes a plain class by default.** For a Megh ORM model
|
|
39
|
+
(columns read from its migration), add `--orm`:
|
|
40
|
+
`megh make:model user --orm`. `--template` and `--fields` still build a
|
|
41
|
+
Megh ORM model without it.
|
|
42
|
+
- **`--orm` now means Megh ORM; TypeORM is `--typeorm`.** On `make:model`,
|
|
43
|
+
`make:controller -m` and `make:service -m`, replace `--orm` with
|
|
44
|
+
`--typeorm` where you generate TypeORM entities or repository services.
|
|
45
|
+
With `-m`, Megh ORM stays the default.
|
|
46
|
+
- **A resource can't be built on a plain class.** `make:resource`,
|
|
47
|
+
`make:controller -m` and `make:factory` stop with a message if the model
|
|
48
|
+
file is a plain class; regenerate it with `make:model <name> --orm --force`.
|
|
49
|
+
- **`megh -v` prints the logo, then `Megh v<version>`**, instead of the bare
|
|
50
|
+
version. A script that reads it should match `v(\d+\.\d+\.\d+)` on the
|
|
51
|
+
last line, or use `npm ls @meghjs/cli`. `megh --help` and `megh new` no
|
|
52
|
+
longer print the logo. (0.7.0 changes this again: `megh -v` prints only the
|
|
53
|
+
version. See [Upgrading to 0.7](/getting-started/upgrading-0.7#megh-v-prints-only-the-version).)
|
|
54
|
+
|
|
55
|
+
### New
|
|
56
|
+
|
|
57
|
+
- **Generators write unit tests.** `make:service user` also writes
|
|
58
|
+
`src/services/user.service.spec.ts`, and so do the other generators except
|
|
59
|
+
`make:model` and the database ones. `make:resource` tests every service
|
|
60
|
+
method and route without a database. Pass `--notest` (or `-nt`) to skip
|
|
61
|
+
them. See [CLI: Tests](/cli/generators#tests).
|
|
62
|
+
- **`make:test` (`m:t`)** writes a test for a file you already have:
|
|
63
|
+
`megh make:test user.service`.
|
|
64
|
+
- **`make:class` (`m:cls`)** writes a plain class in `src/classes/`.
|
|
65
|
+
- **`megh --info`** prints the CLI, Node.js and OS versions and the project's
|
|
66
|
+
Megh packages, for bug reports. See [Version and info](/cli/basic#version-and-info).
|
|
67
|
+
- **Compression.** `app.useCompression()`, over `@fastify/compress`. See
|
|
68
|
+
[Compression](/getting-started/application#compression).
|
|
69
|
+
- **Global prefix and versioning.** `app.setGlobalPrefix('api', { exclude })`
|
|
70
|
+
and `app.useVersioning({ type: 'uri' | 'header' })` with `@Version()`. See
|
|
71
|
+
[Global prefix and versioning](/core-concept/controller#global-prefix-and-versioning).
|
|
72
|
+
- **Redirects and response headers.** `@Redirect(url, status)`,
|
|
73
|
+
`Results.Redirect(url, status)` and `@ResponseHeader(name, value)`. See
|
|
74
|
+
[Redirects and headers](/getting-started/usage#redirects-and-headers).
|
|
75
|
+
- **Validated environment and config.** `app.useEnvSchema(EnvDto)` and
|
|
76
|
+
`@AppConfig({ schema })` check values at boot and list every problem in a
|
|
77
|
+
`ConfigValidationError`. See [Validating at boot](/core-concept/configuration#validating-at-boot).
|
|
78
|
+
- **Socket.IO authentication.** The `useAuthentication` handler runs on the
|
|
79
|
+
handshake and sets `socket.data.user`. See
|
|
80
|
+
[WebSocket: Authentication](/microservices/websocket#authentication).
|
|
81
|
+
- **`megh migrate --compiled`** (and `db:seed --compiled`) runs the built
|
|
82
|
+
`.js` migrations, for production images without `src/`. It is picked
|
|
83
|
+
automatically when there is no `src/` folder. See
|
|
84
|
+
[Database Commands](/cli/database).
|
|
85
|
+
|
|
86
|
+
### Fixes
|
|
87
|
+
|
|
88
|
+
- The CLI's generated files load when a name matches a Megh decorator:
|
|
89
|
+
`make:config app` (`AppConfig`) and a `Post`, `Get` or `Query` model in
|
|
90
|
+
`make:resource`.
|
|
91
|
+
- `MeghTest.getController` / `getProvider` stand-ins are no longer written to
|
|
92
|
+
the shared container, and requests wait for the routes to be mapped. See
|
|
93
|
+
[Testing](/advanced/testing#replacing-dependencies).
|
|
94
|
+
- `PartialType`, `PickType` and `OmitType` copy class-validator,
|
|
95
|
+
class-transformer, Megh and OpenAPI metadata.
|
|
96
|
+
- `MEGH_DOTENV=false` stops `Environment` from reading `.env`;
|
|
97
|
+
`GetConfig` passes on errors from `config()` and caches until
|
|
98
|
+
`Environment.reload()`.
|
|
99
|
+
- Controller auto-discovery reads the tsconfig `rootDir`/`outDir`, detects
|
|
100
|
+
tsx and other TypeScript runtimes, and fails on a file it can't import.
|
|
101
|
+
- Scheduler: tasks stop when startup fails, `close()` waits for running jobs,
|
|
102
|
+
and `useScheduler({})` scans `src/tasks`.
|
|
103
|
+
- `useControllers()` adds to earlier lists; a clear boot error for
|
|
104
|
+
`@Body()` / `@Query()` without decorator metadata; Scalar serves the
|
|
105
|
+
generated spec; `FileStorage` confines saves after following symlinks; the
|
|
106
|
+
error logger logs the path without the query string.
|
|
107
|
+
- `megh doctor` requires Node.js 22, like the packages.
|
|
108
|
+
|
|
109
|
+
## New in 0.6.3
|
|
110
|
+
|
|
111
|
+
- **Generators for events, queues and scheduled tasks.** `make:event`,
|
|
112
|
+
`make:listener` (`--event` to type it), `make:queue`, `make:worker` and
|
|
113
|
+
`make:task` (`--cron`, `--interval`). See [Events](/advanced/events),
|
|
114
|
+
[Queue](/advanced/queue) and [Scheduler](/advanced/scheduler).
|
|
115
|
+
- **`make:*` puts the module folder first.** `megh make:model users/user`
|
|
116
|
+
now writes `src/users/models/user.model.ts`, not
|
|
117
|
+
`src/models/users/user.model.ts`. The same goes for controllers, services,
|
|
118
|
+
DTOs, middleware, config and mail. Existing files stay where they are, and
|
|
119
|
+
`make:resource`, `make:factory` and `sync:model` still find models in
|
|
120
|
+
the old place. See [Folders](/cli/generators#folders).
|
|
121
|
+
- **Auto-discovered controllers.** `useControllers({ auto: true })` without
|
|
122
|
+
a `path` now scans every `controllers/` folder under `src/`, so module
|
|
123
|
+
controllers are found. With a `path`, nothing changes.
|
|
124
|
+
- **`megh new` offers OpenAPI, CORS and MeghORM only.** Mail, Scalar UI,
|
|
125
|
+
TypeORM and Knex are no longer set up by `megh new`; asking for them with
|
|
126
|
+
`--features` prints how to add them. Existing projects are not affected.
|
|
127
|
+
See [Mail: Setting it up](/advanced/mail#setting-it-up).
|
|
128
|
+
- **Generated models put each decorator on its own line**, with a blank
|
|
129
|
+
line between columns. `sync:model` still reads models in the one-line
|
|
130
|
+
style, and keeps hand-written fields as they are.
|
|
131
|
+
|
|
132
|
+
- **`update:model` is now `sync:model`** (alias `s:m`). The old name and
|
|
133
|
+
`u:m` still work.
|
|
134
|
+
- **Generators review changes to existing files.** `sync:model` and any
|
|
135
|
+
`make:*` run with `-f` show a diff of each file they would change, the
|
|
136
|
+
files that import it and the lines that use removed or retyped members,
|
|
137
|
+
then ask before writing. Declining puts everything back. Pass `-y` to skip
|
|
138
|
+
the question; scripts and CI aren't asked. See
|
|
139
|
+
[Reviewing changes](/cli/generators#reviewing-changes).
|
|
140
|
+
- **A smaller Megh logo** above `megh --help`.
|
|
141
|
+
|
|
142
|
+
## New in 0.6.1
|
|
143
|
+
|
|
144
|
+
No code changes needed. Everything here is opt-in.
|
|
145
|
+
|
|
146
|
+
- **Mail.** Inject `Mailer` and send `Mailable` classes over SMTP, or over
|
|
147
|
+
SendGrid, Mailgun, Postmark or Resend's HTTP APIs. A failover mailer tries
|
|
148
|
+
each in turn. `queue()` and `later()` send through the queue. Turn it on
|
|
149
|
+
with `app.useMail()`, configured from `MEGH_MAIL_*` in `.env`; options
|
|
150
|
+
passed to `useMail()` override them. See [Mail](/advanced/mail).
|
|
151
|
+
- **Security headers.** `app.useSecurityHeaders()` sends a Content Security
|
|
152
|
+
Policy, HSTS, `X-Frame-Options`, `nosniff` and the other usual headers. It
|
|
153
|
+
is built in, so `@fastify/helmet` is no longer needed. See
|
|
154
|
+
[Security Hardening](/production/security#add-security-headers).
|
|
155
|
+
- **Rate limiting.** `app.useRateLimit()` limits requests per client and
|
|
156
|
+
answers 429. `@RateLimit()` gives a route its own limit, and
|
|
157
|
+
`RedisRateLimitStore` shares counts between replicas. It is built in, so
|
|
158
|
+
`@fastify/rate-limit` is no longer needed. See
|
|
159
|
+
[Security Hardening](/production/security#add-rate-limits).
|
|
160
|
+
- **CLI:**
|
|
161
|
+
- `megh make:mail <Name>` creates a Mailable.
|
|
162
|
+
- `megh new` offers a Mail feature.
|
|
163
|
+
- `megh new` runs `git init` (skip it with `--skip-git` or
|
|
164
|
+
`MEGH_SKIP_GIT=1`).
|
|
165
|
+
- Generated resource services have JSDoc.
|
|
166
|
+
- **Fixes:**
|
|
167
|
+
- `megh new` now installs the OpenAPI packages when you pick OpenAPI or
|
|
168
|
+
Scalar, so the generated app starts.
|
|
169
|
+
- The "No mailer is set" error lists every configured mailer.
|
|
170
|
+
|
|
171
|
+
If you registered `@fastify/helmet` or `@fastify/rate-limit` yourself in an
|
|
172
|
+
`onInit` hook, as the 0.6.0 docs suggested, that keeps working. To switch,
|
|
173
|
+
remove the `app.app.register(...)` calls, uninstall the two packages, and
|
|
174
|
+
call `app.useSecurityHeaders()` and `app.useRateLimit()` instead.
|
|
175
|
+
|
|
176
|
+
## Breaking in 0.6.0
|
|
177
|
+
|
|
178
|
+
### Removed APIs
|
|
179
|
+
|
|
180
|
+
These did nothing, or were a second name for another API. Delete the calls,
|
|
181
|
+
or switch to the replacement:
|
|
182
|
+
|
|
183
|
+
| Removed | Use instead |
|
|
184
|
+
|---------|-------------|
|
|
185
|
+
| `app.useHttps()` | Nothing: it was a no-op. For HTTPS, pass `server: { https: { key, cert } }` to `Megh.createApplication()`, or terminate TLS at a proxy |
|
|
186
|
+
| `app.useSerialization()` | Nothing: it was a no-op |
|
|
187
|
+
| `app.mapFeatures()` | Nothing: it was a no-op |
|
|
188
|
+
| `MeghSocketIo` | Get the server with `MeghContainer.get(SocketIoServer)`. See [WebSocket](/microservices/websocket) |
|
|
189
|
+
| `DuplicateRouteException` | Nothing. Fastify already refuses duplicate routes at startup |
|
|
190
|
+
| `MeghRouter.mapRoute()`, `MeghRouter.registerMiddleware()` | `app.mapGet()` and the other `map*` methods, and `app.useMiddlewares()` |
|
|
191
|
+
| `CreateSwaggerObjectSchema`, `GetObjectSchema` | `generateClassSchema` |
|
|
192
|
+
|
|
193
|
+
Your type checker finds every call that needs changing.
|
|
194
|
+
|
|
195
|
+
### `app.run()` reads `PORT`
|
|
196
|
+
|
|
197
|
+
`app.run()` without a port now listens on the `PORT` environment variable,
|
|
198
|
+
like it already read `HOST`, and falls back to `4000`. A port passed to
|
|
199
|
+
`run()` still wins:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
app.run(); // PORT, else 4000
|
|
203
|
+
app.run(3000); // 3000, whatever PORT says
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
An app that calls `app.run()` without a port and has `PORT` set to something
|
|
207
|
+
else, for example by the hosting platform, now listens on `PORT`. That's
|
|
208
|
+
usually what you want. To keep the old behaviour, pass the port explicitly.
|
|
209
|
+
|
|
210
|
+
An invalid `PORT`, such as `abc`, now stops startup with an error.
|
|
211
|
+
|
|
212
|
+
Apps created by the CLI read `PORT` themselves in `serve.ts` and keep working.
|
|
213
|
+
You can simplify `serve.ts` to `app.run()`.
|
|
214
|
+
|
|
215
|
+
### Framework logs go through the logger
|
|
216
|
+
|
|
217
|
+
Framework messages that went to `console` now go through the
|
|
218
|
+
[logger](/advanced/logging). That includes the startup line
|
|
219
|
+
`Application running on <address>`, and warnings such as a route using
|
|
220
|
+
`@Authorized` with no authorization handler registered. In production they're
|
|
221
|
+
JSON lines like every other log entry.
|
|
222
|
+
|
|
223
|
+
If a test spied on `console.warn` or `console.error` to check one of these
|
|
224
|
+
messages, spy on the logger instead. See [Testing](/advanced/testing).
|
|
225
|
+
|
|
226
|
+
## Other changes
|
|
227
|
+
|
|
228
|
+
- **New projects leave `NODE_ENV` out of `.env`.** `megh serve` already runs
|
|
229
|
+
the app in development and `megh start` in production. The old line turned
|
|
230
|
+
on development mode, with error details in responses, when a project's
|
|
231
|
+
`.env` was deployed and the app started with `node dist/serve.js`. In an
|
|
232
|
+
existing project, remove `NODE_ENV=development` from `.env` if you deploy
|
|
233
|
+
that file. See [Deployment](/production/deployment#environment).
|
|
234
|
+
- **`MeghScheduler` is exported**, for running scheduled tasks in a process
|
|
235
|
+
without the HTTP app. See [Scheduler](/advanced/scheduler).
|
|
236
|
+
- **New docs:** [Application](/getting-started/application),
|
|
237
|
+
[Configuration](/core-concept/configuration),
|
|
238
|
+
[Scheduler](/advanced/scheduler), [Testing](/advanced/testing),
|
|
239
|
+
[Deployment](/production/deployment),
|
|
240
|
+
[Security Hardening](/production/security),
|
|
241
|
+
[API Reference](/reference/api),
|
|
242
|
+
[Versioning Policy](/reference/versioning) and
|
|
243
|
+
[FAQ](/reference/faq).
|
|
244
|
+
- **Doc fixes:** `useStaticFiles` takes `root`, not `path`. `useMultipart`
|
|
245
|
+
limits files to 10 MB unless you pass `limits`, on top of `FileStorage`'s
|
|
246
|
+
50 MB.
|
|
247
|
+
|
|
248
|
+
## Coming from older versions
|
|
249
|
+
|
|
250
|
+
On 0.5.0 to 0.5.4, read [Upgrading to 0.5.5](/getting-started/upgrading-0.5)
|
|
251
|
+
first.
|