hearth-hkt-derivation

Derive polymorphic type-class instances for F[_] using Hearth macros across Scala 2.13 and Scala 3.

68|7|Updated Nov 24, 2025
One-click install
npx skills add https://github.com/kubuszok/kindlings --skill hearth-hkt-derivation
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hearth-hkt-derivation
Source: https://github.com/kubuszok/kindlings/tree/main/docs/contributing/hearth-hkt-derivation
Command: npx skills add https://github.com/kubuszok/kindlings --skill hearth-hkt-derivation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Polymorphic (kind * -> *) type class derivation across Scala 2.13 and Scala 3, enabling consistent derivation for F[_] like Functor, Traverse, and ConsK, while hiding the complexity of higher-kinded generics behind Hearth macros.

Core Features & Use Cases

  • Erased approach for macro-based derivation to avoid runtime reflection and maintain binary compatibility.
  • Two-probe field classification to distinguish direct, invariant, and nested fields for efficient instance assembly.
  • Bridge methods for type constructor summoning to handle nested F[_] fields.
  • Runtime helpers for erased HKT calls to implement bounds-safe operations across different F instances.
  • ConsK carry-and-absorb algorithm to compose fields for higher-kinded type constructors.

Quick Start

Invoke the hearth macro-based derivation to generate a Functor instance for your F[_] and inspect the resulting implementation.

Frequently Asked Questions about hearth-hkt-derivation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I derive polymorphic type class instances for higher-kinded types in Scala?

Polymorphic type class derivation for higher-kinded types like F[_] is handled by Hearth macros, which generate instances for abstractions such as Functor and Foldable. It uses an erased representation to maximize compilation speed and runtime performance.

Can I derive type classes for type constructors across both Scala 2.13 and Scala 3?

Yes, cross-version Scala derivation targets both Scala 2.13 and Scala 3. The macro-based approach requires explicit support for bridging constructors and runtime helpers to handle higher-kinded types across varied field shapes consistently.

Why use an erased representation for macro-based type class derivation?

An erased representation avoids runtime reflection and maintains binary compatibility during macro-based type class derivation. It uses a two-probe field classification to distinguish direct, invariant, and nested fields for efficient instance assembly.

How does the ConsK carry-and-absorb algorithm compose fields for higher-kinded types?

The ConsK carry-and-absorb algorithm composes fields for higher-kinded type constructors during derivation. It works alongside bridge methods for type constructor summoning to handle nested F[_] fields and runtime helpers for erased HKT calls.

What are the limitations of deriving higher-kinded type classes with Hearth?

Derivation requires explicit support for bridging constructors, field classification, and runtime helpers to handle higher-kinded types. Without these explicit bridging mechanisms for varied field shapes, the macro cannot assemble valid type class instances.