From 9ddda03bd6e863132dcaababa56230997c842da3 Mon Sep 17 00:00:00 2001
From: Eric Rumsey <ehrumsey@gmail.com>
Date: Fri, 23 May 2025 17:36:31 -0500
Subject: [PATCH] Functional programming module

---
 src/lib/util/basic/either.ts  | 28 +++++++++++++++++++++++++++
 src/lib/util/basic/list.ts    | 36 +++++++++++++++++++++++++++++++++++
 src/lib/util/basic/option.ts  | 22 +++++++++++++++++++++
 src/lib/util/basic/utility.ts | 22 +++++++++++++++++++++
 4 files changed, 108 insertions(+)
 create mode 100644 src/lib/util/basic/either.ts
 create mode 100644 src/lib/util/basic/list.ts
 create mode 100644 src/lib/util/basic/option.ts
 create mode 100644 src/lib/util/basic/utility.ts

diff --git a/src/lib/util/basic/either.ts b/src/lib/util/basic/either.ts
new file mode 100644
index 0000000..e7e460f
--- /dev/null
+++ b/src/lib/util/basic/either.ts
@@ -0,0 +1,28 @@
+export type Left<E> = {readonly _tag: 'Left', readonly left: E}
+export type Right<A> = {readonly _tag: 'Right', readonly right: A}
+export type Either<E, A> = Left<E> | Right<A>
+
+// Constructors
+export const left = <E>(e: E): Either<E, never> => ({
+  _tag: 'Left',
+  left: e,
+})
+export const right = <A>(a: A): Either<never, A> => ({
+  _tag: 'Right',
+  right: a,
+})
+
+// Operations
+export const eitherMap =
+  <E, A, B>(f: (a: A) => B) => (fa: Either<E, A>): Either<E, B> =>
+    fa._tag === 'Right' ? right(f(fa.right)) : fa
+
+export const eitherChain =
+  <E, A, B>(f: (a: A) => Either<E, B>) =>
+  (fa: Either<E, A>): Either<E, B> =>
+    fa._tag === 'Right' ? f(fa.right) : fa
+
+export const fold =
+  <E, A, B>(onLeft: (e: E) => B, onRight: (a: A) => B) =>
+  (fa: Either<E, A>): B =>
+    fa._tag === 'Left' ? onLeft(fa.left) : onRight(fa.right)
diff --git a/src/lib/util/basic/list.ts b/src/lib/util/basic/list.ts
new file mode 100644
index 0000000..ffc672f
--- /dev/null
+++ b/src/lib/util/basic/list.ts
@@ -0,0 +1,36 @@
+export type Nil = { readonly _tag: 'Nil' };
+export type Cons<A> = {
+  readonly _tag: 'Cons';
+  readonly head: A;
+  readonly tail: List<A>;
+};
+export type List<A> = Nil | Cons<A>;
+
+// Constructors
+export const nil: Nil = { _tag: 'Nil' };
+export const cons = <A>(head: A, tail: List<A>): List<A> => ({
+  _tag: 'Cons',
+  head,
+  tail,
+});
+
+// Operations
+type ListMap = <A, B>(f: (a: A) => B) => (fa: List<A>) => List<B>;
+export const listMap: ListMap = (f) => (fa) =>
+  fa._tag === 'Cons' ? cons(f(fa.head), listMap(f)(fa.tail)) : nil;
+
+type ListReduce = <A, B>(
+  f: (b: B, a: A) => B,
+  initial: B
+) => (fa: List<A>) => B;
+export const listReduce: ListReduce = (f, initial) => (fa) =>
+  fa._tag === 'Cons' ? listReduce(f, f(initial, fa.head))(fa.tail) : initial;
+
+// Helpers
+type FromArray = <A>(arr: Array<A>) => List<A>;
+export const fromArray: FromArray = <A>(arr: Array<A>) =>
+  arr.reduceRight((acc: List<A>, val: A) => cons(val, acc), nil as List<A>);
+
+type ToArray = <A>(fa: List<A>) => Array<A>;
+export const toArray: ToArray = <A>(fa: List<A>) =>
+  listReduce<A, Array<A>>((acc, val) => [...acc, val], [] as Array<A>)(fa);
diff --git a/src/lib/util/basic/option.ts b/src/lib/util/basic/option.ts
new file mode 100644
index 0000000..165c0c1
--- /dev/null
+++ b/src/lib/util/basic/option.ts
@@ -0,0 +1,22 @@
+export type None = {readonly _tag: 'None'}
+export type Some<A> = {readonly _tag: 'Some', readonly value: A}
+export type Option<A> = Some<A> | None
+
+// Constructors
+export const none: Option<never> = {_tag: 'None'}
+export const some = <A>(value: A): Option<A> => ({
+  _tag: 'Some',
+  value,
+})
+
+// Operations
+export const map =
+  <A, B>(f: (a: A) => B) => (fa: Option<A>): Option<B> =>
+    fa._tag === 'Some' ? some(f(fa.value)) : none
+
+export const chain =
+  <A, B>(f: (a: A) => Option<B>) => (fa: Option<A>): Option<B> =>
+    fa._tag === 'Some' ? f(fa.value) : none
+
+export const getOrElse = <A>(defaultValue: A) => (fa: Option<A>): A =>
+  fa._tag === 'Some' ? fa.value : defaultValue
diff --git a/src/lib/util/basic/utility.ts b/src/lib/util/basic/utility.ts
new file mode 100644
index 0000000..b7dd0b5
--- /dev/null
+++ b/src/lib/util/basic/utility.ts
@@ -0,0 +1,22 @@
+import { type Either, left, right } from './either'
+import { none, type Option, some } from './option'
+
+// Pipe function for composition
+export const pipe = <A, B, C>(
+  a: A,
+  ab: (a: A) => B,
+  bc: (b: B) => C,
+): C => bc(ab(a))
+
+// TryCatch helper using Either
+export const tryCatch = <A>(f: () => A): Either<Error, A> => {
+  try {
+    return right(f())
+  } catch (e) {
+    return left(e instanceof Error ? e : new Error(String(e)))
+  }
+}
+
+// Option from nullable
+export const fromNullable = <A>(a: A | null | undefined): Option<A> =>
+  a == null ? none : some(a)