Zap - @mvdlei/zap

A Node.js package for making HTTP requests with ease. It provides a simple interface to define and execute requests, along with options for customization.

Installation

npm install @mvdlei/zap

Usage

import { zap } from "@mvdlei/zap";
import { z } from "zod";
 
// Define a request
const getTodo = zap.define("/todos", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "X-My-Header": "Hello World",
  },
  output: z.object({
    userId: z.number(),
    id: z.number(),
    title: z.string(),
    completed: z.boolean(),
  }),
});
 
// Execute the request
const main = async () => {
  try {
    const todo = await getTodo({ url: "/1", params: { userId: "1" } });
    console.log("Todo", todo);
  } catch (error) {
    console.error("Error", error);
  }
};
 
main();

Options

define

Takes in an input of type string | Request | URL and an options object.

The define method is used to define a request with the following options:

  • method: The HTTP method (default is "POST").
  • input: The input schema for the request payload.
  • output: The output schema for the response payload.
  • headers: Additional headers for the request.
const getTodo = zap.define("/todos", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "X-My-Header": "Hello World",
  },
  output: z.object({
    userId: z.number(),
    id: z.number(),
    title: z.string(),
    completed: z.boolean(),
  }),
});

Error Handling

The zap package uses the fetch API under the hood. It will throw an error if the request fails. You can use a try/catch block to handle errors.

The following errors are thrown by the handler if the request fails:

  • HTTPError: If the response status code is not ok.
  • TimeoutError: If the request times out.
  • ZodError: If the response payload does not match the output schema.

Will not throw zod error if output is not defined.

API

RestMethods

An object containing various HTTP methods for requests.

import { RestMethods } from "@mvdlei/zap";
 
const getMethod = RestMethods.GET; // "GET"

Zap Class

The main class that provides the core functionality for making HTTP requests. It includes methods for defining and executing requests.

import { Zap } from "@mvdlei/zap";
 
const zap = new Zap({ origin: "https://example.com", timeout: 5000 });

Callback Function

When defining a request, you will receive a callback function that takes an input object and returns a Promise of the response payload.

This input will be parsed to query parameters for GET requests and as the request payload for other methods.

const getTodo = zap.define("/todos", {
  url: ,
  method: "GET",
  output: z.object({
    userId: z.number(),
    id: z.number(),
    title: z.string(),
    completed: z.boolean(),
  }),
  input: z.object({
    userId: z.string(),
  }),
});
 
const todo = await getTodo({
  url: "/1",
  params: {
    userId: "1",
  }
});
// ^ /todos/1?userId=1

Example

import { zap } from "@mvdlei/zap";
import { z } from "zod";
 
const main = async () => {
  const getTodo = zap.define("/todos", {
    method: "GET",
    output: z.object({
      userId: z.number(),
      id: z.number(),
      title: z.string(),
      completed: z.boolean(),
    }),
    input: z.object({
      userId: z.string(),
    }),
  });
 
  const todo = await getTodo({ url: "/1", params: { userId: "1" } });
  console.log("Todo", todo);
 
  const postTodo = zap.define("/todos", {
    method: "POST",
    output: z.object({
      id: z.number(),
    }),
    input: z.object({
      userId: z.string(),
      title: z.string(),
      completed: z.boolean(),
    }),
  });
 
  const newTodo = await postTodo({
    userId: "1",
    title: "test",
    completed: false,
  });
  console.log("New Todo", newTodo); // { id: number }
};

Links

zap.ts

Related