README
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.
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.