@heliosjs/aws 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +540 -0
- package/dist/constants.d.ts +25 -0
- package/dist/constants.js +34 -0
- package/dist/constants.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +19 -0
- package/dist/index.js.map +1 -0
- package/dist/lambda.d.ts +14 -0
- package/dist/lambda.js +149 -0
- package/dist/lambda.js.map +1 -0
- package/dist/types/aws/index.d.ts +2 -0
- package/dist/types/aws/index.js +19 -0
- package/dist/types/aws/index.js.map +1 -0
- package/dist/types/aws/lambda.d.ts +55 -0
- package/dist/types/aws/lambda.js +3 -0
- package/dist/types/aws/lambda.js.map +1 -0
- package/dist/types/aws/plugin.d.ts +16 -0
- package/dist/types/aws/plugin.js +3 -0
- package/dist/types/aws/plugin.js.map +1 -0
- package/dist/types/core/common.d.ts +44 -0
- package/dist/types/core/common.js +15 -0
- package/dist/types/core/common.js.map +1 -0
- package/dist/types/core/controller.d.ts +78 -0
- package/dist/types/core/controller.js +3 -0
- package/dist/types/core/controller.js.map +1 -0
- package/dist/types/core/cors.d.ts +10 -0
- package/dist/types/core/cors.js +3 -0
- package/dist/types/core/cors.js.map +1 -0
- package/dist/types/core/error.d.ts +72 -0
- package/dist/types/core/error.js +19 -0
- package/dist/types/core/error.js.map +1 -0
- package/dist/types/core/index.d.ts +9 -0
- package/dist/types/core/index.js +26 -0
- package/dist/types/core/index.js.map +1 -0
- package/dist/types/core/multipart.d.ts +8 -0
- package/dist/types/core/multipart.js +3 -0
- package/dist/types/core/multipart.js.map +1 -0
- package/dist/types/core/request.d.ts +65 -0
- package/dist/types/core/request.js +3 -0
- package/dist/types/core/request.js.map +1 -0
- package/dist/types/core/response.d.ts +49 -0
- package/dist/types/core/response.js +3 -0
- package/dist/types/core/response.js.map +1 -0
- package/dist/types/core/sanitize.d.ts +8 -0
- package/dist/types/core/sanitize.js +3 -0
- package/dist/types/core/sanitize.js.map +1 -0
- package/dist/types/core/sse.d.ts +37 -0
- package/dist/types/core/sse.js +3 -0
- package/dist/types/core/sse.js.map +1 -0
- package/dist/types/ws/index.d.ts +50 -0
- package/dist/types/ws/index.js +3 -0
- package/dist/types/ws/index.js.map +1 -0
- package/dist/utils/aws/helpers.d.ts +4 -0
- package/dist/utils/aws/helpers.js +84 -0
- package/dist/utils/aws/helpers.js.map +1 -0
- package/dist/utils/aws/index.d.ts +6 -0
- package/dist/utils/aws/index.js +23 -0
- package/dist/utils/aws/index.js.map +1 -0
- package/dist/utils/aws/lambda.d.ts +6 -0
- package/dist/utils/aws/lambda.event.normalizers.d.ts +42 -0
- package/dist/utils/aws/lambda.event.normalizers.js +260 -0
- package/dist/utils/aws/lambda.event.normalizers.js.map +1 -0
- package/dist/utils/aws/lambda.js +50 -0
- package/dist/utils/aws/lambda.js.map +1 -0
- package/dist/utils/aws/parsers.d.ts +8 -0
- package/dist/utils/aws/parsers.js +69 -0
- package/dist/utils/aws/parsers.js.map +1 -0
- package/dist/utils/aws/plugin.d.ts +9 -0
- package/dist/utils/aws/plugin.js +43 -0
- package/dist/utils/aws/plugin.js.map +1 -0
- package/dist/utils/aws/request.factory.d.ts +6 -0
- package/dist/utils/aws/request.factory.js +14 -0
- package/dist/utils/aws/request.factory.js.map +1 -0
- package/dist/utils/aws/response.factory.d.ts +8 -0
- package/dist/utils/aws/response.factory.js +14 -0
- package/dist/utils/aws/response.factory.js.map +1 -0
- package/dist/utils/core/controller.d.ts +25 -0
- package/dist/utils/core/controller.js +219 -0
- package/dist/utils/core/controller.js.map +1 -0
- package/dist/utils/core/cors.d.ts +8 -0
- package/dist/utils/core/cors.js +128 -0
- package/dist/utils/core/cors.js.map +1 -0
- package/dist/utils/core/endpoint.d.ts +3 -0
- package/dist/utils/core/endpoint.js +28 -0
- package/dist/utils/core/endpoint.js.map +1 -0
- package/dist/utils/core/error/apperror.d.ts +31 -0
- package/dist/utils/core/error/apperror.js +131 -0
- package/dist/utils/core/error/apperror.js.map +1 -0
- package/dist/utils/core/error/authorizations.d.ts +7 -0
- package/dist/utils/core/error/authorizations.js +17 -0
- package/dist/utils/core/error/authorizations.js.map +1 -0
- package/dist/utils/core/error/base.d.ts +20 -0
- package/dist/utils/core/error/base.js +52 -0
- package/dist/utils/core/error/base.js.map +1 -0
- package/dist/utils/core/error/dependencyFailed.d.ts +7 -0
- package/dist/utils/core/error/dependencyFailed.js +17 -0
- package/dist/utils/core/error/dependencyFailed.js.map +1 -0
- package/dist/utils/core/error/duplicateEntry.d.ts +7 -0
- package/dist/utils/core/error/duplicateEntry.js +17 -0
- package/dist/utils/core/error/duplicateEntry.js.map +1 -0
- package/dist/utils/core/error/forbidden.d.ts +7 -0
- package/dist/utils/core/error/forbidden.js +17 -0
- package/dist/utils/core/error/forbidden.js.map +1 -0
- package/dist/utils/core/error/helpers.d.ts +8 -0
- package/dist/utils/core/error/helpers.js +144 -0
- package/dist/utils/core/error/helpers.js.map +1 -0
- package/dist/utils/core/error/index.d.ts +12 -0
- package/dist/utils/core/error/index.js +29 -0
- package/dist/utils/core/error/index.js.map +1 -0
- package/dist/utils/core/error/invalidState.d.ts +7 -0
- package/dist/utils/core/error/invalidState.js +17 -0
- package/dist/utils/core/error/invalidState.js.map +1 -0
- package/dist/utils/core/error/notfound.d.ts +7 -0
- package/dist/utils/core/error/notfound.js +18 -0
- package/dist/utils/core/error/notfound.js.map +1 -0
- package/dist/utils/core/error/rateLimit.d.ts +7 -0
- package/dist/utils/core/error/rateLimit.js +17 -0
- package/dist/utils/core/error/rateLimit.js.map +1 -0
- package/dist/utils/core/error/serviceUnavailable.d.ts +7 -0
- package/dist/utils/core/error/serviceUnavailable.js +17 -0
- package/dist/utils/core/error/serviceUnavailable.js.map +1 -0
- package/dist/utils/core/error/validation.d.ts +10 -0
- package/dist/utils/core/error/validation.js +20 -0
- package/dist/utils/core/error/validation.js.map +1 -0
- package/dist/utils/core/headers.d.ts +2 -0
- package/dist/utils/core/headers.js +10 -0
- package/dist/utils/core/headers.js.map +1 -0
- package/dist/utils/core/helper.d.ts +6 -0
- package/dist/utils/core/helper.js +66 -0
- package/dist/utils/core/helper.js.map +1 -0
- package/dist/utils/core/index.d.ts +10 -0
- package/dist/utils/core/index.js +27 -0
- package/dist/utils/core/index.js.map +1 -0
- package/dist/utils/core/multipart.d.ts +9 -0
- package/dist/utils/core/multipart.js +207 -0
- package/dist/utils/core/multipart.js.map +1 -0
- package/dist/utils/core/request.d.ts +100 -0
- package/dist/utils/core/request.js +218 -0
- package/dist/utils/core/request.js.map +1 -0
- package/dist/utils/core/response.d.ts +48 -0
- package/dist/utils/core/response.js +269 -0
- package/dist/utils/core/response.js.map +1 -0
- package/dist/utils/core/routeWalker.d.ts +2 -0
- package/dist/utils/core/routeWalker.js +115 -0
- package/dist/utils/core/routeWalker.js.map +1 -0
- package/dist/utils/core/sanitize.d.ts +30 -0
- package/dist/utils/core/sanitize.js +134 -0
- package/dist/utils/core/sanitize.js.map +1 -0
- package/dist/utils/shared/index.d.ts +2 -0
- package/dist/utils/shared/index.js +19 -0
- package/dist/utils/shared/index.js.map +1 -0
- package/dist/utils/shared/parsers.d.ts +11 -0
- package/dist/utils/shared/parsers.js +133 -0
- package/dist/utils/shared/parsers.js.map +1 -0
- package/dist/utils/shared/validate.d.ts +1 -0
- package/dist/utils/shared/validate.js +41 -0
- package/dist/utils/shared/validate.js.map +1 -0
- package/dist/utils/socket/index.d.ts +3 -0
- package/dist/utils/socket/index.js +20 -0
- package/dist/utils/socket/index.js.map +1 -0
- package/dist/utils/socket/server.d.ts +33 -0
- package/dist/utils/socket/server.js +218 -0
- package/dist/utils/socket/server.js.map +1 -0
- package/dist/utils/socket/service.d.ts +20 -0
- package/dist/utils/socket/service.js +42 -0
- package/dist/utils/socket/service.js.map +1 -0
- package/dist/utils/socket/socket.d.ts +16 -0
- package/dist/utils/socket/socket.js +33 -0
- package/dist/utils/socket/socket.js.map +1 -0
- package/dist/utils/sse/index.d.ts +2 -0
- package/dist/utils/sse/index.js +19 -0
- package/dist/utils/sse/index.js.map +1 -0
- package/dist/utils/sse/server.d.ts +14 -0
- package/dist/utils/sse/server.js +85 -0
- package/dist/utils/sse/server.js.map +1 -0
- package/dist/utils/sse/service.d.ts +17 -0
- package/dist/utils/sse/service.js +40 -0
- package/dist/utils/sse/service.js.map +1 -0
- package/package.json +33 -0
package/README.md
ADDED
|
@@ -0,0 +1,540 @@
|
|
|
1
|
+
# Project Overview
|
|
2
|
+
|
|
3
|
+
This project is a decorator-based API framework supporting both HTTP and WebSocket servers. It is designed to simplify the creation of scalable and maintainable APIs with features such as controllers, middlewares, interceptors, error handling, and WebSocket support. Additionally, it supports AWS Lambda integration for serverless deployments.
|
|
4
|
+
|
|
5
|
+
# Installation
|
|
6
|
+
|
|
7
|
+
To install dependencies and build the project, run:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
yarn install
|
|
11
|
+
# or npm install
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
# Usage
|
|
15
|
+
|
|
16
|
+
You can use controllers and server functionality by importing controllers and creating server instances as shown in the examples above. Use your preferred testing framework to write unit and integration tests.
|
|
17
|
+
|
|
18
|
+
# Project Structure
|
|
19
|
+
|
|
20
|
+
- `quantum-flow/http` - Main application source code for HTTP servers.
|
|
21
|
+
- `quantum-flow/aws` - Main application source code for AWS Lambda.
|
|
22
|
+
- `quantum-flow/core` - Core framework components like Controller and Endpoint.
|
|
23
|
+
- `quantum-flow/middlewares` - Core middlewares to use within the application.
|
|
24
|
+
- `quantum-flow/ws` - Websocket decorators.
|
|
25
|
+
- `quantum-flow/sse` - Server side events decorators.
|
|
26
|
+
- `quantum-flow/plugins/aws` - Exports plugins types for lambda.
|
|
27
|
+
- `quantum-flow/plugins/http` - Exports plugins types for http server.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Defining Controllers
|
|
32
|
+
|
|
33
|
+
Use the `@Controller` decorator to define controllers with options such as prefix, sub-controllers, middlewares, and interceptors.
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
import {
|
|
37
|
+
Body,
|
|
38
|
+
Controller,
|
|
39
|
+
Headers,
|
|
40
|
+
IWebSocketService,
|
|
41
|
+
Params,
|
|
42
|
+
PUT,
|
|
43
|
+
Query,
|
|
44
|
+
Request,
|
|
45
|
+
Response,
|
|
46
|
+
Status,
|
|
47
|
+
ANY,
|
|
48
|
+
IRequest,
|
|
49
|
+
IResponse
|
|
50
|
+
} from 'quantum-flow/core';
|
|
51
|
+
import {IsString} from 'class-validator'
|
|
52
|
+
import { Catch, Cors, Sanitize, Use, SANITIZER } from 'quantum-flow/middlewares';
|
|
53
|
+
import { InjectWS } from 'quantum-flow/ws';
|
|
54
|
+
import { HttpRequest } from 'quantum-flow/http';
|
|
55
|
+
// SANITIZER - prefilled Joi schema for common data
|
|
56
|
+
class UserDto {
|
|
57
|
+
constructor() {}
|
|
58
|
+
@IsString()
|
|
59
|
+
name: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
@Controller({
|
|
63
|
+
prefix: 'user',
|
|
64
|
+
controllers: [UserMetadata, ...],
|
|
65
|
+
interceptor: (data, req, res) => data,
|
|
66
|
+
})
|
|
67
|
+
@Cors({ origin: '*' })
|
|
68
|
+
@Catch((err) => ({ status: 500, err }))
|
|
69
|
+
@Use(()=>{})
|
|
70
|
+
@Sanitize({
|
|
71
|
+
schema: Joi.object({name: Joi.string().trim().min(2).max(50).required()}),
|
|
72
|
+
action: 'both',
|
|
73
|
+
options: { abortEarly: false },
|
|
74
|
+
stripUnknown: true,
|
|
75
|
+
type: 'body',
|
|
76
|
+
})
|
|
77
|
+
export class User {
|
|
78
|
+
@Status(201)
|
|
79
|
+
@PUT(':id',[(req, res)=>{} , ...middlewares])
|
|
80
|
+
@Cors({ origin: '*' })
|
|
81
|
+
async createUser(
|
|
82
|
+
@Body(UserDto) body: UserDto,
|
|
83
|
+
@Query() query: Record<string, string | string[]>,
|
|
84
|
+
@Headers() headers: Record<string, string | string[]>,
|
|
85
|
+
@Params(ParamDTO, 'param') params: string,
|
|
86
|
+
@Request() req: IResponse,
|
|
87
|
+
@Response() resp: IRequest,
|
|
88
|
+
@InjectWS() ws: IWebSocketService,
|
|
89
|
+
) {}
|
|
90
|
+
|
|
91
|
+
@ANY([...middlewares])
|
|
92
|
+
async any(@Response() resp: any) {...}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
@Controller(api, [...middlewares])
|
|
96
|
+
@Controller({
|
|
97
|
+
prefix: 'api',
|
|
98
|
+
controllers: [UserController, SocketController],
|
|
99
|
+
middlewares: [...middlewares],
|
|
100
|
+
interceptor: (data, req, res) => data,
|
|
101
|
+
})
|
|
102
|
+
@Catch((error) => ({ status: 400, error }))
|
|
103
|
+
class RootController {}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Creating a http Server
|
|
107
|
+
|
|
108
|
+
Use the `@Server` decorator with configuration options like port, host, controllers, and WebSocket enablement.
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
import { Server, Port, Host, Use, Catch, HttpServer } from 'quantum-flow/http';
|
|
112
|
+
|
|
113
|
+
@Server({ controllers: [RootController], cors: { origin: '*' } })
|
|
114
|
+
@Port(3000)
|
|
115
|
+
@Host('localhost')
|
|
116
|
+
@Use((data) => data)
|
|
117
|
+
@Catch((error) => ({ status: 400, error }))
|
|
118
|
+
class App {}
|
|
119
|
+
|
|
120
|
+
const server = new HttpServer(App);
|
|
121
|
+
|
|
122
|
+
server.listen().catch(console.error);
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Middlewares, Interceptors, and Error Handlers
|
|
126
|
+
|
|
127
|
+
- Use `@Use` to apply middlewares.
|
|
128
|
+
- Use `@Catch` to handle errors.
|
|
129
|
+
- Use `@Port` and `@Host` to configure server port and host.
|
|
130
|
+
- Use `@Cors` to configure cors.
|
|
131
|
+
- Use `@Sanitize` to apply sanitization to reqest.
|
|
132
|
+
|
|
133
|
+
## Request decorators
|
|
134
|
+
|
|
135
|
+
- Use `@Body` to handle request bodies.
|
|
136
|
+
- Use `@Headers` to access request headers.
|
|
137
|
+
- Use `@Query` to handle query parameters.
|
|
138
|
+
- Use `@Params` to access route parameters.
|
|
139
|
+
- Use `@Files` to access files sent within multipart/form-data requests.
|
|
140
|
+
Text sent as multipart/form-data is exposed with `@Body` decorators
|
|
141
|
+
- Use `@Request` to access the original request object.
|
|
142
|
+
- Use `@Response` to access the original object.
|
|
143
|
+
- Use `@InjectWS` to access the websocket service.
|
|
144
|
+
- Use `@InjectSSE` to access the server-side-event service.
|
|
145
|
+
|
|
146
|
+
# AWS Lambda Support
|
|
147
|
+
|
|
148
|
+
Use `LambdaAdapter` to convert API Gateway events to requests and responses. Create Lambda handlers from controllers.
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
Example Lambda handler creation
|
|
152
|
+
import { LambdaAdapter, LambdaRequest, LambdaResponse } from 'quantum-flow/aws';
|
|
153
|
+
import { Request, Query, Headers, Params, Response, IResponse, IRequest } from 'quantum-flow/core'
|
|
154
|
+
|
|
155
|
+
@Controller({ prefix: 'user' })
|
|
156
|
+
class UserController {
|
|
157
|
+
@Body(UserDto) body: UserDto,
|
|
158
|
+
@Query() query: Record<string, string | string[]>,
|
|
159
|
+
@Headers() headers: Record<string, string | string[]>,
|
|
160
|
+
@Params(ParamDTO, 'param') params: string,
|
|
161
|
+
@Request() req: IRequest,
|
|
162
|
+
@Response() res: IResponse
|
|
163
|
+
) { }
|
|
164
|
+
}
|
|
165
|
+
const lambdaAdapter = new LambdaAdapter(UserController);
|
|
166
|
+
export const handler = lambdaAdapter.handler;
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
You can access context and event throught @Request() decorator:
|
|
170
|
+
@Request() request: LambdaRequest
|
|
171
|
+
request.context
|
|
172
|
+
request.event
|
|
173
|
+
|
|
174
|
+
# WebSocket Support
|
|
175
|
+
|
|
176
|
+
Enable WebSocket in the server configuration and register WebSocket controllers.
|
|
177
|
+
|
|
178
|
+
## Enabling WebSocket Support in Server
|
|
179
|
+
|
|
180
|
+
To enable WS support, configure your HTTP server with the `path: string` option and register controllers that use SSE.
|
|
181
|
+
|
|
182
|
+
Example server setup:
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
@Server( { websocket: { path:'/ws' } })
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Injecting WebSocket events in Controller
|
|
189
|
+
|
|
190
|
+
```typescript
|
|
191
|
+
import { OnConnection, Subscribe, OnMessage } from 'quantum-flow/ws';
|
|
192
|
+
@Controller('socket')
|
|
193
|
+
export class Socket {
|
|
194
|
+
@OnConnection()
|
|
195
|
+
onConnection(event: WebSocketEvent) {
|
|
196
|
+
// Send greeting ONLY to this client
|
|
197
|
+
event.client.socket.send(JSON.stringify({ type: 'welcome', data: { message: 'Welcome!' } }));
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* 2. @Subscribe - AUTOMATIC broadcast to all subscribers
|
|
202
|
+
* No need to use WebSocketService!
|
|
203
|
+
*/
|
|
204
|
+
@Subscribe('chat')
|
|
205
|
+
onChatMessage(event: WebSocketEvent) {
|
|
206
|
+
// This method is called for EACH subscriber
|
|
207
|
+
// The message is ALREADY automatically broadcast to all!
|
|
208
|
+
|
|
209
|
+
const msg = event.message?.data;
|
|
210
|
+
// You can add logic, but no need to broadcast
|
|
211
|
+
if (msg?.text.includes('bad')) {
|
|
212
|
+
// If return empty, the message will not be sent
|
|
213
|
+
return;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
// That's it, the message will be sent to subscribers automatically!
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* 4. @OnMessage for commands (without WebSocketService)
|
|
221
|
+
*/
|
|
222
|
+
@OnMessage('ping')
|
|
223
|
+
onPing(event: WebSocketEvent) {
|
|
224
|
+
// Send response only to this client
|
|
225
|
+
event.client.socket.send(
|
|
226
|
+
JSON.stringify({
|
|
227
|
+
type: 'pong',
|
|
228
|
+
data: { time: Date.now() },
|
|
229
|
+
}),
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* 5. @OnMessage for subscription
|
|
235
|
+
*/
|
|
236
|
+
@OnMessage('subscribe')
|
|
237
|
+
onSubscribe(event: WebSocketEvent) {
|
|
238
|
+
const topic = event.message?.data.topic;
|
|
239
|
+
|
|
240
|
+
// Server will save the subscription automatically, no need to do anything!
|
|
241
|
+
// Just confirm
|
|
242
|
+
event.client.socket.send(
|
|
243
|
+
JSON.stringify({
|
|
244
|
+
type: 'subscribed',
|
|
245
|
+
topic,
|
|
246
|
+
data: { success: true },
|
|
247
|
+
}),
|
|
248
|
+
);
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
# Server-Sent Events (SSE) Support
|
|
254
|
+
|
|
255
|
+
The framework supports Server-Sent Events (SSE) to enable real-time, one-way communication from the server to clients over HTTP.
|
|
256
|
+
|
|
257
|
+
## Defining SSE Controllers
|
|
258
|
+
|
|
259
|
+
Use the `@Controller` decorator to define controllers with a `prefix` and optionally include sub-controllers. This allows modular organization of your API endpoints.
|
|
260
|
+
|
|
261
|
+
Example:
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
@Controller({
|
|
265
|
+
prefix: 'user',
|
|
266
|
+
controllers: [UserMetadata],
|
|
267
|
+
middlewares: [function UserGlobalUse() {}],
|
|
268
|
+
interceptor: (data, req, res) => {
|
|
269
|
+
return { data, intercepted: true };
|
|
270
|
+
},
|
|
271
|
+
})
|
|
272
|
+
export class User {}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
## Injecting SSE Service
|
|
276
|
+
|
|
277
|
+
Use the `@InjectSSE` decorator in your controller methods to create and manage SSE connections. This service allows sending events to connected clients.
|
|
278
|
+
|
|
279
|
+
Example method using SSE:
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
import { InjectSSE } from 'quantum-flow/sse';
|
|
283
|
+
|
|
284
|
+
@Controller('user')
|
|
285
|
+
export class UserMetadata {
|
|
286
|
+
@GET('/subscribesse')
|
|
287
|
+
async subscribesse(@InjectSSE() sse) {
|
|
288
|
+
const client = sse.createConnection(res);
|
|
289
|
+
sse.sendToClient(client.id, {
|
|
290
|
+
event: 'welcome message',
|
|
291
|
+
data: { message: 'Connected to notifications' },
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## SSE Event Decorators
|
|
298
|
+
|
|
299
|
+
The framework provides decorators to handle SSE connection lifecycle events:
|
|
300
|
+
|
|
301
|
+
- `@OnSSEConnection()`: Decorate a method to handle new SSE connections.
|
|
302
|
+
- `@OnSSEError()`: Decorate a method to handle SSE errors.
|
|
303
|
+
- `@OnSSEClose()`: Decorate a method to handle SSE connection closures.
|
|
304
|
+
|
|
305
|
+
Example usage:
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
import { OnSSEConnection, OnSSEError, OnSSEClose } from 'quantum-flow/sse';
|
|
309
|
+
|
|
310
|
+
@Controller('user')
|
|
311
|
+
export class User {
|
|
312
|
+
@OnSSEConnection()
|
|
313
|
+
async onsseconnection(@Request() req, @Response() res) {
|
|
314
|
+
console.log('SSE connection established');
|
|
315
|
+
return req.body;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
@OnSSEError()
|
|
319
|
+
async onsseerror(@Request() req, @Response() res) {
|
|
320
|
+
console.log('SSE error occurred');
|
|
321
|
+
return req.body;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
@OnSSEClose()
|
|
325
|
+
async onsseclose(@Request() req, @Response() res) {
|
|
326
|
+
console.log('SSE connection closed');
|
|
327
|
+
return req.body;
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
## Sending SSE Events
|
|
333
|
+
|
|
334
|
+
Use the injected SSE service to send events to clients. You can send events to all clients or specific clients by ID.
|
|
335
|
+
|
|
336
|
+
Example:
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
sse.sendToClient(clientId, { event: 'eventName', data: { key: 'value' } });
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## Enabling SSE Support in Server
|
|
343
|
+
|
|
344
|
+
To enable SSE support, configure your HTTP server with the `sse: true` option and register controllers that use SSE.
|
|
345
|
+
|
|
346
|
+
Example server setup:
|
|
347
|
+
|
|
348
|
+
```typescript
|
|
349
|
+
import { Server, HttpServer } from 'quantum-flow/http';
|
|
350
|
+
import { User, UserMetadata } from './controllers';
|
|
351
|
+
|
|
352
|
+
@Server({
|
|
353
|
+
controllers: [User, UserMetadata],
|
|
354
|
+
sse: { enabled: true },
|
|
355
|
+
})
|
|
356
|
+
class App {}
|
|
357
|
+
|
|
358
|
+
const server = new HttpServer(App);
|
|
359
|
+
server.listen().catch(console.error);
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
## Enabling static files
|
|
363
|
+
|
|
364
|
+
To enable serving static files, use statics option.
|
|
365
|
+
|
|
366
|
+
Example server setup:
|
|
367
|
+
|
|
368
|
+
```typescript
|
|
369
|
+
import { Server, HttpServer } from 'quantum-flow/http';
|
|
370
|
+
import { User, UserMetadata } from './controllers';
|
|
371
|
+
|
|
372
|
+
@Server({
|
|
373
|
+
statics: [
|
|
374
|
+
{
|
|
375
|
+
path: path.join(__dirname, './public'),
|
|
376
|
+
options: {
|
|
377
|
+
index: 'index.html',
|
|
378
|
+
extensions: ['html', 'htm', 'css', 'js'],
|
|
379
|
+
maxAge: 86400,
|
|
380
|
+
immutable: true,
|
|
381
|
+
dotfiles: 'deny',
|
|
382
|
+
fallthrough: false,
|
|
383
|
+
setHeaders: (res, filePath, stats) => {
|
|
384
|
+
if (filePath.endsWith('.css')) {
|
|
385
|
+
res.setHeader('Content-Type', 'text/css');
|
|
386
|
+
}
|
|
387
|
+
},
|
|
388
|
+
},
|
|
389
|
+
},
|
|
390
|
+
],
|
|
391
|
+
})
|
|
392
|
+
class App {}
|
|
393
|
+
|
|
394
|
+
const server = new HttpServer(App);
|
|
395
|
+
server.listen().catch(console.error);
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
## Custom plugins.
|
|
399
|
+
|
|
400
|
+
Use plugins to extend app with custom logic.
|
|
401
|
+
|
|
402
|
+
Example server setup:
|
|
403
|
+
|
|
404
|
+
```typescript
|
|
405
|
+
import { Server, HttpServer } from 'quantum-flow/http';
|
|
406
|
+
import { User, UserMetadata } from './controllers';
|
|
407
|
+
import client from 'prom-client';
|
|
408
|
+
|
|
409
|
+
const register = new client.Registry();
|
|
410
|
+
client.collectDefaultMetrics({ register });
|
|
411
|
+
|
|
412
|
+
const httpRequestsTotal = new client.Counter({
|
|
413
|
+
name: 'http_requests_total',
|
|
414
|
+
help: 'Total number of HTTP requests',
|
|
415
|
+
labelNames: ['method', 'path', 'status'],
|
|
416
|
+
});
|
|
417
|
+
|
|
418
|
+
@Controller({ prefix: 'metrics' })
|
|
419
|
+
export class MetricsController {...}
|
|
420
|
+
@Server({...})
|
|
421
|
+
class App {}
|
|
422
|
+
|
|
423
|
+
const server = new HttpServer(App);
|
|
424
|
+
server.usePligun(metricsPlugin)
|
|
425
|
+
server.listen().catch(console.error);
|
|
426
|
+
|
|
427
|
+
// Lambda setup
|
|
428
|
+
let connection;
|
|
429
|
+
const dbConnectionPlugin: Plugin = {
|
|
430
|
+
name: 'metric',
|
|
431
|
+
beforeRequest: async(server) => {
|
|
432
|
+
if(!connection){
|
|
433
|
+
connection = await connetct(...)
|
|
434
|
+
}
|
|
435
|
+
},
|
|
436
|
+
hooks: {...},
|
|
437
|
+
};
|
|
438
|
+
|
|
439
|
+
const lambdaAdapter = new LambdaAdapter(Root);
|
|
440
|
+
lambdaAdapter.usePlugin(dbConnectionPlugin);
|
|
441
|
+
|
|
442
|
+
export const handler = lambdaAdapter.handler;
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
## GraphQL
|
|
446
|
+
|
|
447
|
+
Quantum Flow provides seamless GraphQL integration using the popular **TypeGraphQL** library. You can build fully typed GraphQL APIs with decorators, while the framework handles the server setup, subscriptions, and PubSub.
|
|
448
|
+
|
|
449
|
+
### Installation
|
|
450
|
+
|
|
451
|
+
```bash
|
|
452
|
+
npm install type-graphql graphql graphql-yoga @graphql-yoga/subscriptions
|
|
453
|
+
# or
|
|
454
|
+
yarn add type-graphql graphql graphql-yoga @graphql-yoga/subscriptions
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
```typescript
|
|
458
|
+
@Server({
|
|
459
|
+
controllers: [/* your REST controllers */],
|
|
460
|
+
graphql: { // GraphQL endpoint (default: '/graphql')
|
|
461
|
+
path: '/graphql', // Enable GraphQL Playground
|
|
462
|
+
resolvers: [UserResolver, MessageResolver], // Your resolver classes
|
|
463
|
+
pubSub: pubSub, // Your PubSub instance (required for subscriptions)
|
|
464
|
+
},
|
|
465
|
+
})
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
## Usage example
|
|
469
|
+
|
|
470
|
+
```typescript
|
|
471
|
+
import { IsEmail, MinLength } from 'class-validator';
|
|
472
|
+
import {
|
|
473
|
+
Arg,
|
|
474
|
+
Ctx,
|
|
475
|
+
Field,
|
|
476
|
+
InputType,
|
|
477
|
+
Mutation,
|
|
478
|
+
ObjectType,
|
|
479
|
+
Query,
|
|
480
|
+
Resolver,
|
|
481
|
+
Root,
|
|
482
|
+
Subscription,
|
|
483
|
+
} from 'type-graphql';
|
|
484
|
+
|
|
485
|
+
import { createPubSub } from 'graphql-yoga';
|
|
486
|
+
|
|
487
|
+
export type PubSubChannels = {
|
|
488
|
+
NOTIFICATIONS: [{ id: string; userId: string; message: string }];
|
|
489
|
+
USER_UPDATED: [{ user: User }];
|
|
490
|
+
};
|
|
491
|
+
|
|
492
|
+
export const pubSub = createPubSub<PubSubChannels>();
|
|
493
|
+
|
|
494
|
+
@ObjectType()
|
|
495
|
+
export class User {
|
|
496
|
+
@Field()
|
|
497
|
+
id: string;
|
|
498
|
+
@Field()
|
|
499
|
+
name: string;
|
|
500
|
+
@Field()
|
|
501
|
+
email: string;
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
@InputType()
|
|
505
|
+
export class CreateUserInput {
|
|
506
|
+
@Field()
|
|
507
|
+
@MinLength(2)
|
|
508
|
+
name: string;
|
|
509
|
+
@Field()
|
|
510
|
+
@IsEmail()
|
|
511
|
+
email: string;
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
@Resolver()
|
|
515
|
+
export class UserResolver {
|
|
516
|
+
@Query(() => [User])
|
|
517
|
+
async users(): Promise<User[]> {
|
|
518
|
+
// pubSub.publish('USER_UPDATED', {...});
|
|
519
|
+
return [];
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
@Mutation(() => User)
|
|
523
|
+
async createUser(@Ctx() ctx: any, @Arg('input') input: CreateUserInput): Promise<User> {
|
|
524
|
+
const user = {
|
|
525
|
+
id: Date.now().toString(),
|
|
526
|
+
...input,
|
|
527
|
+
};
|
|
528
|
+
|
|
529
|
+
return user;
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
@Subscription(() => User, {
|
|
533
|
+
topics: 'USER_UPDATED',
|
|
534
|
+
filter: ({ payload, args }) => true,
|
|
535
|
+
})
|
|
536
|
+
newUser(@Root() user: User): User {
|
|
537
|
+
return user;
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export declare const PARAM_METADATA_KEY = "design:parameters";
|
|
2
|
+
export declare const APP_METADATA_KEY = "app:configuration";
|
|
3
|
+
export declare const ROUTE_PREFIX = "route:prefix";
|
|
4
|
+
export declare const ROUTE_MIDDLEWARES = "route:middlewares";
|
|
5
|
+
export declare const MIDDLEWARES = "controller:middlewares";
|
|
6
|
+
export declare const CONTROLLERS = "app:controllers";
|
|
7
|
+
export declare const INTERCEPTOR = "app:interceptors";
|
|
8
|
+
export declare const ENDPOINT = "route:endpoints";
|
|
9
|
+
export declare const OK_METADATA_KEY = "custom:ok";
|
|
10
|
+
export declare const SERVER_CONFIG_KEY = "server:config";
|
|
11
|
+
export declare const USE_MIDDLEWARE = "controller:usemiddleware";
|
|
12
|
+
export declare const WS_HANDLER = "websocket:handler";
|
|
13
|
+
export declare const WS_TOPIC_KEY = "websocket:topic";
|
|
14
|
+
export declare const WS_SERVICE_KEY = "websocket:service";
|
|
15
|
+
export declare const INTECEPT = "server:intercept";
|
|
16
|
+
export declare const CATCH = "server:catch";
|
|
17
|
+
export declare const SANITIZE = "action:sanitize";
|
|
18
|
+
export declare const STOPPED = "\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551 \uD83D\uDC4B Server stopped \u2551\n\u2551 \uD83D\uDCCA Status: STOPPED \u2551\n\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n ";
|
|
19
|
+
export declare const OK_STATUSES: number[];
|
|
20
|
+
export declare const TO_VALIDATE: string[];
|
|
21
|
+
export declare const CORS_METADATA = "cors:config";
|
|
22
|
+
export declare const SSE_METADATA_KEY = "sse:handlers";
|
|
23
|
+
export declare const SSE_TOPIC_KEY = "sse:topics";
|
|
24
|
+
export declare const SSE_SERVICE_KEY = "sse:service";
|
|
25
|
+
export declare const STATIC_METADATA_KEY = "static:config";
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.STATIC_METADATA_KEY = exports.SSE_SERVICE_KEY = exports.SSE_TOPIC_KEY = exports.SSE_METADATA_KEY = exports.CORS_METADATA = exports.TO_VALIDATE = exports.OK_STATUSES = exports.STOPPED = exports.SANITIZE = exports.CATCH = exports.INTECEPT = exports.WS_SERVICE_KEY = exports.WS_TOPIC_KEY = exports.WS_HANDLER = exports.USE_MIDDLEWARE = exports.SERVER_CONFIG_KEY = exports.OK_METADATA_KEY = exports.ENDPOINT = exports.INTERCEPTOR = exports.CONTROLLERS = exports.MIDDLEWARES = exports.ROUTE_MIDDLEWARES = exports.ROUTE_PREFIX = exports.APP_METADATA_KEY = exports.PARAM_METADATA_KEY = void 0;
|
|
4
|
+
exports.PARAM_METADATA_KEY = 'design:parameters';
|
|
5
|
+
exports.APP_METADATA_KEY = 'app:configuration';
|
|
6
|
+
exports.ROUTE_PREFIX = 'route:prefix';
|
|
7
|
+
exports.ROUTE_MIDDLEWARES = 'route:middlewares';
|
|
8
|
+
exports.MIDDLEWARES = 'controller:middlewares';
|
|
9
|
+
exports.CONTROLLERS = 'app:controllers';
|
|
10
|
+
exports.INTERCEPTOR = 'app:interceptors';
|
|
11
|
+
exports.ENDPOINT = 'route:endpoints';
|
|
12
|
+
exports.OK_METADATA_KEY = 'custom:ok';
|
|
13
|
+
exports.SERVER_CONFIG_KEY = 'server:config';
|
|
14
|
+
exports.USE_MIDDLEWARE = 'controller:usemiddleware';
|
|
15
|
+
exports.WS_HANDLER = 'websocket:handler';
|
|
16
|
+
exports.WS_TOPIC_KEY = 'websocket:topic';
|
|
17
|
+
exports.WS_SERVICE_KEY = 'websocket:service';
|
|
18
|
+
exports.INTECEPT = 'server:intercept';
|
|
19
|
+
exports.CATCH = 'server:catch';
|
|
20
|
+
exports.SANITIZE = 'action:sanitize';
|
|
21
|
+
exports.STOPPED = `
|
|
22
|
+
╔════════════════════════════════════════╗
|
|
23
|
+
║ 👋 Server stopped ║
|
|
24
|
+
║ 📊 Status: STOPPED ║
|
|
25
|
+
╚════════════════════════════════════════╝
|
|
26
|
+
`;
|
|
27
|
+
exports.OK_STATUSES = [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
|
|
28
|
+
exports.TO_VALIDATE = ['headers', 'params', 'multipart', 'query', 'body'];
|
|
29
|
+
exports.CORS_METADATA = 'cors:config';
|
|
30
|
+
exports.SSE_METADATA_KEY = 'sse:handlers';
|
|
31
|
+
exports.SSE_TOPIC_KEY = 'sse:topics';
|
|
32
|
+
exports.SSE_SERVICE_KEY = 'sse:service';
|
|
33
|
+
exports.STATIC_METADATA_KEY = 'static:config';
|
|
34
|
+
//# sourceMappingURL=constants.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,kBAAkB,GAAG,mBAAmB,CAAC;AACzC,QAAA,gBAAgB,GAAG,mBAAmB,CAAC;AACvC,QAAA,YAAY,GAAG,cAAc,CAAC;AAC9B,QAAA,iBAAiB,GAAG,mBAAmB,CAAC;AACxC,QAAA,WAAW,GAAG,wBAAwB,CAAC;AACvC,QAAA,WAAW,GAAG,iBAAiB,CAAC;AAChC,QAAA,WAAW,GAAG,kBAAkB,CAAC;AACjC,QAAA,QAAQ,GAAG,iBAAiB,CAAC;AAC7B,QAAA,eAAe,GAAG,WAAW,CAAC;AAE9B,QAAA,iBAAiB,GAAG,eAAe,CAAC;AACpC,QAAA,cAAc,GAAG,0BAA0B,CAAC;AAE5C,QAAA,UAAU,GAAG,mBAAmB,CAAC;AACjC,QAAA,YAAY,GAAG,iBAAiB,CAAC;AACjC,QAAA,cAAc,GAAG,mBAAmB,CAAC;AACrC,QAAA,QAAQ,GAAG,kBAAkB,CAAC;AAC9B,QAAA,KAAK,GAAG,cAAc,CAAC;AACvB,QAAA,QAAQ,GAAG,iBAAiB,CAAC;AAE7B,QAAA,OAAO,GAAG;;;;;WAKZ,CAAC;AAEC,QAAA,WAAW,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AACjE,QAAA,WAAW,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAElE,QAAA,aAAa,GAAG,aAAa,CAAC;AAC9B,QAAA,gBAAgB,GAAG,cAAc,CAAC;AAClC,QAAA,aAAa,GAAG,YAAY,CAAC;AAC7B,QAAA,eAAe,GAAG,aAAa,CAAC;AAChC,QAAA,mBAAmB,GAAG,eAAe,CAAC"}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
require("reflect-metadata");
|
|
18
|
+
__exportStar(require("./lambda"), exports);
|
|
19
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4BAA0B;AAE1B,2CAAyB"}
|
package/dist/lambda.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { ILambdaAdapter, Plugin as LambdaPlugin } from './types/aws';
|
|
2
|
+
import { Handler } from 'aws-lambda';
|
|
3
|
+
import { ControllerClass } from './types/core';
|
|
4
|
+
import { Plugin } from './utils/aws';
|
|
5
|
+
export declare class LambdaAdapter extends Plugin implements ILambdaAdapter {
|
|
6
|
+
handler: Handler;
|
|
7
|
+
controllers: ControllerClass[];
|
|
8
|
+
plugins: LambdaPlugin[];
|
|
9
|
+
constructor(Controller: ControllerClass);
|
|
10
|
+
private createHandler;
|
|
11
|
+
private runControllers;
|
|
12
|
+
private toLambdaResponse;
|
|
13
|
+
private handleError;
|
|
14
|
+
}
|