@habitual/typing v1.0.3

@habitual/typing

The @habitual/typing library is designed to provide dynamic (runtime) type checking for applications that perform input validation, or applications that require extreme flexibility and specificity in modeling their problem domain.

Installation

npm install @habitual/typing

Building Runtime Type Checkers

The library provides functionality for defining runtime types from a large selection of predefined basic and complex elements such as Integers, Strings, Lists, Tuples, Objects, Enums, and more.

Example

Define (runtime) types...

// More imports available. See 'API'.
import { 
    isa, 
    Optional,
    Int, 
    Float,
    Digit,
    Str,
    TemplateStr,
    Datetime, 
    List, 
    Tuple, 
    Obj, 
    IntEnum, 
    StrEnum
} from '@habitual/typing'

// Runtime type definitions.
const SubscriptionStatus = IntEnum('active', 'past_due', 'expired')

const CreditCard = Obj({
    brand: Optional(StrEnum('visa', 'mastercard', 'amex')),
    last4: TemplateStr(Digit, Digit, Digit, Digit),
    expiry: Tuple(Int, Int) //month, year
})

const Customer = Obj({
    id: Int,
    name: Str,
    rating: Float,
    signedUpAt: Datetime,
    subscriptionStatus: SubscriptionStatus,
    paymentMethods: List(CreditCard),
})

...then use them to validate runtime values.

const aCustomer = {
    id: 10,
    name: 'Gillian',
    rating: 0.24,
    signedUpAt: new Date(),
    subscriptionStatus: 1,
    paymentMethods: [
        {
            brand: 'amex',
            last4: '1123',
            expiry: [10, 22]
        },
        {
            last4: '2943',
            expiry: [7, 21]
        }
    ]
}

// Two ways to check if value is valid (according to Type).
// 1.
if (isa(Customer, aCustomer)) {
    // aCustomer is a Customer.
}

// 2.
const validatedCustomer = Customer(aUser)
if (validatedCustomer === undefined) {
    // validatedCustomer is not a Customer.
    // note: be careful when using this form with Optional(...) types.
}

About undefined

Runtime types are defined such that the undefined value is not a member of the type. To allow a value to be undefined, specify its type as Optional(T) instead of T (where T is a runtime type).

API

Basic Types

Bool

Allows any boolean value.

Char

Allows a single character.

Digit

Allows a single decimal digit.

isa(Digit, '4') //true
isa(Digit, '12') //false
isa(Digit, 4) //false

Float

Allows any non-null, non-NaN finite number value.

Int

Allows any non-null, non-NaN finite integer number value.

Letter

Allows a single ASCII letter.

isa(Letter, 'a') //true
isa(Letter, 'A') //true
isa(Letter, '4') //false

Literal(v: any)

Allows the specific value v.

const Zero = Literal(0)

isa(Zero, 0) //true
isa(Zero, 1) //false

Zero.value === 0 //true

LowercaseLetter

Allows a single lowercase ASCII letter.

isa(LowercaseLetter, 'a') //true
isa(LowercaseLetter, 'A') //false
isa(LowercaseLetter, '4') //false

Str

Allows any string value.

UppercaseLetter

Allows a single uppercase ASCII letter.

isa(LowercaseLetter, 'a') //false
isa(LowercaseLetter, 'A') //true
isa(LowercaseLetter, '4') //false

Composite Types

TemplateStr(...T)

Allows a string where each character has the type of its corresponding element in ...T.

const PostalCode = TemplateStr(Letter, Digit, Letter, Digit, Letter, Digit)
isa(PostalCode, 'k1M2f4') // true
isa(PostalCode, 'k122f4') // false

const ZipCode = TemplateStr(new Array(5).fill(Digit))
isa(ZipCode, '90210') // true

Tuple(...T)

Allows an array with in-place values defined by the runtime types ...T.

const Point = Tuple(Float, Float)
const Point3D = Tuple(Float, Float, Float)

isa(Point, [0, 0]) //true
isa(Point3D, [0, 0, 3.14]) //true

List(T)

Allows an array containing zero or elements that each conform to the runtime type T.

const Points = List(Tuple(Float, Float))

isa(Points, [ [0,0], [1,2] ]) //true

Obj(blueprint: { [key: string]: T })

Allows an object containing keys with the corresponding runtime types in the given blueprint.

const Point = Obj({
    x: Float,
    y: Float
})

const Point3D = Obj({
    x: Float,
    y: Float,
    z: Float
}

isa(Point, { x: 0, y: 0 }) // true
isa(Point, { x: 0, y: 0, z: 0 }) // true

isa(Point3D, { x: 0, y: 0 }) // false
isa(Point3D, { x: 0, y: 0, z: 0 }) // true

Enum(cases: { [key: string]: any })

Allows any one of the literal values specified by cases.

const Defaults = Enum({
    int: 0,
    str: '',
    datetime: new Date(0)
})

isa(Defaults, Defaults.datetime) //true
isa(Defaults, new Date(0)) //false

isa(Defaults, Defaults.int) //true
isa(Defaults, 0)) //true

MappedEnum(cases: string[], mapper: (label: string, index: number) => any)

Allows any one of the literal values mapped from cases by mapper.

const Compass = MappedEnum(['north', 'east', 'south', 'west'], (l, i) => i * 90)

Compass.north === 0 //true
Compass.east === 90 //true 
Compass.south === 180 //true
Compass.west = 270 //true

StrEnum(cases: string[])

Shortcut for declaring an Enum with Str type case values.

IntEnum(cases: string[])

Shortcut for declaring an Enum with Int type case values.

Defining Arbitrary Types

TypeConstructor((v: any) => boolean): T

Define your own type by providing a function that returns true when passed a value of the type, and false otherwise.

const EvenLength = TypeConstructor(v => v.length % 2 === 0)
isa(EvenLength, [1,2]) //true

Type Operations

Optional(T)

Allows undefined to be a value of the underlying runtime type ...T.

isa(Optional(Int), 1) //true

isa(Int, undefined) //false
isa(Optional(Int, undefined)) //true

Or(...T)

Allows values that conform to one of the given runtime types ...T.

const NumberLike = Or(Int, Float, Bool)

isa(NumberLike, 1) //true
isa(NumberLike, 3.14) //true
isa(NumberLike, true) //true

And(...T)

Allows values that conform to all of the given runtime types ...T.

const X = Obj({ x: Float })
const Y = Obj({ y: Float })

const Point = And(X, Y)

isa(Point, { x: 1.2, y: 3.4 }) //true

Not(T)

Allows values that are not of runtime type T.

const Even = And(Int, TypeConstructor(v => v % 2 === 0))
const Odd = Not(Even)

isa(Even, 0) //true 
isa(Even, 2) //true 

isa(Odd, 1) //true