CU-9rr532 Deprecate k wrappers (#340)

* Deprecate KList
* Deprecate MapK
* Deprecate SequenceK
* Deprecate SetK
* Deprecate SortedMapK

arrow-core-data/src/main/kotlin/arrow/core/ListK.kt

@@ -6,6 +6,10 @@ import arrow.typeclasses.Applicative
 import arrow.typeclasses.Show
 import arrow.typeclasses.ShowDeprecation
 
+const val ListKDeprecation =
+  "ListK is deprecated along side Higher Kinded Types in Arrow. Prefer to simply use kotlin.collections.List instead." +
+    "Arrow provides extension functions on Iterable to cover all the behavior defined for ListK as extension functions"
+
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
@@ -138,6 +142,7 @@ inline fun <A> ListKOf<A>.fix(): ListK<A> =
  * ```
  *
  */
+@Deprecated(ListKDeprecation)
 data class ListK<out A>(private val list: List<A>) : ListKOf<A>, List<A> by list {
 
   fun <B> flatMap(f: (A) -> ListKOf<B>): ListK<B> = list.flatMap { f(it).fix().list }.k()
@@ -446,8 +451,10 @@ data class ListK<out A>(private val list: List<A>) : ListKOf<A>, List<A> by list
 
   companion object {
 
+    @Deprecated(ListKDeprecation, ReplaceWith("listOf<A>(a)"))
     fun <A> just(a: A): ListK<A> = listOf(a).k()
 
+    @Deprecated(ListKDeprecation, ReplaceWith("emptyList<A>()"))
     fun <A> empty(): ListK<A> = emptyList<A>().k()
 
     @Suppress("UNCHECKED_CAST")
@@ -468,14 +475,17 @@ data class ListK<out A>(private val list: List<A>) : ListKOf<A>, List<A> by list
       }
     }
 
+    @Deprecated(ListKDeprecation, ReplaceWith("tailRecMIterable(a, f)"))
     fun <A, B> tailRecM(a: A, f: (A) -> Kind<ForListK, Either<A, B>>): ListK<B> {
       val buf = ArrayList<B>()
       go(buf, f, f(a).fix())
       return ListK(buf)
     }
 
+    @Deprecated(ListKDeprecation, ReplaceWith("a.align(b, fa)"))
     fun <A, B, C> alignWith(a: ListK<A>, b: ListK<B>, fa: (Ior<A, B>) -> C): ListK<C> = align(a, b).map(fa)
 
+    @Deprecated(ListKDeprecation, ReplaceWith("a.align(b)"))
     fun <A, B> align(a: ListK<A>, b: ListK<B>): ListK<Ior<A, B>> = alignRec(a, b).k()
 
     private fun <X, Y> alignRec(ls: List<X>, rs: List<Y>): List<Ior<X, Y>> = when {
@@ -605,10 +615,13 @@ data class ListK<out A>(private val list: List<A>) : ListKOf<A>, List<A> by list
   }
 }
 
+@Deprecated(ListKDeprecation, ReplaceWith("this + y"))
 fun <A> ListKOf<A>.combineK(y: ListKOf<A>): ListK<A> =
   (fix() + y.fix()).k()
 
+@Deprecated(ListKDeprecation, ReplaceWith("this"))
 fun <A> List<A>.k(): ListK<A> = ListK(this)
 
+@Deprecated(ListKDeprecation, ReplaceWith("listOf(elements)"))
 fun <A> listKOf(vararg elements: A): ListK<A> =
   listOf(*elements).k()

arrow-core-data/src/main/kotlin/arrow/core/MapK.kt

@@ -6,6 +6,10 @@ import arrow.typeclasses.Applicative
 import arrow.typeclasses.Show
 import arrow.typeclasses.ShowDeprecation
 
+const val MapKDeprecation =
+  "MapK is deprecated along side Higher Kinded Types in Arrow. Prefer to simply use kotlin.collections.Map instead." +
+    "Arrow provides extension functions on kotlin.collections.Map to cover all the behavior defined for MapK"
+
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
@@ -23,8 +27,10 @@ import arrow.typeclasses.ShowDeprecation
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
-)inline fun <K, A> MapKOf<K, A>.fix(): MapK<K, A> = this as MapK<K, A>
+)
+inline fun <K, A> MapKOf<K, A>.fix(): MapK<K, A> = this as MapK<K, A>
 
+@Deprecated(MapKDeprecation)
 data class MapK<K, out A>(private val map: Map<K, A>) : MapKOf<K, A>, Map<K, A> by map {
 
   fun <B> map(f: (A) -> B): MapK<K, B> = this.map.map { it.key to f(it.value) }.toMap().k()
@@ -205,6 +211,7 @@ data class MapK<K, out A>(private val map: Map<K, A>) : MapKOf<K, A>, Map<K, A>
   }
 }
 
+@Deprecated(MapKDeprecation, ReplaceWith("this"))
 fun <K, A> Map<K, A>.k(): MapK<K, A> = MapK(this)
 
 @Deprecated("Deprecated, use nullable instead", ReplaceWith("Tuple2<K, A>>?.let { ... }"))
@@ -214,14 +221,17 @@ fun <K, A> Option<Tuple2<K, A>>.k(): MapK<K, A> =
     is None -> emptyMap<K, A>().k()
   }
 
+@Deprecated("Applicative is deprecated use sequenceEither or sequenceValidated on Map instead.")
 fun <K, V, G> MapKOf<K, Kind<G, V>>.sequence(GA: Applicative<G>): Kind<G, MapK<K, V>> =
   fix().traverse(GA, ::identity)
 
+@Deprecated(MapKDeprecation, ReplaceWith("this.map { it.key to it.value }.toMap()"))
 fun <K, A> List<Map.Entry<K, A>>.k(): MapK<K, A> = this.map { it.key to it.value }.toMap().k()
 
 @Deprecated("Deprecated, use nullable instead", ReplaceWith("map[k]?.let { ... }"))
 fun <K, A> Map<K, A>.getOption(k: K): Option<A> = Option.fromNullable(this[k])
 
+@Deprecated(MapKDeprecation, ReplaceWith("this + Pair(k, value)"))
 fun <K, A> MapK<K, A>.updated(k: K, value: A): MapK<K, A> = (this + (k to value)).k()
 
 @Deprecated("Available for binary compat", level = DeprecationLevel.HIDDEN)
@@ -231,12 +241,6 @@ fun <K, A, B> Map<K, A>.foldLeft(b: Map<K, B>, f: (Map<K, B>, Map.Entry<K, A>) -
   return result
 }
 
-inline fun <K, A, B> Map<K, A>.foldLeft(b: B, f: (B, Map.Entry<K, A>) -> B): B {
-  var result = b
-  this.forEach { result = f(result, it) }
-  return result
-}
-
 internal fun <K, A> Pair<K, A>?.asIterable(): Iterable<Pair<K, A>> =
   when (this) {
     null -> emptyList()
@@ -247,8 +251,6 @@ internal fun <K, A> Pair<K, A>?.asIterable(): Iterable<Pair<K, A>> =
 fun <K, A, B> Map<K, A>.foldRight(b: Map<K, B>, f: (Map.Entry<K, A>, Map<K, B>) -> Map<K, B>): Map<K, B> =
   this.entries.reversed().k().foldLeft(b) { x, y: Map.Entry<K, A> -> f(y, x) }
 
-inline fun <K, A, B> Map<K, A>.foldRight(b: B, f: (Map.Entry<K, A>, B) -> B): B =
-  this.entries.reversed().k().foldLeft(b) { x, y: Map.Entry<K, A> -> f(y, x) }
-
+@Deprecated("Tuple2 is deprecated in favor of Kotlin's Pair", ReplaceWith("tuple.map { (k, v) -> Pair(k, v) }.toMap()"))
 fun <K, V> mapOf(vararg tuple: Tuple2<K, V>): MapK<K, V> =
   if (tuple.isNotEmpty()) tuple.map { it.a to it.b }.toMap().k() else emptyMap<K, V>().k()

arrow-core-data/src/main/kotlin/arrow/core/SequenceK.kt

@@ -6,6 +6,10 @@ import arrow.typeclasses.Applicative
 import arrow.typeclasses.Show
 import arrow.typeclasses.ShowDeprecation
 
+const val SequenceKDeprecation =
+  "SequenceK is deprecated along side Higher Kinded Types in Arrow. Prefer to simply use kotlin.sequences.Sequence instead." +
+    "Arrow provides extension functions on kotlin.sequences.Sequence to cover all the behavior defined for SequenceK"
+
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
@@ -27,6 +31,7 @@ typealias SequenceKOf<A> = arrow.Kind<ForSequenceK, A>
 inline fun <A> SequenceKOf<A>.fix(): SequenceK<A> =
   this as SequenceK<A>
 
+@Deprecated(SequenceKDeprecation)
 data class SequenceK<out A>(val sequence: Sequence<A>) : SequenceKOf<A>, Sequence<A> by sequence {
 
   fun <B> flatMap(f: (A) -> SequenceKOf<B>): SequenceK<B> = sequence.flatMap { f(it).fix().sequence }.k()
@@ -100,8 +105,10 @@ data class SequenceK<out A>(val sequence: Sequence<A>) : SequenceKOf<A>, Sequenc
 
   companion object {
 
+    @Deprecated(SequenceKDeprecation, ReplaceWith("emptySequence<A>()"))
     fun <A> empty(): SequenceK<A> = emptySequence<A>().k()
 
+    @Deprecated(SequenceKDeprecation, ReplaceWith("sequenceOf<A>(a)"))
     fun <A> just(a: A): SequenceK<A> = sequenceOf(a).k()
 
     fun <B, C, D> mapN(
@@ -223,6 +230,7 @@ data class SequenceK<out A>(val sequence: Sequence<A>) : SequenceKOf<A>, Sequenc
         }
       }
 
+    @Deprecated("tailRecM for Sequence is a terminal operator that breaks the Sequence semantics and will be no longer be supported")
     fun <A, B> tailRecM(a: A, f: (A) -> SequenceKOf<Either<A, B>>): SequenceK<B> {
       tailrec fun <A, B> go(
         buf: MutableList<B>,
@@ -250,36 +258,15 @@ data class SequenceK<out A>(val sequence: Sequence<A>) : SequenceKOf<A>, Sequenc
       go(buf, f, f(a).fix())
       return SequenceK(buf.asSequence())
     }
-
-    fun <A, B> tailRecM(a: A, f: (A) -> Sequence<Either<A, B>>): Sequence<B> {
-      tailrec fun <A, B> go(
-        buf: MutableList<B>,
-        f: (A) -> Sequence<Either<A, B>>,
-        v: Sequence<Either<A, B>>
-      ) {
-        if (v.any()) {
-          when (val head: Either<A, B> = v.first()) {
-            is Either.Right -> {
-              buf += head.b
-              go(buf, f, v.drop(1))
-            }
-            is Either.Left -> {
-              go(buf, f, (f(head.a) + v.drop(1)))
-            }
-          }
-        }
-      }
-
-      val buf = mutableListOf<B>()
-      go(buf, f, f(a))
-      return buf.asSequence()
-    }
   }
 }
 
+@Deprecated(SequenceKDeprecation, ReplaceWith("this + y"))
 fun <A> SequenceKOf<A>.combineK(y: SequenceKOf<A>): SequenceK<A> = (fix().sequence + y.fix().sequence).k()
 
+@Deprecated("Applicative is deprecated use sequenceEither or sequenceValidated on Sequence instead.")
 fun <A, G> SequenceKOf<Kind<G, A>>.sequence(GA: Applicative<G>): Kind<G, SequenceK<A>> =
   fix().traverse(GA, ::identity)
 
+@Deprecated(SequenceKDeprecation, ReplaceWith("this"))
 fun <A> Sequence<A>.k(): SequenceK<A> = SequenceK(this)

arrow-core-data/src/main/kotlin/arrow/core/SetK.kt

@@ -4,6 +4,10 @@ import arrow.KindDeprecation
 import arrow.typeclasses.Show
 import arrow.typeclasses.ShowDeprecation
 
+const val SetKDeprecation =
+  "SetK is deprecated along side Higher Kinded Types in Arrow. Prefer to simply use kotlin.collections.Set instead." +
+    "Arrow provides extension functions on Iterable and kotlin.collections.Set to cover all the behavior defined for SetK"
+
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
@@ -18,9 +22,11 @@ import arrow.typeclasses.ShowDeprecation
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
-)inline fun <A> SetKOf<A>.fix(): SetK<A> =
+)
+inline fun <A> SetKOf<A>.fix(): SetK<A> =
   this as SetK<A>
 
+@Deprecated(SetKDeprecation)
 data class SetK<out A>(private val set: Set<A>) : SetKOf<A>, Set<A> by set {
 
   fun <B> foldLeft(b: B, f: (B, A) -> B): B = fold(b, f)
@@ -48,16 +54,18 @@ data class SetK<out A>(private val set: Set<A>) : SetKOf<A>, Set<A> by set {
 
   companion object {
 
+    @Deprecated(SetKDeprecation, ReplaceWith("setOf(a)"))
     fun <A> just(a: A): SetK<A> = setOf(a).k()
 
+    @Deprecated(SetKDeprecation, ReplaceWith("emptySet<Nothing>()"))
     fun empty(): SetK<Nothing> = empty
 
     private val empty = emptySet<Nothing>().k()
   }
 }
 
-@Deprecated("Kind is deprecated, and will be removed in 0.13.0. Please use one of the provided concrete methods instead")
+@Deprecated(SetKDeprecation, ReplaceWith("this + y"))
 fun <A> SetKOf<A>.combineK(y: SetKOf<A>): SetK<A> = (fix() + y.fix()).k()
 
-@Deprecated("Kind is deprecated, and will be removed in 0.13.0. Please use one of the provided concrete methods instead")
+@Deprecated(SetKDeprecation, ReplaceWith("this"))
 fun <A> Set<A>.k(): SetK<A> = SetK(this)

arrow-core-data/src/main/kotlin/arrow/core/SortedMap.kt

@@ -1,3 +1,4 @@
 package arrow.core
 
+@Deprecated("Arrow will no longer provide a typealias for SortedMap", ReplaceWith("java.util.SortedMap<K, V>"))
 typealias SortedMap<K, V> = java.util.SortedMap<K, V>

arrow-core-data/src/main/kotlin/arrow/core/SortedMapK.kt

@@ -7,6 +7,10 @@ import arrow.typeclasses.Show
 import arrow.typeclasses.ShowDeprecation
 import kotlin.collections.flatMap
 
+const val SortedMapKDeprecation =
+  "SortedMapK is deprecated along side Higher Kinded Types in Arrow. Prefer to simply use java.util.SortedMap instead." +
+    "Arrow provides extension functions on java.util.SortedMap and kotlin.collections.Map to cover all the behavior defined for SortedMapK"
+
 @Deprecated(
   message = KindDeprecation,
   level = DeprecationLevel.WARNING
@@ -35,6 +39,7 @@ typealias SortedMapKKindedJ<A, B> = arrow.HkJ2<ForSortedMapK, A, B>
 inline fun <A, B> SortedMapKOf<A, B>.fix(): SortedMapK<A, B> where A : kotlin.Comparable<A> =
   this as SortedMapK<A, B>
 
+@Deprecated(SortedMapKDeprecation)
 data class SortedMapK<A : Comparable<A>, B>(private val map: SortedMap<A, B>) : SortedMapKOf<A, B>, SortedMapKKindedJ<A, B>, SortedMap<A, B> by map {
 
   fun <C> map(f: (B) -> C): SortedMapK<A, C> =
@@ -97,27 +102,29 @@ data class SortedMapK<A : Comparable<A>, B>(private val map: SortedMap<A, B>) :
   companion object
 }
 
+@Deprecated(SortedMapKDeprecation, ReplaceWith("this"))
 fun <A : Comparable<A>, B> SortedMap<A, B>.k(): SortedMapK<A, B> = SortedMapK(this)
 
+@Deprecated(SortedMapKDeprecation, ReplaceWith("this.fold({ sortedMapOf<A, B>() }, { (k, v) -> sortedMapOf(k to v) })"))
 fun <A : Comparable<A>, B> Option<Tuple2<A, B>>.k(): SortedMapK<A, B> = this.fold(
   { sortedMapOf<A, B>().k() },
   { mapEntry -> sortedMapOf(mapEntry.a to mapEntry.b).k() }
 )
 
+@Deprecated(SortedMapKDeprecation)
 fun <K : Comparable<K>, V, G> SortedMapKOf<K, Kind<G, V>>.sequence(GA: Applicative<G>): Kind<G, SortedMapK<K, V>> =
   fix().traverse(GA, ::identity)
 
+@Deprecated(SortedMapKDeprecation, ReplaceWith("this.map { (k, v) -> Pair(k, v) }.toMap().toSortedMap()"))
 fun <A : Comparable<A>, B> List<Map.Entry<A, B>>.k(): SortedMapK<A, B> =
   this.map { it.key to it.value }.toMap().toSortedMap().k()
 
+@Deprecated(SortedMapKDeprecation, ReplaceWith("Option.fromNullable(this[k])", "arrow.core.Option"))
 fun <A, B> SortedMap<A, B>.getOption(k: A): Option<B> = Option.fromNullable(this[k])
 
-fun <A : Comparable<A>, B> SortedMapK<A, B>.updated(k: A, value: B): SortedMapK<A, B> {
-  val sortedMutableMap = this.toSortedMap()
-  sortedMutableMap.put(k, value)
-
-  return sortedMutableMap.k()
-}
+@Deprecated(SortedMapKDeprecation, ReplaceWith("this.apply { put(k, value) }"))
+fun <A : Comparable<A>, B> SortedMapK<A, B>.updated(k: A, value: B): SortedMapK<A, B> =
+  this.apply { put(k, value) }
 
 fun <A, B, C> SortedMap<A, B>.foldLeft(b: SortedMap<A, C>, f: (SortedMap<A, C>, Map.Entry<A, B>) -> SortedMap<A, C>): SortedMap<A, C> {
   var result = b

arrow-core-data/src/main/kotlin/arrow/core/map.kt

@@ -338,3 +338,12 @@ private class MapMonoid<K, A>(private val SG: Semigroup<A>) : Monoid<Map<K, A>>
   override fun Map<K, A>.combine(b: Map<K, A>): Map<K, A> =
     combine(SG, b)
 }
+
+inline fun <K, A, B> Map<K, A>.foldRight(b: B, f: (Map.Entry<K, A>, B) -> B): B =
+  this.entries.reversed().k().foldLeft(b) { x, y: Map.Entry<K, A> -> f(y, x) }
+
+inline fun <K, A, B> Map<K, A>.foldLeft(b: B, f: (B, Map.Entry<K, A>) -> B): B {
+  var result = b
+  this.forEach { result = f(result, it) }
+  return result
+}