go-go-try 7.2.0 → 7.3.0

package/dist/index.d.mts

@@ -1,6 +1,11 @@
+/**
+ * Core Result types for go-go-try
+ */
 type Success<T> = readonly [undefined, T];
 type Failure<E> = readonly [E, undefined];
 type Result<E, T> = Success<T> | Failure<E>;
+type ResultWithDefault<E, T> = readonly [E | undefined, T];
+type MaybePromise<T> = T | Promise<T>;
 /**
  * Base interface for tagged errors.
  * The `_tag` property enables discriminated union narrowing.
@@ -10,55 +15,101 @@ interface TaggedError<T extends string> {
     readonly message: string;
     readonly cause?: unknown;
 }
+interface GoTryAllOptions {
+    /**
+     * Maximum number of concurrent promises.
+     * Set to 0 (default) for unlimited concurrency (all promises run in parallel).
+     */
+    concurrency?: number;
+}
 /**
- * Creates a tagged error class for discriminated error handling.
+ * Type for error constructors that can be used with goTryRaw.
+ */
+type ErrorConstructor<E> = new (message: string, options?: {
+    cause?: unknown;
+}) => E;
+/**
+ * Creates a union type from multiple tagged error classes.
  *
- * @template T The literal type of the tag
- * @param tag The string tag to identify this error type (e.g., 'DatabaseError')
- * @returns A class constructor for creating tagged errors
+ * @template T A tuple of tagged error class types
+ * @returns A union of all instance types
  *
  * @example
  * const DatabaseError = taggedError('DatabaseError')
  * const NetworkError = taggedError('NetworkError')
  *
- * type MyError = InstanceType<typeof DatabaseError> | InstanceType<typeof NetworkError>
+ * type AppError = TaggedUnion<[typeof DatabaseError, typeof NetworkError]>
+ * // Equivalent to: DatabaseError | NetworkError
+ */
+type TaggedUnion<T extends readonly ErrorConstructor<unknown>[]> = {
+    [K in keyof T]: T[K] extends ErrorConstructor<infer E> ? E : never;
+}[number];
+
+/**
+ * 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.
  *
- * function fetchUser(id: string): Result<MyError, User> {
- *   const [err, user] = goTryRaw(fetch(`/users/${id}`), DatabaseError)
- *   if (err) return failure(err)
- *   // ...
- * }
+ * @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
  *
- * // Pattern matching on errors
- * if (err._tag === 'DatabaseError') {
- *   // TypeScript knows this is DatabaseError
- * }
+ * @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 taggedError<T extends string>(tag: T): {
-    new (message: string, options?: {
-        cause?: unknown;
-    }): {
-        readonly _tag: T;
-        readonly cause?: unknown;
-        name: string;
-        message: string;
-        stack?: string;
-    };
-    isError(error: unknown): error is Error;
-};
-type ResultWithDefault<E, T> = readonly [E | undefined, T];
-type MaybePromise<T> = T | Promise<T>;
-interface GoTryAllOptions {
-    /**
-     * Maximum number of concurrent promises.
-     * Set to 0 (default) for unlimited concurrency (all promises run in parallel).
-     */
-    concurrency?: number;
-}
-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>;
+declare function goTry<T>(fn: () => never): Result<string, never>;
+declare function goTry<T>(fn: () => Promise<T>): Promise<Result<string, T>>;
+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
+ * @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
+ */
+declare function goTryRaw<T, E = Error>(fn: () => never): Result<E, never>;
+declare function goTryRaw<T, E = Error>(fn: () => never, ErrorClass: ErrorConstructor<E>): Result<E, never>;
+declare function goTryRaw<T, E = Error>(fn: () => Promise<T>): Promise<Result<E, T>>;
+declare function goTryRaw<T, E = Error>(fn: () => Promise<T>, ErrorClass: ErrorConstructor<E>): Promise<Result<E, T>>;
+declare function goTryRaw<T, E = Error>(promise: Promise<T>): Promise<Result<E, T>>;
+declare function goTryRaw<T, E = Error>(promise: Promise<T>, ErrorClass: ErrorConstructor<E>): Promise<Result<E, T>>;
+declare function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>;
+declare function goTryRaw<T, E = Error>(fn: () => T, ErrorClass: ErrorConstructor<E>): Result<E, T>;
+declare function goTryRaw<T, E = Error>(value: T): Result<E, T>;
+declare function goTryRaw<T, E = Error>(value: T, ErrorClass: ErrorConstructor<E>): Result<E, T>;
+
 /**
  * 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.
@@ -85,6 +136,7 @@ declare function goTryOr<T>(fn: () => Promise<T>, defaultValue: T | (() => T)):
 declare function goTryOr<T>(promise: Promise<T>, defaultValue: T | (() => T)): Promise<ResultWithDefault<string, T>>;
 declare function goTryOr<T>(fn: () => T, defaultValue: T | (() => T)): ResultWithDefault<string, T>;
 declare function goTryOr<T>(value: T, defaultValue: T | (() => T)): ResultWithDefault<string, T>;
+
 /**
  * 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 -
@@ -141,105 +193,114 @@ declare function goTryAllRaw<T extends readonly unknown[]>(items: {
 }, {
     [K in keyof T]: T[K] | undefined;
 }]>;
+
 /**
- * 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.
+ * Creates a tagged error class for discriminated error handling.
  *
- * @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
+ * @template T The literal type of the tag
+ * @param tag The string tag to identify this error type (e.g., 'DatabaseError')
+ * @returns A class constructor for creating tagged errors
  *
  * @example
- * // With a value
- * const [err, result] = goTry(42);
+ * const DatabaseError = taggedError('DatabaseError')
+ * const NetworkError = taggedError('NetworkError')
  *
- * @example
- * // With a function
- * const [err, result] = goTry(() => JSON.parse('{"key": "value"}'));
+ * type MyError = InstanceType<typeof DatabaseError> | InstanceType<typeof NetworkError>
  *
- * @example
- * // With a promise
- * const [err, result] = await goTry(fetch('https://api.example.com/data'));
- */
-declare function goTry<T>(fn: () => never): Result<string, never>;
-declare function goTry<T>(fn: () => Promise<T>): Promise<Result<string, T>>;
-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>;
-/**
- * Type for error constructors that can be used with goTryRaw.
+ * function fetchUser(id: string): Result<MyError, User> {
+ *   const [err, user] = goTryRaw(fetch(`/users/${id}`), DatabaseError)
+ *   if (err) return failure(err)
+ *   // ...
+ * }
+ *
+ * // Pattern matching on errors
+ * if (err._tag === 'DatabaseError') {
+ *   // TypeScript knows this is DatabaseError
+ * }
  */
-type ErrorConstructor<E> = new (message: string, options?: {
-    cause?: unknown;
-}) => E;
+declare function taggedError<T extends string>(tag: T): {
+    new (message: string, options?: {
+        cause?: unknown;
+    }): {
+        readonly _tag: T;
+        readonly cause?: unknown;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    isError(error: unknown): error is Error;
+};
+
 /**
- * Extracts the instance type from a tagged error class.
- * Useful for creating cleaner error type definitions.
+ * Asserts that a condition is true, otherwise throws the provided error.
+ * Provides type narrowing when used with Result types.
  *
- * @template T The tagged error class type
- * @returns The instance type of the error class
+ * @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
- * const DatabaseError = taggedError('DatabaseError')
- * type DbError = TaggedInstance<typeof DatabaseError>
- * // Equivalent to: InstanceType<typeof DatabaseError>
- */
-type TaggedInstance<T extends ErrorConstructor<unknown>> = T extends ErrorConstructor<infer E> ? E : never;
-/**
- * Creates a union type from multiple tagged error classes.
- *
- * @template T A tuple of tagged error class types
- * @returns A union of all instance types
+ * // 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
- * const DatabaseError = taggedError('DatabaseError')
- * const NetworkError = taggedError('NetworkError')
+ * // With string message
+ * assert(response.ok, 'Response was not ok')
  *
- * type AppError = TaggedUnion<[typeof DatabaseError, typeof NetworkError]>
- * // Equivalent to: DatabaseError | NetworkError
+ * @example
+ * // With custom Error instance
+ * assert(value > 0, new ValidationError('Value must be positive'))
  */
-type TaggedUnion<T extends readonly ErrorConstructor<unknown>[]> = {
-    [K in keyof T]: T[K] extends ErrorConstructor<infer E> ? E : never;
-}[number];
+declare function assert(condition: unknown, error: Error | string): asserts condition;
 /**
- * Executes a function, promise, or value and returns a Result type.
- * If an error occurs, it returns a Failure with the raw error object.
+ * Asserts that a condition is true, otherwise instantiates and throws the error class.
+ * Provides type narrowing when used with Result types.
  *
- * @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
+ * @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
- * // With a value
- * const [err, result] = goTryRaw(42);
+ * const ValidationError = taggedError('ValidationError')
+ * assert(value > 0, ValidationError, 'Value must be positive')
+ * // Equivalent to: if (!(value > 0)) throw new ValidationError('Value must be positive')
+ */
+declare function assert<T extends Error>(condition: unknown, ErrorClass: new (message: string) => T, message: string): asserts condition;
+
+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>;
+/**
+ * Helper for exhaustive switch checks on discriminated unions.
+ * If this function is called, it means a case was forgotten in a switch statement.
+ * Use this in the `default` case of switch statements handling tagged errors.
  *
- * @example
- * // With a function
- * const [err, result] = goTryRaw(() => JSON.parse('{"key": "value"}'));
+ * @param value - The value that should be of type `never` if all cases are handled
+ * @throws {Error} Always throws an error indicating unhandled case
  *
  * @example
- * // With a promise
- * const [err, result] = await goTryRaw(fetch('https://api.example.com/data'));
+ * const DatabaseError = taggedError('DatabaseError')
+ * const NetworkError = taggedError('NetworkError')
+ * type AppError = InstanceType<typeof DatabaseError> | InstanceType<typeof NetworkError>
  *
- * @example
- * // With tagged error for discriminated unions
- * const DatabaseError = taggedError('DatabaseError');
- * const [err, result] = await goTryRaw(fetchData(), DatabaseError);
- * // err is InstanceType<typeof DatabaseError> | undefined
+ * function handleError(err: AppError): string {
+ *   switch (err._tag) {
+ *     case 'DatabaseError':
+ *       return `DB: ${err.message}`
+ *     case 'NetworkError':
+ *       return `NET: ${err.message}`
+ *     default:
+ *       // TypeScript will error if we forget a case above
+ *       return assertNever(err)
+ *   }
+ * }
  */
-declare function goTryRaw<T, E = Error>(fn: () => never): Result<E, never>;
-declare function goTryRaw<T, E = Error>(fn: () => never, ErrorClass: ErrorConstructor<E>): Result<E, never>;
-declare function goTryRaw<T, E = Error>(fn: () => Promise<T>): Promise<Result<E, T>>;
-declare function goTryRaw<T, E = Error>(fn: () => Promise<T>, ErrorClass: ErrorConstructor<E>): Promise<Result<E, T>>;
-declare function goTryRaw<T, E = Error>(promise: Promise<T>): Promise<Result<E, T>>;
-declare function goTryRaw<T, E = Error>(promise: Promise<T>, ErrorClass: ErrorConstructor<E>): Promise<Result<E, T>>;
-declare function goTryRaw<T, E = Error>(fn: () => T): Result<E, T>;
-declare function goTryRaw<T, E = Error>(fn: () => T, ErrorClass: ErrorConstructor<E>): Result<E, T>;
-declare function goTryRaw<T, E = Error>(value: T): Result<E, T>;
-declare function goTryRaw<T, E = Error>(value: T, ErrorClass: ErrorConstructor<E>): Result<E, T>;
+declare function assertNever(value: never): never;
 
-export { failure, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };
-export type { ErrorConstructor, Failure, GoTryAllOptions, MaybePromise, Result, ResultWithDefault, Success, TaggedError, TaggedInstance, TaggedUnion };
+export { assert, assertNever, failure, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };
+export type { ErrorConstructor, Failure, GoTryAllOptions, MaybePromise, Result, ResultWithDefault, Success, TaggedError, TaggedUnion };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sources":["../src/index.ts"],"mappings":"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","names":[]}
+{"version":3,"file":"index.d.mts","sources":["../src/types.ts","../src/goTry.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;;;AAE5B;;;;;;;;;;;;;AAaM,KAAM,WAAW,oBAAoB,gBAAgB;iCAC1B,gBAAgB;;;AC7CjD;;;;;;;;;;;;;;;;;;;;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;;ACxB1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,iBAAgB,QAAQ,QAAQ,KAAK,oBAAoB,MAAM;AAC/D,iBAAgB,QAAQ,QAAQ,KAAK,+BAA+B,gBAAgB,MAAM,MAAM;AAChG,iBAAgB,QAAQ,QAAQ,KAAK,YACzB,OAAO,MAChB,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,QAAQ,KAAK,YACzB,OAAO,iBACL,gBAAgB,MAC3B,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,QAAQ,KAAK,WAC1B,OAAO,MACf,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,QAAQ,KAAK,WAC1B,OAAO,iBACJ,gBAAgB,MAC3B,OAAO,CAAC,MAAM;AACjB,iBAAgB,QAAQ,QAAQ,KAAK,gBAAgB,MAAM;AAC3D,iBAAgB,QAAQ,QAAQ,KAAK,2BAA2B,gBAAgB,MAAM,MAAM;AAC5F,iBAAgB,QAAQ,QAAQ,KAAK,aAAa,MAAM;AACxD,iBAAgB,QAAQ,QAAQ,KAAK,wBAAwB,gBAAgB,MAAM,MAAM;;AC/CzF;;;;;;;;;;;;;;;;;;;;;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":[]}

package/dist/index.mjs

@@ -1,13 +1,3 @@
-function taggedError(tag) {
-  return class TaggedErrorClass extends Error {
-    constructor(message, options) {
-      super(message);
-      this._tag = tag;
-      this.name = tag;
-      this.cause = options?.cause;
-    }
-  };
-}
 function isSuccess(result) {
   return result[0] === void 0;
 }
@@ -20,9 +10,71 @@ function success(value) {
 function failure(error) {
   return [error, void 0];
 }
+function assertNever(value) {
+  throw new Error(`Unhandled case: ${String(value)}`);
+}
+
+function getErrorMessage(error) {
+  if (error === void 0) return "undefined";
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+function isPromise(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isError(value) {
+  return value instanceof Error;
+}
 function resolveDefault(defaultValue) {
   return typeof defaultValue === "function" ? defaultValue() : defaultValue;
 }
+
+function goTry(value) {
+  try {
+    const result = typeof value === "function" ? value() : value;
+    if (isPromise(result)) {
+      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(getErrorMessage(err)));
+    }
+    return success(result);
+  } catch (err) {
+    return failure(getErrorMessage(err));
+  }
+}
+
+function goTryRaw(value, ErrorClass) {
+  const wrapError = (err) => {
+    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));
+    }
+    if (err === void 0) {
+      return new Error("undefined");
+    }
+    return isError(err) ? err : new Error(String(err));
+  };
+  try {
+    const result = typeof value === "function" ? value() : value;
+    if (isPromise(result)) {
+      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
+    }
+    return success(result);
+  } catch (err) {
+    return failure(wrapError(err));
+  }
+}
+
 function goTryOr(value, defaultValue) {
   try {
     const result = typeof value === "function" ? value() : value;
@@ -34,6 +86,7 @@ function goTryOr(value, defaultValue) {
     return [getErrorMessage(err), resolveDefault(defaultValue)];
   }
 }
+
 async function runWithConcurrency(items, concurrency) {
   if (items.length === 0) {
     return [];
@@ -97,60 +150,28 @@ async function goTryAllRaw(items, options) {
   }
   return [errors, results];
 }
-function getErrorMessage(error) {
-  if (error === void 0) return "undefined";
-  if (typeof error === "string") return error;
-  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
-    return error.message;
-  }
-  try {
-    return JSON.stringify(error);
-  } catch {
-    return String(error);
-  }
-}
-function isPromise(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function isError(value) {
-  return value instanceof Error;
-}
-function goTry(value) {
-  try {
-    const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
-      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(getErrorMessage(err)));
+
+function taggedError(tag) {
+  return class TaggedErrorClass extends Error {
+    constructor(message, options) {
+      super(message);
+      this._tag = tag;
+      this.name = tag;
+      this.cause = options?.cause;
     }
-    return success(result);
-  } catch (err) {
-    return failure(getErrorMessage(err));
-  }
+  };
 }
-function goTryRaw(value, ErrorClass) {
-  const wrapError = (err) => {
-    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));
-    }
-    if (err === void 0) {
-      return new Error("undefined");
+
+function assert(condition, errorOrClass, message) {
+  if (!condition) {
+    if (typeof errorOrClass === "string") {
+      throw new Error(errorOrClass);
     }
-    return isError(err) ? err : new Error(String(err));
-  };
-  try {
-    const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
-      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
+    if (typeof errorOrClass === "function" && message !== void 0) {
+      throw new errorOrClass(message);
     }
-    return success(result);
-  } catch (err) {
-    return failure(wrapError(err));
+    throw errorOrClass;
   }
 }
 
-export { failure, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };
+export { assert, assertNever, failure, goTry, goTryAll, goTryAllRaw, goTryOr, goTryRaw, isFailure, isSuccess, success, taggedError };

package/package.json

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

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
+  }
+}