Need help with play-monadic-actions?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Kanaka-io
127 Stars 28 Forks Other 100 Commits 7 Opened issues

Description

A simple scala DSL to allow clean and monadic style for Play! Actions

Services available

!
?

Need anything else?

Contributors list

Play monadic actions

Build Status Gitter chat Coverage Status Maven Central

This little play module provides some syntactic sugar that allows boilerplate-free Actions using for-comprehensions.

Motivation

It is commonly admitted that controllers should be lean and only focus on parsing an incoming HTTP request, call (possibly many) service methods and finally build an HTTP response (preferably with a proper status). In the context of an asynchronous framework like Play!, most of these operations results are (or can be) wrapped in a

Future
, and since their outcome can be either positive or negative, these results have a type that is more or less isomorphic to
Future[Either[X, Y]]
.

This matter of facts raises some readability issues. Consider for example the following action :

class ExampleController extends Controller {

val beerOrderForm: Form[BeerOrder] = ??? def findAdultUser(id: String): Future[Either[UnderageError, User]] = ??? def sellBeer(beerName: String, customer: User): Future[Either[OutOfStockError, Beer]] = ???

def orderBeer() = Action.async { beerOrderForm.bindFromRequest().fold( formWithErrors => BadRequest(views.html.orderBeer(formWithErrors), beerOrder => findAdultUser(beerOrder.userId).map( _.fold( ue => Conflict(displayError(ue)), user => sellBeer(beerOrder.beerName, user).map( _.fold( oose => NotFound(displayError(oose)), beer => Ok(displayBeer(beer)
) )
) ) } }

This is pretty straightforward, and yet the different steps of the computation are not made very clear. And since I've typed this in a regular text editor with no syntax highlighting nor static code analysis, there is an obvious error that you may not have spotted (there's a

map
instead of a
flatMap
somewhere).

This library addresses this problem by defining a

Step[A]
monad, which is roughly a
Future[Either[Result, A]]
, but with a right bias on the
Either
part, and providing a little DSL to lift relevant types into this monad's context.

Using it, the previous example becomes :

import io.kanaka.monadic.dsl._

// don't forget to import an implicit ExecutionContext import play.api.libs.concurrent.Execution.Implicits.defaultContext

class ExampleController extends Controller {

val beerOrderForm: Form[BeerOrder] = ??? def findAdultUser(id: String): Future[Either[UnderageError, User]] = ??? def sellBeer(beerName: String, customer: User): Future[Either[OutOfStockError, Beer]] = ???

def orderBeer() = Action.async { for { beerOrder BadRequest(views.html.orderBeer(formWithErrors)) user Conflict(displayError(ue)) beer NotFound(displayError(oose))
} yield Ok(displayBeer(beer)) } }

IMPORTANT NOTE : one MUST provide an implicit

ExecutionContext
for the DSL to work

How it works

The DSL introduces the binary

?|
operator. The happy path goes on the left hand side of the operator and the error path goes on the right :
happy ?| error
. Such expression produces a
Step[A]
which has all the required methods to make it usable in a for-comprehension.

So for example, if a service methods

foo
returns a
Future[Option[A]]
, we assume the happy path to be the case where the
Future
succeeds with a
Some[A]
and the error path to be the case where it succeeds with a
None
(the case where the
Future
fails is already taken care of by play's error handler). So we need to provide a proper
Result
to be returned in the error case (most probably a
NotFound
) and then we can write
for {
 // ...
 a 

The

a
here would be of type
A
, meaning that we've extracted the meaningful value from the
Future[Option[A]]
return by
foo
. Of course, if
foo
returns a
Future[None]
the for-comprehension is not evaluated further, and returns
NotFound
.

The right hand side of the

?|
operator (the error management part) is a function (or a thunk) that must return a
Result
and whose input type depends of the type of the expression on the left hand side of the operator (see the table of supported conversions below).

Filtering and Pattern-matching

Step[_]
defines a
withFilter
method, which means that one can use pattern matching and filtering in for-comprehensions involving
Step[_]
.

For example, if

bar
is of type
Future[Option[(Int, String)]]
, one can write
for {
 (i, s) = i
} yield Ok(s.take(i))

Please note though that in the case where the predicate

s.length >= i
does not hold, the whole
Future
will fail with a
NoSuchElementException
, and there is no easy way to transform this failure into a user-specified
Result
.

Supported conversions

The DSL supports the following conversions :

| Defining module | Source type | Type of the right hand side | Type of the extracted value | | --- | --- | --- | --- | |

play-monadic-actions
|
Boolean
|
=> Result
|
Unit
| |
play-monadic-actions
|
Option[A]
|
=> Result
|
A
| |
play-monadic-actions
|
Try[A]
|
Throwable => Result
|
A
| |
play-monadic-actions
|
Either[B, A]
|
B => Result
|
A
| |
play-monadic-actions
|
Form[A]
|
Form[A] => Result
|
A
| |
play-monadic-actions
|
JsResult[A]
|
Seq[(JsPath, Seq[ValidationError])] => Result
|
A
| |
play-monadic-actions
|
Future[A]
|
Throwable => Result
|
A
| |
play-monadic-actions
|
Future[Boolean]
|
=> Result
|
Unit
| |
play-monadic-actions
|
Future[Option[A]]
|
=> Result
|
A
| |
play-monadic-actions
|
Future[Either[B, A]]
|
B => Result
|
A
| |
play-monadic-actions-cats
|
B Xor A
|
B => Result
|
A
| |
play-monadic-actions-cats
|
Future[B Xor A]
|
B => Result
|
A
| |
play-monadic-actions-cats
|
XorT[Future, B, A]
|
B => Result
|
A
| |
play-monadic-actions-cats
|
OptionT[Future, A]
|
=> Result
|
A
| |
play-monadic-actions-cats
|
Validated[B Xor A]
|
B => Result
|
A
| |
play-monadic-actions-cats
|
Future[Validated[B Xor A]]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
B \/ A
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
Future[B \/ A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
Validation[B, A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
EitherT[Future, B, A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
OptionT[Future, A]
|
Unit => Result
|
A
| |
play-monadic-actions-scalaz-7-1
|
Future[Validation[B, A]]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
B \/ A
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
Future[B \/ A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
Validation[B, A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
EitherT[Future, B, A]
|
B => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
OptionT[Future, A]
|
Unit => Result
|
A
| |
play-monadic-actions-scalaz-7-2
|
Future[Validation[B, A]]
|
B => Result
|
A
|

Installation

As of version

2.2.1
, all modules are published for Scala versions
2.11
up to
2.13
.

Using sbt :

Current version is 2.2.0 ~~~scala libraryDependencies += "io.kanaka" %% "play-monadic-actions" % "2.2.0" ~~~

There are also contrib modules for interoperability with scalaz and cats :

|module name|is compatible with / built against| | --- | --- | |play-monadic-actions-cats| cats 2.0.0| |play-monadic-actions-scalaz_7-2| scalaz 7.2.28|

Each of these module provides

Functor
and
Monad
instances for
Step[_]
as well as conversions for relevant types in the target library

These instances and conversions are made available by importing

io.kanaka.monadic.dsl.compat.cats._
and
io.kanaka.monadic.dsl.compat.scalaz._
respectively.

Compatibility

  • Version
    2.2.0
    is compatible with Play!
    2.7.x
  • Version
    2.1.0
    is compatible with Play!
    2.6.x
  • Version
    2.0.0
    is compatible with Play!
    2.5.x
  • Version
    1.1.0
    is compatible with Play!
    2.4.x
  • Version
    1.0.1
    is compatible with Play!
    2.3.x

From version

2.0.0
up, dependencies toward play and cats are defined as
provided
, meaning that you can use the DSL along with any version of these projects you see fit. The sample projects under
samples/
demonstrate this capability.

From version

2.1.0
up, the modules are published for scala
2.11
and
2.12
. Previous versions are only published for scala
2.11
.

Contributors

Valentin Kasas

Damien Gouyette

David R. Bild

Bjørn Madsen

Christophe Calves

Maxim Karpov

Richard Searle

Andrew Adams

... your name here

Credits

This project is widely inspired from the play-monad-transformers activator template by Lunatech.

It also uses coursier to fetch dependencies in parallel, which is a pure bliss. Take a look if you don't know it yet.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.