Function toError

src/utils/errorUtils.ts:27–54

(err: unknown, contextMessage?: string)

 * ```
 */
export function toError(err: unknown, contextMessage?: string): Error {
  // If it's already an Error, return it as-is when there's no context to add.
  if (err instanceof Error) {
    if (!contextMessage) {
      return err;
    }
    // Do NOT mutate the caller's Error. Mutating err.message compounds context
    // prefixes when the same Error instance is reported through multiple layers
    // (e.g. "outer: inner: original"). Return a fresh Error that prepends the
    // context while preserving the original name and stack trace.
    const wrapped = new Error(`${contextMessage}: ${err.message}`);
    wrapped.name = err.name;
    wrapped.stack = err.stack;
    return wrapped;
  }
  
  // If it's a string, create a new Error with it
  if (typeof err === 'string') {
    return new Error(contextMessage ? `${contextMessage}: ${err}` : err);
  }
  
  // For everything else, convert to string and create an Error
  const errorMessage = contextMessage 
    ? `${contextMessage}: ${String(err)}`
    : String(err);
    
  return new Error(errorMessage);
}

/**
 * Checks if an error indicates user cancellation rather than a real error.