@armscye/express NPM

@armscye/express

A collection of shared standard TypeScript definitions (@express).

Installation

Using npm:

npm install --save-dev @armscye/express

or using yarn:

yarn add @armscye/express --dev

Reference

NotchHandler `Interface`

Handles a server request and produces a response.

interface NotchHandler<TRequest = any, TResponse = any> {
  handle(req: TRequest, res: TResponse, next?: any): any;
}

The handle method is the heart of the NotchHandler. It takes three arguments:

req: This represents the incoming HTTP request.
res: This represents the response object that will be sent back to the client.
next (optional): Allows the handler to delegate further processing to the next middleware in the chain if necessary.

Usage notes

Here's a basic example demonstrating how to use a NotchHandler to handle a HTTP request and return a simple response:

class MyHandler implements NotchHandler {
  handle(req: any, res: any) {
    // Access request details:
    const method = req.method;
    const url = req.url;
    const headers = req.headers;

    // Perform any necessary logic...

    // Return a response:
    return res.status(200).json({ message: 'Hello from the handler!' });
  }
}

NotchMiddleware `Interface`

Participant in processing a server request and response.

interface NotchMiddleware<TRequest = any, TResponse = any> {
  process(req: TRequest, res: TResponse, next?: any): any;
  process(err: any, req: TRequest, res: TResponse, next?: any): any;
}

The process method in the NotchMiddleware is responsible for handling incoming server requests and participating in the overall request-response cycle. The method takes three main arguments:

req: This represents the incoming HTTP request.
res: This represents the response object that will be sent back to the client.
next (optional): Allows passing control to the next middleware in a chain or to the final request handler.

Some middleware implementations might also handle errors. They receive an additional err argument before the req, res, and next arguments. This allows them to:

Log the error for debugging purposes.
Send an appropriate error response to the client.
Call next() to pass the error to the next middleware for further handling.

Usage notes

Here's a basic example demonstrating how to use a NotchMiddleware for authentication:

class AuthMiddleware implements NotchMiddleware {
  process(req, res, next) {
    // Extract authentication token from request headers
    const token = req.headers.authorization;

    // Validate token (replace with actual validation logic)
    if (isValidToken(token)) {
      // User is authenticated, proceed to the next middleware or handler
      next();
    } else {
      // Unauthorized access, send error response
      res.status(401).json({ message: 'Unauthorized' });
    }
  }
}

Response Generator `Interface`

Describes the interface for composing and sending HTTP responses.

interface ResponseGenerator {
  reply(response: any, body: any, statusCode?: number): any;
}

The reply method within the ResponseGenerator is responsible for the final step in crafting and delivering an HTTP response to the client. The method takes three arguments:

response: An object representing the in-flight response.
body: The actual content of the response, which can be:
- A string representing text or HTML.
- An object that will be serialized to JSON (e.g., for sending data).
- Any other supported data type.
statusCode (optional): A numeric HTTP status code (e.g., 200 for success, 404 for not found). If not provided, a default status code might be used.

Usage notes

Here's an example of how to use ResponseGenerator to send a simple JSON response:

class MyResponseGenerator implements ResponseGenerator {
  reply(response, body, statusCode) {
    response.setHeader('Content-Type', 'application/json');
    if (statusCode) {
      response.end(
        JSON.stringify({
          message: 'Hello from the server!',
          status: statusCode,
        }),
      );
    } else {
      response.end(JSON.stringify({ message: 'Hello from the server!' }));
    }
  }
}