ALB Router

A user-friendly router for Amazon Application Load Balancer (ALB) paths. Quickly match URLs, extract parameters, and handle routing in Node.js or AWS environments.

Overview

• Powerful & Flexible: Leverages path-to-regexp for robust path matching.
• Easy ALB Integration: Ideal for Amazon AWS load balancer setups, but also applicable to any Node.js server handling URL routing.
• Lightweight: Designed to be minimal yet fully featured for route parsing and parameter extraction.
• TypeScript-Ready: Includes type definitions for seamless integration in TypeScript projects.

Table of Contents

1. Features
2. Installation
3. Usage
4. Examples
5. API Reference
6. Contributing
7. License

Features

• Dynamic Route Matching: Match complex patterns using path parameters and wildcards.
• AWS-Friendly: Specifically designed for Amazon AWS Application Load Balancer (ALB) routing rules.
• Parameter Extraction: Retrieve URL parameters for further processing.
• Method-Based Handlers: Organize your route handlers by HTTP method (e.g., GET, POST, PUT, DELETE).
• Zero Config: Start routing with minimal code changes—just define your routes.

Installation

Install via npm:

npm install alb-router

Or via yarn:

yarn add alb-router

Usage

Below is a quick example showing how to set up routes and extract parameters:

import { extractParams } from "alb-router";

const routes = [
  {
    pattern: "/users/:userId",
    methods: {
      GET: "getUserHandler",
      POST: "createUserHandler",
    },
  },
  {
    pattern: "/products/:category/:productId",
    methods: {
      GET: "getProductHandler",
    },
  },
];

const path = "/products/electronics/12345";
const method = "GET";

const { params, handler } = extractParams(path, method, routes);

console.log(params);
// Output: { category: "electronics", productId: "12345" }

console.log(handler);
// Output: "getProductHandler"

Tip: This function is particularly useful in AWS Lambda functions triggered by an ALB event where you need to parse the path from the event.

Examples

1. Simple Route Matching

import { extractParams } from "alb-router";

const routes = [
  {
    pattern: "/hello/:name",
    methods: {
      GET: "sayHello",
    },
  },
];

const path = "/hello/John";
const method = "GET";

const result = extractParams(path, method, routes);
console.log(result.params); // { name: "John" }
console.log(result.handler); // "sayHello"

2. Handling Multiple Methods

const routes = [
  {
    pattern: "/api/data",
    methods: {
      GET: "fetchData",
      POST: "createData",
      PUT: "updateData",
    },
  },
];

const getResult = extractParams("/api/data", "GET", routes);
console.log(getResult.handler); // "fetchData"

const postResult = extractParams("/api/data", "POST", routes);
console.log(postResult.handler); // "createData"

3. Nested or Wildcard Routes

const routes = [
  {
    pattern: "/files/*",
    methods: {
      GET: "fetchFiles",
    },
  },
];

const result = extractParams("/files/docs/2025/report.pdf", "GET", routes);
console.log(result.params); // { '0': 'docs/2025/report.pdf' }
console.log(result.handler); // "fetchFiles"

API Reference

extractParams(path: string, method: string, routes: Route[]): ExtractParamsResult

Arguments:

• path - The request path (e.g., "/users/123").
• method - The HTTP method (e.g., "GET", "POST").
• routes - An array of route definitions:

  export type Route = {
    pattern: string;
    methods: {
      [key: string]: string;
    };
  };

Returns:

export type ExtractParamsResult = {
  params: { [key: string]: string };
  handler: string | null;
};

• params - Captured route parameters.
• handler - The method handler if found, otherwise null.

Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check the issues page.

1. Fork the repository.
2. Create your feature branch: git checkout -b feature/my-new-feature.
3. Commit your changes: git commit -m "Add some feature".
4. Push to the branch: git push origin feature/my-new-feature.
5. Open a Pull Request.

If you find a bug or have a feature request, please create an issue describing it.

License

ISC © Nethsara
This project is not affiliated with or endorsed by Amazon or AWS. Amazon and AWS are registered trademarks of Amazon.com, Inc.

Keywords & Tags

alb, router, routing, amazon, aws, application-load-balancer, url-params, path-matching, nodejs, typescript, path-to-regexp

For more details, visit the GitHub repository. Happy routing!