Skip to content

Latest commit

 

History

History
170 lines (123 loc) · 10.9 KB

README.md

File metadata and controls

170 lines (123 loc) · 10.9 KB
Raw

EAPI

EAPI for Edge API, or Extremelly Awesome Programming Interface, you decide 😎

lerna lerna codecov Build Status License FOSSA Status

What are EAPI packages?

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 version changelog
@p-j/eapi-middleware-cors Validate Origin & Apply CORS Headers version changelog
@p-j/eapi-middleware-errorhandler Catch exceptions, forward them or print them version changelog
@p-j/eapi-middleware-redirect Redirect, Rewrite or Proxy Requests version changelog
@p-j/eapi-middleware-headers Add/Remove headers on Request & Response version changelog
@p-j/eapi-util-applymiddlewares A utility to combine multiple middlewares version changelog
@p-j/eapi-util-fetcheventhandler Apply global middlewares & Match Routes version changelog
@p-j/eapi-types Common TypeScript typings for EAPI projects version changelog

Usage

Middlewares

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.

With @p-j/worker-eapi-template

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

With EAPI toolkit

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))
})

Standalone

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))
})

API

Types

Contributing

Creating your own Middleware

As you create your own middlewares to extend your application a few things should be considered:

Making use of factory functions

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.

Making use of the provided types

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.

Making them discoverable

Feel free to use the eapi-* naming if your middleware is compatible, and the eapi tag on github & npm to ensure discoverability.

Contributing to this repository

Pull Request are welcome to add more middlewares, utility or request handler to this collection.

License

FOSSA Status