@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,166 @@
1
+ ---
2
+ title: Installation
3
+ description: Creating a Megh project with the CLI, or setting one up by hand.
4
+ ---
5
+
6
+ # Installation
7
+
8
+ Megh requires **Node.js 22 or newer**.
9
+
10
+ ## Using the CLI
11
+
12
+ If you already installed @meghjs/cli globally then run the following command:
13
+
14
+ ```sh
15
+ megh new myapi
16
+ ```
17
+
18
+ else you can install using npx:
19
+
20
+ ::: code-group
21
+ ```sh [npm]
22
+ npx @meghjs/cli new myapi
23
+ ```
24
+ ```sh [pnpm]
25
+ pnpm dlx @meghjs/cli new myapi
26
+ ```
27
+ ```sh [yarn]
28
+ yarn dlx @meghjs/cli new myapi
29
+ ```
30
+ :::
31
+
32
+ The CLI asks which package manager to use and which features to include —
33
+ OpenAPI docs, CORS and MeghORM — then scaffolds the project and
34
+ installs its dependencies.
35
+
36
+ ```sh
37
+ cd myapi
38
+ npm run start:dev
39
+ ```
40
+
41
+ The app starts on `http://localhost:4000`, and with OpenAPI enabled the docs are
42
+ served at `/docs`.
43
+
44
+ ### What you get
45
+
46
+ ```
47
+ myapi/
48
+ ├── src/
49
+ │ ├── controllers/ # Route controllers
50
+ │ ├── services/ # Business logic
51
+ │ ├── config/ # App configuration
52
+ │ ├── app.ts # App setup
53
+ │ └── serve.ts # Entry point
54
+ ├── test/
55
+ ├── tsconfig.json
56
+ └── package.json
57
+ ```
58
+
59
+ | Script | Description |
60
+ |--------|-------------|
61
+ | `start:dev` | Start the dev server with hot reload |
62
+ | `build` | Compile TypeScript to JavaScript |
63
+ | `start` | Start the production server |
64
+ | `test` | Run unit tests |
65
+
66
+ ## Manual setup
67
+
68
+ Go to your desired project directory and run the following commands:
69
+
70
+ ::: code-group
71
+ ```sh [Bash]
72
+ mkdir myapi && cd myapi && mkdir src
73
+ ```
74
+ ```powershell [Powershell]
75
+ New-Item -ItemType Directory -Name myapi
76
+ Set-Location myapi
77
+ New-Item -ItemType Directory -Name src
78
+
79
+ ```
80
+ :::
81
+
82
+ ::: code-group
83
+ ```sh [npm]
84
+ npm init -y
85
+ npm i @meghjs/core reflect-metadata class-validator class-transformer
86
+ npm i --save-dev typescript @types/node
87
+ npx tsc --init
88
+ ```
89
+ ```sh [pnpm]
90
+ pnpm init
91
+ pnpm i @meghjs/core reflect-metadata class-validator class-transformer
92
+ pnpm i --save-dev typescript @types/node
93
+ pnpm tsc --init
94
+ ```
95
+ ```sh [yarn]
96
+ yarn init -y
97
+ yarn add @meghjs/core reflect-metadata class-validator class-transformer
98
+ yarn add --dev typescript @types/node
99
+ yarn tsc --init
100
+ ```
101
+ :::
102
+
103
+ Since 0.3, `class-validator` and `class-transformer` are peer dependencies. The
104
+ package loads them at import time, so install them in every project, even if
105
+ your DTOs use Megh's own [validation decorators](/core-concept/validation).
106
+
107
+ Ensure `experimentalDecorators` and `emitDecoratorMetadata` are enabled in
108
+ tsconfig.json — Megh's decorators do not work without them.
109
+
110
+ ```json{3-4}
111
+ {
112
+ "compilerOptions": {
113
+ "experimentalDecorators": true,
114
+ "emitDecoratorMetadata": true
115
+ }
116
+ }
117
+ ```
118
+
119
+ Then add a minimal entry point:
120
+
121
+ ```ts [src/app.ts]
122
+ import { Megh } from '@meghjs/core';
123
+
124
+ const app = Megh.createApplication();
125
+
126
+ app.mapGet('/', () => 'Welcome to Megh.');
127
+
128
+ app.run();
129
+ ```
130
+
131
+ You can still use the CLI's generators and dev server in a manually created
132
+ project by installing it locally:
133
+
134
+ ```sh
135
+ npm i -D @meghjs/cli
136
+ npx megh serve
137
+ ```
138
+
139
+ ## Optional dependencies
140
+
141
+ Install these only for the features you use. Without them the package still
142
+ imports, and you get a clear install hint the moment a feature needs one:
143
+
144
+ | Feature | Package |
145
+ |---------|---------|
146
+ | CORS (`useCors`) | `@fastify/cors` |
147
+ | File uploads (`useMultipart`, `@UploadFile`) | `@fastify/multipart` |
148
+ | Static files (`useStaticFiles`) | `@fastify/static` |
149
+ | OpenAPI with Swagger UI | `@fastify/swagger`, `@fastify/swagger-ui` |
150
+ | OpenAPI with Scalar | `@fastify/swagger`, `@scalar/fastify-api-reference` |
151
+ | `@IsUUID`, `@IsUrl`, `@IsEmail(options)` | `validator` |
152
+ | Models and migrations (`useMeghORM`) | a driver: `pg`, `mysql2`, `better-sqlite3`, or `tedious` + `tarn` |
153
+ | TypeORM (alternative to MeghORM) | `@meghjs/data`, `typeorm` + a driver (`pg`, `mysql2`, `sqlite3`, `better-sqlite3`, `mssql`) |
154
+ | Knex (alternative to MeghORM) | `@meghjs/data`, `knex` + a driver |
155
+ | Queues | `bullmq`, `ioredis` (not needed with the `memory`/`sync` drivers) |
156
+ | Redis cache | `ioredis` |
157
+ | Websockets | `socket.io`, `fastify-socket.io` |
158
+ | `@react` islands in [views](/advanced/views#react) | `@swc/core` |
159
+ | Image transforms | `sharp` |
160
+ | Pretty dev logs | `pino-pretty` (dev dependency) |
161
+
162
+ ## Module format
163
+
164
+ `@meghjs/core` ships a single CommonJS build. ESM projects can still
165
+ `import { ... } from '@meghjs/core'`. Only the package root is exported:
166
+ deep imports such as `@meghjs/core/dist/...` are not supported.
@@ -0,0 +1,136 @@
1
+ ---
2
+ title: Introduction
3
+ description: What Megh is, who it's for, what it includes and how it compares.
4
+ ---
5
+
6
+ # Introduction
7
+
8
+ Megh is a TypeScript-first web framework for building REST APIs on Node.js.
9
+ It runs on [Fastify](https://fastify.dev) and gives you decorators,
10
+ dependency injection, validation, an ORM and OpenAPI docs, with less
11
+ boilerplate than most structured frameworks.
12
+
13
+ ```ts [controllers/user.controller.ts]
14
+ import { ApiController, Get, Post, Param, Body } from '@meghjs/core';
15
+ import { UserService } from '../services/user.service';
16
+ import { CreateUserDto } from '../dtos/create-user.dto';
17
+
18
+ @ApiController('/users')
19
+ export class UserController {
20
+ constructor(private readonly users: UserService) {}
21
+
22
+ @Get('/:id')
23
+ findOne(@Param('id') id: number) {
24
+ return this.users.find(id);
25
+ }
26
+
27
+ @Post('/')
28
+ create(@Body() dto: CreateUserDto) {
29
+ return this.users.create(dto); // dto is already validated
30
+ }
31
+ }
32
+ ```
33
+
34
+ ```ts [app.ts]
35
+ import { Megh } from '@meghjs/core';
36
+ import { UserController } from './controllers/user.controller';
37
+
38
+ const app = Megh.createApplication();
39
+ app.useControllers([UserController]);
40
+ app.run();
41
+ ```
42
+
43
+ The controller gets its service through the constructor, the body is
44
+ validated against `CreateUserDto` before the handler runs, and with
45
+ `app.useOpenApi()` both routes appear in the generated OpenAPI document.
46
+
47
+ ## Who it's for
48
+
49
+ - **TypeScript developers who want structure without ceremony.** Controllers,
50
+ services and DTOs, but no module files or provider arrays to keep in sync.
51
+ - **Developers coming from Laravel, Rails or Django** who miss models,
52
+ migrations, seeders and generators in Node.
53
+ - **Teams building business APIs**, where the CLI can scaffold a working
54
+ domain with auth and roles in minutes.
55
+
56
+ ## What's included
57
+
58
+ **HTTP**
59
+ - Decorator-based [controllers](/core-concept/controller) and inline routes
60
+ - [Middleware](/core-concept/middleware) with one fixed pipeline order
61
+ - [Validation](/core-concept/validation) with class-validator-compatible
62
+ decorators, compiled once per DTO
63
+ - [Authentication](/core-concept/authentication) and deny-by-default
64
+ authorization
65
+ - [Error handling](/core-concept/error-handling) with exception filters
66
+ - [OpenAPI](/microservices/openapi) documents with Swagger UI or Scalar
67
+
68
+ **Application**
69
+ - [Dependency injection](/core-concept/dependency-injection) with Megh's own
70
+ container
71
+ - [Configuration](/core-concept/configuration) from `.env` and typed config
72
+ classes
73
+ - [Lifecycle hooks](/getting-started/application#lifecycle-hooks) and
74
+ graceful shutdown
75
+ - [Health checks](/advanced/health), request IDs and
76
+ [structured logging](/advanced/logging)
77
+
78
+ **Data and background work**
79
+ - [MeghORM](/advanced/orm): typed models, a query builder, migrations,
80
+ seeders and factories
81
+ - Optional [TypeORM and Knex](/advanced/database) integrations through
82
+ `@meghjs/data`
83
+ - [Events](/advanced/events), [queues](/advanced/queue),
84
+ [scheduled tasks](/advanced/scheduler) and [caching](/advanced/caching)
85
+ - [File uploads](/advanced/file-uploads) with safe defaults
86
+ - [WebSockets](/microservices/websocket) with Socket.IO
87
+
88
+ **Tooling**
89
+ - The [`megh` CLI](/cli/basic): new projects, generators, migrations and
90
+ [scaffolding](/cli/scaffold/)
91
+ - [Testing helpers](/advanced/testing) and in-memory queue drivers
92
+
93
+ ## How it's built
94
+
95
+ - **On Fastify.** Megh adds structure on top of Fastify rather than replacing
96
+ it. The Fastify instance is always available as `app.app`, so any Fastify
97
+ plugin works.
98
+ - **Install only what you use.** Integrations such as CORS, OpenAPI, uploads,
99
+ Redis and Socket.IO are optional peer dependencies. If one is missing, the
100
+ `use*` call tells you what to install.
101
+ - **Safe defaults.** `@Authorized` routes are denied unless an authorization
102
+ handler allows them, fields a DTO doesn't declare are rejected with a 400,
103
+ 5xx details are hidden in production, and uploads get random names inside
104
+ a fixed folder.
105
+ - **CommonJS.** `@meghjs/core` ships one CommonJS build, which ESM projects
106
+ can still import. See [Installation](/getting-started/installation).
107
+
108
+ ## How it compares
109
+
110
+ - **Express and Fastify** give you routing and leave structure to you. Megh
111
+ adds controllers, DI, validation, an ORM and OpenAPI, on Fastify.
112
+ - **NestJS** is the closest in style: decorators, DI and controllers. Megh
113
+ has no module system, so there's less wiring, and it ships its own ORM and
114
+ scaffolding. NestJS has a much larger ecosystem and community.
115
+ - **AdonisJS** shares the batteries-included idea. Megh is decorator-first and
116
+ runs on Fastify.
117
+
118
+ ## Project status
119
+
120
+ Megh is in `0.x` and heading to 1.0. Minor releases can still contain
121
+ breaking changes, each with an upgrade guide. See the
122
+ [versioning policy](/reference/versioning) and
123
+ [upcoming changes](/getting-started/upgrading-next).
124
+
125
+ > **On 0.5.x?** See [Upgrading to 0.6](/getting-started/upgrading-0.6).
126
+
127
+ > **Coming from Avleon?** Avleon is now Megh. See
128
+ > [Moving from Avleon to Megh](/getting-started/upgrading-megh). On 0.3 or
129
+ > earlier, read [Upgrading to 0.4](/getting-started/upgrading-0.4) first.
130
+
131
+ ## Next steps
132
+
133
+ 1. [Install Megh](/getting-started/installation) and create a project.
134
+ 2. Follow the [Quick Start](/getting-started/usage) to write your first routes.
135
+ 3. Read [Application](/getting-started/application) to see how an app is
136
+ put together.
@@ -0,0 +1,125 @@
1
+ ---
2
+ title: Upgrading to 0.4
3
+ description: Breaking changes from 0.3 and what is new in 0.4.
4
+ ---
5
+
6
+ # Upgrading to 0.4
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
+ 0.4 moves the database integrations into their own package, adds plugins and
14
+ lifecycle hooks, and fixes security issues in optional dependencies. `@avleon/core`,
15
+ `@avleon/cli` and the new `@avleon/data` are released together and share a
16
+ version, so upgrade them together:
17
+
18
+ ```sh
19
+ npm i @avleon/core@^0.4.1 @avleon/cli@^0.4.1
20
+ ```
21
+
22
+ ## 1. TypeORM and Knex moved to `@avleon/data`
23
+
24
+ If your app uses `useTypeORM`, `useKnex` or any database helper, install the
25
+ new package:
26
+
27
+ ```sh
28
+ npm i @avleon/data@^0.4.0
29
+ ```
30
+
31
+ `app.useTypeORM()` and `app.useKnex()` keep their signatures. They are added by
32
+ the `@avleon/data` [plugin](/advanced/plugins), which the app finds among its
33
+ dependencies, so there is nothing to import or register. For TypeScript to see
34
+ the methods, add this file and include it in `tsconfig.json`:
35
+
36
+ ```ts [avleon-env.d.ts]
37
+ /// <reference types="@avleon/data" />
38
+ ```
39
+
40
+ ```json [tsconfig.json]
41
+ {
42
+ "include": ["avleon-env.d.ts", "src/**/*"]
43
+ }
44
+ ```
45
+
46
+ Import the database APIs from `@avleon/data` instead of `@avleon/core`:
47
+
48
+ ```ts
49
+ // Before
50
+ import { InjectRepository, KnexDB, AvleonRepository, Like } from '@avleon/core';
51
+ // After
52
+ import { InjectRepository, KnexDB, AvleonRepository, Like } from '@avleon/data';
53
+ ```
54
+
55
+ That covers `InjectRepository`, `PaginatedRepository`, `AvleonRepository`,
56
+ `Repository`, the query operators (`Like`, `ILike`, `In`, `Not`, `Between`, …),
57
+ `KnexDB`, `AVLEON_KNEX_DB`, `paginateKnex`, `registerDataSource`,
58
+ `getDataSource` and `DATASOURCE_TOKEN`. `Collection`, `List` and the
59
+ pagination helpers stay in `@avleon/core`.
60
+
61
+ Also changed:
62
+
63
+ - `Collection.fromRepository(Entity)` is now `paginatedRepository(Entity)` from
64
+ `@avleon/data`.
65
+ - `useDatasource()`, the `dataSourceOptions` application option and the
66
+ `dataSource` option of `createTestApplication` are removed. Use
67
+ `await app.useTypeORM(options)`.
68
+ - The connection opened by `useTypeORM` or `useKnex` is now closed when the app
69
+ shuts down.
70
+
71
+ ## 2. Upgrade `@fastify/static` and `@fastify/swagger-ui`
72
+
73
+ Every 8.x and 9.x release of `@fastify/static` is vulnerable to path
74
+ traversal, so core now requires patched versions of these optional peers. If
75
+ you use `useStaticFiles` or Swagger UI:
76
+
77
+ ```sh
78
+ npm i @fastify/static@^10.1.2 @fastify/swagger-ui@^6.1.2
79
+ ```
80
+
81
+ ## 3. `MockDB` is removed
82
+
83
+ `MockDB` called the global `jest.fn()` and only worked under Jest. Mock your
84
+ data layer with your test framework instead.
85
+
86
+ ## 4. Dependency injection
87
+
88
+ Avleon now has its own container API. Use it rather than importing `typedi`,
89
+ which may be replaced:
90
+
91
+ | Use | For |
92
+ |-----|-----|
93
+ | `AvleonContainer.get / set / has / reset` | Resolving and registering values |
94
+ | `@Injectable()` | Classes the container constructs (as `@AppService` does) |
95
+ | `new Token<T>('name')` | Values that are not classes |
96
+
97
+ `AvleonContainer` no longer exposes the rest of typedi's API, and
98
+ `@Utility()` / `@Helper()` no longer take typedi options. `AvleonContainer.reset()`
99
+ no longer calls `destroy()` on the instances it discards.
100
+
101
+ ## 5. New projects use Vitest
102
+
103
+ `avleon new` now scaffolds Vitest instead of Jest, with SWC for decorator
104
+ metadata. Existing projects are not changed.
105
+
106
+ ## What's new
107
+
108
+ - [Lifecycle hooks](/getting-started/application#lifecycle-hooks): `app.onInit`,
109
+ `app.onReady`, `app.onClose`, and `app.close()` for a clean shutdown.
110
+ - [Plugins](/advanced/plugins): packages can add `app.use*` methods, services
111
+ and hooks, and are found automatically once installed.
112
+
113
+ ### 0.4.1
114
+
115
+ - [MeghORM](/advanced/orm): type-safe models built on Kysely, with
116
+ relations and eager loading, timestamps, soft deletes, casts and
117
+ transactions. Connect them with `app.useDatabase(db)`.
118
+ - [Migrations](/advanced/orm/migrations): `avleon make:migration` and the
119
+ `migrate`, `migrate:status`, `migrate:rollback`, `migrate:reset` and
120
+ `migrate:refresh` [commands](/cli/database#migrations).
121
+ - The generated [OpenAPI](/microservices/openapi) spec now documents request
122
+ bodies.
123
+
124
+ The full list of changes is in the
125
+ [changelog](https://github.com/avleonjs/avleon/blob/main/packages/core/CHANGELOG.md).