Showing:

15

178

5yrs ago

3

1

19.3KB

ISC

No

# maryamyriameliamurphies.js Learn functional programming in ES2015 JavaScript from the principles and code patterns of Haskell

Make your own code more functional by using this library as it is or just implementing its ideas yourself

## Now in version 1.0

• Comprehensive HTML documentation!
• Linting your mother would be proud of!
• Fully tested—with guaranteed 100% code coverage!
• Standalone browser bundles at no extra charge!
• Not scary!

All told, a monad in X is just a monoid in the category of endofunctors of X, with product × replaced by composition of endofunctors and unit set by the identity endofunctor. — Saunders Mac Lane, Categories for the Working Mathematician

In general, an arrow type will be a parameterised type with two parameters, supporting operations analogous to return and >>=. Just as we think of a monadic type m a as representing a 'computation delivering an a', so we think of an arrow type a b c (that is, the application of the parameterised type a to the two parameters b and c) as representing a 'computation with input of type b delivering a c'. — John Hughes, Generalising monads to arrows

In mathematics, a functor is a type of mapping between categories which is applied in category theory. Functors can be thought of as homomorphisms between categories. In the category of small categories, functors can be thought of more generally as morphisms. — Wikipedia, Functor

murphy come, murphy go, murphy plant, murphy grow, a maryamyriameliamurphies, in the lazily eye of his lapis — James Joyce, Finnegans Wake

maryamyriameliamurphies.js is a library of Haskell-style morphisms implemented in JavaScript using ECMAScript 2015 syntax. That is, it's a collection of pure functions designed to showcase in a more widely-used language than Haskell the ways and means of functional programming, for which the newest dialect of JavaScript has improved support. If you're interested in functional programming or even Haskell itself, but find that world intimidating, this library may be a useful conceptual bridge. The syntax I use will probably come across as unconventional, as it mirrors as closely as possible the terse, efficient style of Haskell. Eventually, however, you may find it easy enough to reason about, thanks to its relative lack of side effects and foundation in function composition. If you're curious about strange-sounding things like functors, monads, partial application, currying, and lazy evaluation, then there's something here for you.

First published entirely by chance on St. Patrick's Day, 2016.

### How to install

• Copy and paste the code. Go nuts.
• `git clone` this repo and then execute `npm install && npm run compile` to compile the code.
• Install with npm `npm install --save-dev maryamyriameliamurphies`.

### How to use with npm if you clone

• `npm run compile` to run Babel on ES2015 code in `./source` and output transpiled ES5 code to `./distribution`.
• `npm run lint` to run ESlint to check the source code for errors.
• `npm test` to run Mocha on the test code in `./test`.
• `npm run cover` to run nyc on the source code and generate testing coverage reports.
• `npm run doc` to run JSDoc to generate HTML documentation for the entire library.
• `npm run bundle` to run Browserify to bundle the library for use in the browser.
• `npm run clean` to delete all files in `./distribution`.
• `npm run build` to run `clean`, `compile`, `bundle`, and `doc` all at once.

These commands require that you have certain npm packages installed. See below.

### How to test in the browser

• Create a new HTML file in the `./bundle` directory, for example `maryamyriameliamurphies.html`.
• Paste this code into it, after any other content: `<script src="maryamyriameliamurphies.js"></script>`.
• Open your browser's JavaScript console.
• Test functions using the library namespace, e.g.:
``````const m = require('maryamyriameliamurphies'); // yes, I know it's too long

const hello = str => { return m.print(`Hello \${str}!`), m.just(str); }

const str = m.just(`world`);

const sayHello = () => {
m.Do(str)
.flatMap(hello)
.flatMap(hello);
}

sayHello();

// "Hello world!"
``````

Your mileage may vary, depending on which browser you use to test. This example works in the latest version of Chrome, but ES2015 syntax is not fully supported in Safari as of this writing.

### Description

Since the average explanation of functional programming terminology makes about as much sense to the average reader as the average page of Finnegans Wake, I gave this library a whimsical, literary name. Also, I'm an English literature Ph.D. student, and functional code strikes me as poetic (as "composed" in multiple senses) even though the technical explanations are impenetrably obtuse. All you need to know—in fact, all I understand—is that a pure function (or a morphism in general) simply describes how one thing can predictably transform into another. So a functional program, much like Joyce's final work, is an extended description of how things change.

These functions are experimental, as Haskell's type system translates only awkwardly to a JavaScript idiom, but I'd be delighted if any of them turn out to be useful. I tried hard to make them as pure as possible, which is why most (but not all) of them accept as arguments and return as values single values, and very few are defined as methods on prototypes. I also followed Haskell code patterns as closely as I could for each implementation (as much as it made sense to do so), resulting in a style that is sometimes extremely straightforward and sometimes bewilderingly terse.

There are two Haskell concepts that I use in the code that do not perfectly fit into the JavaScript way of doing things: the type class and the data type. In Haskell, a type class is similar to a protocol or trait in other programming languages. It describes an interface that objects conforming to it must implement.

A type class is a way of making fully parameterized types more useful by placing constraints on them. For example, the `Eq` type class in this library provides functionality for comparing whether the objects that implement it are equal. Objects that provide their own `isEq()` function will perform this test and return a `boolean`. Note that Haskell type classes are in no way comparable to "classes" in OOP.

A data type, on the other hand, is much closer to an OO class definition, as it does describe a custom type. The `Tuple` type is an example of a data type, as it represents a container for other, more basic values. As is often the case with objects in classical languages, instances of Haskell data types are created with special constructor functions that initialize them based on the arguments to those functions. A data type does not inherit (in the usual way) from other data types, however. Instead, it describes how constructor functions convert values passed in as arguments to those functions into the values that comprise that particular type.

As mentioned above, data types can be constrained (or not) by type classes, so as to provide additional functionality—`Eq` is an example of this, as is `Ord`, a type class that allows objects to be compared (greater than, less than, etc.). `Tuple` implements both of these type classes, as one may rightly want to compare tuples or test them for equality, for example.

Since JavaScript is not a strongly typed language by nature, it seemed unnecessary to me (and, for better or worse, antithetical to the JS spirit) to recreate the entirety of Haskell's static type system, though I do provide a limited amount of type checking. Anyone interested in better type safety should probably be using something like PureScript or GHCJS. Instead, I use the new ES2015 `class` pattern for data types with static methods defined on those classes to provide the functionality of type classes. Since the classes and their constructors are not exposed in the API this library provides, instances of data types must be created using specialized functions provided for this purpose. This keeps the static "type class" methods private and affords some degree of namespace protection for the data types.

ES2015 specifies tail call optimization, which will ensure that all the nifty Haskell-esque recursions this library uses won't blow up your call stack (when it's actually implemented).

### Development

Requires:

• Node - JavaScript runtime for the server
• npm - node package manager
• Babel - ES2015 and later to ES5 JavaScript compiler (see below)
• Mocha - testing framework
• Should - assertion library
• ESLint - static analysis of code for JavaScript
• nyc - a command line interface for istanbul compatible with ES2015
• JSDoc - documentation utility

Babel packages and plugins:

### What the name of this library means

The word "maryamyriameliamurphies" occurs on pg. 293 of James Joyce's Finnegans Wake. The two brothers Kev and Dolph (surrogates for the archetypal Shem and Shaun, who represent all rival brothers in history and myth) are having a math lesson. Dolph, the elder, is attempting to explain to Kev the first postulate of Euclid, which results in a rather prurient diagram of circles and triangles. Happily for me, as a functional programmer, it contains a `λ`. If you want to find out about the naughtier significances of this diagram, you'll have to research that for yourself (hint: like functional programming, it involves "lifting"). In the middle of Dolph's explanation, Kev starts to daydream, hence all the invocations of "murphy," an allusion to Morpheus, the Greek god of dreams (also the common Irish surname, Murphy, as well as a slang word meaning both "potato" and "confidence game").

Here's my own interpretation of maryamyriameliamurphies:

• mary — A variant of the interjection "marry" common during the early modern period. It expresses surprise or outrage, more or less equivalent to "wow!" Also a mild oath, since it refers to the Virgin Mary (as pure as a monadic interface, she was).
• myria — Probably the word myriad, "many people or things." Also the ancient Greek word for 10,000, though used just as often to mean an uncountably large number of things (because who would ever need to count higher than 10,000?).
• melia — Similar to the Latin word for a thousand (mille), but it also looks to me like the plural of the Greek word for "honey," which can also be used to describe something sweet (or, at a stretch, the Latin word "meliora" meaning "better than").
• murphies — As an allusion to Morpheus, refers to the Greek word for "form" since dreaming is an experience of many forms shifting and changing. A "morphism" is also another word for a "mapping" or "function" in various branches of mathematics, though it's doubtful this would have occurred to Joyce.

## API

See the online documentation for more extensive explanations and examples. The online docs can also be generated locally with JSDoc if you `git clone` or `npm install` this repo.

### Basic functions

• `partial(f, ...as)` Partially applies arguments `as` to function `f`.
• `\$(f)` Composes function `f` with another function `g`.
• `flip(f)` Reverses the order of arguments to a function.
• `id(a)` Returns `a`. The identity function.
• `constant(a, b)` Returns `a`, discarding `b`.
• `until(pred, f, x)` Apply `f` to `x` until `pred` is true.
• `and(a, b)` Boolean "and".
• `or(a, b)` Boolean "or".
• `not(a)` Boolean "not".
• `even(a)` Return true if `a` is even.
• `odd(a)` Return true if `a` is odd.
• `isEmpty(a)` Return true if `a` is an empty list, tuple, or array.
• `show(a)` Return a string representation of a value (for data types from this library).
• `print(a)` Display the results of `show` on the console.

### Eq

• `isEq(a, b)` Returns true if `a` equals `b`.
• `isNotEq(a, b)` Returns true if `a` does not equal `b`.

### Ord

• `EQ` Ordering for equals.
• `LT` Ordering for less than.
• `GT` Ordering for greater than.
• `compare(a, b)` Return the Ordering of `a` as compared to `b`.
• `lessThan(a, b)` Return true if `a` is less than `b`.
• `lessThanOrEqual(a, b)` Return true if `a` is less than or equal to `b`.
• `greaterThan(a, b)` Return true if `a` is greater than `b`.
• `greaterThanOrEqual(a, b)` Return true if `a` is greater than or equal to `b`.
• `max(a, b)` Return the greater of `a` and `b`.
• `min(a, b)` Return the lesser of `a` and `b`.

### Monoid

• `mempty(a)` Return the identity for the monoid.
• `mappend(a, b)` Perform an associative operation on two monoids.
• `mconcat(a)` Fold a list using the monoid.

### Functor

• `fmap(f, a)` Map the function `f` over the functor `a`.
• `fmapReplaceBy(a, b)` Replace all `b` with `a` in a functor.

### Applicative

• `pure(f, a)` Lift `a` into applicative context `f`.
• `ap(f, a)` Apply applicative function `f` to applicative value `a`.
• `apFlip(f, a, b)` `ap` with its arguments reversed.
• `then(a1, a2)` Sequence actions, discarding the value of `a1`.
• `skip(a1, a2)` Sequence actions, discarding the value of `a2`.
• `liftA(f, a)` Lift function `f` into applicative context `a`.
• `liftA2(f, a, b)` Lift binary function `f` into applicative context `a`.

• `inject(m, a)` Inject value `a` into monadic context `m`.
• `flatMap(m, f)` Bind function `f` to the value contained in monadic context `m`.
• `chain(m, f)` Sequence actions, ignoring the value of the monadic context `m`.
• `bindFlip(f, m)` `bind` with its arguments reversed.
• `join(m)` Remove one level of monadic structure, like `concat`.
• `liftM(f, m)` Lift a function `f` into monadic context `m`.
• `Do(m)` Wrap a monad `m` in a special container for the purpose of chaining actions, in imitation of Haskell's "do" notation.

### Foldable

• `fold(a)` Combine the elements of a structure using a monoid.
• `foldMap(f, a)` Map `f` to each element in monoid `a`.
• `foldr(f, z, t)` Fold function `f` over monoid `t` with accumulator `z`.

### Traversable

• `traverse(f, a)` Map `f` over each element in monoid `a` and collect the results of evaluating each action.
• `mapM(f, m)` `traverse` for monads.
• `sequence(m)` Evaluate each action in monadic structure `m` and collect the results.

### Maybe

• `just(a)` Insert a value into a Maybe monad, returning `Just a` or `Nothing`.
• `maybe(n, f, m)` Apply `f` to the value in Maybe `m` or return `n` if `m` is `Nothing`.
• `isMaybe(a)` Return true if `a` is a Maybe.
• `isJust(m)` Return true if Maybe `m` is `Just`.
• `isNothing(m)` Return true if Maybe `m` is `Nothing`.
• `fromJust(m)` Extract the value from Maybe `m`, throwing an error if `m` is `Nothing`.
• `fromMaybe(d, m)` Extract the value from Maybe `m`, returning `d` if `m` is `Nothing`.
• `listToMaybe(as)` Return `Nothing` on an empty list or `Just a` where `a` is the first element of the list.
• `maybeToList(m)` Return an empty list if `m` if `Nothing` or a singleton list [`a`] if `m` is `Just a`.
• `catMaybes(as)` Return a list of all `Just` values from a list of Maybes.
• `mapMaybe(f, as)` Map `f` (that returns a Maybe) over a list and return a list of each `Just` result.

### Tuple

• `tuple(...as)` Create a new tuple from any number of values.
• `fst(p)` Return the first element of a tuple.
• `snd(p)` Return the second element of a tuple.
• `curry(f, x, y)` Convert `f` taking arguments `x` and `y` into a curried function.
• `uncurry(f, p)` Convert curried function `f` taking argument tuple pair `p` into an uncurried function.
• `swap(p)` Swap the first two values of a tuple.
• `isTuple(a)` Return true if `a` is a tuple.
• `fromArrayToTuple(a)` Convert an array into a tuple.
• `fromTupleToArray(p)` Convert a tuple into an array.

### List

#### Basic functions

• `list(...as)` Create a new list from a series of values.
• `listRange(start, end, f, filter)` Create a new list from `start` to `end` using step function `f` with values optionally filtered by `filter`.
• `listFilter(start, end, filter)` Create a new list of consecutive values, filtered using `filter`.
• `listRangeLazy(start, end)` Create a new list of consecutive values from `start` to `end`, using lazy evaluation.
• `listRangeLazyBy(start, end, step)` Create a new list from `start` to `end` incremented by step function `step`, using lazy evaluation.
• `listAppend(as, bs)` Append list `as` to list `bs`.
• `cons(x, xs)` Create a new list with head `x` and tail `xs`.
• `head(as)` Extract the first element of a list.
• `last(as)` Extract the last element of a list.
• `tail(as)` Extract the elements of a list after the head.
• `init(as)` Extract all elements of a list except the last one.
• `uncons(as)` Decompose a list into its head and tail.
• `empty(t)` Test whether a foldable structure is empty.
• `length(as)` Return the length of list.
• `isList(a)` Return true if `a` is a list.
• `fromArrayToList(a)` Convert an array into a list.
• `fromListToArray(as)` Convert a list into an array.
• `fromListToString(as)` Convert a list into a string.
• `fromStringToList(as)` Convert a string into a list.

#### List transformations

• `map(f, as)` Map the function `f` over the elements in list `as`.
• `reverse(as)` Reverse the elements of a list.
• `intersperse(sep, as)` Intersperse the separator `sep` between the elements of `as`.
• `intercalate(xs, xss)` Intersperse the list `xs` between the lists in `xss` (a list of lists).
• `transpose(lss)` Transpose the "rows" and "columns" of a list of lists.

#### Reducing lists

• `foldl(f, z, as)` Fold a list `as` from right to left, using function `f` and accumulator `z`.

#### Special folds

• `concat(xss)` Concatenate the elements in a list of lists.
• `concatMap(f, as)` Map the function `f` (that returns a list) over the list `as` and concatenate the result list.

#### Building lists

• `scanl(f, q, ls)` Reduce a list `ls` from right to left using function `f` and accumulator `q` and return a list of successive reduced values.
• `scanr(f, q0, as)` Like `scanl` but scans the list `as` from right to left.

#### Infinite lists

• `listInf(start)` Return an infinite list of consecutive values beginning with `start`.
• `listInfBy(start, step)` Return an infinite list of values, incremented with function `step`, beginning with `start`.
• `iterate(f, x)` Return an infinite list of repeated applications of `f` to `x`.
• `repeat(a)` Return an infinite list in which all the values are `a`.
• `replicate(n, x)` Return a list of length `n` in which all values are `x`.
• `cycle(as)` Return the infinite repetition of a list.

#### Sublists

• `take(n, as)` Return the prefix of a list of length `n`.
• `drop(n, as)` Return the suffix of a list after discarding `n` values.
• `splitAt(n, as)` Return a tuple in which the first element is the prefix of a list and the second element is the remainder of the list.
• `takeWhile(pred, as)` Return the longest prefix of a list of values that satisfy the predicate function `pred`.
• `dropWhile(pred, as)` Drop values from a list while the predicate function `pred` returns true.
• `span(pred, as)` Return a tuple in which the first element is the longest prefix of a list of values that satisfy the predicate function `pred` and the second element is the rest of the list.
• `spanNot(pred, as)` Return a tuple in which the first element is the longest prefix of a list of values that do not satisfy the predicate function `pred` and the second element is the rest of the list.
• `stripPrefix(as, bs)` Drop the prefix `as` from the list `bs`.
• `group(as)` Take a list and return a list of lists such that the concatenation of the result is equal to the argument. Each sublist in the result contains only equal values.
• `groupBy(eq, as)` Take a list and return a list of lists such that the concatenation of the result is equal to the argument. Each sublist in the result is grouped according to function `eq`.

#### Searching

• `lookup(key, assocs)` Look up `key` in the association list `assocs`.
• `filter(f, as)` Return the list of elements from `as` to satisfy the predicate function `f`.

#### Indexing

• `index(as, n)` Return the value in `as` at index `n`.
• `elemIndex(a, as)` Return the index of the first value in `as` equal to `a` or `Nothing` if there is no such value.
• `elemIndices(a, as)` Return the indices of all values in `as` equal to `a`, in ascending order.
• `find(pred, xs)` Return the first value in `xs` that satisfies the predicate function `pred` or `Nothing` if there is no such value.
• `findIndex(pred, xs)` Return the index of the first value in `xs` that satisfies the predicate function `pred` or `Nothing` if there is no such value.
• `findIndices(pred, xs)` Return the indices of all values in `xs` that satisfy `pred`, in ascending order.

#### Zipping and unzipping lists

• `zip(as, bs)` Take two lists and return a list of corresponding pairs.
• `zip3(as, bs, cs)` `zip` for three lists.
• `zipWith(f, as, bs)` Zip `as` and `bs` using function `f`.
• `zipWith3(f, as, bs, cs)` Zip three lists using function `f`.

#### "Set" operations

• `nub(as)` Remove duplicate values from a list.
• `nubBy(eq, as)` Remove duplicate values from a list, testing equality using function `eq`.
• `deleteL(a, as)` Remove the first occurrence of `a` from `as`.
• `deleteLBy(eq, a, as)` Remove the first occurrence of `a` from `as`, testing equality using function `eq`.
• `deleteFirsts(as, bs)` Remove the first occurrence of each value of `as` from `bs`.
• `deleteFirsts(eq, as, bs)` Remove the first occurrence of each value of `as` from `bs`, using function `eq` to test for equality.

#### Ordered lists

• `sort(as)` Sort a list.
• `sortBy(cmp, as)` Sort a list using comparison function `cmp`.
• `mergeSort(as)` Sort a list using a merge sort algorithm.
• `mergeSortBy(cmp, as)` Merge sort a list using comparison function `cmp`.
• `insert(e, ls)` Insert `e` at the first position in `ls` where it is less than or equal to the next element.
• `insertBy(cmp, e, ls)` Insert `e` at the first position in `ls` using comparison function `cmp`.

### Utility functions

• `throwError(e)` Throws an error with message `e`.
• `defines(...methods)` Defines a type class that requires implementations of `methods`.
• `dataType(a)` Returns the data type of `a` (a synonym for `a.constructor`).
• `type(a)` Returns the type of `a` as defined by this library or `typeof` otherwise.
• `typeCheck(a, b)` Checks whether `a` and `b` are the same type.

## Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100