@gmazovec/flow-typer v0.2.1

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 @gmazovec/flow-typer

Importing

import typer from '@gmazovec/flow-typer' // ES6
var typer = require('@gmazovec/flow-typer') // 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,
  tupleOf2,
  unionOf2,
  string,
  number,
  boolean,
  maybe
} from '@gmazovec/flow-typer'

// 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: unionOf2(male$Literal, female$Literal),
  tags: arrayOf(string),
  location: tupleOf2(number, number)
})

// infer Flow type to JS variable from schema
const personType = typeOf(personSchema)

// define Flow type from JS variable
type PersonType = typeof personType

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

// 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)

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

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)
• typer.arrayOf(schema)

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

• typer.tupleOf1(...schema[])
• typer.tupleOf2(...schema[])
• typer.tupleOf3(...schema[])
• typer.tupleOf4(...schema[])
• typer.tupleOf5(...schema[])

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

• typer.unionOf2(...schema[])
• typer.unionOf3(...schema[])
• typer.unionOf4(...schema[])
• typer.unionOf5(...schema[])

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

Utilities

• typer.isType(schema)
• typer.typeOf(schema)

const schema = arrayOf(userSchema)
const userListT = typeOf(schema)

// flow
type UserListT = typeof userListT

TODO

• Improve error messages for runtime validation.

• Find ways to create generic tupleOf and unionOf validators with variable cardinality.

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