Functions

This is the main module to interact with Nhost’s Functions service. Typically you would use this module via the main Nhost client but you can also use it directly if you have a specific use case.

Import

You can import and use this package with:

import { createClient } from "@nhost/nhost-js/functions";

Usage

You can use this library by passing the path to the function you want to call and any body or fetch options you want to apply (optional):

import { createClient } from "@nhost/nhost-js";

const nhost = createClient({
  subdomain,
  region,
});

const funcResp = await nhost.functions.post("/helloworld", {
  message: "Hello, World!",
});
console.log(JSON.stringify(funcResp.body, null, 2));
// {
//   "message": "Hello, World!"
// }

The post method above is a convenience method for executing a POST request with a JSON body. For more generic requests, you can use the fetch method instead:

import { createClient } from "@nhost/nhost-js";

const nhost = createClient({
  subdomain,
  region,
});

const funcResp = await nhost.functions.fetch("/helloworld", {
  method: "GET",
  headers: {
    Accept: "text/plain",
    ContentType: "application/json",
  },
});
console.log(funcResp.body);
// "Hello, World!"

Error handling

The SDK will throw errors in most operations if the request returns a status >=300 or if the request fails entirely (i.e., due to network errors). The type of the error will be a FetchError<T>:

import { createClient } from "@nhost/nhost-js";
import { FetchError } from "@nhost/nhost-js/fetch";

const nhost = createClient({
  subdomain,
  region,
});

try {
  await nhost.functions.fetch("/helloworld", {
    method: "GET",
    headers: {
      Accept: "application/octet-stream",
    },
  });
} catch (error) {
  if (!(error instanceof FetchError)) {
    throw error; // Re-throw if it's not a FetchError
  }

  console.log("Error:", JSON.stringify(error, null, 2));
  // Error: {
  //   "body": "Unsupported Accept Header",
  //   "status": 400,
  //   "headers": {...}
  // }
  //
  // error handling...
}

This type extends the standard Error type so if you want to just log the error you can do so like this:

import { createClient } from "@nhost/nhost-js";
import { FetchError } from "@nhost/nhost-js/fetch";

const nhost = createClient({
  subdomain,
  region,
});

try {
  await nhost.functions.fetch("/helloworld", {
    method: "GET",
    headers: {
      Accept: "application/octet-stream",
    },
  });
} catch (error) {
  if (!(error instanceof Error)) {
    throw error; // Re-throw if it's not a FetchError
  }

  console.log("Error:", error.message);
  // Error: Unsupported Accept Header
  // error handling...
}

Interfaces

Client

Functions client interface providing methods for executing serverless function calls

Properties

baseURL

baseURL: string;

Methods

fetch()

fetch<T>(path: string, options?: RequestInit): Promise<FetchResponse<T>>;

Execute a request to a serverless function The response body will be automatically parsed based on the content type into the following types:

• Object if the response is application/json
• string text string if the response is text/*
• Blob if the response is any other type

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type	Description
path	string	The path to the serverless function
options?	RequestInit	Additional fetch options to apply to the request

Returns

Promise<FetchResponse<T>>

Promise with the function response and metadata.

post()

post<T>(
   path: string,
   body?: unknown,
   options?: RequestInit): Promise<FetchResponse<T>>;

Executes a POST request to a serverless function with a JSON body

This is a convenience method assuming the request is a POST with JSON body setting the Content-Type and ‘Accept’ headers to application/json and automatically stringifying the body.

For a more generic request, use the fetch method instead.

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type	Description
path	string	The path to the serverless function
body?	unknown	The JSON body to send in the request
options?	RequestInit	Additional fetch options to apply to the request

Returns

Promise<FetchResponse<T>>

Promise with the function response and metadata

pushChainFunction()

pushChainFunction(chainFunction: ChainFunction): void;

Add a middleware function to the fetch chain

Parameters

Parameter	Type	Description
chainFunction	ChainFunction	The middleware function to add

Returns

void

Functions

createAPIClient()

function createAPIClient(
  baseURL: string,
  chainFunctions?: ChainFunction[],
): Client;

Creates a Functions API client for interacting with serverless functions.

This client provides methods for executing requests against serverless functions, with support for middleware functions to handle authentication, error handling, and other cross-cutting concerns.

Parameters

Parameter	Type	Default value	Description
baseURL	string	undefined	Base URL for the functions endpoint
chainFunctions	ChainFunction[]	[]	Array of middleware functions for the fetch chain

Returns

Client

Functions client with fetch method