Fantasy Land method aliases

There are several related questions which must be answered before we can merge #216. Discussing these in a dedicated thread seems wise, as that pull request is very large.

Currently we provide Maybe and Either types compatible with the Fantasy Land spec prior to the merging of fantasyland/fantasy-land#146. In #216 we’re adding support for the prefixed method names. Should we continue to expose methods via the unprefixed names? Concretely, should we provide Maybe#map and Maybe#fantasy-land/map or just the latter?

Reasons to alias (👽):

• to maintain Ramda compatibility until ramda/ramda#1900 is merged; and
• to support method chaining.

Reasons not to alias (🚫 👽):

• it would violate The Zen of Python (python -c 'import this' | grep 'only one');
• it would increase Sanctuary’s surface area (more to document and test); and
• method chaining is at odds with Sanctuary’s emphasis on function composition.

If we decide to include these aliases, there’s a second question to answer: should we also provide Maybe.empty, Maybe.of, and Either.of? These are already aliases (for () => Nothing, Just, and Right respectively). There’s value, of course, in providing the prefixed equivalents to facilitate the creation of polymorphic functions, but if one is dealing with the Maybe type, say, I see no reason to write Maybe.empty() rather than Nothing. Am I missing anything?

The final question is what to do with Maybe#filter. It’s currently defined for compatibility with R.filter and R.reject. My plan, though, is to define filter in sanctuary-type-classes, since it can be derived from other FL functions:

//# filter :: (Monad m, Monoid m a) => ((a -> Boolean), m a) -> m a
var filter = function(pred, m) {
  return chain(function(x) { return pred(x) ? of(m, x) : empty(m); }, m);
};

Thanks, @joneshf, for sharing this approach way back in #10!

With Z.filter in place, #216 could easily add S.filter and S.reject. At that point Maybe#filter would only be useful for Ramda compatibility. Is that important, do you think?

I have views on these matters, but I’d love to hear from @safareli and @Bradcomp (and others) before weighing in.

[davidchambers]

I’m reconsidering this issue.

My long-term goal is to move the Maybe and Either types to their own packages. These packages will only provide the data constructors and the various fantasy-land/-prefixed methods. They will be compatible with Sanctuary and sanctuary-type-classes (and Ramda if it is updated to support version 2 of the FL spec). I do not intend to provide unprefixed methods. Those who prefer method chaining to function composition are better served by Folktale, which is to Scala as Sanctuary is to Haskell.

Given this goal, what is the best transition? Initially I had thought it wise to keep the unprefixed methods around for the next six months, say, to making upgrading to sanctuary@0.12.x less onerous. I’m now questioning this logic. sequence has been replaced with fantasy-land/traverse. Should we keep the sequence methods around for some time? The type of fantasy-land/ap differs from that of ap. Should we keep both versions of the method? What about new methods? Should we provide alt in addition to fantasy-land/alt? alt is not required for backwards compatibility, but providing some aliases but not others for historical reasons would be confusing for new users.

I’m now in favour of removing all the aliases from #232. This will mean code which invokes Sanctuary methods directly will need to be updated when upgrading to v0.12.0, but this cost will need to be paid at some point regardless.

[davidchambers]

Thank you both for your thoughtful feedback.

I intend to do the following:

• Add prefixes to the documentation of the methods. We’ll document Maybe#fantasy-land/map, for example, rather than Maybe#map.
• Update the code examples to use S functions. The doctests for Maybe#fantasy-land/map, for example, will feature S.map rather than direct method invocations.
• Leave the method aliases. These will still be verified by the test suite, but will no longer be documented. We may decide to remove these at some point in the future.
• Remove Maybe.empty, Maybe.of, and Either.of. These simply aren’t necessary.
• Remove Maybe#filter. #216 will add S.filter and S.reject so I don’t think maintaining compatibility with the Ramda equivalents is important.

It would be nice to have an S.of function (does it already exist?) that takes a type as a parameter.

It doesn’t exist yet, but we can add it in #216 once we agree on the appropriate type of Z.of in sanctuary-js/sanctuary-type-classes#3.