Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juanjh1/asimilation/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The RouteModule class allows you to organize routes hierarchically with shared path prefixes. It’s perfect for structuring API versions, grouping related endpoints, or creating modular route configurations. 
import { RouteModule, url } from '@asimilation/core';

​
Type Definition

class RouteModule {
  constructor(manager: RouteManager, nameSpace: string)
  addPath(path: string, callback: Controller, kwargs?: PathKwargs): void
  createRouteModule(name: string): RouteModule
}

​
Creating Route Modules

There are two ways to create a RouteModule:

​
1. Using url.createRouteModule()

This is the recommended approach for creating route modules.
import { url } from '@asimilation/core';

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

​
2. Direct Instantiation

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

// Not recommended - use url.createRouteModule() instead
const apiV1 = new RouteModule(url, '/api/v1');

​
Constructor

​
manager
RouteManager
required
The route manager instance that will handle the routes.
​
nameSpace
string
required
The base path prefix for all routes in this module. Automatically normalized.

​
Methods

​
addPath()

Registers a route within the module’s namespace. The path is automatically prefixed with the module’s base path.
​
path
string
required
The relative path for the route. Will be combined with the module’s base path.
​
callback
Controller
required
The controller function to handle requests to this route.Type:
(req: ArgumentedIncomingMessageAbc, res: ArgumentedServerResponseAbc) => void
​
kwargs
PathKwargs
Optional configuration for the route.Properties:
  • methods?: string[] - HTTP methods allowed for this route
  • handlers?: MiddlewareFunction[] - Route-specific middleware
​
return
void
This method does not return a value.
Example: 
const apiV1 = url.createRouteModule('/api/v1');

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

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

​
createRouteModule()

Creates a nested route module with a combined path prefix.
​
name
string
required
The path segment to append to the current module’s base path.
​
return
RouteModule
A new RouteModule instance with the combined path prefix.
Example: 
const api = url.createRouteModule('/api');
const v1 = api.createRouteModule('/v1');
const v2 = api.createRouteModule('/v2');

v1.addPath('/users', handler); // /api/v1/users
v2.addPath('/users', handler); // /api/v2/users

​
Examples

​
Basic Module Usage

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

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

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

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

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

​
Nested Modules

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

// Create base API module
const api = url.createRouteModule('/api');

// Create version modules
const v1 = api.createRouteModule('/v1');
const v2 = api.createRouteModule('/v2');

// V1 routes
v1.addPath('/users', (req, res) => {
  // /api/v1/users
  res.sendJson({ version: '1.0', users: [] }, 200);
});

// V2 routes with new features
v2.addPath('/users', (req, res) => {
  // /api/v2/users
  res.sendJson({ version: '2.0', users: [], metadata: {} }, 200);
});

​
Resource-Based Organization

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

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

// Users module
const users = api.createRouteModule('/users');
users.addPath('/', (req, res) => {
  // /api/users
  res.sendJson({ users: [] }, 200);
}, { methods: ['GET'] });

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

// Posts module
const posts = api.createRouteModule('/posts');
posts.addPath('/', (req, res) => {
  // /api/posts
  res.sendJson({ posts: [] }, 200);
}, { methods: ['GET'] });

posts.addPath('/:id/comments', (req, res) => {
  // /api/posts/:id/comments
  const { id } = req.params;
  res.sendJson({ postId: id, comments: [] }, 200);
}, { methods: ['GET'] });

​
Modular File Structure

routes/users.ts 
import { RouteModule } from '@asimilation/core';

export function registerUserRoutes(module: RouteModule) {
  module.addPath('/', (req, res) => {
    res.sendJson({ users: [] }, 200);
  }, { methods: ['GET'] });

  module.addPath('/:id', (req, res) => {
    const { id } = req.params;
    res.sendJson({ id }, 200);
  }, { methods: ['GET'] });

  module.addPath('/', (req, res) => {
    res.sendJson({ success: true }, 201);
  }, { methods: ['POST'] });
}
routes/posts.ts 
import { RouteModule } from '@asimilation/core';

export function registerPostRoutes(module: RouteModule) {
  module.addPath('/', (req, res) => {
    res.sendJson({ posts: [] }, 200);
  }, { methods: ['GET'] });

  module.addPath('/:id', (req, res) => {
    const { id } = req.params;
    res.sendJson({ id }, 200);
  }, { methods: ['GET'] });
}
index.ts 
import { url, asi } from '@asimilation/core';
import { registerUserRoutes } from './routes/users';
import { registerPostRoutes } from './routes/posts';

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

const usersModule = api.createRouteModule('/users');
registerUserRoutes(usersModule);

const postsModule = api.createRouteModule('/posts');
registerPostRoutes(postsModule);

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

​
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 admin = url.createRouteModule('/admin');

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

admin.addPath('/settings', (req, res) => {
  res.sendJson({ settings: {} }, 200);
}, {
  methods: ['GET'],
  handlers: [authMiddleware]
});

​
Path Normalization

RouteModule automatically normalizes all paths by ensuring they start with / and removing trailing slashes.
const api = url.createRouteModule('/api/v1');

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

// All register as: /api/v1/users

​
Benefits

Organization

Group related routes together with shared path prefixes

Reusability

Create reusable route modules that can be mounted at different paths

Versioning

Easily manage multiple API versions with separate modules

Maintainability

Split route definitions across multiple files for better code organization

url

Main route manager for creating modules

Controller Type

Controller function signatures

PathKwargs Type

Route configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us