go-go-try 6.0.5 → 6.0.6

package/README.md

@@ -46,7 +46,7 @@ const [err, todos = []] = await goTry(fetchTodos()) // err is string | undefined
 if (err) sendToErrorTrackingService(err)
 
 // goTry extracts the error message from the error object, if you want the raw error object, use goTryRaw
-const [err, value] = goTryRaw(() => JSON.parse('{/}')) // err will be Error, value will be always T
+const [err, value] = goTryRaw(() => JSON.parse('{/}')) // err is Error | undefined, value is T | undefined
 
 // fetch todos, fallback to empty array, send error to your error tracking service
 const [err, todos = []] = await goTryRaw(fetchTodos()) // err is Error | undefined
@@ -59,11 +59,7 @@ if (err) sendToErrorTrackingService(err)
 
 -   synchronous/asynchronous function / Promise
 
-**Returns** a tuple with the possible error and result (Golang style)
+**Returns** a tuple with the possible error and result as `[Err | undefined, T | undefined]` (Golang style)
 
 
 If you use TypeScript, the types are well defined and won't let you make a mistake.
-
-## Inspiration
-
--   This library started as a fork of [good-try](https://github.com/astoilkov/good-try) but diverged a lot so I decided to rename it

package/dist/index.d.cts

@@ -6,9 +6,50 @@ declare function isSuccess<E, T>(result: Result<E, T>): result is Success<T>;
 declare function isFailure<E, T>(result: Result<E, T>): result is Failure<E>;
 declare function success<T>(value: T): Success<T>;
 declare function failure<E>(error: E): Failure<E>;
+/**
+ * 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'));
+ */
 declare function goTry<T>(promise: Promise<T>): Promise<Result<string, T>>;
 declare function goTry<T>(fn: () => T): Result<string, T>;
 declare function goTry<T>(value: T): Result<string, T>;
+/**
+ * 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
+ * @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'));
+ */
 declare function goTryRaw<T, E = Error>(promise: Promise<T>): Promise<Result<E, T>>;
 declare function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>;
 declare function goTryRaw<T, E = Error>(value: T): Result<E, T>;

package/dist/index.d.mts

@@ -6,9 +6,50 @@ declare function isSuccess<E, T>(result: Result<E, T>): result is Success<T>;
 declare function isFailure<E, T>(result: Result<E, T>): result is Failure<E>;
 declare function success<T>(value: T): Success<T>;
 declare function failure<E>(error: E): Failure<E>;
+/**
+ * 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'));
+ */
 declare function goTry<T>(promise: Promise<T>): Promise<Result<string, T>>;
 declare function goTry<T>(fn: () => T): Result<string, T>;
 declare function goTry<T>(value: T): Result<string, T>;
+/**
+ * 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
+ * @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'));
+ */
 declare function goTryRaw<T, E = Error>(promise: Promise<T>): Promise<Result<E, T>>;
 declare function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>;
 declare function goTryRaw<T, E = Error>(value: T): Result<E, T>;

package/package.json

@@ -1,52 +1,55 @@
 {
-	"name": "go-go-try",
-	"version": "6.0.5",
-	"description": "Tries to execute a sync/async function, returns a result tuple",
-	"license": "MIT",
-	"repository": "thelinuxlich/go-go-try",
-	"author": {
-		"name": "Alisson Cavalcante Agiani",
-		"email": "thelinuxlich@gmail.com"
-	},
-	"type": "module",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.mts",
-	"exports": {
-		"require": {
-			"types": "./dist/index.d.cts",
-			"default": "./dist/index.cjs"
-		},
-		"import": {
-			"types": "./dist/index.d.mts",
-			"default": "./dist/index.mjs"
-		}
-	},
-	"engines": {
-		"node": ">=16"
-	},
-	"scripts": {
-		"build": "pkgroll",
-		"lint": "biome lint --write src/*.ts",
-		"test": "npm run build && npm run lint && vitest run"
-	},
-	"keywords": [
-		"errors",
-		"try",
-		"catch",
-		"error handling",
-		"nice-try",
-		"good-try",
-		"go-go-try",
-		"gotry",
-		"go-try"
-	],
-	"devDependencies": {
-		"@ark/attest": "^0.46.0",
-		"@biomejs/biome": "^1.9.4",
-		"pkgroll": "^2.12.1",
-		"tsx": "^4.19.3",
-		"typescript": "^5.8.3",
-		"vitest": "^3.1.2"
-	}
+  "name": "go-go-try",
+  "version": "6.0.6",
+  "description": "Tries to execute a sync/async function, returns a result tuple",
+  "license": "MIT",
+  "repository": "thelinuxlich/go-go-try",
+  "author": {
+    "name": "Alisson Cavalcante Agiani",
+    "email": "thelinuxlich@gmail.com"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    },
+    "import": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "pkgroll",
+    "lint": "biome lint --write src/*.ts",
+    "test": "npm run build && npm run lint && vitest run"
+  },
+  "keywords": [
+    "errors",
+    "try",
+    "catch",
+    "error handling",
+    "nice-try",
+    "good-try",
+    "neverthrow",
+    "ts-result",
+    "effect",
+    "go-go-try",
+    "gotry",
+    "go-try"
+  ],
+  "devDependencies": {
+    "@ark/attest": "^0.46.0",
+    "@biomejs/biome": "^1.9.4",
+    "pkgroll": "^2.12.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
 }

package/src/index.ts

@@ -1,92 +1,133 @@
-export type Success<T> = readonly [undefined, T];
-export type Failure<E> = readonly [E, undefined];
-export type Result<E, T> = Success<T> | Failure<E>;
+export type Success<T> = readonly [undefined, T]
+export type Failure<E> = readonly [E, undefined]
+export type Result<E, T> = Success<T> | Failure<E>
 
-export type MaybePromise<T> = T | Promise<T>;
+export type MaybePromise<T> = T | Promise<T>
 
 export function isSuccess<E, T>(result: Result<E, T>): result is Success<T> {
-	return result[0] === undefined;
+  return result[0] === undefined
 }
 export function isFailure<E, T>(result: Result<E, T>): result is Failure<E> {
-	return result[0] !== undefined;
+  return result[0] !== undefined
 }
 
 export function success<T>(value: T): Success<T> {
-	return [undefined, value] as const;
+  return [undefined, value] as const
 }
 
 export function failure<E>(error: E): Failure<E> {
-	return [error, undefined] as const;
+  return [error, undefined] as const
 }
 
 function getErrorMessage(error: unknown): string {
-	if (typeof error === "string") return error;
+  if (typeof error === 'string') return error
 
-	if (
-		typeof error === "object" &&
-		error !== null &&
-		"message" in error &&
-		typeof (error as Record<string, unknown>).message === "string"
-	) {
-		return (error as { message: string }).message;
-	}
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    typeof (error as Record<string, unknown>).message === 'string'
+  ) {
+    return (error as { message: string }).message
+  }
 
-	try {
-		return JSON.stringify(error);
-	} catch {
-		// fallback in case there's an error stringifying the error
-		// with circular references for example.
-		return String(error);
-	}
+  try {
+    return JSON.stringify(error)
+  } catch {
+    // fallback in case there's an error stringifying the error
+    // with circular references for example.
+    return String(error)
+  }
 }
 
 function isPromise<T>(value: unknown): value is Promise<T> {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		"then" in value &&
-		typeof (value as { then: unknown }).then === "function"
-	);
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof (value as { then: unknown }).then === 'function'
+  )
 }
 
-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>;
+/**
+ * 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>(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>),
+  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));
-	}
+  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))
+  }
 }
 
+/**
+ * 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
+ * @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'));
+ */
 export function goTryRaw<T, E = Error>(
-	promise: Promise<T>,
-): Promise<Result<E, T>>;
-export function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>;
-export function goTryRaw<T, E = Error>(value: T): Result<E, T>;
+  promise: Promise<T>,
+): Promise<Result<E, T>>
+export function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>
+export function goTryRaw<T, E = Error>(value: T): Result<E, T>
 export function goTryRaw<T, E = Error>(
-	value: T | Promise<T> | (() => T | Promise<T>),
+  value: T | Promise<T> | (() => T | Promise<T>),
 ): Result<E, T> | Promise<Result<E, 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<E>(err as E));
-		}
-		return success<T>(result);
-	} catch (err) {
-		return failure<E>(err 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>(err as E))
+    }
+    return success<T>(result)
+  } catch (err) {
+    return failure<E>(err as E)
+  }
 }