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.

Dynamic routes allow you to capture parameters from the URL path, enabling you to build flexible and data-driven endpoints.

​
Basic Dynamic Route Syntax

Define dynamic parameters using angle brackets with a type and name: 
import { url } from '@asimilation/core';

url.addPath('/users/<int:id>', (req, res) => {
  const userId = req.params.id;
  res.sendJson({ userId, message: `Fetching user ${userId}` }, 200);
});
Dynamic parameters are accessible via req.params (see src/core/router-manager.ts:137).

​
Available Parameter Types

Asimilation supports multiple parameter types, each with built-in validation: 
// Matches: /users/1, /users/42, /users/999
// Does NOT match: /users/abc, /users/1.5
url.addPath('/users/<int:id>', (req, res) => {
  const id = req.params.id; // "1", "42", "999"
  res.sendJson({ userId: id }, 200);
});
Parameter values are always strings. Parse them to the appropriate type in your handler:
const id = parseInt(req.params.id, 10);
const enabled = req.params.enabled === 'true';

​
Parameter Type Reference

The available parameter types are defined in src/enums/param-type.ts:1-34:
TypeSyntaxPatternExample
int<int:name>\d+123, 0, 999
string<string:name>[a-zA-Z]+hello, World
slug<slug:name>[a-z0-9-]+my-post, article-2024
boolean<boolean:name>(true|false)true, false

​
Multiple Parameters

Capture multiple parameters in a single route: 
url.addPath('/users/<int:userId>/posts/<int:postId>', (req, res) => {
  const { userId, postId } = req.params;
  
  res.sendJson({
    message: `Fetching post ${postId} from user ${userId}`,
    userId,
    postId
  }, 200);
});

// Matches: /users/5/posts/42
// req.params = { userId: "5", postId: "42" }

​
Mixing Static and Dynamic Segments

Combine static path segments with dynamic parameters: 
url.addPath('/api/v1/users/<int:id>/profile', (req, res) => {
  const userId = req.params.id;
  res.sendJson({ userId, profile: {} }, 200);
});

// Matches: /api/v1/users/123/profile
// Does NOT match: /api/v1/users/abc/profile

​
Accessing Route Parameters

Route parameters are available on the request object after middleware execution: 
url.addPath('/articles/<slug:slug>', (req, res) => {
  // Access all parameters
  console.log(req.params); // { slug: "my-article" }
  
  // Access specific parameter
  const slug = req.params.slug;
  
  // Validate and use
  if (!slug) {
    res.sendJson({ error: 'Slug is required' }, 400);
    return;
  }
  
  res.sendJson({ article: { slug } }, 200);
});

​
Parameter Validation

While type validation is automatic, you can add custom validation: 
url.addPath('/users/<int:id>', (req, res) => {
  const id = parseInt(req.params.id, 10);
  
  // Custom validation
  if (id < 1 || id > 10000) {
    res.sendJson({ error: 'Invalid user ID range' }, 400);
    return;
  }
  
  res.sendJson({ userId: id }, 200);
});

​
Route Matching Process

Asimilation uses a two-step matching process:
1

Check static routes first

The router first checks if the URL matches any static route exactly:
// Static route (checked first)
url.addPath('/users/new', handler1);
2

Match dynamic routes

If no static route matches, dynamic routes are tested using compiled regex patterns:
// Dynamic route (checked second)
url.addPath('/users/<int:id>', handler2);
3

Extract parameters

When a dynamic route matches, named capture groups extract the parameters:
// URL: /users/42
// Regex: ^/users/(?<id>\d+)$
// Result: req.params = { id: "42" }
Static routes always take precedence over dynamic routes (see src/core/router-manager.ts:95-101).

​
How Dynamic Routes Work

Under the hood, Asimilation compiles dynamic routes into regular expressions:
  1. Pattern Detection: The framework checks if a path contains type parameters (see src/helpers/url-regex.ts:4-7)
  2. Parameter Extraction: Parameter names are extracted from the path (see src/helpers/url-regex.ts:25-36)
  3. Regex Compilation: The path is compiled into a regex pattern with named capture groups (see src/helpers/url-regex.ts:56-63)
  4. Route Matching: Incoming URLs are tested against the compiled patterns (see src/core/router-manager.ts:55-60)
// Your route definition:
url.addPath('/users/<int:id>/posts/<slug:slug>', handler);

// Compiled to regex:
// ^/users/(?<id>\d+)/posts/(?<slug>[a-z0-9-]+)$

// Matches:
// ✓ /users/42/posts/my-post
// ✗ /users/abc/posts/my-post (id must be integer)
// ✗ /users/42/posts/My-Post (slug must be lowercase)

​
Common Patterns

// List all users
url.addPath('/users', listUsers, { methods: ['GET'] });

// Get specific user
url.addPath('/users/<int:id>', getUser, { methods: ['GET'] });

// Update user
url.addPath('/users/<int:id>', updateUser, { methods: ['PUT'] });

// Delete user
url.addPath('/users/<int:id>', deleteUser, { methods: ['DELETE'] });

​
Error Handling

When a parameter type doesn’t match, the route won’t be selected: 
url.addPath('/users/<int:id>', (req, res) => {
  res.sendJson({ userId: req.params.id }, 200);
});

// Request: GET /users/abc
// Result: 404 Not Found (route doesn't match)

// Request: GET /users/123
// Result: 200 OK (route matches)
If an undefined parameter type is used, Asimilation throws a TypeIsNotDefined error at startup (see src/exceptions/domain/url-regex.ts:1-7).

​
Best Practices

1

Choose appropriate types

Use the most restrictive type that fits your data:
// Good: Specific type for IDs
url.addPath('/users/<int:id>', handler);

// Less ideal: Too permissive
url.addPath('/users/<string:id>', handler);
2

Validate parameter values

Add business logic validation beyond type checking:
const id = parseInt(req.params.id, 10);
if (id < 1) {
  res.sendJson({ error: 'ID must be positive' }, 400);
  return;
}
3

Use descriptive parameter names

// Good
url.addPath('/users/<int:userId>/posts/<int:postId>', handler);

// Unclear
url.addPath('/users/<int:id1>/posts/<int:id2>', handler);
4

Document expected formats

If using slugs or strings, document the expected format:
// Slug format: lowercase letters, numbers, hyphens only
// Example: "my-blog-post-2024"
url.addPath('/posts/<slug:slug>', handler);

​
What’s Next?

Middleware Pipeline

Add middleware to validate parameters and enhance routes

Error Handling

Learn how to handle validation errors and 404s

Build docs developers (and LLMs) love

Get started for freeTalk to us