go-go-try 7.2.0 → 7.3.0

package/src/goTry.ts

@@ -0,0 +1,45 @@
+import type { Result } from './types.js'
+import { success, failure } from './result-helpers.js'
+import { isPromise, getErrorMessage } from './internals.js'
+
+/**
+ * Executes a function, promise, or value and returns a Result type.
+ * If an error occurs, it returns a Failure with the error message as a string.
+ *
+ * @template T The type of the successful result
+ * @param {T | Promise<T> | (() => T | Promise<T>)} value - The value, promise, or function to execute
+ * @returns {Result<string, T> | Promise<Result<string, T>>} A Result type or a Promise of a Result type
+ *
+ * @example
+ * // With a value
+ * const [err, result] = goTry(42);
+ *
+ * @example
+ * // With a function
+ * const [err, result] = goTry(() => JSON.parse('{"key": "value"}'));
+ *
+ * @example
+ * // With a promise
+ * const [err, result] = await goTry(fetch('https://api.example.com/data'));
+ */
+export function goTry<T>(fn: () => never): Result<string, never>
+export function goTry<T>(fn: () => Promise<T>): Promise<Result<string, T>>
+export function goTry<T>(promise: Promise<T>): Promise<Result<string, T>>
+export function goTry<T>(fn: () => T): Result<string, T>
+export function goTry<T>(value: T): Result<string, T>
+export function goTry<T>(
+  value: T | Promise<T> | (() => T | Promise<T>),
+): Result<string, T> | Promise<Result<string, T>> {
+  try {
+    const result =
+      typeof value === 'function' ? (value as () => T | Promise<T>)() : value
+    if (isPromise<T>(result)) {
+      return result
+        .then((resolvedValue) => success<T>(resolvedValue))
+        .catch((err) => failure<string>(getErrorMessage(err)))
+    }
+    return success<T>(result)
+  } catch (err) {
+    return failure<string>(getErrorMessage(err))
+  }
+}

package/src/goTryAll.ts

@@ -0,0 +1,141 @@
+import type { GoTryAllOptions } from './types.js'
+import { isError, getErrorMessage, type PromiseFactory } from './internals.js'
+
+async function runWithConcurrency<T extends readonly unknown[]>(
+  items: { [K in keyof T]: Promise<T[K]> | PromiseFactory<T[K]> },
+  concurrency: number,
+): Promise<PromiseSettledResult<T[number]>[]> {
+  if (items.length === 0) {
+    return []
+  }
+
+  // Auto-detect factory mode by checking if first item is a function
+  const isFactoryMode = typeof items[0] === 'function'
+
+  // concurrency of 0 means unlimited (run all in parallel)
+  if (!isFactoryMode && (concurrency <= 0)) {
+    return Promise.allSettled(items as Promise<T[number]>[])
+  }
+
+  const results: PromiseSettledResult<T[number]>[] = new Array(items.length)
+  let index = 0
+
+  async function worker(): Promise<void> {
+    while (index < items.length) {
+      const currentIndex = index++
+      try {
+        const item = items[currentIndex]
+        // If factory mode, call the function; otherwise await the promise directly
+        const value = isFactoryMode
+          ? await (item as PromiseFactory<T[number]>)()
+          : await (item as Promise<T[number]>)
+        results[currentIndex] = { status: 'fulfilled', value }
+      } catch (reason) {
+        results[currentIndex] = { status: 'rejected', reason }
+      }
+    }
+  }
+
+  // Determine number of workers
+  const workerCount = concurrency <= 0 ? items.length : Math.min(concurrency, items.length)
+
+  // Start workers
+  const workers: Promise<void>[] = []
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(worker())
+  }
+
+  await Promise.all(workers)
+  return results
+}
+
+/**
+ * Executes multiple promises or factory functions in parallel (or with limited concurrency)
+ * and returns a tuple of [errors, results]. Unlike Promise.all, this doesn't fail fast -
+ * it waits for all promises to settle.
+ *
+ * Accepts either:
+ * - An array of promises (for simple parallel execution)
+ * - An array of factory functions that return promises (for lazy execution with concurrency control)
+ *
+ * @template T The tuple type of all promise results
+ * @param {readonly [...{ [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) }]} items - Array of promises or factories
+ * @param {GoTryAllOptions} options - Optional configuration
+ * @returns {Promise<[{ [K in keyof T]: string | undefined }, { [K in keyof T]: T[K] | undefined }]>}
+ *          A tuple where the first element is a tuple of errors (or undefined) and
+ *          the second element is a tuple of results (or undefined), preserving input order
+ *
+ * @example
+ * // Run all in parallel (default) - with promises
+ * const [errors, results] = await goTryAll([
+ *   fetchUser(1),
+ *   fetchUser(2),
+ *   fetchUser(3)
+ * ])
+ *
+ * @example
+ * // Limit concurrency with factory functions (lazy execution)
+ * const [errors, results] = await goTryAll([
+ *   () => fetchUser(1),  // Only called when a slot is available
+ *   () => fetchUser(2),  // Only called when a slot is available
+ *   () => fetchUser(3),  // Only called when a slot is available
+ * ], { concurrency: 2 })
+ */
+export async function goTryAll<T extends readonly unknown[]>(
+  items: { [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) },
+  options?: GoTryAllOptions,
+): Promise<[{ [K in keyof T]: string | undefined }, { [K in keyof T]: T[K] | undefined }]> {
+  const settled = await runWithConcurrency(items, options?.concurrency ?? 0)
+
+  const errors = [] as { [K in keyof T]: string | undefined }
+  const results = [] as { [K in keyof T]: T[K] | undefined }
+
+  for (let i = 0; i < settled.length; i++) {
+    const item = settled[i]!
+    if (item.status === 'fulfilled') {
+      ;(errors as (string | undefined)[])[i] = undefined
+      ;(results as unknown[])[i] = (item as PromiseFulfilledResult<T[number]>).value
+    } else {
+      ;(errors as (string | undefined)[])[i] = getErrorMessage((item as PromiseRejectedResult).reason)
+      ;(results as unknown[])[i] = undefined
+    }
+  }
+
+  return [errors, results]
+}
+
+/**
+ * Like `goTryAll`, but returns raw Error objects instead of error messages.
+ *
+ * @template T The tuple type of all promise results
+ * @param {readonly [...{ [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) }]} items - Array of promises or factories
+ * @param {GoTryAllOptions} options - Optional configuration
+ * @returns {Promise<[{ [K in keyof T]: Error | undefined }, { [K in keyof T]: T[K] | undefined }]>}
+ *          A tuple where the first element is a tuple of Error objects (or undefined) and
+ *          the second element is a tuple of results (or undefined), preserving input order
+ */
+export async function goTryAllRaw<T extends readonly unknown[]>(
+  items: { [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) },
+  options?: GoTryAllOptions,
+): Promise<[{ [K in keyof T]: Error | undefined }, { [K in keyof T]: T[K] | undefined }]> {
+  const settled = await runWithConcurrency(items, options?.concurrency ?? 0)
+
+  const errors = [] as { [K in keyof T]: Error | undefined }
+  const results = [] as { [K in keyof T]: T[K] | undefined }
+
+  for (let i = 0; i < settled.length; i++) {
+    const item = settled[i]!
+    if (item.status === 'fulfilled') {
+      ;(errors as (Error | undefined)[])[i] = undefined
+      ;(results as unknown[])[i] = (item as PromiseFulfilledResult<T[number]>).value
+    } else {
+      const reason = (item as PromiseRejectedResult).reason
+      ;(errors as (Error | undefined)[])[i] = isError(reason)
+        ? reason
+        : new Error(String(reason))
+      ;(results as unknown[])[i] = undefined
+    }
+  }
+
+  return [errors, results]
+}

package/src/goTryOr.ts

@@ -0,0 +1,55 @@
+import type { ResultWithDefault } from './types.js'
+import { success } from './result-helpers.js'
+import { isPromise, getErrorMessage, resolveDefault } from './internals.js'
+
+/**
+ * Executes a function, promise, or value and returns a Result type with a fallback default.
+ * If an error occurs, it returns the error message and the default value.
+ *
+ * @template T The type of the successful result
+ * @param {T | Promise<T> | (() => T | Promise<T>)} value - The value, promise, or function to execute
+ * @param {T | (() => T)} defaultValue - The default value or a function to compute it (only called on failure)
+ * @returns {ResultWithDefault<string, T> | Promise<ResultWithDefault<string, T>>} A tuple of [error, value] or Promise thereof
+ *
+ * @example
+ * // With a static default
+ * const [err, config] = goTryOr(() => JSON.parse('invalid'), { port: 3000 })
+ * // err is the error message, config is { port: 3000 }
+ *
+ * @example
+ * // With a computed default (lazy evaluation)
+ * const [err, user] = await goTryOr(fetchUser(id), () => ({
+ *   id: 'anonymous',
+ *   name: 'Guest'
+ * }))
+ */
+export function goTryOr<T>(fn: () => never, defaultValue: T | (() => T)): ResultWithDefault<string, T>
+export function goTryOr<T>(
+  fn: () => Promise<T>,
+  defaultValue: T | (() => T),
+): Promise<ResultWithDefault<string, T>>
+export function goTryOr<T>(
+  promise: Promise<T>,
+  defaultValue: T | (() => T),
+): Promise<ResultWithDefault<string, T>>
+export function goTryOr<T>(fn: () => T, defaultValue: T | (() => T)): ResultWithDefault<string, T>
+export function goTryOr<T>(value: T, defaultValue: T | (() => T)): ResultWithDefault<string, T>
+export function goTryOr<T>(
+  value: T | Promise<T> | (() => T | Promise<T>),
+  defaultValue: T | (() => T),
+): ResultWithDefault<string, T> | Promise<ResultWithDefault<string, T>> {
+  try {
+    const result =
+      typeof value === 'function' ? (value as () => T | Promise<T>)() : value
+
+    if (isPromise<T>(result)) {
+      return result
+        .then((resolvedValue) => success<T>(resolvedValue))
+        .catch((err) => [getErrorMessage(err), resolveDefault(defaultValue)] as const)
+    }
+
+    return success<T>(result)
+  } catch (err) {
+    return [getErrorMessage(err), resolveDefault(defaultValue)] as const
+  }
+}

package/src/goTryRaw.ts

@@ -0,0 +1,89 @@
+import type { Result, ErrorConstructor } from './types.js'
+import { success, failure } from './result-helpers.js'
+import { isPromise, isError } from './internals.js'
+
+/**
+ * Executes a function, promise, or value and returns a Result type.
+ * If an error occurs, it returns a Failure with the raw error object.
+ *
+ * @template T The type of the successful result
+ * @template E The type of the error, defaults to Error
+ * @param {T | Promise<T> | (() => T | Promise<T>)} value - The value, promise, or function to execute
+ * @param {ErrorConstructor<E>} [ErrorClass] - Optional error constructor to wrap caught errors
+ * @returns {Result<E, T> | Promise<Result<E, T>>} A Result type or a Promise of a Result type
+ *
+ * @example
+ * // With a value
+ * const [err, result] = goTryRaw(42);
+ *
+ * @example
+ * // With a function
+ * const [err, result] = goTryRaw(() => JSON.parse('{"key": "value"}'));
+ *
+ * @example
+ * // With a promise
+ * const [err, result] = await goTryRaw(fetch('https://api.example.com/data'));
+ *
+ * @example
+ * // With tagged error for discriminated unions
+ * const DatabaseError = taggedError('DatabaseError');
+ * const [err, result] = await goTryRaw(fetchData(), DatabaseError);
+ * // err is InstanceType<typeof DatabaseError> | undefined
+ */
+export function goTryRaw<T, E = Error>(fn: () => never): Result<E, never>
+export function goTryRaw<T, E = Error>(fn: () => never, ErrorClass: ErrorConstructor<E>): Result<E, never>
+export function goTryRaw<T, E = Error>(
+  fn: () => Promise<T>,
+): Promise<Result<E, T>>
+export function goTryRaw<T, E = Error>(
+  fn: () => Promise<T>,
+  ErrorClass: ErrorConstructor<E>,
+): Promise<Result<E, T>>
+export function goTryRaw<T, E = Error>(
+  promise: Promise<T>,
+): Promise<Result<E, T>>
+export function goTryRaw<T, E = Error>(
+  promise: Promise<T>,
+  ErrorClass: ErrorConstructor<E>,
+): Promise<Result<E, T>>
+export function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>
+export function goTryRaw<T, E = Error>(fn: () => T, ErrorClass: ErrorConstructor<E>): Result<E, T>
+export function goTryRaw<T, E = Error>(value: T): Result<E, T>
+export function goTryRaw<T, E = Error>(value: T, ErrorClass: ErrorConstructor<E>): Result<E, T>
+export function goTryRaw<T, E = Error>(
+  value: T | Promise<T> | (() => T | Promise<T>),
+  ErrorClass?: ErrorConstructor<E>,
+): Result<E, T> | Promise<Result<E, T>> {
+  // Helper to wrap error in the provided class or return as-is
+  const wrapError = (err: unknown): E => {
+    if (ErrorClass) {
+      if (err === undefined) {
+        return new ErrorClass('undefined')
+      }
+      if (isError(err)) {
+        return new ErrorClass(err.message, { cause: err })
+      }
+      return new ErrorClass(String(err))
+    }
+    // Default behavior: return raw error
+    if (err === undefined) {
+      return new Error('undefined') as unknown as E
+    }
+    return (
+      isError(err) ? err : new Error(String(err))
+    ) as unknown as E
+  }
+
+  try {
+    const result =
+      typeof value === 'function' ? (value as () => T | Promise<T>)() : value
+    if (isPromise<T>(result)) {
+      return result
+        .then((resolvedValue) => success<T>(resolvedValue))
+        .catch((err) => failure<E>(wrapError(err)))
+    }
+    return success<T>(result)
+  } catch (err) {
+    return failure<E>(wrapError(err))
+  }
+}

package/src/index.test.ts

@@ -1,15 +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 TaggedInstance,
   type TaggedUnion,
+  assert as assertTry,
+  assertNever,
   failure,
   goTry,
   goTryAll,
@@ -363,6 +358,190 @@ 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', () => {
+    try {
+      assertTry(false, 'custom error message')
+      // Should not reach here
+      assert.equal(true, false)
+    } catch (err) {
+      assert.ok(err instanceof Error)
+      assert.equal((err as Error).message, 'custom error message')
+    }
+  })
+
+  test('throws with Error instance when condition is false', () => {
+    const customError = new Error('custom error instance')
+    try {
+      assertTry(false, customError)
+      // Should not reach here
+      assert.equal(true, false)
+    } catch (err) {
+      assert.equal(err, customError)
+    }
+  })
+
+  test('throws with tagged error when condition is false', () => {
+    const DatabaseError = taggedError('DatabaseError')
+    try {
+      assertTry(false, new DatabaseError('database connection failed'))
+      // Should not reach here
+      assert.equal(true, false)
+    } catch (err) {
+      assert.ok(err instanceof DatabaseError)
+      assert.equal((err as InstanceType<typeof DatabaseError>)._tag, 'DatabaseError')
+      assert.equal((err as Error).message, 'database connection failed')
+    }
+  })
+
+  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' }), 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' }), 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)
+      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' }), 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'
@@ -1080,7 +1259,7 @@ describe('taggedError', () => {
         case 'ValidationError':
           return `VAL: ${err.message}`
         default:
-          return `UNK: ${err.message}`
+          return assertNever(err)
       }
     }
 
@@ -1149,18 +1328,6 @@ describe('taggedError type tests', () => {
 })
 
 
-describe('TaggedInstance type helper', () => {
-  test('extracts instance type from tagged error class', () => {
-    const DatabaseError = taggedError('DatabaseError')
-    type DbError = TaggedInstance<typeof DatabaseError>
-
-    // DbError should be the instance type
-    const err: DbError = new DatabaseError('fail')
-    assert.equal(err._tag, 'DatabaseError')
-    assert.equal(err.message, 'fail')
-  })
-})
-
 describe('TaggedUnion type helper', () => {
   test('creates union type from multiple error classes', () => {
     const DatabaseError = taggedError('DatabaseError')
@@ -1189,7 +1356,7 @@ describe('TaggedUnion type helper', () => {
         case 'ValidationError':
           return `VAL: ${err.message}`
         default:
-          return `UNK: ${err.message}`
+          return assertNever(err)
       }
     }