hearth-api-reference

name	hearth-api-reference
description	Quick-reference table of commonly used Hearth API signatures: Expr, Type, MIO, ValDefsCache, CaseClass, Enum, LambdaBuilder, Environment. Always verify with MCP.
user-invocable	false

Hearth API Quick Reference

Living cache of hearth API signatures used in kindlings. Always verify with kindlings-metals MCP before use.

Last verified against hearth version: check build.sbt versions.hearth

Effect system (MIO, Log)

API	Signature	Description
MIO.pure	[A](a: A): MIO[A]	Lift a pure value
MIO.fail	(error: Throwable): MIO[Nothing]	Fail with error
MIO { ... }	[A](thunk: => A): MIO[A]	Lift a thunk
mio1 >> mio2	MIO[A] >> MIO[B]: MIO[B]	Sequence, discard first result
mio.flatMap(f)	MIO[A].flatMap(A => MIO[B]): MIO[B]	Monadic bind
mio.map(f)	MIO[A].map(A => B): MIO[B]	Functor map
MIO.scoped	[A](f: (MIO ~> Id) => A): MIO[A]	Unsafe escape hatch for builders
Log.info	(msg: => String): MIO[Unit]	Log at info level
Log.debug	(msg: => String): MIO[Unit]	Log at debug level
Log.namedScope	[A](name: String)(body: MIO[A]): MIO[A]	Hierarchical log scope
Environment.reportErrorAndAbort	(msg: String): Nothing	Abort compilation with error (outside MIO chain)

Type representations

API	Signature	Description
Type.of[A]	[A](implicit ev: Type[A]): Type[A]	Get type representation
Type[A].prettyPrint	: String	Human-readable type name
Type[A].shortName	: String	Short type name (no package)
Type[A] <:< Type[B]	: Boolean	Subtype check
Type[A] =:= Type[B]	: Boolean	Type equality
Type[A].summonExpr	: ImplicitSearchResult[A]	Summon implicit
Type[A].summonExprIgnoring	(symbols: UntypedMethod*): ImplicitSearchResult[A]	Summon ignoring symbols
Type[A].methods	: List[Existential[Method]]	List methods on type
Type.Ctor1.of[F]	Higher-kinded type constructor	For F[_] types

Expression manipulation

API	Signature	Description
Expr(value)	[A](value: A)(implicit Liftable[A]): Expr[A]	Lift literal value
Expr.quote { ... }	[A](body: => A): Expr[A]	Cross-platform quasiquote
Expr.splice(expr)	[A](expr: Expr[A]): A	Splice inside quote
expr.prettyPrint	: String	String representation of tree
expr.upcast[B]	[B](implicit ev: A <:< B): Expr[B]	Widen type (not narrow!)
expr.as_??	: Expr_??	Wrap into existential

Existentials (Expr_??, ??)

API	Signature	Description
expr.as_??	Expr[A] => Expr_??	Erase concrete type
Type[A].as_??	Type[A] => ??	Erase concrete type from Type
import e.Underlying	Brings Type[Underlying] into scope	Pattern: import e.{Underlying as T, value as v}
import e.value	Brings typed expression into scope	Used with Underlying alias

Lambda and val builders

API	Signature	Description
LambdaBuilder.of1[A]	(name: String): LambdaBuilder1[A]	1-arg lambda builder
LambdaBuilder.of2[A, B]	(name1: String, name2: String): LambdaBuilder2[A, B]	2-arg lambda builder
LambdaBuilder.of3[A, B, C]	(name1: String, name2: String, name3: String): LambdaBuilder3[A, B, C]	3-arg lambda builder
builder.traverse	(f: Expr[A] => MIO[Expr[B]]): MIO[Built1[A, B]]	Build with MIO body
builder.buildWith	(f: Expr[A] => Expr[B]): Expr[A => B]	Build with pure body
built.build[B]	: Expr[A => B]	Finalize lambda
ValDefBuilder.ofLazy[T]	(name: String): ValDefBuilder	lazy val builder
ValDefBuilder.ofDef1[A, B]	(name: String, argName: String): ValDefBuilder	def with 1 arg
ValDefBuilder.ofDef2[A, B, C]	(name: String, argName1: String, argName2: String): ValDefBuilder	def with 2 args
ValDefBuilder.ofDef3[A, B, C, D]	(name: String, a1: String, a2: String, a3: String): ValDefBuilder	def with 3 args
ValDefsCache.mlocal	: MLocal[ValDefsCache]	Create cache storage
cache.get0Ary[T]	(key: String): MIO[Option[Expr[T]]]	Get cached value
cache.get1Ary[A, B]	(key: String): MIO[Option[Expr[A] => Expr[B]]]	Get cached function
cache.get2Ary[A, B, C]	(key: String): MIO[Option[(Expr[A], Expr[B]) => Expr[C]]]	Get cached 2-arg function
cache.get3Ary[A, B, C, D]	(key: String): MIO[Option[(Expr[A], Expr[B], Expr[C]) => Expr[D]]]	Get cached 3-arg function
cache.buildCachedWith	(key: String, builder: ValDefBuilder)(body: ...): MIO[...]	Build and cache
cache.forwardDeclare	(key: String, builder: ValDefBuilder): MIO[Unit]	Forward-declare for recursion
cache.get	: MIO[ValDefsCache]	Extract accumulated cached defs
vals.toValDefs.use	(f: ... => Expr[A]): Expr[A]	Wrap expr in cached val defs block

Data model introspection

API	Signature	Description
ClassViewResult	Sealed trait: Compatible(value) / Incompatible(reason)	Return type of all .parse methods
result.toOption	: Option[V]	Some(value) for Compatible, None for Incompatible
result.toEither	: Either[String, V]	Right(value) for Compatible, Left(reason) for Incompatible
CaseClass.parse[A]	: ClassViewResult[CaseClass[A]]	Parse type as case class (excludes singletons)
cc.caseFieldValuesAt(expr)	: ListMap[String, Expr_??]	Read field values (encoder)
cc.primaryConstructor(map)	(Map[String, Expr_??]): Either[String, Expr[A]]	Construct from field map (decoder)
cc.construct[F](f)	(ConstructField[F] => F[Option[Expr[A]]])	Construct via callback (Scala 2 pitfall!)
SingletonValue.parse[A]	: ClassViewResult[SingletonValue[A]]	Parse type as singleton (case object, parameterless enum case, etc.)
SingletonValue.unapply(tpe)	(Type[A]): Option[SingletonValue[A]]	Pattern match extractor for singletons
sv.singletonExpr	: Expr[A]	The expression representing the singleton value
Enum.parse[A]	: ClassViewResult[Enum[A]]	Parse type as enum/sealed trait
enum.parMatchOn[F, R]	(expr)(handler): F[Expr[R]]	Exhaustive pattern match
NamedTuple.parse[A]	: ClassViewResult[NamedTuple[A]]	Parse type as named tuple (Scala 3.7+)
NamedTuple.unapply(tpe)	(Type[A]): Option[NamedTuple[A]]	Pattern match extractor for named tuples
nt.primaryConstructor	: Method.NoInstance[A]	Named tuple's primary constructor
nt.fields	: List[(String, ??)]	Named tuple field names and types
nt.construct[F](f)	(ConstructField[F], Accessible): F[Option[Expr[A]]]	Construct named tuple
param.tpe	: Existential[Type]	Parameter's type (existential)
param.index	: Int	Parameter position index
param.isImplicit / param.isByName	: Boolean	Implicit / by-name parameter flags
param.byNameUnderlying	: Option[??]	Underlying A of a by-name (=> A) param, both platforms (Hearth 0.3.1-48+)

Expression destructuring & DSL parsing (DestructuredExpr)

Parse selector/path lambdas (_.a.b.each.when[T]) and method references. See hearth-expr-parsing-dsl.

API	Signature	Description
DestructuredExpr.parse(e)	(Expr[A]): DestructuredExpr	Semantic parse; .collect { case ... } walks pre-order
DestructuredExpr.extractLambda(e)	strips Inlined/Block(DefDef…)	Get the lambda body
DestructuredExpr.extractFieldPath[S, A](p)	: Either[String, FieldPath]	FIELD-ONLY path _.a.b; Lefts on any method-call step
fieldPath.fieldNames	: List[String]	The field names of a FieldPath
DestructuredExpr.MethodCall	{ method: Method; applied: List[Applied] }	A resolved call node
MethodCall.AppliedInstance	{ value: DestructuredExpr }	Receiver
MethodCall.AppliedTypes	{ typeArgs: List[??] }	A [T] clause (S3 extension [C] THEN method [T] → take the LAST)
MethodCall.AppliedValues	{ args: List[DestructuredExpr] }	A (...) value clause
node.tpe / node.toUntypedExpr	: ?? / : UntypedExpr	Recover precise type: node.toUntypedExpr.asTyped[node.tpe.Underlying].as_??

Class building & matching (AnonymousInstance, MatchCase)

API	Signature	Description
AnonymousInstance.parse[A]	: ClassViewResult[AnonymousInstance[A]]	Synthesize a subtype of a trait/class
ai.mustOverride	: List[ClassifiedMethod]	Members the subtype must implement
ai.classParent	: Option[(??, List[Method])]	For a CLASS parent: its accessible constructors
ai.construct(ctor, ctorArgs, overrides)	(Option[Method], Arguments, Map[UntypedMethod, OverrideBody]): Either[NEV[String], Expr[A]]	Build it. For a class parent pass Some(ai.classParent.flatMap(_._2.headOption)) + dummy ctorArgs (e.g. summoned Defaultable/ClassTag)
OverrideContext	{ self: Expr_??; method; parameters: List[Expr_??]; returnType: ??; returnsThisType: Boolean }	Override body context. returnsThisType (Hearth 0.3.1-49+) ⇒ return octx.self uncast (do NOT cast to the widened returnType)
MatchCase.typeMatch[Sub]()	builds a case s: Sub => … arm	One arm of a type match
MatchCase.matchOn[S, R](scrutinee)(arms)	(NonEmptyVector[MatchCase]): Expr[R]	Emit the match. Non-exhaustive .when[Sub]: arm typeMatch[Sub] + catch-all typeMatch[Parent] (returns unchanged). S3 marks scrutinee @unchecked

Class lookup (Type.classOfType)

API	Signature	Description
Type.classOfType[A] / Type[A].getRuntimeClass	: Option[java.lang.Class[A]]	Runtime class at compile time — only for CLASSPATH types (not the current project)
(emit classOf[M])	—	NOT possible for abstract M; summon ClassTag[M] + .runtimeClass instead — see cross-compilation pitfall #35

Type extractors (std extensions)

API	Pattern	Description
IsCollection	Type[A] match { case IsCollection(ic) => ... }	Detect collection types
IsMap	Type[A] match { case IsMap(im) => ... }	Detect map types
IsOption	Type[A] match { case IsOption(io) => ... }	Detect optional types
IsValueType	Type[A] match { case IsValueType(ivt) => ... }	Detect value classes

Rules

API	Signature	Description
Rule.matched(value)	: Rule.Applicability[A]	Rule applies with result
Rule.yielded(reason)	: Rule.Applicability[Nothing]	Rule does not apply
Rules(r1, r2, ...)	(f): MIO[Either[reasons, A]]	Try rules in order, first match wins

Known gotchas

Gotcha	Details	Workaround
Path-dependent types in Expr.quote	import param.tpe.Underlying as F; Expr.quote { x.asInstanceOf[F] } fails on Scala 2	Use LambdaBuilder.of1[F] or runtime type witness
Macro-internal types leak	??, Expr_?? inside Expr.quote causes reification failures on Scala 2	Extract to val before Expr.quote
Array needs ClassTag	Array.empty[T] inside Expr.quote fails on Scala 2	Use List.empty[T] and ::
upcast only widens	expr.upcast[B] requires A <:< B; also needs Type[A] in scope	Use .asInstanceOf for narrowing
Raw quotes in LambdaBuilder	'{ } captures wrong Quotes on Scala 3	Use Expr.quote/Expr.splice
Generic macro wrapper	def helper[A](v: A) calling macro sees abstract A	Call macros with concrete types
Sibling splice isolation	Each Expr.splice in an Expr.quote gets its own Quotes context on Scala 3; types/exprs can't be shared between sibling splices	Derive everything in one runSafe, use LambdaBuilder to package as function Exprs, then splice references only
IsMap/IsCollection types need import	isMap.Key, isMap.Value, isMap.CtorResult need Type in scope	import isMap.{Key, Value, CtorResult} before Expr.quote
toValDefs.use wrapping scope	Wrapping individual lambdas with all cached defs causes unused-method warnings	Wrap the outermost expression that contains all references
ValDefsCache key is composite	Cache key = (String name, Seq[UntypedType] args, UntypedType returned). hashCode uses only the string; equals checks all three. Using Any as return type for all types causes cache collisions — different types sharing the same string key will overwrite each other	Use type-specific string keys (e.g., s"cached-decode-method:${Type[B].prettyPrint}") when the return type must be Any, OR use a type-specific return type (e.g., Either[Err, B]) in the ValDefBuilder
.asInstanceOf not erased for outer types	validated.asInstanceOf[Either[E, A]] fails at runtime — JVM checks the outer type (Either vs Validated). Only inner type parameters are erased: Left[E, String].asInstanceOf[Either[E, Int]] succeeds	Don't rely on .asInstanceOf to cross between different outer types like Either and Validated; use Any as the declared type and cast at call sites where you know the actual type
Phantom type param inference	schemaOf[A]: Schema (A not in signature) infers Nothing on Scala 2, Any on Scala 3	Guard against both: Type[A] =:= Type.of[Nothing]... || Type[A] =:= Type.of[Any]...
Scala 2 reification of refined types	DecodingFailure("msg", Nil): Either[DecodingFailure, A] inside nested Expr.quote fails on Scala 2 with scala.reflect.api.Trees errors. Even .asInstanceOf doesn't help — the reifier captures refined type trees	Avoid constructing such expressions in nested quotes. Use runtime helper methods or LambdaBuilder + fresh derivation to build the expression outside the problematic quote scope
MacroExtension ClassTag erasure	MacroExtension[A & B & C] — ClassTag only preserves first component (A). ServiceLoader discovery fails silently for extensions with custom traits in the intersection type	Use MacroExtension[A & B] (minimal intersection), do runtime match/asInstanceOf in extend() for the custom trait
Cross-quotes implicit Type unused warning	implicit val t: Type[X] = ... inside Expr.quote scope flagged as "is never used" — fatal with -Xfatal-warnings	Wrap in @scala.annotation.nowarn("msg=is never used") def myMethod = { implicit val t: ...; Expr.quote { ... } }
ProviderResult ≠ Option	IsOption.parse[A], IsCollection.parse[A], IsMap.parse[A] return ProviderResult, not Option — no .orElse chaining	Use Type[A] match { case IsOption(io) => ... case IsCollection(ic) => ... } pattern matching
IsMap before IsCollection ordering	Map <: Iterable, so IsCollection matches maps. If checked first, maps lose key information and are handled as flat collections	Always check IsMap before IsCollection in Type[A] match blocks
summonExprIgnoring OOM failure	Using Expr.summonImplicit[TC[A]] instead of summonExprIgnoring when target library has auto-derivation (e.g., Schema.derivedSchema) causes infinite macro expansion -> OOM -> SBT crash	Always use summonExprIgnoring with both own derived and library's auto-derivation methods in ignoredImplicits
Type.Ctor2.of[Function1].unapply wrong on Scala 3	Impl.unapply uses case '[HKT[a, b]] pattern matching which returns (Nothing, Boolean) instead of (Int, Boolean) for Function1[Int, Boolean] on Scala 3	Wrap with fromUntyped: val c = Type.Ctor2.of[Function1]; Type.Ctor2.fromUntyped[Function1](c.asUntyped)
primaryConstructor strict type check	primaryConstructor(Map[String, Expr_??]) checks Expr_??.Underlying <:< paramType. Passing Expr[Any].as_?? for a Function1[Any, R] field fails	Use helper method pattern: move Expr.quote with .asInstanceOf[Field] into a method where Field is a regular type param with implicit Type[Field]

Related skills

• ../hearth-documentation/ — finding Hearth docs, verifying APIs via MCP, Hearth source as reference
• ../hearth-def-caching/ — ValDefsCache detailed usage patterns
• ../hearth-lambda-builder/ — when to use LambdaBuilder vs alternatives
• ../hearth-standard-extensions/ — loading type extractors (IsCollection, IsMap, etc.)