Sanctuary-dynamic NPM

Sanctuary (Dynamic)

A fork of Sanctuary that does not require any static typing. All the power of Sanctuary, with dynamism of Ramda.

Install

yarn add sanctuary-dynamic

Overview

Sanctuary is a JavaScript functional programming library inspired by Haskell and PureScript. It's stricter than Ramda, and provides a similar suite of functions.

Sanctuary promotes programs composed of simple, pure functions. Such programs are easier to comprehend, test, and maintain – they are also a pleasure to write.

Sanctuary provides two data types, Maybe and Either, both of which are compatible with Fantasy Land. Thanks to these data types even Sanctuary functions which may fail, such as head, are composable.

Sanctuary makes it possible to write safe code without null checks. In JavaScript it's trivial to introduce a possible run-time type error:

words[0].toUpperCase()

If words is [] we'll get a familiar error at run-time:

TypeError: Cannot read property 'toUpperCase' of undefined

Sanctuary gives us a fighting chance of avoiding such errors. We might write:

S.map(S.toUpper, S.head(words))

Sanctuary is designed to work in Node.js and in ES5-compatible browsers.

Types

Sanctuary uses Haskell-like type signatures to describe the types of values, including functions. 'foo', for example, is a member of String; [1, 2, 3] is a member of Array Number. The double colon (::) is used to mean "is a member of", so one could write:

'foo' :: String
[1, 2, 3] :: Array Number

An identifier may appear to the left of the double colon:

Math.PI :: Number

The arrow (->) is used to express a function's type:

Math.abs :: Number -> Number

That states that Math.abs is a unary function which takes an argument of type Number and returns a value of type Number.

Some functions are parametrically polymorphic: their types are not fixed. Type variables are used in the representations of such functions:

S.I :: a -> a

a is a type variable. Type variables are not capitalized, so they are differentiable from type identifiers (which are always capitalized). By convention type variables have single-character names. The signature above states that S.I takes a value of any type and returns a value of the same type. Some signatures feature multiple type variables:

S.K :: a -> b -> a

It must be possible to replace all occurrences of a with a concrete type. The same applies for each other type variable. For the function above, the types with which a and b are replaced may be different, but needn't be.

Since all Sanctuary functions are curried (they accept their arguments one at a time), a binary function is represented as a unary function which returns a unary function: * -> * -> *. This aligns neatly with Haskell, which uses curried functions exclusively. In JavaScript, though, we may wish to represent the types of functions with arities less than or greater than one. The general form is (<input-types>) -> <output-type>, where <input-types> comprises zero or more comma–space (, ) -separated type representations:

() -> String
(a, b) -> a
(a, b, c) -> d

Number -> Number can thus be seen as shorthand for (Number) -> Number.

The question mark (?) is used to represent types which include null and undefined as members. String?, for example, represents the type comprising null, undefined, and all strings.

Sanctuary embraces types. JavaScript doesn't support algebraic data types, but these can be simulated by providing a group of data constructors which return values with the same set of methods. A value of the Either type, for example, is created via the Left constructor or the Right constructor.

It's necessary to extend Haskell's notation to describe implicit arguments to the methods provided by Sanctuary's types. In x.map(y), for example, the map method takes an implicit argument x in addition to the explicit argument y. The type of the value upon which a method is invoked appears at the beginning of the signature, separated from the arguments and return value by a squiggly arrow (~>). The type of the fantasy-land/map method of the Maybe type is written Maybe a ~> (a -> b) -> Maybe b. One could read this as:

When the fantasy-land/map method is invoked on a value of type Maybe a (for any type a) with an argument of type a -> b (for any type b), it returns a value of type Maybe b.

The squiggly arrow is also used when representing non-function properties. Maybe a ~> Boolean, for example, represents a Boolean property of a value of type Maybe a.

Sanctuary supports type classes: constraints on type variables. Whereas a -> a implicitly supports every type, Functor f => (a -> b) -> f a -> f b requires that f be a type which satisfies the requirements of the Functor type class. Type-class constraints appear at the beginning of a type signature, separated from the rest of the signature by a fat arrow (=>).

Type representatives

What is the type of Number? One answer is a -> Number, since it's a function which takes an argument of any type and returns a Number value. When provided as the first argument to is, though, Number is really the value-level representative of the Number type.

Sanctuary uses the TypeRep pseudotype to describe type representatives. For example:

Number :: TypeRep Number

Number is the sole inhabitant of the TypeRep Number type.

Type checking

Sanctuary functions are defined via sanctuary-def to provide run-time type checking. This is tremendously useful during development: type errors are reported immediately, avoiding circuitous stack traces (at best) and silent failures due to type coercion (at worst). For example:

S.add(2, true)
// ! TypeError: Invalid value
//
//   add :: FiniteNumber -> FiniteNumber -> FiniteNumber
//                          ^^^^^^^^^^^^
//                               1
//
//   1)  true :: Boolean
//
//   The value at position 1 is not a member of ‘FiniteNumber’.
//
//   See https://github.com/sanctuary-js/sanctuary-def/tree/v0.14.0#FiniteNumber for information about the sanctuary-def/FiniteNumber type.

Compare this to the behaviour of Ramda's unchecked equivalent:

R.add(2, true)
// => 3

There is a performance cost to run-time type checking. One may wish to disable type checking in certain contexts to avoid paying this cost. create facilitates the creation of a Sanctuary module which does not perform type checking.

In Node, one could use an environment variable to determine whether to perform type checking:

const { create, env } = require('sanctuary')

const checkTypes = process.env.NODE_ENV !== 'production'
const S = create({ checkTypes, env })

API

Takes an options record and returns a Sanctuary module. checkTypes specifies whether to enable type checking. The module's polymorphic functions (such as I) require each value associated with a type variable to be a member of at least one type in the environment.

A well-typed application of a Sanctuary function will produce the same result regardless of whether type checking is enabled. If type checking is enabled, a badly typed application will produce an exception with a descriptive error message.

The following snippet demonstrates defining a custom type and using create to produce a Sanctuary module which is aware of that type:

const { create, env } = require('sanctuary')
const $ = require('sanctuary-def')
const type = require('sanctuary-type-identifiers')

//    Identity :: a -> Identity a
const Identity = function Identity(x) {
  if (!(this instanceof Identity)) return new Identity(x)
  this.value = x
}

Identity['@@type'] = 'my-package/Identity@1'

Identity.prototype['fantasy-land/map'] = function(f) {
  return Identity(f(this.value))
}

//    IdentityType :: Type -> Type
const IdentityType = $.UnaryType(
  Identity['@@type'],
  'http://example.com/my-package#Identity',
  x => type(x) === Identity['@@type'],
  identity => [identity.value],
)

const S = create({
  checkTypes: process.env.NODE_ENV !== 'production',
  env: env.concat([IdentityType($.Unknown)]),
})

S.map(S.sub(1), Identity(43))
// => Identity(42)

Placeholder

Sanctuary functions are designed with partial application in mind. In many cases one can define a more specific function in terms of a more general one simply by applying the more general function to some (but not all) of its arguments. For example, one could define sum :: Foldable f => f Number -> Number as S.reduce(S.add, 0).

In some cases, though, there are multiple orders in which one may wish to provide a function's arguments. S.concat('prefix') is a function which prefixes its argument, but how would one define a function which suffixes its argument? It's possible with the help of __, the special placeholder value.

The placeholder indicates a hole to be filled at some future time. The following are all equivalent (_ represents the placeholder):

f(x, y, z)
f(_, y, z)(x)
f(_, _, z)(x, y)
f(_, _, z)(_, y)(x)

The special placeholder value.

> S.map(S.concat('@'), ['foo', 'bar', 'baz'])
['@foo', '@bar', '@baz']

> S.map(S.concat(S.__, '?'), ['foo', 'bar', 'baz'])
['foo?', 'bar?', 'baz?']

Classify

Returns the result of parsing the type identifier of the given value.

> S.type(S.Just(42))
{namespace: Just('sanctuary'), name: 'Maybe', version: 0}

> S.type([1, 2, 3])
{namespace: Nothing, name: 'Array', version: 0}

Takes a type representative and a value of any type and returns true iff the given value is of the specified type. Subtyping is not respected.

> S.is(Number, 42)
true

> S.is(Object, 42)
false

> S.is(String, 42)
false

Showable

Alias of Z.toString.

> S.toString(-0)
'-0'

> S.toString(['foo', 'bar', 'baz'])
'["foo", "bar", "baz"]'

> S.toString({x: 1, y: 2, z: 3})
'{"x": 1, "y": 2, "z": 3}'

> S.toString(S.Left(S.Right(S.Just(S.Nothing))))
'Left(Right(Just(Nothing)))'

Fantasy Land

Sanctuary is compatible with the Fantasy Land specification.

Curried version of Z.equals which requires two arguments of the same type.

To compare values of different types first use create to create a Sanctuary module with type checking disabled, then use that module's equals function.

> S.equals(0, -0)
true

> S.equals(NaN, NaN)
true

> S.equals(S.Just([1, 2, 3]), S.Just([1, 2, 3]))
true

> S.equals(S.Just([1, 2, 3]), S.Just([1, 2, 4]))
false

Returns true iff the second argument is less than the first according to Z.lt. The arguments must be provided one at a time.

Combinator

The I combinator. Returns its argument. Equivalent to Haskell's id function.

> S.I('foo')
'foo'

The K combinator. Takes two values and returns the first. Equivalent to Haskell's const function.

> S.K('foo', 'bar')
'foo'

> S.map(S.K(42), S.range(0, 5))
[42, 42, 42, 42, 42]

The A combinator. Takes a function and a value, and returns the result of applying the function to the value. Equivalent to Haskell's ($) function.

> S.A(S.add(1), 42)
43

> S.map(S.A(S.__, 100), [S.add(1), Math.sqrt])
[101, 10]

The T (thrush) combinator. Takes a value and a function, and returns the result of applying the function to the value. Equivalent to Haskell's (&) function.

> S.T(42, S.add(1))
43

> S.map(S.T(100), [S.add(1), Math.sqrt])
[101, 10]

Function

Curries the given binary function.

> S.map(S.curry2(Math.pow)(10), [1, 2, 3])
[10, 100, 1000]

> S.map(S.curry2(Math.pow, 10), [1, 2, 3])
[10, 100, 1000]

Curries the given ternary function.

> global.replaceString = S.curry3((what, replacement, string) =>
.   string.replace(what, replacement)
. )
replaceString

> replaceString('banana')('orange')('banana icecream')
'orange icecream'

> replaceString('banana', 'orange', 'banana icecream')
'orange icecream'

Curries the given quaternary function.

> global.createRect = S.curry4((x, y, width, height) =>
.   ({x, y, width, height})
. )
createRect

> createRect(0)(0)(10)(10)
{x: 0, y: 0, width: 10, height: 10}

> createRect(0, 0, 10, 10)
{x: 0, y: 0, width: 10, height: 10}

Curries the given quinary function.

> global.toUrl = S.curry5((protocol, creds, hostname, port, pathname) =>
.   protocol + '//' +
.   S.maybe('', _ => _.username + ':' + _.password + '@', creds) +
.   hostname +
.   S.maybe('', S.concat(':'), port) +
.   pathname
. )
toUrl

> toUrl('https:')(S.Nothing)('example.com')(S.Just('443'))('/foo/bar')
'https://example.com:443/foo/bar'

> toUrl('https:', S.Nothing, 'example.com', S.Just('443'), '/foo/bar')
'https://example.com:443/foo/bar'

Takes a curried binary function and two values, and returns the result of applying the function to the values in reverse order.

This is the C combinator from combinatory logic.

> S.flip(S.concat, 'foo', 'bar')
'barfoo'

Composition

Curried version of Z.compose.

When specialized to Function, compose composes two unary functions, from right to left (this is the B combinator from combinatory logic).

The generalized type signature indicates that compose is compatible with any Semigroupoid.

Maybe type

The Maybe type represents optional values: a value of type Maybe a is either a Just whose value is of type a or Nothing (with no value).

The Maybe type satisfies the Ord, Monoid, Monad, Alternative, Traversable, and Extend specifications.

A UnaryType for use with sanctuary-def.

The type representative for the Maybe type.

Nothing.

> S.Nothing
Nothing

Takes a value of any type and returns a Just with the given value.

> S.Just(42)
Just(42)

Maybe type identifier, 'sanctuary/Maybe'.

Returns Nothing.

It is idiomatic to use empty rather than use this function directly.

> S.empty(S.Maybe)
Nothing

Takes a value of any type and returns a Just with the given value.

It is idiomatic to use of rather than use this function directly.

> S.of(S.Maybe, 42)
Just(42)

Returns Nothing.

It is idiomatic to use zero rather than use this function directly.

> S.zero(S.Maybe)
Nothing

true if this is Nothing; false if this is a Just.

> S.Nothing.isNothing
true

> S.Just(42).isNothing
false

true if this is a Just; false if this is Nothing.

> S.Just(42).isJust
true

> S.Nothing.isJust
false

Returns the string representation of the Maybe.

> S.toString(S.Nothing)
'Nothing'

> S.toString(S.Just([1, 2, 3]))
'Just([1, 2, 3])'

Returns the string representation of the Maybe. This method is used by util.inspect and the REPL to format a Maybe for display.

Either type

The Either type represents values with two possibilities: a value of type Either a b is either a Left whose value is of type a or a Right whose value is of type b.

The Either type satisfies the Ord, Semigroup, Monad, Alt, Traversable, Extend, and Bifunctor specifications.

A BinaryType for use with sanctuary-def.

The type representative for the Either type.

Takes a value of any type and returns a Left with the given value.

> S.Left('Cannot divide by zero')
Left('Cannot divide by zero')

Takes a value of any type and returns a Right with the given value.

> S.Right(42)
Right(42)

Either type identifier, 'sanctuary/Either'.

Takes a value of any type and returns a Right with the given value.

It is idiomatic to use of rather than use this function directly.

> S.of(S.Either, 42)
Right(42)

true if this is a Left; false if this is a Right.

> S.Left('Cannot divide by zero').isLeft
true

> S.Right(42).isLeft
false

true if this is a Right; false if this is a Left.

> S.Right(42).isRight
true

> S.Left('Cannot divide by zero').isRight
false

Returns the string representation of the Either.

> S.toString(S.Left('Cannot divide by zero'))
'Left("Cannot divide by zero")'

> S.toString(S.Right([1, 2, 3]))
'Right([1, 2, 3])'

Returns the string representation of the Either. This method is used by util.inspect and the REPL to format a Either for display.