feat: Add monad util

README.md

@@ -306,4 +306,32 @@ type SummaryResult = { // Self-explanatory
     ok:number;
     error:number;
 };
-```
+```
+To assert errors, you can use the `monad` and `asyncMonad` utils:
+```typescript
+import { test, monad, asyncMonad } from "arrange-act-assert";
+
+import { thing, asyncThing } from "./myThing";
+
+test("Should throw an error when invalid arguments", {
+    ACT() {
+        return monad(() => thing(-1));
+    },
+    ASSERT(res) {
+        res.should.error({
+            message: "Argument must be >= 0"
+        });
+    }
+});
+test("Should throw an error when invalid arguments in async function", {
+    async ACT() {
+        return await asyncMonad(async () => await thing(-1));
+    },
+    ASSERT(res) {
+        res.should.error({
+            message: "Argument must be >= 0"
+        });
+    }
+});
+```
+They will return a `Monad` object with the properties `ok` and `error` and the methods `should.ok(VALUE)` and `should.error(ERROR)`. The error validation is done using the [NodeJS Assert.throws() error argument](https://nodejs.org/api/assert.html#assertthrowsfn-error-message).

src/index.test.ts

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import * as Assert from "node:assert";
 
 import { TestSuite } from "./TestSuite/TestSuite";
+import { monad, asyncMonad } from "./monad/monad";
 
 import * as INDEX from "./index";
 
@@ -12,5 +13,7 @@ test.describe("Index", () => {
         Assert.strictEqual(typeof INDEX.describe, "function", "doesn't have describe method");
         Assert.strictEqual(INDEX.default, INDEX.test, "doesn't export defaults");
         Assert.strictEqual(INDEX.TestSuite, TestSuite, "doesn't export TestSuite");
+        Assert.strictEqual(INDEX.monad, monad, "doesn't export monad");
+        Assert.strictEqual(INDEX.asyncMonad, asyncMonad, "doesn't export asyncMonad");
     });
 });

src/index.ts

@@ -4,6 +4,7 @@ export type { TestSuiteOptions, TestSuiteContext } from "./TestSuite/TestSuite";
 export type { TestInterface, TestFunction, Test } from "./testRunner/testRunner";
 
 export { TestSuite } from "./TestSuite/TestSuite";
+export { monad, asyncMonad } from "./monad/monad";
 
 export default TR;
 export const test = TR.test;

src/monad/monad.test.ts

@@ -0,0 +1,102 @@
+import { test } from "node:test";
+import * as Assert from "node:assert";
+
+import { monad, asyncMonad } from "./monad";
+
+test.describe("monad", () => {
+    test.describe("sync", () => {
+        test("should return ok", () => {
+            // Act
+            const res = monad(() => 123);
+
+            // Assert
+            Assert.deepStrictEqual(res, {
+                ok: 123,
+                should: res.should
+            });
+        });
+        test("should return error", () => {
+            // Act
+            const res = monad(() => {
+                throw "ok";
+            });
+
+            // Assert
+            Assert.deepStrictEqual(res, {
+                error: "ok",
+                should: res.should
+            });
+        });
+        test.describe("should", () => {
+            test("should assert ok", () => {
+                // Act
+                const res = monad(() => 123);
+
+                // Assert
+                Assert.doesNotThrow(() => res.should.ok(123));
+            });
+            test("should assert error", () => {
+                // Act
+                const res = monad(() => {
+                    throw new Error("ok")
+                });
+
+                // Assert
+                Assert.doesNotThrow(() => res.should.error({
+                    message: "ok"
+                }));
+            });
+        });
+    });
+    test.describe("async", () => {
+        test("should return a promise", () => {
+            // Act
+            const res = asyncMonad(async () => 123);
+
+            // Assert
+            Assert.strictEqual(res instanceof Promise, true);
+        });
+        test("should return ok", async () => {
+            // Act
+            const res = await asyncMonad(async () => 123);
+
+            // Assert
+            Assert.deepStrictEqual(res, {
+                ok: 123,
+                should: res.should
+            });
+        });
+        test("should return error", async () => {
+            // Act
+            const res = await asyncMonad(async () => {
+                throw "ok";
+            });
+
+            // Assert
+            Assert.deepStrictEqual(res, {
+                error: "ok",
+                should: res.should
+            });
+        });
+        test.describe("should", () => {
+            test("should assert ok", async () => {
+                // Act
+                const res = await asyncMonad(async () => 123);
+
+                // Assert
+                Assert.doesNotThrow(() => res.should.ok(123));
+            });
+            test("should assert error", async () => {
+                // Act
+                const res = await asyncMonad(async () => {
+                    throw new Error("ok")
+                });
+
+                // Assert
+                Assert.doesNotThrow(() => res.should.error({
+                    message: "ok"
+                }));
+            });
+        });
+    });
+});

src/monad/monad.ts

@@ -0,0 +1,58 @@
+import * as Assert from "assert";
+
+type MonadObject<T> = {
+    ok:T;
+} | {
+    error:unknown;
+};
+export type Monad<T> = MonadObject<T> & {
+    should: {
+        ok(value:T):void;
+        error(error:Assert.AssertPredicate):void;
+    }
+};
+function monadify<T>(res:MonadObject<T>):Monad<T> {
+    return {
+        ...res,
+        should: {
+            ok(value) {
+                if ("ok" in res) {
+                    Assert.strictEqual(res.ok, value);
+                } else {
+                    throw new Error(`Monad has error: ${res.error}`);
+                }
+            },
+            error(error) {
+                if ("error" in res) {
+                    Assert.throws(() => {
+                        throw res.error
+                    }, error);
+                } else {
+                    throw new Error(`Monad is ok with value: ${res.ok}`);
+                }
+            }
+        }
+    };
+}
+export function monad<T>(cb:()=>T):Monad<T> {
+    try {
+        return monadify({
+            ok: cb()
+        });
+    } catch (e) {
+        return monadify({
+            error: e
+        });
+    }
+}
+export async function asyncMonad<T>(cb:()=>PromiseLike<T>):Promise<Monad<T>> {
+    try {
+        return monadify({
+            ok: await cb()
+        });
+    } catch (e) {
+        return monadify({
+            error: e
+        });
+    }
+}