Merge pull request #4 from giraugh/feat/attempt-error-utils

Utils for attempting ops and catching errors

.changeset/warm-toes-try.md

@@ -0,0 +1,5 @@
+---
+"@giraugh/tools": minor
+---
+
+Add utilities for attempting operations and catching errors

lib/errors/attemptOrCatch.ts

@@ -0,0 +1,32 @@
+/**
+ * Attempt to call a function returning either the result or an error if one occurs
+ * @param f the function to call
+ * @returns either the result of f or an error
+ * 
+ * @example
+ * attemptOrCatch(() => { throw new Error() }) // returns error
+ * @example
+ * attemptOrCatch(() => 'hello') === 'hello'
+ */
+export const attemptOrCatch = <TErr extends Error, TReturn>(f: () => TReturn): TErr | TReturn => {
+  try {
+    return f()
+  } catch (err) {
+    return err as TErr
+  }
+}
+
+
+// Tests
+if (import.meta.vitest) {
+  const { it, expect } = import.meta.vitest
+
+  it('works for example 1', () => {
+    const err = new Error()
+    expect(attemptOrCatch(() => { throw err })).toBe(err)
+  })
+
+  it('works for example 2', () => {
+    expect(attemptOrCatch(() => 'hello')).toBe('hello')
+  })
+}

lib/errors/attemptOrElse.ts

@@ -0,0 +1,36 @@
+/**
+ * Attempt to call a function or call a handler if an error occurs.
+ * @param fnRes the function to call
+ * @param fnErr the handler to call if an error occurs
+ * @returns the result of fnRes if succesfull or the result of fnErr
+ * @note the type of the return is always the same regardless of if an error occurs
+ * 
+ * @example
+ * attemptOrElse(() => { throw new Error() }, (err) => 'oh no') // returns 'oh no'
+ * @example
+ * attemptOrElse(() => 'hello', (err) => 'oh no') === 'hello'
+ * @example
+ * const isDebugEnv = attemptOrElse(() => process.env.NODE_ENV === 'debug', () => false)
+ */
+export const attemptOrElse = <TReturn, TError extends Error>(fnRes: () => TReturn, fnErr: (err: TError) => TReturn): TReturn => {
+  try {
+    return fnRes()
+  } catch (err) {
+    return fnErr(err as TError)
+  }
+}
+
+
+// Tests
+if (import.meta.vitest) {
+  const { it, expect } = import.meta.vitest
+
+  it('works for example 1', () => {
+    const err = new Error()
+    expect(attemptOrElse(() => { throw err }, () => 'oh no')).toEqual('oh no')
+  })
+
+  it('works for example 2', () => {
+    expect(attemptOrElse(() => 'hello', () => 'oh no')).toEqual('hello')
+  })
+}

lib/errors/index.ts

@@ -1 +1,3 @@
 export * from './expectOrThrow'
+export * from './attemptOrCatch'
+export * from './attemptOrElse'