Section "Dealing with success and failure with Either" is unclear

[marco-m]

hello Shantanu, thanks for promenade!

I was going through the documentation and got tripped by the example in
section "Dealing with success and failure with Either":

(prom/either->> order-id
  fetch-order-details
  check-inventory
  [(cancel-order order-id) process-order]
  [stock-replenish-init]
  fulfil-order)

What was not evident for me is that the error handlers MUST return a failure always.

To make a concrete example, if fetch-order-details returns a failure, then the
cancel-order error handler will be called. If by mistake it returns anything that
is not a failure, fulfil-order will be called.

This might be the normal behavior of the Either monad, but for a non-expert
like myself it was quite confusing :-)

Would it make sense to make it more explicit in the documentation that all error handlers
MUST return a failure ?

[kumarshantanu]

Hi Marco, thanks for bringing the issue to my notice! I indeed want promenade to be useful for people without them necessarily having to know about monads.

A failure-handler may or may not recover from a failure, hence they may return either failure or success. However, a failure-handler is only invoked if the prior result is a failure. Specifically, in the example that you cited, cancel-order would deliberately keep the status as failure so that the control can flow to the next step stock-replenish-init. Perhaps I can use a clearer example, however, below is how the flow happens (please excuse the | separator - it is only for illustrative formatting):

(prom/either->>        order-id
;; ---- failure track ---- | ---- success track ----
                           | fetch-order-details
;;               failure  ↙↙       ↓↓↓  success
                           | check-inventory
;;               failure  ↙↙       ↓↓↓  success
  [(cancel-order order-id) | process-order]
;;       failure ↓↓↓       ↘↘  success
  [stock-replenish-init    |              ]
;;       failure ↓↓↓       ↘↘  success
                           | fulfil-order)

I guess it may help to illustrate the example snippets in a similar fashion. But before that, I am interested to know your feedback.

[marco-m]

I think that the paragraph "A failure-handler may or may not recover from a failure, hence they may return either failure or success. However, a failure-handler is only invoked if the prior result is a failure. Specifically, in the example that you cited, cancel-order would deliberately keep the status as failure so that the control can flow to the next step stock-replenish-init" is perfect to clarify! Also the diagram can be helpful I think.

Thanks again!