ResultHandler

Customize API responses and error handling

Overview

The ResultHandler class controls how your API sends responses and handles errors. It defines response schemas for success and error cases.

import { ResultHandler } from "express-zod-api";
import { z } from "zod";

const customResultHandler = new ResultHandler({
  positive: (data) => ({
    schema: z.object({ success: z.literal(true), data }),
    mimeType: "application/json",
  }),
  negative: z.object({ success: z.literal(false), error: z.string() }),
  handler: ({ error, output, response }) => {
    if (error) {
      response.status(error.statusCode || 500).json({
        success: false,
        error: error.message,
      });
    } else {
      response.status(200).json({ success: true, data: output });
    }
  },
});

Configuration

positive

Type: (output: Schema) => { schema: Schema; mimeType: string | string[] | null }

Description: Defines success response schema.

positive: (data) => ({
  schema: z.object({ data }),
  mimeType: "application/json",
})

negative

Type: Schema

Description: Error response schema.

negative: z.object({ error: z.string() })

handler

Type: (params: HandlerParams) => void

Required: Yes

Description: Sends the actual response.

Parameters:

output · any

Validated endpoint output (on success)

error · Error | null

Error object (on failure)

request · Request

Express request object

response · Response

Express response object

logger · Logger

Logger instance

input · any

Validated input

Pre-built Result Handlers

defaultResultHandler

Standard JSON responses:

// Success
{ "status": "success", "data": { ... } }

// Error
{ "status": "error", "error": { "message": "..." } }

arrayResultHandler

(Deprecated) Returns arrays directly for legacy APIs.

Examples

Custom Status Codes

const customStatusHandler = new ResultHandler({
  positive: (data) => ({
    schema: z.object({ data }),
    mimeType: "application/json",
    statusCode: 201,
  }),
  negative: z.object({ error: z.string() }),
  handler: ({ error, output, response }) => {
    if (error) {
      const status = error.statusCode || 500;
      response.status(status).json({ error: error.message });
    } else {
      response.status(201).json({ data: output });
    }
  },
});

Non-JSON Responses

import { ez } from "express-zod-api";

const fileHandler = new ResultHandler({
  positive: { schema: ez.buffer(), mimeType: "image/png" },
  negative: { schema: z.string(), mimeType: "text/plain" },
  handler: ({ error, output, response }) => {
    if (error) {
      response.status(400).send(error.message);
    } else if (output.buffer) {
      response.type("image/png").send(output.buffer);
    }
  },
});

Empty Responses

const emptyHandler = new ResultHandler({
  positive: { statusCode: 204, mimeType: null, schema: z.never() },
  negative: { statusCode: 404, mimeType: null, schema: z.never() },
  handler: ({ error, response }) => {
    response.status(error ? 404 : 204).end();
  },
});

Error Helpers

ensureHttpError()

Normalizes errors to have status codes:

import { ensureHttpError } from "express-zod-api";

const httpError = ensureHttpError(error);
console.log(httpError.statusCode); // 400, 401, 500, etc.

getMessageFromError()

Extracts error message:

import { getMessageFromError } from "express-zod-api";

const message = getMessageFromError(error);

See Also

Response Customization

Advanced response patterns

Error Handling

Error handling concepts