v0.12.0 release notes

https://github.com/sanctuary-js/sanctuary/compare/v0.11.1...v0.12.0

Overview

This is a huge release, representing hundreds of hours of work over the course of more than eight months, spanning multiple projects. I’m thrilled to be able to share the result. Many thanks to those who contributed to this release, either by submitting pull requests or by participating in discussions on GitHub and Gitter.

Ramda

Sanctuary began life as a tiny library intended for use alongside Ramda. At the time Ramda provided several partial functions such as R.head (this is still the case today). Since Sanctuary’s inception two years ago, Ramda and Sanctuary have diverged philosophically to the point that it’s now reasonable for Sanctuary to duplicate much of Ramda’s functionality. Until now, though, Sanctuary has lacked crucial functions such as map, ap, and chain.

Fantasy Land

Thanks in large part to sanctuary-type-classes, Sanctuary now supports version 3 of the Fantasy Land specification. There are two aspects to this:

• the Maybe and Either types provide lawful fantasy-land/-prefixed methods; and
• there are 20 or so new functions for interacting with Fantasy Land methods.

In the Sanctuary world, Fantasy Land methods are not intended for direct use. Until now one was expected to use R.map(f, maybe) rather than maybe.map(f). Now that Sanctuary provides a map function, the recommended expression is S.map(f, maybe). Since S.map enforces its invariants (if type checking is enabled) there’s no reason for S.Maybe.prototype['fantasy-land/map'] to do so as well. As a result, methods of the Maybe and Either types no longer perform type checking.

sanctuary-def

https://github.com/sanctuary-js/sanctuary-def/compare/v0.6.0...v0.9.0

Sanctuary now depends on sanctuary-def@0.9.0 which is significantly more capable than the version on which Sanctuary previously depended. It now supports higher-order functions and unary (and binary) type variables. For example:

S.filter(S.I, [0, 1, 2, 3]);
// ! TypeError: Invalid value
//
//   filter :: (Applicative f, Foldable f, Monoid f) => (a -> Boolean) -> f a -> f a
//                                                            ^^^^^^^
//                                                               1
//
//   1)  0 :: Number, FiniteNumber, Integer, ValidNumber
//
//   The value at position 1 is not a member of ‘Boolean’.
//
//   See https://github.com/sanctuary-js/sanctuary-def/tree/v0.9.0#Boolean for information about the Boolean type.

Sanctuary functions now have useful string representations for those who enjoy the REPL:

> S.lift2
lift2 :: Apply f => (a -> b -> c) -> f a -> f b -> f c

> S.match
match :: NonGlobalRegExp -> String -> Maybe { groups :: Array (Maybe String), match :: String }

> S.matchAll
matchAll :: GlobalRegExp -> String -> Array { groups :: Array (Maybe String), match :: String }

Breaking changes

• ⚠️ Values of the Maybe and Either types are no longer compatible with Ramda (#257)
• ⚠️ Nothing() is now known simply as Nothing (#225)
• ⚠️ and and or are now monomorphic (#279)
• ⚠️ xor has been removed (#279)
• ⚠️ meld has been removed (#280)
• ⚠️ flip is now known as flip_ (#330)
• ⚠️ C is now known as flip (#330)
• ⚠️ B is now known only as compose (#330)
• ⚠️ S has been removed in favour of ap (#216)
• ⚠️ lift is now known as map (#216)
• ⚠️ match now has a more appropriate type (#283)
• ⚠️ pluck now has prop semantics rather than get semantics (#293)
• ⚠️ get, gets, and parseJson now take predicates rather than type representatives (#191)

New exports

• __ :: Placeholder (#232)
• alt :: Alt f => f a -> f a -> f a (#216)
• ap :: Apply f => f (a -> b) -> f a -> f b (#216)
• apFirst :: Apply f => f a -> f b -> f a (#216)
• apSecond :: Apply f => f a -> f b -> f b (#216)
• bimap :: Bifunctor f => (a -> b) -> (c -> d) -> f a c -> f b d (#216)
• chain :: Chain m => (a -> m b) -> m a -> m b (#216)
• chainRec :: ChainRec m => TypeRep m -> (a -> m (Either a b)) -> a -> m b (#216)
• curry2 :: ((a, b) -> c) -> a -> b -> c (#289)
• curry3 :: ((a, b, c) -> d) -> a -> b -> c -> d (#289)
• curry4 :: ((a, b, c, d) -> e) -> a -> b -> c -> d -> e (#289)
• curry5 :: ((a, b, c, d, e) -> f) -> a -> b -> c -> d -> e -> f (#289)
• empty :: Monoid a => TypeRep a -> a (#216)
• equals :: Setoid a => a -> a -> Boolean (#216)
• extend :: Extend w => (w a -> b) -> w a -> w b (#216)
• extract :: Comonad w => w a -> a (#216)
• filter :: (Applicative f, Foldable f, Monoid (f a)) => (a -> Boolean) -> f a -> f a (#216)
• filterM :: (Monad m, Monoid (m a)) => (a -> Boolean) -> m a -> m a (#216)
• fromEither :: b -> Either a b -> b (#229)
• fromMaybe_ :: (() -> a) -> Maybe a -> a (#316)
• join :: Chain m => m (m a) -> m a (#216)
• joinWith :: String -> Array String -> String (#256)
• matchAll :: GlobalRegExp -> String -> Array { match :: String, groups :: Array (Maybe String) } (#283)
• maybe_ :: (() -> b) -> (a -> b) -> Maybe a -> b (#285)
• mean :: Foldable f => f FiniteNumber -> Maybe FiniteNumber (#234)
• of :: Applicative f => TypeRep f -> a -> f a (#216)
• on :: (b -> b -> c) -> (a -> b) -> a -> a -> c (#282)
• on_ :: ((b, b) -> c) -> (a -> b) -> a -> a -> c (#282)
• promap :: Profunctor p => (a -> b) -> (c -> d) -> p b c -> p a d (#216)
• props :: Accessible a => Array String -> a -> b (#310)
• sequence :: (Applicative f, Traversable t) => TypeRep f -> t (f a) -> f (t a) (#216)
• splitOn :: String -> String -> Array String (#256)
• toEither :: a -> b? -> Either a b (#249)
• toString :: Any -> String (#216)
• traverse :: (Applicative f, Traversable t) => TypeRep f -> (a -> f b) -> t a -> f (t b) (#216)
• zero :: Plus f => TypeRep f -> f a (#216)

Contributors

• @Avaq
• @Bradcomp
• @Jacse
• @Shard
• @davidchambers
• @jdudek
• @laduke
• @rjmk
• @svozza
• @syaiful6
• @wennergr

[Avaq]

How is the string representation of functions in the REPL implemented?

Hi @fvictorio, in NodeJS, you can override the inspect method of any object, including functions, to create a custom representation of your object to show when util.inspect() is called on it. The Node REPL uses util.inspec() internally to format return values of expressions.

This feature is used by sanctuary-def to attach representations derived from the type information passed to def when defining a function. Implementation can be seen here: https://github.com/sanctuary-js/sanctuary-def/blob/v0.9.0/index.js#L2342

Most functions (if not all) exported by Sanctuary were defined using sanctuary-def, in order to curry them, decorate them with type checking, and have the custom inspection value.

I’m pretty sure this is not the right place to ask this

That’s alright. If you’re looking for a place to ask general questions, the Gitter channel is quite active 😃

[fvictorio]

How is the string representation of functions in the REPL implemented?

(I’m pretty sure this is not the right place to ask this, but that feature blew my mind and I really, really want to know how to do it.)