v0.4.3 (7 May 2026)

v0.4.3 on GitHub

Pluggable HTTP Error Status Strategy, Header Carriers, and Documentation Refresh

This release introduces pluggable error-to-status mapping for hkj-spring, lets domain errors inject custom HTTP headers (Retry-After, WWW-Authenticate, Location, ...), and delivers a comprehensive refresh of the hkj-book: the Effect Path API chapter restructured into five sub-chapters, optics documentation reorganised along Diátaxis lines, the Monad Transformers chapter rebuilt as a coherent learning path with a hands-on tutorial track, the Foundations chapter rewritten around a single recurring "one line, six layers" anchor, and refreshed hands-on materials with tiered hints and per-exercise teaching prose across every tutorial journey.

  • HttpHeaderCarrier: Mix-in interface for error values to inject custom HTTP headers into the response. All Effect Path return-value handlers now apply carrier headers before writing the JSON body, enabling 429 Too Many Requests errors to surface Retry-After, 401 Unauthorized errors to surface WWW-Authenticate, and 201 Created / 301 Moved Permanently outcomes to surface Location
  • ErrorStatusCodeStrategy: Pluggable strategy bean replacing the hard-coded heuristics in ErrorStatusCodeMapper. The default DefaultErrorStatusCodeStrategy combines explicit mappings from hkj.web.error-status-mappings (by simple or fully-qualified class name) with token-aware heuristics on the simple class name and the configured default status code; teams can supply a custom ErrorStatusCodeStrategy bean to override end-to-end
  • hkj.web.error-status-mappings: New configuration property for explicit error-class to HTTP-status mappings, supporting both simple and fully-qualified class names. Covers 4xx/5xx codes outside the heuristic table such as 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, and 503 Service Unavailable
  • Tokenised class-name matching: ErrorStatusCodeMapper now splits class names on CamelCase boundaries and matches whole tokens, eliminating false positives like RevalidationError previously matching the validation heuristic

Documentation & Tutorial Improvements

  • Effect Path API Restructure: The Effect Path API chapter is reorganised into five sub-chapters (Quickstart, Core Paths, Optics Integration, Advanced Paths, Reference) so a Java developer reaches runnable Effect Path code in under five minutes without advanced material blocking the beginner path. New API-level Effect Path quickstart with three runnable examples covering MaybePath, EitherPath, and ForPath
  • Manual Gradle and Maven Setup: Book-level Quickstart trimmed to lead with the recommended hkj-gradle-plugin and hkj-maven-plugin setup; full manual build-file configuration extracted to a new dedicated page so adopters who must wire dependencies by hand have one canonical reference
  • Optics Documentation Reorganised: Optics chapter restructured along Diátaxis lines: narrative pages focus on learning, while new dedicated reference pages serve returning readers. New Quickstart, Annotations at a Glance, Optic Capabilities, Conversions, Decision Trees, Compiler Errors, and Production Readiness;
  • Monad Transformers Learning Path: Transformers chapter rebuilt as a coherent learning path: new Quickstart, Transformers at a Glance, Migration Cookbook, When to Drop to Transformers, Common Errors, and Transformer Capstone.
  • Monad Transformers Hands-On Track: New tutorial journey in hkj-examples: Tutorial 01 (When Path Isn't Enough, EitherT entry), Tutorial 02 (Async with Absence, OptionalT/MaybeT), Tutorial 03 (Stacking Transformers), and Tutorial 04 (Polymorphic Capabilities). Default test task runs solutions; new tutorialTest task includes the in-progress exercises with predictable failures
  • Foundations Chapter Refresh: Foundations reframed as the engine-room tour readers reach after shipping with the Effect Path API, Optics, or Monad Transformers, with three reading paths (mechanism tour, generic-code author, library extender) anchored on a single recurring "one line, six layers" service-method example. New pages: One Line, Six Layers, Lifting the Hood (end-to-end trace through widen / dispatch / narrow with allocation costs), and Foundations FAQ (ten direct answers including comparisons with Vavr, Cyclops, Arrow-Kt, and the Valhalla question).
  • Hands-On Tutorial Refresh: Refreshed every tutorial journey: Tutorial 00 chapter anchor (One Line, Six Layers, setup-check exercise), new Capstone Journey building the chapter anchor up to a real workflow, tiered hint structure (Nudge / Strategy / Spoiler) on tutorial files, and hand-rolled per-exercise teaching prose on every @Test in every solution file in the Why this is idiomatic / Alternative / Common wrong attempt format. New tutorialProgress Gradle task counts answerRequired() placeholders across journeys and prints a per-journey progress bar

Previous: v0.4.4 Next: v0.4.2