go-go-try 7.3.0 → 7.4.1

package/src/index.test.ts

@@ -15,6 +15,7 @@ import {
   isSuccess,
   success,
   taggedError,
+  UnknownError,
 } from './index.js'
 
 test(`value returned by callback is used when callback doesn't throw`, async () => {
@@ -319,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', () => {
@@ -367,38 +372,41 @@ describe('assert helper', () => {
   })
 
   test('throws with string message when condition is false', () => {
+    let caught = false
     try {
       assertTry(false, 'custom error message')
-      // Should not reach here
-      assert.equal(true, false)
     } 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)
-      // Should not reach here
-      assert.equal(true, false)
     } 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'))
-      // Should not reach here
-      assert.equal(true, false)
     } 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', () => {
@@ -434,7 +442,7 @@ describe('assert helper', () => {
 
   test('type narrowing works with tagged errors', () => {
     const DatabaseError = taggedError('DatabaseError')
-    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), DatabaseError)
+    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), { errorClass: DatabaseError })
 
     // Before assert
     attest<InstanceType<typeof DatabaseError> | undefined>(err)
@@ -452,13 +460,13 @@ describe('assert helper', () => {
     const DatabaseError = taggedError('DatabaseError')
 
     function fetchUserOldStyle(): Result<InstanceType<typeof DatabaseError>, { id: string }> {
-      const [err, user] = goTryRaw(() => ({ id: '123' }), DatabaseError)
+      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' }), DatabaseError)
+      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
@@ -526,7 +534,7 @@ describe('assert helper', () => {
 
   test('shorter syntax with tagged errors provides type narrowing', () => {
     const DatabaseError = taggedError('DatabaseError')
-    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), DatabaseError)
+    const [err, user] = goTryRaw(() => ({ id: '123', name: 'John' }), { errorClass: DatabaseError })
 
     // Before assert
     attest<InstanceType<typeof DatabaseError> | undefined>(err)
@@ -1099,7 +1107,7 @@ describe('goTryAllRaw', () => {
     assert.deepEqual(results, ['a', 42, true])
   })
 
-  test('returns Error objects for failed promises', async () => {
+  test('wraps non-tagged errors in UnknownError', async () => {
     const [errors, results] = await goTryAllRaw([
       Promise.resolve('success'),
       Promise.reject(new Error('fail1')),
@@ -1107,6 +1115,8 @@ describe('goTryAllRaw', () => {
     ])
 
     assert.equal(errors[0], undefined)
+    assert.ok(errors[1] instanceof UnknownError)
+    assert.equal(errors[1]?._tag, 'UnknownError')
     assert.equal(errors[1]?.message, 'fail1')
     assert.equal(errors[2], undefined)
 
@@ -1115,15 +1125,44 @@ describe('goTryAllRaw', () => {
     assert.equal(results[2], 42)
   })
 
-  test('converts non-Error rejections to Error objects', async () => {
+  test('tagged errors pass through unchanged', async () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const NetworkError = taggedError('NetworkError')
+
+    const [errors] = await goTryAllRaw([
+      Promise.reject(new DatabaseError('db failed')),
+      Promise.reject(new NetworkError('network timeout')),
+      Promise.reject(new Error('plain error')),
+    ])
+
+    // Tagged errors pass through
+    assert.ok(errors[0] instanceof DatabaseError)
+    assert.equal(errors[0]?._tag, 'DatabaseError')
+    assert.equal(errors[0]?.message, 'db failed')
+    assert.ok(errors[1] instanceof NetworkError)
+    assert.equal(errors[1]?._tag, 'NetworkError')
+    assert.equal(errors[1]?.message, 'network timeout')
+    // Non-tagged errors get wrapped in UnknownError
+    assert.ok(errors[2] instanceof UnknownError)
+    assert.equal(errors[2]?._tag, 'UnknownError')
+    assert.equal(errors[2]?.message, 'plain error')
+  })
+
+  test('converts non-Error rejections to UnknownError objects', async () => {
     const [errors] = await goTryAllRaw([
       Promise.reject('string error'),
       Promise.reject(42),
       Promise.reject(undefined),
     ])
 
+    assert.ok(errors[0] instanceof UnknownError)
+    assert.equal(errors[0]?._tag, 'UnknownError')
     assert.equal(errors[0]?.message, 'string error')
+    assert.ok(errors[1] instanceof UnknownError)
+    assert.equal(errors[1]?._tag, 'UnknownError')
     assert.equal(errors[1]?.message, '42')
+    assert.ok(errors[2] instanceof UnknownError)
+    assert.equal(errors[2]?._tag, 'UnknownError')
     assert.equal(errors[2]?.message, 'undefined')
   })
 
@@ -1133,6 +1172,60 @@ describe('goTryAllRaw', () => {
     assert.deepEqual(errors, [])
     assert.deepEqual(results, [])
   })
+
+  test('errorClass wraps all errors', async () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const NetworkError = taggedError('NetworkError')
+
+    const [errors] = await goTryAllRaw([
+      Promise.reject(new DatabaseError('db error')),
+      Promise.reject(new NetworkError('network error')),
+      Promise.reject(new Error('plain error')),
+    ], { errorClass: DatabaseError })
+
+    // All errors should be wrapped in DatabaseError
+    assert.ok(errors[0] instanceof DatabaseError)
+    assert.equal(errors[0]?._tag, 'DatabaseError')
+    assert.ok(errors[1] instanceof DatabaseError)
+    assert.equal(errors[1]?._tag, 'DatabaseError')
+    assert.ok(errors[2] instanceof DatabaseError)
+    assert.equal(errors[2]?._tag, 'DatabaseError')
+  })
+
+  test('systemErrorClass only wraps non-tagged errors', async () => {
+    const DatabaseError = taggedError('DatabaseError')
+    const NetworkError = taggedError('NetworkError')
+    const SystemError = taggedError('SystemError')
+
+    const [errors] = await goTryAllRaw([
+      Promise.reject(new DatabaseError('db error')),
+      Promise.reject(new NetworkError('network error')),
+      Promise.reject(new Error('plain error')),
+    ], { systemErrorClass: SystemError })
+
+    // Tagged errors pass through
+    assert.ok(errors[0] instanceof DatabaseError)
+    assert.equal(errors[0]?._tag, 'DatabaseError')
+    assert.ok(errors[1] instanceof NetworkError)
+    assert.equal(errors[1]?._tag, 'NetworkError')
+    // Non-tagged error wrapped in SystemError
+    assert.ok(errors[2] instanceof SystemError)
+    assert.equal(errors[2]?._tag, 'SystemError')
+  })
+
+  test('concurrency option works with errorClass', async () => {
+    const DatabaseError = taggedError('DatabaseError')
+
+    const [errors] = await goTryAllRaw([
+      Promise.reject(new Error('error 1')),
+      Promise.reject(new Error('error 2')),
+      Promise.reject(new Error('error 3')),
+    ], { concurrency: 2, errorClass: DatabaseError })
+
+    assert.ok(errors[0] instanceof DatabaseError)
+    assert.ok(errors[1] instanceof DatabaseError)
+    assert.ok(errors[2] instanceof DatabaseError)
+  })
 })
 
 
@@ -1187,8 +1280,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) {
@@ -1214,14 +1307,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
     }
@@ -1374,7 +1467,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
@@ -1398,14 +1491,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)
 
@@ -1443,14 +1536,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
@@ -1481,19 +1574,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)
 
@@ -1530,3 +1623,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)
+  })
+})

package/src/index.ts

@@ -9,6 +9,8 @@ export type {
   GoTryAllOptions,
   ErrorConstructor,
   TaggedUnion,
+  GoTryRawOptions,
+  GoTryAllRawOptions,
 } from './types.js'
 
 // Export core functions
@@ -21,3 +23,6 @@ export { goTryAll, goTryAllRaw } from './goTryAll.js'
 export { taggedError } from './tagged-error.js'
 export { assert } from './assert.js'
 export { isSuccess, isFailure, success, failure, assertNever } from './result-helpers.js'
+
+// Export UnknownError tagged error
+export { UnknownError } from './unknown-error.js'

package/src/types.ts

@@ -33,6 +33,30 @@ export interface GoTryAllOptions {
  */
 export type ErrorConstructor<E> = new (message: string, options?: { cause?: unknown }) => E
 
+/**
+ * Checks if a value is a tagged error (has a _tag property).
+ */
+export type IsTaggedError<T> = T extends { _tag: string } ? true : false
+
+/**
+ * Options for goTryRaw function.
+ * errorClass and systemErrorClass are mutually exclusive - you can only provide one.
+ */
+export type GoTryRawOptions<E = Error> =
+  | { errorClass: ErrorConstructor<E>; systemErrorClass?: never }
+  | { errorClass?: never; systemErrorClass: ErrorConstructor<E> }
+  | { errorClass?: never; systemErrorClass?: never }
+
+/**
+ * Options for goTryAllRaw function.
+ * Includes concurrency control and error class options.
+ * errorClass and systemErrorClass are mutually exclusive.
+ */
+export type GoTryAllRawOptions<E = Error> =
+  | { concurrency?: number; errorClass: ErrorConstructor<E>; systemErrorClass?: never }
+  | { concurrency?: number; errorClass?: never; systemErrorClass: ErrorConstructor<E> }
+  | { concurrency?: number; errorClass?: never; systemErrorClass?: never }
+
 /**
  * Creates a union type from multiple tagged error classes.
  *

package/src/unknown-error.ts

@@ -0,0 +1,20 @@
+import { taggedError } from './tagged-error.js'
+
+/**
+ * Default system error class for errors that aren't already wrapped in a tagged error class.
+ *
+ * @example
+ * // By default, goTryRaw wraps unknown errors in UnknownError
+ * const [err, result] = goTryRaw(() => mightThrow())
+ * if (err) {
+ *   console.log(err._tag) // 'UnknownError'
+ * }
+ *
+ * @example
+ * // Use a custom system error class
+ * const SystemError = taggedError('SystemError')
+ * const [err, result] = goTryRaw(() => mightThrow(), {
+ *   systemErrorClass: SystemError
+ * })
+ */
+export const UnknownError = taggedError('UnknownError')