codebuff/common/src/util/error.ts at main · java66liu/codebuff

352 lines (329 loc) · 10.1 KB
export type ErrorOr<T, E extends ErrorObject = ErrorObject> =
  | Success<T>
  | Failure<E>
export type Success<T> = {
  success: true
export type Failure<E extends ErrorObject = ErrorObject> = {
  success: false
 * Result type for prompt functions that can be aborted.
 * Provides rich semantics to distinguish between successful completion and user abort.
 * ## When to use `PromptResult<T>` vs `ErrorOr<T>`
 * Use `PromptResult<T>` when:
 * - The operation can be cancelled by the user (via AbortSignal)
 * - An abort is an expected outcome, not an error
 * - You need to distinguish between errors (which might trigger fallbacks) and
 *   user-initiated aborts (which should propagate immediately)
 * Use `ErrorOr<T>` when:
 * - The operation can fail with an error that should be handled
 * - There's no concept of user-initiated abort
 * - You want to return error details rather than throw
 * ## Abort handling patterns
 * 1. **Check and return early** - For graceful handling where abort means "stop, no error":
 *    ```ts
 *    const result = await promptAiSdk({ ... })
 *    if (result.aborted) return // or return null, false, etc.
 *    doSomething(result.value)
 * 2. **Unwrap and throw** - For propagating aborts as exceptions:
 *    ```ts
 *    const value = unwrapPromptResult(await promptAiSdk({ ... }))
 *    // Throws if aborted, callers should use isAbortError() in catch blocks
 * 3. **Rethrow in catch blocks** - Prevent swallowing abort errors:
 *    ```ts
 *    try {
 *      await someOperation()
 *    } catch (error) {
 *      if (isAbortError(error)) throw error // Don't swallow aborts
 *      // Handle other errors
export type PromptResult<T> = PromptSuccess<T> | PromptAborted
export type PromptSuccess<T> = {
  aborted: false
export type PromptAborted = {
  aborted: true
  reason?: string
export type ErrorObject = {
  name: string
  message: string
  stack?: string
  /** HTTP status code from error.status (used by some libraries) */
  status?: number
  /** HTTP status code from error.statusCode (used by AI SDK and Codebuff errors) */
  statusCode?: number
  /** Optional machine-friendly error code, if available */
  code?: string
  /** Optional raw error object */
  rawError?: string
  /** Response body from API errors (AI SDK APICallError) */
  responseBody?: string
  /** URL that was called (API errors) */
  url?: string
  /** Whether the error is retryable (API errors) */
  isRetryable?: boolean
  /** Request body values that were sent (API errors) - stringified for safety */
  requestBodyValues?: string
  /** Cause of the error, if nested */
  cause?: ErrorObject
export function success<T>(value: T): Success<T> {
    success: true,
export function failure(error: unknown): Failure<ErrorObject> {
    success: false,
    error: getErrorObject(error),
 * Create a successful prompt result.
export function promptSuccess<T>(value: T): PromptSuccess<T> {
    aborted: false,
 * Create an aborted prompt result.
export function promptAborted(reason?: string): PromptAborted {
    aborted: true,
    ...(reason !== undefined && { reason }),
 * Standard error message for aborted requests.
 * Use this constant when throwing abort errors to ensure consistency.
export const ABORT_ERROR_MESSAGE = 'Request aborted'
 * Custom error class for abort errors.
 * Use this class instead of generic Error for abort errors to ensure
 * robust detection via isAbortError() (checks error.name === 'AbortError').
export class AbortError extends Error {
  constructor(reason?: string) {
    super(reason ? `${ABORT_ERROR_MESSAGE}: ${reason}` : ABORT_ERROR_MESSAGE)
    this.name = 'AbortError'
 * Check if an error is an abort error.
 * Use this helper to detect abort errors in catch blocks.
 * Detects both:
 * - Errors with message starting with 'Request aborted' (thrown by our code via AbortError)
 * - Native AbortError (thrown by fetch/AI SDK when AbortSignal is triggered)
export function isAbortError(error: unknown): boolean {
  if (!(error instanceof Error)) {
    return false
  // Check for our custom abort error message:
  // - Exact match: 'Request aborted'
  // - With reason: 'Request aborted: <reason>' (from AbortError class)
    error.message === ABORT_ERROR_MESSAGE ||
    error.message.startsWith(`${ABORT_ERROR_MESSAGE}: `)
    return true
  // Check for native AbortError (DOMException or Error with name 'AbortError')
  // This is thrown by fetch, AI SDK, and other web APIs when AbortSignal is triggered
  if (error.name === 'AbortError') {
    return true
  return false
 * Unwrap a PromptResult, returning the value if successful or throwing if aborted.
 * Use this helper for consistent abort handling when you want aborts to propagate
 * as exceptions. Callers should use `isAbortError()` in catch blocks to detect
 * and handle abort errors appropriately (e.g., rethrow instead of logging as errors).
 * @throws {AbortError} When result.aborted is true.
export function unwrapPromptResult<T>(result: PromptResult<T>): T {
  if (result.aborted) {
    throw new AbortError(result.reason)
  return result.value
 * Parses a JSON response body string from an API error to extract structured error details.
 * Used to extract machine-readable error codes and human-readable messages from API responses
 * (e.g., AI SDK's APICallError includes a responseBody with the server's JSON response).
 * Returns extracted fields, or an empty object if the responseBody is not a valid JSON string
 * with the expected shape.
export function parseApiErrorResponseBody(responseBody: unknown): {
  errorCode?: string
  message?: string
  countryCode?: string
  countryBlockReason?: string
  ipPrivacySignals?: string[]
  if (typeof responseBody !== 'string') return {}
    const parsed: unknown = JSON.parse(responseBody)
    if (!parsed || typeof parsed !== 'object') return {}
    const result: {
      errorCode?: string
      message?: string
      countryCode?: string
      countryBlockReason?: string
      ipPrivacySignals?: string[]
      'error' in parsed &&
      typeof (parsed as { error: unknown }).error === 'string'
      result.errorCode = (parsed as { error: string }).error
      'message' in parsed &&
      typeof (parsed as { message: unknown }).message === 'string'
      result.message = (parsed as { message: string }).message
      'countryCode' in parsed &&
      typeof (parsed as { countryCode: unknown }).countryCode === 'string'
      result.countryCode = (parsed as { countryCode: string }).countryCode
      'countryBlockReason' in parsed &&
      typeof (parsed as { countryBlockReason: unknown }).countryBlockReason ===
        'string'
      result.countryBlockReason = (
        parsed as { countryBlockReason: string }
      ).countryBlockReason
    if ('ipPrivacySignals' in parsed) {
      const signals = (parsed as { ipPrivacySignals: unknown }).ipPrivacySignals
      if (Array.isArray(signals)) {
        result.ipPrivacySignals = signals.filter(
          (signal): signal is string => typeof signal === 'string',
    return result
  } catch {
    return {}
// Extended error properties that various libraries add to Error objects
interface ExtendedErrorProperties {
  status?: number
  statusCode?: number
  code?: string
  // API error properties (AI SDK APICallError, etc.)
  responseBody?: string
  url?: string
  isRetryable?: boolean
  requestBodyValues?: Record<string, unknown>
  cause?: unknown
 * Safely stringify an object, handling circular references and large objects.
function safeStringify(value: unknown, maxLength = 10000): string | undefined {
  if (value === undefined || value === null) return undefined
  if (typeof value === 'string') return value.slice(0, maxLength)
    const seen = new WeakSet()
    const str = JSON.stringify(
      value,
      (_, val) => {
        if (typeof val === 'object' && val !== null) {
          if (seen.has(val)) return '[Circular]'
          seen.add(val)
        return val
    return str?.slice(0, maxLength)
  } catch {
    return '[Unable to stringify]'
export function getErrorObject(
  error: unknown,
  options: { includeRawError?: boolean } = {},
): ErrorObject {
  if (error instanceof Error) {
    const extError = error as Error & Partial<ExtendedErrorProperties>
    // Extract responseBody - could be string or object
    let responseBody: string | undefined
    if (extError.responseBody !== undefined) {
      responseBody = safeStringify(extError.responseBody)
    // Extract requestBodyValues - typically an object, stringify for logging
    let requestBodyValues: string | undefined
      extError.requestBodyValues !== undefined &&
      typeof extError.requestBodyValues === 'object'
      requestBodyValues = safeStringify(extError.requestBodyValues)
    // Extract cause - recursively convert to ErrorObject if present
    let cause: ErrorObject | undefined
    if (extError.cause !== undefined) {
      cause = getErrorObject(extError.cause, options)
    return {
      name: error.name,
      message: error.message,
      stack: error.stack,
      status: typeof extError.status === 'number' ? extError.status : undefined,
      statusCode:
        typeof extError.statusCode === 'number'
          ? extError.statusCode
          : undefined,
      code: typeof extError.code === 'string' ? extError.code : undefined,
      rawError: options.includeRawError
        ? safeStringify(error)
        : undefined,
      // API error fields
      responseBody,
      url: typeof extError.url === 'string' ? extError.url : undefined,
      isRetryable:
        typeof extError.isRetryable === 'boolean'
          ? extError.isRetryable
          : undefined,
      requestBodyValues,
      cause,
    name: 'Error',
    message: `${error}`,
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

error.ts

Latest commit

History

error.ts

File metadata and controls
