0
# Inversify Express Utils
1
2
Inversify Express Utils provides a comprehensive set of utilities and decorators for building Express.js applications using the Inversify dependency injection container. It enables a decorator-based approach for defining controllers and routes, with built-in support for parameter binding, middleware integration, and authentication.
3
4
## Package Information
5
6
- **Package Name**: inversify-express-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install inversify-express-utils`
10
11
## Core Imports
12
13
```typescript
14
import {
15
InversifyExpressServer,
16
controller,
17
httpGet,
18
httpPost,
19
BaseHttpController,
20
requestParam,
21
requestBody,
22
queryParam
23
} from "inversify-express-utils";
24
```
25
26
For CommonJS:
27
28
```javascript
29
const {
30
InversifyExpressServer,
31
controller,
32
httpGet,
33
httpPost,
34
BaseHttpController,
35
requestParam,
36
requestBody,
37
queryParam
38
} = require("inversify-express-utils");
39
```
40
41
## Basic Usage
42
43
```typescript
44
import { Container } from "inversify";
45
import { InversifyExpressServer, controller, httpGet, requestParam, BaseHttpController } from "inversify-express-utils";
46
import express from "express";
47
48
// Create container and bind controllers
49
const container = new Container();
50
51
@controller("/users")
52
class UserController extends BaseHttpController {
53
@httpGet("/:id")
54
public getUser(@requestParam("id") userId: string) {
55
return this.ok({ id: userId, name: "John Doe" });
56
}
57
}
58
59
// Create and configure server
60
const server = new InversifyExpressServer(container);
61
server.setConfig((app) => {
62
app.use(express.json());
63
});
64
65
const app = server.build();
66
app.listen(3000);
67
```
68
69
## Architecture
70
71
Inversify Express Utils is built around several key components:
72
73
- **Server Wrapper**: `InversifyExpressServer` class that integrates Inversify container with Express
74
- **Decorator System**: Method and parameter decorators for defining routes and extracting request data
75
- **Controller Base Classes**: `BaseHttpController` and `BaseMiddleware` providing common functionality
76
- **Action Results**: Rich set of result classes for structured HTTP responses
77
- **HTTP Context**: Request-scoped context providing access to container and user information
78
- **Type System**: Full TypeScript integration with comprehensive interfaces and type definitions
79
80
## Capabilities
81
82
### Server Configuration
83
84
Core server setup and configuration functionality for integrating Inversify container with Express application. Handles route registration, middleware resolution, and HTTP context management.
85
86
```typescript { .api }
87
class InversifyExpressServer {
88
constructor(
89
container: interfaces.Container,
90
customRouter?: Router | null,
91
routingConfig?: RoutingConfig | null,
92
customApp?: Application | null,
93
authProvider?: (new () => AuthProvider) | null,
94
forceControllers?: boolean
95
);
96
97
setConfig(fn: ConfigFunction): this;
98
setErrorConfig(fn: ConfigFunction): this;
99
build(): Application;
100
}
101
102
interface RoutingConfig {
103
rootPath: string;
104
}
105
106
type ConfigFunction = (app: Application) => void;
107
```
108
109
[Server Configuration](./server.md)
110
111
### Controller Decorators
112
113
Decorator-based routing system for defining controllers and HTTP endpoints. Provides method decorators for all HTTP verbs and parameter decorators for request data extraction.
114
115
```typescript { .api }
116
function controller(path: string, ...middleware: Middleware[]): ClassDecorator;
117
118
function httpGet(path: string, ...middleware: Middleware[]): MethodDecorator;
119
function httpPost(path: string, ...middleware: Middleware[]): MethodDecorator;
120
function httpPut(path: string, ...middleware: Middleware[]): MethodDecorator;
121
function httpPatch(path: string, ...middleware: Middleware[]): MethodDecorator;
122
function httpDelete(path: string, ...middleware: Middleware[]): MethodDecorator;
123
function httpHead(path: string, ...middleware: Middleware[]): MethodDecorator;
124
function httpOptions(path: string, ...middleware: Middleware[]): MethodDecorator;
125
126
function requestParam(paramName?: string): ParameterDecorator;
127
function queryParam(queryParamName?: string): ParameterDecorator;
128
function requestBody(): ParameterDecorator;
129
function requestHeaders(headerName?: string): ParameterDecorator;
130
function cookies(cookieName?: string): ParameterDecorator;
131
function request(): ParameterDecorator;
132
function response(): ParameterDecorator;
133
function next(): ParameterDecorator;
134
function principal(): ParameterDecorator;
135
```
136
137
[Controller Decorators](./decorators.md)
138
139
### Base Controller
140
141
Base controller class providing helper methods for common HTTP responses and access to HTTP context. Includes methods for standard status codes and content negotiation.
142
143
```typescript { .api }
144
class BaseHttpController {
145
protected readonly httpContext: HttpContext;
146
147
protected created<T>(location: string | URL, content: T): CreatedNegotiatedContentResult<T>;
148
protected conflict(): ConflictResult;
149
protected ok<T>(content: T): OkNegotiatedContentResult<T>;
150
protected ok(): OkResult;
151
protected badRequest(): BadRequestResult;
152
protected badRequest(message: string): BadRequestErrorMessageResult;
153
protected internalServerError(): InternalServerErrorResult;
154
protected internalServerError(error: Error): ExceptionResult;
155
protected notFound(): NotFoundResult;
156
protected redirect(uri: string | URL): RedirectResult;
157
protected statusCode(statusCode: number): StatusCodeResult;
158
protected json(content: unknown, statusCode?: number): JsonResult;
159
protected stream(readableStream: Readable, contentType: string, statusCode?: number): StreamResult;
160
}
161
```
162
163
[Base Controller](./base-controller.md)
164
165
### Action Results
166
167
Comprehensive set of action result classes for structured HTTP responses. Implements the action result pattern for type-safe response handling with content negotiation support.
168
169
```typescript { .api }
170
interface IHttpActionResult {
171
executeAsync(): Promise<HttpResponseMessage>;
172
}
173
174
class HttpResponseMessage {
175
content: HttpContent;
176
headers: OutgoingHttpHeaders;
177
statusCode: number;
178
}
179
180
// Result classes
181
class OkResult implements IHttpActionResult;
182
class OkNegotiatedContentResult<T> implements IHttpActionResult;
183
class BadRequestResult implements IHttpActionResult;
184
class NotFoundResult implements IHttpActionResult;
185
class JsonResult implements IHttpActionResult;
186
class RedirectResult implements IHttpActionResult;
187
```
188
189
[Action Results](./results.md)
190
191
### Authentication & Authorization
192
193
Authentication and authorization system supporting custom auth providers, user principals, and role-based access control. Integrates seamlessly with dependency injection.
194
195
```typescript { .api }
196
interface Principal<T = unknown> {
197
details: T;
198
isAuthenticated(): Promise<boolean>;
199
isInRole(role: string): Promise<boolean>;
200
isResourceOwner(resourceId: unknown): Promise<boolean>;
201
}
202
203
interface AuthProvider {
204
getUser(req: Request, res: Response, next: NextFunction): Promise<Principal>;
205
}
206
207
interface HttpContext<T = unknown> {
208
container: interfaces.Container;
209
request: Request;
210
response: Response;
211
user: Principal<T>;
212
}
213
```
214
215
[Authentication](./auth.md)
216
217
### Middleware System
218
219
Middleware integration system supporting both Express middleware and custom Inversify-based middleware with dependency injection support.
220
221
```typescript { .api }
222
abstract class BaseMiddleware {
223
httpContext: HttpContext;
224
225
protected bind<T>(serviceIdentifier: interfaces.ServiceIdentifier<T>): interfaces.BindingToSyntax<T>;
226
abstract handler(req: Request, res: Response, next: NextFunction): void | Promise<void>;
227
}
228
229
function withMiddleware(...middleware: Middleware[]): ClassDecorator | MethodDecorator;
230
231
type Middleware = interfaces.ServiceIdentifier | RequestHandler;
232
```
233
234
[Middleware](./middleware.md)
235
236
### HTTP Content Classes
237
238
Content classes for structured HTTP response content with proper MIME type handling. Used internally by action results but also available for custom response scenarios.
239
240
```typescript { .api }
241
abstract class HttpContent {
242
readonly headers: OutgoingHttpHeaders;
243
abstract readAsync(): Promise<unknown>;
244
}
245
246
class JsonContent extends HttpContent {
247
constructor(content: unknown);
248
readAsync(): Promise<unknown>;
249
}
250
251
class StringContent extends HttpContent {
252
constructor(content: string);
253
readAsync(): Promise<string>;
254
}
255
256
class StreamContent extends HttpContent {
257
constructor(content: Readable, mediaType: string);
258
readAsync(): Promise<Readable>;
259
}
260
```
261
262
### Debug Utilities
263
264
Debug and introspection utilities for getting route information and metadata from the application. Useful for development, testing, and runtime inspection.
265
266
```typescript { .api }
267
function getRouteInfo(container: interfaces.Container): RouteInfo[];
268
function getRawMetadata(container: interfaces.Container): RawMetadata[];
269
270
interface RouteInfo {
271
controller: string;
272
endpoints: RouteDetails[];
273
}
274
275
interface RouteDetails {
276
route: string;
277
args?: string[];
278
}
279
280
interface RawMetadata {
281
controllerMetadata: ControllerMetadata;
282
methodMetadata: ControllerMethodMetadata[];
283
parameterMetadata: ControllerParameterMetadata;
284
}
285
```
286
287
## Constants and Types
288
289
```typescript { .api }
290
enum PARAMETER_TYPE {
291
REQUEST,
292
RESPONSE,
293
PARAMS,
294
QUERY,
295
BODY,
296
HEADERS,
297
COOKIES,
298
NEXT,
299
PRINCIPAL
300
}
301
302
enum HTTP_VERBS_ENUM {
303
all = 'all',
304
connect = 'connect',
305
delete = 'delete',
306
get = 'get',
307
head = 'head',
308
options = 'options',
309
patch = 'patch',
310
post = 'post',
311
propfind = 'propfind',
312
put = 'put',
313
trace = 'trace'
314
}
315
316
const TYPE = {
317
AuthProvider: Symbol.for('AuthProvider'),
318
Controller: Symbol.for('Controller'),
319
HttpContext: Symbol.for('HttpContext')
320
};
321
322
const METADATA_KEY = {
323
controller: 'inversify-express-utils:controller',
324
controllerMethod: 'inversify-express-utils:controller-method',
325
controllerParameter: 'inversify-express-utils:controller-parameter',
326
httpContext: 'inversify-express-utils:httpcontext',
327
middleware: 'inversify-express-utils:middleware'
328
};
329
```
330
331
### Utility Functions
332
333
Utility functions for working with controller metadata and Inversify container integration.
334
335
```typescript { .api }
336
function getControllersFromContainer(container: interfaces.Container, forceControllers: boolean): Controller[];
337
function getControllersFromMetadata(): DecoratorTarget[];
338
function getControllerMetadata(constructor: NewableFunction): ControllerMetadata;
339
function getControllerMethodMetadata(constructor: NewableFunction): ControllerMethodMetadata[];
340
function getControllerParameterMetadata(constructor: NewableFunction): ControllerParameterMetadata;
341
function cleanUpMetadata(): void;
342
function instanceOfIhttpActionResult(value: unknown): value is IHttpActionResult;
343
```