Bracket for producing a value from an IO that can be cleaned up

jnape · jnape · commit a88cd97ca1a4 · 2019-05-11T17:55:47.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -47,6 +47,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - `IO#safe`, mapping an `IO<A>` to an `IO<Either<Throwable, A>>` that will never throw
 - `IO#ensuring`, like `finally` semantics for `IO`s
 - `IO#throwing`, for producing an `IO<A>` that will throw a given `Throwable` when executed
+- `Bracket`, for bracketing an `IO` operation with a mapping operation and a cleanup operation 
 
 ## [3.3.0] - 2019-02-18
 ### Added
diff --git a/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn3/Bracket.java b/src/main/java/com/jnape/palatable/lambda/functions/builtin/fn3/Bracket.java
@@ -0,0 +1,52 @@
+package com.jnape.palatable.lambda.functions.builtin.fn3;
+
+import com.jnape.palatable.lambda.functions.Fn1;
+import com.jnape.palatable.lambda.functions.Fn2;
+import com.jnape.palatable.lambda.functions.Fn3;
+import com.jnape.palatable.lambda.io.IO;
+import com.jnape.palatable.lambda.monad.Monad;
+
+/**
+ * Given an {@link IO} that yields some type <code>A</code>, a cleanup operation to run if a value of that type could be
+ * provisioned, and a kleisli arrow from that type to a new {@link IO} of type <code>B</code>, produce an
+ * <code>{@link IO}&lt;B&gt;</code> that, when run, will provision the <code>A</code>,
+ * {@link Monad#flatMap(Fn1) flatMap} it to <code>B</code>, and clean up the original value if it was produced in the
+ * first place.
+ *
+ * @param <A> the initial value to map and clean up
+ * @param <B> the resulting type
+ */
+public final class Bracket<A, B> implements
+        Fn3<IO<A>, Fn1<? super A, ? extends IO<?>>, Fn1<? super A, ? extends IO<B>>, IO<B>> {
+
+    private static final Bracket<?, ?> INSTANCE = new Bracket<>();
+
+    private Bracket() {
+    }
+
+    @Override
+    public IO<B> checkedApply(IO<A> io, Fn1<? super A, ? extends IO<?>> cleanupIO,
+                              Fn1<? super A, ? extends IO<B>> bodyIO) throws Throwable {
+        return io.flatMap(a -> bodyIO.apply(a).ensuring(cleanupIO.apply(a)));
+    }
+
+    @SuppressWarnings("unchecked")
+    public static <A, B> Bracket<A, B> bracket() {
+        return (Bracket<A, B>) INSTANCE;
+    }
+
+    public static <A, B> Fn2<Fn1<? super A, ? extends IO<?>>, Fn1<? super A, ? extends IO<B>>, IO<B>> bracket(
+            IO<A> io) {
+        return Bracket.<A, B>bracket().apply(io);
+    }
+
+    public static <A, B> Fn1<Fn1<? super A, ? extends IO<B>>, IO<B>> bracket(
+            IO<A> io, Fn1<? super A, ? extends IO<?>> cleanupIO) {
+        return Bracket.<A, B>bracket(io).apply(cleanupIO);
+    }
+
+    public static <A, B> IO<B> bracket(IO<A> io, Fn1<? super A, ? extends IO<?>> cleanupIO,
+                                       Fn1<? super A, ? extends IO<B>> bodyIO) {
+        return Bracket.<A, B>bracket(io, cleanupIO).apply(bodyIO);
+    }
+}
diff --git a/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn3/BracketTest.java b/src/test/java/com/jnape/palatable/lambda/functions/builtin/fn3/BracketTest.java
@@ -0,0 +1,77 @@
+package com.jnape.palatable.lambda.functions.builtin.fn3;
+
+import com.jnape.palatable.lambda.io.IO;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static com.jnape.palatable.lambda.functions.builtin.fn3.Bracket.bracket;
+import static com.jnape.palatable.lambda.io.IO.io;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+
+public class BracketTest {
+
+    private AtomicInteger count;
+
+    @Before
+    public void setUp() {
+        count = new AtomicInteger(0);
+    }
+
+    @Test
+    public void cleanupHappyPath() {
+        IO<Integer> hashIO = bracket(io(() -> count), c -> io(c::incrementAndGet), c -> io(c::hashCode));
+
+        assertEquals(0, count.get());
+        assertEquals((Integer) count.hashCode(), hashIO.unsafePerformIO());
+        assertEquals(1, count.get());
+    }
+
+    @Test
+    public void cleanupSadPath() {
+        IllegalStateException thrown = new IllegalStateException("kaboom");
+        IO<Integer>           hashIO = bracket(io(count), c -> io(c::incrementAndGet), c -> io(() -> {throw thrown;}));
+
+        try {
+            hashIO.unsafePerformIO();
+            fail("Expected exception to be raised");
+        } catch (IllegalStateException actual) {
+            assertEquals(thrown, actual);
+            assertEquals(1, count.get());
+        }
+    }
+
+    @Test
+    public void cleanupOnlyRunsIfInitialIORuns() {
+        IllegalStateException thrown = new IllegalStateException("kaboom");
+        IO<Integer> hashIO = bracket(io(() -> {throw thrown;}),
+                                     __ -> io(count::incrementAndGet),
+                                     __ -> io(count::incrementAndGet));
+        try {
+            hashIO.unsafePerformIO();
+            fail("Expected exception to be raised");
+        } catch (IllegalStateException actual) {
+            assertEquals(thrown, actual);
+            assertEquals(0, count.get());
+        }
+    }
+
+    @Test
+    public void errorsInCleanupAreAddedToBodyErrors() {
+        IllegalStateException bodyError    = new IllegalStateException("kaboom");
+        IllegalStateException cleanupError = new IllegalStateException("KABOOM");
+        IO<Integer> hashIO = bracket(io(count),
+                                     c -> io(() -> {throw cleanupError;}),
+                                     c -> io(() -> {throw bodyError;}));
+        try {
+            hashIO.unsafePerformIO();
+            fail("Expected exception to be raised");
+        } catch (IllegalStateException actual) {
+            assertEquals(bodyError, actual);
+            assertArrayEquals(new Throwable[]{cleanupError}, actual.getSuppressed());
+        }
+    }
+}
