Next Handle

A small library which provides a uniform way to handle server actions in Next.js applications.

Installation

npm install --save next-handle

Basic Usage

Use Next Handle to create uniform, fully-typed server actions. The following example creates a server action that registers a new user.

"use server";

// ... import

export async function register(payload: { values: RegisterFormValues }) {
  return await Handlers.Service.action(async () => {
    // ... validate input

    if (!valid) {
      return Handlers.Service.sendResponse(400, {
        detail: "Invalid payload",
        data: null,
      });
    }

    // ... hash password

    // ... check if user already exists

    if (userExists) {
      return Handlers.Service.sendResponse(409, {
        detail: "User already exists",
        data: null,
      });
    }

    // ... create user

    return Handlers.Service.sendResponse(201, {
      detail: `User created with email: ${userEmail}`,
      data: null,
    });
  });
}

Now you can use register as a server action, and receive an automatically fully-typed response.

const response = await register(values);
//    ^? typeof response = Handlers.Basic.Response<500, null> | Handlers.Basic.Response<400, null> | Handlers.Basic.Response<409, null> | Handlers.Basic.Response<201, null>

The possible status code and data types are automatically included in the return type. All actions might encounter unexpected errors, which are caught automatically. This is why any action could return a Handlers.Types.Response<500, null>.

Logging

You can control which responses are logged to the console, by setting the following environment variables:

Variable Name	Description
NEXT_HANDLE_LOG_AUTO_ERROR	Whether to log when a server action encounters an unexpected error, and fails
NEXT_HANDLE_LOG_STATUS	A comma-separated list of status codes to log. If set to *, all status codes will be logged. Add ERR or OK to log all error responses, and all OK responses respectively
NEXT_HANDLE_EXCLUDE_STATUS	A comma-separated list of status codes to exclude from logging. If set to *, all status codes will be excluded. Add ERR or OK to exclude all error responses, and all OK responses respectively (excludes take precedence over logging)

Response Object

The object returned in a response contains the following properties:

Property	Generic Type	Description
status	number	The status code of the response.
ok	boolean	Whether the response was successful (determined by status).
title	string	A standard title (determined by status).
detail	string	A human-readable explanation specific to this occurrence of the problem
data	any	The data returned in the response.

The exact types of status, ok, title, and data will be included in the type of the response. For example, a response of type Handlers.Types.Response<200, User> will have the following types:

Property	Exact Type
status	200
ok	true
title	"OK"
detail	string
data	User

Response Codes

Response codes mostly follow those as defined by this page. In addition, IIS, NGINX, and Cloudflare common response codes are included.

Next Handle also provides "non-standard" codes, 631, 632, 633, 634, 635, with the last digit representing the category of the response (1 for 'information', 2 for 'success'...). When using these codes, it is important to include an adequate description in the response.