Enhanced Error Messages

Better error messages and debugging utilities. (v1.11.0)

Overview

Enhanced error message types help you create detailed, informative type errors with suggestions, diagnostics, and recovery options.

Error Enhancement

DetailedError

Type with detailed error information.

type DetailedError<T> = T & {
  __error_details__: ErrorDetails
}

ErrorDetails

Detailed error information.

interface ErrorDetails {
  code: string
  message: string
  category: ErrorCategory
  context?: ErrorContext
  suggestion?: string
  docs?: string
  stack?: string
  timestamp?: number
}

ErrorCategory

Category of the error.

type ErrorCategory =
  | 'type'
  | 'syntax'
  | 'semantic'
  | 'constraint'
  | 'runtime'
  | 'validation'
  | 'assertion'
  | 'inference'

TypedError

Error with a specific category.

type TypedError<T extends ErrorCategory> = {
  category: T
  message: string
  code: string
}

Example:

type TypeErr = TypedError<'type'>
// { category: 'type'; message: string; code: string }

ErrorContext

Context information for an error.

type ErrorContext<T = unknown> = {
  originalType?: T
  expectedType?: string
  actualType?: string
  path?: string[]
  line?: number
  column?: number
  filePath?: string
  data?: Record<string, unknown>
}

ErrorSuggestion

Type with a suggestion for fixing.

type ErrorSuggestion<T> = T & {
  __suggestion__: SuggestionInfo
}

Diagnostic Types

Diagnostic

Diagnostic information attached to a type.

type Diagnostic<T> = T & {
  __diagnostic__: DiagnosticInfo
}

DiagnosticInfo

Diagnostic details.

interface DiagnosticInfo {
  code: DiagnosticCode
  message: string
  severity: DiagnosticSeverity
  source?: string
  related?: RelatedDiagnostic[]
}

DiagnosticSeverity

Severity level for diagnostics.

type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint'

DiagnosticLocation

Location of a diagnostic.

interface DiagnosticLocation {
  file: string
  startLine: number
  startColumn: number
  endLine?: number
  endColumn?: number
}

Type Errors

TypeMismatch

Error for type mismatches.

type TypeMismatch<T, Expected> = {
  actual: T
  expected: Expected
  message: string
  details: MismatchDetails
}

MismatchKind

Kind of type mismatch.

type MismatchKind =
  | 'type'
  | 'structure'
  | 'value'
  | 'constraint'
  | 'missing_property'
  | 'extra_property'
  | 'nullability'
  | 'optionality'
  | 'arity'
  | 'return_type'
  | 'parameter_type'

MissingProperty

Error for missing properties.

type MissingProperty<T, K extends keyof T> = {
  object: T
  key: K
  message: string
}

InvalidType

Error for invalid types.

type InvalidType<T, Valid> = {
  invalid: T
  valid: Valid
  message: string
}

ConstraintViolation

Error for constraint violations.

type ConstraintViolation<T, Constraint> = {
  type: T
  constraint: Constraint
  details: string
}

Error Recovery

RecoverableError

Error that can be recovered.

type RecoverableError<T> = T & {
  __recoverable__: true
  __recovery_options__: RecoveryOption[]
}

ErrorRecovery

Recovery information for an error.

type ErrorRecovery<T> = {
  error: T
  strategy: RecoveryStrategy
  recovered?: unknown
  success?: boolean
}

RecoveryStrategy

Strategy for recovering from errors.

type RecoveryStrategy =
  | 'fallback'
  | 'default'
  | 'skip'
  | 'retry'
  | 'transform'
  | 'ignore'
  | 'abort'

RecoveryOption

Option for recovering from an error.

interface RecoveryOption {
  name: string
  strategy: RecoveryStrategy
  description: string
  value?: unknown
  isDefault?: boolean
}

FallbackType

Fallback type for error recovery.

type FallbackType<T, Fallback> = T extends Fallback ? T : Fallback

Example:

type Result = FallbackType<string | undefined, string>
// string

GracefulDegradation

Type that gracefully degrades.

type GracefulDegradation<T> = T | DegradedValue

Help Messages

HelpMessage

Type with help information.

type HelpMessage<T> = T & {
  __help__: HelpInfo
}

HelpInfo

Help information.

interface HelpInfo {
  text: string
  url?: string
  examples?: HelpExample[]
  related?: string[]
}

DocumentationLink

Type with documentation link.

type DocumentationLink<T> = T & {
  __docs__: string
}

ExampleUsage

Type with example usage.

type ExampleUsage<T> = T & {
  __example__: string
}

QuickFix

Type with quick fix information.

type QuickFix<T> = T & {
  __quick_fix__: QuickFixInfo
}

QuickFixAction

Action type for quick fixes.

type QuickFixAction = 'replace' | 'insert' | 'delete' | 'rename' | 'refactor'

Error Reporting

ErrorReport

Report of errors and warnings.

interface ErrorReport {
  id: string
  timestamp: Date
  errorCount: number
  warningCount: number
  errors: ReportedError[]
  warnings: ReportedWarning[]
  summary: string
}

ErrorCatalog

Catalog of error types.

interface ErrorCatalog {
  version: string
  entries: Record<string, ErrorCatalogEntry>
  categories: ErrorCategory[]
  lastUpdated: Date
}

CommonErrorType

Common error type names.

type CommonErrorType =
  | 'type_error'
  | 'syntax_error'
  | 'reference_error'
  | 'range_error'
  | 'constraint_error'
  | 'assertion_error'
  | 'null_error'
  | 'undefined_error'
  | 'property_error'
  | 'argument_error'
  | 'return_error'
  | 'generic_error'

Related Types

• Breaking Change Detection - Detect breaking changes
• Migration Utilities - Type migration tools
• Deprecation Management - Deprecation warnings