@dikur/http

The http package provides decorators that map a class to a router, it consists of the following decorators:
- Class Decorators:
- Http
- Middleware
- Method Decorators:
- Get
- Post
- Patch
- Put
- Delete
- Middleware
- Parameter Decoators:
- Context
- Body
- Param
- Query
- Static property decorators:
- NestedRouter

Example Usage:
``ts
@Middleware(authGuard)
@Http("/users")
class UserController {

@Get("/")
getUsers(@Context() ctx: Ctx, @Query(PageQuerySchema) {page, size}: PageQuerySchema) {
let result = await users.paginate({page, size});
return ctx.json({data: result});
}

@Patch("/:id")
updateUsers(
@Context() ctx: Ctx,
@Param(IdParamSchema): {id}: IdParamSchema,
@Body(UserUpdateSchema) data: UserUpdateSchema
) {
await users.update(id, data);
return ctx.json({message: "user updated successfully"})
}
}
`

Class Decorators

$3

function Http(basePath?: string): ClassDecorator
Maps the class to a router, it takes a single parameter, basePath.
which is prefixed to all other routes defined in the class.

$3

function Middleware(handler: MiddlewareHandler | (...args: any[]) => Promise): ClassOrMethodDecorator
Registers a middleware function to the router or route, it takes any kind of function as the middleware signature
depends on the specific router implementation.
While less type safe, this allows existing router middleware libraries to be used as is.

Method Decorators

$3

function Get|Post|Patch|Put|Delete: MethodDecorator
Registers the method as a route handler on the router set by the Http decorator.
It takes a a single optional parameter, path, which if not provided, will have the method name be used instead.
`ts
class {
@Get()
async getUsers() {} // path is "/getUsers"
}
`
The path is passed to the router as is, so in case you which to use path parameters, use the same syntax your router uses
e.g: express: get('/:id') // req.params: { id: string };

$3

Identical to the class decorator, but applied to only a specific route.
`ts
class {
// this route does not have the middleware applied
@Get()
async getProducts() {}

// but this one does
@Middleware(authGuard)
@Post()
async addProduct() {}
}
`

Parameter Decorators

Parameter decorators are used to inject values into the route handlers assigned using method decorators like Get and Post.
Aside from telling Dikur which parameters are in use and what order they are in, they can also be used for validation and documentation.

$3

function Context(): ParameterDecorator
Injects the handler context in the decorated parameter's stead, the actual value will depend on the router implementation.
Whatever the router passes to their route handlers will be included in the context object.
- For Hono it will inject the Context object.
- For Express it will inject an object containing the request, response and next parameters.

$3

function Body(schema?: Schema, mediatype?: "json" | "form"): ParameterDecorator
Injects the request's body in the decorated parameter's stead, it accepts two optional parameters:
- schema: a JSON schema, used with Ajv for validating the response
- mediaType: specifies whether it's a JSON or FormData, defaults to JSON
- no-op, adapters currently parse based on headers, but it's used by the openapi doc generator.

$3

function Param | Query: ParameterDecorator
Injects the entire request's path parameter or query object in the decorated parameter's stead.
It accepts an optional schema parameter for validation.

Static Property Decorators

$3

function NestedRouter(): StaticPropertyDecorator`
Registers the static property as a nested router, expects the property to be another class that was decorated using the Http decorator.