ServerQuickstart

Quickstart

feTS Server is a library that allows you to create a fully type-safe REST API.

  • It includes a high-speed HTTP server.
  • The schemas are based on JSON Schema allowing the use of any tool from this ecosystem.
  • It provides OpenAPI documentation, making the API consumable with any OpenAPI compatible tool.
  • It is platform-agnostic, and thus can be deployed on any platform that supports JavaScript.
  • It offers a simple way to test your API with Swagger UI

For JavaScript environments, we highly recommend using feTS Client, which is a HTTP client that uses OpenAPI to provide end-to-end type-safety without code generation.

Installation

Use the following command to install feTS Server:

npm i fets uWebSockets.js@uNetworking/uWebSockets.js#semver:^20

Creating Your First Route

The following example demonstrates how to create a route with feTS that returns a greeting message:

greetings-router.ts
// The example code assumes that we're in a Node.js environment.
// It's recommended to use `Response` from `fets` as the native one isn't type-safe.
import { createRouter, Response } from 'fets'
import { App } from 'uWebSockets.js'
 
// Creating a new router
const router = createRouter()
  // Use `.route` method to create a new /greetings route
  .route({
    path: '/greetings',
    method: 'GET',
    // Defining the response schema
    schemas: {
      responses: {
        // The status code
        200: {
          type: 'object',
          properties: {
            message: {
              type: 'string'
            }
          },
          required: ['message'],
          additionalProperties: false
        }
      }
    },
    handler() {
      // If the status code is not specified, it defaults to 200
      return Response.json({
        message: 'Hello from feTS!'
      })
    }
  })
 
App()
  .any('/*', router)
  .listen(3000, () => {
    console.info(`Server is listening on http://localhost:3000`)
  })

Test your API using Swagger UI, available at http://localhost:3000/docs.

If you prefer using node:http over uWebSockets, see node:http integration recipe.

The .route API

The .route() method allows you to create new routes and it accepts the following arguments:

  • method: The HTTP method of the request. If not provided, it handles all methods.
  • path: The URL pattern to match the request. The URL pattern is a string that follows the URLPattern standard. Learn more about URL patterns here.
  • schemas: An object containing the schemas for the request and response, providing type safety and validation. Learn more about schemas here.
  • handler: The function called when the request matches the specified method and path. This function can be either synchronous or asynchronous. If asynchronous, it should return a Promise that resolves to a Response object.

The feTS Router gives you an extended version of the regular Request object. It has the following properties:

  • request.params: An object containing the parameters passed in an URL.
  • request.query: An object containing the query parameters.

You can learn more about the original Request object here.

Type-Safety & Validation