MiddlewarePipeline

Overview

The MiddlewarePipeline is a singleton instance that manages the execution of global middleware functions in your Asimilation application. It provides a centralized way to add middleware that runs on every request.

import { MiddlewarePipeline } from '@asimilation/core';

MiddlewarePipeline is a singleton instance of MiddlewareManager. There is only one instance shared across your entire application.

Type Definition

class MiddlewareManager implements MiddlewareManagerI {
  addMiddleware(middleware: MiddlewareFunction | MiddlewareFunctionAsync): void
  run(
    req: ArgumentedIncomingMessageInterface,
    res: ArgumentedServerResponseInterface,
    callbackMidd: MiddlewareFunctionAsync | MiddlewareFunction
  ): Promise<{req: ArgumentedIncomingMessageInterface, res: ArgumentedServerResponseInterface}>
  runRouteMiddlewares(
    req: ArgumentedIncomingMessageInterface,
    res: ArgumentedServerResponseInterface,
    middlewareList: (MiddlewareFunction | MiddlewareFunctionAsync)[],
    callbackMidd: MiddlewareFunctionAsync | MiddlewareFunction
  ): {req: ArgumentedIncomingMessageInterface, res: ArgumentedServerResponseInterface}
}

Methods

addMiddleware()

Adds a global middleware function to the pipeline. Global middleware runs on every incoming request before any route-specific middleware or controllers.

middleware

MiddlewareFunction | MiddlewareFunctionAsync

required

The middleware function to add to the global pipeline.Type Signatures:

type MiddlewareFunction = (
  req: ArgumentedIncomingMessageAbc,
  res: ArgumentedServerResponseAbc,
  next: (error?: Error) => void
) => void

type MiddlewareFunctionAsync = (
  req: ArgumentedIncomingMessageAbc,
  res: ArgumentedServerResponseAbc,
  next: (error?: Error) => void
) => Promise<void>

return

void

This method does not return a value.

Example:

import { MiddlewarePipeline } from '@asimilation/core';

// Synchronous middleware
MiddlewarePipeline.addMiddleware((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

// Asynchronous middleware
MiddlewarePipeline.addMiddleware(async (req, res, next) => {
  await logToDatabase(req);
  next();
});

run()

This method is primarily used internally by the framework. You typically don’t need to call it directly.

Executes all global middleware in sequence, followed by a callback middleware.

req

ArgumentedIncomingMessageInterface

required

The incoming HTTP request object.

res

ArgumentedServerResponseInterface

required

The HTTP response object.

callbackMidd

MiddlewareFunction | MiddlewareFunctionAsync

required

A callback middleware to execute after all global middleware.

return

Promise<{req, res}>

Returns a promise that resolves to an object containing the request and response objects.

runRouteMiddlewares()

This method is primarily used internally by the framework. You typically don’t need to call it directly.

Executes route-specific middleware in sequence, followed by a callback middleware.

req

ArgumentedIncomingMessageInterface

required

The incoming HTTP request object.

res

ArgumentedServerResponseInterface

required

The HTTP response object.

middlewareList

(MiddlewareFunction | MiddlewareFunctionAsync)[]

required

Array of route-specific middleware functions to execute.

callbackMidd

MiddlewareFunction | MiddlewareFunctionAsync

required

A callback middleware to execute after all route middleware.

return

{req, res}

Returns an object containing the request and response objects.

Examples

Logging Middleware

import { MiddlewarePipeline, asi, url } from '@asimilation/core';

// Add global logging middleware
MiddlewarePipeline.addMiddleware((req, res, next) => {
  const start = Date.now();
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  
  next();
  
  const duration = Date.now() - start;
  console.log(`Request completed in ${duration}ms`);
});

url.addPath('/users', (req, res) => {
  res.sendJson({ users: [] }, 200);
});

asi.setup(3000, '');
asi.run();

Authentication Middleware

import { MiddlewarePipeline, asi, url } from '@asimilation/core';

// Global authentication check
MiddlewarePipeline.addMiddleware((req, res, next) => {
  const publicPaths = ['/login', '/register', '/health'];
  
  if (publicPaths.includes(req.url || '')) {
    next();
    return;
  }
  
  const token = req.headers.authorization;
  if (!token) {
    res.sendJson({ error: 'Unauthorized' }, 401);
    return;
  }
  
  // Validate token here
  next();
});

url.addPath('/users', (req, res) => {
  res.sendJson({ users: [] }, 200);
});

url.addPath('/login', (req, res) => {
  res.sendJson({ token: 'abc123' }, 200);
});

asi.setup(3000, '');
asi.run();

CORS Middleware

import { MiddlewarePipeline } from '@asimilation/core';

MiddlewarePipeline.addMiddleware((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  
  if (req.method === 'OPTIONS') {
    res.writeHead(204);
    res.end();
    return;
  }
  
  next();
});

Request Body Parser

import { MiddlewarePipeline } from '@asimilation/core';

MiddlewarePipeline.addMiddleware(async (req, res, next) => {
  if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
    const chunks: Buffer[] = [];
    
    req.on('data', (chunk) => {
      chunks.push(chunk);
    });
    
    req.on('end', () => {
      const body = Buffer.concat(chunks).toString();
      
      try {
        (req as any).body = JSON.parse(body);
      } catch (error) {
        (req as any).body = body;
      }
      
      next();
    });
  } else {
    next();
  }
});

Multiple Middleware

import { MiddlewarePipeline, asi, url } from '@asimilation/core';

// Middleware 1: Request ID
MiddlewarePipeline.addMiddleware((req, res, next) => {
  (req as any).requestId = Math.random().toString(36).substring(7);
  next();
});

// Middleware 2: Logging
MiddlewarePipeline.addMiddleware((req, res, next) => {
  const requestId = (req as any).requestId;
  console.log(`[${requestId}] ${req.method} ${req.url}`);
  next();
});

// Middleware 3: CORS
MiddlewarePipeline.addMiddleware((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', '*');
  next();
});

// Middleware 4: Authentication
MiddlewarePipeline.addMiddleware((req, res, next) => {
  const publicPaths = ['/login', '/health'];
  if (publicPaths.includes(req.url || '')) {
    next();
    return;
  }
  
  const token = req.headers.authorization;
  if (!token) {
    res.sendJson({ error: 'Unauthorized' }, 401);
    return;
  }
  
  next();
});

url.addPath('/users', (req, res) => {
  const requestId = (req as any).requestId;
  res.sendJson({ requestId, users: [] }, 200);
});

asi.setup(3000, '');
asi.run();

Execution Order

Middleware executes in the following order:

Global middleware (added via MiddlewarePipeline.addMiddleware())
Route-specific middleware (defined in PathKwargs.handlers)
Controller function (the route handler)

import { MiddlewarePipeline, url } from '@asimilation/core';

// 1. Runs first (global)
MiddlewarePipeline.addMiddleware((req, res, next) => {
  console.log('Global middleware');
  next();
});

// 2. Runs second (route-specific)
const routeMiddleware = (req, res, next) => {
  console.log('Route middleware');
  next();
};

// 3. Runs last (controller)
url.addPath('/users', (req, res) => {
  console.log('Controller');
  res.sendJson({ users: [] }, 200);
}, {
  handlers: [routeMiddleware]
});

// Output:
// Global middleware
// Route middleware
// Controller

Best Practices

Always call next() in your middleware unless you want to stop the request processing (e.g., for authentication failures).

If you send a response in middleware (e.g., res.sendJson()), do NOT call next() afterward, as this will continue processing and may cause errors.

// Good: Send response and return
MiddlewarePipeline.addMiddleware((req, res, next) => {
  if (!authorized) {
    res.sendJson({ error: 'Unauthorized' }, 401);
    return; // Don't call next()
  }
  next();
});

// Bad: Calling next() after sending response
MiddlewarePipeline.addMiddleware((req, res, next) => {
  if (!authorized) {
    res.sendJson({ error: 'Unauthorized' }, 401);
    next(); // This will cause errors!
  }
});

Middleware Types

Middleware function type definitions

PathKwargs

Route-specific middleware configuration

url

Adding routes with middleware

Core API

Types

Overview

Type Definition

Methods

addMiddleware()

run()

runRouteMiddlewares()

Examples

Logging Middleware

Authentication Middleware

CORS Middleware

Request Body Parser

Multiple Middleware

Execution Order

Best Practices

Middleware Types

PathKwargs

url

Build docs developers (and LLMs) love

Core API

Types

Documentation Index

​Overview

​Type Definition

​Methods

​addMiddleware()

​run()

​runRouteMiddlewares()

​Examples

​Logging Middleware

​Authentication Middleware

​CORS Middleware

​Request Body Parser

​Multiple Middleware

​Execution Order

​Best Practices

​Related

Middleware Types

PathKwargs

url

Build docs developers (and LLMs) love

Overview

Type Definition

Methods

addMiddleware()

run()

runRouteMiddlewares()

Examples

Logging Middleware

Authentication Middleware

CORS Middleware

Request Body Parser

Multiple Middleware

Execution Order

Best Practices

Related