EAPI for Edge API, or Extremelly Awesome Programming Interface, you decide 😎
It's a collection of common building blocks you can use to build scalable and composable API at the Edge using Cloudflare Workers and TypeScript.
While EAPI packages are meant to work together with p-j/worker-eapi-template, you can also use them as standalone functions as demonstrated below.
| Package | Description | Version | Changelog |
|---|---|---|---|
@p-j/eapi-middleware-cache |
Configure browser & CDN cache | ||
@p-j/eapi-middleware-cors |
Validate Origin & Apply CORS Headers | ||
@p-j/eapi-middleware-errorhandler |
Catch exceptions, forward them or print them | ||
@p-j/eapi-middleware-redirect |
Redirect, Rewrite or Proxy Requests | ||
@p-j/eapi-middleware-headers |
Add/Remove headers on Request & Response | ||
@p-j/eapi-util-applymiddlewares |
A utility to combine multiple middlewares | ||
@p-j/eapi-util-fetcheventhandler |
Apply global middlewares & Match Routes | ||
@p-j/eapi-types |
Common TypeScript typings for EAPI projects |
eapi-middleware-* packages are providing Middleware Factory, that, given a number of options, will return actual Middlewares functions.
The middlewares functions can then be applied to the request handler middlware(requestHandler) and returns an enhanced request handler.
The type definitions can help you better understand how things work together.
That's the recommended way of using this middlewares as it was built with this integration in mind.
This example is already setup in @p-j/worker-eapi-template
// src/router.ts import { Router } from 'tiny-request-router' import { withCache } from '@p-j/eapi-middleware-cache' import { withErrorHandler } from '@p-j/eapi-middleware-errorhandler' import { applyMiddlewares } from '@p-j/eapi-util-applymiddlewares' const TTL_30MINUTES = 60 * 30 function requestHandler({ event, request, params }: RequestContext): Response { return new Response('Hello World!') } /** * Route definitions */ export const router = new Router() router.all( '/', applyMiddlewares( requestHandler, withErrorHandler({ enableDebug: true }), withCache({ cacheControl: `public, max-age=${TTL_30MINUTES}`, cdnTtl: TTL_30MINUTES, }), ), ) // The router is then used to match request in the src/index.ts
Combining some of the EAPI tools while not embracing the whole template, you can build an extensible setup that allow you to easily apply a variaty of middlewares.
import { withCache } from '@p-j/eapi-middleware-cache' import { applyMiddlewares } from '@p-j/eapi-util-applymiddlewares' import { withAwesomeMiddleware } from './withAwesomeMiddleware' function requestHandler({ event, request, params }: RequestContext): Response { return new Response('Hello World!') } addEventListener('fetch', (event) => { const requestContext = { event, request: event.request, params: {} } // apply all the middlewares on top of the original handler const handler = applyMiddlewares( requestHandler, withCache({ cacheControl: 'public, max-age=3600', cdnTtl: 3600, }), withAwesomeMiddleware(), ) // use the enhanced handler to respond event.respondWith(handler(requestContext)) })
While this middleware is intended to be used with @p-j/worker-eapi-template, you can also make use of it without any other EAPI dependency.
import { withCache } from '@p-j/eapi-middleware-cache' function requestHandler({ event, request, params }: RequestContext): Response { return new Response('Hello World!') } // withCache is a Middleware Factory, here we get back a "pre configured" middleware const cacheForOneHour = withCache({ cacheControl: 'public; max-age=3600' }) // apply the middleware to the request handler const finalRequestHandler = cacheForOneHour(requestHandler) addEventListener('fetch', (event) => { // The only constraints is that the RequestHandler needs to take in a RequestContext const requestContext = { event, request: event.request, params: {} } // use the enhanced request handler to build the response event.respondWith(finaleRequestHandler(requestContext)) })
@p-j/eapi-middleware-cache@p-j/eapi-middleware-cors@p-j/eapi-middleware-errorhandler@p-j/eapi-middleware-redirect@p-j/eapi-middleware-headers@p-j/eapi-util-applymiddlewares@p-j/eapi-util-fetcheventhandler
As you create your own middlewares to extend your application a few things should be considered:
By convention and to facilitate evolution without breaking changes, middleware are usually returned by a factory function, even if at the beginning they don't take in any options.
You may want to consider doing the same for your own middlewares, especially if you plan on opensourcing them.
While nothing prevents you from using all the eapi-* packages in a Javascript project, using TypeScript will a whole lot to the table with very limited friction. You can check @p-j/worker-eapi-template as an example or inspiration for your own configuration.
@p-j/eapi-types contains types that are useful for building compatible functions. You may want to depend on it to ensure compatibility.
Feel free to use the eapi-* naming if your middleware is compatible, and the eapi tag on github & npm to ensure discoverability.
Pull Request are welcome to add more middlewares, utility or request handler to this collection.