✨ Add tryCatch function

Closes #61

api.ts

@@ -304,7 +304,8 @@ const api: Api = {
     ramda: 'takeLast',
     rambda: 'takeLast',
     lodash: 'takeRight'
-  }
+  },
+  tryCatch: ['rambda', 'ramda']
   // test: {
   //   fonction: undefined
   // },

mod.ts

@@ -78,6 +78,7 @@ export type { TrimLeft } from './src/trimLeft.ts'
 export { trimLeft } from './src/trimLeft.ts'
 export type { TrimRight } from './src/trimRight.ts'
 export { trimRight } from './src/trimRight.ts'
+export { tryCatch } from './src/tryCatch.ts'
 export type {
   AnyFn,
   Empty,

src/tryCatch.ts

@@ -0,0 +1,42 @@
+// Copyright 2021-present the Fonction authors. All rights reserved. MIT license.
+import { advance } from './advance.ts'
+import { ifElse } from './ifElse.ts'
+import { isFunction } from './isFunction.ts'
+import { isUndefined } from './isUndefined.ts'
+import { N } from './N.ts'
+import { AnyFn } from './types/index.ts'
+
+/**
+ * `tryCatch` takes two functions, a `tryer` and a `catcher`. The returned function evaluates the `tryer`; if it does not throw, it simply returns the result. If the `tryer` does throw, the returned function evaluates the catcher function and returns its result.
+ *
+ * @param tryer - The function that may throw.
+ * @param catcher - The function that will be evaluated if tryer throws.
+ * @returns - The result of `try { tryer() } catch(e) { catcher(e) }`
+ *
+ * @example
+ * ```ts
+ * tryCatch(() => { throw Error('error') }) // Error('error')
+ * tryCatch(() => { throw Error('error') }, 0) // 0
+ * tryCatch(() => { throw Error('error') }, (e: Error) => e.message ) // 'error'
+ * ```
+ *
+ * @category `Logic`
+ *
+ * @beta
+ */
+const tryCatch = <R, E, P = unknown>(
+  tryer: AnyFn<any, R>,
+  catcher?: E | AnyFn<P, E>
+): R | E => {
+  try {
+    return advance(tryer)
+  } catch (e) {
+    return ifElse(
+      isFunction(catcher),
+      () => (catcher as AnyFn<P, E>)(e),
+      () => ifElse(N(isUndefined(catcher)), catcher, e)
+    )
+  }
+}
+
+export { tryCatch }

test/tryCatch.test.ts

@@ -0,0 +1,87 @@
+// Copyright 2021-present the Fonction authors. All rights reserved. MIT license.
+import { assertEquals } from '../dev_deps.ts'
+import { tryCatch } from '../src/tryCatch.ts'
+import { AnyFn } from '../src/types/index.ts'
+import { assertEqual } from './asserts.ts'
+
+Deno.test('tryCatch', () => {
+  const table: [AnyFn, unknown][] = [
+    [() => true, true],
+    [() => false, false],
+    [
+      () => {
+        throw Error('hello')
+      },
+      Error('hello')
+    ]
+  ]
+  table.forEach(([val, expected]) => {
+    assertEquals(tryCatch(val), expected, `tryCatch(${val}) -> ${expected}`)
+  })
+
+  const table2: [AnyFn, unknown | AnyFn, unknown][] = [
+    [() => true, () => false, true],
+    [() => true, false, true],
+    [
+      () => {
+        throw Error('hello')
+      },
+      false,
+      false
+    ],
+    [
+      () => {
+        throw Error('hello')
+      },
+      (e: Error) => e.message,
+      'hello'
+    ],
+    [
+      () => {
+        throw Error('hello')
+      },
+      () => 1,
+      1
+    ]
+  ]
+  table2.forEach(([tryer, catcher, expected]) => {
+    assertEquals(
+      tryCatch(tryer, catcher),
+      expected,
+      `tryCatch(${tryer}, ${catcher}) -> ${expected}`
+    )
+  })
+
+  assertEqual<unknown>(tryCatch(() => true))
+  assertEqual<true | Error>(tryCatch<true, Error>(() => true))
+  assertEqual<1 | Error>(tryCatch<1, Error>(() => 1))
+  assertEqual<unknown>(
+    tryCatch(() => {
+      throw Error('hello')
+    })
+  )
+  assertEqual<never | Error>(
+    tryCatch<never, Error>(() => {
+      throw Error('hello')
+    })
+  )
+  assertEqual<0 | 1>(tryCatch(() => 1, 0))
+  assertEqual<0 | 1>(
+    tryCatch(
+      () => 1,
+      () => 0
+    )
+  )
+  assertEqual<1 | Error>(
+    tryCatch(
+      () => 1,
+      (e: Error) => e
+    )
+  )
+  assertEqual<1 | string>(
+    tryCatch(
+      () => 1,
+      (e: Error) => e.message
+    )
+  )
+})