@habitual/typing
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.3 • Public • Published

    @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

    Install

    npm i @habitual/typing

    DownloadsWeekly Downloads

    11

    Version

    1.0.3

    License

    ISC

    Unpacked Size

    50.8 kB

    Total Files

    35

    Last publish

    Collaborators

    • avatar