edge-master v0.9.3

EdgeMaster is a flexible microframework designed to handle routing and intercept requests/responses in cloud based environments such, as Cloudflare Workers or serverless functions. It offers a robust set of tools that can greatly simplify the development of your edge applications.

Table of Contents

• Features
• Installation
• Getting Started
• Routing
• Interceptors
• Examples
• Contributing
• Credits

Features

• Lightweight: EdgeMaster is incredibly small in size, allowing you to keep your application's footprint minimal.
• Fully-Typed: Enjoy the benefits of TypeScript with complete type definitions.
• Simplified Routing: Create concise and expressive routes with ease.
• Interception Support: Implement interceptors for Request/Response effortlessly, whether built-in or custom.
• Platform-Agnostic: Functions seamlessly in diverse cloud-based environments such as Cloudflare Workers and serverless platforms, while providing full compatibility with the Fetch API.
• Error Handling: Gracefully handle errors and define error responses.

Installation

To get started with EdgeMaster, you can install it via npm:

npm install edge-master

Getting Started

Here's a simple example of setting up EdgeMaster in a Cloudflare Worker module:

import {
  EdgeController,
  RouteHandler,
  Task,
  routePattern,
  initResponse
} from 'edge-master';

// Cloudflare Worker
export default {
  async fetch(req) {
    return EdgeApp.handleRequest({ req });
  },
}

const EdgeApp = new EdgeController();

EdgeApp.addRoute(
  routePattern('*/users/profile/*'),
  new RouteHandler().registerTask(new Task({
    do: async ({ req }) => {
      const tempRes = await fetch(req);
      // some transform on response
      return new Response(tempRes.body, {
        ...tempRes,
        headers: {
          ...tempRes.headers,
          'My-Res-Status': 'transformed'
        }
      });
    }
  }))
);

EdgeApp.addRoute(
  routePattern('*'),
  new RouteHandler().registerTask(initResponse())
);

Routing

EdgeMaster streamlines routing in your application with built-in route matchers, and we're continually adding more. If your project requires custom, intricate route matching, you can easily implement it with the flexibility our framework offers. At EdgeMaster, we aim to make complex route matching straightforward and accessible for developers.

import {
  EdgeController,
  routePattern, // You can use wildcards and optional segments to create flexible route patterns.
  pathStartWith,
  urlStartWith,
} from 'edge-master';

const App = new EdgeController();

App.addRoute(routePattern('*/user/*/info'), {/** RouteHandler of UserInfo  */});

App.addRoute(pathStartWith('/api/v2/user'), {/** RouteHandler of User  */});

App.addRoute(urlStartWith('https://origin.com/api/v2/user'), {/** RouteHandler of User  */});

// This handler will be executed when none of the other registered routes don't match the request.
App.addRoute(() => true, {/** RouteHandler of Default or Non-matching routes */});

Custom Route Matcher

EdgeMaster allows you to define your own route matcher.

type Matcher = (req: Request) => boolean;

const onlyGetMethod = (matcher: Matcher): Matcher => {
  return (req) => (req.method === "GET" && matcher(req))
}

App.addRoute(
  onlyGetMethod(routePattern('*/some/*/wildcard')),
  {/** RouteHandler */ }
);

Interceptors

EdgeMaster provides a convenient way to intercept incoming requests and outgoing responses using interceptors. Interceptors can be used for tasks such as authentication, logging, and response modification.

Request Interceptors

Request interceptors are executed before your route handlers, allowing you to modify the incoming request.

const authenticationInterceptor = {
  type: InterceptorType.Request,
  async intercept(context) {
    // Check authentication and modify the request if needed
    const { reqCtx: { req }, responder } = context;
    if (/** req is ok*/)
      return req;
    else
      // responder will break all next steps and respond instnatly the request.
      responder(new Response('Not Authenticated', { status: 401 }))
  },
};

router.addInterceptor(authenticationInterceptor);

Response Interceptors

Response interceptors are executed after your route handlers, enabling you to modify the response before it's sent back to the client.

const loggingInterceptor = {
  type: InterceptorType.Response,
  async intercept(context) {
    // Log the response or make changes before sending it
    const { res } = context;
    // ...
    return res;
  },
};

router.addInterceptor(loggingInterceptor);

Examples

Check out more examples and use cases in the EdgeMaster Examples.

Contributing

We welcome contributions from the community to make EdgeMaster even better. If you'd like to contribute, please follow these steps:

1. Fork the repository.
2. Install dependencies npm install.
3. Start the test runner npm run test.
4. Add your code and tests.
5. Commit your changes && Submit a pull request.

We'll review your contribution and, if

everything looks good, merge it into the main codebase.

Credits

EdgeMaster is developed and maintained by Sharif Eiri. It's inspired by the simplicity of microframeworks like Express.js and is built to be highly compatible with cloud-based serverless environments. Special thanks to the open-source community for their contributions and support.

Thank you for choosing EdgeMaster for your edge application development! If you have any questions or encounter issues, please don't hesitate to reach out on our GitHub repository.

Happy coding! 🚀