Basic Types for the HTTP Protocol

Introduction

This TypeScript library provides some basic types to describe the HTTP protocol. Use it to improve the type-safety of your code.

• Introduction
• Quick Start
• V1 API
  • HttpStatusCode
  • httpStatusCodeFrom()
  • isHttpStatusCode()
  • mustBeHttpStatusCode()
• NPM Scripts
  • npm run clean
  • npm run build
  • npm run test
  • npm run cover

Quick Start

# run this from your Terminal
npm install @ganbarodigital/ts-lib-http-types

// add this import to your Typescript code
import { HttpStatusCode } from "@ganbarodigital/ts-lib-http-types/lib/v1"

VS Code users: once you've added a single import anywhere in your project, you'll then be able to auto-import anything else that this library exports.

V1 API

HttpStatusCode

/**
 * represents any HTTP status code in the range `100` to `599` inclusive
 */
export type HttpStatusCode = Branded<number, "@ganbarodigital/HttpStatusCode">;

HttpStatusCode is a type. At runtime, it resolves down to a native Javascript number.

httpStatusCodeFrom()

export function httpStatusCodeFrom(input: number, onError?: OnError): HttpStatusCode;

httpStatusCodeFrom() is a smart constructor. It converts input numbers into HttpStatusCode types at compile time.

isHttpStatusCode()

/**
 * data guard. checks to see if the `input` value is in the range
 * of HTTP status codes.
 *
 * returns `true` if `input` is a number between 100 and 599 inclusive.
 */
export function isHttpStatusCode(input: number): boolean;

isHttpStatusCode() is a data guard. Use it to check that a given number is a valid HTTP status code.

mustBeHttpStatusCode()

/**
 * data guarantee. calls the supplied `onError()` handler if the `input`
 * number is not a valid HTTP status code.
 */
export function mustBeHttpStatusCode(input: number, onError: OnError): void

mustBeHttpStatusCode() is a data guarantee. Use it to make sure that a given number is a valid HTTP status code.

Internal Note

This package simply republishes internal types from @ganbarodigital/ts-lib-error-reporting.

The types used to live in here. Unfortunately, we ran into a lot of trouble with circular dependencies (which broke unit testing).

NPM Scripts

npm run clean

Use npm run clean to delete all of the compiled code.

npm run build

Use npm run build to compile the Typescript into plain Javascript. The compiled code is placed into the lib/ folder.

npm run build does not compile the unit test code.

npm run test

Use npm run test to compile and run the unit tests. The compiled code is placed into the lib/ folder.

npm run cover

Use npm run cover to compile the unit tests, run them, and see code coverage metrics.

Metrics are written to the terminal, and are also published as HTML into the coverage/ folder.