README.md

Deepkit Http Extension

Extension of @deepkit/http package for more convenient HTTP request handling.

npm i @deepkit-rest/http-extension

Overview

DeepKit Framework allows us to define schemas of a route via the type system so that the framework will do serialization/deserialization and validation for us, which is quite convenient in most simple cases but also limits how far we can abstract some fixed process to implement automation because everything should be defined ahead of time by ourselves instead of generated by services.

By using DeepKit HTTP Extension, we are able to handle HTTP requests in anyway we want in services and get rid of the fixed request handling process of DeepKit Framework, because now everything related to the request are available for you via the Dependency Injection System so that you can parse the request progressively in different services:

class Paginator {
  constructor(private request: HttpRequestParsed) {}

  paginate<Entity>(query: Query<Entity>): Query<Entity> {
    const purifiedQueries = this.request.getQueries<Pagination>();
    const { limit, offset } = purifiedQueries;
    return query.limit(limit).skip(offset);
  }
}

interface Pagination {
  limit: number & PositiveNoZero & Maximum<100>;
  offset: number & Positive & Maximum<1000>;
}

Manual

You need to import the HttpExtensionModule to leverage the features of this library:

new App({
  imports: [new FrameworkModule(), new HttpExtensionModule()],
}).run();

Http Scoped Dynamic Injection

In Deepkit, a provider can only inject the root InjectorContext instance no matter in what scope it is, which means you cannot inject the http scoped InjectorContext in an http scoped provider and thus you cannot dynamically get other http scoped dependencies.

Fortunately, with DeepKit HTTP Extension this problem no longer exists. You can now inject the http scoped InjectorContext instance using the HttpInjectorContext injection token:

class MyService {
  constructor(private injectorContext: HttpInjectorContext) {}
}

Route Information

You can get the route information via these new http scoped injection tokens:

Token	Value
HttpRouteConfig	RouteConfig instance of the current route
HttpControllerMeta	HttpController instance of the current controller
HttpActionMeta	HttpAction instance of the current controller action

Note that the injection value of HttpControllerMeta and HttpActionMeta will be null in functional routes.

Dynamic Request Parsing

You can now parse the HttpRequest using HttpRequestParser in any services:

class MyService {
  constructor(
    private request: HttpRequest,
    private requestParser: HttpRequestParser,
  ) {}

  method() {
    const url = this.request.getUrl();
    const [path, queries] = this.requestParser.parseUrl(url);
    // ...
  }
}

Method	Description
parseUrl	Extract a path and an object representing queries
parsePath	Extract the path parameters as an object
parseBody	Load the request body as an object

This is not really convenient because there are two providers need to be injected, and the result will not be deserialized or validated. Therefore, there is a higher-lever provider HttpRequestParsed for you, which will cache results and also deserialize/validate the result based on the type you provided:

class MyService {
  constructor(private request: HttpRequestParsed) {}

  method() {
    type PathParams = { id: number };
    const pathParams = this.request.getPathParams<PathParams>();
    // ...
  }
}

Method
getBody
getQueries
getPathParams

Dynamic Response for onAccessDenied

DeepKit doesn't allow developers to specify the response when jumping to the onAccessDenied state from other states in the HTTP workflow.

Now you can custom the response for onAccessDenied by:

@eventDispatcher.listen(httpWorkflow.onAuth)
onAuth(event: typeof httpWorkflow.onAuth.event) {
  const response = new HtmlResponse("Unauthorized", 401);
  event.injectorContext.set(HttpAccessDeniedResponse, response);
  event.accessDenied();
}

No Content Response

To send a No Content Response (204 response) you'll need to construct the response like new HtmlResponse("", 204) previously. Now this process is simplified via NoContentResponse:

@http.DELETE(":id")
delete() {
  // ...
  return new NoContentResponse();
}