Module: core.check

Stability:1 - Experimental
Bug Tracker:https://github.com/folktale/core.check/issues
Version:0.1.0
Repository:https://github.com/folktale/core.check
Portability:Portable
npm package:core.check

Interface checking for JS values.

Loading

Require the core.check package, after installing it:

var check = require('core.check')

Why?

JavaScript is an untyped language, and this makes it fairly flexible for certain things. More often than not, however, you want to make sure that the values going into a certain code path have some kind of structure, to reduce the complexity of the whole program. core.check helps you to do this by providing composable contracts:

1
2
3
4
5
check.assert(check.String(1))
// => Error: Expected 1 to have tag String

check.assert(check.Or([check.String, check.Boolean])(1))
// => Error: Expected 1 to have tag String, or 1 to have tag Boolean

core.check can also be used for validating data structures without crashing the process. All contracts return a Validation(Violation, α) result. One can then use the cata() operation on the data.validation.Validation object to deal with the result of the operation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
function logString(a) {
  return check.String(a).cata({
    Failure: function(error){ return 'Not a string: ' + a },
    Success: function(value){ return 'String: ' + value }
  })
}

logString(1)
// => 'Not a string: 1'

logString('foo')
// => 'String: foo'

Dependent validations

Value()

core.check.Value(expected)
α → (α → Validation(Violation, α))

An interface that matches the given value by structural equality.

Identity()

core.check.Identity(expected)
α → (α → Validation(Violation, α))

An interface that matches the given value by reference equality.

Higher-order validations

Or()

core.check.Or(interfaces)
Returns:An interface that matches any of the given interfaces.
Array(α → Validation(Violation, α)) → α → Validation(Violation, α)

And()

core.check.And(interfaces)
Returns:An interface that matches only if all of the given interfaces match.
Array(α → Validation(Violation, α)) → α → Validation(Violation, α)

Seq()

core.check.Seq(interfaces)
Returns:An interface that matches an N-Tuple with the given interfaces.
Array( α₁ → Validation<Violation, α₁)
     , α₂ → Validation(Violation, α₂)
     , ...
     , αₙ → Validation(Violation, αₙ)>
→ Array(α₁, α₂, ..., αₙ)
→ Validation(Violation, Array(α₁, α₂, ..., αₙ))

ArrayOf()

core.check.ArrayOf(interface)
Returns:An interface that matches an Array with values matching the given interface.
(α → Validation(Violation, α)) → α → Validation(Violation, α)

ObjectOf()

core.check.ObjectOf(aPattern)
Returns:An interface that matches an Object with the exact key/type mapping given.
Object(Validation(Violation, Any)) → Object(Any) → Validation(Violation, Object(Any))

Primitive validations

Null()

core.check.Null(aValue)
Any → Validation(Violation, Any)

An interface that matches only null values.

Undefined()

core.check.Undefined(aValue)
Any → Validation(Violation, Any)

An interface that matches only undefined values.

Boolean()

core.check.Boolean(aValue)
Any → Validation(Violation, Any)

An interface that matches only Boolean values.

Number()

core.check.Number(aValue)
Any → Validation(Violation, Any)

An interface that matches only Number values.

String()

core.check.String(aValue)
Any → Validation(Violation, Any)

An interface that matches only String values.

Function()

core.check.Function(aValue)
Any → Validation(Violation, Any)

An interface that matches only Function values.

Array()

core.check.Array(aValue)
Any → Validation(Violation, Any)

An interface that matches only Array values.

Object()

core.check.Object(aValue)
Any → Validation(Violation, Any)

An interface that matches only Object values.

Any()

core.check.Any(aValue)
Any → Validation(Violation, Any)

An interface that matches any values.

Types and structures

Violation

class core.check.Violation
type Violation = Tag(String, Any)
               | Equality(Any, Any)
               | Identity(Any, Any)
               | Any(Array(Any))
               | All(Array(Any))

implements
  Equality, Extractor, Reflect, Cata, Semigroup, ToString

Represents a violation of an interface’s constraint.

Validating interfaces

assert()

core.check.assert(aValidation)
Returns:

The value, if no violations exist.

Raises:
  • TypeError - If any violation exists.
Validation(Violation, α) → α :: throws