@bpinternal/expresso
TypeScript icon, indicating that this package has built-in type declarations

0.2.19 • Public • Published

Expresso

Description

Small wrapper above express that uses zod to add the following features:

  • it can auto generate your documentation and openapi specification.
  • it validates input requests.
  • it adds a bunch of typings so TypeScript can help your detect dumb errors.

Usage

1. Create Zod Schemas

import { z } from 'zod'

export const zError = z.object({ type: z.string(), code: z.number(), message: z.string() })
export const zSuccessResponse = z.object({ status: z.literal('success') })
export const zErrorResponse = z.object({ status: z.literal('error'), error: zError })

export const zCompileBody = z.object({ book: z.object({...}) })
export const zCompileSuccessResponse = zSuccessResponse.extend({ artifact_id: z.string() })
export const zCompileResponse = z.union([zCompileSuccessResponse, zErrorResponse])
export const userHeader = { ["x-user-id"]: z.string() }

2. Create an register a router

import * as io from './io' // your zod schemas
import express from 'express'
import swaggerExpress from 'swagger-ui-express'
import * as xo from '@bpinternal/expresso'

const expressApp = express()
const router = new xo.JsonRouter({ info: { title: 'My XO Server', version: '0.1.0' }, bodySize: options.bodySize })

// This route is documented, validated and fully typed
router.post(
  {
    path: '/compile',
    input: io.zCompileBody,
    output: io.zCompileResponse,
    headers: io.userHeader,
    operationId: 'compileBook'
  },
  async (req, res, next) => {
    try {
      const { ['x-user-id']: x_user_id } = req.headers
      const { book } = req.body
      const artifactId = await app.compile(x_user_id, book)
      res.send({ status: 'success', artifact_id: artifactId })
      return next()
    } catch (thrown) {
      return next(thrown)
    }
  }
)

// This route is not documented but is still active. It shows the openapi spec content.
router.inner.get('/openapi.json', async (req, res, next) => {
  try {
    const { openapi } = router
    const specs = openapi.getSpec()
    res.send(specs)
    return next()
  } catch (thrown) {
    return next(thrown)
  }
})

// These will display the Swagger UI to interract with your backend
const { openapi } = router
router.inner.use('/', swaggerExpress.serve)
router.inner.get('/', swaggerExpress.setup(openapi.getSpec()))

expressApp.use('/', router.inner)

3. Document with Redoc

const redocHtml = (specUrl: string) => `<!DOCTYPE html>
<html>
  <head>
    <title>Redoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link
      href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
      rel="stylesheet"
    />

    <!--
    Redoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc
      spec-url="${specUrl}"
    ></redoc>
    <script src="https://unpkg.com/redoc@2.0.0-rc.72/bundles/redoc.standalone.js"></script>
  </body>
</html>
`

router.inner.get('/redoc', async (req, res, next) => {
  try {
    res.send(redocHtml('/openapi.json'))
    return next()
  } catch (thrown) {
    return next(thrown)
  }
})

Disclaimer ⚠️

This package is published under the @bpinternal organization. All packages of this organization are meant to be used by the Botpress team internally and are not meant for our community. However, these packages were still left intentionally public for an important reason : We Love Open-Source. Therefore, if you wish to install this package feel absolutly free to do it. We strongly recomand that you tag your versions properly.

The Botpress Engineering team.

Readme

Keywords

none

Package Sidebar

Install

npm i @bpinternal/expresso

Weekly Downloads

1

Version

0.2.19

License

MIT

Unpacked Size

138 kB

Total Files

45

Last publish

Collaborators

  • davidvitora
  • slvnperron
  • botpress-cloud-ops
  • spgingras
  • chsir17
  • allardy
  • eff
  • franklevasseur
  • michael.masson