Better Call

Endpoints are the fundamental building blocks of better-call. You can create an endpoint using createEndpoint, which takes a path, an options object (defining method, body/query schemas, etc.), and a handler function.

Endpoints can be used in two ways:

1. Directly as a function: Call the endpoint object directly with an options object. This is useful for internal server-side logic.
2. Via a Router: Mount the endpoint to a router to serve it over HTTP via a web-standard compatible server (like Bun or Node.js).

import { createEndpoint } from "better-call"
import { z } from "zod"

// 1. Define the endpoint
export const createItem = createEndpoint("/item", {
    method: "POST",
    body: z.object({
        id: z.string()
    })
}, async (ctx) => {
    return {
        item: {
            id: ctx.body.id
        }
    }
})

// 2. Call it directly as a function
const item = await createItem({
    body: {
        id: "123"
    }
})

Better Call utilizes the StandardSchemaV1 interface to support validation libraries that adhere to the Standard Schema specification. This allows the library to work seamlessly with various schema validation tools by providing a unified way to validate unknown input values and retrieve inferred types.

A schema object must include a ~standard property containing the following:

• version: Must be 1.
• vendor: The name of the schema library (e.g., 'zod', 'valibot').
• validate: A function that accepts unknown and returns a Result<Output> or a Promise<Result<Output>>.
• types (optional): An object containing the input and output types for TypeScript inference.

// Example of what a compatible schema object looks like
const mySchema: StandardSchemaV1 = {
  "~standard": {
    version: 1,
    vendor: 'my-validator',
    validate: async (value) => {
      // validation logic
      return { value: value as Output };
    },
    types: {
      input: unknown,
      output: string
    }
  }
};

Middleware in better-call can be applied globally or to specific paths via the routerMiddleware configuration in createRouter.

When a request matches a path defined in routerMiddleware, the middleware is executed before the actual endpoint handler. If a middleware returns a Response object, that response is immediately returned to the client, bypassing the endpoint handler.

Middleware receives a context object containing path, method, headers, params, request, body, query, and context (from routerContext). Note that when running as middleware, the asResponse flag in the context is set to false.

const router = createRouter(endpoints, {
  routerMiddleware: [
    {
      path: '/admin',
      middleware: async (ctx) => {
        if (!ctx.headers.get('authorization')) {
          return new Response('Unauthorized', { status: 401 });
        }
      }
    }
  ]
});

The InputContext type represents the raw input provided to an endpoint or middleware. It is used to define the shape of the data that the framework expects to receive. It is composed of several inferred types based on the provided EndpointOptions or MiddlewareOptions:

• body: The validated body content (inferred from StandardSchemaV1 or metadata.$Infer.body).
• method: The HTTP method (e.g., GET, POST, or *).
• query: The validated query parameters.
• params: The URL path parameters (inferred from the path string).
• request: The raw Request object (if requireRequest is true).
• headers: The request headers (if requireHeaders is true).

Additionally, it includes control flags for the framework:

• asResponse: If true, methods like .json() will return a response-like object instead of raw data.
• returnHeaders: Indicates if headers should be returned.
• returnStatus: Indicates if the status should be returned.
• use: An array of middleware to apply.
• path: The current request path.
• context: A user-provided object for sharing state.
• asResponse: If true, methods like .json() will return a response-like object instead of raw data.

Handlers can return various types: a Response object, a plain JavaScript value (which is serialized), or the result of ctx.json().

Status Codes

Use ctx.setStatus(status) to change the success status code.

Errors

To return an error, you can:

1. Throw ctx.error(codeOrStatus, data, headers)
2. Throw a new APIError instance
3. Throw a raw status code (e.g., throw 400)

When mounted to a router, errors are converted to HTTP responses. When called as a function, they are thrown.

import { APIError } from "better-call"

const createItem = createEndpoint("/item", {
    method: "POST",
}, async (ctx) => {
    // Using ctx.error helper
    if (ctx.body.id === "123") {
        throw ctx.error("BAD_REQUEST", { message: "Id is not allowed" })
    }

    // Using APIError class
    if (ctx.body.id === "456") {
        throw new APIError("BAD_REQUEST", { message: "Id is not allowed" })
    }

    // Using status code
    if (ctx.body.id === "789") {
        throw ctx.error(400, { message: "Error" })
    }

    // Setting custom status
    ctx.setStatus(201)
    return { success: true }
})