theangrydev/business-flows

A combination of the Try monad and the Either monad, to help tame complex business flows

business-flows's Issues

Investigate making it harder to leave a flow dangling

Currently it is all too easy to have an exception swallowed by the framework and to not handle it. Issue #8 will help with this a little in void cases, but I have another idea.

There could be a checked FlowInProgress exception that is declared on all the methods apart from the ones that end a flow like join. This would give a compile time error if the exception is not caught or declared, which could prompt someone to end the flow. Ideally the compiler would also prevent catching the exception, not sure if that is possible.

This is all just a hack to try to make it hard to make the mistake of having swallowed exceptions that do not end up in the application logs.

Consider renaming "peek" to "tee"

The method that inspects a flow and leaves it untouched (unless there is a technical failure during the inspection) is currently called peek. That name caused some initial confusion with users and so maybe tee is better since it should be more universally familiar. There might be other names too which fit the readability and understanding requirements better that I haven't thought of yet.

Add consume methods

Similar to the existing join methods, this one would just take 3 peeks to end a flow by performing some action, with return type void. Probably a 2 peek version that throws the technical failure as a runtime exception too and another consumeOrThrow that throws it as a checked exception. Could also have 1 peek versions for each of the branches that throws a runtime exception if the bias is not present.

The motivation for this is that there is currently no clean way to end a flow in a void.

Mapping.identity should allow upcasting

At the moment, Mapping.identity produces a Mapping<Old, Old>. It should really produce Mapping<Old, New> where Old extends New.

Optimized overrides for ifHappy etc

HappyPath can return this for ifHappy and similar for the other paths

Inline methods to make debugging easier

Rather than having e.g. map delegating to then etc, it might be better to take the hit of duplication in the library so that the resulting stack is smaller, making stack traces and manual debugging easier to manage

HappyPath.happyPathAttempt should accept any BusinessFlow

Currently, it only accepts a HappyPath

Write some example before and after code snippets

Something like exception based flow control vs the railway oriented approach.

More examples of usage of business flows

Here is a link to the repo where I have created a few examples of using business flows, you might want to add the link to your readme.

https://github.com/hanfak/railway-prog-examples

No tests, might add later.

Run static analysis over test code

Not that important but might pick up on some unexpected things...

consumeOrThrowUnchecked

It would be useful to have a version of consumeOrThrow that throws unchecked

Write some comprehensive documentation for all the features

This is an epic, will raise issues for each bit.

Any code snippets should be linked to actual code examples and ideally have something in the build that generates the wiki pages or at least validates that the examples correspond to real code. This is to prevent the documentation from becoming out of date.

Review usage of {@inheritDoc}

Not sure if it is being used properly

throwItAsARuntimeException and throwIt should not be void

So they can be chained

Add methods to help with multiple return style

Sometimes, e.g. when there is a lot of scope that is needed to proceed a business flow, it is easier to exit early and have multiple return statements per possible sad path and a try-catch around the entire block.

To facilitate this, the following methods would help:

• ifHappy and ifSad
• getHappy and getSad

Investigate whether a PotentialRecovery class makes sense

Like the PotentialFailure class but for sad recoveries

Think about removing happyAttempt

Remembering that this library is supposed to be about two tracks flows, it doesn't really make sense to have a happyAttempt method at all, because at that point there is only one track. The happyPathAttempt method does make sense.

Investigate allowing then methods to change the type

For example, a happy path then could change the happy type and a sad path then could change the sad type?

Wiki generator

As part of #14, it seemed like a good idea to generate some usage examples from the code. There is currently a proof of concept of this already working.

I have some more ideas for it:

• Add @since documentation, either in the Javadoc or in some custom annotation (if there are 2 places they should be synced up somehow)
• Javadoc links to the wiki pages, with e.g. example usage that is syntax highlighted
• Test that any external links in the Javadoc are live (easy for wiki pages, can use relative paths)
• Create a "live links" file, which would be a set of wiki page paths that are supposed to be reachable forever more. The build could append to this list when generating the wiki, but never delete from it
• All links that have moved should have a redirect to the new page, or some blanket page that explains why the link was broken
• Create a "redirect.properties" file that maps old paths to new paths. This could be used during the wiki generation to populate the redirects, complaining if there is a "live links" file entry that has neither a page nor a redirect