Getting Started

Installation

npm install @zayne-labs/callapi

Or via CDN:

<script type="module">
	import { callApi } from "https://esm.run/@zayne-labs/callapi@1.10.3";
</script>

Quick Start

To get started with callApi, simply import the function and make your first request:

api.ts

import {  } from "@zayne-labs/callapi";

type  = {
	: boolean;
	: number;
	: string;
	: string;
};

const { , ,  } = await <>("https://jsonplaceholder.typicode.com/todos/1");Hover over the data or error object to see the type

As shown in the example, callApi returns a result object containing:

data: The response data
error: An error object containing info about any error that occurred during the lifecycle of the request
response: The Response object from the underlying fetch API

You can specify the data type and error type via TypeScript generics, or using a Validation Schema to validate and infer the types automatically.

api.ts

import {  } from "@zayne-labs/callapi";
import {  } from "zod";

type  = {
	: boolean;
	: number;
	: string;
	: string;
};

// Via TypeScript generics
const { , ,  } = await <>("https://jsonplaceholder.typicode.com/todos/1");

// Via Validation Schemas (automatic type inference)
const  = .({
	: .(),
	: .(),
	: .(),
	: .(),
});

const { :  } = await ("https://jsonplaceholder.typicode.com/todos/1", {
	: {
		: ,
	},
});

Hover over any of the properties to see the type

The result object format can also be customized using the resultMode option.

api.ts

import {  } from "@zayne-labs/callapi";

type  = {
	: boolean;
	: number;
	: string;
	: string;
};

const  = await <>("https://jsonplaceholder.typicode.com/todos/1", {Hover over the data to see the type
	: "onlyData",
});

Creating a Configured Client

Create a reusable client with base configuration using createFetchClient. Instance options override base defaults.

callBackendApi.ts

import {  } from "@zayne-labs/callapi";

export const  = ({
	: "https://jsonplaceholder.typicode.com",
	: 3,
	: "same-origin",
	: 10000,
});

type  = {
	: boolean;
	: number;
	: string;
	: string;
};

const  = await <>("/todos/10");

const  = await <>("/todos/5", {
	// Override timeout and retry attempts
	: 2,
	: 5000,
});

Request and Response Validation

CallApi supports runtime validation using the Standard Schema specification, compatible with Zod, Valibot, ArkType, and more.

api.ts

import {  } from "@zayne-labs/callapi";
import {  } from "zod";

const  = .({
	: .(),
	: .(),
	: .(),
});

const  = .({
	: .(),
	: .(
		.({
			: .(),
			: .(),
		})
	),
});

const { ,  } = await ("/todos/1", {
	: {
		: , // Validates successful response data
		: , // Validate error response data from the server
	},
});

See the Validation Guide for comprehensive details on validation strategies and best practices.

Throwing Errors

You can throw errors instead of returning them by passing the throwOnError option.

If you set the throwOnError option to true, the callApi function will throw the error.

If set it to a function instead, it will be passed the error context object, and it should return a boolean indicating whether to throw the error or not.

callBackendApi.ts

import {  } from "@zayne-labs/callapi";

export const  = ({
	: "https://jsonplaceholder.typicode.com",
	: true,
});

const {  } = await <{ : number }>("https://jsonplaceholder.typicode.com/todos/1");This will throw an error if the request fails or there is an error response

Learn more about handling errors in the Error Handling section.

Getting Started

Installation

Quick Start

Creating a Configured Client

Request and Response Validation

Throwing Errors

On this page