Adapting the Library to Our API Format

[mima0815]

I am trying to adapt the library to match our API's response format, which is structured as follows:

On success:

{
  "data": {} | [],
  "meta": {}
}

On error:

{
  "errors": [...],
  "meta": {}
}

The endpoints factory is currently configured like this:

output: z.object({
  data: z.object({
    greetings: z.string(),
  }),
  meta: z.object({
    test: z.string(),
  }),
}),

Questions

1. Is there a way to restrict or enforce the top-level response format in both the EndpointsFactory and ResultHandler?
2. Can the handler function inside the ResultHandler be made aware of (and type-safe for) the output format?

Current Approach

At the moment, I’m manually adding types to the response to suppress TypeScript warnings, for example:

response.json({
  data: output.data as Record<string, never> | Record<string, never>[],
  meta: output.meta as Record<string, never>,
});

---

Feedback and Suggestions

• Is there a recommended approach to ensure the response format is consistent and type-safe across all endpoints?
• Can the library be extended or configured to encapsulate this pattern, reducing the need for manual type assertions?

---

Any guidance or best practices would be greatly appreciated!

[RobinTail]

Hello @mima0815. Here is my recommendation to you.

1. Check out the implementation of these two instances of ResultHandler:

• express-zod-api/express-zod-api/src/result-handler.ts

  Line 98 in 5f85ac0

  export const defaultResultHandler = new ResultHandler({

• express-zod-api/express-zod-api/src/result-handler.ts

  Line 147 in 5f85ac0

  export const arrayResultHandler = new ResultHandler({

2. Then make your own ones in a similar way: one that responds with an object and another one that responds with an array.
   a. Avoid using as in implementation, instead use type asserting conditions, like this:

   express-zod-api/express-zod-api/src/result-handler.ts

   Line 182 in 5f85ac0

   if ("items" in output && Array.isArray(output.items)) {

3. Then make two instances of EndpointsFactory based on those two ResultHandler you created, example:

   express-zod-api/example/factories.ts

   Line 55 in 5f85ac0

   export const arrayRespondingFactory = new EndpointsFactory(arrayResultHandler);

4. Using those factories, .build() the Endpoints accordingly, example for arrays:

   express-zod-api/example/endpoints/list-users.ts

   Lines 8 to 12 in 5f85ac0

   	export const listUsersEndpoint = arrayRespondingFactory.build({
   	tag: "users",
   	output: z.object({
   	// the arrayResultHandler will take the "items" prop as the response
   	items: z

Thus, you do the customizations you need and avoid assumptions. And each Endpoint would have a clear response schema: either object or array.

In case for some reason you want to combine it into a single ResultHandler (which is unclear to me), check out this article: https://ez.robintail.cz/v24.6.0/different-responses-for-different-status-codes

I hope it helps.