Arika Dispatcher

@arikajs/dispatcher is the execution engine of the ArikaJS ecosystem.

Before the response is sent back to the client, this package handles the journey from route to result:

• Route handler resolution (Closures or Controllers)
• Dependency Injection for controllers
• Method invocation with parameter injection
• Middleware pipeline execution
• Response normalization

If the following works cleanly, the dispatcher is considered correct:

const dispatcher = new Dispatcher(container);
const response = await dispatcher.dispatch(matchedRoute, request, responseInstance);

Arika Dispatcher is to ArikaJS what illuminate/routing’s dispatcher is to Laravel: it takes a route and makes things happen.

Status

• Stage: Experimental / v0.x
• Scope (v0.x):
  • Controller & Closure resolution
  • Method parameter injection (Request + Route Params)
  • Basic middleware pipeline
  • Response normalization (String, Object, Response)
• Out of scope (for this package):
  • Route matching (see @arikajs/router)
  • Request parsing (see @arikajs/http)
  • Template rendering

The goal of this package is to be the reliable executor of application logic.

Features

• Handler Resolution

  • Support for basic closures: (req) => 'Hello'
  • Support for class-based controllers: [UserController, 'show']
  • Automatic instantiation of controllers via Service Container

• Method Invocation

  • Resolves method dependencies
  • Injects Request object automatically
  • Maps route parameters (e.g., {id}) to method arguments

• Middleware Pipeline

  • Executes route-specific middleware
  • Onion-style execution flow (nested next() calls)
  • Asynchronous middleware support
  • Container-based middleware resolution

• Response Normalization

  • Automatically converts return values to HTTP responses
  • Objects/Arrays → JSON response
  • Strings → Plain text response
  • null/undefined → 204 No Content

Installation

npm install @arikajs/dispatcher
# or
yarn add @arikajs/dispatcher
# or
pnpm add @arikajs/dispatcher

This package is written in TypeScript and ships with type definitions.

Quick Start

1. Simple Dispatching

import { Dispatcher } from '@arikajs/dispatcher';

const dispatcher = new Dispatcher();
const response = await dispatcher.dispatch(matchedRoute, request, response);

2. Using Controllers with DI

import { Dispatcher } from '@arikajs/dispatcher';
import { Container } from '@arikajs/foundation';

const container = new Container();
const dispatcher = new Dispatcher(container);

// Dispatch to [UserController, 'index']
const response = await dispatcher.dispatch(matchedRoute, request, response);

Dispatcher

The Dispatcher class is the central coordinator that manages the lifecycle of a request dispatch.

Core responsibilities:

• Resolves the handler (Closure or Controller)
• Manages the middleware pipeline
• Coordinates the invocation of the handler
• Ensures the return value is normalized into a Response

Minimal API:

class Dispatcher {
  constructor(container?: Container);

  setContainer(container: Container): this;
  dispatch(matchedRoute: MatchedRoute, request: Request, response: Response): Promise<Response>;
}

Typical usage:

import { Dispatcher } from '@arikajs/dispatcher';

const dispatcher = new Dispatcher(app.container);
const response = await dispatcher.dispatch(matched, request, response);

Middleware Pipeline

The MiddlewarePipeline executes middleware in an "onion" pattern, where each layer can perform logic before and after the next layer.

Minimal API:

pipeline.use(middleware);
pipeline.handle(request, destination);

Usage

const pipeline = new MiddlewarePipeline(container);

pipeline.use(async (req, next) => {
  const res = await next(req);
  res.header('X-Processed-By', 'Arika');
  return res;
});

Response Resolver

The ResponseResolver ensures that your controller methods can stay clean by returning plain data.

Conversion Rules:

• Objects: Automatically converted to JSON via response.json()
• Strings/Buffers: Sent as the body via response.send()
• null/undefined: Sets status 204 (No Content)
• Response: Returned as-is

Project Structure (recommended)

Inside the arika-dispatcher repository:

• src/
  • Dispatcher.ts – Main coordinator
  • ControllerResolver.ts – DI-aware handler resolution
  • MethodInvoker.ts – Dynamic method execution
  • ResponseResolver.ts – Logic for normalizing return values
  • MiddlewarePipeline.ts – The execution stack for middleware
  • index.ts – Public exports

Versioning & Stability

• While in v0.x, the API may change between minor versions.
• Once the API stabilizes, @arikajs/dispatcher will move to v1.0 and follow semver strictly.

Contributing

Contributions are welcome, especially around:

• Advanced dependency injection in controller methods
• Performance optimizations for middleware execution
• Enhanced error handling hooks
• Support for attribute-based routing

Before submitting a PR:

• Run the test suite
• Add tests for any new behavior
• Keep the public API focused and well-documented

License

@arikajs/dispatcher is open-sourced software licensed under the MIT license.

Philosophy

“Routing decides the path. Dispatcher executes the journey.”