Server
Type-Safety & Validation

Type-Safety & Validation

feTS uses JSON Schema to describe the request parameters and the response body.

It allows us to have:

  • Type-safety: In the handler, complete type safety for the request parameters and the response body is ensured. You can use a tool like feTS Client that is capable of inferring these types from the router instance.
  • Request Validation: feTS validates the request parameters and if the request is invalid, it returns a 400 Bad Request.
  • Safe and Fast Serialization: feTS uses the response schema to serialize the response body. Rather than JSON.stringify, it uses fast-json-stringifywhich is twice as fast according to the benchmarks found here.
💡

If you want to use JSON Schema formats like uuid, you need to register formats using registerFormats.

import { registerFormats } from 'fets'
 
registerFormats();

Request

You can type individual parts of the Request object including JSON body, form data, headers, query parameters, and URL parameters.

Headers

You can describe the shape of the headers using schemas.request.headers property. This is useful for validating API keys or authorization headers.

import { createRouter, Response } from 'fets'
 
const router = createRouter().route({
  method: 'POST',
  path: '/todos',
  // Define the request body schema
  schemas: {
    request: {
      headers: {
        type: 'object',
        properties: {
          'x-api-key': { type: 'string' }
        },
        additionalProperties: false,
        required: ['x-api-key']
      }
    }
  } ,
  handler: async request => {
    // This part is fully typed
    const apiKey = request.headers.get('x-api-key')
    // Would result in TypeScript compilation fail
    const wrongHeaderName = request.headers.get('x-api-key-wrong')
    // ...
    return Response.json({ message: 'ok' })
  }
})

Path Parameters

schemas.request.params can be used to validate the URL parameters like id inside /todos/:id:

By default, feTS already extracts and validates path parameters defined in the path. So unless you have some specific format for parameters, you don’t need to define schemas for path parameters..

import { createRouter, Response } from 'fets'
 
const router = createRouter().route({
  method: 'GET',
  path: '/todos/:id',
  // Define the request body schema
  schemas: {
    request: {
      // This is not needed since feTS already extracts and validates path parameters
      params: {
        type: 'object',
        properties: {
          id: { type: 'string' }
        },
        additionalProperties: false,
        required: ['id']
      }
      // Unless it is `uuid` or some specific format
      params: {
        type: 'object',
        properties: {
          id: { type: 'string', format: 'uuid' }
        },
        additionalProperties: false,
        required: ['id']
      }
    }
  } ,
  handler: async request => {
    // This part is fully typed
    const { id } = request.params
    // ...
    return Response.json({ message: 'ok' })
  }
})

Query Parameters

Similar, for query parameters like /todos?limit=10&offset=0, we can use schemas.request.query to define the schema:

import { createRouter, Response } from "fets";
 
const router = createRouter().route({
  method: "GET",
  path: "/todos",
  // Define the request body schema
  schemas: {
    request: {
      query: {
        type: "object",
        properties: {
          limit: { type: "number" },
          offset: { type: "number" },
        },
        additionalProperties: false,
        required: ["limit"],
      },
    },
  } ,
  handler: async (request) => {
    // This part is fully typed
    const { limit, offset } = request.query;
    // You can also use `URLSearchParams` API
    const limit = request.parsedURL.searchParams.get("limit");
    // ...
    return Response.json({ message: "ok" });
  },
});

JSON Body

We can also specify the JSON body schema by using schemas.request.json property:

import { createRouter, Response } from 'fets'
 
const router = createRouter().route({
  method: 'POST',
  path: '/todos',
  // Define the request body schema
  schemas: {
    request: {
      json: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          completed: { type: 'boolean' }
        },
        additionalProperties: false,
        required: ['title']
      }
    }
  },
  handler: async request => {
    // This part is fully typed
    const { title, completed } = await request.json()
    // ...
    return Response.json({ message: 'ok' })
  }
})

Form Data / File Uploads

You can also type the request body as multipart/form-data or application/x-www-form-urlencoded which are typically used for file uploads.

We use type: string and format: binary to define a File object. The maxLength and minLength of JSON Schema can be used to limit the file size. Learn more in the OpenAPI docs.

import { createRouter, Response } from 'fets'
 
const router = createRouter().route({
  method: 'POST',
  path: '/upload-image',
  // Define the request body schema
  schemas: {
    request: {
      formData: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          completed: { type: 'boolean' },
          image: {
            type: 'string',
            format: 'binary',
            maxLength: 1024 * 1024 * 5 // 5MB
          }
        },
        additionalProperties: false,
        required: ['title']
      }
    }
  },
  handler: async request => {
    // This part is fully typed
    const { title, completed, file } = await request.formData()
    // ...
    return Response.json({ message: 'ok' })
  }
})

Response (optional)

The response body can also be typed by the status code. It is highly recommended to explicitly define the status codes.

💡

If you don’t define the response schema, feTS will still infer types from the handler’s return value. However, in this case, you won’t have response types in OpenAPI schema and runtime validation. For example, if you use OpenAPI schema with feTS Client, you won’t have response typings. You will need to infer types directly from the router instead as shown here.

Example:

import { createRouter, Response } from 'fets'
 
const router = createRouter().route({
  method: 'GET',
  path: '/todos',
  // Define the request body schema
  schemas: {
    request: {
      headers: {
        type: 'object',
        properties: {
          'x-api-key': { type: 'string' }
        },
        additionalProperties: false,
        required: ['x-api-key']
      }
    },
    responses: {
      200: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            title: { type: 'string' },
            completed: { type: 'boolean' }
          },
          additionalProperties: false,
          required: ['id', 'title', 'completed']
        }
      },
      401: {
        type: 'object',
        properties: {
          message: { type: 'string' }
        },
        additionalProperties: false,
        required: ['message']
      }
    }
  },
  handler: async request => {
    const apiKey = request.headers.get('x-api-key')
    if (!apiKey) {
      return Response.json(
        { message: 'API key is required' },
        {
          status: 401
        }
      )
    }
    const todos = await getTodos({
      apiKey
    })
    // This part is fully typed
    return Response.json(todos)
  }
})
QuickstartError Handling