go-go-try 7.2.1 → 7.4.0

package/src/assert.ts

@@ -0,0 +1,59 @@
+/**
+ * Asserts that a condition is true, otherwise throws the provided error.
+ * Provides type narrowing when used with Result types.
+ *
+ * @param condition - The condition to assert
+ * @param error - An Error instance or string message to throw if condition is falsy
+ * @throws {Error} Throws the provided error if condition is falsy
+ *
+ * @example
+ * // With Result type - narrows error to undefined after assertion
+ * const [err, user] = goTryRaw(fetchUser(), DatabaseError)
+ * assert(err === undefined, new DatabaseError('Failed to fetch user'))
+ * // TypeScript now knows: err is undefined, user is User
+ *
+ * @example
+ * // With string message
+ * assert(response.ok, 'Response was not ok')
+ *
+ * @example
+ * // With custom Error instance
+ * assert(value > 0, new ValidationError('Value must be positive'))
+ */
+export function assert(condition: unknown, error: Error | string): asserts condition
+
+/**
+ * Asserts that a condition is true, otherwise instantiates and throws the error class.
+ * Provides type narrowing when used with Result types.
+ *
+ * @param condition - The condition to assert
+ * @param ErrorClass - An Error class constructor (e.g., from taggedError)
+ * @param message - The error message to pass to the constructor
+ * @throws {Error} Throws a new instance of ErrorClass if condition is falsy
+ *
+ * @example
+ * const ValidationError = taggedError('ValidationError')
+ * assert(value > 0, ValidationError, 'Value must be positive')
+ * // Equivalent to: if (!(value > 0)) throw new ValidationError('Value must be positive')
+ */
+export function assert<T extends Error>(
+  condition: unknown,
+  ErrorClass: new (message: string) => T,
+  message: string,
+): asserts condition
+
+export function assert(
+  condition: unknown,
+  errorOrClass: Error | string | (new (message: string) => Error),
+  message?: string,
+): asserts condition {
+  if (!condition) {
+    if (typeof errorOrClass === 'string') {
+      throw new Error(errorOrClass)
+    }
+    if (typeof errorOrClass === 'function' && message !== undefined) {
+      throw new errorOrClass(message)
+    }
+    throw errorOrClass
+  }
+}

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,126 @@
+import type { Result, GoTryRawOptions } from './types.js'
+import { success, failure } from './result-helpers.js'
+import { isPromise, isError } from './internals.js'
+import { UnknownError } from './unknown-error.js'
+
+/**
+ * Checks if a value is a tagged error (has a _tag property).
+ */
+function isTaggedError(err: unknown): err is { _tag: string } {
+  return isError(err) && '_tag' in err && typeof (err as { _tag?: unknown })._tag === 'string'
+}
+
+/**
+ * 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
+ * @param {T | Promise<T> | (() => T | Promise<T>)} value - The value, promise, or function to execute
+ * @param {GoTryRawOptions<E>} [options] - Optional options object
+ * @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 options object - wrap all errors
+ * const DatabaseError = taggedError('DatabaseError');
+ * const [err, result] = await goTryRaw(fetchData(), { errorClass: DatabaseError });
+ *
+ * @example
+ * // With options object - systemErrorClass only wraps non-tagged errors
+ * const [err, result] = await goTryRaw(fetchData(), { systemErrorClass: UnknownError });
+ * // Errors thrown as tagged errors pass through
+ * // Other errors are wrapped in UnknownError
+ */
+export function goTryRaw<T>(fn: () => never): Result<Error, never>
+export function goTryRaw<T, E = InstanceType<typeof UnknownError>>(fn: () => never, options: GoTryRawOptions<E>): Result<E, never>
+export function goTryRaw<T>(
+  fn: () => Promise<T>,
+): Promise<Result<Error, T>>
+export function goTryRaw<T, E = InstanceType<typeof UnknownError>>(
+  fn: () => Promise<T>,
+  options: GoTryRawOptions<E>,
+): Promise<Result<E, T>>
+export function goTryRaw<T>(
+  promise: Promise<T>,
+): Promise<Result<Error, T>>
+export function goTryRaw<T, E = InstanceType<typeof UnknownError>>(
+  promise: Promise<T>,
+  options: GoTryRawOptions<E>,
+): Promise<Result<E, T>>
+export function goTryRaw<T>(fn: () => T): Result<Error, T>
+export function goTryRaw<T, E = InstanceType<typeof UnknownError>>(fn: () => T, options: GoTryRawOptions<E>): Result<E, T>
+export function goTryRaw<T>(value: T): Result<Error, T>
+export function goTryRaw<T, E = InstanceType<typeof UnknownError>>(value: T, options: GoTryRawOptions<E>): Result<E, T>
+export function goTryRaw<T, E = Error>(
+  value: T | Promise<T> | (() => T | Promise<T>),
+  options?: GoTryRawOptions<E>,
+): Result<E, T> | Promise<Result<E, T>> {
+  const { errorClass, systemErrorClass } = options || {}
+
+  // Determine the actual system error class to use
+  // Default to UnknownError when systemErrorClass is not specified
+  const actualSystemErrorClass = systemErrorClass ?? UnknownError
+
+  // Helper to wrap error based on the options
+  const wrapError = (err: unknown): E => {
+    // If errorClass is specified, wrap all errors with it
+    if (errorClass) {
+      if (err === undefined) {
+        return new errorClass('undefined')
+      }
+      if (isError(err)) {
+        return new errorClass(err.message, { cause: err })
+      }
+      return new errorClass(String(err))
+    }
+
+    // If actualSystemErrorClass is specified, only wrap non-tagged errors
+    if (actualSystemErrorClass) {
+      if (isTaggedError(err)) {
+        return err as unknown as E
+      }
+
+      // Wrap non-tagged errors with systemErrorClass
+      if (err === undefined) {
+        return new actualSystemErrorClass('undefined') as unknown as E
+      }
+      if (isError(err)) {
+        return new actualSystemErrorClass(err.message, { cause: err }) as unknown as E
+      }
+      return new actualSystemErrorClass(String(err)) as unknown as E
+    }
+
+    // No options - original 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))
+  }
+}