Skip to main content

Server-side utilities

caution

Prior to the library v1.47.0-alpha.8 all these utilities were exported as fields and methods of the server function, exported from the main library export; starting with v1.47.0-alpha.8 they are moved to separate exports from the dedicated server-side package export @dr.pogodin/react-utils/server.

Constants

  • CODES — A map from HTTP status code names to the corresponding numeric codes.
  • ERRORS — A map from HTTP status code names to their pretty-printed names.
  • SCRIPT_LOCATIONS — The map of valid location values in Script objects.

Functions

  • assert() — Validates a value against the given validation schema compliant to the Standard Schema Specs, e.g. Zod (recommended), or Joi, etc.

  • fail() — Throws an error with the given message and HTTP status code.

  • getErrorForCode() — Given HTTP status code returns the corresponding error text.

  • launchServer() — Creates and launches a web-server for ReactJS application.

  • newError() — Creates a new Error object with the given error message and attached HTTP status.

  • getDefaultCspSettings() — Returns a deep copy of default CSP settings object used by react-utils.

Deprecated
  • errors.joi — Removed in v1.44.0; an alias for Joi library, which provides methods for HTTP request validation.

Constants​

CODES​

import { CODES } from '@dr.pogodin/react-utils/server';

enum CODES {
  // Same as StatusCodes from 'http-status-codes'.
}

Enum of HTTP status codes — an alias of StatusCodes enum from the http-status-codes library.

Example

import { CODES } from '@dr.pogodin/react-utils/server';

console.log(CODES.BAD_REQUEST);

// Prints: 400

ERRORS​

import { ERRORS } from '@dr.pogodin/react-utils/server';

ERRORS: object

A map from HTTP status code names to their pretty-printed names. It is an alias for ReasonPhrases object from http-status-codes library.

Example

import { ERRORS } from '@dr.pogodin/react-utils/server';

console.log(ERRORS.BAD_REQUEST);

// Prints: Bad Request

SCRIPT_LOCATIONS​

import { SCRIPT_LOCATIONS } from '@dr.pogodin/react-utils/server';

SCRIPT_LOCATIONS: object

This object provides the map of valid Script's location values:

  • BODY_OPEN - Right after the opening <body> tag.
  • DEFAULT - In the end of <body> tag, just before the main application bundle. This is the default location where scripts are injected when provided as strings rather than Script objects.
  • HEAD_OPEN - Right after the opening <head> tag.

Functions​

assert()​

import { assert, CODES } from '@dr.pogodin/react-utils/server';

async function assert<T extends StandardSchemaV1>(
  value: unknown,
  schema: T,
  message = '',
  statusCode = CODES.BAD_REQUEST, // 400
): Promise<StandardSchemaV1.InferOutput<T>>;

Validates the value against the given validation schema, compliant to the Standard Schema Specs, e.g. Zod (recommended), or Joi, etc.. Throws an error with the given error message and statusCode if the validation fails, otherwise resolves to the validated value.

Arguments

  • value — unknown — The value to validate.
  • schema — StandardSchemaV1 — The validation schema, compliant to the Standard Schema Specs.
  • message = '' — string — Optional. Error message. If given, the error message from the validator will be appended to it, otherwise the error message from the validator is used as is.
  • statusCode = 400 — number — Optional. Error status code. Defaults 400 (bad request).

Resolves the validated value, with correctly inferred type.

fail()​

import { CODES, fail } from '@dr.pogodin/react-utils/server';

function fail(
  message: string,
  statusCode: CODES = CODES.INTERNAL_SERVER_ERROR,
): Error;

Throws an error with the given message and HTTP statusCode.

Arguments

  • message — string — Error message.
  • statusCode — CODES — Optional. HTTP status code. Defaults 500 (internal server error).

It never returns; however, its return type is declared as Error to allow throw fail(..), thus allowing the following TypeScript code:

const value: number | undefined = someFunction();
if (value === undefined) throw fail('Some error');

// TypeScript allows this, because `throw fail()` above narrows down
// the `value` down to just `number`. 
const nextValue = value + 1;

// NOTE: According to TypeScript documentation it seems that `never` return
// type would be more appropriate for `fail()`; however, `never` return type
// does not result in the same value type narrowing in this example.

getErrorForCode()​

import { getErrorForCode } from '@dr.pogodin/react-utils/server';

function getErrorForCode(code): string

Given HTTP status code returns the corresponding error text. It is an alias for getReasonPhrase() function from http-status-codes library.

Arguments & Result

  • code - number - HTTP status code.
  • Returns string - Error message.

newError()​

import { newError } from '@dr.pogodin/react-utils/server';

function newError(message, statusCode = 500): Error

Creates a new Error object with given message, and HTTP statusCode attached to the result as result.status field.

Arguments & Result

  • message - string - Error message.
  • statusCode = 500 - number - Optional. HTTP status code. Defaults 500 (Internal Server Error).
  • Returns Error.

getDefaultCspSettings()​

import { getDefaultCspSettings } from '@dr.pogodin/react-utils/server';

getDefaultCspSettings(): object

Returns a deep copy of default CSP settings object used by react-utils, with exception of nonce-xxx clause in script-src directive, which is added dynamically for each request.

errors.joi​

Deprecated

Removed in v1.44.0. The original documentation below is kept for reference.

server.errors.joi: object

An alias for Joi library, which provides methods useful for HTTP request validation.

Example: Joi methods are used to create validation schema for the body of a sample HTTP request.

import { server } from '@dr.pogodin/react-utils';

const { joi } = server.errors;
const requestBodySchema = joi.object({
  sampleKey: joi.string().max(16).required(),
});