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.