chanfana

Chanfana uses native Zod schemas to define input types for API endpoints. This approach provides TypeScript type safety, built-in validation, and automatic OpenAPI documentation generation for request bodies, query parameters, path parameters, and headers.

Key benefits include:

• Type safety: Full TypeScript inference for validated data.
• Validation: Built-in Zod validation logic.
• OpenAPI generation: Automatic schema documentation.
• Flexibility: Access to all Zod features.

import { OpenAPIRoute, contentJson } from 'chanfana';
import { z } from 'zod';

class MyEndpoint extends OpenAPIRoute {
    schema = {
        request: {
            params: z.object({ id: z.uuid() }),
            query: z.object({ search: z.string().optional() }),
            headers: z.object({ 'X-Custom-Header': z.string() }),
            body: contentJson(z.object({ name: z.string() }))
        },
        responses: {
            '200': { description: 'Success' }
        }
    };

    async handle(c) {
        const data = await this.getValidatedData<typeof this.schema>();
        // data.params.id, data.query.search, etc. are typed
    }
}

Chanfana integrates with the middleware capabilities of your underlying router (Hono or itty-router).

Router Middleware

You can apply middleware for authentication, logging, or request modification. When using Hono, you can pass middleware directly into the Chanfana route registration method: openapi.get('/path', middleware, EndpointClass);

Endpoint Interceptors

Chanfana's auto endpoints (e.g., CreateEndpoint, ReadEndpoint, UpdateEndpoint, DeleteEndpoint, ListEndpoint) provide lifecycle methods that act as interceptors. You can override these to perform actions before or after the core logic:

• before: Executes before the core logic (useful for authorization or data validation).
• after: Executes after the core logic (useful for post-processing or logging).

Refer to the specific documentation for each auto-endpoint type to see the full list of available lifecycle methods.

import { Hono } from 'hono';
import { fromHono, OpenAPIRoute } from 'chanfana';

const authMiddleware = async (c, next) => {
    const apiKey = c.req.header('X-API-Key');
    if (apiKey !== 'valid-api-key') {
        return c.json({ success: false, message: 'Unauthorized' }, 401);
    }
    await next();
};

class ProtectedEndpoint extends OpenAPIRoute {
    schema = { responses: { "200": { description: 'Protected resource' } } };
    async handle(c: any) { return { message: 'Protected data' }; }
}

const app = new Hono();
const openapi = fromHono(app);

// Apply middleware to a specific route
openapi.get('/protected', authMiddleware, ProtectedEndpoint);

export default app;

To use auto endpoints, you must define a Meta object for each endpoint. This object describes your data model, including its schema, primary keys, and database table name. The Meta object is assigned to the endpoint class via the _meta property.

MetaInput Structure

type MetaInput = {
    model: Model;
    fields?: AnyZodObject; // Optional, defaults to model.schema
    pathParameters?: Array<string>; // Optional, to explicitly define path parameters
    tags?: Array<string>; // Optional, OpenAPI tags for grouping operations
};

type Model = {
    tableName: string; // Required, the database table name
    schema: AnyZodObject; // Zod schema defining the data model
    primaryKeys: Array<string>; // Array of primary key field names
    serializer?: (obj: object, context?: SerializerContext) => object; // Optional serializer function
    serializerSchema?: AnyZodObject; // Optional schema for serialized output
};

Key Properties

• model.tableName (required): The database table name (used by D1 endpoints for SQL generation).
• model.schema (required): A Zod schema defining the data model structure for validation and schema generation.
• model.primaryKeys (required): An array of strings representing the primary key fields. Used by ReadEndpoint, UpdateEndpoint, and DeleteEndpoint to identify resources.
• model.serializer (optional): A function to transform data before it is sent in a response. It receives the object and a SerializerContext (which includes filters and options like pagination/ordering).
• model.serializerSchema (optional): A Zod schema for the serialized output. If provided, it documents the structure of the response after the serializer has run.
• fields (optional): A Zod schema representing all possible fields. Defaults to model.schema. Use this if your database table has more columns than you want to expose via the API.
• pathParameters (optional): An array of strings to explicitly define which URL parameters correspond to the model's primary keys. This is essential for nested routes.
• tags (optional): OpenAPI tags for grouping operations in documentation (e.g., Swagger UI).

The MultiException class is used to group multiple ApiException instances together, allowing you to report several errors (like multiple validation failures) in a single response.

Key properties:

• errors: An Array<ApiException> containing the grouped exceptions.
• status: The highest HTTP status code among the contained exceptions (defaults to 400).
• isVisible: Defaults to true, but becomes false if any contained exception has isVisible: false.
• buildResponse(): Returns a combined array of error objects from all contained exceptions.

import { MultiException, InputValidationException, OpenAPIRoute, contentJson } from 'chanfana';
import { z } from 'zod';
import { type Context } from 'hono';

class ValidateMultipleFieldsEndpoint extends OpenAPIRoute {
    schema = {
        request: {
            body: contentJson(z.object({
                field1: z.string().min(5),
                field2: z.number().positive(),
                field3: z.boolean(),
            })),
        },
        responses: {
            ...InputValidationException.schema(), // Document HTTP 400 error
        },
    };

    async handle(c: Context) {
        const data = await this.getValidatedData<typeof this.schema>();
        const field1 = data.body.field1;
        const field2 = data.body.field2;
        const field3 = data.body.field3;

        const errors: ApiException[] = [];

        if (field1.length > 10) {
            errors.push(new InputValidationException("Field 1 is too long", ['body', 'field1']));
        }
        if (field2 > 100) {
            errors.push(new InputValidationException("Field 2 is too large", ['body', 'field2']));
        }

        if (errors.length > 0) {
            throw new MultiException(errors);
        }

        return { message: 'Validation successful' };
    }
}

When using Zod schemas with .default() values, getValidatedData() will always include those default values in the returned object, even if the client did not send the field. This can make it difficult to perform partial updates (e.g., PATCH requests) where you only want to update fields explicitly provided by the user.

To distinguish between a field being 'absent' and a field being 'sent with a default value', use getUnvalidatedData(). This method returns the raw request data before Zod applies any transformations or defaults.

class UpdateUser extends OpenAPIRoute {
  schema = {
    request: {
      body: contentJson(z.object({
        name: z.string().optional(),
        status: z.string().default('active'),
      })),
    },
  };

  async handle() {
    const validated = await this.getValidatedData();
    // validated.body = { status: 'active' } - default applied even if not sent

    const raw = await this.getUnvalidatedData();
    // raw.body = {} - shows what was actually in the request

    if ('status' in raw.body) {
      // User explicitly sent status field
    }
  }
}