go-go-try 7.2.1 → 7.4.0

package/src/index.test.ts

@@ -1,14 +1,10 @@
 import { attest } from '@ark/attest'
 import { assert, describe, test } from 'vitest'
-
-// Helper for exhaustive switch checks - if this function is called,
-// it means we forgot to handle a case in a switch statement
-function assertNever(value: never): never {
-  throw new Error(`Unhandled case: ${String(value)}`)
-}
 import {
   type Result,
   type TaggedUnion,
+  assert as assertTry,
+  assertNever,
   failure,
   goTry,
   goTryAll,
@@ -19,6 +15,7 @@ import {
   isSuccess,
   success,
   taggedError,
+  UnknownError,
 } from './index.js'
 
 test(`value returned by callback is used when callback doesn't throw`, async () => {
@@ -323,8 +320,12 @@ describe('edge cases', () => {
     assert.equal(value1, undefined)
     assert.equal(value2, undefined)
     assert.equal(err1, 'custom error')
-    assert.equal(err2 instanceof CustomError, true)
-    assert.equal((err2 as CustomError).code, 500)
+    // goTryRaw now wraps errors in UnknownError by default
+    assert.equal(err2 instanceof UnknownError, true)
+    assert.equal((err2 as InstanceType<typeof UnknownError>)?._tag, 'UnknownError')
+    assert.equal(err2?.message, 'custom error')
+    // Original error is preserved in cause
+    assert.equal(((err2 as unknown as { cause?: unknown })?.cause as CustomError)?.code, 500)
   })
 
   test('throwing a string', () => {
@@ -362,6 +363,193 @@ describe('edge cases', () => {
   })
 })
 
+describe('assert helper', () => {
+  test('does not throw when condition is true', () => {
+    // Should not throw
+    assertTry(true, 'should not throw')
+    assertTry(1 > 0, new Error('should not throw'))
+    assertTry('truthy', 'should not throw')
+  })
+
+  test('throws with string message when condition is false', () => {
+    let caught = false
+    try {
+      assertTry(false, 'custom error message')
+    } catch (err) {
+      caught = true
+      assert.ok(err instanceof Error)
+      assert.equal((err as Error).message, 'custom error message')
+    }
+    assert.equal(caught, true)
+  })
+
+  test('throws with Error instance when condition is false', () => {
+    const customError = new Error('custom error instance')
+    let caught = false
+    try {
+      assertTry(false, customError)
+    } catch (err) {
+      caught = true
+      assert.equal(err, customError)
+    }
+    assert.equal(caught, true)
+  })
+
+  test('throws with tagged error when condition is false', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    let caught = false
+    try {
+      assertTry(false, new DatabaseError('database connection failed'))
+    } catch (err) {
+      caught = true
+      assert.ok(err instanceof DatabaseError)
+      assert.equal((err as InstanceType<typeof DatabaseError>)._tag, 'DatabaseError')
+      assert.equal((err as Error).message, 'database connection failed')
+    }
+    assert.equal(caught, true)
+  })
+
+  test('type narrowing works with Result types using err === undefined', () => {
+    const [err, value] = goTry(() => 'success')
+
+    // Before assert: err is string | undefined, value is string | undefined
+    attest<string | undefined>(err)
+    attest<string | undefined>(value)
+
+    // Using err === undefined provides the best type narrowing
+    assertTry(err === undefined, 'should have no error')
+
+    // TypeScript now knows err is undefined and value is string
+    attest<undefined>(err)
+    attest<string>(value)
+    assert.equal(value, 'success')
+  })
+
+  test('type narrowing works with err === undefined check', () => {
+    const [err, value] = goTryRaw(() => ({ id: 1, name: 'test' }))
+
+    // Before assert
+    attest<Error | undefined>(err)
+    attest<{ id: number; name: string } | undefined>(value)
+
+    // Using err === undefined pattern
+    assertTry(err === undefined, new Error('should have no error'))
+
+    // After assert: TypeScript knows err is undefined, value is defined
+    attest<{ id: number; name: string }>(value)
+    assert.deepEqual(value, { id: 1, name: 'test' })
+  })
+
+  test('type narrowing works with tagged errors', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), { errorClass: DatabaseError })
+
+    // Before assert
+    attest<InstanceType<typeof DatabaseError> | undefined>(err)
+    attest<{ id: string; name: string } | undefined>(user)
+
+    // Use assert with tagged error
+    assertTry(err === undefined, new DatabaseError('Failed to fetch user'))
+
+    // After assert: TypeScript knows err is undefined, user is defined
+    attest<{ id: string; name: string }>(user)
+    assert.deepEqual(user, { id: '123', name: 'John' })
+  })
+
+  test('reduces boilerplate compared to if(err) throw', () => {
+    const DatabaseError = taggedError('DatabaseError')
+
+    function fetchUserOldStyle(): Result<InstanceType<typeof DatabaseError>, { id: string }> {
+      const [err, user] = goTryRaw(() => ({ id: '123' }), { errorClass: DatabaseError })
+      if (err) return failure(err)  // Old style
+      return [undefined, user] as const
+    }
+
+    function fetchUserNewStyle(): Result<InstanceType<typeof DatabaseError>, { id: string }> {
+      const [err, user] = goTryRaw(() => ({ id: '123' }), { errorClass: DatabaseError })
+      assertTry(err === undefined, new DatabaseError('Failed to fetch user'))
+      // TypeScript now knows user is defined
+      return [undefined, user] as const
+    }
+
+    const [err1, user1] = fetchUserOldStyle()
+    const [err2, user2] = fetchUserNewStyle()
+
+    assert.equal(err1, undefined)
+    assert.equal(err2, undefined)
+    assert.deepEqual(user1, { id: '123' })
+    assert.deepEqual(user2, { id: '123' })
+  })
+
+  test('works with falsy values as condition', () => {
+    // 0 is falsy - should throw
+    assert.throws(() => assertTry(0, 'zero is falsy'))
+
+    // empty string is falsy - should throw
+    assert.throws(() => assertTry('', 'empty string is falsy'))
+
+    // null is falsy - should throw
+    assert.throws(() => assertTry(null, 'null is falsy'))
+
+    // undefined is falsy - should throw
+    assert.throws(() => assertTry(undefined, 'undefined is falsy'))
+
+    // NaN is falsy - should throw
+    assert.throws(() => assertTry(Number.NaN, 'NaN is falsy'))
+  })
+
+  test('works with truthy values as condition', () => {
+    // non-zero number is truthy
+    assertTry(1, new Error('one is truthy'))
+
+    // non-empty string is truthy
+    assertTry('hello', new Error('string is truthy'))
+
+    // object is truthy
+    assertTry({}, new Error('object is truthy'))
+
+    // array is truthy
+    assertTry([], new Error('array is truthy'))
+
+    // true is truthy
+    assertTry(true, new Error('true is truthy'))
+  })
+
+  test('works with ErrorClass and message (shorter syntax)', () => {
+    const ValidationError = taggedError('ValidationError')
+
+    // Should not throw when condition is true
+    assertTry(5 > 0, ValidationError, 'Value must be positive')
+
+    // Should throw with instantiated error when condition is false
+    try {
+      assertTry(-1 > 0, ValidationError, 'Value must be positive')
+      assert.equal(true, false) // Should not reach here
+    } catch (err) {
+      assert.ok(err instanceof ValidationError)
+      assert.equal((err as InstanceType<typeof ValidationError>)._tag, 'ValidationError')
+      assert.equal((err as Error).message, 'Value must be positive')
+    }
+  })
+
+  test('shorter syntax with tagged errors provides type narrowing', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), { errorClass: DatabaseError })
+
+    // Before assert
+    attest<InstanceType<typeof DatabaseError> | undefined>(err)
+    attest<{ id: string; name: string } | undefined>(user)
+
+    // Use assert with shorter syntax
+    assertTry(err === undefined, DatabaseError, 'Failed to fetch user')
+
+    // After assert: TypeScript knows err is undefined, user is defined
+    attest<undefined>(err)
+    attest<{ id: string; name: string }>(user)
+    assert.deepEqual(user, { id: '123', name: 'John' })
+  })
+})
+
 describe('goTry type tests', () => {
   test('synchronous function returns correct types', () => {
     const fn = () => 'value'
@@ -1007,8 +1195,8 @@ describe('taggedError', () => {
     }
 
     // Wrap in functions so goTryRaw can catch the errors
-    const [dbErr, dbResult] = goTryRaw(fetchFromDb, DatabaseError)
-    const [netErr, netResult] = goTryRaw(fetchFromNetwork, NetworkError)
+    const [dbErr, dbResult] = goTryRaw(fetchFromDb, { errorClass: DatabaseError })
+    const [netErr, netResult] = goTryRaw(fetchFromNetwork, { errorClass: NetworkError })
 
     // Type narrowing via discriminated union
     if (dbErr) {
@@ -1034,14 +1222,14 @@ describe('taggedError', () => {
     async function fetchUser(id: string): Promise<Result<AppError, { id: string; name: string }>> {
       const [dbErr, user] = await goTryRaw(
         Promise.resolve({ id, name: 'John' }),
-        DatabaseError,
+        { errorClass: DatabaseError },
       )
       if (dbErr) return failure<AppError>(dbErr)
       return [undefined, user] as const
     }
 
     async function fetchData(): Promise<Result<AppError, string>> {
-      const [netErr, data] = await goTryRaw(Promise.resolve('data'), NetworkError)
+      const [netErr, data] = await goTryRaw(Promise.resolve('data'), { errorClass: NetworkError })
       if (netErr) return failure<AppError>(netErr)
       return [undefined, data] as const
     }
@@ -1079,7 +1267,7 @@ describe('taggedError', () => {
         case 'ValidationError':
           return `VAL: ${err.message}`
         default:
-          return `UNK: ${err.message}`
+          return assertNever(err)
       }
     }
 
@@ -1176,7 +1364,7 @@ describe('TaggedUnion type helper', () => {
         case 'ValidationError':
           return `VAL: ${err.message}`
         default:
-          return `UNK: ${err.message}`
+          return assertNever(err)
       }
     }
 
@@ -1194,7 +1382,7 @@ describe('TaggedUnion type helper', () => {
     async function fetchData(): Promise<Result<AppError, string>> {
       const [err, data] = await goTryRaw(
         Promise.reject(new Error('timeout')),
-        NetworkError,
+        { errorClass: NetworkError },
       )
       if (err) return failure<AppError>(err)
       return [undefined, data] as const
@@ -1218,14 +1406,14 @@ describe('inferred return types with tagged errors', () => {
       // First operation might fail with DatabaseError
       const [dbErr, user] = await goTryRaw(
         Promise.resolve({ id, name: 'John' }),
-        DatabaseError,
+        { errorClass: DatabaseError },
       )
       if (dbErr) return failure(dbErr)
 
       // Second operation might fail with NetworkError
       const [netErr, enriched] = await goTryRaw(
         Promise.resolve({ ...user!, email: 'john@example.com' }),
-        NetworkError,
+        { errorClass: NetworkError },
       )
       if (netErr) return failure(netErr)
 
@@ -1263,14 +1451,14 @@ describe('inferred return types with tagged errors', () => {
     // No explicit return type annotation
     function processConfig(input: string) {
       // Parse step
-      const [parseErr, parsed] = goTryRaw(() => JSON.parse(input), ParseError)
+      const [parseErr, parsed] = goTryRaw(() => JSON.parse(input), { errorClass: ParseError })
       if (parseErr) return failure(parseErr)
 
       // Validate step
       const [validateErr, validated] = goTryRaw(() => {
         if (!parsed!.port) throw new Error('Missing port')
         return parsed as { port: number }
-      }, ValidateError)
+      }, { errorClass: ValidateError })
       if (validateErr) return failure(validateErr)
 
       return [undefined, validated] as const
@@ -1301,19 +1489,19 @@ describe('inferred return types with tagged errors', () => {
     async function complexOperation(shouldFail: 'a' | 'b' | 'c' | 'none') {
       const [errA, valA] = await goTryRaw(
         shouldFail === 'a' ? Promise.reject(new Error('a')) : Promise.resolve('step1'),
-        ErrorA,
+        { errorClass: ErrorA },
       )
       if (errA) return failure(errA)
 
       const [errB, valB] = await goTryRaw(
         shouldFail === 'b' ? Promise.reject(new Error('b')) : Promise.resolve('step2'),
-        ErrorB,
+        { errorClass: ErrorB },
       )
       if (errB) return failure(errB)
 
       const [errC, valC] = await goTryRaw(
         shouldFail === 'c' ? Promise.reject(new Error('c')) : Promise.resolve('step3'),
-        ErrorC,
+        { errorClass: ErrorC },
       )
       if (errC) return failure(errC)
 
@@ -1350,3 +1538,204 @@ describe('inferred return types with tagged errors', () => {
     )
   })
 })
+
+
+describe('UnknownError', () => {
+  test('UnknownError is exported as a tagged error class', () => {
+    const err = new UnknownError('something went wrong')
+    assert.equal(err._tag, 'UnknownError')
+    assert.equal(err.message, 'something went wrong')
+    assert.equal(err.name, 'UnknownError')
+    assert.ok(err instanceof Error)
+    assert.ok(err instanceof UnknownError)
+  })
+
+  test('UnknownError supports cause option', () => {
+    const cause = new Error('original error')
+    const err = new UnknownError('wrapped error', { cause })
+    assert.equal(err.cause, cause)
+  })
+
+  test('goTryRaw defaults to UnknownError for system errors', () => {
+    const fn = () => {
+      throw new Error('system error')
+    }
+
+    const [err, value] = goTryRaw(fn)
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof UnknownError)
+    assert.equal(err._tag, 'UnknownError')
+    assert.equal(err.message, 'system error')
+  })
+
+  test('goTryRaw defaults to UnknownError for thrown strings', () => {
+    const fn = () => {
+      throw 'string error'
+    }
+
+    const [err, value] = goTryRaw(fn)
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof UnknownError)
+    assert.equal(err._tag, 'UnknownError')
+    assert.equal(err.message, 'string error')
+  })
+
+  test('goTryRaw defaults to UnknownError for thrown undefined', () => {
+    const fn = () => {
+      throw undefined
+    }
+
+    const [err, value] = goTryRaw(fn)
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof UnknownError)
+    assert.equal(err._tag, 'UnknownError')
+    assert.equal(err.message, 'undefined')
+  })
+
+  test('goTryRaw with async defaults to UnknownError', async () => {
+    const promise = Promise.reject(new Error('async error'))
+
+    const [err, value] = await goTryRaw(promise)
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof UnknownError)
+    assert.equal(err._tag, 'UnknownError')
+    assert.equal(err.message, 'async error')
+  })
+})
+
+describe('goTryRaw with options object', () => {
+  test('errorClass wraps all errors including tagged ones', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const NetworkError = taggedError('NetworkError')
+
+    // When a DatabaseError is thrown, it gets wrapped in NetworkError
+    const fn = () => {
+      throw new DatabaseError('db connection failed')
+    }
+
+    const [err, value] = goTryRaw(fn, { errorClass: NetworkError })
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof NetworkError)
+    assert.equal(err._tag, 'NetworkError')
+    assert.equal(err.message, 'db connection failed')
+    // Original error is preserved in cause
+    assert.ok(err.cause instanceof DatabaseError)
+  })
+
+  test('errorClass wraps non-tagged errors', () => {
+    const NetworkError = taggedError('NetworkError')
+
+    const fn = () => {
+      throw new Error('plain error')
+    }
+
+    const [err, value] = goTryRaw(fn, { errorClass: NetworkError })
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof NetworkError)
+    assert.equal(err._tag, 'NetworkError')
+    assert.equal(err.message, 'plain error')
+  })
+
+  test('systemErrorClass only wraps non-tagged errors', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const SystemError = taggedError('SystemError')
+
+    // Tagged errors should pass through
+    const fnTagged = () => {
+      throw new DatabaseError('db error')
+    }
+
+    const [err1, value1] = goTryRaw(fnTagged, { systemErrorClass: SystemError })
+
+    assert.equal(value1, undefined)
+    assert.ok(err1 instanceof DatabaseError)
+    assert.equal(err1._tag, 'DatabaseError')
+
+    // Non-tagged errors should be wrapped
+    const fnPlain = () => {
+      throw new Error('system error')
+    }
+
+    const [err2, value2] = goTryRaw(fnPlain, { systemErrorClass: SystemError })
+
+    assert.equal(value2, undefined)
+    assert.ok(err2 instanceof SystemError)
+    assert.equal(err2._tag, 'SystemError')
+    assert.equal(err2.message, 'system error')
+  })
+
+  test('systemErrorClass defaults to UnknownError when not specified', () => {
+    const fn = () => {
+      throw new Error('plain error')
+    }
+
+    const [err, value] = goTryRaw(fn, {})
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof UnknownError)
+    assert.equal(err._tag, 'UnknownError')
+  })
+
+  test('async with options object', async () => {
+    const DatabaseError = taggedError('DatabaseError')
+
+    const promise = Promise.reject(new Error('async error'))
+
+    const [err, value] = await goTryRaw(promise, { errorClass: DatabaseError })
+
+    assert.equal(value, undefined)
+    assert.ok(err instanceof DatabaseError)
+    assert.equal(err._tag, 'DatabaseError')
+  })
+
+})
+
+describe('goTryRaw options type tests', () => {
+  test('systemErrorClass preserves tagged errors', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const SystemError = taggedError('SystemError')
+
+    // Wrap in a function so goTryRaw can catch the error
+    const [err, _value] = goTryRaw(() => {
+      throw new DatabaseError('db error')
+    }, { systemErrorClass: SystemError })
+
+    // Type is systemErrorClass since TypeScript cannot know which tagged errors
+    // might be thrown at runtime (tagged errors pass through, others get wrapped)
+    attest<InstanceType<typeof SystemError> | undefined>(err)
+
+    // But at runtime, tagged errors are preserved
+    if (err) {
+      assert.equal(err._tag, 'DatabaseError')
+    }
+  })
+
+  test('errorClass wraps all errors to specified type', () => {
+    const DatabaseError = taggedError('DatabaseError')
+
+    const [err, value] = goTryRaw(() => 'test', { errorClass: DatabaseError })
+
+    attest<InstanceType<typeof DatabaseError> | undefined>(err)
+    attest<string | undefined>(value)
+  })
+
+  test('no options defaults to Error type (backward compatible)', () => {
+    const [err, value] = goTryRaw(() => 'test')
+
+    attest<Error | undefined>(err)
+    attest<string | undefined>(value)
+  })
+
+  test('empty options object defaults to UnknownError type', () => {
+    const [err, value] = goTryRaw(() => 'test', {})
+
+    attest<InstanceType<typeof UnknownError> | undefined>(err)
+    attest<string | undefined>(value)
+  })
+})