Promise.then* and catchError

Overview of handlers

Different types of promises handlers.

• then - use this to handle async calls
• thenExpected - use this to handle async calls whose result could be null
• thenSafe - use this to report errors with async call and your handler
• thenSafeExpected - same as thenSafe but used where the result could be null
• thenMap - converts one type of promise into another type of promise
• catchError - handles an exception

thenExpect and thenSafeExpect

The handlers thenExpect and thenSafeExpect return a Reakt Expected instance. Expected is like Option in Java 8, it has methods like map, filter, etc. and adds methods ifEmpty, isEmpty. This gives a nice fluent API when you don't know if a successful return is null or not.

then and thenSafeExpect

The methods then and thenSafe async return the result that is not wrapped in an Expected object, i.e., the raw result. Use then and thenSafe when you know the async return will not be null. Use thenExpect and thenSafeExpect if the value could be null or if you want to map or filter the result.

thenMap

Use thenMap when a promise returns for example a List<Employee>, but you only want the first Employee. See Promise.thenMap for more details.

safe thenSafe thenSafeExpect

Unless you are using a reactor, custom Promises or blocking promises, the then* handlers will typically run in a foreign thread and if they throw an exception depending on the library, they could get logged in an odd way. If you think your handler could throw an exception (not the service you are calling but your handlers), then you might want to use thenSafe or thenSafeExpect. These will wrap your async then* handler code in a try/catch and pass the thrown exception to a ThenHandlerException to catchError. If your code ever hangs when making an async call, try using a thenSafe or thenSafeExpect. They ensure that any exceptions thrown in your handler don't get dropped by the system you are using, which could indicate a lack of understanding of the async lib you are using or that you are using it wrong. If it hangs, try thenSafe or thenSafeExpect. They help you debug async problems.