8000 Add `.hoist`, interop typeclasses by arainko · Pull Request #143 · arainko/chanterelle · GitHub
[go: up one dir, main page]

Skip to content

Add .hoist, interop typeclasses - #143

Merged
arainko merged 101 commits into
mainfrom
map-on-tuples
Nov 12, 2026
Merged

arainko merged 101 commits into
mainfrom
map-on-tuples

Conversation

@arainko
@arainko arainko commented Nov 11, 2026 •
Copy link
Copy Markdown
Owner

So, what's new?

.hoist

Adds a new .hoist modifier which (taken straight from the docs):

Hoist a single field up to the top of the transformation (based on the Mode that's currently in scope).
This will also hoist each fallible field that it encouters on the path to the selected field.

Example:

import chanterelle.*

val tup = (field1 = 1, field2 = (nested = Some(1)))
Mode.FailFast.option {
  // evaluates to Some((field1 = 1, field2 = (nested = 1)))
  tup.transform(_.hoist(_.field2.nested))
}

Note that this transformation can be further customized with .local and .regional:

  • .local hoists the currently selected set of fields (like in the example above, note that nestedField1 wasn't hoisted)
  • .regional hoists ALL possible fields in a given region.

An example with .regional:

import chanterelle.*
val tup = (field1 = Some(1), field2 = Some(2), field3 = Some(3), nested = (nestedField1 = Some(1)))

Mode.FailFast.option {
// evaluates to Some(field1 = 1, field2 = 2, field3 = 3, nested = (nestedField1 = 1))
tup.transform(_.hoist.regional)
}

Transformation Mode[F]

Mode is a capability that provides the ability to 'bubble up' nested wrapped values (i.e. ones wrapped in an F) up to the top, for example:

import chanterelle.*

Mode.FailFast.option {
  // evaluates to Some((field1 = 1, field2 = 2, field3 = 3))
  (field1 = Some(1), field2 = Some(2), field3 = Some(3)).transform(_.hoist)
}

Modes come in 3 flavors:

  • Accumulating - the least powerful, able to model error accumulation but the the whole structure needs to be known from the get go (in other words, it can't hoist nested fallible fields like F[F[Int]]),
  • FailFast - the intermediate in terms of power - can't model error accumulation, but can hoist nested fallible fields,
  • Parallel - the most powerful, a mix of both Accumulating and FailFast. It can model both error accumulation AND hoisting of nested fallible fields.

Note that a Mode is not really a typeclass since there isn't really a single instance for each F (for example, instances for Either could come in all sorts of shapes - sometimes it's best to use FailFast, other times Accumulating).
Modes are usually provided at the callsite with their .apply method that puts them in the implicit scope of a block of code (just like in the example above).

Interop typeclasses

chanterelle.interop.Collection.IntoIterator

Defined as:

opaque type IntoIterator[Elem, Collection] = IsIterableOnce[Collection] { type A = Elem }

An interop typeclass representing types that can be converted into iterators.
Instances of Collection.IntoIterator are usually created with Collection.IntoIterator.from, for example:

  import chanterelle.interop.*

  given [Elem]: Collection.IntoIterator[Elem, List[Elem]] =
    Collection.IntoIterator.from(_.iterator)

  // or for a Map-shaped collection:
  given [Key, Value]: Collection.IntoIterator[(Key, Value), Map[Key, Value]] =
    Collection.IntoIterator.from(_.iterator)

This typeclass requires its 2 type parameters to be fully-applied and that's because it abstracts over both 'classic' collection shapes (i.e. ones with a single elem type constructor - like List)
and Map-shaped ones (i.e. with a two elem type constructor - like HashMap).

Note that chanterelle will only consider Coll[_] and Map[_, _] shaped instances (like the two aforementioned examples) when looking for candidates during the expansion of its .transform macro.

An instance of Collection.IntoIterator and Collection.Builder (or Collection.Builder.Fallible) will allow chanterelle to consider a given type as a collection type which enables some additional combinators inside the .transform macro, like the .each operator that 'cuts through' collection shapes when configuring transformations.

chanterelle.interop.Collection.Builder

Defined as:

opaque type Builder[Elem, Collection] <: Builder.Fallible[[a] =>> a, Elem, Collection] =
    Builder.Fallible[[a] =>> a, Elem, Collection]

An interop typeclass that abstracts over collection builders where the collectiom being built can be empty, its fallible sibling Collect.Builder.Fallible allows for
constructing collections that are meant to be non-empty (eg. like cats' NonEmptyList).

Custom instances of Collection.Builder are usually meant to be built using Collection.Builder.from as the starting point and then transforming it into our target type with .transform, for example:

import chanterelle.interop.*

case class MyVector[A](underlying: Vector[A])

given [Elem]: Collection.Builder[Elem, MyVector[Elem]] =
  Collection.Builder.from[Vector[Elem]].transform(MyVector.apply)

...or if we're operating on a custom Map:

import chanterelle.interop.*

case class MyMap[K, V](underlying: Map[K, V])

given [K, V]: Collection.Builder[(K, V), MyMap[K, V]] =
  Collection.Builder.from[Map[K, V]].transform(MyMap.apply)

An instance of Collection.Builder (or Collection.Builder.Fallible) and Collection.IntoIterator will allow chanterelle to consider a given type as a collection type which enables some additional combinators inside the .transform macro,
like the .each operator that 'cuts through' collection shapes when configuring transformations.

This typeclass requires its 2 type parameters to be fully-applied and that's because it abstracts over both 'classic' collection shapes (i.e. ones with a single elem type constructor - like List)
and Map-shaped ones (i.e. with a two elem type constructor - like HashMap).

Note that chanterelle will only consider Coll[_] and Map[_, _] shaped instances when looking for candidates during the expansion of its .transform macro.

chanterelle.interop.Collection.Builder.Fallible

Defined as:

opaque type Fallible[F[_], Elem, Collection] <: Factory[Elem, F[Collection]] = Factory[Elem, F[Collection]]

An interop typeclass that abstracts over collection builders where the collection being built cannot be empty (or their construction is fallible in any other way).

Custom instances of Collection.Builder.Fallible are usually meant to be built using Collection.Builder.from as the starting point and then transforming it into our target type with .transform and finishing up with .fallible, for example:

import chanterelle.interop.*

case class NonEmptyList[A] private (head: A, tail: List[A])

object NonEmptyList {
  def fromList[A](list: List[A]): Option[NonEmptyList[A]] = ???
}

given [Elem]: Collection.Builder.Fallible[Option, Elem, NonEmptyList[Elem]] =
  Collection.Builder
    .from[List[Elem]]
    .transform(NonEmptyList.fromList)
    .fallible

...or if we're operating on a custom Map:

import chanterelle.interop.*

case class NonEmptyMap[K, V] private (underlying: Map[K, V])

object NonEmptyMap {
  def fromMap[K, V](map: Map[K, V]): Option[NonEmptyMap[K, V]] = ???
}

given [K, V]: Collection.Builder.Fallible[Option, (K, V), NonEmptyMap[K, V]] =
  Collection.Builder
    .from[Map[K, V]]
    .transform(NonEmptyMap.fromMap)
    .fallible

This typeclass requires its 2 type parameters to be fully-applied and that's because it abstracts over both 'classic' collection shapes (i.e. ones with a single elem type constructor - like List)
and Map-shaped ones (i.e. with a two elem type constructor - like HashMap).

Note that chanterelle will only consider Coll[_] and Map[_, _] shaped instances when looking for candidates during the expansion of its .transform macro.

chanterelle.interop.Mappable

Defined as:

trait Mappable[F[_]] {
  def map[A, B](fa: F[A], f: A => B): F[B]
}

Mappable is an interop typeclass that allows chanterelle to cut through wrapper types (by allowing .element calls inside path selectors inside the .transform macro). For example:

import chanterelle.*
import chanterelle.interop.*

case class MyWrapper[A](value: A)

object MyWrapper {
  given Mappable[MyWrapper] with {
    def map[A, B](fa: MyWrapper[A], f: A => B): MyWrapper[B] = fa.copy(value = f(fa.value))
  }
}

val tup = (field = MyWrapper(1))
tup.transform(_.update(_.field.element)(_ + 1)) // evaluates to (field = MyWrapper(2)), the instance of `Mappable` allows for the `.element` call to go through

Other stuff

So apart from all of the above there's also some deprecated and some new path selectors (.element has been deprecated on Option[A] | Iterable[A] and replaces (respectively) with .some and .each.

arainko added 30 commits August 2, 2026 21:31
holy shit the quickly thrown together POC actually worked the first t… < 8000 button aria-expanded="false" aria-label="Commit message body" type="button" data-view-component="true" class="ellipsis-expander js-details-target btn"> …
…ime LMAOOO
eh
8000
…he end results (only when you explicitly USE those you'll get a wrapped result)
Comment thread checklist.md Resolved
Comment thread IDEAS.md Resolved
Comment thread README.md Resolved
@arainko
arainko merged commit 7ba3173 into main Nov 12, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0