url

Route manager for registering HTTP routes and handlers

Overview

The url object is the main route manager for registering HTTP routes in your Asimilation application. It provides methods to define routes with controllers and optional middleware.

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

The url object is a singleton instance of RouteManagerI returned from asi.urlManager().

Type Definition

interface RouteManagerI {
  addPath(url: string, callback: Controller, kwargs?: PathKwargs): void
  createRouteModule(initialPath: string): RouteModule
}

Methods

addPath()

Registers a new route with a controller function and optional configuration.

url · string · required

The URL path for the route. Supports static paths like /users and dynamic paths like /users/:id.

Dynamic Parameters:

• Use :paramName syntax for path parameters
• Parameters are accessible via req.params.paramName

callback · Controller · required

The controller function to handle requests to this route.

Type:

(req: ArgumentedIncomingMessageAbc, res: ArgumentedServerResponseAbc) => void

kwargs · PathKwargs

Optional configuration object for the route.

Properties:

• methods?: string[] - HTTP methods allowed for this route (e.g., ['GET', 'POST'])
• handlers?: MiddlewareFunction[] - Route-specific middleware functions

return · void

This method does not return a value.

Examples

Basic Route

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

url.addPath('/hello', (req, res) => {
  res.sendText('Hello, World!', 200);
});

Dynamic Route with Parameters

url.addPath('/users/:id', (req, res) => {
  const userId = req.params.id;
  res.sendJson({ userId, name: 'John Doe' }, 200);
});

url.addPath('/posts/:postId/comments/:commentId', (req, res) => {
  const { postId, commentId } = req.params;
  res.sendJson({ postId, commentId }, 200);
});

Route with HTTP Methods

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

url.addPath('/users', (req, res) => {
  // Create new user
  res.sendJson({ success: true }, 201);
}, {
  methods: ['POST']
});

Route with Middleware

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

const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization;
  if (!token) {
    res.sendJson({ error: 'Unauthorized' }, 401);
    return;
  }
  next();
};

const logMiddleware = (req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
};

url.addPath('/protected', (req, res) => {
  res.sendJson({ data: 'Protected content' }, 200);
}, {
  methods: ['GET'],
  handlers: [logMiddleware, authMiddleware]
});

Multiple Routes

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

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

// Get specific user
url.addPath('/users/:id', (req, res) => {
  const { id } = req.params;
  res.sendJson({ id, name: 'John' }, 200);
}, { methods: ['GET'] });

// Create user
url.addPath('/users', (req, res) => {
  res.sendJson({ success: true }, 201);
}, { methods: ['POST'] });

// Update user
url.addPath('/users/:id', (req, res) => {
  const { id } = req.params;
  res.sendJson({ id, updated: true }, 200);
}, { methods: ['PUT', 'PATCH'] });

// Delete user
url.addPath('/users/:id', (req, res) => {
  const { id } = req.params;
  res.sendJson({ id, deleted: true }, 200);
}, { methods: ['DELETE'] });

Path Normalization

Asimilation automatically normalizes paths by ensuring they start with / and removing trailing slashes.

// These are all equivalent:
url.addPath('/users', handler);
url.addPath('users', handler);   // Normalized to '/users'
url.addPath('/users/', handler); // Normalized to '/users'

Dynamic Path Parameters

Dynamic segments in paths are defined using the :paramName syntax:

url.addPath('/api/:version/users/:userId', (req, res) => {
  const { version, userId } = req.params;
  res.sendJson({ version, userId }, 200);
});

// Matches: /api/v1/users/123
// req.params = { version: 'v1', userId: '123' }

createRouteModule()

Creates a route module for organizing routes with a common prefix.

initialPath · string · required

The base path prefix for all routes in the module.

return · RouteModule

A new RouteModule instance with the specified prefix.

Example:

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

const apiV1 = url.createRouteModule('/api/v1');

apiV1.addPath('/users', (req, res) => {
  // Registered as /api/v1/users
  res.sendJson({ users: [] }, 200);
});

See the RouteModule documentation for more details.

Related

Controller Type

Learn about controller function signatures

PathKwargs Type

Route configuration options

RouteModule

Organize routes with modules

Middleware

Middleware function types