go-go-try 7.4.0 → 8.0.0

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sources":["../src/types.ts","../src/goTry.ts","../src/unknown-error.ts","../src/goTryRaw.ts","../src/goTryOr.ts","../src/goTryAll.ts","../src/tagged-error.ts","../src/assert.ts","../src/result-helpers.ts"],"mappings":"AAAA;;;AAIM,KAAM,OAAO;AACb,KAAM,OAAO;AACb,KAAM,MAAM,SAAS,OAAO,MAAM,OAAO;AAEzC,KAAM,iBAAiB;AAEvB,KAAM,YAAY,UAAU,OAAO;AAEzC;;;;AAIM,UAAW,WAAW;;;;;AAMtB,UAAW,eAAe;;;;;;;AAQhC;;;AAGM,KAAM,gBAAgB;;;AAO5B;;;;AAIM,KAAM,eAAe,KAAK,KAAK;gBACnB,gBAAgB;;;;sBACU,gBAAgB;;;;;AAG5D;;;;;;;;;;;;;AAaM,KAAM,WAAW,oBAAoB,gBAAgB;iCAC1B,gBAAgB;;;AC3DjD;;;;;;;;;;;;;;;;;;;;AAoBA,iBAAgB,KAAK,sBAAsB,MAAM;AACjD,iBAAgB,KAAK,cAAc,OAAO,MAAM,OAAO,CAAC,MAAM;AAC9D,iBAAgB,KAAK,aAAa,OAAO,MAAM,OAAO,CAAC,MAAM;AAC7D,iBAAgB,KAAK,kBAAkB,MAAM;AAC7C,iBAAgB,KAAK,eAAe,MAAM;;AC1B1C;;;;;;;;;;;;;;;;;AAiBA,cAAa,YAAY;;;;;;;;;;;;;ACPzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,iBAAgB,QAAQ,sBAAsB,MAAM,CAAC,KAAK;AAC1D,iBAAgB,QAAQ,QAAQ,YAAY,QAAQ,YAAY,6BAA6B,eAAe,MAAM,MAAM;AACxH,iBAAgB,QAAQ,cACZ,OAAO,MAChB,OAAO,CAAC,MAAM,CAAC,KAAK;AACvB,iBAAgB,QAAQ,QAAQ,YAAY,QAAQ,YAAY,aACpD,OAAO,cACR,eAAe,MACvB,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,aACb,OAAO,MACf,OAAO,CAAC,MAAM,CAAC,KAAK;AACvB,iBAAgB,QAAQ,QAAQ,YAAY,QAAQ,YAAY,YACrD,OAAO,cACP,eAAe,MACvB,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,kBAAkB,MAAM,CAAC,KAAK;AACtD,iBAAgB,QAAQ,QAAQ,YAAY,QAAQ,YAAY,yBAAyB,eAAe,MAAM,MAAM;AACpH,iBAAgB,QAAQ,eAAe,MAAM,CAAC,KAAK;AACnD,iBAAgB,QAAQ,QAAQ,YAAY,QAAQ,YAAY,sBAAsB,eAAe,MAAM,MAAM;;AC5DjH;;;;;;;;;;;;;;;;;;;;;AAqBA,iBAAgB,OAAO,mDAAmD,iBAAiB;AAC3F,iBAAgB,OAAO,cACX,OAAO,mCAEhB,OAAO,CAAC,iBAAiB;AAC5B,iBAAgB,OAAO,aACZ,OAAO,mCAEf,OAAO,CAAC,iBAAiB;AAC5B,iBAAgB,OAAO,+CAA+C,iBAAiB;AACvF,iBAAgB,OAAO,4CAA4C,iBAAiB;;ACgBpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,iBAAsB,QAAQ;oBACH,OAAO,gBAAgB,OAAO;aAC7C,eAAe,GACxB,OAAO;;;;;AAoBV;;;;;;;;;;AAUA,iBAAsB,WAAW;oBACN,OAAO,gBAAgB,OAAO;aAC7C,eAAe,GACxB,OAAO;oBAAoB,KAAK;;;;;ACrHnC;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,iBAAgB,WAAW;;;;;;;;;;;;;AC1B3B;;;;;;;;;;;;;;;;;;;;;;AAsBA,iBAAgB,MAAM,4BAA4B,KAAK;AAEvD;;;;;;;;;;;;;;AAcA,iBAAgB,MAAM,WAAW,KAAK;;ACpCtC,iBAAgB,SAAS,eAAe,MAAM,mBAAmB,OAAO;AAIxE,iBAAgB,SAAS,eAAe,MAAM,mBAAmB,OAAO;AAIxE,iBAAgB,OAAO,eAAe,OAAO;AAI7C,iBAAgB,OAAO,eAAe,OAAO;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,iBAAgB,WAAW","names":[]}
+{"version":3,"file":"index.d.mts","sources":["../src/types.ts","../src/goTry.ts","../src/unknown-error.ts","../src/goTryRaw.ts","../src/goTryOr.ts","../src/goTryAll.ts","../src/tagged-error.ts","../src/assert.ts","../src/ensure.ts","../src/result-helpers.ts","../src/goElse.ts"],"mappings":"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","names":["ResultWithDefault","ErrorConstructor"]}

package/dist/index.mjs

@@ -26,7 +26,7 @@ function getErrorMessage(error) {
     return String(error);
   }
 }
-function isPromise(value) {
+function isPromise$1(value) {
   return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
 function isError(value) {
@@ -39,7 +39,7 @@ function resolveDefault(defaultValue) {
 function goTry(value) {
   try {
     const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
+    if (isPromise$1(result)) {
       return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(getErrorMessage(err)));
     }
     return success(result);
@@ -61,7 +61,7 @@ function taggedError(tag) {
 
 const UnknownError = taggedError("UnknownError");
 
-function isTaggedError(err) {
+function isTaggedError$1(err) {
   return isError(err) && "_tag" in err && typeof err._tag === "string";
 }
 function goTryRaw(value, options) {
@@ -78,7 +78,7 @@ function goTryRaw(value, options) {
       return new errorClass(String(err));
     }
     if (actualSystemErrorClass) {
-      if (isTaggedError(err)) {
+      if (isTaggedError$1(err)) {
         return err;
       }
       if (err === void 0) {
@@ -96,7 +96,7 @@ function goTryRaw(value, options) {
   };
   try {
     const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
+    if (isPromise$1(result)) {
       return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
     }
     return success(result);
@@ -108,7 +108,7 @@ function goTryRaw(value, options) {
 function goTryOr(value, defaultValue) {
   try {
     const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
+    if (isPromise$1(result)) {
       return result.then((resolvedValue) => success(resolvedValue)).catch((err) => [getErrorMessage(err), resolveDefault(defaultValue)]);
     }
     return success(result);
@@ -117,6 +117,31 @@ function goTryOr(value, defaultValue) {
   }
 }
 
+function isTaggedError(err) {
+  return isError(err) && "_tag" in err && typeof err._tag === "string";
+}
+function wrapError(err, errorClass, systemErrorClass) {
+  if (errorClass) {
+    if (err === void 0) {
+      return new errorClass("undefined");
+    }
+    if (isError(err)) {
+      return new errorClass(err.message, { cause: err });
+    }
+    return new errorClass(String(err));
+  }
+  const actualSystemErrorClass = systemErrorClass ?? UnknownError;
+  if (isTaggedError(err)) {
+    return err;
+  }
+  if (err === void 0) {
+    return new actualSystemErrorClass("undefined");
+  }
+  if (isError(err)) {
+    return new actualSystemErrorClass(err.message, { cause: err });
+  }
+  return new actualSystemErrorClass(String(err));
+}
 async function runWithConcurrency(items, concurrency) {
   if (items.length === 0) {
     return [];
@@ -164,6 +189,7 @@ async function goTryAll(items, options) {
   return [errors, results];
 }
 async function goTryAllRaw(items, options) {
+  const { errorClass, systemErrorClass } = options || {};
   const settled = await runWithConcurrency(items, options?.concurrency ?? 0);
   const errors = [];
   const results = [];
@@ -174,7 +200,7 @@ async function goTryAllRaw(items, options) {
       results[i] = item.value;
     } else {
       const reason = item.reason;
-      errors[i] = isError(reason) ? reason : new Error(String(reason));
+      errors[i] = wrapError(reason, errorClass, systemErrorClass);
       results[i] = void 0;
     }
   }
@@ -193,4 +219,62 @@ function assert(condition, errorOrClass, message) {
   }
 }
 
-export { UnknownError, assert, assertNever, failure, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };
+function isPromise(value) {
+  return value instanceof Promise;
+}
+function isErrorConstructor(error) {
+  return typeof error === "function" && error.prototype !== void 0 && error.prototype instanceof Error;
+}
+function throwError(value, error) {
+  if (isErrorConstructor(error)) {
+    throw new error(String(value), { cause: value });
+  }
+  throw error(value);
+}
+function ensure(value, predicate, error = UnknownError) {
+  if (typeof value === "function") {
+    const result = value();
+    if (isPromise(result)) {
+      return result.then((resolved) => {
+        if (!predicate(resolved)) {
+          throwError(resolved, error);
+        }
+        return resolved;
+      });
+    }
+    if (!predicate(result)) {
+      throwError(result, error);
+    }
+    return result;
+  }
+  if (isPromise(value)) {
+    return value.then((resolved) => {
+      if (!predicate(resolved)) {
+        throwError(resolved, error);
+      }
+      return resolved;
+    });
+  }
+  if (!predicate(value)) {
+    throwError(value, error);
+  }
+  return value;
+}
+
+function goElse(value, defaultValue) {
+  try {
+    const result = typeof value === "function" ? value() : value;
+    if (isPromise$1(result)) {
+      return result.then((resolvedValue) => [void 0, resolvedValue]).catch((err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        return [error, resolveDefault(defaultValue)];
+      });
+    }
+    return [void 0, result];
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    return [error, resolveDefault(defaultValue)];
+  }
+}
+
+export { UnknownError, assert, assertNever, ensure, failure, goTryRaw as go, goTryAllRaw as goAll, goElse, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "go-go-try",
-	"version": "7.4.0",
+	"version": "8.0.0",
 	"description": "Tries to execute a sync/async function, returns a result tuple",
 	"license": "MIT",
 	"repository": "thelinuxlich/go-go-try",

package/src/ensure.test.ts

@@ -0,0 +1,116 @@
+import { describe, test, expect } from 'vitest'
+import { ensure } from './ensure.js'
+import { taggedError } from './tagged-error.js'
+import { UnknownError } from './unknown-error.js'
+
+describe('ensure', () => {
+	test('returns value when predicate passes', () => {
+		const result = ensure(42, (n) => n > 0, () => new Error('negative'))
+		expect(result).toBe(42)
+	})
+
+	test('uses UnknownError when error parameter is omitted', () => {
+		expect(() => ensure(-1, (n) => n > 0)).toThrow(UnknownError)
+	})
+
+	test('uses UnknownError with async when error parameter is omitted', async () => {
+		await expect(ensure(Promise.resolve(-1), (n) => n > 0)).rejects.toThrow(UnknownError)
+	})
+
+	test('returns value when predicate passes with error class', () => {
+		const MyError = taggedError('MyError')
+		const result = ensure(42, (n) => n > 0, MyError)
+		expect(result).toBe(42)
+	})
+
+	test('returns value with complex predicate', () => {
+		const result = ensure([1, 2, 3], (arr) => arr.length > 0, () => new Error('empty'))
+		expect(result).toEqual([1, 2, 3])
+	})
+
+	test('throws error when predicate fails', () => {
+		expect(() => ensure(-1, (n) => n > 0, (n) => new Error(`${n} is negative`))).toThrow('-1 is negative')
+	})
+
+	test('throws with access to value in error factory', () => {
+		const obj = { status: 404 }
+		expect(() =>
+			ensure(
+				obj,
+				(o) => o.status === 200,
+				(o) => new Error(`HTTP ${o.status}`)
+			)
+		).toThrow('HTTP 404')
+	})
+
+	test('throws with error class constructor', () => {
+		const RequestFailed = taggedError('RequestFailed')
+		const obj = { status: 404 }
+		expect(() =>
+			ensure(
+				obj,
+				(o: { status: number }) => o.status === 200,
+				RequestFailed
+			)
+		).toThrow()
+		try {
+			ensure(obj, (o: { status: number }) => o.status === 200, RequestFailed)
+		} catch (e) {
+			expect(e).toBeInstanceOf(RequestFailed)
+			expect((e as Error & { cause?: unknown }).cause).toBe(obj)
+		}
+	})
+
+	test('narrows type when predicate is type guard', () => {
+		interface User {
+			name: string
+		}
+		const maybeUser: unknown = { name: 'Alice' }
+
+		const user = ensure(
+			maybeUser as unknown,
+			(u): u is User => typeof u === 'object' && u !== null && 'name' in u,
+			() => new Error('Not a user')
+		)
+
+		// TypeScript knows this is User, not unknown
+		expect((user as User).name).toBe('Alice')
+	})
+
+	test('works with async values (promise passed directly)', async () => {
+		const result = await ensure(Promise.resolve(42), (n) => n > 0, () => new Error('negative'))
+		expect(result).toBe(42)
+	})
+
+	test('throws with async values when predicate fails', async () => {
+		await expect(
+			ensure(Promise.resolve(-1), (n) => n > 0, (n) => new Error(`${n} is negative`))
+		).rejects.toThrow('-1 is negative')
+	})
+
+	test('works with sync functions', () => {
+		const result = ensure(() => 42, (n) => n > 0, () => new Error('negative'))
+		expect(result).toBe(42)
+	})
+
+	test('throws with sync functions when predicate fails', () => {
+		expect(() =>
+			ensure(() => -1, (n) => n > 0, (n) => new Error(`${n} is negative`))
+		).toThrow('-1 is negative')
+	})
+
+	test('works with async functions', async () => {
+		const result = await ensure(
+			() => Promise.resolve(42),
+			(n) => n > 0,
+			() => new Error('negative')
+		)
+		expect(result).toBe(42)
+	})
+
+	test('throws with async functions when predicate fails', async () => {
+		await expect(
+			ensure(() => Promise.resolve(-1), (n) => n > 0, (n) => new Error(`${n} is negative`))
+		).rejects.toThrow('-1 is negative')
+	})
+})

package/src/ensure.ts

@@ -0,0 +1,137 @@
+import { UnknownError } from './unknown-error.js'
+
+/**
+ * Error class constructor type.
+ */
+type ErrorConstructor<E extends Error = Error> = new (
+	message: string,
+	options?: { cause?: unknown },
+) => E
+
+/**
+ * Helper to check if value is a Promise.
+ */
+function isPromise<T>(value: unknown): value is Promise<T> {
+	return value instanceof Promise
+}
+
+/**
+ * Type guard to check if error is an Error class constructor.
+ */
+function isErrorConstructor<E extends Error>(
+	error: ErrorConstructor<E> | ((value: unknown) => E) | ((value: never) => E),
+): error is ErrorConstructor<E> {
+	return (
+		typeof error === 'function' &&
+		error.prototype !== undefined &&
+		error.prototype instanceof Error
+	)
+}
+
+/**
+ * Helper to throw error from class or factory.
+ */
+function throwError<T, E extends Error>(
+	value: T,
+	error: ErrorConstructor<E> | ((value: never) => E),
+): never {
+	if (isErrorConstructor(error)) {
+		// It's an Error class constructor
+		throw new error(String(value), { cause: value })
+	}
+	// It's a factory function - cast to any to handle type variance
+	throw (error as (value: T) => E)(value)
+}
+
+/**
+ * Ensures a value satisfies a predicate, throwing an error if not.
+ * Returns the value if the predicate passes.
+ *
+ * Accepts sync values, promises, or functions - just like `go`.
+ *
+ * The error can be either:
+ * - An Error class constructor (instantiated with the value as cause)
+ * - A function that creates and returns an Error
+ * - If omitted, defaults to UnknownError
+ *
+ * @example
+ * ```typescript
+ * // With sync value (uses UnknownError by default)
+ * ensure(42, n => n > 0)
+ *
+ * // With promise (awaited internally)
+ * const res = await ensure(fetch('/api'), r => r.ok, RequestFailedError)
+ *
+ * // With function
+ * const res = ensure(() => parseInt('42'), n => !isNaN(n), Error)
+ *
+ * // With error factory function
+ * const res = ensure(
+ *   await fetch('/api'),
+ *   r => r.ok,
+ *   r => new Error(`HTTP ${r.status}`)
+ * )
+ * ```
+ */
+// Promise overloads first (more specific)
+export function ensure<T>(
+	value: Promise<T>,
+	predicate: (value: T) => boolean,
+	error?: ErrorConstructor<Error> | ((value: T) => Error),
+): Promise<T>
+// Function returning Promise
+export function ensure<T>(
+	fn: () => Promise<T>,
+	predicate: (value: T) => boolean,
+	error?: ErrorConstructor<Error> | ((value: T) => Error),
+): Promise<T>
+// Sync function
+export function ensure<T>(
+	fn: () => T,
+	predicate: (value: T) => boolean,
+	error?: ErrorConstructor<Error> | ((value: T) => Error),
+): T
+// Sync value (catch-all)
+export function ensure<T>(
+	value: T,
+	predicate: (value: T) => boolean,
+	error?: ErrorConstructor<Error> | ((value: T) => Error),
+): T
+export function ensure<T>(
+	value: T | Promise<T> | (() => T | Promise<T>),
+	predicate: (value: T) => boolean,
+	error: ErrorConstructor<Error> | ((value: T) => Error) = UnknownError,
+): T | Promise<T> {
+	// Handle function
+	if (typeof value === 'function') {
+		const result = (value as () => T | Promise<T>)()
+		if (isPromise<T>(result)) {
+			return result.then((resolved) => {
+				if (!predicate(resolved)) {
+					throwError(resolved, error)
+				}
+				return resolved
+			})
+		}
+		if (!predicate(result)) {
+			throwError(result, error)
+		}
+		return result
+	}
+
+	// Handle promise
+	if (isPromise<T>(value)) {
+		return value.then((resolved) => {
+			if (!predicate(resolved)) {
+				throwError(resolved, error)
+			}
+			return resolved
+		})
+	}
+
+	// Handle sync value
+	if (!predicate(value)) {
+		throwError(value, error)
+	}
+	return value
+}

package/src/go.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from 'vitest'
+import { go, goAll, goElse } from './index.js'
+
+describe('go (alias for goTryRaw)', () => {
+	test('returns value on success', async () => {
+		const result = await go(Promise.resolve(42))
+		expect(result).toEqual([undefined, 42])
+	})
+
+	test('returns error on failure', async () => {
+		const error = new Error('oops')
+		const result = await go(Promise.reject(error))
+		// goTryRaw wraps errors in UnknownError by default
+		expect(result[0]).toBeInstanceOf(Error)
+		expect(result[0]?.message).toBe('oops')
+		expect(result[1]).toBeUndefined()
+	})
+
+	test('works with non-promise values', async () => {
+		const result = await go(42)
+		expect(result).toEqual([undefined, 42])
+	})
+
+	test('works with sync functions', async () => {
+		const result = await go(() => 'hello')
+		expect(result).toEqual([undefined, 'hello'])
+	})
+
+	test('catches sync errors', async () => {
+		const result = await go(() => {
+			throw new Error('sync error')
+		})
+		expect(result[0]?.message).toBe('sync error')
+		expect(result[1]).toBeUndefined()
+	})
+
+	test('is exported from index', () => {
+		// Verified by the import at the top of the file
+		expect(go).toBeDefined()
+	})
+})
+
+describe('goAll (alias for goTryAllRaw)', () => {
+	test('returns all results', async () => {
+		const [errors, results] = await goAll([
+			() => Promise.resolve(1),
+			() => Promise.resolve(2),
+			() => Promise.resolve(3),
+		])
+		expect(errors).toEqual([undefined, undefined, undefined])
+		expect(results).toEqual([1, 2, 3])
+	})
+
+	test('handles mixed success and failure', async () => {
+		const [errors, results] = await goAll([
+			() => Promise.resolve(1),
+			() => Promise.reject(new Error('failed')),
+			() => Promise.resolve(3),
+		])
+		expect(errors[0]).toBeUndefined()
+		expect(errors[1]).toBeInstanceOf(Error)
+		expect(errors[2]).toBeUndefined()
+		expect(results).toEqual([1, undefined, 3])
+	})
+
+	test('is exported from index', () => {
+		expect(goAll).toBeDefined()
+	})
+})
+
+describe('goElse', () => {
+	test('returns value on success', async () => {
+		const [err, value] = await goElse(Promise.resolve(42), 0)
+		expect(err).toBeUndefined()
+		expect(value).toBe(42)
+	})
+
+	test('returns default on failure with Error object', async () => {
+		const originalError = new Error('oops')
+		const [err, value] = await goElse(() => Promise.reject(originalError), 'default')
+		expect(err).toBeInstanceOf(Error)
+		expect(err?.message).toBe('oops')
+		expect(value).toBe('default')
+	})
+
+	test('returns default on sync error with Error object', async () => {
+		const [err, value] = await goElse(() => {
+			throw new Error('sync error')
+		}, 'fallback')
+		expect(err).toBeInstanceOf(Error)
+		expect(err?.message).toBe('sync error')
+		expect(value).toBe('fallback')
+	})
+
+	test('wraps non-Error throws in Error', async () => {
+		const [err, value] = await goElse(() => {
+			throw 'string error'
+		}, 'fallback')
+		expect(err).toBeInstanceOf(Error)
+		expect(err?.message).toBe('string error')
+		expect(value).toBe('fallback')
+	})
+
+	test('is exported from index', () => {
+		expect(goElse).toBeDefined()
+	})
+})

package/src/go.ts

@@ -0,0 +1,37 @@
+/**
+ * Alias for goTryRaw - the most common usage of go-go-try.
+ *
+ * @example
+ * ```typescript
+ * const [err, data] = await go(fetch('/api'))
+ * const [err2, result] = await go(() => computeSomething())
+ * ```
+ */
+export { goTryRaw as go } from './goTryRaw.js'
+
+/**
+ * Alias for goTryAllRaw - run multiple operations in parallel.
+ *
+ * @example
+ * ```typescript
+ * const results = await goAll([
+ *   fetch('/api/users'),
+ *   fetch('/api/posts'),
+ *   fetch('/api/comments')
+ * ])
+ * // results is [Result<Error, Response>, Result<Error, Response>, Result<Error, Response>]
+ * ```
+ */
+export { goTryAllRaw as goAll } from './goTryAll.js'
+
+/**
+ * Alias for goElse - returns a default value on error.
+ * Returns the actual Error object (not just message) on failure.
+ *
+ * @example
+ * ```typescript
+ * const [err, data] = await goElse(fetch('/api'), { users: [] })
+ * // err is Error | undefined, data is the response or { users: [] }
+ * ```
+ */
+export { goElse } from './goElse.js'

package/src/goElse.ts

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