@p-j/eapi-types NPM

EAPI

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

What are EAPI packages?

It's a collection of common building blocks you need to build a 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-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

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

@p-j/eapi-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.