Getting Started

Installation

Via NPM (recommended)

To install CallApi via npm, run the following command:

npm install @zayne-labs/callapi

Without NPM

To use CallApi without npm, import it directly into your JavaScript files via a CDN by using a script tag with the type="module" attribute:

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

If you want to use a specific version, you can specify it in the URL like this:

<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
const  = .({
	: .(),
	: .(),
	: .(),
	: .(),
});

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

Hover over any of the properties to see the type

The result object format can be 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",
});

CreateFetchClient

CreateFetchClient allows you to create a callApi instance with custom base configurations.

You can pass any of the fetch API options to the createFetchClient function along with any of the CallApi options.

Any similar options passed to the callApi instance created will override the options passed to the createFetchClient function, since they both take in the same options.

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");

Request and Response Validation

CallApi comes with built-in support for request and response validation, both on type-level and runtime, ensuring your API calls and their responses match their expected types. The validation system is powered by the Standard Schema specification, giving you the freedom to use your favorite validation library:

Zod - Popular choice with excellent TypeScript integration
Valibot - Lightweight and performant validation
ArkType - Advanced type-level validation
And more! - Any library implementing the Standard Schema spec

Here's a quick example of how to validate your API responses:

api.ts

import {  } from "@zayne-labs/callapi";
import {  } from "zod"; // You can use any schema validation library that implements the Standard Schema specification

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

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

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

For a comprehensive deep-dive into validation strategies, including global validation, request-options (body, headers, params, query) validation, custom validators, and best practices, check out our Validation Guide.

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

Via NPM (recommended)

Without NPM

Quick Start

CreateFetchClient

Request and Response Validation

Throwing Errors

On this page