Skip to content

Fjell: Structured HTTP Errors and FjellHttpError API v4.4.41

Choose a tag to compare

View all tags
released this 18 Oct 22:05
· 41 commits to working since this release
v4.4.41
c4ab467

This release introduces a new structured error handling mechanism for Fjell HTTP responses, adds a dedicated FjellHttpError type and related utilities, and updates the HTTP client to surface rich Fjell error information. It also expands the public API surface to expose the new error handling primitives and includes extensive tests and integration tests to validate the new behavior. The focus is on making server-side errors more actionable and preserving rich error context for debugging and UX.

New Features

  • Added FjellHttpError class and ErrorInfo type to encapsulate Fjell server errors with rich context
    • New file: src/errors/FjellHttpError.ts
    • Exposed via public exports so downstream consumers can import FjellHttpError, isFjellHttpError, and extractErrorInfo
    • Provides helpers: getUserMessage(), isRetryable(), getCode(), and toJSON()
  • Introduced structured Fjell error handling in the HTTP client
    • The HTTP client now recognizes structured Fjell error payloads (with success: false and error: ErrorInfo)
    • Throws FjellHttpError when a structured error is returned by the server instead of a generic error
    • Legacy/non-structured errors continue to be handled with existing paths, ensuring backward compatibility where appropriate
  • Public API surface updated to include FjellHttpError exports
    • index.ts updated to export from src/errors/FjellHttpError
  • Tests and integration tests for FjellHttpError and structured error handling
    • New unit tests covering constructor, messaging, retryability, error code, JSON serialization, and guards
    • New integration tests validating structured error handling, Not Found, and Duplicate scenarios, as well as legacy error fallback paths

Improvements

  • Refined error handling flow to prefer structured Fjell errors when server responses include error details, improving debuggability and user-facing messages
  • Remove obsolete internal error guards and legacy unwrap logic to simplify error handling and reduce duplication
  • Public error utilities provide a consistent way to inspect and log error information across the codebase

Bug Fixes

  • Fix: Ensure FjellHttpError is correctly propagated through the error pipeline when server returns structured errors
  • Fix: Improve error logging consistency for both structured and legacy error paths
  • Fix: Update exports to ensure FjellHttpError is accessible from the public API surface

Developer Experience

  • Added new tests and integration tests to validate new error handling paths
  • Updated API surface with FjellHttpError exports to enable straightforward usage in downstream projects
  • Alignment with testing scaffold for FjellHttpError to enable future extensions

Testing Improvements

  • New tests: tests/errors/FjellHttpError.test.ts to cover constructor, user messaging, retry logic, code extraction, and serialization
  • New integration tests: tests/errors/http-fjell-error-integration.test.ts to validate structured vs legacy error flows and error wrapping behavior
  • Extended tests cover: Not Found (NOT_FOUND), Duplicate (DUPLICATE_ERROR), and general structured error payloads

Configuration Changes

  • Minor import path adjustments to support exporting FjellHttpError from the public API
  • No breaking configuration changes required for existing consumers, but consumers should adopt the new FjellHttpError usage for structured API errors

Notes on Release Focus and Scope

  • This release centers on robust, structured server error handling for Fjell HTTP interactions. The primary goal is to preserve rich error information from server responses and present meaningful, actionable messages to developers and users of the API client.
  • The Release Size Context indicates a large release; the notes above reflect deep changes across core error handling, new error types, and substantial test coverage to support reliable adoption.

Backward Compatibility and Migration Guidance

  • Existing error handling paths remain in place for non-structured responses, ensuring legacy integrations continue to operate. When servers return structured error payloads, FjellHttpError will be thrown with the embedded error information.
  • To adopt the new error model, consumers can switch to catching FjellHttpError and use its helpers (getCode(), getUserMessage(), isRetryable(), toJSON()) for robust error handling and logging.

Files Affected (high level)

  • src/api/http.ts: Updated to recognize structured Fjell errors and throw FjellHttpError
  • src/errors/FjellHttpError.ts: New file implementing ErrorInfo and FjellHttpError, type guards, and helpers
  • src/index.ts: Re-export of FjellHttpError and related utilities
  • tests/errors/FjellHttpError.test.ts: New unit tests for FjellHttpError
  • tests/errors/http-fjell-error-integration.test.ts: New integration tests for structured vs legacy errors
  • package.json / package-lock.json: Version bumps and dependency alignment as part of the release – no functional changes beyond error handling and public API exposure
Assets 2
Loading