In 2020, U.S. retail e-commerce revenue from the sale of fashion apparel, footwear, and accessories accounted for an estimated 29.5% of U.S. fashion retail sales, with a steady annual growth rate since 2003. Despite this growth, e-commerce customers returned an estimated 56% of clothing and shoes in 2020. Furthermore, mismatches in description or customer expectations were the second-highest reason behind an item being damaged or broken. Video content is proven to increase traffic to a website and help shoppers be more confident to make purchases. Still, what’s missing from online shopping is touching the clothes and trying them on, and that’s why brick and mortar retail continues to play an essential role for customers.

In the absence of a dressing room, fashion brands have tried multiple images or videos of the same clothing item but on different body types. This way, customers can see what the item might look like on them without having to mentally “Photoshop” it onto their bodies. Japanese clothing brand Anayi is experimenting with another approach — publishing 19 original volumetric videos on their website for their Spring and Summer Collection 2021. The sheer novelty of volumetric video should increase traffic to their website, but Anayi believes it may also help narrow the expectation gap. Volumetric enables consumers to view the fashion model in motion–from any angle, including close-ups, to see how the fabric will drape and move with the wearer. If they’re right, customers will make better-informed decisions that hopefully reduce the percentage of returns.

The fashion shoot becomes the “fashion capture”

Anayi commissioned Crescent Studios in Tokyo, owner of the world’s largest volumetric production studio, to capture their fashion models in three-dimensional space. Using multiple cameras, Crescent recorded close-ups of these models along with the entire stage. This approach allows viewers to explore the whole scene in HD quality, zooming close to see the details in the fabric or backing out to see how it moves. After finishing the volume capture, Crescent imported the data into Arcturus HoloSuite for processing and publishing.

Crescent’s post-production process starts by editing and compressing the volumetric data using Arcturus HoloEdit. Like a non-linear editor, such as Adobe Premiere but in 3D, HoloEdit composites multiple layers of volumetric captures into a volumetric video sequence. Then, after the compression, Crescent exports this volumetric sequence into HoloStream for streaming. HoloStream encodes the video into a set of quality profiles and creates a unique URL that allows it to be previewed, shared, or embedded as an online volumetric video. The quality profiles enable the video to be adaptively streamed, ensuring playback and quality are maintained, regardless of a viewer’s internet speed or stability.

Embedding the volumetric videos on the Anayi website

For the final step, Anayi’s web developers took the URLs generated from HoloStream and included them within a MPEG-DASH container on their website’s Spring/Summer section. MPEG-DASH is a streaming method that breaks videos down into smaller chunks and encodes those chunks at different quality levels. There is no app or plugin to install; apparel customers visit the Anayi website to view the volumetric videos directly within their web browser.

The quality profiles generated during the previous step make it possible to stream the volumetric videos at different quality levels, switching from one level to another to adapt to any bandwidth changes during streaming. The volumetric videos are served directly from a HoloStream server, which uses a Content Distribution Network (CDN) to ensure high availability and the highest quality streams onto the customer’s device.

As a bonus, Crescent teamed with Palo Alto-based 8th Wall to add WebAR support to Anayi’s volumetric videos. This integration by Arcturus and 8th Wall is now available to anyone wishing to combine HoloStream holograms with WebAR. Anayi customers are offered a “3D Hologram” button or a QR Code to scan with a mobile device to place a 3D hologram of the fashion model in their room using web-based augmented reality. If you’d like to try it yourself, use your iOS or Android smartphone to scan the QR code in the above figure. You’ll be able to view the hologram of one of their fashion models in your environment.

What do we think?

Apparel e-commerce is a compelling use case for volumetric video, especially when it’s coupled with an AR application so that the consumer can see these models within their environment. In this scenario, the virtual fashion runway is not only a novel way to shop for clothes, but it may also reduce the percentage of clothing returns and improve the bottom line. However, when viewing on the website without AR, it’s a toss-up whether the virtual runway is any better than an actual runway. Instead of a plain white background, we would’ve preferred to see more contextual information, like a typical fashion show, when we’re not using WebAR.

We suspect that Anayi is A/B testing (also known as split testing), which is a process of showing two variants of the same web page to different segments of website visitors at the same time and comparing which variant drives more conversions. Thus, if we see Anayi is using volumetric videos again for their fall lineup, it could be a signal of the success of their experiment.

The most significant challenge for volumetric in the near term is the limited number of capture studios worldwide and the cost of production, averaging around $10,000 for processing one day of shooting. This situation will improve as these systems become cheaper, portable, and more compact. For the time being, volumetric videos will primarily come from the enterprise for utilization in eCommerce, sports, and concerts. With apparel eCommerce approaching USD 33 billion in the U.S. alone, the potential return on investment more than justifies the cost of production. So expect to see more fashion brands streaming volumetric videos to a web browser near you.

Originally published in Graphics Speak on May 13, 2021 by Alex Kelley

This is Tutorial 27 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximately once-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 26

In the last Tutorial, we finished all of the basic concepts of functional programming. Now, we’ll use what we learned to develop an application that uses the Spotify API to find common ground between two music artists. In this first of our final three tutorials, we’ll determine the necessary HTTP endpoints from the Spotify API. Once we have our endpoints, we’ll sketch a high-level data flow diagram. Then we’ll begin coding this data flow in PureScript.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course ‘Professor Frisby Introduces Composable Functional JavaScript’ by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

Important Note: the Spotify API has evolved since Brian published his tutorial. In particular, they have removed unauthenticated calls to all of their API endpoints. Consequently, to make this application work, you’ll need a Spotify account to obtain an API access token.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, if you like what you see, then please give it a star to help me publicize these tutorials.

What We’re Building

We’re going to build an application that finds common music artists shared between two or more artists by querying the Spotify API. For example, if a user inputs The Beatles and The Rolling Stones, then our application returns an array of artists that the Spotify algorithm determines they have in common. The code for the completed application is in Tutorial 29. You can run this final implementation by typing the following in your terminal:

# Compiles and produces a single executable 'index.js' in root dir
$ npm run bundle 
# Use node to run it 
$ node index.js Beatles 'Rolling Stones' 
# Returns 34 related artists; 5 artists in common. 
$ (Tuple 34 ["Jimi Hendrix","The Kinks","George Harrison","Chuck Berry","Eric Clapton","John Lennon"])

Development Roadmap

Here’s our development plan:

1. Start by looking at the Spotify Web API Documentation to discover suitable endpoints.
2. Test these endpoints in the terminal using Curl and Spotify’s Console to ensure they deliver the metadata we need.
3. Create a data flow diagram of our application.
4. Finish coding the user argument capture, while mocking the rest of the data flow in PureScript.

We’ll cover each step of our plan in detail in the next four sections.

Step 1 — Search the Spotify API docs

After a brief tour of Spotify’s API documentation, it appears that the Artists page (see Figure 1) has the metadata we need for our application. In particular, there’s an endpoint /v1/artists/{id}/related-artists that, given an artist's id, returns their related artists. How to obtain this id? Well, there's also the Search for an Item page, shown in Figure 1, hinting that we can retrieve an artist id by entering a query together with the type of metadata we need.

For example, if we want to search for The Beatles, then our API endpoint is v1/search?q=Beatles&type=artist&limit=1. To determine whether these endpoints are sufficient, let's test them using the tools outlined in the next section.

Step 2— Test the Endpoint Responses

Armed with our prospective API endpoints, we’re ready to begin testing them in the Spotify console shown above. I found this approach to be the easiest but, naturally, you can also try them out in your terminal using Curl. For example, if we want to retrieve the artist id for The Beatles, then a Curl request is along the lines of:

curl -X "GET" "https://api.spotify.com/v1/search?q=Beatles&type=artist&limit=1" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer YourSecretTokenGoesHere"

Notice that the JSON response contains the artist id within the items array, nested under artists:

{ 
  "artists": { 
    "href": "https://api.spotify.com/v1/search?query=Beatles&type=artist&offset=0&limit=1", 
    "items": [ 
      { 
        ... 
        "genres": [ "british invasion", 
                    "classic rock", 
                    "merseybeat", 
                    "psychedelic rock", 
                    "rock"
                  ], 
        "href": "https://api.spotify.com/v1/artists/3WrFJ7ztbogyGnTHbHJFl2", 
        "id": "3WrFJ7ztbogyGnTHbHJFl2", 
        ... 
      ... 
    }] 
... 
}

Satisfied that these two endpoints deliver the metadata we require, we can move onto sketching our data flow before beginning to code in PureScript.

Step 3— Sketch the Data Flow Diagram

Recently, I’ve noticed greater interest by the JavaScript community in using finite states to model the logic in their programs declaratively. It’s a great way to identify corner cases, and it helps to eliminate mistakes stemming from improper logic. For example, as of this writing, David Khourshid’s work on XState has over 11.5K stars on Github. Be it State Charts, Behavior Trees, or Data Flow Diagrams; they’re all useful for describing the behavior of your code to programmers and non-programmers alike.

A Data Flow Diagram illustrates the flow of data explicitly, with objects representing transformations, and the data flow depicted as a line or pipe. They’re also simple to draw. You can model data flow with just four basic symbols, representing a Process, Data Store, External Entity, and a Note. For example, the Data Flow Diagram directly below utilizes all four basic symbols.

The leftmost External Entity block represents a user or other outside system that provides data to or receives output from the system. Next is the Note, whose arrow designates the path direction of the data, and the label describes the data itself. The Process block receives this input data and transforms it before passing it to the final External Entity. In this case, we’re using a Data Store Entity for storing data to be used at another time. Note that we call External Entities terminators because they designate where the data originates and where it ends.

There’s just one basic rule when drawing data flow diagrams — all flow must begin with and end at a Process block. The point here is that an External Entity should not provide data to another External Entity without being processed beforehand. Instead, place a Process block between the two External Entities.

For more information on Data Flow Diagrams, check out the Visual Paradigm website. You can use their tools or pick your favorite drawing program to achieve similar results. I used Sketch.app to draw the figures you see in this Section. If you are a Sketch user, then feel free to take my symbols page from the file flow_diagram.sketch, located in my GitHub repository.

App Data Flow Diagram

Our application is simple and, consequently, the Data Flow Diagram, shown in Figure 3, is too. In the next tutorial, we’ll add another layer to the diagram to better illustrate our HTTP GET calls to the Spotify API. But, at a high level, it appears that we’re looking at approximately three primary functions: Process 1 to extract the artist names from the user command line arguments; Process 2 to take these artist names and obtain their id, and Process 3 to find the relevant artists that they share in common.

Step 4— Mock the Data Flow in PureScript

Now, with our data flow sketch at hand, we can start to code our application. For the first part of this three-part series, we’ll stop at getting our artist name arguments in Process 1 and mock the other two processes that involve HTTP Get requests.

Getting artist names from command line arguments

To capture our artist name arguments from the command line, we use process.argv (see docs) in Node.js directly, launching the Node.js process as

$ node index.js Beatles Oasis

Spago, our PureScript package manager, has the ability to bundle a PureScript project into a single JS file. The command for this is:

$ spago bundle-module --main Main --to index.js

I have included a bundle script in package.json file to help you remember. Invoking npm run bundle on the command line triggers Spago to create a single, executable, dead code eliminated index.js file that we can run it with Node. From the example above, process.argv generates the output array:

0: /usr/local//bin/node 
1: ~/tut27/index.js 
2: Beatles 
3: Oasis

It is the third and fourth arguments that we should capture to accomplish Process 1 in our diagram. Moreover, we’re not limited to just two artists. So this process should be capable of capturing two or more artist names and flag an error when there are no artist names.

Wrapping argv in a Task

As Brian mentions in his video, it’s best to wrap argv in an asynchronous Task, whose callback delivers our artists names and handles any errors. We've used Task in several tutorials, starting with Tutorial 13. So start there if you're not familiar with this abstraction.

The main lines of code that carry out Process 1 is:

import Node.Process (argv) 

type Error = String
type Names = Array String 

names :: TaskE Error Names 
names =
  let 
    checkArgs :: Effect (Either Error Names)
    checkArgs = do
       args <- (drop 2) <$> argv
       pure $ 
         if (length args > 0)
           then Right args 
           else Left "you must enter at least one artist"
  in newTask $ \callback -> do 
    checkArgs >>= \args ->
      callback $ either (\e -> rej e) (\xs -> res xs) args
    pure $ nonCanceler 

main :: Effect Unit
  void $ launchAff $ 
    names # 
    fork (\e -> Console.error $ "Error: " <> e) 
         (\xs -> Console.logShow xs)

Starting with our main function, launchAff launches our names method asynchronously, and fork handles one of two possible outcomes - either success or failure. Here, 'success' means that the callback returns an array with the artist names that we retrieved from the command line. And 'failure' results in an error message logged to the terminal.

Within thenames method, we inline a checkArgs function that grabs the artist names from argv (whose type is Effect (Array String)). From Tutorial 14, we know that argv is an array and, therefore, it is a functor that we can map over. We map over argv to drop the first two items in the array.

There should be at least one artist name that is bound to args, and we check that by ensuring that the length of args is greater than 0. If so, then we'll wrap our artist names in a Right constructor from the Either (see Tutorial 3) monad. If not, then wrap an error message in a Left constructor because, by convention, this represents failure. Finally, we wrap the result in a Task and clean up before returning to main.

Mocking Processes 2 & 3

Referring back to our data flow diagram, Process 2 takes the artist names and searches for and returns the artist IDs. This Process requires an HTTP GET call to our Spotify search endpoint to extract the artist IDs from the JSON response. We’ll tackle all of that in the next tutorial. In the meantime, we’ll mock the entire data flow by wrapping each artist’s name in a Task and wrap their fake id in another Task. Note that taskOf from Control.Monad.Task always returns a successful Task. However, you can model failure by using taskRejected from the same module.

type Id = Int
type Artist = String

-- point free, assume artist name is valid for now
findArtist :: Artist -> TaskE Error Artist 
findArtist = taskOf

-- return an arbitrary id
artistId :: Artist -> TaskE Error Id 
artistId _ = taskOf 10

Process 3 finds the artists that are related. Here again, we’ll defer the actual work of calling the Spotify API for the next Tutorial. For now, let’s just wrap an array of arbitrary artists into a Task.

type RelatedArtists = Array String

relatedArtists :: Id -> TaskE Error RelatedArtists
relatedArtists id = taskOf ["John Lennon", "Paul McCartney"]

Finally, within the function related, we compose the entire data flow together using a couple of monadic binds that thread our data through our three functions findartist, artistId, and relatedArtists; just as we modeled it in the data flow diagram.

type RelatedArtists = Array String

related :: String -> TaskE Error RelatedArtists
related name = relatedArtists =<< artistId =<< findArtist name

Now, assuming there’s more than one artist name to process, we need a function that traverses our array of artist names and returns all their related artists. The keyword here is traverse from PureScript's Data.Traversable module, which runs our related method through each artist's name and collects the results into a nested array of related artists. So we'll modify our main function from before to:

main :: Effect Unit 
main = do 
  void $ launchAff $ 
    names >>= traverse related # 
    fork (\e -> Console.error $ "Error: " <> e) 
         (\xs -> Console.logShow xs)

Summary

In this tutorial, we began to wrap up this series by applying what we’ve learned about functional programming. We used our newly acquired FP skills to develop a node application that finds commonality between two or more music artists using the Spotify API. In the first of this three-part series, we accomplished the majority of the groundwork by 1) reviewing Spotify’s API documentation; 2) testing possible endpoint responses; 3) sketching our data flow execution diagram; and 4) mocking the data flow in PureScript. In our PureScript code, we built the functions that successfully retrieve the artist name arguments from the command line while mocking the remaining data flow.

In the next tutorial, we’ll add another layer to our data flow diagram that further illustrates the data coming to and from the Spotify API. We’ll also work on replacing the mocks with the working code. We’ll also explore to find the best abstraction to handle the asynchronous API calls. As a teaser, let me just say that you’re in for a surprise.

Finally, if you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Until next time.

Note: This is Tutorial 26 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximatelyonce-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 25 | Tutorial 27 >>

In the last tutorial, we wrapped up natural transformations in functional programming. Now we’ll move onto Isomorphisms and round trip transformations, which, spoiler alert, have nothing to do with running the same code on the client and server. Isomorphisms are an important concept in functional programming because they allow methods belonging to one type to be made available to other types that are isomorphic. The canonical example of two types that are isomorphic to one another is String and Array String. For example, “hello” and [“h”, “e”, “l”, “l”, “o”], respectively.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a star to help me publicize these tutorials.

What is an Isomorphism?

An Isomorphism is a set of two functions from and to such that composing them together is the same as doing nothing. That is:

from <<< to $ x == x 
to <<< from $ y == y 

-- or 
(from <<< to $ x) == (identity x) 
(to >>> from $ y) == (identity y)

We see from above that the result of these compositions is the same as applying the identity function. You can also think of from and to as functions f and g, so that more formally:

Constructing the Isomorphism type constructor

In Brian’s example, he constructed the isomorphism that takes a to and a from into a type with the following javascript:

const Iso = (to, from) => ({ to, from })

Then, as an example, he turned a string into a list of characters using an isomorphism.

const chars = Iso(s => s.split(''), c => c.join('')) 

const res = chars.from(chars.to('hello world')) 
console.log(res) 

/* Terminal output * "hello world" */

You can check to see that it actually split on every character by getting rid of chars.from, to return [ 'h', 'e', 'l', 'l', 'o',' ', 'w', 'o', 'r', 'l', 'd'].

In purescript, we can construct a type for an Isomorphism with the following constructor, and its methods:

data Iso a b = Iso (a -> b) (b -> a) 

inverse :: forall a b. Iso a b -> Iso b a 
inverse (Iso f g) = Iso g f 

to :: forall a b. Iso a b -> a -> b 
to (Iso f _) = f 

from :: forall f g a b. Iso f g -> b -> a 
from = to <<< inverse

The function to takes two arguments, the Iso a b type constructor, where a and b are functions, and the value a to be transformed. Using PureScripts pattern matching, we match on the first function f and use it to transform our a value. The function from is similar, but in this case, we are transforming a b value to an a value. Now, matching the JavaScript example above, let's use this isomorphism to turn a string into a list of characters. First, we create our Iso type constructor:

chars :: Iso String (Array String) 
chars = Iso (split (Pattern "")) (joinWith "")

Our Iso a b is constructed using the chars function. Thus, to chars a transforms a string a into a character array, and from chars b takes a character array b and transforms it into a string. Using purescript's REPL, we can test both sides to ensure we've constructed this isomorphism correctly:

pulp psci 
> import Main 
> to chars "hello world" 
["h","e","l","l","o"," ","w","o","r","l","d"] 
> from chars <<< to chars $ "hello world" 
"hello world" 
> (from chars <<< to chars $ "hello") == (identity "hello") 
true

Why are isomorphisms useful?

Isomorphisms are utilized in everyday programming because they make additional methods available to our types. For example, using our chars isomorphism from above, we're essentially making javascript's applicable array methods available to our string by turning it into an array of characters. Then, after applying one or more array methods, we turn it right back into a string.

For our second example, imagine we want to truncate the first three characters of a string and concatenate "..." to its tail. By using an isomorphism, we can take advantage of the array methods slice and concat to accomplish this task:

truncate :: String -> String 
truncate xs = 
  from chars $ concat [slice 0 3 $ to chars xs, ["..."]] 

main = 
log $ truncate "hello world"  -- returns "hel..."

Let’s make another isomorphism that proves a singleton array of String (i.e., an array holding one string value) is isomorphic to Either String String. First, we determine our isomorphism, naming it single:

-- Input must be a non-empty array or Just a 
single ::Iso (Either String String) (Array String) 
single = Iso (fromFoldable) (first) 

first :: Array String -> Either String String 
first [] = Left "" 
first xs = Right $ fromMaybe "" $ head xs

filterEither :: (String -> Boolean) 
             -> Either String String 
             -> Either String String
filterEither pred m = from single $ filter pred $ to single m

We are using fromFoldable from the Data.Array module to take our Either constructor and turn it into an array. Since type constructors such as Maybe and Either are foldable, this natural transformation (see Tutorial 25) turns them into an array. Note that if our Maybe or Either value is Nothing or Left e respectively, then an empty array is returned. The function head from Data.Array returns a Maybe value, so we'll transform it to an Either constructor using a natural transformation. Now that we have our isomorphism, let's go ahead and test it in the REPL by turning our Either into an array so that we can later filter it using available array methods.

pulp psci 
> import Main 
> import Data.Either 
> to single (Right "Hello")
["Hello"] 
> from single ["Hello"] 
(Right "Hello") 

Testing our filter in the REPL produces the following results:

pulp psci 
> import Main 
> import Data.Either 
> toUpper <$> filterEither (\x -> contains (Pattern "h") x) (Right "hello") 
(Right HELLO) 
> toUpper <$> filterEither (\x -> contains (Pattern "h") x) (Right "eello") 
(Left "")

Summary

In this tutorial, we covered isomorphisms and delved into a couple of use cases in everyday coding. Isomorphisms rank high on our “need to know” list because they allow methods belonging to one type to be made available to other types that are isomorphic. We demonstrated the canonical example of two types that are isomorphic to one another, namely String and Array String. For example, “hello” and [“h”, “e”, “l”, “l”, “o”], respectively. Subsequently, we showed our newfound ability to leverage several methods belonging to Array to manipulate our strings.

Like many concepts in functional programming, isomorphisms come directly from category theory. So if you’re interested in learning more about their properties, then I highly recommend you look at Bartosz Milewski’s blog or video on this topic; but also category theory in general. In the next tutorial, we’ll embark on the first of the final three posts in this series that ultimately finds common ground between two music artists using the Spotify API. If you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Until next time.

Note: This is Tutorial 25 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximatelyonce-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 24 | Tutorial 26 > Tutorial 27 >>

In the last tutorial, we began looking at natural transformations in functional programming — what they are and their laws. In this tutorial, we’ll continue on this topic by showing how to leverage natural transformations within your code. To review, a natural transformation is a function that takes a functor holding some a to another functor holding that a (i.e. F a -> G a).

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a star to help me publicize these tutorials.

Case 1: When a function doesn’t support your type constructor

What do you do when a library function doesn’t support your type constructor? Do you write it yourself? Instead, consider using a natural transformation. In Brian’s example, there’s no instance of chain for Javascript arrays. Consequently, we're not able to split on a character directly:

/* This won't work - no instance of chain on arrays */ 
['hello', 'world'] 
.chain(x => x.split(''))

To solve this problem, he used a natural transformation to turn the array into a list, knowing that chain exists on the List type constructor.

const res = List(['hello', 'world'])
            .chain(x => List(x.split('')))

Terminal Output

List [ "h", "e", "l", "l", "o", "w", "o", "r", "l", "d" ]

PureScript’s Array has an instance of bind (infix operator >==), which is the equivalent to chain above. Thus, we can act on the array directly to split its words into characters. But imagine having a List of words! Now we have a problem because split from Data.String.Common supports arrays only! So, similar to Brian's solution, we use natural transformations between List and Array. We perform them using fromFoldable; available in both Data.Array and Data.List. The type signature for fromFoldable in Data.Array is:

fromFoldable :: forall f. Foldable f => f ~> Array

It converts any Foldable structure into Array. For example:

fromFoldable (Just 1) = [1] 
fromFoldable (Nothing) = []

Notice the ~> in fromFoldable's type signature. It is the infix operator for NaturalTransformation, and its a signal to not only the compiler but to anyone reading your code that this function will perform a natural transformation. With that explanation, let's see how we can convert a list of words to characters in PureScript:

import Data.Array (fromFoldable) as A 
import Data.List (fromFoldable)
import Data.String.Common (split) 

wordList :: List String
wordList = ("hello" : "world" : Nil)

main :: Effect Unit 
main = do 
  log "\nSplit on characters from a wordList" 
  logShow $ fromFoldable $ 
    (A.fromFoldable wordList) >>= \x -> split (Pattern "") x

In main, working from right to left, the steps are as follows: 1. transform wordList into an array using Data.Array.fromFoldable; 2. perform the split into characters by binding the array with split; 3. transform Array back to List ~ with ~Data.List.fromFoldable.

Case 2: Accessing arbitrary elements within a foldable structure

Most functional programming languages don’t assume that an index into a foldable structure exists before attempting to access it. For example, how can a function be pure when attempting to return the first element of an empty array? The solution is to return a type constructor that addresses this possibility, typically Either or Maybe.

The helper functions in PureScript’s Data.Array use the Maybe type constructor to address this possibility. For example, when an array is non-empty, the helper function Data.Array.head returns the first element, Just a. Otherwise, it returns Nothing.

With this in mind, let’s port Brian’s second example to PureScript:

numbers :: Array Int
numbers = [2, 400, 5, 1000] 

largeNumbers :: Array Int -> Array Int
largeNumbers = filter (\x -> x > 100)

larger :: Int -> Int
larger = \x -> x * 2

main :: Effect Unit
main = do 
  log "\nProve that head is a natural transformation" 
  log $ (show $ larger <$> head (largeNumbers numbers)) <> 
     " == " <> (show $ head $ larger <$> (largeNumbers numbers))

In main, using the commutative law covered in the previous tutorial, we prove that head is a natural transformation. That is, map larger $ head (largeNumbers numbers) == head $ map larger (largeNumbers numbers). With our knowledge of natural transformations, we choose larger <$> head (largeNumbers numbers) because it's faster on large arrays and produces the same result as head $ larger <$> (largeNumbers numbers)

Case 3: Binding multiple database queries

Our last use case example for natural transformations involves the task of querying a user and, if the query is successful, perform another query for this user’s best friend. Imagine this database of users has the following fields:

type Id = Int 
type User = { id :: Id , name :: String , bestFriendId :: Id }

This example is where things get a little tricky because either query can return an error if the user id is less than 3. So we'll account for this Error using the Either constructor in our task:

fake :: Id -> User
fake x = { id: x, name: "user" <> (show x)
         , best_friend_id: (x + 1)
         }

dbFind :: Id -> TaskE Error (Either Error User)
dbFind id = 
  let 
    query :: Id -> Either Error User 
    query id_ = if (id_ > 2) 
                  then Right $ fake id_ 
                  else Left "not found" 
  in 
    taskOf $ query id

If we apply dbFind to a user id of 3, we get back Task(Right {id: 3, name: "user3", bestFriendId: 4}). In the next query, we want the best friend of user3, whose name is user4.

One approach, assuming we’re unaware of natural transformations, is to map either over Task(Right {id: 3, name: "user3", bestFriendId: 4}) to get user3 out. Then, rinse and repeat to find and return user4:

notFound :: User 
notFound = {id: -1, name: "notFound", bestFriendId: -1} 

main :: Effect Unit 
main = do 
  void $ launchAff $ 
  let 
    s = "\nFind best friend record (no natural transformations): "     
    eitherUser = either (\x -> notFound) identity
    user = \x -> map eitherUser (dbFind x) 
    bestFriend = user 3 >>= \x -> user x.bestFriendId 
  in 
   bestFriend # 
   fork (\e -> Console.error $ s <> e)
        (\p -> Console.log (s <> (show p)))

Terminal Output:

Find best friend record (no natural transformations): { bestFriendId: 5, id: 4, name: "user4" }

I can attest that this code was challenging to write, let alone follow! Moreover, when a user record doesn’t exist, we return {id: -1, name: "notFound", bestFriendId: -1}, which isn't what we want. Rather, the computation should fail and forgo the second query.

The correct approach is to use the natural transformation eitherToTask to turn that inner Either (i.e., Task(Right {id: 3, name: "user3", bestFriendId: 4})) into a task Task(Task {id: 3, name: "user3", bestFriendId: 4}. Then, bind it to get user3 and rinse and repeat to get user4:

eitherToTask :: forall a. Either Error a -> TaskE Error a eitherToTask = either (\e -> taskRejected e) (\a -> taskOf a) 

main :: Effect Unit 
main = do 
  void $ launchAff $ 
    let 
      s = "\nFind best friend record (natural transformations): "
    in 
      do (dbFind 3) >>= eitherToTask >>= \user -> (dbFind 
           user.bestFriendId) >>= eitherToTask # 
      fork (\e -> Console.error $ s <> e) 
           (\p -> Console.log (s <> (show p)))

Much better! Our eitherToTask found their ids and returned the right results even though we've transformed our eithers into tasks. Before calling fork, we're left with Task(Task {user: 4, name: "user4", bestFriendId: 5}). The function fork resolves both tasks and our output to the console is:

Find best friend record (natural transformations): { bestFriendId: 5, id: 4, name: "user4" }

Summary

In this tutorial, we covered three use cases for using natural transformations in our everyday code. The first case showed how natural transformations could be used to transform a data structure to match the type required by a function. In the example, we showed how a List is naturally transformed into an Array using Data.Array.fromFoldable. The second example focused on turning the first element of an Array into a Maybe type constructor. This transformation is useful in cases where the Array may be empty, and we're looking for safety. Finally, we showed how to naturally transform a composition of multiple database queries in order to bind them together more efficiently. This approach avoids nested map functions and leads to more readable code.

In the next tutorial, we’ll move onto a new topic — isomorphisms and round trip data transformations. That’s all for now. If you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Till next time!

Note: This is Tutorial 24 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximatelyonce-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 23 | Tutorial 25 > Tutorial 27 >>

In the last tutorial, we wrapped up our look at the Traversable type class with an example of how to process a sequence of HTTP GET requests using the member function traverse. Now, we'll move on to natural transformations in functional programming - what they are and the laws they must obey. Then, in the next tutorial, we'll show how natural transformations come in handy during everyday programming.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a star to help me publicize these tutorials.

Natural Transformations

As Brian mentions in his video, a simple explanation of a natural transformation is that its a type conversion. It takes one functor holding an element a to another functor holding that same a. You can think of it as a change in data constructors F a -> G a. Let’s implement a natural transformation by turning an Either data constructor into a Task data constructor.

Example: Transforming Either to a Task

Recall from Tutorial 3 that Either is used to express a computation that may or may not succeed. Either a b always contains a value of a or b; defined by the constructors Left a or Right b, but never both at the same time. Right b is the idiomatic designation of a successful computation, while Left a means a failed computation. We naturally transform Either to a Task by mapping Left a to taskRejected and Right b to taskOf.

Let's create this natural transformation eitherToTask with the following JavaScript code:

const eitherToTask = e => 
  e.fold(Task.rejected, Task.of)

eitherToTask(Right('nightingale')) 
.fork(e => console.error('err', e),       
      r => console.log('res', r))

eitherToTask(Left('errrrr')) 
.fork(e => console.error('err', e),       
      r => console.log('res', r))

In PureScript, the equivalent to e.fold is the either function from the Data.Either module. Using point free style, the equivalent code in PureScript is:

type Error = String 

eitherToTask :: forall a. Either Error a -> TaskE Error a eitherToTask = 
  either (\e -> taskRejected e) (\a -> taskOf a) 

main :: Effect Unit 
main = do 
  void $ launchAff $ eitherToTask (Right "Nightingale") # 
  fork (\e -> Console.error $ "Error: " <> e) 
       (\s -> Console.log $ "Result: " <> s)

With the help of a type alias, we designate our Error type to be a String. Calling eitherToTask with (Right "Nightingale")and logging to the console we get Result: Nightengale. Calling eitherToTask with a (Left "errrrr") argument will console.error the string Error: errrrr.

Now, let’s try another example using our old friend Box from Tutorial 2.

Example: Transforming Box to Either

First, Brian’s example in JavaScript:

const boxToEither = b => 
  b.fold(Right) 

const res = boxToEither(Box(100))

Similarly in PureScript:

type Error = String 

boxToEither :: forall b. Box b -> Either Error b 
boxToEither (Box b) = Right b

main :: Effect Unit
main = do
  logShow $ boxToEither $ Box 100

Compared to the JavaScript example, notice that we don’t provide a fold operation in our PureScript code. Instead, we leverage Purescript’s pattern matching capabilities to take our b from Box and put it into Either's Right constructor directly.

If you try compiling boxToEither (Box b) = Left b, you'll get an error. Why? Look at boxToEither's type signature: forall b. Box b -> Either Error b. We see that when Box b is transformed, our b is defined by the Right b constructor. If the compiler permitted us to chose Left b, then it would be invalid because it violates the laws of natural transformations, described below.

Natural Transformation Laws

We can express the laws of natural transformations with the following:

1. For every element a, and the functors F and G, the natural transformation nt between F and G is a morphism (i.e., mapping) from F a to G a.
2. For any natural transformation nt, when you transform any element a and map over it, then it is equivalent to mapping over a, then applying the natural transformation to the result. This is a commutative operation that can be expressed as: map (a -> b) -> nt a -> nt b == nt $ map (a -> b) -> f a -> f b.

Natural Transformation Diagram

The commutative diagram below helps to visualize the natural transformation laws expressed above:

If we have an element a, contained within the functor F and we map over it with a function map (a -> b), then we obtain F b. Furthermore, if we apply the natural transformation nt to F b, we get G b. Going the other way, if instead we first apply the natural transformation nt to F a to obtain G a, then we map over it with the same function (a -> b) we reach the same result G b.

Testing for a natural transformation

Let’s apply these laws to confirm that boxToEither is a natural transformation:

-- The left side of the commutative expression 
-- (a -> b) -> nt a -> nt b 
res1 :: Either Error Int 
res1 = map (\x -> x * 2) (boxToEither $ Box 100) 

-- The right side of the commutative expression 
-- nt $ (a -> b) -> f a -> f b 
res2 :: Either Error Int 
res2 = boxToEither $ map (\x -> x * 2) (Box 100)

When we log the results of both functions, the console output is Right 200, confirming that boxToEither is a natural transformation. Let's apply these laws to one more example, head, which takes the first element of Array Int and naturally transforms it to Maybe Int:

-- (a -> b) -> nt a -> nt b 
res3 :: Maybe Int 
res3 = (\x -> x + 1) <$> head [1, 2, 3] 

-- nt $ (a -> b) -> f a -> f b 
res4 :: Maybe Int 
res4 = head $ (\x -> x + 1) <$> [1, 2, 3]

The functionhead, gets the first element a , from an array, returning Just a or Nothing when the array is empty. Here again, logging the result to the console produces: Just 2 for both functions. Whenever the array is empty, then both functions return Nothing.

Summary

In this tutorial, we looked at a natural transformation — what it is, and what laws it obeys. A simple explanation of a natural transformation is that it is a type conversion. It takes one functor holding an elementa, to another functor holding that same a. You can think of it as a data constructor change F a -> G a. Delving further, we find that natural transformations obey the law of commutativity. Such that map (a -> b) -> nt a -> nt b == nt $ map (a -> b) -> F a -> F b, where nt is a natural transformation from the functor F to a functor G.

In the next tutorial, we’ll continue with natural transformations by looking at examples of where they come in handy. That’s all for now. If you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Till next time!

Note: This is Tutorial 23 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximatelyonce-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 22 | Tutorial 24 > Tutorial 27 >>

In the last tutorial, we looked at a new type class called Traversable. We found that its member functions can commute two types, such as Array (Maybe a); turning these structures inside out: Maybe (Array a). In this case, it reflects the overall success or failure of our transformation function. This is useful when your transformation is part of a chain of functions, and you need to halt this sequence whenever there's a processing error. We'll continue with another example of Traversable by simulating a sequence of HTTP GET requests that resolves when all these requests have resolved; similar to Promise.all() in JavaScript. Then, I'll show how to perform two traversals within the same workflow; useful when you have an Array (Array a) to process. Again, this leans heavily on the previous tutorial, so be sure you have read and coded the exercises.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a star to help me publicize these tutorials.

Traversable’s member functions

From the last tutorial, we learned that the two member functions belonging to the Traversable class are sequence and traverse. First, the sequence function commutes two types T1 (T2 a) to T2 (T1 a).

For example, imagine we want to turn an Array of String into an Array of Maybe (String), followed by commuting these structures to obtain Maybe (Array String). The rationale for inverting these types is to signal the overall success (i.e., Just (Array String)) or failure (i.e., Nothing) in transforming each of the string elements. This way, if this function is part of a chain of functions then, in case of Nothing the computation chain halts and we handle the error subsequently. Using map and sequence the approach is:

• First our mapping function: map (\s -> Maybe String) (Array String), which results in Array (Maybe String)
• Next, our sequence function: sequence Array (Maybe String), which results in Maybe (Array String)

The other member function, traverse, performs the above map and commute operations all in the same expression. Its type signature is forall a b m t. Traversable t => Applicative m => (a -> m b) -> t a -> m (t b). Thus, the two operations, map and sequence, are reduced to: traverse (\s -> Maybe String) (Array String), which results in Maybe (Array String). We'll use traverse in both asynchronous processing examples below.

Mapping HTTP Get Requests

Imagine we have a Map of key/value pairs representing routes within our website, so that we can map over it to obtain the contents of each page. In Javascript, we might represent this Map as:

Map({home: '/', about: '/about-us', blog: '/blog'}).map

When you .map over a Map, it transforms each value, taking as input a path for every key. In Purescript, Map is a foldable data structure with the key/value pairs wrapped in a Tuple. More flexible than Javascript objects, our key/value pairs can be of any type. I'll use Map String String for both examples below. The Purescript representation for our Map of routes looks like:

(fromFoldable [(Tuple "home:" "/"), (Tuple "about:" "/about-us"), (Tuple "blog:" "/blog")])

Note, there’s an infix representation (/\) for Tuple in Data.Tuple.Nested which makes reading and writing these structures a little easier on the eyes:

(fromFoldable ["home:" /\ "/", "about:" /\ "/about-us", "blog:" /\ "/blog"])

Now, let’s create a function that simulates an HTTP Get request by taking a Path and Params and returning a fake result. We do this by wrapping each request in a Task that is performed sometime in the future. So, instead of String, we return a Task of String. Note, we'll ignore the Params argument for simplicity.

httpGet :: Path -> Params -> TaskE Error Result
httpGet path _ = taskOf $ path <> " result"

Once we process our Map of key/value pairs, we end up with a Map of Task (Tuple String String) That is, [Task ("home:" //\ "//" <> " result"), Task ("about:" /\ "/about-us" <> " result"), Task ("blog:" /\ "/blog" <> " result")] However, similar to the last tutorial, we don't want Array (Task (Tuple String String)). Instead, we want one Task on the outside, with all the HTTP Get requests resolved. Then, when we fork this outside Task, we end up with a Map of key/value pairs, and all the results from out HTTP Get requests. Let's call on traverse, followed by fork to do just that:

main :: Effect Unit 
main = do 
  void $ launchAff $ 
    traverse (\path -> httpGet path "{}") routes # 
    fork (\e -> Console.errorShow e) (\rs -> Console.logShow rs)

When we run this at the terminal, the output is:

(fromFoldable [(Tuple "home:" "/ result"), (Tuple "about:" "/about-us result"), (Tuple "blog:" "/blog result")])

In reality, we can traverse as much as we want. For example, let’s say we want to traverse over a Map whose values are an array of multiple routes? Note in the example below, home: is represented as/home or /:

(fromFoldable ["home:" /\ ["/home, "/"], "about:" /\ ["/about-us"], "blog:" /\ ["/blog"]])

Instead of mapping twice, we simply traverse twice:

main :: Effect Unit
main = do 
  void $ launchAff $ traverse 
    (\paths -> traverse (\path -> httpGet path "{}") paths) multiRoutes # 
    fork (\e -> Console.errorShow e) (\rs -> Console.logShow rs)

and our terminal output will look like this:

(fromFoldable [(Tuple "home:" ["/ result", "/home result"], (Tuple "about:" ["/about-us result"]), (Tuple "blog:" ["/blog result"]))])

Summary

In this tutorial, we explored another application of traverse from the Traversable class, namely processing a foldable structure of asynchronous functions while maintaining its structure. For example, similar to Promise.all() in JavaScript, we may want to resolve a list of HTTP Get requests that download the contents of the list of web pages.

Another popular use case is reading from a customer database: readCustomerFromDB :: customerID -> Maybe Customer; returning Just Customer when we find the customer record, or Nothing otherwise. Now, what if we have a list of customerID to process? We can use map, to return a list of Maybe Customer. But also, when readCustomerFromDB is part of a chain of functions, we can use traverse to return Maybe (List Customer). This way, the computation halts within the chain and we deal with the error.

In the next tutorial, we’ll cover a new topic of natural transformations in functional programming. These come in handy, for example, when you want to split an array of word strings["hello", "world"] into a list of characters ('h', 'e', 'l', 'l', 'o', 'w', 'o', 'r', 'l', 'd'). If you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Till next time!

Note: This is Tutorial 22 in the series Make the leap from JavaScript to PureScript. Be sure to read the series introduction where we cover the goals & outline, and the installation,compilation, & running of PureScript. I’ll be publishing a new tutorial approximatelyonce-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 21 | Tutorial 23 > Tutorial 27 >>

In the last tutorial, we concluded our extensive exploration of Functor type classes, by ending with the Applicative Functor. Now, in this tutorial, we'll look at a new type class that has a relationship with Functor, called Traversable. Throughout our Functor exploration the transformation functions processed the elements within a Functor type class (using map, apply or bind) while preserving the structure of the original Functor. For example, map (\x -> x + 1) [1, 2, 3] takes the array [1, 2, 3] and returns a new array [2, 3, 4], leaving the outer structure intact. However, what if we what to change the original Functor to another type constructor? For example, perhaps we want Array String to become `Maybe (Array String)~ to reflect the overall success or failure of our transformation function. That is the topic of this and the next tutorial - commuting two types, turning the these structures inside out.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a star to help me publicize these tutorials.

One final review of functors

I mentioned above that Traversable has a relationship with the Functor type class. To help explain this relationship, let's take stock of the functors we have covered thus far. Back in Tutorial 14, we started with the most basic and ubiquitous type class in functional programming, namely the Functor. Any type constructor that supports a mapping operation is considered a Functor. Examples of Functor type constructors include List, Array, Maybe, Task, Either, and many more. The map operation allows us to transform the elements inside the Functor uniformly while preserving the structure and shape of the type constructor.

In Tutorial 18, we looked at the Applicative Functor, which is a subclass of Functor that adds the apply and pure operations. The apply operation is similar to map, but it differs because it acts on transformation functions that are wrapped in a functor. We do that using pure , which lifts a value or expression into Functor. Then we can apply (i.e., <*>) this function over multiple functor arguments; for example: pure (+) <*> [1] <*> [2, 3] = [3, 4].

Finally, in Tutorial 16, we covered the Monad type class, which is a subclass of the Applicative Functor. Monad not only supports the map and pure operations, but also bind. The bind operation helps to prevent double nesting of the Functor when applying multiple sequential operations to it; avoiding messes like Just (Just a).

With our review out of functors out of the way, we can move on to Traversable, which holds a relationship with Functor.

The Traversable Class

I mentioned that the Traversable type class has a relationship with functors. That's because every Traversable is an Applicative Functor that is Foldable. By Foldable, I mean type constructors that can be folded, such as a List or Array, to return a value. I didn't cover Data.Foldable formally, but we looked at a couple of its methods, foldMap and foldr in Tutorial 10. Like map, the two operations within the Traversable class allow us to transform the elements within the Functor. Moreover, like Foldable, we accumulate the results and effects of this transformation function along the way into an Applicative Functor.

For a simple example, imagine you have an array of string elements that you wish to parse, but one or more of these elements may be invalid. The function signature is, parseStrings :: Array String -> Array (Maybe String), where the Maybe type constructor represents the possibility of a valid or invalid string. If this is what we want, then the map operation suffices - map (\x -> Maybe x) (Array String) = Array (Maybe String) However, what if we want parseStrings to signal a failure whenever it encounters an invalid string within the array? In this case, our type signature becomes parseStrings :: Array String -> Maybe (Array String). Unfortunately map is not up to this task; therefore, we rely on one of the member functions from the Traversable class to help complete this job.

Member functions

There are two member functions associated with Traversable, sequence and traverse . The sequence operation is perhaps the simplest to grok. From the purescript REPL (i.e., pulp psci), you see that sequence turns our foldable functor structure inside out:

> import Data.Traversable 
> :t sequence 
forall a m t. Traversable t => Applicative m => t (m a) -> m (t a)

For example, imagine you have Array (Maybe a), but you want to transform it to Maybe (Array a) , to signal the overall success or failure of the transformation function used to process the array elements. Let's try a few examples at the REPL to work it out:

> import Data.Traversable 
> import Data.Maybe 
> p = \x -> if (x > 0) then (Just x) else Nothing 
> process1 = map p [1, 2, 3] 
> sequence process1 
Just [1, 2, 3] 
> process2 = map p [1, -1, 3] 
> sequence process2 
Nothing

From the above, sequence lifts the resulting accumulation outside of the structure, turning it inside out. Thus, when all the elements pass the predicate function (e.g., process1, it returns Just (Array Int). When one of the elements fails the predicate function (i.e., process2), it returns Nothing.

The sequence function is perfectly fine, assuming you've processed every element within the Foldable structure in advance. However, you may be wondering whether there's also a way to act on every element at the same time. For this type of functionality, we use traverse :

> import Data.Traversable 
> :t traverse 
forall a b m t. Traversable t => Applicative m => (a -> m b) -> t a -> m (t b)

Using the same predicate function from above, we can play with traverse in the purescript REPL:

> import Data.Traversable 
> import Data.Maybe 
> p = \x -> if (x > 0) then (Just x) else Nothing 
> traverse p [1, 2, 3] 
Just [1, 2, 3] 
> traverse p [1, -1, 3] 
Nothing

In summary, whenever we want to commute two types like this, what we can do instead of calling map followed by sequence is to call traverse. It's nice and short!

From the above example, we can also infer that sequence is equivalent to traverse identity, where identity is the identity function \x -> x. Fun fact - the sequence operation is actually implemented in the purescript library using traverse identity (See purescript-foldable-traversable). Also, vice versa, traverse f xs is equivalent to sequence (map f xs).

Now, with the sequence and traverse operations in our back pocket, let's move onto the example from Brian's video.

Example

In Brian’s video, we lean on our Task module (see Tutorial 13) once again to read multiple files asynchronously, wrapping each file in a Task:

const fs = require('fs') 
const Task = require('data.task') 
const futurize = require('futurize').futurize(Task) 
const { List } = require('immutable-ext') 

const readFile = futurize(fs.readFile) 
const files = ['box.js', 'config.json'] 
const res = files.map(fn => readFile(fn, 'utf-8')) 
console.log(res)

which returns an array of tasks:

Terminal output:

[ Task { fork: [Function], cleanup: [Function] }, Task { fork: [Function], cleanup: [Function] } ]

The problem becomes knowing when all the Tasks finish and how to fork each one. We’ll solve this shortly with traverse. First, here's how to achieve the equivalent example in purescript:

files :: Array String
files = ["./resources/Box.purs", "./resources/config.json"] 

taskReadTextFile :: String → TaskE Error String 
taskReadTextFile fname = 
  let 
    tryReadTextFile :: String → Effect (Either Error String)
    tryReadTextFile fname_ = try $ readTextFile UTF8 fname_ 
   in 
    newTask $ \callback → do 
      tryReadTextFile fname >>= \r → 
        callback $ either (\e → rej e) (\s → res s) r 
      pure $ nonCanceler 

main :: Effect unit 
main = 
  void $ launchAff $ 
    map (\x -> taskReadFile x) files # 
    (\rs -> Console.log $ show rs)

Note that the last line generates a compiler error because there’s no class instance of show for TaskE. We don't need to write it, but if we did, then we could make the text look similar to the terminal output from the JavaScript code above.

Let’s move onto the solution we’re seeking, by turning these type constructors inside out, so that Task is on the outside of the Array.

main :: Effect Unit 
main = 
  void $ launchAff $ 
    traverse (\x → taskReadTextFile x) files # 
    fork (\e → Console.error $ show e) 
         (\rs → Console.log $ foldl (<>) "" rs)

Upon executing traverse (\x -> taskReadfile x) files, the resulting type is TaskE (Array String), assuming there were no errors while reading our files. Then, after executing fork, we concatenate the array elements using foldl and log the text from each of the files to the console. Otherwise, the type result becomes TaskE Error.

Summary

In this tutorial, we introduced a new type class, Traversable that holds a relationship with the Foldable and Functor type classes. The member functions within Traversable will commute two types: t (m a) -> m (t a). Here t belongs to Foldable and Functor type classes, and m is an Applicative Functor, confirming there is the relationship mentioned above.

Example use cases for Traversable, covered above, include signaling the overall success or failure of a function when mapping (a -> m b) over a foldable functor of elements t a. We can use sequence $ map (a -> m b) (t a) or the shorter traverse (a -> m b) (t a) operation. The result is the same - m (t b), turning these two types, m and t, inside out. We can also leverage Traversable to execute multiple Tasks within a foldable structure and fork the entire structure at once to end up with a list of results.

In the next tutorial, we’ll continue with another example of using Traversable to resolve a list of tasks of HTTP requests. That's all for now. If you are enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Till next time!

Note: This is Tutorial 21 in the series Make the leap from JavaScript to PureScript . Be sure to read the series introduction where we cover the goals & outline, and the installation, compilation, & running of PureScript. I’ll be publishing a new tutorial approximately once-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 20 | Tutorial 22 > Tutorial 27 >>

In the last tutorial, we continued our exploration of Applicative Functors with a practical example that captured the pattern of nested loops for constructing foldable (e.g., array) comprehensions. We’ll finish off applicatives in this tutorial with another example that pings a mock database, returning a result from a query. As you’ll see, a query in our example is independent of the result of previous queries. Consequently, instead of performing these queries serially, we can leverage concurrency by employing applicatives to run them simultaneously. We’ll look at both the serial and concurrent approaches so that you can see the difference in coding. We’ll mock a “database find” method using our homegrown Task module from Tutorial 13.

I borrowed this series outline, and the JavaScript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it a start to help me publicize these tutorials.

Let’s start with a quick review of TaskE then move onto the example.

Reviewing the Task module

Recall from Tutorial 13 that TaskE runs an asynchronous computation that may fail, and it models any side-effects explicitly. There isn't a specific TaskE module in PureScript, so we created one ourselves to mimic data.task from the JavaScript Folktale library. As you'll see, TaskE is a good structure to help mock a database API query, because it runs asynchronously and allows for effects that may fail. For example, when pinging a database endpoint, there's always the possibility that your endpoint might be down. Also, what if the caller invokes an invalid query? Well, in our example, we don't want to continue with the next query because we're building a report header that's constructed from the aggregate queries. In these and other cases TaskE should fail gracefully by reporting that there's a problem back to the caller.

The type alias for TaskE is:

type TaskE x a = ExceptT x Aff a

With ExceptT x, we're creating a structure that can fail during its computation, and Aff a denotes that it is asynchronous and produces side-effects. Note that ExceptT x is a monad transformer for the Either x Monad, whose type we introduced in Tutorial 3.

We haven’t covered monad transformers in this series, and we may not have the opportunity. However, in simple terms, ExceptT helps us to handle a successful or failed computation within the Aff monad. We wrap the computation with a Right a and Left a from the Either monad, denoting success or failure respectively. So, we've got two monads operating together (i.e., Aff and Either) and ExceptT is the glue that makes this possible.

A simple and successful TaskE is created by wrapping the result using pure from Control.Applicative. In Tutorial 13, we used the taskOf method for this purpose. It’s just syntax sugar for pure since we hadn't covered applicatives at the time. The example below wraps the string "good task" in a Task whose computation is later run in main. It is guaranteed to be successful since we're returning a string, "good task", unfettered by any side-effects.

goodTask :: TaskE String String 
goodTask = pure $ "good task" 

main :: Effect Unit 
main = do void $ launchAff $ 
  goodTask 
  # fork (\e → Console.error e) (\r → Console.log r)

The launchAff method launches an asynchronous fiber, which in this case is goodTask. The fork method is there to handle the two possible outcomes - either success or failure. Ultimately, it logs "good task" to the console. In case you're wondering how to create a "bad" task - throw an error! You use throwError with the comfort that ExceptT ensures that Either and Aff play nice together.

badTask :: TaskE String String 
badTask = throwError "bad task" 

main :: Effect Unit main = do void $ launchAff $ 
  badTask 
  # fork (\e → Console.error e) (\r → Console.log r)

These, are perhaps, the simplest tasks to write. In the next section, we’ll use our “database find” example to show how to add callbacks within our tasks and clean up the fiber after finishing the asynchronous computation.

Mocking a database query using Task

With our review of TaskE complete, let's move on to our mock example that queries a database API for project records and later logs the titles of those projects. Here, we have a database of projects; each modeled with a record of type, Project = { id :: Int, title :: String } where id is the record identifier and title is the name of the project.

We perform a query by running an asynchronous task with effects that may fail with an exception of type String or succeed by returning a result of type Project. Also, since we're mocking an API endpoint, the Project record response is a time-dependent value. We can model that behavior using setTimeout within our Task to mimic the delay in the response returned by the API.

type Project = { id :: Int, title :: String } 

dbFind :: Int → TaskE String Project 
dbFind id = 
  let 
    query :: Int → Effect (Either String Project) 
    query id_ = pure $ do 
      let validIds = [20, 8] 
      case (elemIndex id_ validIds) of 
        Just _ → Right { id: id_, title: "Project: " <> (show id)} 
        Nothing → Left $ "record id: " <> (show id) <> " not found." 
   in 
    newTask $ \callback → do 
      let requestResponse = query id >>= \r → 
            callback $ either (\e → rej e) (\s → res s) r 
       _ <- setTimeout 100 requestResponse 
       pure $ nonCanceler

Within dbFind, a successful query returns a Project record with side-effects modeled explicitly (i.e., Effect (Right Project)). Alternatively, in the case of failure (i.e., Effect (Left String)), we return an error message that the record id was not found in the database.

The newTask method has been designed to perform this computation by accepting (as arguments) a function that transforms an effectful callback to a canceler. We perform the query and then, using the bind 1 operation (>>=), we pass the return value in sequence to our callback. Depending on success or failure and, with the help of the either function, the callback uses res or rej, respectively to wrap the result in our TaskE type signature.

To simulate a time-dependent value, we call setTimeout to delay the callback by 100 milliseconds. We're not interested in the timeout id, so we ignore it by not binding it to a variable. Finally, we tell makeAff (the function underpinning newTask) how to clean up after our asynchronous computation. In this case, there's no elaborate asynchronous process going on, so providing newTask with nonCanceler (a canceler that doesn't do anything) is good enough.

Sequential dbFinds using Monads

There are two approaches to executing multiple queries on a database. The first approach executes them sequentially, as shown below. Take this approach when the formation of a database query is dependent on the information retrieved from one or more previous queries.

In the code example below, the overall goal is to “console log” a report header constructed from our two queries, dbFind 20 and dbFind 8. We use reportHeader to construct a string from the two project titles. To accomplish this, we call dbFind 20 as our first query, which returns its result wrapped in the TaskE. So alas, we know we're working in the TaskE monad, so bind the first query to the lambda function p1 and compose it with reportHeader and our next query dbFind 8, which is bound to p2.

reportHeader :: Project -> Project -> String 
reportHeader p1 p2 = 
  "Report: " <> p1.title <> " compared to " <> p2.title 

main :: Effect Unit 
main = void $ launchAff $ 
  dbFind 20 >>= (\p1 → (\p2 → reportHeader p1 p2) <$> dbFind 8) 
  # fork (\e → Console.error e) (\p → Console.log p)

Recall that bind, whose infix operator is >==, is equivalent to chain in Brian's javascript examples (see example below). The map function, whose infix operator is <$>, lifts reportHeader into the TaskE monad so that it can operate on the TaskE applicative arguments, p1 and p2. Remember that map is a substitute for pure and one apply operation within an applicative expression.

For a comparison, look at the javascript code adapted from Brian’s example:

const reportHeader = (p1, p2) => 
  `Report: ${p1.title} compared to ${p2.title}` 

Task.of (Db.find (20).chain (p1 => 
          Db.find (8).map (p2 => 
            reportHeader (p1, p2)))) 
.fork (console.error, console.log)

Concurrent dbFinds using Applicative Functors

The queries, dbFind 20 and dbFind 8 can be run independent of each other, so it's not necessary to run them sequentially. When we run them concurrently in an applicative expression, it helps to make our code more readable, and perhaps execute faster.

Compared to our sequential example in the previous section, I believe the applicative expression is much more readable. In the example below, if either of these queries fails, then execute (\e → Console.error e) to call out the offending query. Otherwise reportHeader is cleared to construct our header string which is printed out to the console.

main = void $ launchAff $ 
  (\p1 p2 → reportHeader p1 p2) <$> (dbFind 20) <*> (dbFind 8) 
  # fork (\e → Console.error e) (\p → Console.log p)

Naturally, if your mental model feels more at home with code that appears sequential, then feel free to use applicative do syntax:

main = void $ launchAff $ ado 
  p1 <- dbFind 20 
  p2 <- dbFind 8 
  in 
   reportHeader p1 p2 
   # fork (\e → Console.error e) (\p → Console.log p)

Once again, let’s compare this with the Javascript code, adapted from Brian’s video:

const reportHeader = (p1, p2) => 
  `Report: ${p1.title} compared to ${p2.title}` 

Task.of (p1 => p2 => reportHeader (p1, p2)) 
.ap (Db.find (20)) 
.ap (Db.find (8)) 
.fork (console.error, console.log)

Both the PureScript Javascript code examples are much easier to read, and again should execute faster than a sequential approach using monads.

Lifting functions into applicative expressions

In the previous section, instead of using pure to lift reportHeader into the TaskE monad, we're using map whose infix operator is <$>. That is, we substituted pure (\a b → f a b) <*> m a <*> m b for (\a b → f a b) <$> m a <*> m b.

If you review the past two tutorials, you'll see that's been our practice. But what’s going on with (\a b → f a b) <$> m a <*> m b and how does it work? Well, it helps to step back and look at the type signatures forpure and the infix operators for apply and map:

pure  ::   (a → b) → m (a → b)
(<*>) :: m (a → b) → m a → m b

(<$>) ::   (a → b) → m a → m b

Notice that pure lifts our function a → b into m to get m (a → b). Next is apply whose infix operator is (<*>). This method takes m (a → b) and our input m a , and applies it to return our output m b.

Now, look at map, whose infix operator is <$>. It lifts the function (a → b) into m, then applies it to the input m a and returns our output m b.

Somap, when used in an applicative expression, is a substitution for pure and one apply operation.

In conclusion, I believe (\a b → f a b) <$> m a <*> m b is easier to read than pure (\a b → f a b) <*> m a <*> m band you’ll find that it is the idiomatic syntax. So use this pattern whenever you’re not using lift2, lift3, ... or applicative do sugar.

Summary

In this tutorial, we refactored a sequence of independent queries using monads into an applicative expression that runs concurrently. After refactoring, we found that our code is not only better optimized for performance, but it is also simpler to read and understand.

We have come to the end of our tutorials that explored the practical examples using Applicative Functors. I hope you agree that it is a dominant pattern that you can exploit in whatever functional programming language you choose to program in.

In the next tutorial, we’ll move on to explore another useful construct that allows us to traverse a foldable structure (e.g., array) of applicative functors and applies a function to each. For example, if our foldable structure is an array, then the type signature for traverse is (a → f b) → Array a → f (Array b). This method is useful when our function f produces side-effects. For example, imagine the array contains a list of filename paths that require reading and parsing their text.

That’s all for now, and till next time!

1 In case you’re a little hazy on bind or even monads, then please refer to Tutorial 16 for a refresher.

Note: This is Tutorial 20 in the series Make the leap from JavaScript to PureScript . Be sure to read the series introduction where we cover the goals & outline, and the installation, compilation, & running of PureScript. I’ll be publishing a new tutorial approximately once-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 19 | Tutorial 21 > Tutorial 27 >>

In the last tutorial, I introduced our first practical example of an Applicative Functor for getting a web page’s screen height from the DOM. In this tutorial, we’ll continue covering them with another example that captures the pattern of nested loops in your imperative code when constructing list comprehensions. For a quick review of applicative functors, please read my last tutorial. Alternatively, if you are new to the Applicative, then please start with tutorial 18.

I borrowed this series outline, and the javascript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption is that you’ve watched his video on the topic before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request. Also, before leaving, please give it star to help me publicize these tutorials.

Foldable Comprehensions

Let’s define this term by breaking it down — Foldable data structures are types which can be folded to a summary value (using foldl or foldr). Comprehensions are type constructs for creating a new Foldable data structure from an existing one. The most common foldable data structures are lists, arrays, and trees. In languages, such as python and CoffeeScript, there are syntactic constructs (see python example) available to a create a list comprehension. Note that there was a preliminary proposal for array comprehensions in Javascript, but it never made it to ES6/ES2015.

For this tutorial, I’ll follow Brian’s lead by illustrating an example of a list comprehension. Again, be sure to review his video, so that you understand the context of what we’re going to accomplish in this tutorial. First, for lack of an array comprehension construct in Javascript, here’s how you can create one using nested loops:

const xs = ['teeshirt', 'sweater'];
const ys = ['large', 'medium', 'small']; 
const clothes = []; 

for (x of xs) { 
  for (y of ys) { 
    // ["teeshirt-large", "teeshirt-medium", ..."]
    clothes.push(`${x}-${y}`); } }

To add more elements to our comprehension, such as color in the example below, we create another inner loop:

const zs = ['red', 'green', 'blue']; 

for (x of xs) { 
  for (y of ys) {
    for (z of zs) {
      // ["teeshirt-large-red", "teeshirt-medium-red", ..."] 
      clothes.push(`${x}-${y}-$(z)`); 
    };
  };
};

Add more nested loops at your peril, because it leads to code that is difficult to read and debug until it becomes a sinister pyramid of doom. So, the critical takeaway from Brian’s tutorial and mine is to replace these messy loops altogether by using an applicative functor. Again, this pattern works on not only lists but any foldable data structure such as an array or tree.

List comprehensions in PureScript

In purescript, we construct a List using a couple of functions provided by the Data.List module from the purescript-lists package.

import Data.List (List(..), (:)) 

newStringList :: String → List String 
newStringList s = s : Nil

The new functions above are cons, whose infix operator is (:), and Nil for representing the empty list. In the above example, we are constructing a new list by prepending the string s to Nil. With these two functions, together with our applicative functor, we have the necessary ingredients for constructing a list comprehension of clothes, created from our type, size, and color lists:

import Prelude 
import Data.List (List(..), (:))

-- returns ('teeshirt-large-black' : 'teeshirt-large-white', ...) merch1 :: List String 
merch1 = (\x y z -> x <> "-" <> y <> "-" <> z) 
  <$> "teeshirt" : "sweater" : Nil
  <*> "large" : "medium" : "small": Nil
  <*> "black" : "white" : Nil

Using lift from Control.Apply

Now, you could argue that the above example is no more readable than our nested loops imperative code example. I disagree, but for the sake of avoiding an argument, we can use lift3 from Control.Apply to further help with readability.

import Prelude
import Control.Apply (lift3)
import Data.List (List(..), (:))

merch2 :: List String
merch2 = lift3 
  (\x y z → x <> "-" <> y <> "-" <> z) 
  ("teeshirt" : "sweater" : Nil)
  ("large" : "medium" : "small" : Nil) 
  ("black" : "white" : Nil)

We are using lift3 in the above example to lift our function of three arguments (i.e., x, y and z) to a function which accepts and returns values wrapped in our List constructor. If you look at the source code for lift3, you'll see that it is merely syntactic sugar that eliminates the need for pure and (<*>), used in our first example.

Using Applicative Do

Once again, you may believe that lift is still not much better than using nested loops. Ok, to appeal to your imperative mental model, let's make our applicative look a little more synchronous by borrowing from do-notation. You may be aware that do blocks in functional programming behave like ; in imperative languages, including JavaScript. We often use them as an alternative to monad bind syntax (e.g., >>=) when sequencing actions that run consecutively.

merch3 :: List String
merch3 = ado
  x <- "teeshirt" : "sweater" : Nil
  y <- "large" : "medium" : "small" : Nil
  z <- "black" : "white" : Nil 
  in (x <> "-" <> y <> "-" <> z)

With Applicative do-notation, introduced with the 0.12.0 compiler, PureScript adds support for desugaring do-notation into Applicative expressions where possible. However, under the hood, this block can be executed in parallel, since x, y, and z are independent of one another. In contrast, we must execute Monad expressions in sequence, because determining the list of ys is dependent on computing the list of xs such that List x → (x → List y) → List y.

The choice is yours whether to use one of the three syntax constructs shown above. Naturally, they all accomplish the same result. So use whichever helps future readers of your code to understand the implementation of your logic better.

Summary

In this tutorial, we covered a simple example of the power of the Applicative Functor for creating foldable comprehensions; eliminating those messy nested loops from imperative code. PureScript supports several foldable data structures, including lists, arrays, and trees. We can construct a list in PureScript using cons and Nil from the Data.List module in the purescript-lists package.

For every argument in our applicative function, when we apply it to a Foldable we eliminate one loop within your imperative code. For example, we can express a double loop pattern by the following applicative function. This example is also a list comprehension because we are creating a new list xys = (4 : 5 : 5 : 6 : Nil) from the lists xs = (1 : 2 : Nil) and ys = (3 : 4 : Nil).

import Prelude
import Data.List (List(..), (:)) 

-- returns (4 : 5 : 5 : 6 : Nil) 
doubleLoop :: List Int
doubleLoop = lift2 
  (\x y → x + y) 
  (1 : 2 : Nil)
  (3 : 4 : Nil)

In summary, Applicative Functors effectively replace loop patterns from imperative programming. In the next tutorial, I’ll show you how to refactor some sequential code that uses monads to achieve concurrency by replacing them with applicatives. If you’re enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Thank you and until next time!

Note: This is Tutorial 19 in the series Make the leap from JavaScript to PureScript . Be sure to read the series introduction where we cover the goals & outline, and the installation, compilation, & running of PureScript. I’ll be publishing a new tutorial approximately once-per-month. So come back often, there’s a lot more to come!

Index | << Introduction < Tutorial 18 | Tutorial 20 > Tutorial 27 >>

In the last tutorial, I introduced the Applicative Functor for applying a function to multiple functor arguments. Now, I’m going to show a practical example of this functor — getting a web page’s screen height from the DOM. However, first, I’ll give a quick refresher on Applicative Functors then dive right into the example.

I borrowed this series outline, and the javascript code samples with permission from the egghead.io course Professor Frisby Introduces Composable Functional JavaScript by Brian Lonsdorf — thank you, Brian! A fundamental assumption of each tutorial is that you’ve watched his video before tackling the equivalent PureScript abstraction featured in this tutorial. Brian covers the featured concepts exceptionally well, and I feel it’s better that you understand its implementation in the comfort of JavaScript.

You’ll find the text and code examples for this tutorial on Github. If you read something that you feel could be explained better, or a code example that needs refactoring, then please let me know via a comment or send me a pull request.

Quick Applicative Functor review

From the last tutorial, we learned that the Applicative Functor type class extends the map method by enabling function application to more than one functor value. Also, it can lift functions of zero arguments or values into a functorial type constructor. To accomplish the former we use the apply method, and the latter is achieved using pure. For example, using the PureScript REPL, we can play with our old friend the Box type constructor to see how apply and pure work:

> import Prelude
> import Control.Apply 
> import Control.Applicative 
> import Data.Box 
> pure (+) `apply` (pure 2) `apply` (pure 3) :: Box Int
Box 5

The pure method, from the Control.Applicative module, lifted our addition function (+) and the values 2, and 3 into our Box constructor. The apply method, from PureScript's Control.Apply module, maps Box (+) over the arguments Box 2 and Box 3 to calcuate and return Box 5. Note, we could have assigned these functor arguments to Box directly (e.g., Box (+)) without using pure. However, in production code, I prefer to use it in case I decide to change the name of the type constructor later on. This way it's a simple name change to one or more arguments in a function's type declaration, avoiding error-prone edits to arguments within the body of the function. We also learned that there's an infix operator for apply, namely <*>:

> (+) <$> (pure 2) <*> (pure 3) :: Box Int
Box 5

Recall that map, whose infix operator is <$>, enables the substitution of pure, and one apply from an applicative expression. Thus, from the above, map takes care of lifting our function into Box , such that + can be partially applied to each argument within Box to obtain the result of the addition.

Also, there are helper methods lift2, lift3, lift4, etc., that help to shorten our code even further. The number in the name of these methods represents the number of functorial arguments to the function. For example:

> lift2 (+) (pure 2) (pure 3) :: Box Int
Box 5

Calculating webpage screen height

Now that our refresher is complete, we’re ready to calculate the screen height from the DOM. I translated Brian’s JavaScript code directly into PureScript, so be sure to review his code first, so that you understand the context of this example.

I chose to model the Selector DOM node element using a record type; creating an instance of show to help log the screen height to the console:

newtype Selector = 
  Selector { selector :: String , height :: Int } instance 

showSelector :: Show Selector where 
  show (Selector s) = show s.height

If you’re not familiar with the newtype keyword, this algebraic data type (ADT) gives us the ability to name an existing type constructor. In our case it’s is a record describing the name of the selector and its height. There is no performance penalty from using newtypes because its values have the same runtime representation as the underlying type. Be sure to check out 5.12 Algebraic Data Types from 'PureScript by Example' for further details.

Next, we’ll stub in a function that takes a fake DOM node element name as an argument, and uses this name to construct a Selector. We'll wrap the Selector in an Either constructor, introduced in Tutorial 3 to factor in the possibility of an error when retrieving this DOM node:

getSelector :: String -> Either Error Selector
getSelector selector = 
  pure $ Selector { selector, height: 10 }

Note once again our use of the pure method, which lifts functions or values into a functorial type constructor; be it a Functor, Applicative, or Monad type class. We used it to lift Selector into the Either type class constructor. Remember that this function is just a stub, and therefore there are no side-effects. So getSelector always returns Right $ Selector { selector, height: 10 }.

Here is the function that calculates our screen size height:

getScreenSize :: Int -> Selector -> Selector -> Selector getScreenSize screen (Selector header) (Selector footer) =
  Selector { selector: "screen"
           , height: screen - (header.height + footer.height) 
           }

This example is an excellent representation of PureScript’s pattern matching capabilities. Notice that we reference both the header and footer from inside the Selector type constructor, enabling the ability to calculate the height of our screen without any contortions. Nice!

Next, I’ll show two approaches for retrieving the header and footer selectors, before calling getScreenSize. The first approach is sequential, retrieving the header and footer by treating our Selector constructor as a monad. Hopefully, monads are familiar already. If not, then read You've been using Monads! first, before proceeding.

Treating Selector as a Monad

result1A :: Either Error Selector 
result1A = 
  (getSelector "header") >>= 
    \header -> (getSelector "footer") >>= 
       \footer -> pure $ getScreenSize 800 header footer

As a first cut, I might use monad chaining to retrieve the header size argument, followed by the footer. The above shows how to chain these two arguments using the bind operator >>=. However, from Tutorial 16, we know that chaining becomes difficult to read rapidly. Thus, for threading two or more arguments onto the next computation, I think that a do block is better for readability.

result1B :: Either Error Selector
result1B = do 
  header <- getSelector "header" 
  footer <- getSelector "footer" 
  pure $ getScreenSize 800 header footer

Treating Selector as an Applicative

Now onto the crux of this tutorial. Given that retrieval of both the header and footer nodes are independent operations, let’s treat the Selector constructor as an Applicative Functor and use apply to retrieve these arguments in parallel.

result2 :: Either Error Selector
result2 = 
  pure (getScreenSize 800) <*> (getSelector "header") <*>
       (getSelector "footer")

-- | Shorten result2 by using lift2 
result3 :: Either Error Selector 
result3 = lift2 (getScreenSize 800) (getSelector "header")
                (getSelector "footer")

The above example shows two approaches; result2 uses the infix operator for apply, namely <*>. The result3 function is slightly shorter because it uses the lift2 helper method; declaring the two arguments required by the function.

There is actually one more approach, introduced in PureScript compiler version 0.12, which takes advantage of Applicative do-notation. The syntax is similar to do-notation, which we saw in result1B from the code example above. However, instead of treating Selector as a monad, we use the ado keyword to tell the compiler to treat it as an Applicative. We also replace pure with the in keyword.

A key motivation for ado is that Applicative syntax can be difficult to read and write, particularly when there are more than two functorial arguments. For example (co-opted from the Glasgow Haskell Compiler documentation):

(\x y z → x*y + y*z + z*x) <$> expr1 <*> expr2 <*> expr3

vs.

ado 
 x <- expr1
 y <- expr2
 z <- expr3
 in (x*y + y*z + z*x)

shows how we can make use of all the applicative benefits while still being able to use do-notation sugar. Similarly, rewriting our getScreenSizeexample to take advantage of Applicative do-notation is a trivial exercise:

result4 :: Either Error Selector
result4 = ado
 header <- getSelector “header”
 footer <- getSelector “footer
 in getScreenSize 800 header footer

As a final point, I should mention that this all works thanks to currying, which I covered in Tutorial 17. That is, getScreenSize becomes a series of nested functions. This means that the expression result = getScreenSize 800 (getSelector "header") (getSelector "footer") is transformed to f1 = getScreenSize 800 ; f2 = f1 (getSelector "header") ; and result = f2 (getSelector "footer") .

Summary

In this tutorial, we saw an example of how to employ Applicatives in our code. Whenever you need to apply a function to multiple functorial arguments, and their calculation or retrieval is independent of one another, then it’s best to treat the type constructor as an Applicative, rather than a Monad (see Treating Selector as an Applicative). This way, we can calculate or retrieve the function's arguments in parallel. On the hand, if the value of one or more function arguments is dependent on the value of another argument, then treat the type constructor as a Monad. This approach calculates or retrieves the arguments sequentially; threading the values through the monad until you have your final result (see Treating Selector as a Monad).

I hope, with this practical example, you found the concept of applying multiple functors as arguments to a function (i.e., Applicatives) to be easy to understand. In the next tutorial, I’ll show another practical example using list comprehensions. That is, using an Applicative Functor to create a list based on existing lists. If you’re enjoying these tutorials, then please help me to tell others by recommending this article and favoring it on social media. Thank you and until next time!