ploeh blog http://blog.ploeh.dk danish software design en-us Mark Seemann Wed, 22 Mar 2017 18:56:53 UTC Wed, 22 Mar 2017 18:56:53 UTC Dependency rejection http://blog.ploeh.dk/2017/02/02/dependency-rejection/ Thu, 02 Feb 2017 08:56:00 UTC <div id="post"> <p> <em>In functional programming, the notion of dependencies must be rejected. Instead, applications should be composed from pure and impure functions.</em> </p> <p> This is the third article in a small article series called <a href="http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection">from dependency injection to dependency rejection</a>. In the <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">previous article in the series</a>, you learned that dependency injection can't be functional, because it makes everything impure. In this article, you'll see what to do instead. </p> <p> <strong>Indirect input and output</strong> </p> <p> One of the first concepts you learned when you learned to program was that units of operation (functions, methods, procedures) take input and produce output. Input is in the form or input parameters, and output is in the form of return values. (Sometimes, though, a method returns nothing, but we know from category theory that nothing is also a value (called <em>unit</em>).) </p> <p> In addition to such input and output, a unit with dependencies also take indirect input, and produce indirect output: </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-and-indirect-input-and-output.png" alt="A unit with dependencies and direct and indirect input and output."> </p> <p> When a unit queries a dependency for data, the data returned from the dependency is indirect input. In the restaurant reservation example used in this article series, when <code>tryAccept</code> calls <code>readReservations</code>, the returned reservations are indirect input. </p> <p> Likewise, when a unit invokes a dependency, all arguments passed to that dependency constitute indirect output. In the example, when <code>tryAccept</code> calls <code>createReservation</code>, the reservation value it uses as input argument to that function call becomes output. The intent, in this case, is to save the reservation in a database. </p> <p> <strong>From indirect output to direct output</strong> </p> <p> Instead of producing indirect output, you can refactor functions to produce direct output. </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-input-and-output-but-no-indirect-output.png" alt="A unit with dependencies and direct input and output, but no indirect output."> </p> <p> Such a refactoring is often problematic in mainstream object-oriented languages like C# and Java, because you wish to control the circumstances in which the indirect output must be produced. Indirect output often implies side-effects, but perhaps the side-effect must only happen when certain conditions are fulfilled. In the restaurant reservation example, the desired side-effect is to add a reservation to a database, but this must only happen when the restaurant has sufficient remaining capacity to serve the requested number of people. Since languages like C# and Java are statement-based, it can be difficult to separate the decision from the action. </p> <p> In expression-based languages like F# and Haskell, <a href="http://blog.ploeh.dk/2016/09/26/decoupling-decisions-from-effects">it's trivial to decouple decisions from effects</a>. </p> <p> In the <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">previous article</a>, you saw a version of <code>tryAccept</code> with this signature: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;(DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list)&nbsp;-&gt;&nbsp;(Reservation&nbsp;-&gt;&nbsp;int)&nbsp;-&gt;&nbsp;Reservation</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;int&nbsp;option</span></pre> </p> <p> The second function argument, with the type <code>Reservation&nbsp;-&gt;&nbsp;int</code>, produces indirect output. The <code>Reservation</code> value is the output. The function even violates Command Query Separation and returns the database ID of the added reservation, so that's additional indirect input. The overall function returns <code>int option</code>: the database ID if the reservation was added, and <code>None</code> if it wasn't. </p> <p> Refactoring the indirect output to direct output is easy, then: just remove the <code>createReservation</code> function and return the <code>Reservation</code> value instead: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;(DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list)&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Reservation&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">readReservations</span>&nbsp;reservation.Date&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;reservedSeats&nbsp;+&nbsp;reservation.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">None</span></pre> </p> <p> Notice that this refactored version of <code>tryAccept</code> returns a <code>Reservation option</code> value. The implication is that the reservation was accepted if the return value is a <code>Some</code> case, and rejected if the value is <code>None</code>. The decision is embedded in the value, but decoupled from the side-effect of writing to the database. </p> <p> This function clearly never writes to the database, so at the boundary of your application, you'll have to connect the decision to the effect. To keep the example consistent with the previous article, you can do this in a <code>tryAcceptComposition</code> function, like this: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAcceptComposition</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;10&nbsp;(<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;connectionString) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">DB</span>.<span style="color:navy;">createReservation</span>&nbsp;connectionString)</pre> </p> <p> Notice that the type of <code>tryAcceptComposition</code> remains <code>Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</code>. This is a true refactoring. The overall API remains the same, as does the behaviour. The reservation is added to the database only if there's sufficient remaining capacity, and in that case, the ID of the reservation is returned. </p> <p> <strong>From indirect input to direct input</strong> </p> <p> Just as you can refactor from indirect output to direct output can you refactor from indirect input to direct input. </p> <p> <img src="/content/binary/unit-with-dependencies-and-direct-input-and-output.png" alt="A unit with dependencies and direct input and output."> </p> <p> Again, in statement-based languages like C# and Java, this may be problematic, because you may wish to defer a query, or base it on a decision inside the unit. In expression-based languages you can decouple decisions from effects, and deferred execution can always be done by lazy evaluation, if that's required. In the case of the current example, however, the refactoring is easy: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;list&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Reservation&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;=&nbsp;reservations&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;reservedSeats&nbsp;+&nbsp;reservation.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">None</span></pre> </p> <p> Instead of calling a (potentially impure) function, this version of <code>tryAccept</code> takes a list of existing reservations as input. It still sums over all the quantities, and the rest of the code is the same as before. </p> <p> Obviously, the list of existing reservations must come from somewhere, like a database, so <code>tryAcceptComposition</code> will still have to take care of that: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;c)&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;c</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">flip</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;y&nbsp;=&nbsp;<span style="color:navy;">f</span>&nbsp;y&nbsp;x <span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAcceptComposition</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;reservation.Date &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">flip</span>&nbsp;(<span style="color:navy;">tryAccept</span>&nbsp;10)&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">DB</span>.<span style="color:navy;">createReservation</span>&nbsp;connectionString)</pre> </p> <p> The type and behaviour of this composition is still the same as before, but the data flow is different. First, the function queries the database, which is an impure operation. Then, it pipes the resulting list of reservations to <code>tryAccept</code>, which is now a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>. It returns a <code>Reservation option</code> that's finally mapped to another impure operation, which writes the reservation to the database if the reservation was accepted. </p> <p> You'll notice that I also added a <code>flip</code> function in order to make the composition more concise, but I could also have used a lambda expression when invoking <code>tryAccept</code>. The <code>flip</code> function is a part of Haskell's standard library, but isn't in F#'s core library. It's not crucial to the example, though. </p> <p> <strong>Evaluation</strong> </p> <p> Did you notice that in the previous diagram, above, all arrows between the unit and its dependencies were gone? This means that the unit no longer has any dependencies: </p> <p> <img src="/content/binary/unit-with-direct-input-and-output.png" alt="A unit with direct input and output, but no dependencies."> </p> <p> Dependencies are, by their nature, impure, and since pure functions can't call impure functions, functional programming must reject the notion of dependencies. Pure functions can't <em>depend</em> on impure functions. </p> <p> Instead, pure functions must take direct input and produce direct output, and the impure boundary of an application must compose impure and pure functions together in order to achieve the desired behaviour. </p> <p> In the previous article, you saw how Haskell can be used to evaluate whether or not an implementation is functional. You can port the above F# code to Haskell to verify that this is the case. </p> <p> <pre><span style="color:#600277;">tryAccept</span>&nbsp;::&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Reservation</span>]&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Maybe&nbsp;<span style="color:blue;">Reservation</span> tryAccept&nbsp;capacity&nbsp;reservations&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">=</span>&nbsp;sum&nbsp;<span style="color:#666666;">$</span>&nbsp;map&nbsp;quantity&nbsp;reservations &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">+</span>&nbsp;quantity&nbsp;reservation&nbsp;<span style="color:#666666;">&lt;=</span>&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;Just&nbsp;<span style="color:#666666;">$</span>&nbsp;reservation&nbsp;{&nbsp;isAccepted&nbsp;<span style="color:#666666;">=</span>&nbsp;True&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;Nothing</pre> </p> <p> This version of <code>tryAccept</code> is pure, and compiles, but as you learned in the previous article, that's not the crucial question. The question is whether the composition compiles? </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;runMaybeT&nbsp;<span style="color:#666666;">$</span> &nbsp;&nbsp;liftIO&nbsp;(<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;connectionString&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation) &nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;<span style="color:#dd0000;">MaybeT</span>&nbsp;<span style="color:#666666;">.</span>&nbsp;return&nbsp;<span style="color:#666666;">.</span>&nbsp;flip&nbsp;(tryAccept&nbsp;<span style="color:#09885a;">10</span>)&nbsp;reservation &nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;liftIO&nbsp;<span style="color:#666666;">.</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString</pre> </p> <p> This version of <code>tryAcceptComposition</code> compiles, and works as desired. The code exhibits a common pattern for Haskell: First, gather data from impure sources. Second, pass pure data to pure functions. Third, take the pure output from the pure functions, and do something impure with it. </p> <p> It's like a sandwich, with the best parts in the middle, and some necessary stuff surrounding it. </p> <p> <strong>Summary</strong> </p> <p> Dependencies are, by nature, impure. They're either non-deterministic, have side-effects, or both. Pure functions can't call impure functions (because that would make them impure as well), so pure functions can't have dependencies. Functional programming must reject the notion of dependencies. </p> <p> Obviously, software is only useful with impure behaviour, so instead of injecting dependencies, functional programs must be composed in impure contexts. Impure functions can call pure functions, so at the boundary, an application must gather impure data, and use it to call pure functions. This <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">automatically leads to the ports and adapters architecture</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://dusted.codes/">Dustin Moris Gorski</a></div> <div class="comment-content"> <p>Hi, Thank you for this blog post series. I also read your other posts on ports and adapters and the proposed architecture makes sense in terms of how it works, but I struggle to see the benefit in a real world application. Maybe let me explain my question with a quick example.</p> <p>In the 2nd blog post of this series you demonstrated this function:</p> <pre><code>// int -&gt; (DateTimeOffset -&gt; Reservation list) -&gt; (Reservation -&gt; int) -&gt; Reservation // -&gt; int option let tryAccept capacity readReservations createReservation reservation = let reservedSeats = readReservations reservation.Date |&gt; List.sumBy (fun x -&gt; x.Quantity) if reservedSeats + reservation.Quantity &lt;= capacity then createReservation { reservation with IsAccepted = true } |&gt; Some else None</code></pre> <p>If I understand it correctly this function is pure if <code>readReservations</code> and <code>createReservation</code> are both pure otherwise it is impure.</p> <p>I also understand the benefit of having a pure function, because it is a lot easier to understand the code, test the code and reason about it. That makes sense as well :).</p> <p>So in the 3rd blog post you make <code>tryAccept</code> a pure function, by removing the function dependencies and replacing it with simple values:</p> <pre><code>// int -&gt; Reservation list -&gt; Reservation -&gt; Reservation option let tryAccept capacity reservations reservation = let reservedSeats = reservations |&gt; List.sumBy (fun x -&gt; x.Quantity) if reservedSeats + reservation.Quantity &lt;= capacity then { reservation with IsAccepted = true } |&gt; Some else None</code></pre> <p>However this was only possible because you essentially moved the impure code into another new function:</p> <pre><code>// Reservation -&gt; int option let tryAcceptComposition reservation = reservation.Date |&gt; DB.readReservations connectionString |&gt; flip (tryAccept 10) reservation |&gt; Option.map (DB.createReservation connectionString)</code></pre> <p>So after all the application hasn't really reduced the total number of impure functions (still 3 in each case - <code>readReservations</code>, <code>createReservation</code> and <code>tryAccept[Composition]</code>).</p> <p>The only difference I see is that one impure function has been refactored into 2 functions - one pure and one impure. Considering that the original <code>tryAccept</code> function was already fully testable from a unit testing point of view and quite readable what is the benefit of this additional step? I would almost argue that the original <code>tryAccept</code> function was even easier to read/understand than the combination of <code>tryAccept</code> and <code>tryAcceptComposition</code>. I understand that impure functions like this are not truly functional, but in a real world application you must have some impure functions and I would like to better understand where trade-off benefit of that additional step is? Am I missing something else?</p> <p></p> </div> <div class="comment-date">2017-02-03 10:34 UTC</div> </div> <div class="comment"> <div class="comment-author"> <a href="http://blog.ploeh.dk">Mark Seemann</a> </div> <div class="comment-content"> </div> <p> Dustin, thank you for writing. There are several answers to your question, depending on the perspective one is interested in. I'll see if I can cover the most important ones. </p> <p> <strong>Is it functional?</strong> </p> <p> On the most fundamental level, I'm interested in learning functional programming. In order to do this, I seek out strictly functional solutions to problems. Haskell is a great help in that endeavour, because it's not a hybrid language. It only allows you to do functional programming. </p> <p> Does it make sense to back-port Haskell solutions to F#, then? That depends on what one is trying to accomplish, but if the goal is nothing but learning how to do it functionally, then that goal is accomplished. </p> <p> <strong>Toy examples</strong> </p> <p> On another level, the example I've presented here is obviously nothing but a toy example. It's simplified, because if I presented readers with a more realistic example, the complexity of the real problem could easily drown out the message of the example. Additionally, most readers would probably give up reading. </p> <p> I'm asking my readers to pretend that the problem is more complex than the one I present here; pretend that this problem is a stand-in for a harder problem. </p> <p> In this particular context, there could be all sorts of complications: <ul> <li> Reservations could be for time slots instead of whole dates. In order to keep the example simple, I treat each reservation as simply blocking out an entire date. I once dined at a restaurant where they started serving at 19:00, and if you weren't there on time, you'd miss the first courses. Most restaurants, though, allow you to make reservations for a particular time, and many have more than one serving on a single evening. </li> <li> Most restaurants have tables, not seats. Again, the same restaurant I mentioned above seated 12 people at a bar-like arrangement facing the kitchen, but most restaurants have tables of varying sizes. If they get a reservation for three people, they may have to reserve a table for four. </li> <li> Perhaps the restaurant would like to implement a feature where, if it receives a reservation that doesn't fill out a table (like a reservation for three people, and only four-people tables are left), it'd defer the decision to see if a 'better' reservation arrives later. </li> <li> Some people make reservations, but never show up. For that reason, a restaurant may want to allow a degree of overbooking, just like airlines. How much overbooking to allow is a business decision. </li> <li> A further wrinkle on the overbooking business rule is that you may have a different overbooking policy for Fridays than for, say, Wednesdays. </li> <li> Perhaps the restaurant would like to implement a waiting-list feature as well. </li> </ul> As you can see, we could easily imagine that the business logic could be more convoluted. Keeping all of that decision logic pure would be beneficial. </p> <p> <strong>Separation of concerns</strong> </p> <p> In my experience, there's an entire category of software defects that occur because of state mutation in business logic. You could have an area of your code that calls other code, which calls other code, and so on, for several levels of nesting. Somewhere, deep in the bowels of such a system, a conditional statement flips a boolean flag that consequently impact how the rest of the program runs. I've seen plenty of examples of such software, and it's inhumane; it doesn't fit within human cognitive limits. </p> <p> Code that allows arbitrary side-effects is difficult to reason about. </p> <p> Knowing that an subgraph of your call tree is pure reduces defects like that. This is nothing but another way to restate the <a href="https://en.wikipedia.org/wiki/Command%E2%80%93query_separation">command-query separation</a> principle. In F#, we still can't be sure unless we exert some discipline, but in Haskell, all it takes is a look at the type of a function or value. If it doesn't include <code>IO</code>, you know that it's pure. </p> <p> Separating pure code from impure code is separation of concern. Business logic is one concern, and I/O is another concern, and the better you can separate these, the fewer sources of defects you'll have. True, I haven't reduced the amount of code by much, but I've <em>separated</em> concerns by separating the code that contains (side) effects from the pure code. </p> <p> <strong>Testability</strong> </p> <p> It's true that the partial application version of <code>tryAccept</code> is <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">testable, because it has isolation</a>, but the tests are more complicated than they have to be: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">NonNegativeInt</span>&nbsp;excessCapacity) &nbsp;&nbsp;&nbsp;&nbsp;(expected&nbsp;:&nbsp;<span style="color:teal;">int</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;excessCapacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;(reservations&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;reservation.Quantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;=&nbsp;((=!)&nbsp;reservation.Date)&nbsp;&gt;&gt;!&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((=!)&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;})&nbsp;&gt;&gt;!&nbsp;expected &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;expected&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&#39;t&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">PositiveInt</span>&nbsp;lackingCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(reservations&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity))&nbsp;-&nbsp;lackingCapacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;_&nbsp;=&nbsp;reservations &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;_&nbsp;=&nbsp;<span style="color:navy;">failwith</span>&nbsp;<span style="color:#a31515;">&quot;Mock&nbsp;shouldn&#39;t&nbsp;be&nbsp;called.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">None</span>&nbsp;=!&nbsp;actual</pre> </p> <p> (You can find these tests in <a href="https://github.com/ploeh/dependency-rejection-samples/commit/d2387cceb81eabc349a63ab7df1249236e9b1d13">commit d2387cceb81eabc349a63ab7df1249236e9b1d13 in the accompanying sample code repository</a>.) Contrast those dependency-injection style tests to these tests against the pure version of <code>tryAccept</code>: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">NonNegativeInt</span>&nbsp;excessCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;excessCapacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;(reservations&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;reservation.Quantity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">Some</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``tryAccept&nbsp;behaves&nbsp;correctly&nbsp;when&nbsp;it&nbsp;can&#39;t&nbsp;accept``</span> &nbsp;&nbsp;&nbsp;&nbsp;(<span style="color:navy;">PositiveInt</span>&nbsp;lackingCapacity)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span>&nbsp;<span style="color:navy;">id</span> &nbsp;&nbsp;&nbsp;&nbsp;&lt;!&gt;&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;&lt;*&gt;&nbsp;<span style="color:teal;">Gen</span>.<span style="color:navy;">listOf</span>&nbsp;<span style="color:teal;">Gen</span>.reservation &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;&nbsp;<span style="color:teal;">Arb</span>.<span style="color:navy;">fromGen</span>&nbsp;|&gt;&nbsp;<span style="color:teal;">Prop</span>.<span style="color:navy;">forAll</span>&nbsp;&lt;|&nbsp;<span style="color:blue;">fun</span>&nbsp;(reservation,&nbsp;reservations)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;capacity&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(reservations&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity))&nbsp;-&nbsp;lackingCapacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;reservations&nbsp;reservation &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">None</span>&nbsp;=!&nbsp;actual</pre> </p> <p> They're simpler, and since they don't use <a href="http://xunitpatterns.com/Mock%20Object.html">mocks</a>, they're more robust. They were easier to write, and I subscribe to the spirit of <a href="http://amzn.to/SM8Yv0">GOOS</a>: <em>if test are difficult to write, the system under test should be simplified</em>. </p> <div class="comment-date">2017-02-05 20:09 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://stackoverflow.com/users/1523776/benjamin-hodgson?tab=profile">Benjamin Hodgson</a></div> <div class="comment-content"> <p>Hi Mark,</p> <p>Thanks for your talk at NDC last month, and for writing this series! I feel that the functional community (myself included) has a habit of using examples that aren't obviously relevant to the sort of line-of-business programming most of us do in our day jobs, so articles like this are sorely needed.</p> <p>We talked a little about this in person after your talk at the conference: I wanted to highlight a potential criticism of this style of programming. Namely, there's still some important business logic being carried out by your <code>tryAcceptComposition</code> function, like checking the capacity <i>on the requested reservation date</i>. How do you unit test that <code>readReservations</code> is called with the correct date? Likewise, how do you unit test that rejected reservations don't get saved? Real world business logic isn't always purely functional in nature. Sometimes the side effects that your code performs are part of the requirements.</p> <p>The Haskell philosophy isn't about rejecting side effects outright - it's about measuring and controlling them. I wouldn't write <code>tryAcceptComposition</code> using <code>IO</code>. Instead I'd program to the interface, not the implementation, using an mtl-style class to abstract over monads which support saving and loading reservations.</p> <pre><code>class Monad m =&gt; MonadReservation m where readReservations :: ConnectionString -&gt; Date -&gt; m [Reservation] createReservation :: ConnectionString -&gt; Reservation -&gt; m ReservationId tryAcceptComposition :: MonadReservation m =&gt; Reservation -&gt; m (Maybe ReservationId) tryAcceptComposition r = runMaybeT $ do reservations &lt;- lift $ readReservations connectionString (date r) accepted &lt;- MaybeT $ return $ tryAccept 10 reservations r lift $ createReservation connectionString accepted</code></pre> <p>Code that lives in a <code>MonadReservation</code> context can read and create reservations in the database but nothing else; it doesn't have all the power of <code>IO</code>. During unit testing I can use an instance of <code>MonadReservation</code> that returns canned values, and in production I can use a monad that actually talks to the database.</p> <p>Since type classes are syntactic sugar for passing an argument, this is really just a nicer way of writing your original DI-style code. I don't advocate the "free monad" style that's presently trendy in Scala-land because I find it unnecessarily complex. 90% of the purported advantages of free monads are already supported by simpler language features.</p> <p>I suppose the main downside of this design is that you can't express it in F#, at least not cleanly. It relies on type classes and higher-kinded types.</p> <p>Hope you find this interesting, I'd love to hear what you think!</p> <p>Benjamin</p> </div> <div class="comment-date">2017-02-06 16:28 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Benjamin, thank you for writing. The alternative you propose looks useful in Haskell, but, as you've already suggested, it doesn't translate well into F#. </p> <p> I write F# code professionally, whereas so far, I've only used Haskell to critique my F# code. (If someone who reads this comment would offer to pay me to write some Haskell code, please get in touch.) In other words, I still have much to learn about Haskell. I think I understand as much, however, that I'd be able to use your suggested design to unit test <code>tryAcceptComposition</code> using the <code>Identity</code> monad for Stubs, or perhaps <code>MonadWriter</code> or <code>MonadState</code> for Mocks. I'll have to try that one day... </p> <p> In F#, I write integration tests. Such tests are important regardless, and often they more closely relate to actual requirements, so I find this a worthwhile effort anyway. </p> </div> <div class="comment-date">2017-02-11 22:42 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="https://twitter.com/la_yumba">Enrico Buonanno</a></div> <div class="comment-content"> <p> Hi Mark, </p> <p> thanks for the post series, which I find interesting and needed. There is one part of your post that I find deserves further exploration. You write: <blockquote> in statement-based languages like C# and Java, this may be problematic, because you may wish to defer a query, or base it on a decision inside the unit. In expression-based languages you can decouple decisions from effects, and deferred execution can always be done by lazy evaluation, if that's required. </blockquote> Firstly, I would say that you can write expression-based programs in any language that has expressions, which naturally includes C# and Java. But that's not particularly relevant to this discussion. </p> <p> More to the point, you're glossing over this as though it were a minor detail, when in fact I don't think it is. Let's explore the case in which "you may wish to defer a query, or base it on a decision inside the unit". The way you do this "by lazy evaluation" would be - I assume - by passing a function as an argument to your unit. But this is then effectively dependency injection, because you're passing in a function which has side effects, which will be called (or not) from the unit. </p> <p> So, it seems to me that your technique of extracting side effects out of the unit provides a good general guideline, but not a completely general way to replace dependency injection. </p> </div> <div class="comment-date">2017-02-16 11:47 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Enrico, thank you for writing. There's a lot to unpack in that quote, which was one of the reasons I didn't expand it. It would have made the article too long, and wandered off compared to its main point. I don't mind going into these details here, though. </p> <p> <strong>Direction of data</strong> </p> <p> In order to get the obvious out of the way first, the issue you point out is with my refactoring of indirect input to direct input. Refactoring from indirect to output to direct output is, as far as I can tell, not on your agenda. Designing with direct input in mind seems uncontroversial to me, so that makes sense. </p> <p> <strong>No hard rules</strong> </p> <p> On this blog, I often write articles as I figure out how to deal with problems. Sometimes, I report on my discoveries at a time where I've yet to accumulate years of experience. What I've learned so far is that dependency injection isn't functional. What I'm <em>still</em> exploring is what to do instead. </p> <p> It's my experience that the type of refactoring I demonstrate here can surprisingly often be performed. I don't want to claim that it's always possible to do it like this. In fact, I'm still looking for good examples where this will not be possible. Whenever I think of a simple enough example that I could share it here, I always realise that if only I simplify the problem, I can put it into the shape seen here. </p> <p> My thinking is, however, constrained by my professional experience. I've been doing web (service) development for so many years now that it constraints my imagination. When you execution scope is exclusively a single HTTP request at a time, you tend to keep things simple. I'd welcome a simplified, but still concrete example where the impure/pure/impure sandwich described here isn't going to be possible. </p> <p> This may seem like a digression, but my point is that I don't claim to be the holder of a single, undeniable truth. Still, I find that this article describes a broadly applicable design and implementation technique. </p> <p> <strong>Language specifics</strong> </p> <p> The next topic we need to consider is our choice of language. When I wrote that deferred execution can always be done by lazy evaluation, that's exactly how Haskell works. Haskell is lazily evaluated, so any value passed as direct input can be unevaluated until required. That goes for <code>IO</code> as well, but then, as we've learned, you can't pass impure data to a pure function. </p> <p> All execution is, in that sense, deferred, unless explicitly forced. Thus, any potential need for deferred execution has no design implications. </p> <p> F#, on the other hand, is an eagerly evaluated language, so there, deferred execution may have design implications. </p> <p> <strong>Performance</strong> </p> <p> Perhaps it's my lack of imagination again, but I can't think of a well-designed system where deferred execution is required for purposes of correctness. As far as I can tell, deferred execution is a performance concern. You wish to defer execution of a query because that operation takes significant time. </p> <p> That's a real concern, but I often find that people worry too much about performance. Again, this is probably my lack of wider experience, as I realise that performance can be important in smart phone apps, games, and the like. Clearly, performance is also important in the world of REST APIs, but I've met a lot of people who worry about performance without ever measuring it. </p> <p> When you start measuring performance, you'll often be surprised to discover where your code spends actual time. So my design approach is always to prioritise making the system work first, and then, if there are performance problems, figure out how to tweak it so that it becomes satisfactory. In my experience, such tweaking is only necessary now and then. I'm not claiming that my code is the fastest it could be, but it's often fast enough, and as easy to maintain as I can make it. </p> <p> <strong>The need for data</strong> </p> <p> Another concern is the need for data. If you consider the above <code>tryAccept</code> function, it <em>always</em> uses <code>reservations</code>. Thus, there's no gain in deferring the database query, because you'll always need the data. </p> <p> Deferred execution is only required in those cases where you have conditional branching, and only in certain cases do you need to read a particular piece of data. </p> <p> Even conditional branching isn't enough of a criterion, though, because you could have branching where, in 99.9 % of the cases, you'd be performing the query anyway. Would you, then, need deferred execution for the remaining 0.1 % of the cases? </p> <p> <strong>Lazy sequences</strong> </p> <p> Still, let's assume that we've implemented a system using pure functions that take pure data, but to our dismay we discover that there's one query that takes time to execute, and that we truly only need it some of the time. In .NET, there are two distinct situations: <ul> <li>We need a scalar value</li> <li>We need a collection of values</li> </ul> If we need a collection of values, we only need to make a minuscule change to the design of our function. Instead of taking an F# list, or an array, as direct input, we can make the function take a sequence (<code>IEnumerable&lt;T&gt;</code> in C#) as input. These can be implemented as lazily evaluated sequences, which gives us the deferred execution we need. </p> <p> <strong>Lazy scalar values</strong> </p> <p> This leaves the corner case where we need a lazily evaluated scalar value. In such cases, I may have to make a concession to performance in my function design, but I wouldn't change the argument to a function, but rather to a <a href="https://docs.microsoft.com/en-us/dotnet/articles/fsharp/language-reference/lazy-computations">lazy</a> value. </p> <p> Lazy values are deferred, but memoised, which is the reason I'd prefer them over function arguments. </p> </div> <div class="comment-date">2017-02-18 19:54 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2017/02/02/dependency-rejection Partial application is dependency injection http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection/ Mon, 30 Jan 2017 12:40:00 UTC <div id="post"> <p> <em>The equivalent of dependency injection in F# is partial function application, but it isn't functional.</em> </p> <p> This is the second article in a small article series called <a href="http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection">from dependency injection to dependency rejection</a>. </p> <p> People often ask me how to do dependency injection in F#. That's only natural, since I wrote <a href="http://amzn.to/12p90MG">Dependency Injection in .NET</a> some years ago, and also since I've increasingly focused my energy on F# and other functional programming languages. </p> <p> Over the years, I've seen other F# experts respond to that question, and often, the answer is that partial function application is the F# way to do dependency injection. For some years, I believed that as well. It turns out to be true in one sense, but incorrect in another. Partial application <em>is</em> equivalent to dependency injection. It's just not a functional solution to dealing with dependencies. </p> <p> (To be as clear as I can be: I'm not claiming that partial application isn't functional. What I claim is that partial application used for dependency injection isn't functional.) </p> <p> <strong>Attempted dependency injection using functions</strong> </p> <p> Returning to the example from the <a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">previous article</a>, you could try to rewrite <code>MaîtreD.TryAccept</code> as a function: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;(DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list)&nbsp;-&gt;&nbsp;(Reservation&nbsp;-&gt;&nbsp;int)&nbsp;-&gt;&nbsp;Reservation</span> <span style="color:green;">//&nbsp;-&gt;&nbsp;int&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;capacity&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">readReservations</span>&nbsp;reservation.Date&nbsp;|&gt;&nbsp;<span style="color:teal;">List</span>.<span style="color:navy;">sumBy</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;x&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;x.Quantity) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;reservedSeats&nbsp;+&nbsp;reservation.Quantity&nbsp;&lt;=&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;{&nbsp;reservation&nbsp;<span style="color:blue;">with</span>&nbsp;IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>&nbsp;}&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">None</span></pre> </p> <p> You could imagine that this <code>tryAccept</code> function is part of a module called <code>MaîtreD</code>, just to keep the examples as equivalent as possible. </p> <p> The function takes four arguments. The first is the capacity of the restaurant in question; a primitive integer. The next two arguments, <code>readReservations</code> and <code>createReservation</code> fill the role of the injected <code>IReservationsRepository</code> in the previous article. In the object-oriented example, the <code>TryAccept</code> method used two methods on the repository: <code>ReadReservations</code> and <code>Create</code>. Instead of using an interface, in the F# function, I make the function take two independent functions. They have (almost) the same types as their C# counterparts. </p> <p> The first three arguments correspond to the injected dependencies in the previous <code>MaîtreD</code> class. The fourth argument is a <code>Reservation</code> value, which corresponds to the input to the previous <code>TryAccept</code> method. </p> <p> Instead of returning a nullable integer, this F# version returns an <code>int option</code>. </p> <p> The implementation is also equivalent to the C# example: Read the relevant reservations from the database using the <code>readReservations</code> function argument, and sum over their quantities. Based on the number of already reserved seats, decide whether or not to accept the reservation. If you can accept the reservation, set <code>IsAccepted</code> to <code>true</code>, call the <code>createReservation</code> function argument, and pipe the returned ID (integer) to <code>Some</code>. If you can't accept the reservation, then return <code>None</code>. </p> <p> Notice that the first three arguments are 'dependencies', whereas the last argument is the 'actual input', if you will. This means that you can use partial function application to compose this function. </p> <p> <strong>Application</strong> </p> <p> If you recall the definition of the previous <code>IMaîtreD</code> interface, the <code>TryAccept</code> method was defined like this (C# code snippet): </p> <p> <pre><span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation);</pre> </p> <p> You could attempt to define a similar function with the type <code>Reservation -&gt; int option</code>. Normally, you'd want to do this closer to the boundary of the application, but the following example demonstrates how to 'inject' real database operations into the function. </p> <p> Imagine that you have a <code>DB</code> module with these functions: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;<span style="color:teal;">DB</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;DateTimeOffset&nbsp;-&gt;&nbsp;Reservation&nbsp;list</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">readReservations</span>&nbsp;<span style="color:#9b9b9b;">connectionString</span>&nbsp;<span style="color:#9b9b9b;">date</span>&nbsp;=&nbsp;<span style="color:green;">//&nbsp;..</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;int</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">createReservation</span>&nbsp;<span style="color:#9b9b9b;">connectionString</span>&nbsp;<span style="color:#9b9b9b;">reservation</span>&nbsp;=&nbsp;<span style="color:green;">//&nbsp;..</span></pre> </p> <p> The <code>readReservations</code> function takes a connection string and a date as arguments, and returns a list of reservations for that date. The <code>createReservation</code> function also takes a connection string, as well as a reservation. When invoked, it creates a new record for the reservation and returns the ID of the newly created row. (This sort of API violates CQS, so you should <a href="http://blog.ploeh.dk/2016/05/06/cqs-and-server-generated-entity-ids">consider alternatives</a>.) </p> <p> If you partially apply these functions with a valid connection string, both have the type desired for their roles in <code>tryAccept</code>. This means that you can create a function from these elements: </p> <p> <pre><span style="color:green;">//&nbsp;Reservation&nbsp;-&gt;&nbsp;int&nbsp;option</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">tryAcceptComposition</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">read</span>&nbsp;&nbsp;&nbsp;=&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">readReservations</span>&nbsp;&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">create</span>&nbsp;=&nbsp;<span style="color:teal;">DB</span>.<span style="color:navy;">createReservation</span>&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">tryAccept</span>&nbsp;10&nbsp;<span style="color:navy;">read</span>&nbsp;<span style="color:navy;">create</span></pre> </p> <p> Notice how <code>tryAccept</code> itself is partially applied. Only the arguments corresponding to the C# dependencies are passed to it, so the return value is a function that 'waits' for the last argument: the reservation. As I've attempted to indicate by the code comment above the function, it has the desired type of <code>Reservation -&gt; int option</code>. </p> <p> <strong>Equivalence</strong> </p> <p> Partial application used like this is equivalent to dependency injection. To see how, consider the generated Intermediate Language (IL). </p> <p> F# is a .NET language, so it compiles to IL. You can decompile that IL to C# to get a sense of what's going on. If you do that with the above <code>tryAcceptComposition</code>, you get something like this: </p> <p> <pre><span style="color:blue;">internal</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">tryAcceptComposition@17&nbsp;:&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:#2b91af;">FSharpOption</span>&lt;<span style="color:blue;">int</span>&gt;&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;createReservation; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">DateTimeOffset</span>,&nbsp;<span style="color:#2b91af;">FSharpList</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&nbsp;readReservations; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">internal</span>&nbsp;tryAcceptComposition@17( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;capacity, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">DateTimeOffset</span>,&nbsp;<span style="color:#2b91af;">FSharpList</span>&lt;<span style="color:#2b91af;">Reservation</span>&gt;&gt;&nbsp;readReservations, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">FSharpFunc</span>&lt;<span style="color:#2b91af;">Reservation</span>,&nbsp;<span style="color:blue;">int</span>&gt;&nbsp;createReservation) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity&nbsp;=&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.readReservations&nbsp;=&nbsp;readReservations; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.createReservation&nbsp;=&nbsp;createReservation; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">override</span>&nbsp;<span style="color:#2b91af;">FSharpOption</span>&lt;<span style="color:blue;">int</span>&gt;&nbsp;Invoke(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#2b91af;">MaîtreD</span>.tryAccept&lt;<span style="color:blue;">int</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity,&nbsp;<span style="color:blue;">this</span>.readReservations,&nbsp;<span style="color:blue;">this</span>.createReservation,&nbsp;reservation); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> I've cleaned it up a bit, mostly by removing all attributes from the various elements. Notice how this is a class, with class fields, and a constructor that takes values for the fields and assigns them. <em>It's constructor injection!</em> </p> <p> Partial application is dependency injection. </p> <p> It compiles, works as expected, but is it functional? </p> <p> <strong>Evaluation</strong> </p> <p> People sometimes ask me: <em>How do I know whether my F# code is functional?</em> </p> <p> I sometimes wonder about that myself, but unfortunately, as nice a language as F# is, it doesn't offer much help in that regard. Its emphasis is on functional programming, but it allows mutation, object-oriented programming, and even procedural programming. It's a friendly and forgiving language. (This also makes it a great 'beginner' functional language, because you can learn functional concepts piecemeal.) </p> <p> Haskell, on the other hand, is a strictly functional language. In Haskell, you can only write your code in the functional way. </p> <p> Fortunately, F# and Haskell are similar enough that it's easy to port F# code to Haskell, as long as the F# code already is 'sufficiently functional'. In order to evaluate if my F# code is properly functional, I sometimes port it to Haskell. If I can get it to compile and run in Haskell, I take that as confirmation that my code is functional. </p> <p> I've <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">previously shown an example similar to this one</a>, but I'll repeat the experiment here. Will porting <code>tryAccept</code> and <code>tryAcceptComposition</code> to Haskell work? </p> <p> It's easy to port <code>tryAccept</code>: </p> <p> <pre><span style="color:#600277;">tryAccept</span>&nbsp;::&nbsp;Int&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(<span style="color:blue;">ZonedTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Reservation</span>])&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;Int)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#666666;">-&gt;</span>&nbsp;<span style="color:#dd0000;">Maybe</span>&nbsp;<span style="color:#dd0000;">Int</span> tryAccept&nbsp;capacity&nbsp;readReservations&nbsp;createReservation&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">=</span>&nbsp;sum&nbsp;<span style="color:#666666;">$</span>&nbsp;map&nbsp;quantity&nbsp;<span style="color:#666666;">$</span>&nbsp;readReservations&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;&nbsp;<span style="color:#af00db;">if</span>&nbsp;reservedSeats&nbsp;<span style="color:#666666;">+</span>&nbsp;quantity&nbsp;reservation&nbsp;<span style="color:#666666;">&lt;=</span>&nbsp;capacity &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">then</span>&nbsp;Just&nbsp;<span style="color:#666666;">$</span>&nbsp;createReservation&nbsp;<span style="color:#666666;">$</span>&nbsp;reservation&nbsp;{&nbsp;isAccepted&nbsp;<span style="color:#666666;">=</span>&nbsp;True&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#af00db;">else</span>&nbsp;Nothing</pre> </p> <p> Clearly, there are differences, but I'm sure that you can also see the similarities. The most important feature of this function is that it's <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a>. All Haskell functions are pure by default, unless explicitly declared to be impure, and that's not the case here. This function is pure, and so are both <code>readReservations</code> and <code>createReservation</code>. </p> <p> The Haskell version of <code>tryAccept</code> compiles, but what about <code>tryAcceptComposition</code>? </p> <p> Like the F# code, the experiment is to see if it's possible to 'inject' functions that actually operate against a database. Equivalent to the F# example, imagine that you have this <code>DB</code> module: </p> <p> <pre><span style="color:#600277;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">ConnectionString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ZonedTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;connectionString&nbsp;date&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:green;">--&nbsp;.. </span> <span style="color:#600277;">createReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ConnectionString</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;Int createReservation&nbsp;connectionString&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:green;">--&nbsp;..</span></pre> </p> <p> Database operations are, by definition, impure, and Haskell admirably models that with the type system. Notice how both functions return <code>IO</code> values. </p> <p> If you partially apply both functions with a valid connection string, the <code>IO</code> context remains. The type of <code>DB.readReservations connectionString</code> is <code>ZonedTime -&gt; IO [Reservation]</code>, and the type of <code>DB.createReservation connectionString</code> is <code>Reservation -&gt; IO Int</code>. You can try to pass them to <code>tryAccept</code>, but the types don't match: </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span> &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;read&nbsp;&nbsp;&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;&nbsp;connectionString &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;create&nbsp;<span style="color:#666666;">=</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;tryAccept&nbsp;<span style="color:#09885a;">10</span>&nbsp;read&nbsp;create&nbsp;reservation</pre> </p> <p> <em>This doesn't compile.</em> </p> <p> It doesn't compile, because the database operations are impure, and <code>tryAccept</code> wants pure functions. </p> <p> In short, partial application used for dependency injection isn't functional. </p> <p> <strong>Summary</strong> </p> <p> Partial application in F# can be used to achieve a result equivalent to dependency injection. It compiles and works as expected, but it's not functional. The reason it's not functional is that (most) dependencies are, by their very nature, impure. They're either non-deterministic, have side-effects, or both, and that's often the underlying reason that they are factored into dependencies in the first place. </p> <p> Pure functions, however, can't call impure functions. If they could, they would become impure themselves. This rule is enforced by Haskell, but not by F#. </p> <p> When you inject impure operations into an F# function, that function becomes impure as well. Dependency injection makes everything impure, which explains why it isn't functional. </p> <p> Functional programming solves the problem of decoupling (side) effects from program logic another way. That's the topic of the next article. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">Dependency rejection</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection Dependency injection is passing an argument http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument/ Fri, 27 Jan 2017 09:27:00 UTC <div id="post"> <p> <em>Is dependency injection really just passing an argument? A brief review.</em> </p> <p> This is the first article in a small article series called <a href="http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection">from dependency injection to dependency rejection</a>. </p> <p> In a talk at the 2012 Northeast Scala Symposium, <a href="https://t.co/oD1oQYZwbz">Rúnar Bjarnason casually remarked</a> that dependency injection is "really just a pretentious way to say 'taking an argument'". Given that I've written a 500+ pages <a href="http://amzn.to/12p90MG">book about dependency injection</a>, you might expect me to disagree with that. Yet, there's some truth to that statement, although it's not quite as simple as that. </p> <p> In this article, I'll show you some simple examples and explain why, on the one hand, Rúnar Bjarnason is right, but also, on the other hand, why there's a bit more to it. </p> <p> <strong>Restaurant reservation example</strong> </p> <p> Like the other articles in this series, the example scenario is on-line restaurant reservation. Imagine that you've been asked to develop an HTTP-based API that accepts JSON documents containing restaurant reservations. Furthermore, assume that you're using ASP.NET Web API with C# for the job, and that you're aspiring to use <a href="http://amzn.to/WBCwx7">domain-driven design</a>. </p> <p> In order to handle the incoming POST request, you could write an action method like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpActionResult</span>&nbsp;Post(<span style="color:#2b91af;">ReservationRequestDto</span>&nbsp;dto) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;validationMsg&nbsp;=&nbsp;validator.Validate(dto); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(validationMsg&nbsp;!=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.BadRequest(validationMsg); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;r&nbsp;=&nbsp;mapper.Map(dto); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;id&nbsp;=&nbsp;maîtreD.TryAccept(r); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(id&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.StatusCode(<span style="color:#2b91af;">HttpStatusCode</span>.Forbidden); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">this</span>.Ok(); }</pre> </p> <p> This method follows a simple and familiar path: validate input, map to a domain model, delegate to said model, examine posterior state, and return a result. </p> <p> You may have noticed, though, that this method doesn't do all the work itself. It delegates some of the work to collaborators: <code>validator</code>, <code>mapper</code>, and <code>maîtreD</code>. Where do these collaborators come from? </p> <p> They are <em>dependencies</em>. Could you make the <code>Post</code> method take them as arguments? </p> <p> Unfortunately, you can't. The <code>Post</code> method constitutes part of the boundary of the HTTP API. ASP NET Web API routes and dispatches incoming HTTP requests by convention, and <em>action methods</em> must follow that convention. You can't just make the function take any argument you'd like, so you have to find another place to pass those dependencies to the object. </p> <p> The second-best option (after the <code>Post</code> method itself) is via the constructor: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;ReservationsController( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IValidator</span>&nbsp;validator, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IMapper</span>&nbsp;mapper, &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IMaîtreD</span>&nbsp;maîtreD) {&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.validator&nbsp;=&nbsp;validator; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.mapper&nbsp;=&nbsp;mapper; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.maîtreD&nbsp;=&nbsp;maîtreD; }</pre> </p> <p> This is the application of a design pattern called <em>constructor injection</em>. It captures the dependencies in class fields, making them available for members (like <code>Post</code>) of the class. </p> <p> This turns out to be a regular pattern. </p> <p> <strong>Turtles all the way down</strong> </p> <p> You could argue that the <code>Post</code> method is a special case, since it's part of the boundary of the system, and therefore must adhere to specific rules. On the other hand, these rule don't apply deeper in the implementation, so could you implement other objects by simply passing in dependencies as arguments? </p> <p> Consider, as an example, the implementation of <code>IMaîtreD.TryAccept</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;reservedSeats&nbsp;=&nbsp;reservationsRepository &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.ReadReservations(reservation.Date) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Sum(r&nbsp;=&gt;&nbsp;r.Quantity); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(reservedSeats&nbsp;+&nbsp;reservation.Quantity&nbsp;&lt;=&nbsp;capacity) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservation.IsAccepted&nbsp;=&nbsp;<span style="color:blue;">true</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;reservationsRepository.Create(reservation); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">null</span>; }</pre> </p> <p> This method has another collaborator: <code>reservationsRepository</code>. It's another dependency. Where does it come from? </p> <p> Could you make the <code>TryAccept</code> method take <code>reservationsRepository</code> as an argument? </p> <p> Unfortunately, that's not possible either, because the method is defined by the <code>IMaîtreD</code> interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IMaîtreD</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>?&nbsp;TryAccept(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation); }</pre> </p> <p> You may recall that the above <code>Post</code> method is programmed against the <code>IMaîtreD</code> interface, and not the concrete class. It'd be a leaky abstraction to add <code>IReservationsRepository</code> as an argument to <code>IMaîtreD.TryAccept</code>, because not all implementations of the interface may need that dependency. Or perhaps another implementation has another dependency. Should we add that to the parameter list of <code>IMaîtreD.TryAccept</code>as well? </p> <p> Surely, that's not a tenable design principle. On the other hand, by using constructor injection, you can decouple implementation details from your abstractions: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;MaîtreD(<span style="color:blue;">int</span>&nbsp;capacity,&nbsp;<span style="color:#2b91af;">IReservationsRepository</span>&nbsp;reservationsRepository) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.capacity&nbsp;=&nbsp;capacity; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.reservationsRepository&nbsp;=&nbsp;reservationsRepository; }</pre> </p> <p> This constructor not only takes an <code>IReservationsRepository</code> object, but also an integer that represents the capacity of the restaurant in question. This demonstrates that <a href="http://blog.ploeh.dk/2012/07/02/PrimitiveDependencies">dependencies can also be primitive values</a>. </p> <p> <strong>Summary</strong> </p> <p> Dependency injection is, in a sense, only a specific way for objects to take arguments. Often, however, objects have roles defined by the the interfaces they implement. Such objects may need collaborators that are not available via the APIs defined by these interfaces, so you'll have to supply dependencies via members that belong to the concrete class in question. Passing dependencies via a class' constructor is the best way to do that. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">Partial application is dependency injection</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument From dependency injection to dependency rejection http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection/ Fri, 27 Jan 2017 07:55:00 UTC <div id="post"> <p> <em>The problem typically solved by dependency injection in object-oriented programming is solved in a completely different way in functional programming.</em> </p> <p> Several years ago, I wrote a book called <a href="http://amzn.to/12p90MG">Dependency Injection in .NET</a>, which was published in 2011. The book contains examples in C#, but since then I've increasingly become interested in functional programming to the extend that I now consider F# my primary language. </p> <p> With that combination, it's no wonder that people often ask me how to do dependency injection in functional programming. </p> <p> I've seen more than one answer, from other people, explaining how partial function application is equivalent to dependency injection. In a small series of articles, I'll explain both why this is true, but also why it's <em>not functional</em>. I'll conclude by showing a functional alternative to decoupling logic and (side) effects. </p> <p> <img src="/content/binary/dependency-injection-in-scala-comic.jpg" alt="Bob: How do I do dependency injection in Scala? Other man: You don't, because Scala is a functional language. Bob: Fine, it's functional. How do I inject dependencies? Other man: You use a free monad which allows you to build a monad from any Functor. Bob: Did you just tell me to go fuck myself? Other man: I believe I did, Bob."> </p> <p> (<a href="https://twitter.com/hmemcpy/status/771359835514368000">Comic</a> courtesy of <a href="http://thinkdifferent.ly">John Muellerleile</a> and <a href="http://hmemcpy.com">Igal Tabachnik</a>.) </p> <p> There's another school of functional programmers who believe that dependency injection in functional programming involves a Free monad. </p> <p> You can often make do with less, though. </p> <p> In my experience, it's usually enough to refactor a unit to take only direct input and output, and then compose an impure/pure/impure 'sandwich'. You'll see an example later. </p> <p> This article series contains the following parts: <ol> <li><a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">Dependency injection is passing an argument</a></li> <li><a href="http://blog.ploeh.dk/2017/01/30/partial-application-is-dependency-injection">Partial application is dependency injection</a></li> <li><a href="http://blog.ploeh.dk/2017/02/02/dependency-rejection">Dependency rejection</a></li> </ol> All articles revolve around a common example, which is one of my favourite scenarios: on-line restaurant reservation. You can see an actual example client in my <a href="http://www.shareasale.com/r.cfm?u=1017843&b=611266&m=53701&afftrack=&urllink=pluralsight%2Ecom%2Fcourses%2Ffunctional%2Darchitecture%2Dfsharp">Functional Architecture with F#</a> Pluralsight course. The (somewhat dated) client source code is <a href="https://github.com/ploeh/booking-web-ui">available on GitHub</a>. The server-side F# and Haskell example code for this article series is <a href="https://github.com/ploeh/dependency-rejection-samples">available on GitHub</a>. </p> <p> The scenario is to implement an HTTP-based API that can accept incoming JSON documents that represent restaurant reservations. </p> <p> I should point out that nowhere in this article series do I reject dependency injection as a set of object-oriented patterns. In object-oriented programming, dependency injection is a well-known and comprehensively described way to achieve decoupling and testability. In the next article, you'll see a brief review of dependency injection in C#. </p> <p> <strong>Next:</strong> <a href="http://blog.ploeh.dk/2017/01/27/dependency-injection-is-passing-an-argument">Dependency injection is passing an argument</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2017/01/27/from-dependency-injection-to-dependency-rejection Decoupling application errors from domain models http://blog.ploeh.dk/2017/01/03/decoupling-application-errors-from-domain-models/ Tue, 03 Jan 2017 12:26:00 UTC <div id="post"> <p> <em>How to prevent application-specific error cases from infecting your domain models.</em> </p> <p> Functional error-handling is often done with the Either monad. If all is good, the <em>right</em> case is returned, but if things go wrong, you'll want to return a value that indicates the error. In an application, you'll often need to be able to distinguish between different kinds of errors. </p> <p> <strong>From application errors to HTTP responses</strong> </p> <p> When an application encounters an error, it should respond appropriately. A GUI-based application should inform the user about the error, a batch job should log it, and a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> API should return the appropriate HTTP status code. </p> <p> Regular readers of this blog will know that I write many RESTful APIs in F#, using ASP.NET Web API. Since I like to write functional F#, but ASP.NET Web API is an object-oriented framework, I prefer to escape the object-oriented framework as soon as possible. (In general, it makes good architectural sense to write most of your code as framework-independent as possible.) </p> <p> In my <a href="http://bit.ly/tddwithfsharp">Test-Driven Development with F#</a> Pluralsight course (a <a href="http://www.infoq.com/presentations/mock-fsharp-tdd">free, condensed version is also available</a>), I demonstrate how to handle various error cases in a Controller class: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;dtr&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationError</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">CapacityExceeded</span>&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">StatusCode</span>&nbsp;<span style="color:teal;">HttpStatusCode</span>.Forbidden&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;()&nbsp;:&gt;&nbsp;_</pre> </p> <p> The injected <code>imp</code> function is a complete, composed, vertical feature implementation that performs both input validation, business logic, and data access. If input validation fails, it'll return <code>Failure (ValidationError msg)</code>, and that value is translated to a <code>400 Bad Request</code> response. Likewise, if the business logic returns <code>Failure CapacityExceeded</code>, the response becomes <code>403 Forbidden</code>, and a success is returned as <code>200 OK</code>. </p> <p> Both <code>ValidationError</code> and <code>CapacityExceeded</code> are cases of an <code>Error</code> type. This is only a simple example, so these are the only cases defined by that type: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Error</span>&nbsp;= |&nbsp;<span style="color:navy;">ValidationError</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> |&nbsp;<span style="color:navy;">CapacityExceeded</span></pre> </p> <p> This seems reasonable, but there's a problem. </p> <p> <strong>Error infection</strong> </p> <p> In F#, a function can't use a type unless that type is already defined. This is a problem because the <code>Error</code> type defined above mixes different concerns. If you seek to <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">make illegal states unrepresentable</a>, it follows that validation is not a concern in your domain model. Validation is still important at the boundary of an application, so you can't just ignore it. The <code>ValidationError</code> case relates to the application boundary, while <code>CapacityExceeded</code> relates to the domain model. </p> <p> Still, when implementing your domain model, you may want to return a <code>CapacityExceeded</code> value from time to time: </p> <p> <pre><span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Result&lt;Reservation,Error&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;capacity&nbsp;reservedSeats&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;capacity&nbsp;&lt;&nbsp;reservation.Quantity&nbsp;+&nbsp;reservedSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">CapacityExceeded</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;reservation</pre> </p> <p> Notice how the return type of this function is <code>Result&lt;Reservation,Error&gt;</code>. In order to be able to implement your domain model, you've now pulled in the <code>Error</code> type, which also defines the <code>ValidationError</code> case. Your domain model is now polluted by an application boundary concern. </p> <p> I think many developers would consider this trivial, but in my experience, failure to manage dependencies is the dominant reason for <a href="https://en.wikipedia.org/wiki/Software_rot">code rot</a>. It makes the code less general, and less reusable, because it's now coupled to something that may not fit into a different context. </p> <p> Particularly, the situation in the example looks like this: </p> <p> <img src="/content/binary/error-infection-dependency-diagram.png" alt="Dependency diagram"> </p> <p> Boundary and data access modules depend on the domain model, <a href="http://blog.ploeh.dk/2013/12/03/layers-onions-ports-adapters-its-all-the-same">as they should</a>, but everything depends on the <code>Error</code> type. This is wrong. Modules or libraries should be able to define their own error types. </p> <p> The <code>Error</code> type belongs in the <a href="http://blog.ploeh.dk/2011/07/28/CompositionRoot">Composition Root</a>, but it's impossible to put it there because F# prevents circular dependencies (a <a href="http://blog.ploeh.dk/2015/04/13/less-is-more-language-features">treasured language feature</a>). </p> <p> Fortunately, the fix is straightforward. </p> <p> <strong>Mapped Either values</strong> </p> <p> A domain model should be self-contained. As Robert C. Martin puts it in <a href="http://amzn.to/19W4JHk">APPP</a>: <blockquote> Abstractions should not depend upon details. Details should depend upon abstractions. </blockquote> Your domain model is an abstraction of the real world (that's why it's called a <em>model</em>), and is the reason you're developing a piece of software in the first place. So start with the domain model: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">BookingError</span>&nbsp;=&nbsp;<span style="color:navy;">CapacityExceeded</span> <span style="color:green;">//&nbsp;int&nbsp;-&gt;&nbsp;int&nbsp;-&gt;&nbsp;Reservation&nbsp;-&gt;&nbsp;Result&lt;Reservation,BookingError&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;capacity&nbsp;reservedSeats&nbsp;reservation&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;capacity&nbsp;&lt;&nbsp;reservation.Quantity&nbsp;+&nbsp;reservedSeats &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">CapacityExceeded</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;reservation</pre> </p> <p> In this example, there's only a single type of domain error (<code>CapacityExceeded</code>), but that's mostly because this is an example. Real production code could define a domain error union with several cases. The crux of the matter is that <code>BookingError</code> isn't infected with irrelevant implementation details like validation error types. </p> <p> You're still going to need an exhaustive discriminated union to model all possible error cases for your particular application, but that type belongs in the Composition Root. Accordingly, you also need a way to return validation errors in your validation module. Often, a <code>string</code> is all you need: </p> <p> <pre><span style="color:green;">//&nbsp;ReservationDtr&nbsp;-&gt;&nbsp;Result&lt;Reservation,string&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">validateReservation</span>&nbsp;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;dtr.Date&nbsp;|&gt;&nbsp;<span style="color:teal;">DateTimeOffset</span>.<span style="color:navy;">TryParse</span>&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;(<span style="color:blue;">true</span>,&nbsp;date)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Reservation</span>.Date&nbsp;=&nbsp;date &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;=&nbsp;dtr.Name &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Email&nbsp;=&nbsp;dtr.Email &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Quantity&nbsp;=&nbsp;dtr.Quantity&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date.&quot;</span></pre> </p> <p> The <code>validateReservation</code> function returns a <code>Reservation</code> value when validation succeeds, and a simple <code>string</code> with an error message if it fails. </p> <p> You could, conceivably, return <code>string</code> values for errors from many different places in your code, so you're going to map them into an appropriate error case that makes sense in your application. </p> <p> In this particular example, the Controller shown above should still look like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Error</span>&nbsp;= |&nbsp;<span style="color:navy;">ValidationError</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> |&nbsp;<span style="color:navy;">DomainError</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">ReservationsController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(dtr&nbsp;:&nbsp;<span style="color:teal;">ReservationDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;dtr&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationError</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;<span style="color:navy;">DomainError</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">StatusCode</span>&nbsp;<span style="color:teal;">HttpStatusCode</span>.Forbidden&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;()&nbsp;:&gt;&nbsp;_</pre> </p> <p> Notice how similar this is to the initial example. The important difference, however, is that <code>Error</code> is defined in the same module that also implements <code>ReservationsController</code>. This is part of the composition of the specific application. </p> <p> In order to make that work, you're going to need to map from one failure type to another. This is trivial to do with an extra function belonging to your Result (or Either) module: </p> <p> <pre><span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;c,&#39;a&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;c,&#39;b&gt;</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;x&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">f</span>&nbsp;fail)</pre> </p> <p> This function takes any <code>Result</code> value and maps the failure case instead of the success case. It enables you to transform e.g. a <code>BookingError</code> into a <code>DomainError</code>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;candidate&nbsp;=&nbsp;<span style="color:blue;">either</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;r&nbsp;=&nbsp;<span style="color:navy;">validateReservation</span>&nbsp;candidate&nbsp;|&gt;&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;<span style="color:navy;">ValidationError</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;&nbsp;i&nbsp;=&nbsp;<span style="color:teal;">SqlGateway</span>.<span style="color:navy;">getReservedSeats</span>&nbsp;connectionString&nbsp;r.Date &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;r&nbsp;=&nbsp;<span style="color:navy;">checkCapacity</span>&nbsp;10&nbsp;i&nbsp;r&nbsp;|&gt;&nbsp;<span style="color:navy;">mapFailure</span>&nbsp;(<span style="color:blue;">fun</span>&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">DomainError</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:teal;">SqlGateway</span>.<span style="color:navy;">saveReservation</span>&nbsp;connectionString&nbsp;r&nbsp;}</pre> </p> <p> This composition is a variation of the composition I've <a href="http://blog.ploeh.dk/2016/03/21/composition-with-an-either-computation-expression">previously published</a>. The only difference is that the error cases are now mapped into the application-specific <code>Error</code> type. </p> <p> <strong>Conclusion</strong> </p> <p> Errors can occur in diverse places in your code base: when validating input, when making business decisions, when writing to, or reading from, databases, and so on. </p> <p> When you use the Either monad for error handling, in a strongly typed language like F#, you'll need to define a discriminated union that models all the error cases you care about in the specific application. You can map module-specific error types into such a comprehensive error type using a function like <code>mapFailure</code>. In Haskell, it would be the <code>first</code> function of the <code>Bifunctor</code> typeclass, so this is a well-known function. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/wortho">David Worthington</a></div> <div class="comment-content"> <p> Mark, </p> <p> Why is it a problem to use <code>HttpStatusCode</code> in the domain model. They appear to be a standard way of categorizing errors. </p> </div> <div class="comment-date">2017-02-07 13:37 UTC</div> </div> <div class="comment"> <div class="comment-author"> <a href="http://blog.ploeh.dk">Mark Seemann</a> </div> <div class="comment-content"> </div> <p> David, thank you for writing. The answer depends on your goals and definition of <em>domain model</em>. </p> <p> I usually think of domain models in terms of separation of concerns. The purpose of a domain model is to model the business logic, and as Martin Fowler writes in <a href="http://bit.ly/patternsofeaa">PoEAA</a> about the Domain Model pattern, "you'll want the minimum of coupling from the <em>Domain Model</em> to other layers in the system. You'll notice that a guiding force of many layering patterns is to keep as few dependencies as possible between the domain model and the other parts of the system." </p> <p> In other words, you're separating the concern of implementing the business rules from the concerns of being able to save data in a database, render it on a screen, send emails, and so on. While also important, these are separate concerns, and I want to be able to vary those independently. </p> <p> People often hear statements like that as though I want to reserve myself the right to replace my SQL Server database with Neo4J (more on that later, though!). That's actually not my main goal, but I find that if concerns are mixed, <em>all</em> change becomes harder. It becomes more difficult to change how data is saved in a database, <em>and</em> it becomes harder to change business rules. </p> <p> The Dependency Inversion Principle tries to address such problems by advising that abstractions shouldn't depend on implementation details, but instead, implementation details should depend on abstractions. </p> <p> This is where the goals come in. I find Robert C. Martin's definition of software architecture helpful. Paraphrased from memory, he defines a software architect's role as enabling change; not predicting change, but making sure that when change has to happen, it's as economical as possible. </p> <p> As an architect, one of the heuristics I use is that I try to imagine how easily I can replace one component with another. It's not that I really believe that I may have to replace the SQL Server database with Neo4J, but thinking about how hard it would be gives me some insights about how to structure a software solution. </p> <p> I also imagine what it'd be like to port an application to another environment. Can I port my web site's business rules to a batch job? Can I port my desktop client to a smart phone app? Again, it's not that I necessarily predict that I'll have to do this, but it tells me something about the degrees of freedom offered by the architecture. </p> <p> If not explicitly addressed, the opposite of freedom tends to happen. In <a href="http://amzn.to/19W4JHk">APPP</a>, Robert C. Martin describes a number of design smells, one of them <em>Immobility</em>: "A design is immobile when it contains parts that could be useful in other systems, but the effort and risk involved with separating those parts from the original system are too great. This is an unfortunate, but very common occurrence." </p> <p> Almost as side-effect, an immobile system is difficult to test. A unit test is a different environment than the intended environment. Well-architected systems are easy to unit test. </p> <p> HTTP is a communications protocol. Its purpose is to enable exchange of information over networks. While it does that well, it's specifically concerned with that purpose. This includes HTTP status code. </p> <p> If you use the heuristic of imagining that you'd have to move the heart of your application to a batch job, status codes like <code>301 Moved Permanently</code>, <code>404 Not Found</code>, or <code>405 Method Not Allowed</code> make little sense. </p> <p> Using HTTP status codes in a domain model couples the model to a particular environment, at least conceptually. It has little to do with the <em>ubiquitous language</em> that Eric Evans discusses in <a href="http://amzn.to/WBCwx7">DDD</a>. </p> <div class="comment-date">2017-02-07 17:08 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2017/01/03/decoupling-application-errors-from-domain-models From REST to algebraic data http://blog.ploeh.dk/2016/12/16/from-rest-to-algebraic-data/ Fri, 16 Dec 2016 07:23:00 UTC <div id="post"> <p> <em>Mapping RESTful HTTP requests to values of algebraic data types is easy.</em> </p> <p> In previous articles, you've seen <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">how to easily model a simple domain model with algebraic data types</a>, and <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">how to use RESTful API design to surface such a model at the boundary of an application</a>. In this article, you'll see how trivial it is to map incoming HTTP requests back to values of <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>. </p> <p> The advantage of <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> is that you can make illegal states unrepresentable. Clients follow links, and while clients are supposed to treat links as opaque values, URLs still contain information your API can use. </p> <p> <strong>Routing and dispatching</strong> </p> <p> Continuing where the <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">previous article</a> left off, clients can issue POST requests against a URL like <code>https://example.com/credit-card</code>. On the server, a well-known piece of code handles such requests. (In the example code base I've used so far, I've been using ASP.NET Web API, so the code that handles such a request is a Controller.) Since you know that URLs like that are always routed to that particular piece of code, you can create a new <code>PaymentType</code> value that specifically represents an individual payment with a credit card: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Individual</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Pay&quot;</span>&nbsp;}</pre> </p> <p> If, on the other hand, the client is using a provided link to POST a representation against the URL <code>https://example.com/recurrent/start/credit-card</code>, your server-side dispatcher will route the request to a different handler (Controller), in which case you can create a <code>PaymentType</code> value like this: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Parent</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Pay&quot;</span>&nbsp;}</pre> </p> <p> Finally, if the client has already created a parent payment and is now using the resulting link to create child payments, it may be POSTing to a URL like <code>https://example.com/recurrent/42</code>. Your server-side dispatcher will route that request to a third handler. Most web frameworks, including ASP.NET Web API, will be able to pull values out of URLs. In this case, you can configure it so that it pulls the value <code>42</code> out of the URL and binds it to a value called <code>transactionKey</code>. With this, again it's trivial to create a <code>PaymentType</code> value: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;paymentType&nbsp;=&nbsp;<span style="color:navy;">Child</span>&nbsp;(transactionKey,&nbsp;{&nbsp;Name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;credit-card&quot;</span>;&nbsp;Action&nbsp;=&nbsp;<span style="color:#a31515;">&quot;PayRecurrent&quot;</span>&nbsp;})</pre> </p> <p> Notice that, despite containing different data, and being created three different places in the code base, they all have the same type: <code>PaymentType</code>. This means that you can pass these values to a common <code>pay</code> function, which handles the actual communication with the third-party payment service. </p> <p> <strong>Code reuse</strong> </p> <p> Independent of the route the data arrived at, a central, reusable function named <code>pay</code> handles all such payments. This is still an impure boundary function that takes various other input apart from <code>PaymentType</code>. Without going into too much detail, it has a type like <code>Config -&gt; PaymentType -&gt; Result&lt;PaymentDtr,BoundaryFailure&gt;</code>. Don't worry if some of the details look obscure; the important point is that <code>pay</code> is a function that takes a <code>PaymentType</code> value as input. You can visualise the transition from HTTP requests to a function call like this: </p> <p> <img src="/content/binary/from-http-to-payment-type-values.png" alt="Three different URLs mapped to three different PaymentType values, which are again passed to the single pay function"> </p> <p> The <code>pay</code> function is composed from various smaller functions, some <a href="https://en.wikipedia.org/wiki/Pure_function">pure</a> and some impure. Ultimately, it transforms all the input data to the format required by the third-party payment service, and forwards the transaction information. Inside that function you'll find the pattern match that you saw in <a href="http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest">my previous article</a>. </p> <p> <strong>Summary</strong> </p> <p> By making good use of routing and dispatching, you can easily map incoming HTTP requests to values of algebraic data types. This enables you to close the loop on exposing your domain model at the boundary of your system. Not only can clients request data from your API in terms of your model, but when clients send data to your API, you can translate that data back to your model. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2016/12/16/from-rest-to-algebraic-data Domain modelling with REST http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest/ Wed, 07 Dec 2016 09:15:00 UTC <div id="post"> <p> <em>Make illegal states unrepresentable by using hyperlinks as the engine of application state.</em> </p> <p> Every piece of software, whether it's a web service, smart phone app, batch job, or speech recognition system, interfaces with the world in some way. Sometimes, that interface is a user interface, sometimes it's a machine-readable interface; sometimes it involves rendering pixels on a screen, and sometimes it involves writing to files, selecting records from a database, sending emails, and so on. </p> <p> Programmers often struggle with how to model these interactions. This is particularly difficult because at the boundaries, systems no longer adhere to popular programming paradigms. Previously, I've explained why, <a href="http://blog.ploeh.dk/2011/05/31/AttheBoundaries,ApplicationsareNotObject-Oriented">at the boundaries, applications aren't object-oriented</a>. By the same type of argument, neither are they functional (as in 'functional programming'). </p> <p> If that's the case, why should you even bother with 'domain modelling'? Particularly, does it even matter that, with <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, you can <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">make illegal states unrepresentable</a>? If you need to compromise once you hit the boundary of your application, is it worth the effort? </p> <p> It is, if you structure your application correctly. Proper (<a href="http://martinfowler.com/articles/richardsonMaturityModel.html">level 3</a>) <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> architecture gives you one way to structure applications in such a way that you can surface the constraints of your domain model to the interface layer. When done correctly, you can also make illegal states unrepresentable at the boundary. </p> <p> <strong>A payment example</strong> </p> <p> In my <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">previous article</a>, I demonstrated how to use (static) types to model an on-line payment domain. To summarise, my task was to model three types of payments: <ul> <li>Individual payments, which happen only once.</li> <li>Parent payments, which start a long-term payment relationship.</li> <li>Child payments, which are automated payments originally authorised by an initial parent payment.</li> </ul> The constraint I had to model is that a child payment requires a <em>transaction key</em> that identifies the original parent payment. When making a payment, however, it's only valid to supply a transaction key for a child payment. It'd be invalid to supply a transaction key to a parent or an individual payment. On the other hand, you have to distinguish individual payments from parent payments, because only parent payments can be used to start a long-term payment relationship. All this leads to this table of possible combinations: <table> <thead> <tr> <th></th> <th><code>"StartRecurrent" : "false"</code></th> <th><code>"StartRecurrent" : "true"</code></th> </tr> </thead> <tbody> <tr> <td><code>"OriginalTransactionKey" : null</code></td> <td><em>Individual</em></td> <td><em>Parent</em></td> </tr> <tr> <td><code>"OriginalTransactionKey" : "1234ABCD"</code></td> <td><em>Child</em></td> <td><strong>(Illegal)</strong></td> </tr> </tbody> </table> The table shows that it's illegal to simultaneously provide a transaction key and set <code>StartRecurrent</code> to <code>true</code>. The other three combinations, on the other hand, are valid. </p> <p> As I demonstrated in my <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">previous article</a>, you can easily model this with algebraic data types. </p> <p> At the boundary, however, there are no static types, so how could you model something like that as a web service? </p> <p> <strong>A RESTful solution</strong> </p> <p> A major advantage of REST is that it gives you a way to realise your domain model at the application boundary. It does require, though, that you design the API according to <a href="http://martinfowler.com/articles/richardsonMaturityModel.html">level 3 of the Richardson maturity model</a>. In other words, it's not REST if you're merely tunnelling JSON (or XML) through HTTP. It's still not REST if you publish URL templates and expect clients to fill data into specific place-holders of those URLs. </p> <p> It's REST if the only way a client can interact with your API is by following hyperlinks. </p> <p> If you follow those design principles, however, it's easy to model the above payment domain as a RESTful API. </p> <p> In the following, I will show examples in XML, but it could as well have been JSON. After all, <a href="http://blog.ploeh.dk/2015/06/22/rest-implies-content-negotiation">a true REST API <em>must</em> support content negotiation</a>. One of the reasons that I prefer XML is that I can use <a href="https://en.wikipedia.org/wiki/XPath">XPath</a> to point out various nodes. </p> <p> A client must begin at a pre-published 'home' resource, just like the home page of a web site. This resource presents <a href="https://en.wikipedia.org/wiki/Affordance">affordances</a> in the shape of hyperlinks. As recommended by the <a href="http://amzn.to/YFnkRg">RESTful Web Services Cookbook</a>, I always use <a href="https://en.wikipedia.org/wiki/Atom_(standard)">ATOM</a> links: </p> <p> <pre><span style="color:blue;">&lt;</span><span style="color:#a31515;">home</span><span style="color:blue;">&nbsp;</span><span style="color:red;">xmlns</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://example.com/payment</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">xmlns:atom</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://www.w3.org/2005/Atom</span>&quot;<span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-methods</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-individual</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/gift-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span>gift-card<span style="color:blue;">&lt;/</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-individual</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/credit-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-parent</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/recurrent/start/credit-card</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span>credit-card<span style="color:blue;">&lt;/</span><span style="color:#a31515;">id</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-method</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">payment-methods</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&lt;/</span><span style="color:#a31515;">home</span><span style="color:blue;">&gt;</span> </pre> </p> <p> A client receiving the above response is effectively presented with a choice. It can choose to pay with a gift card or credit card, and nothing else, however much it'd like to pay with, say, PayPal. For each of these payment methods, zero or more links are available. </p> <p> Specifically, there are links to create both an individual or a parent payment with a credit card, but it's only possible to make an individual payment with a gift card. You can't set up a long-term, automated payment relationship with a gift card. (This may or may not make sense, depending on how you look at it, but it's fundamentally a business decision.) </p> <p> Links are defined by <em>relationship types</em>, which are unique identifiers present in the <code>rel</code> attributes. You can think of them as equivalent to the human-readable text in an HTML <code>a</code> tag that suggests to a human user what to expect from clicking the link; only, <code>rel</code> attribute values are machine-readable and part of the contract between client and service. </p> <p> Notice how the above XML representation only gives a client the option of making an individual or a parent payment with a credit card. A client can't make a child payment at this point. This follows the domain model, because you can't make a child payment without first having made a parent payment. </p> <p> <strong>RESTful individual payments</strong> </p> <p> If a client wishes to make an individual payment, it follows the link identified by </p> <p> <pre>/home/payment-methods/payment-method[id = 'credit-card']/links/atom:link[@rel = 'example:pay-individual']/@href</pre> </p> <p> In the above XPath query, I've ignored the default document namespace in order to make the expression more readable. The query returns <code>https://example.com/credit-card</code>, and the client can now make an HTTP POST request against that URL with a JSON or XML document containing details about the payment (not shown here, because it's not important for this particular discussion). </p> <p> <strong>RESTful parent payments</strong> </p> <p> If a client wishes to make a parent payment, the initial procedure is the same. First, it follows the link identified by </p> <p> <pre>/home/payment-methods/payment-method[id = 'credit-card']/links/atom:link[@rel = 'example:pay-parent']/@href</pre> </p> <p> The result of that XPath query is <code>https://example.com/recurrent/start/credit-card</code>, so the client can make an HTTP POST request against that URL with the payment details. Unlike the response for an individual payment, the response for a parent payment contains <em>another</em> link: </p> <p> <pre><span style="color:blue;">&lt;</span><span style="color:#a31515;">payment</span><span style="color:blue;">&nbsp;</span><span style="color:red;">xmlns</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://example.com/payment</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">xmlns:atom</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">http://www.w3.org/2005/Atom</span>&quot;<span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:pay-child</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/recurrent/42</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">atom:link</span><span style="color:blue;">&nbsp;</span><span style="color:red;">rel</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">example:payment-details</span>&quot; <span style="color:blue;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color:red;">href</span><span style="color:blue;">=</span>&quot;<span style="color:blue;">https://example.com/42</span>&quot;<span style="color:blue;">&nbsp;/&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;/</span><span style="color:#a31515;">links</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">amount</span><span style="color:blue;">&gt;</span>13.37<span style="color:blue;">&lt;/</span><span style="color:#a31515;">amount</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">currency</span><span style="color:blue;">&gt;</span>EUR<span style="color:blue;">&lt;/</span><span style="color:#a31515;">currency</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&nbsp;&nbsp;&lt;</span><span style="color:#a31515;">invoice</span><span style="color:blue;">&gt;</span>1234567890<span style="color:blue;">&lt;/</span><span style="color:#a31515;">invoice</span><span style="color:blue;">&gt;</span> <span style="color:blue;">&lt;/</span><span style="color:#a31515;">payment</span><span style="color:blue;">&gt;</span></pre> </p> <p> This response echoes the details of the payment: this is a payment of 13.37 EUR for invoice 1234567890. It also includes some links that a client can use to further interact with the payment: <ul> <li>The <code>example:payment-details</code> link can be used to query the API for details about the payment, for example its status.</li> <li>The <code>example:pay-child</code> link can be used to make a child payment.</li> </ul> The <code>example:pay-child</code> link is only returned if the previous payment was a parent payment. When a client makes an individual payment, this link isn't present in the response, but when the client makes a parent payment, it is. </p> <p> Another design principle of REST is that <a href="https://www.w3.org/Provider/Style/URI.html.en">cool URIs don't change</a>; once the API has shown a URL like <code>https://example.com/recurrent/42</code> to a client, it should honour that URL indefinitely. The upshot of that is that a client can <em>save</em> that URL for later use. If a client wants to, say, renew a subscription, it can make a new HTTP POST request to that URL <em>a month later</em>, and that's going to be a child payment. Clients don't have to <a href="http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls">hack the URL</a> in order to figure out what the transaction key is; they can simply store the complete URL as is and use it later. </p> <p> <strong>A network of options</strong> </p> <p> Using a design like the one sketched above, you can make illegal states unrepresentative. There's no way for a client to make a payment with <code>StartRecurrent = true</code> and a non-null transaction key; there's no link to that combination. Such an API uses <a href="https://en.wikipedia.org/wiki/HATEOAS">hypermedia as the engine of application state</a>. </p> <p> It shouldn't be surprising that proper RESTful design works that way. After all, REST is essentially a distillate of the properties that make the World Wide Web work. On a human-readable web page, the user follows links to other pages, and a well-designed web site will only enable a link if the destination exists. </p> <p> You can even draw a graph of the the API I've sketched above: </p> <p> <img src="/content/binary/graph-of-payment-paths.png" alt="Graph of payment options, including a start node, and end node, and a node for each of the three payment types"> </p> <p> In this diagram, you can see that when you make an individual payment, that's all you can do. You can also see that the only way to make a child payment is by first making a parent payment. There's also a path from parent payments directly to the end node, because a client doesn't <em>have</em> to make a child payment just because it made a parent payment. </p> <p> If you think that this looks like a finite state machine, then that's no coincidence. That's exactly what it is. You have states (the nodes) and paths between them. If a state is illegal, then don't add that node; only add nodes for legal states, then add links between the nodes that model legal transitions. </p> <p> Incidentally, languages like F# excel at implementing finite state machines, so it's no wonder I like to implement RESTful APIs in F#. </p> <p> <strong>Summary</strong> </p> <p> Truly RESTful design enables you to make illegal states unrepresentable by using hypermedia as the engine of application state. This gives you a powerful design tool to ensure that clients can only perform correct operations. </p> <p> As I also wrote in <a href="http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types">my previous article</a>, this, too, is no silver bullet. You can turn an API into a pit of success, but there are still many fault scenarios that you can't prevent. </p> <p> If you were intrigued by this article, but are having trouble applying these design techniques to your own field, I'm <a href="http://blog.ploeh.dk/hire-me">available for hire</a> for short or long-term engagements. </p> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2016/12/07/domain-modelling-with-rest Easy domain modelling with types http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types/ Mon, 28 Nov 2016 07:21:00 UTC <div id="post"> <p> <em>Algebraic data types make domain modelling easy.</em> </p> <p> People often ask me if I think that F# is a good general-purpose language, and when I emphatically answer <em>yes!</em>, the natural next question is: <em>why?</em> </p> <p> For years, I've been able to answer this question in the abstract, but I've been looking for a good concrete example with which I could illustrate the answer. I believe that I've now found such an example. </p> <p> The abstract answer, by the way, is that F# has <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, which makes domain modelling much easier than in languages that don't have such types. Don't worry if the word 'algebraic' sounds scary, though. It's not at all difficult to understand, and I'll show you a simple example. </p> <p> <strong>Payment types</strong> </p> <p> At the moment, I'm working on an integration project: I'm developing a RESTful API that serves as Facade in front of a third-party payment provider. The third-party provider exposes their own API and web-based GUI that enable our end users to pay for services using credit cards, PayPal, and so on. The API that I'm developing presents a simplified, RESTful API to other clients in our organisation. </p> <p> The example you're going to see here is real code that I'm writing in order to implement the desired functionality. </p> <p> The system must be able to handle several different types of payment: <ul> <li>Sometimes, a user pays for a single thing, and that's the end of that transaction.</li> <li>Other times, however, a user engages into a long-term payment relationship. This could be, for example, a subscription, or an 'auto-fill' style of relationship. This is handled in two distinct phases:</li> <ul> <li>An initial payment (can sometimes be for a zero amount) that authorises the merchant to make further transactions.</li> <li>Subsequent payments, based off that initial payment. These payments can be automated, because they require no further user interaction than the initial authorisation.</li> </ul> </ul> The third-party service calls these 'long-term relationship' payments for <em>recurring</em> payments, but in order to distinguish between the first and the subsequent payments in such a relationship, I decided to call them <em>parent</em> and <em>child</em> payments; accordingly, I call the one-off payments <em>individual</em> payments. </p> <p> You can indicate the type of payment when interacting with the payment service's JSON-based API, like this: </p> <p> <pre>{ &nbsp;&nbsp;... &nbsp;&nbsp;"StartRecurrent": "false" &nbsp;&nbsp;... }</pre> </p> <p> Obviously, as the (illegal) ellipses suggests, there's much more data associated with a payment, but that's not important in this example. Since <code>StartRecurrent</code> is <code>false</code>, this is either an individual payment, or a child payment. If you want to start a long-term relationship, you must create a parent payment and set <code>StartRecurrent</code> to <code>true</code>. </p> <p> Child payments, however, are a bit different, because you have to tell the payment service about the parent payment: </p> <p><pre>{ &nbsp;&nbsp;... &nbsp;&nbsp;"OriginalTransactionKey": "1234ABCD", &nbsp;&nbsp;"StartRecurrent": "false" &nbsp;&nbsp;... }</pre> </p> <p> As you can see, when making a child payment, you supply the transaction ID for the parent payment. (This ID is given to you by the payment service when you initiate the parent payment.) </p> <p> In this case, you're clearly <em>not</em> starting a <em>new</em> recurrent transaction. </p> <p> There are two dimensions of variation in this example: <code>StartRecurrent</code> and <code>OriginalTransactionKey</code>. Let's put them in a table: <table> <thead> <tr> <th></th> <th><code>"StartRecurrent" : "false"</code></th> <th><code>"StartRecurrent" : "true"</code></th> </tr> </thead> <tbody> <tr> <td><code>"OriginalTransactionKey" : null</code></td> <td><em>Individual</em></td> <td><em>Parent</em></td> </tr> <tr> <td><code>"OriginalTransactionKey" : "1234ABCD"</code></td> <td><em>Child</em></td> <td><strong>(Illegal)</strong></td> </tr> </tbody> </table> As the table suggests, the combination of an <code>OriginalTransactionKey</code> and setting <code>StartRecurrent</code> to <code>true</code> is illegal, or, in best case, meaningless. </p> <p> How would you model the rules laid out in the above table? In languages like C#, it's difficult, but in F# it's easy. </p> <p> <strong>C# attempts</strong> </p> <p> Most C# developers would, I think, attempt to model a payment transaction with a class. If they aim for <a href="http://blog.ploeh.dk/2011/05/24/Poka-yokeDesignFromSmelltoFragrance">poka-yoke design</a>, they might come up with a design like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">PaymentType</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;PaymentType(<span style="color:blue;">bool</span>&nbsp;startRecurrent) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.StartRecurrent&nbsp;=&nbsp;startRecurrent; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;PaymentType(<span style="color:blue;">string</span>&nbsp;originalTransactionKey) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(originalTransactionKey&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(originalTransactionKey)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.StartRecurrent&nbsp;=&nbsp;<span style="color:blue;">false</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.OriginalTransactionKey&nbsp;=&nbsp;originalTransactionKey; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">bool</span>&nbsp;StartRecurrent&nbsp;{&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">string</span>&nbsp;OriginalTransactionKey&nbsp;{&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&nbsp;<span style="color:blue;">get</span>;&nbsp;} }</pre> </p> <p> This goes a fair way towards <a href="http://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable">making illegal states unrepresentable</a>, but it doesn't communicate to a fellow programmer how it should be used. </p> <p> Code that <em>uses</em> instances of this <code>PaymentType</code> class could attempt to read the <code>OriginalTransactionKey</code>, which, depending on the type of payment, could return null. That sort of design leads to <a href="http://blog.ploeh.dk/2013/07/08/defensive-coding">defensive coding</a>. </p> <p> Other people might attempt to solve the problem by designing a class hierarchy: </p> <p> <img src="/content/binary/hypothetical-payment-class-hierarchy.png" alt="A hypothetical payment class hierarchy, showing a Payment base class, and three derived classes: IndividualPayment, ParentPayment, and ChildPayment."> </p> <p> (A variation on this design is to define an <code>IPayment</code> interface, and three concrete classes that implement that interface.) </p> <p> This design trades better protection of invariants for violations of the <a href="https://en.wikipedia.org/wiki/Liskov_substitution_principle">Liskov Substitution Principle</a>. Clients will have to (attempt to) downcast to subtypes in order to access all relevant data (particularly <code>OriginalTransactionKey</code>). </p> <p> For completeness sake, I can think of at least one other option with significantly different trade-offs: applying the <a href="https://en.wikipedia.org/wiki/Visitor_pattern">Visitor design pattern</a>. This is, however, quite a complex solution, and most people will find the disadvantages greater than the benefits. </p> <p> Is it such a big deal, then? After all, it's only a single data value (<code>OriginalTransactionKey</code>) that may or may not be there. Surely, most programmers will be able to deal with that. </p> <p> This may be true in this isolated case, but keep in mind that this is only a motivating <em>example</em>. In many other situations, the domain you're trying to model is much more intricate, with many more exceptions to general rules. The more dimensions you add, the more difficult it becomes to reason about the code. </p> <p> <strong>F# model</strong> </p> <p> F#, on the other hand, makes dealing with such problems so simple that it's almost anticlimactic. The reason is that F#'s type system enables you to model <em>alternatives</em> of data, in addition to the combinations of data that C# (or Java) enables. Such alternatives are called <a href="https://docs.microsoft.com/en-us/dotnet/articles/fsharp/language-reference/discriminated-unions">discriminated unions</a>. </p> <p> In the code base I'm currently developing, I model the various payment types like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentService</span>&nbsp;=&nbsp;{&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span>;&nbsp;Action&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;} <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentType</span>&nbsp;= |&nbsp;<span style="color:navy;">Individual</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">Parent</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">Child</span>&nbsp;<span style="color:blue;">of</span>&nbsp;originalTransactionKey&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;*&nbsp;paymentService&nbsp;:&nbsp;<span style="color:teal;">PaymentService</span></pre> </p> <p> Here, <code>PaymentService</code> is a record type with some data about the payment (e.g. which credit card to use). </p> <p> Even if you're not used to reading F# code, you can see three alternatives outlined on each of the three lines of code that start with a vertical bar (<code>|</code>). The <code>PaymentType</code> type has <em>exactly</em> three 'subtypes' (they're called <em>cases</em>, though). The illegal state of a non-null <code>OriginalTransactionKey</code> combined with <code>StartRecurrent</code> value of <code>true</code> is not possible. It can't be compiled. </p> <p> Not only that, but all clients given a <code>PaymentType</code> value <em>must</em> deal with all three cases (or the compiler will issue a warning). Here's one example where our code is creating the JSON document to send to the payment service: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;name,&nbsp;action,&nbsp;startRecurrent,&nbsp;transaction&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;req.PaymentType&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;}&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;}&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">true</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Child</span>&nbsp;(transactionKey,&nbsp;{&nbsp;Name&nbsp;=&nbsp;name;&nbsp;Action&nbsp;=&nbsp;action&nbsp;})&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name,&nbsp;action,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">Some</span>&nbsp;transactionKey</pre> </p> <p> This code example also extracts <code>name</code> and <code>action</code> from the <code>PaymentType</code> value, but the relevant values to be aware of are <code>startRecurrent</code> and <code>transaction</code>. <ul> <li>For an individual payment, <code>startRecurrent</code> becomes <code>false</code> and <code>transaction</code> becomes <code>None</code> (meaning that the value is missing).</li> <li>For a parent payment, <code>startRecurrent</code> becomes <code>true</code> and <code>transaction</code> becomes <code>None</code>.</li> <li>For a child payment, <code>startRecurrent</code> becomes <code>false</code> and <code>transaction</code> becomes <code>Some transactionKey</code>.</li> </ul> Notice that the (parent) <code>transactionKey</code> is only available when the payment is a child payment. </p> <p> The values <code>startRecurrent</code> and <code>transaction </code> (as well as <code>name</code> and <code>action</code>) are then used to create a JSON document. I'm not showing that part of the code here, since there's actually a lot going on in the real code base, and it's not related to how to model the domain. Imagine that these values are passed to a constructor. </p> <p> This is a real-world example that, I hope, demonstrates why I prefer F# over C# for domain modelling. The type system enables me to model alternatives as well as combinations of data, and thereby <em>making illegal states unrepresentable</em> - all in only a few lines of code. </p> <p> <strong>Summary</strong> </p> <p> Classes, in languages like C# and Java, enable you to model <em>combinations</em> of data. The more fields or properties you add to a class, the more combinations are possible. This is often useful, but sometimes you need to be able to model <em>alternatives</em>, rather than combinations. </p> <p> Some languages, like F#, Haskell, OCaml, Elm, Kotlin, and many others, have type systems that give you the power to model both combinations and alternatives. Such types systems are said to have <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, but while the word sounds 'mathy', such types make it much easier to model complex domains. </p> <p> There are more reasons to love F# than only its algebraic data types, but this is the foremost reason I find it a better language for mainstream development work than C#. </p> <p> If you want to see a more complex example of modelling with types, a good next step would be <a href="http://blog.ploeh.dk/2016/02/10/types-properties-software-designing-with-types">the first article</a> in my <a href="http://blog.ploeh.dk/2016/02/10/types-properties-software">Types + Properties = Software</a> article series. </p> <p> Finally, I should be careful that I don't oversell the idea of making illegal states unrepresentable. Algebraic data types give you an extra dimension in which you can model domains, but there are still rules that they can't enforce. As an example, you can't state that integers must only fall in a certain range (e.g. only positive integers allowed). There are other type systems, such as <a href="https://en.wikipedia.org/wiki/Dependent_type">dependent types</a>, that give you even more power to embed domain rules into types, but as far as I know, there are no type systems that can fully model all rules as types. You'll still have to write some code as well. </p> <p> The article is an instalment in the <a href="https://sergeytihon.wordpress.com/2016/10/23/f-advent-calendar-in-english-2016">2016 F# Advent calendar</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://lambdaklub.wordpress.com">Botond Balázs</a></div> <div class="comment-content"> <p>Mark,</p> <p>I must be missing something important but it seems to me that the only advantage of using F# in this case is that the match is enforced to be exhaustive by the compiler. And of course the syntax is also nicer than a bunch of if's. In all other respects, the solution is basically equivalent to the C# class hierarchy approach.</p> <p>Am I mistaken?</p> </div> <div class="comment-date">2016-12-03 08:38 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Botond, thank you for writing. The major advantage is that enumeration of all possible cases is available at compile-time. One derived advantage of that is that the compiler can check whether a piece of code handles all cases. That's already, in my experience, a big deal. The sooner you can get feedback on your work, the better, and <a href="http://blog.ploeh.dk/2011/04/29/Feedbackmechanismsandtradeoffs">it doesn't get faster than compile-time feedback</a>. </p> <p> Another advantage of having all cases encoded in the type system is that it gives you better tool support. Imagine that you're looking at the return value of a function, and that this is the first time you're encountering that return type. If the return value is an abstract base class (or interface), you'll need to resort to either the documentation or reflection in order to figure out which subtypes exist. There can be arbitrarily many subtypes, and they can be scattered over arbitrarily many libraries (assemblies). Figuring out what to do with an abstract base class introduces a context switch that could have been avoided. </p> <p> This is exactly another advantage offered by discriminated unions: when a function returns a discriminated union, you can immediately get tool support to figure out what to do with it, even if you've never encountered the type before. </p> <p> The problem with examples such as the above is that I'm trying to explain how a language feature can help you with modelling <em>complex</em> domains, but if I try to present a really complex problem, no-one will have the patience to read the article. Instead, I have to come up with an example that's so simple that the reader doesn't give up, and hopefully still complex enough that the reader can imagine how it's a stand-in for a more complex problem. </p> <p> When you look at the problem presented above, it's not <em>that</em> complex, so you can still keep a C# implementation in your head. As you add more variability to the problem, however, you can easily find yourself in a situation where the combinatorial explosion of possible values make it difficult to ensure that you've dealt with all edge cases. This is one of the main reasons that C# and Java code often throws run-time exceptions (particularly null-reference exceptions). </p> <p> It did, in fact, turn out that the above example domain became more complex as I learned more about the entire range of problems I had to solve. When I described the problem above, I thought that all payments would have pre-selected payment methods. In other words, when a user is presented with a check-out page, he or she selects the payment method (PayPal, direct debit, and so on), and only then, when we know payment method, do we initiate the payment flow. It turns out, though, that in some cases, we should start the payment flow first, and then let the user pick the payment method from a list of options. It should be noted, however, that user-selection only makes sense for interactive payments, so a <em>child</em> payment can never be user-selectable (since it's automated). </p> <p> It was trivial to extend the domain model with that new requirement: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentService</span>&nbsp;=&nbsp;{&nbsp;Name&nbsp;:&nbsp;<span style="color:teal;">string</span>;&nbsp;Action&nbsp;:&nbsp;<span style="color:teal;">string</span>&nbsp;} <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentMethod</span>&nbsp;= |&nbsp;<span style="color:navy;">PreSelected</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentService</span> |&nbsp;<span style="color:navy;">UserSelectable</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;<span style="color:teal;">list</span> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">TransactionKey</span>&nbsp;=&nbsp;<span style="color:navy;">TransactionKey</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">override</span>&nbsp;this.<span style="color:navy;">ToString</span>&nbsp;()&nbsp;=&nbsp;<span style="color:blue;">match</span>&nbsp;this&nbsp;<span style="color:blue;">with</span>&nbsp;<span style="color:navy;">TransactionKey</span>&nbsp;s&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;s <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PaymentType</span>&nbsp;= |&nbsp;<span style="color:navy;">Individual</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentMethod</span> |&nbsp;<span style="color:navy;">Parent</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">PaymentMethod</span> |&nbsp;<span style="color:navy;">Child</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">TransactionKey</span>&nbsp;*&nbsp;<span style="color:teal;">PaymentService</span></pre> </p> <p> This effectively uses the static type system to state that both the <code>Individual</code> and <code>Parent</code> cases can be defined in one of two ways: <code>PreSelected</code> or <code>UserSelectable</code>, each of which, again, contains heterogeneous data (<code>PaymentService</code> versus <code>string list</code>). Child payments, on the other hand, can't be user-selectable, but must be defined by a <code>PaymentService</code> value, as well as a transaction key (at this point, I'd also created a single-case union for the transaction key, but that's a different topic; it's still a string). </p> <p> Handling all the different combinations was equally easy, and the compiler guarantees that I've handled all possible combinations: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;services,&nbsp;selectables,&nbsp;startRecurrent,&nbsp;transaction&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;req.PaymentType&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;(<span style="color:navy;">PreSelected</span>&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Individual</span>&nbsp;(<span style="color:navy;">UserSelectable</span>&nbsp;us)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[||],&nbsp;us&nbsp;|&gt;&nbsp;<span style="color:teal;">String</span>.<span style="color:navy;">concat</span>&nbsp;<span style="color:#a31515;">&quot;,&nbsp;&quot;</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;(<span style="color:navy;">PreSelected</span>&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">true</span>,&nbsp;&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Parent</span>&nbsp;(<span style="color:navy;">UserSelectable</span>&nbsp;us)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[||],&nbsp;us&nbsp;|&gt;&nbsp;<span style="color:teal;">String</span>.<span style="color:navy;">concat</span>&nbsp;<span style="color:#a31515;">&quot;,&nbsp;&quot;</span>&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span>,&nbsp;<span style="color:blue;">true</span>,&nbsp;&nbsp;<span style="color:navy;">None</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Child</span>&nbsp;(<span style="color:navy;">TransactionKey</span>&nbsp;transactionKey,&nbsp;ps)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">service</span>&nbsp;ps,&nbsp;<span style="color:navy;">None</span>,&nbsp;<span style="color:blue;">false</span>,&nbsp;<span style="color:navy;">Some</span>&nbsp;transactionKey</pre> </p> <p> How would you handle this with a class hierarchy, and what would the consuming code look like? </p> </div> <div class="comment-date">2016-12-06 10:50 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2016/11/28/easy-domain-modelling-with-types When variable names are in the way http://blog.ploeh.dk/2016/10/25/when-variable-names-are-in-the-way/ Tue, 25 Oct 2016 06:20:00 UTC <div id="post"> <p> <em>While Clean Code recommends using good variable names to communicate the intent of code, sometimes, variable names can be in the way.</em> </p> <p> Good guides to more readable code, like <a href="http://amzn.to/XCJi9X">Clean Code</a>, explain how explicitly introducing variables with descriptive names can make the code easier to understand. There's much literature on the subject, so I'm not going to reiterate it here. It's not the topic of this article. </p> <p> In the majority of cases, introducing a well-named variable will make the code more readable. There are, however, no rules without exceptions. After all, <a href="http://martinfowler.com/bliki/TwoHardThings.html">one of the hardest tasks in programming is naming things</a>. In this article, I'll show you an example of such an exception. While the example is slightly elaborate, it's a <em>real-world</em> example I recently ran into. </p> <p> <strong>Escaping object-orientation</strong> </p> <p> Regular readers of this blog will know that I write many <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful APIs</a> in F#, but using ASP.NET Web API. Since I like to write functional F#, but ASP.NET Web API is an object-oriented framework, I prefer to escape the object-oriented framework as soon as possible. (In general, it makes good architectural sense to write most of your code as framework-independent as possible.) </p> <p> ASP.NET Web API expects you handle HTTP requests using <em>Controllers</em>, so I use Constructor Injection to inject a function that will do all the actual work, and delegate each request to a function call. It often looks like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(<span style="color:#9b9b9b;">portalId</span>&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">PushRequestDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> This particular Controller only handles HTTP POST requests, and it does it by delegating to the injected <code>imp</code> function and translating the return value of that function call to various HTTP responses. This enables me to compose <code>imp</code> from F# functions, and thereby escape the object-oriented design of ASP.NET Web API. In other words, each Controller is an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> over a functional implementation. </p> <p> For good measure, though, this Controller implementation ought to be unit tested. </p> <p> <strong>A naive unit test attempt</strong> </p> <p> Each HTTP request is handled at the boundary of the system, and <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">the boundary of the system is always impure</a> - even in Haskell. This is particularly clear in the case of the above <code>PushController</code>, because it handles <code>Success ()</code>. In success cases, the result is <code>()</code> (<code>unit</code>), which strongly implies a side effect. Thus, a unit test ought to care not only about what <code>imp</code> returns, but also the input to the function. </p> <p> While you could write a unit test like the following, it'd be naive. </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;_&nbsp;=&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> This unit test uses <a href="https://fscheck.github.io/FsCheck">FsCheck</a>'s integration for <a href="https://xunit.github.io">xUnit.net</a>, and <a href="http://www.swensensoftware.com/unquote">Unquote</a> for assertions. Additionally, it uses a <code>convertsTo</code> function that I've <a href="http://blog.ploeh.dk/2014/03/21/composed-assertions-with-unquote">previously described</a>. </p> <p> The <code>imp</code> function for <code>PushController</code> must have the type <code>PushRequestDtr -&gt; Result&lt;unit, BoundaryFailure&gt;</code>. In the unit test, it uses a wild-card (<code>_</code>) for the input value, so its type is <code>'a -&gt; Result&lt;'b, BoundaryFailure&gt;</code>. That's a wider type, but it matches the required type, so the test compiles (and passes). </p> <p> FsCheck populates the <code>req</code> argument to the test function itself. This value is passed to <code>sut.Post</code>. If you look at the definition of <code>sut.Post</code>, you may wonder what happened to the individual (and currently unused) <code>portalId</code> argument. The explanation is that the <code>Post</code> method can be viewed as a method with two parameters, but it can also be viewed as an impure function that takes a <em>single</em> argument of the type <code>string * PushRequestDtr</code> - a tuple. In other words, the test function's <code>req</code> argument is a tuple. The test is not only concise, but also robust against refactorings. If you change the signature of the <code>Post</code> method, odds are that the test will still compile. (This is one of the many benefits of type inference.) </p> <p> The problem with the test is that it doesn't verify the data flow into <code>imp</code>, so this version of <code>PushController</code> <em>also</em> passes the test: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(<span style="color:#9b9b9b;">portalId</span>&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;<span style="color:#9b9b9b;">req</span>&nbsp;:&nbsp;<span style="color:teal;">PushRequestDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;minimalReq&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;Transaction&nbsp;=&nbsp;{&nbsp;Invoice&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>;&nbsp;Status&nbsp;=&nbsp;{&nbsp;Code&nbsp;=&nbsp;{&nbsp;Code&nbsp;=&nbsp;0&nbsp;}&nbsp;}&nbsp;}&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;minimalReq&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;()&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> As the name implies, the <code>minimalReq</code> value is the 'smallest' value I can create of the <code>PushRequestDtr</code> type. As you can see, this implementation ignores the <code>req</code> method argument and instead passes <code>minimalReq</code> to <code>imp</code>. This is clearly wrong, but it passes the unit test test. </p> <p> <strong>Data flow testing</strong> </p> <p> Not only should you care about the output of <code>imp</code>, but you should also care about the input. This is because <code>imp</code> is inherently impure, so it'd be conceivable that the input values matter in some way. </p> <p> As <a href="http://bit.ly/xunitpatterns">xUnit Test Patterns</a> explains, automated tests should contain no branching, so I don't think it's a good idea to define a test-specific <code>imp</code> function using conditionals. Instead, we can use guard assertions to verify that the input is as expected: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;<span style="color:navy;">snd</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> The <code>imp</code> function is now implemented using Unquote's custom <code>=!</code> operator, which means that <code>candidate</code> must equal <code>req</code>. If not, Unquote will throw an exception, and thereby fail the test. </p> <p> If <code>candidate</code> is equal to <code>snd req</code>, the <code>=!</code> operator does nothing, enabling the <code>imp</code> function to return the value <code>Result.fail (ValidationFailure msg)</code>. </p> <p> This version of the test verifies the entire data flow through <code>imp</code>: both input and output. </p> <p> There is, however, a small disadvantage to writing the <code>imp</code> code this way. It isn't a big issue, but it annoys me. </p> <p> Here's the heart of the matter: I had to come up with a name for the local <code>PushRequestDtr</code> value that the <code>=!</code> operator evaluates against <code>snd req</code>. I chose to call it <code>candidate</code>, which may seem reasonable, but that naming strategy doesn't scale. </p> <p> In order to keep the introductory example simple, I chose a Controller method that doesn't (yet) use its <code>portalId</code> argument, but the code base contains other Controllers, for example this one: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">IdealController</span>&nbsp;(<span style="color:navy;">imp</span>)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">inherit</span>&nbsp;<span style="color:teal;">ApiController</span>&nbsp;() &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">member</span>&nbsp;this.<span style="color:navy;">Post</span>&nbsp;(portalId&nbsp;:&nbsp;<span style="color:teal;">string</span>,&nbsp;req&nbsp;:&nbsp;<span style="color:teal;">IDealRequestDtr</span>)&nbsp;:&nbsp;<span style="color:teal;">IHttpActionResult</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">match</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;portalId&nbsp;req&nbsp;<span style="color:blue;">with</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;(resp&nbsp;:&nbsp;<span style="color:teal;">IDealResponseDtr</span>)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">Ok</span>&nbsp;resp&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;this.<span style="color:navy;">BadRequest</span>&nbsp;msg&nbsp;:&gt;&nbsp;_ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;(<span style="color:navy;">IntegrationFailure</span>&nbsp;msg)&nbsp;<span style="color:blue;">-&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;this.<span style="color:navy;">InternalServerError</span>&nbsp;(<span style="color:teal;">InvalidOperationException</span>&nbsp;msg)&nbsp;:&gt;&nbsp;_</pre> </p> <p> This Controller's <code>Post</code> method passes <em>both</em> <code>portalId</code> and <code>req</code> to <code>imp</code>. In order to perform data flow verification of that implementation, the test has to look like this: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;success``</span>&nbsp;portalId&nbsp;req&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;pid&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pid&nbsp;=!&nbsp;portalId &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">IdealController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;(portalId,&nbsp;req) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">OkNegotiatedContentResult</span><span style="background:yellow;">&lt;</span><span style="color:teal;background:yellow;">IDealResponseDtr</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;"></span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Content</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">resp</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> This is where I began to run out of good argument names. You need names for the <code>portalId</code> and <code>req</code> arguments of <code>imp</code>, but you can't use those names because they're already in use. You can't even shadow the names of the outer values, because the test-specific <code>imp</code> function has to close over those outer values in order to compare them to their expected values. </p> <p> While I decided to call the local <em>portal ID</em> argument <code>pid</code>, it's hardly helpful. Explicit arguments have become a burden rather than a help to the reader. If only we could get rid of those explicit arguments. </p> <p> <strong>Point free</strong> </p> <p> Functional programming offers a well-known alternative to explicit arguments, commonly known as <a href="https://en.wikipedia.org/wiki/Tacit_programming">point-free programming</a>. Some people find point-free style unreadable, but sometimes it can make the code more readable. Could this be the case here? </p> <p> If you look at the test-specific <code>imp</code> functions in both of the above examples with explicit arguments, you may notice that they follow a common pattern. First they invoke one or more guard assertions, and then they return a value. You can model this with a custom operator: </p> <p> <pre><span style="color:green;">//&nbsp;&#39;Guard&#39;&nbsp;composition.&nbsp;Returns&nbsp;the&nbsp;return&nbsp;value&nbsp;if&nbsp;``assert``&nbsp;doesn&#39;t&nbsp;throw.</span> <span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;unit)&nbsp;-&gt;&nbsp;&#39;b&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;b</span> <span style="color:blue;">let</span>&nbsp;(&gt;&gt;!)&nbsp;<span style="color:navy;">``assert``</span>&nbsp;returnValue&nbsp;x&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">``assert``</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;returnValue</pre> </p> <p> The first argument, <code>``assert``</code>, is a function with the type <code>'a -&gt; unit</code>. This is the assertion function: it takes any value as input, and returns <code>unit</code>. The implication is that it'll throw an exception if the assertion fails. </p> <p> After invoking the assertion, the function returns the <code>returnValue</code> argument. </p> <p> The reason I designed it that way is that it's <em>composable</em>, which you'll see in a minute. The reason I named it <code>&gt;&gt;!</code> was that I wanted some kind of arrow, and I thought that the exclamation mark relates nicely to Unquote's use of exclamation marks. </p> <p> This enables you to compose the first <code>imp</code> example (for <code>PushController</code>) in point-free style: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;validation&nbsp;failure``</span>&nbsp;req&nbsp;(<span style="color:navy;">NonNull</span>&nbsp;msg)&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;(<span style="color:navy;">snd</span>&nbsp;req))&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">fail</span>&nbsp;(<span style="color:navy;">ValidationFailure</span>&nbsp;msg) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">PushController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">BadRequestErrorMessageResult</span><span style="background:yellow;">&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Message</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">msg</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> At first glance, most people would be likely to consider this to be <em>less</em> readable than before, and clearly, that's a valid standpoint. On the other hand, once you get used to identify the <code>&gt;&gt;!</code> operator, this becomes a concise shorthand. A data-flow-verifying <code>imp</code> mock function is composed of an assertion on the left-hand side of <code>&gt;&gt;!</code>, and a return value on the right-hand side. </p> <p> Most importantly, those hard-to-name arguments are gone. </p> <p> Still, let's dissect the expression <code>((=!) (snd req)) &gt;&gt;! Result.fail (ValidationFailure msg)</code>. </p> <p> The expression on the left-hand side of the <code>&gt;&gt;!</code> operator is the assertion. It uses Unquote's <em>must equal</em> <code>=!</code> operator as a function. (In F#, infix operators are functions, and you can use them as functions by surrounding them by brackets.) While you can write an assertion as <code>candidate =! snd req</code> using infix notation, you can also write the same expression as a function call: <code>(=!) (snd req) candidate</code>. Since this is a function, it can be partially applied: <code>(=!) (snd req)</code>; the type of that expression is <code>PushRequestDtr -&gt; unit</code>, which matches the required type <code>'a -&gt; unit</code> that <code>&gt;&gt;!</code> expects from its <code>``assert``</code> argument. That explains the left-hand side of the <code>&gt;&gt;!</code> operator. </p> <p> The right-hand side is easier, because that's the return value of the composed function. In this case the value is <code>Result.fail (ValidationFailure msg)</code>. </p> <p> You already know that the type of <code>&gt;&gt;!</code> is <code>('a -&gt; unit) -&gt; 'b -&gt; 'a -&gt; 'b</code>. Replacing the generic type arguments with the actual types in use, <code>'a</code> is <code>PushRequestDtr</code> and <code>'b</code> is <code>Result&lt;'a ,BoundaryFailure&gt;</code>, so the type of <code>imp</code> is <code>PushRequestDtr -&gt; Result&lt;'a ,BoundaryFailure&gt;</code>. When you set <code>'a</code> to <code>unit</code>, this fits the required type of <code>PushRequestDtr -&gt; Result&lt;unit, BoundaryFailure&gt;</code>. </p> <p> This works because in its current incarnation, the <code>imp</code> function for <code>PushController</code> only takes a single value as input. Will this also work for <code>IdealController</code>, which passes both <code>portalId</code> and <code>req</code> to its <code>imp</code> function? </p> <p> <strong>Currying</strong> </p> <p> The <code>imp</code> function for <code>IdealController</code> has the type <code>string -&gt; IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, BoundaryFailure&gt;</code>. Notice that it takes two arguments instead of one. Is it possible to compose an <code>imp</code> function with the <code>&gt;&gt;!</code> operator? </p> <p> Consider the above example that exercises the success case for <code>IdealController</code>. What if, instead of writing </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;pid&nbsp;candidate&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;pid&nbsp;=!&nbsp;portalId &nbsp;&nbsp;&nbsp;&nbsp;candidate&nbsp;=!&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp</pre> </p> <p> you write the following? </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp </pre> </p> <p> Unfortunately, that does work, because the type of that function is <code>string * IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, 'a&gt;</code>, and not <code>string -&gt; IDealRequestDtr -&gt; Result&lt;IDealResponseDtr, BoundaryFailure&gt;</code>, as it should be. It's almost there, but the input values are tupled, instead of curried. </p> <p> You can easily correct that with a standard <a href="https://gist.github.com/ploeh/6d8050e121a5175fabb1d08ef5266cd7">curry function</a>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp&nbsp;|&gt;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span> </pre> </p> <p> The <code>Tuple2.curry</code> function takes as input a function that has tupled arguments, and turns it into a curried function. Exactly what we need here! </p> <p> The entire test is now: </p> <p> <pre>[&lt;<span style="color:teal;">Property</span>(QuietOnSuccess&nbsp;=&nbsp;<span style="color:blue;">true</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``Post&nbsp;returns&nbsp;correct&nbsp;result&nbsp;on&nbsp;success``</span>&nbsp;req&nbsp;resp&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">imp</span>&nbsp;=&nbsp;((=!)&nbsp;req)&nbsp;&gt;&gt;!&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">succeed</span>&nbsp;resp&nbsp;|&gt;&nbsp;<span style="color:teal;">Tuple2</span>.<span style="color:navy;">curry</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">use</span>&nbsp;sut&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:teal;">IdealController</span>&nbsp;(<span style="color:navy;">imp</span>) &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;sut.<span style="color:navy;">Post</span>&nbsp;req &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">test</span>&nbsp;<span style="background:yellow;">&lt;@&nbsp;</span><span style="background:yellow;">actual</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:navy;background:yellow;">convertsTo</span><span style="background:yellow;">&lt;</span><span style="background:yellow;">Results</span><span style="background:yellow;">.</span><span style="color:teal;background:yellow;">OkNegotiatedContentResult</span><span style="background:yellow;">&lt;</span><span style="color:teal;background:yellow;">IDealResponseDtr</span><span style="background:yellow;">&gt;&gt;</span><span style="background:yellow;"></span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">map</span><span style="background:yellow;">&nbsp;(</span><span style="color:blue;background:yellow;">fun</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">&nbsp;</span><span style="color:blue;background:yellow;">-&gt;</span><span style="background:yellow;">&nbsp;</span><span style="background:yellow;">r</span><span style="background:yellow;">.</span><span style="background:yellow;">Content</span><span style="background:yellow;">)</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="background:yellow;">|&gt;</span><span style="background:yellow;">&nbsp;</span><span style="color:teal;background:yellow;">Option</span><span style="background:yellow;">.</span><span style="color:navy;background:yellow;">exists</span><span style="background:yellow;">&nbsp;((</span><span style="background:yellow;">=</span><span style="background:yellow;">)&nbsp;</span><span style="background:yellow;">resp</span><span style="background:yellow;">)&nbsp;@&gt;</span></pre> </p> <p> Whether or not you find this more readable than the previous example is, as always, subjective, but I like it because it's a succinct, composable way to address data flow verification. Once you get over the initial shock of partially applying Unquote's <code>=!</code> operator, as well as the cryptic-looking <code>&gt;&gt;!</code> operator, you may begin to realise that the same idiom is repeated throughout. In fact, it's more than an idiom. It's an implementation of a design pattern. </p> <p> <strong>Mocks</strong> </p> <p> When talking about unit testing, I prefer the vocabulary of <a href="http://bit.ly/xunitpatterns">xUnit Test Patterns</a>, because of its unrivalled consistent terminology. Using Gerard Meszaros' nomenclature, a <a href="http://martinfowler.com/bliki/TestDouble.html">Test Double</a> with built-in verification of interaction is called a <em>Mock</em>. </p> <p> Most people (including me) dislike Mocks because they tend to lead to brittle unit tests. They <em>tend</em> to, but <a href="http://blog.ploeh.dk/2013/10/23/mocks-for-commands-stubs-for-queries">sometimes you need them</a>. Mocks are useful when you care about side-effects. </p> <p> Functional programming emphasises <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>, which, by definition, are free of side-effects. <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">In pure functional programming, you don't need Mocks</a>. </p> <p> Since F# is a multi-paradigmatic language, you sometimes have to write code in a more object-oriented style. In the example you've seen here, I've shown you how to unit test that Controllers correctly work as Adapters over (impure) functions. Here, Mocks are useful, even if they have no place in the rest of the code base. </p> <p> Being able to express a Mock with a couple of minimal functions is, in my opinion, preferable to adding a big dependency to a 'mocking library'. </p> <p> <strong>Concluding remarks</strong> </p> <p> Sometimes, explicit values and arguments are in the way. By their presence, they force you to name them. Often, naming is good, because it compels you to make tacit knowledge explicit. In rare cases, though, the important detail isn't a value, or an argument, but instead an <em>activity</em>. An example of this is when verifying data flow. While the values are obviously present, the focus ought to be on the comparison. Thus, by making the local function arguments implicit, you can direct the reader's attention to the interaction - in this case, Unquote's <code>=!</code> <em>must equal</em> comparison. </p> <p> In the introduction to this article, I told you that the code you've seen here is a real-life example. This is true. </p> <p> I submitted my refactoring to point-free style as an internal pull request on the project I'm currently working. When I did that, I was genuinely in doubt about the readability improvement this would give, so I asked my reviewers for their opinions. I was genuinely ready to accept if they wanted to reject the pull request. </p> <p> My reviewers disagreed internally, ultimately had a vote, and decided to reject the pull request. I don't blame them. We had a civil discussion about the pros and cons, and while they understood the advantages, they felt that the disadvantages weighed heavier. </p> <p> In their context, I understand why they decided to decline the change, but that doesn't mean that I don't find this an interesting experiment. I expect to use something like this in the future in some contexts, while in other contexts, I'll stick with the more verbose (and harder to name) test-specific functions with explicit arguments. </p> <p> Still, I like to solve problems using well-known compositions, which is the reason I prefer a composable, idiomatic approach over ad-hoc code. </p> <p> If you'd like to learn more about unit testing and property-based testing in F# (and C#), you can watch some of <a href="http://bit.ly/ploehralsight">my Pluralsight courses</a>. </p> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2016/10/25/when-variable-names-are-in-the-way Decoupling decisions from effects http://blog.ploeh.dk/2016/09/26/decoupling-decisions-from-effects/ Mon, 26 Sep 2016 21:51:00 UTC <div id="post"> <p> <em>Functional programming emphasises pure functions, but sometimes decisions must be made based on impure data. The solution is to decouple decisions and effects.</em> </p> <p> Functional programmers love <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>. Not only do they tend to be easy to reason about, they are also <a href="http://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable">intrinsically testable</a>. It'd be wonderful if we could build entire systems only from pure functions, but every functional programmer knows that the world is impure. Instead, we strive towards implementing as much of our code base as pure functions, so that an application is <a href="http://blog.ploeh.dk/2016/03/18/functional-architecture-is-ports-and-adapters">impure only at its boundaries</a>. </p> <p> The more you can do this, the more testable the system becomes. One rule of thumb about unit testing that I often use is that if a particular candidate for unit testing has a <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity">cyclomatic complexity</a> of 1, it may be acceptable to skip unit testing it. Instead, we can consider such a unit a <a href="http://xunitpatterns.com/Humble%20Object.html">humble unit</a>. If you can separate decisions from <em>effects</em> (which is what functional programmers often call impurities), you can often make the impure functions humble. </p> <p> In other words: put all logic in pure functions that can be unit tested, and implement impure effects as humble functions that you don't need to unit test. </p> <p> You want to see an example. So do I! </p> <p> <strong>Example: conditional reading from file</strong> </p> <p> In a <a href="https://gist.github.com/jcansdale/de58c2b2c389851f72b00ef525be820c">recent discussion</a>, Jamie Cansdale asks how I'd design and unit test something like the following C# method if I could instead redesign it in F#. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;GetUpperText(<span style="color:blue;">string</span>&nbsp;path) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;(!<span style="color:#2b91af;">File</span>.Exists(path))&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;text&nbsp;=&nbsp;<span style="color:#2b91af;">File</span>.ReadAllText(path); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;text.ToUpperInvariant(); }</pre> </p> <p> Notice how this method contains two impure operations: <code>File.Exists</code> and <code>File.ReadAllText</code>. Decision logic seems interleaved with IO. How can decisions be separated from effects? </p> <p> (For good measure I ought to point out that obviously, the above example is so simple that by itself, it almost doesn't warrant testing. Think of it as a stand-in for a more complex problem.) </p> <p> With a statement-based language like C#, it can be difficult to see how to separate decision logic from effects without introducing interfaces, but with expression-based languages like F#, it becomes close to trivial. In this article, I'll show you three alternatives. </p> <p> All three alternatives, however, make use of the same function for turning text into upper case: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpper</span>&nbsp;(text&nbsp;:&nbsp;<span style="color:teal;">string</span>)&nbsp;=&nbsp;text.<span style="color:navy;">ToUpperInvariant</span>&nbsp;()</pre> </p> <p> Obviously, this function is so trivial that it's hardly worth testing, but remember to think about it as a stand-in for a more complex problem. It's a pure function, so it's easy to unit test: </p> <p> <pre>[&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;foo&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;FOO&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;bar&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;BAR&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``getUpper&nbsp;returns&nbsp;correct&nbsp;value``</span>&nbsp;input&nbsp;expected&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">getUpper</span>&nbsp;input &nbsp;&nbsp;&nbsp;&nbsp;expected&nbsp;=!&nbsp;actual</pre> </p> <p> This test uses <a href="https://xunit.github.io">xUnit.net 2.1.0</a> and <a href="http://www.swensensoftware.com/unquote">Unquote 3.1.2</a>. The <code>=!</code> operator is a custom Unquote operator; you can read it as <em>must equal</em>; that is: <em>expected must equal actual</em>. It'll throw an exception if this isn't the case. </p> <p> <strong>Custom unions</strong> </p> <p> Languages like F# come with <a href="https://en.wikipedia.org/wiki/Algebraic_data_type">algebraic data types</a>, which means that in addition to complex structures, they also enable you to express types as <em>alternatives</em>. This means that you can represent a decision as one or more alternative <em>pure</em> values. </p> <p> Although the examples you'll see later in this article are simpler, I think it'll be helpful to start with an ad hoc solution to the problem. Here, the decision is to either read from a file, or return a default value. You can express that using a custom discriminated union: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Action</span>&nbsp;=&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span>&nbsp;|&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:blue;">of</span>&nbsp;<span style="color:teal;">string</span> </pre> </p> <p> This type models two mutually exclusive cases: either you decide to read from the file identified by a file path (<code>string</code>), or your return a default value (also modelled as a <code>string</code>). </p> <p> Using this <code>Action</code> type, you can write a <em>pure</em> function that makes the decision: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;bool&nbsp;-&gt;&nbsp;Action</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;fileExists&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;fileExists &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span></pre> </p> <p> This function takes two arguments: <code>path</code> (a <code>string</code>) and <code>fileExists</code> (a <code>bool</code>). If <code>fileExists</code> is <code>true</code>, it returns the <code>ReadFromFile</code> case; otherwise, it returns the <code>UseDefault</code> case. </p> <p> Notice how this function neither checks whether the file exists, nor does it attempt to read the contents of the file. It only makes a decision based on input, and returns information about this decision as output. This function is <em>pure</em>, so (as I've claimed numerous times) is easy to unit test: </p> <p> <pre>[&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;ploeh.txt&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;fnaah.txt&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``decide&nbsp;returns&nbsp;correct&nbsp;result&nbsp;when&nbsp;file&nbsp;exists``</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;<span style="color:blue;">true</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;path&nbsp;=!&nbsp;actual [&lt;<span style="color:teal;">Theory</span>&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;ploeh.txt&quot;</span>)&gt;] [&lt;<span style="color:teal;">InlineData</span>(<span style="color:#a31515;">&quot;fnaah.txt&quot;</span>)&gt;] <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">``decide&nbsp;returns&nbsp;correct&nbsp;result&nbsp;when&nbsp;file&nbsp;doesn&#39;t&nbsp;exist``</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;actual&nbsp;=&nbsp;<span style="color:navy;">decide</span>&nbsp;path&nbsp;<span style="color:blue;">false</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>&nbsp;=!&nbsp;actual</pre> </p> <p> One unit test function exercises the code path where the file exists, whereas the other test exercises the code path where it doesn't. Straightforward. </p> <p> There's still some remaining work, because you need to somehow compose your pure functions with <code>File.Exists</code> and <code>File.ReadAllText</code>. You also need a way to extract the string value from the two cases of <code>Action</code>. One way to do that is to introduce another pure function: </p> <p> <pre><span style="color:green;">//&nbsp;(string&nbsp;-&gt;&nbsp;string)&nbsp;-&gt;&nbsp;Action&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getValue</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">ReadFromFile</span>&nbsp;path&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">UseDefault</span>&nbsp;value&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;value</pre> </p> <p> This is a function that returns the <code>UseDefault</code> data for that case, but invokes a function <code>f</code> in the <code>ReadFromFile</code> case. Again, since this function is pure it's easy to unit test it, but I'll leave that as an exercise. </p> <p> You now have all the building blocks required to compose a function similar to the above <code>GetUpperText</code> C# method: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">decide</span>&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">getValue</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>)</pre> </p> <p> This implementation pipes <code>path</code> into <code>File.Exists</code>, which returns a Boolean value indicating whether the file exists. This Boolean value is then piped into <code>decide path</code>, which (as you may recall) returns an <code>Action</code>. That value is finally piped into <code>getValue (File.ReadAllText &gt;&gt; getUpper)</code>. Recall that <code>getValue</code> will only invoke the function argument when the <code>Action</code> is <code>ReadFromFile</code>, so <code>File.ReadAllText &gt;&gt; getUpper</code> is only executed in this case. </p> <p> Notice how decisions and effectful functions are interleaved. All the decision functions are covered by unit tests; only <code>File.Exists</code> and <code>File.ReadAllText</code> aren't covered, but I find it reasonable to treat these as humble functions. </p> <p> <strong>Either</strong> </p> <p> Normally, decisions often involve a choice between two alternatives. In the above example, you saw how the alternatives were named <code>ReadFromFile</code> and <code>UseDefault</code>. Since a choice between two alternatives is so common, there's a well-known 'pattern' that gives you general-purpose tools to model decisions. This is known as the <em>Either</em> monad. </p> <p> The F# core library doesn't (<a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1004-result-type.md">yet</a>) come with an implementation of the Either monad, but it's easy to add. In this example, I'm using code from <a href="https://fsharpforfunandprofit.com">Scott Wlaschin's</a> <a href="https://fsharpforfunandprofit.com/posts/recipe-part2">railway-oriented programming</a>, although slightly modified, and including only the most essential building blocks for the example: </p> <p> <pre> <span style="color:blue;">type</span>&nbsp;<span style="color:teal;">Result<'TSuccess, 'TFailure></span>&nbsp;= | Success <span style="color:blue;">of</span> 'TSuccess | Failure <span style="color:blue;">of</span> 'TFailure <span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Result</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&gt;)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">bind</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;Result&lt;&#39;b,&nbsp;&#39;c&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">map</span>&nbsp;<span style="color:navy;">f</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;(<span style="color:navy;">f</span>&nbsp;succ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;bool)&nbsp;-&gt;&nbsp;&#39;a&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;a&gt;</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">split</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;=&nbsp;<span style="color:blue;">if</span>&nbsp;<span style="color:navy;">f</span>&nbsp;x&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:navy;">Success</span>&nbsp;x&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:navy;">Failure</span>&nbsp;x &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;(&#39;a&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;(&#39;c&nbsp;-&gt;&nbsp;&#39;b)&nbsp;-&gt;&nbsp;Result&lt;&#39;a,&nbsp;&#39;c&gt;&nbsp;-&gt;&nbsp;&#39;b</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">either</span>&nbsp;<span style="color:navy;">f</span>&nbsp;<span style="color:navy;">g</span>&nbsp;=&nbsp;<span style="color:blue;">function</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Success</span>&nbsp;succ&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">f</span>&nbsp;succ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;<span style="color:navy;">Failure</span>&nbsp;fail&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:navy;">g</span>&nbsp;fail</pre> </p> <p> In fact, the <code>bind</code> and <code>map</code> functions aren't even required for this particular example, but I included them anyway, because otherwise, readers already familiar with the Either monad would wonder why they weren't there. </p> <p> All these functions are generic and pure, so they are easy to unit test. I'm not going to show you the unit tests, however, as I consider the functions belonging to that <code>Result</code> module as reusable functions. This is a module that would ship as part of a well-tested library. In fact, <a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1004-result-type.md">it'll soon be added to the F# core library</a>. </p> <p> With the already tested <code>getUpper</code> function, you now have all the building blocks required to implement the desired functionality: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">split</span>&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Result</span>.<span style="color:navy;">either</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>)&nbsp;(<span style="color:blue;">fun</span>&nbsp;_&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span>)</pre> </p> <p> This composition pipes <code>path</code> into <code>Result.split</code>, which uses <code>File.Exists</code> as a predicate to decide whether the path should be packaged into a <code>Success</code> or <code>Failure</code> case. The resulting <code>Result&lt;string, string&gt;</code> is then piped into <code>Result.either</code>, which invokes <code>File.ReadAllText &gt;&gt; getUpper</code> in the <code>Success</code> case, and the anonymous function in the <code>Failure</code> case. </p> <p> Notice how, once again, the impure functions <code>File.Exists</code> and <code>File.ReadAllText</code> are used as humble functions, but interleaved with testable, pure functions that make all the decisions. </p> <p> <strong>Maybe</strong> </p> <p> Sometimes, a decision isn't so much between two alternatives as it's a decision between something that may exist, but also may not. You can model this with the <em>Maybe</em> monad, which in F# comes in the form of the built-in <code>option</code> type. </p> <p> In fact, so much is already built in (and tested by the F# development team) that you almost don't need to add anything yourself. The only function you could consider adding is this: </p> <p> <pre><span style="color:blue;">module</span>&nbsp;<span style="color:teal;">Option</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:green;">//&nbsp;&#39;a&nbsp;-&gt;&nbsp;&#39;a&nbsp;option&nbsp;-&gt;&nbsp;&#39;a</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;<span style="color:navy;">defaultIfNone</span>&nbsp;def&nbsp;x&nbsp;=&nbsp;<span style="color:navy;">defaultArg</span>&nbsp;x&nbsp;def</pre> </p> <p> As you can see, this function simply swaps the arguments for the built-in <code>defaultArg</code> function. This is done to make it more pipe-friendly. This function <a href="https://github.com/fsharp/FSharpLangDesign/blob/master/RFCs/FS-1007-additional-Option-module-functions.md">will most likely be added in a future version of F#</a>. </p> <p> That's all you need: </p> <p> <pre><span style="color:green;">//&nbsp;string&nbsp;-&gt;&nbsp;string</span> <span style="color:blue;">let</span>&nbsp;<span style="color:navy;">getUpperText</span>&nbsp;path&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;path &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:navy;">Some</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">filter</span>&nbsp;<span style="color:teal;">File</span>.<span style="color:navy;">Exists</span> &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">map</span>&nbsp;(<span style="color:teal;">File</span>.<span style="color:navy;">ReadAllText</span>&nbsp;&gt;&gt;&nbsp;<span style="color:navy;">getUpper</span>) &nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;<span style="color:teal;">Option</span>.<span style="color:navy;">defaultIfNone</span>&nbsp;<span style="color:#a31515;">&quot;DEFAULT&quot;</span></pre> </p> <p> This composition starts with the <code>path</code>, puts it into a <code>Some</code> case, and pipes that <code>option</code> value into <code>Option.filter File.Exists</code>. This means that the <code>Some</code> case will only stay a <code>Some</code> value if the file exists; otherwise, it will be converted to a <code>None</code> value. Whatever the <code>option</code> value is, it's then piped into <code>Option.map (File.ReadAllText &gt;&gt; getUpper)</code>. The composed function <code>File.ReadAllText &gt;&gt; getUpper</code> is only executed in the <code>Some</code> case, so if the file doesn't exist, the function will not attempt to read it. Finally, the <code>option</code> value is piped into <code>Option.defaultIfNone</code>, which returns the mapped value, or <code>"DEFAULT"</code> if the value was <code>None</code>. </p> <p> Like in the two previous examples, the decision logic is implemented by pure functions, whereas the impure functions <code>File.Exists</code> and <code>File.ReadAllText</code> are handled as humble functions. </p> <p> <strong>Summary</strong> </p> <p> Have you noticed a pattern in all the three examples? Decisions are separated from effects using discriminated unions (both the above <code>Action</code>, <code>Result&lt;'TSuccess, 'TFailure&gt;</code>, and the built-in <code>option</code> are discriminated unions). In my experience, as long as you need to decide between two alternatives, the Either or Maybe monads are often sufficient to decouple decision logic from effects. Often, I don't even need to write any tests, because I compose my functions from the known, well-tested functions that belong to the respective monads. </p> <p> If your decision has to branch between three or more alternatives, you can consider a custom discriminated union. For this particular example, though, I think I prefer the third, Maybe-based composition, but closely followed by the Either-based composition. </p> <p> In this article, you saw three examples of how to decouple decision from effects; and I didn't even show you the <em>Free</em> monad! </p> </div> <div id="comments"> <hr> <h2 id="comments-header">Comments</h2> <div class="comment"> <div class="comment-author"><a href="https://github.com/blainne">Grzegorz Sławecki</a></div> <div class="comment-content"> <p> Mark, </p> <p> I can't understand how can the <code>getValue</code> function be pure. While I agree that it's easy to test, it's still the higher order function and it's purity depends on the purity of function passed as the argument. Even in Your example it takes <code>File.ReadAllText&nbsp;&gt;&gt;&nbsp;getUpper</code> which actually reaches to a file on the disk and I perceive it as reaching to an external shared state. Is there something I misunderstood? </p> </div> <div class="comment-date">2016-10-14 09:06 UTC</div> </div> <div class="comment"> <div class="comment-author"><a href="http://blog.ploeh.dk">Mark Seemann</a></div> <div class="comment-content"> <p> Grzegorz, thank you for writing. You make a good point, and in a sense you're correct. F# doesn't enforce purity, and this is both an advantage and a disadvantage. It's an advantage because it makes it easier for programmers migrating from C# to make a gradual transition to a more functional programming style. It's also an advantage exactly because it relies on the programmer's often-faulty reasoning to ensure that code is properly functional. </p> <p> Functions in F# are only pure if they're implemented to be pure. For any given function type (signature) you can always create an impure function that fits the type. (If nothing else, you can always write "Hello, world!" to the console, before returning a value.) </p> <p> The result of this is that few parts of F# are pure in the sense that you imply. Even <code>List.map</code> could be impure, if passed an impure function. In other words, higher-order functions in F# are only pure if composed of exclusively pure parts. </p> <p> Clearly, this is in stark contrast to Haskell, where purity is enforced at the type level. In Haskell, a throw-away, poorly designed mini-API like the <code>Action</code> type and associated functions shown here wouldn't even compile. The Either and Maybe examples, on the other hand, would. </p> <p> My assumption here is that function composition happens at the edge of the application - that is, in an impure (<code>IO</code>) context. </p> </div> <div class="comment-date">2016-10-15 09:02 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NZEPYW8KVZ8WL">buy me a cup of coffee</a>. Mark Seemann http://blog.ploeh.dk/2016/09/26/decoupling-decisions-from-effects