@priestine/grace NPM

@priestine/grace

Minimalistic middleware-based framework for building web apps with Node.js.

Installation

npm i --save @priestine/data @priestine/routing @priestine/grace

yarn add @priestine/data @priestine/routing @priestine/grace

Overview

@priestine/grace is a set of helper code to speed up development with @priestine/routing. It is going to include most common things wrapped up into middleware, pipelines or even routers that you can concat to your code where necessary.

Usage

Errors

HttpError is a class that extends Error and you can use it to exit the pipeline with required status code and error message. It provides chaining methods for setting up the response you want to send:

const { HttpError } = require('@priestine/grace');

throw new HttpError().withStatusCode(400).withMessage('Missing required field "id"');

// or

reject(new HttpError().withStatusCode(400).withMessage('Missing required field "id"'));

NOTE: HttpError is not intended to be used for debugging or serving as a wrapper for ambiguous errors you do not anticipate.

There is a set of predefined errors with appropriate status codes assigned so you can use them and extend with required error messages. Refer to RFC or MDN for the description of status codes.

const { BadRequestError } = require('@priestine/grace');

throw BadRequestError.withMessage('No-no-no');

4xx Errors

BadRequestError (400)
UnauthorizedError (401)
ForbiddenError (402)
NotFoundError (404)
MethodNotAllowedError (405)
NotAcceptableError (406)
ProxyAuthenticationRequiredError (407)
RequestTimeoutError (408)
ConflictError (409)
GoneError (410)
LengthRequiredError (411)
PreconditionFailedError (412)
PayloadTooLargeError (413)
URITooLongError (414)
UnsupportedMediaTypeError (415)
RequestedRangeNotSatisfiableError (416)
ExpectationFailedError (417)
MisdirectedRequestError (421)
UnprocessableEntityError (422)
LockedError (423)
FailedDependencyError (424)
TooEarlyError (425)
UpgradeRequiredError (426)
PreconditionRequiredError (428)
TooManyRequestsError (429)
RequestHeaderFieldsTooLargeError (431)
UnavailableForLegalReasonsError (451)

5xx Errors

InternalServerError (500)
NotImplementedError (501)
BadGatewayError (502)
ServiceUnavailableError (503)
GatewayTimeoutError (504)
HttpVersionNotSupportedError (505)
VariantAlsoNegotiatesError (506)
InsufficientStorageError (507)
LoopDetectedError (508)
NotExtendedError (510)
NetworkAuthenticationRequiredError (511)

Pipelines

`AccessControlPipeline`

Access control pipeline assigns the following response headers:

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers (optional)
Access-Control-Expose-Headers (optional)

Accepted arguments

/**
 * @interface AccessControlPipelineOpts
 */
export interface AccessControlPipelineOpts {
  /**
   * Origin to be set to Access-Control-Allow-Origin value.
   */
  origin: string;
  /**
   * Top-level HttpRouter for detecting methods available for current route.
   */
  router: HttpRouter;
  /**
   * Headers allowed to be sent in request.
   */
  headers?: string[];
  /**
   * Headers allowed to be referenced from browser.
   */
  exposeHeaders?: string[];
}

Usage

const { Pipeline } = require('@priestine/data/src');
const { AccessControlPipeline } = require('@priestine/grace');
const router = require('../routing').MainRouter;

const MyPipeline = Pipeline.empty()
  .concat(
    AccessControlPipeline({
      origin: '*',
      router,
      headers: ['Accept', 'Content-Type', 'Authorization', 'X-Request-ID', 'If-None-Match'],
      exposeHeaders: ['ETag'],
    })
  )
  .concat(/**/);

`AuthorizationHeaderPipeline`

Authorization header pipeline checks if Authorization header is in place in IncomingMessage and assigns its value to ctx.intermediate.authorizationHeaderValue.

If the header is missing, it throws UnauthorizedError. If the header is invalid (auth type wrong or no value), it throws ForbiddenError.

NOTE: This pipeline is agnostic and you need to unpack the token or whatever the auth string is yourself.

For TypeScript developers, it provides helper AuthorizationHeaderAware interface to be passed to generic HttpContextInterface.

import { HttpContextInterface } from '@priestine/routing';
import { AuthorizationHeaderAware } from '@priestine/grace';

const MyAuthRelatedMiddleware = (ctx: HttpContextInterface<AuthorizationHeaderAware>) => {};

Accepted arguments

/**
 * @interface AuthorizationHeaderPipelineOpts
 */
export interface AuthorizationHeaderPipelineOpts {
  /**
   * Authentication type.
   */
  authType: WWWAuthenticateType;
  /**
   * Custom messages to be displayed in case error occurs.
   */
  errors?: {
    /**
     * Error if request does not have Authorization header.
     * @default UnauthorizedError
     */
    unauthorized?: HttpError;
    /**
     * Error if request has invalid Authorization header.
     * @default ForbiddenError
     */
    forbidden?: HttpError;
  };
}

Usage

const { Pipeline } = require('@priestine/data/src');
const { AuthorizationHeaderPipeline, UnauthorizedError, ForbiddenError } = require('@priestine/grace');

const MyPipeline = Pipeline.empty()
  .concat(
    AuthorizationHeaderPipeline({
      authType: 'Bearer',
      errors: {
        unauthorized: UnauthorizedError.withMessage('Log in to get access to this resource'),
        forbidden: ForbiddenError.withMessage('You shall not pass'),
      },
    })
  )
  .concat(/**/);

`EndResponseBodyPipeline`

DEPRECATED: Will be renamed to SendResponseBodyPipeline

End response by sending the contents of ctx.intermediate.responseBody to the client.

If response is finished and an error occurred, the error will be put to stdout. If response is finished and no error happened, the pipeline does nothing.

For TypeScript developers, it provides helper ResponseBodyAware interface to be passed to generic HttpContextInterface.

import { HttpContextInterface } from '@priestine/routing';
import { ResponseBodyAware } from '@priestine/grace';

const MyResponseRelatedMiddleware = (ctx: HttpContextInterface<ResponseBodyAware>) => {};

ResponseBodyAware is generic and provided type is referenced by intermediate.responseBody, e.g.:

import { HttpContextInterface } from '@priestine/routing';
import { ResponseBodyAware } from '@priestine/grace';

const MyResponseRelatedMiddleware = (ctx: HttpContextInterface<ResponseBodyAware<{ id: number }>>) => {};

Accepted arguments

/**
 * @interface EndResponsePipelineOpts
 */
export interface EndResponsePipelineOpts {
  /**
   * Flag for the pipeline to JSON.stringify responseBody.
   */
  json?: boolean;
  /**
   * Flag for wrapping response body into `{ success: boolean, data: <responseBody> }`.
   */
  wrap?: boolean;
}

Usage

const { Pipeline } = require('@priestine/data/src');
const { EndResponseBodyPipeline } = require('@priestine/grace');

const MyPipeline = Pipeline.empty()
  .concat(/**/)
  .concat(
    EndResponseBodyPipeline({
      json: true,
    })
  );

`EndEmptyResponsePipeline`

DEPRECATED: Will be renamed to SendEmptyResponsePipeline

End response with empty string ("").

If response is finished and an error occurred, the error will be put to stdout. If response is finished and no error happened, the pipeline does nothing.

Usage

const Pipeline = require('@priestine/data/src').Pipeline;

const MyPipeline = Pipeline.empty()
  .concat(/**/)
  .concat(EndEmptyResponsePipeline);

Utils

`getFromEnv`

Simple function that returns contents of process.env for given key, or the default value.

const { getFromEnv } = require('@priestine/grace');

getFromEnv('MY_ENV_VAR', 'default_value');

`CaseTransformer`

DEPRECATED: Will be moved to external package

CaseTransformer is a tool for transforming string from one case to another. Supported cases are:

camelCase
PascalCase
kebab-case
snake_case
dot.case
colon:case

CaseTransformer can be used itself using its of pointer interface:

const { CaseTransformer } = require('@priestine/grace');

const helloWorld = CaseTransformer.of('hello-world').from.kebab.to.camel;
console.log(helloWorld); // helloWorld

Alternatively, you can use one of many helper functions:

transformCase(str: string)

transformCase is a pointer interface for lifting a string into transformation which is built via fluent interface chaining.

const { transformCase } = require('@priestine/grace');

console.log(transformCase('helloWorld').from.camel.to.snake); // hello_world

toXCase(strs: string[])

Transforms array of strings to a string with given case. Supported helpers are:

toCamelCase
toKebabCase
toPascalCase
toSnakeCase
toDotCase
toColonCase

// Example
const { toDotCase } = require('@priestine/grace');

toDotCase(['http', 'errors', 'access_denied']); // 'http.errors.access_denied'

fromXCase(str: string)

Transforms string in specified case to an array of separate strings. Supported helpers are:

fromCamelCase
fromKebabCase
fromPascalCase
fromSnakeCase
fromDotCase
fromColonCase

// Example
const { fromDotCase } = require('@priestine/grace');
const myTranslationsObject = require('./en_US.json');

R.path(fromDotCase('http.errors.access_denied'), myTranslationsObject);

Middleware

Response-specific

`SetHeader`

A set of middleware for setting response headers. Each function accepts a value and returns a function that accepts the HttpContextInterface.

const { Pipeline } = require('@priestine/data/src');
const { SetContentTypeHeader, SetContentLanguageHeader, SetDateHeader } = require('@priestine/grace');

const MyHeadersPipeline = Pipeline.from([
  SetContentTypeHeader('application/json'),
  SetContentLanguageHeader('en_US'),
  SetDateHeader(new Date().toUTCString()),
]);

List of supported SetHeader middleware

SetAcceptPatchHeader
SetAcceptRangesHeader
SetAllowHeader
SetAgeHeader
SetCacheControlHeader
SetConnectionHeader
SetContentTypeHeader
SetContentDispositionHeader
SetContentEncodingHeader
SetContentLanguageHeader
SetContentLengthHeader
SetContentLocationHeader
SetContentRangeHeader
SetDateHeader
SetETagHeader
SetLastModifiedHeader
SetLinkHeader
SetLocationHeader
SetProxyAuthenticateHeader
SetRetryAfterHeader
SetServerHeader
SetSetCookieHeader
SetStrictTransportPolicyHeader
SetTransferEncodingHeader
SetUpgradeHeader
SetVaryHeader
SetViaHeader
SetWarningHeader
SetWWWAuthenticateHeader
SetXRequestIDHeader
SetAccessControlAllowOriginHeader
SetAccessControlAllowMethodsHeader
SetAccessControlAllowHeadersHeader
SetAccessControlExposeHeadersHeader

You can use these pre-defined middleware for building custom logic, e.g.:

const uuid = require('uuid/v4');
const { SetXRequestIDHeader, CheckAcceptHeader, SetContentTypeHeader } = require('@priestine/grace');
const { Pipeline } = require('@priestine/data/src');

/**
 * Simple example.
 * Sign each request with new UUID value.
 */
const SignRequest = SetXRequestIDHeader(uuid());

/**
 * A bit more complicated example.
 * Check if client accepts application/json and fallback to application/xml if it doesn't.
 * We don't need any checks as we have applied them in the previous step of the pipeline (see below).
 */
const AssignContentType = (ctx) => {
  const acceptable = ctx.request.headers.accept.split(', ');
  const json = acceptable.includes('*/*') || acceptable.includes('application/json');

  return SetContentTypeHeader(json ? 'application/json' : 'application/xml')(ctx);
};

const MyPipeline = Pipeline.from([
  // Check Accept header exists and has supported value
  CheckAcceptHeader(['*/*', 'application/json', 'application/xml']),
  // Sign request with UUID
  SignRequest,
  // Assign response Content-Type header
  AssignContentType,
]);

`TransformResponseKeys`

Transform keys of response object with given transformer function. The transformation is applied recursively.

const { Pipeline } = require('@priestine/data/src');
const { TransformResponseObjectKeys, EndResponseBodyPipeline } = require('@priestine/grace');

const MyPipeline = Pipeline.of(TransformResponseObjectKeys((x) => x.toUpperCase())).concat(
  EndResponseBodyPipeline({ json: true })
);

The middleware has two helpers for common cases:

TransformResponseObjectKeysFromCamelToSnake
TransformResponseObjectKeysFromSnakeToCamel

Request-specific

`CheckAcceptHeader`

Check if request Accept header value is defined and supported. Throws NotAcceptableError if header value is not acceptable by the server.

This middleware accepts the following arguments:

acceptable: array of strings representing MIME-types acceptable by the server, e.g. ["application/json", "application/xml"], defaults to ['*/*']
error: optional error to be thrown in case MIME-type is not acceptable (defaults to NotAcceptableError.withMessage('not acceptable'))

If acceptable includes '*/*', any value of Accept header does not trigger the error. You can limit that to ['application/json'] if you are building JSON API.

const { Pipeline } = require('@priestine/data/src');
const { CheckAcceptHeader } = require('@priestine/grace');

const MyPipeline = Pipeline.of(CheckAcceptHeader(['application/json']));

`ValidateObjectBodyProp`

Validate request body object with given set of validators by given request body key. This middleware should be used when object is expected in request body.

@priestine/grace provides a set of common data-type validators. You can use any other validator, e.g. provided by Ramda or Validator.js - validators are functions that accept a value and return a boolean.

Validators provided by the package:

isInstanceOf
isObject
isString
isBoolean
isTrue
isFalse
isNumber
isInteger
isFloat
isEmpty
isRequired - fails if value is falsy
isNull
isUndefined
isFunction
isIn - fails if value is not in the array provided in the argument
lt - fails if value is greater than or equal to the one provided in the argument
lte - fails if value is greater than the one provided in the argument
gt - fails if value is less than or equal to the one provided in the argument
gte - fails if value is less than the one provided in the argument
isOptional - applies validators provided in the argument only if the value is defined
negate - negates the result of validation (e.g. negate(isNull) fails if value is null) This function is added for composing notX validators.

ValidateObjectBodyProp provides generic interface for type-hinting.

Accepted arguments

/**
 * @interface ValidateBodyOpts
 */
export interface ValidateBodyOpts<T, K extends keyof T = keyof T> {
  /**
   * requestBody key to be referenced for validating its value.
   */
  key: K;
  /**
   * Array of validators to be applied to the value.
   */
  validators: Array<(value: T[K]) => boolean>;
  /**
   * Custom error to be thrown.
   * @default BadRequestError
   */
  error?: HttpError;
}

Example

import { Pipeline } from '@priestine/data/src';
import { ValidateObjectBodyProp, isRequired, isInteger, isOptional, isString } from '@priestine/grace';

interface ExpectedBody {
  id: number;
  firstName: string;
}

const MyPipeline = Pipeline.from([
  ValidateObjectBodyProp<ExpectedBody>('id', [isRequired, isInteger]),
  ValidateObjectBodyProp<ExpectedBody>('firstName', [isOptional([isString])]),
]);

`ValidateArrayBodyProp`

ValidateArrayBodyProp is the same as ValidateObjectBodyProp with the only difference - it should be used when array request body is expected as it applies validation recursively on each element in the array.

Accepted arguments

/**
 * @interface ValidateBodyOpts
 */
export interface ValidateBodyOpts<T, K extends keyof T = keyof T> {
  /**
   * requestBody key to be referenced for validating its value.
   */
  key: K;
  /**
   * Array of validators to be applied to the value.
   */
  validators: Array<(value: T[K]) => boolean>;
  /**
   * Custom error to be thrown.
   * @default BadRequestError
   */
  error?: HttpError;
}

Example

import { Pipeline } from '@priestine/data/src';
import { ValidateArrayBodyProp, isRequired, isInteger, isOptional, isString } from '@priestine/grace';

interface ExpectedBodyArrayItem {
  id: number;
  firstName: string;
}

const MyPipeline = Pipeline.from([
  ValidateArrayBodyProp<ExpectedBodyArrayItem>({ key: 'id', validators: [isRequired, isInteger] }),
  ValidateArrayBodyProp<ExpectedBodyArrayItem>({ key: 'firstName', validators: [isOptional([isString])] }),
]);

`ValidateBodyProp`

Apply ValidateArrayBodyProp or ValidateObjectBodyProp depending on whether request body is an array or an object.

If a primitive is passed, throws BadRequestError. If validation is not passed, throws BadRequestError.

Accepted arguments

/**
 * @interface ValidateBodyOpts
 */
export interface ValidateBodyOpts<T, K extends keyof T = keyof T> {
  /**
   * requestBody key to be referenced for validating its value.
   */
  key: K;
  /**
   * Array of validators to be applied to the value.
   */
  validators: Array<(value: T[K]) => boolean>;
  /**
   * Custom error to be thrown.
   * @default BadRequestError
   */
  error?: HttpError;
}

Example

import { Pipeline } from '@priestine/data/src';
import { ValidateBodyProp, isRequired, isInteger, isOptional, isString } from '@priestine/grace';

interface ExpectedObjectOrArrayItem {
  id: number;
  firstName: string;
}

const MyPipeline = Pipeline.from([
  ValidateBodyProp<ExpectedObjectOrArrayItem>({ key: 'id', validators: [isRequired, isInteger] }),
  ValidateBodyProp<ExpectedObjectOrArrayItem>({ key: 'firstName', validators: [isOptional([isString])] }),
]);

`ExtractJSONRequestBody`

Extract body from the IncomingMessage. This middleware unpacks the data by piping request to JSONStream, then to event-stream.map and finally puts the request body to intermediate.requestBody.

For TypeScript developers, it provides helper RequestBodyAware<T = {}> interface to be passed to generic HttpContextInterface.

import { HttpContextInterface } from '@priestine/routing';
import { RequestBodyAware } from '@priestine/grace';

const MyRequestBodyAwareMiddleware = (ctx: HttpContextInterface<RequestBodyAware>) => {};

Accepted arguments

requestTimeout: amount of time in milliseconds until request timeout.

Example

const { Pipeline } = require('@priestine/data/src');
const { ExtractJSONRequestBody } = require('@priestine/grace');

const MyPipeline = Pipeline.of(ExtractJSONRequestBody(90000));

`ExtractRequestParams`

Extract request params from the IncomingMessage if route was registered with RegExp and puts them to intermediate.requestParams as array.

Example

const { Pipeline } = require('@priestine/data/src');
const { ExtractRequestParams } = require('@priestine/grace');

const MyPipeline = Pipeline.of(ExtractRequestParams);

`TransformRequestKeys`

Transform keys of request object with given transformer function. The transformation is applied recursively.

const { Pipeline } = require('@priestine/data/src');
const { TransformRequestObjectKeys, EndRequestBodyPipeline } = require('@priestine/grace');

const MyPipeline = Pipeline.of(TransformRequestObjectKeys((x) => x.toUpperCase())).concat(
  EndRequestBodyPipeline({ json: true })
);

The middleware has two helpers for common cases:

TransformRequestObjectKeysFromCamelToSnake
TransformRequestObjectKeysFromSnakeToCamel

framework routing http typescript

JSONStream event-stream ramda

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago