@phila/philaroute

philaroute

A lightweight, composable HTTP router for Node.js Lambda/API Gateway environments, written in TypeScript. Supports composable middleware pipelines and CORS out of the box.

Features

• TypeScript-first API
• Simple route and method registration
• Middleware pipeline support
• Built-in CORS support for Lambda/API Gateway
• Easily testable and extendable

Getting Started

Installation

npm install philaroute

Usage Example

Philaroute revolves around the usage of pipelines to composably and easily manage different routes and controllers. Parsing and response are built in. Effectively, you need to supply an array of functions that utilize the following type:

export type RestAccumulator = {
    request?: {
        params?: {
            [key: string]: string
        },
        body?: any,
        headers?: {
            [key: string]: string
        },
        mvHeaders?: {
            [key: string]: string[]
        },
    }
    data?: {
        [key: string]: any
    },
    response: {
        statusCode?: number,
        headers?: {
            [key: string]: string
        },
        isBase64Encoded?: boolean,
        body?: string | Record<string, any> | any[]
    }
};

type RestPipelineFn = (acc: RestAccumulator): Promise<RestAccumulator>

import { Router, http } from 'philaroute';
const { HttpStatus } = http;

const router = Router({ cors: { 'Access-Control-Allow-Origin': '*' } });
const world = router.path('/hello');

world.get([
  http.set({
     body: 'Hello World!'
  })
]);

// In your Lambda handler:
export const main = async (event) => {
  return router.routeToPath(event);
};

Advanced pipeline example

import { validate } from './validate';
import { opensearch } from './opensearch';

const router = Router();
const page = router.path('page')

page.get([
  validate.pageName,
  validate.userToken,
  opensearch.search(['search, vector']), // does relevant logic to search two different collections in paralle, puts data into acc.data. 
  opensearch.rank, // ranks search results, applies to acc.response.body
  // Can use http.set to customize response; otherwise acc.response.body will be preferentially returned, acc.data otherwise. 
]);

---

## CORS

CORS headers can be set globally when creating the router or updated later:

```typescript
const worldRouter = router({
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
});

Development

• Build: npm run build
• Test: npm test
• Lint: npm run lint
• Format: npm run format

License

MIT © City of Philadelphia

Documentation

For more information, see the Official Project Documentation.