flow-typer

Declarative static and runtime type checking with Flow.

So you are using Flow to type check your code. That's great but how do you check types for data that is not known before running the code? Like JSON input. Sure, you can use your favorite validation library and do unsafe type casting. Or you write verbose code and do low-level type checking with typeof operator to satisfy Flow's refinement.

flow-typer is solving these problems by writing maintainable type schemas in JavaScript with Flow interoperability.

Features

• support for primitive and complex Flow types
• complete Flow coverage
• type functions are immutable
• define Flow types with JavaScript
• no transpilation required
• works with ES6 JavaScript (modern browsers and Node 6+)

Installation

npm install --save flow-typer-js

Importing

import typer from 'flow-typer-js' // ES6
var typer = require('flow-typer-js') // ES5 with npm

Usage

flow-typer exposes a set of functions for type checking at runtime. These functions are constructed in way that allows Flow to infer types and keep refinement of the code. By composing functions, we define a type schema that can be used to create inferred Flow types (static checking) and for validating values with unknown type at runtime.

import {
  typeOf,
  objectOf,
  arrayOf,
  tupleOf,
  unionOf,
  literalOf,
  string,
  number,
  boolean,
  maybe
} from 'flow-typer-js'

import type { $Literal } from 'flow-typer-js'

// literal types require Flow annotation
const male$Literal = (literalOf('male'): $Literal<'male'>)
const female$Literal = (literalOf('female'): $Literal<'female'>)

// define type schema
const personSchema = objectOf({
  name: string,
  age: maybe(number),
  active: boolean,
  gender: unionOf(male$Literal, female$Literal),
  tags: arrayOf(string),
  location: tupleOf(number, number)
})

// define Flow type from JS type schema
type PersonT = $Call<typeof personSchema>

// check value of unknown type against type schema
const person = personSchema(unknownInput)
// => person: PersonT

// type schema returns value of specific type
person.name.toUpperCase() // No error
person.email // Flow error (unknown attribute)
person.active = 1 // Flow error (boolean value expected)

Errors

Type validation throws TypeValidatorError which contains useful information about why validation failed and what kind of type is expected.

TypeValidatorError: invalid "string" value type; "array" type expected
    ...

    scope    PackageT.dependencies
    expected Array<{"name":"string","version":"string"}>
    type     string
    value    "flow-typer"
    file     .../flow-typer-examples/index.js:15:15

• scope - level at which validation failed
• expected - the expected type of input value
• type - the actual type of input value
• value - input value in JSON format
• file - file with position where the validator was called

type TypeValidatorError {
  expectedType: string
  valueType: string
  value: string
  typeScope: string
  sourceFile: string
}

API

These functions will check for specific JavaScript type with correct Flow type refinement.

• typer.isNil
• typer.isUndef
• typer.isBoolean
• typer.isNumber
• typer.isString
• typer.isObject
• typer.isFunction

Primitive types

• typer.nil
• typer.undef
• typer.boolean
• typer.number
• typer.string
• typer.literalOf(value) (requires Flow annotations *)

const flow$Literal = (literalOf('flow'): $Literal<'flow'>) // => type T = 'flow'

Complex types

• typer.mixed
• typer.object
• typer.maybe(schema)
• typer.objectOf(schemaObject, label)
• typer.optional(schema)

const schema = objectOf({
  username: string,
  nickname: optional(string)
})
// => type T = {| username: string, nickname: (string | void) |}

• typer.arrayOf(schema, label)

const schema = arrayOf(number) // => type T = number[]

• typer.tupleOf(...schema[])

const schema = tupleOf(string, number) // => type T = [string, number]

• typer.unionOf(...schema[])

const schema = unionOf('week', 'month') // => type T = 'week' | 'month'

• typer.mapOf(keySchema, valueSchema)

const schema = mapOf(string, boolean) // => type T = { [_string]: boolean }

Utilities

• typer.isType(schema): boolean
• typer.getType(schema): string

const schema = objectOf({
  dependencies: arrayOf(objectOf(
    name: string,
    version: number,
    exact: boolean
  ))
})

getType(schema)
// => {| dependencies: Array<{| name: string, version: number, exact: boolean |}> |}

TODO

• Use literalOf without explicit Flow type annotations. Literal type can not be inferred by Flow. This could be solved with new Flow utility types $Literal.