cloudflare/chanfana v3.3.0

v3.3.0

Repository: cloudflare/chanfana

Tag: v3.3.0

Published: 2026-03-18T10:10:57Z

Prerelease: no

Release notes:

Minor Changes

• #316 `d30cc36` Thanks @G4brym! - Add customizable pagination and ordering parameter names to ListEndpoint via pageFieldName, perPageFieldName, orderByFieldName, and orderByDirectionFieldName class properties.

Breaking change for subclasses overriding `optionFields`: optionFields is now a computed getter derived from the four *FieldName properties. Subclasses that previously overrode optionFields directly should instead override the individual field name properties.

• #317 `39c89d2` Thanks @G4brym! - Add validateResponse router option to validate and sanitize response bodies against their Zod schemas at runtime.

When enabled, responses are parsed through z.object().parseAsync(), which strips unknown fields and validates required fields/types. This prevents accidental data leaks (e.g., internal fields like passwordHash reaching the client) and catches handler bugs where the response doesn't match the declared schema.

const router = fromHono(app, { validateResponse: true });

Behavior:

• Plain object responses are validated against the 200 response schema
• Response objects with application/json content are cloned, validated, and reconstructed with corrected headers
• Non-JSON responses and responses without a matching Zod schema are passed through unchanged
• Validation failures return 500 Internal Server Error (code 7013) and log the full error via console.error

New exports:

• ResponseValidationException — thrown when a handler's response doesn't match its declared schema (status 500, code 7013, isVisible: false)

• #315 `47d304a` Thanks @G4brym! - Add SerializerContext parameter to auto endpoint serializer function, providing access to filters and options for context-aware serialization.

The serializer signature changes from (obj: object) => object to (obj: object, context?: SerializerContext) => object. The SerializerContext type contains:

• filters — Array: the active filter conditions for the current request
• options — pagination and ordering options (page, per_page, order_by, order_by_direction)

Context passed per endpoint type:

| Endpoint | Context | | ----------------------------------- | ---------------------- | | ListEndpoint / ReadEndpoint | { filters, options } | | UpdateEndpoint / DeleteEndpoint | { filters } | | CreateEndpoint | { filters: [] } |

const meta = {
model: {
schema: UserSchema,
primaryKeys: ["id"],
tableName: "users",
serializer: (obj: any, context?: SerializerContext) => {
const hasRoleFilter = context?.filters?.some((f) => f.field === "role");
// Conditionally include fields based on active filters
return hasRoleFilter ? obj : omit(obj, ["role"]);
},
},
};

New exports:

• SerializerContext — type for the serializer's second parameter

Patch Changes

• #335 `028c256` Thanks @andrewheberle! - Fix: Error from Zod transform is returning 500 instead of 400

• #328 `662ff72` Thanks @G4brym! - Include CHANGELOG.md in the npm package so AI agents and tools can read the project's change history. Also add a changelog page to the documentation site.