From 3758c621ff000cfaaa420296cf1f2e99d73c6a07 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petrus=20Nguy=E1=BB=85n=20Th=C3=A1i=20H=E1=BB=8Dc?=
 <hoc081098@gmail.com>
Date: Sun, 8 Oct 2023 18:24:02 +0700
Subject: [PATCH] feat(chunked): add `Flow.chunked` as an alias to
 `Flow.bufferCount`.

Related issues:
- https://github.com/Kotlin/kotlinx.coroutines/issues/1290
- https://github.com/Kotlin/kotlinx.coroutines/issues/902
- https://github.com/Kotlin/kotlinx.coroutines/pull/1558
- https://github.com/Kotlin/kotlinx.coroutines/pull/2378
---
 CHANGELOG.md                                  | 12 +++++++++
 README.md                                     |  6 +++--
 api/FlowExt.api                               |  1 +
 .../com/hoc081098/flowext/bufferCount.kt      | 26 ++++++++++++++++---
 4 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2bc0f39e..49b1fa18 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Change Log
 
+## [Unreleased] - TODO
+
+### Changed
+
+- Update dependencies
+  - `Kotlin` to `1.9.10`.
+  - `Gradle` to `8.4`.
+
+### Added
+
+- Add `Flow.chunked` operator, it is an alias to `Flow.bufferCount` operator.
+
 ## [0.7.2] - Oct 7, 2023
 
 ### Changed
diff --git a/README.md b/README.md
index 63271bec..fa61c79a 100644
--- a/README.md
+++ b/README.md
@@ -120,11 +120,12 @@ dependencies {
   - [`timer`](#timer)
 
 - Intermediate operators
-  - [`bufferCount`](#buffercount)
+  - [`bufferCount`](#buffercount--chunked)
   - [`combine`](#combine)
   - [`cast`](#cast--castnotnull--castnullable--safeCast)
   - [`castNotNull`](#cast--castnotnull--castnullable--safeCast)
   - [`castNullable`](#cast--castnotnull--castnullable--safeCast)
+  - [`chunked`](#buffercount--chunked)
   - [`safeCast`](#cast--castnotnull--castnullable--safeCast)
   - [`concatWith`](#concatwith)
   - [`startWith`](#startwith)
@@ -157,13 +158,14 @@ dependencies {
   - [`throttleTime`](#throttletime)
   - [`withLatestFrom`](#withlatestfrom)
 
-#### bufferCount
+#### bufferCount / chunked
 
 - Similar to [RxJS bufferCount](https://rxjs.dev/api/operators/bufferCount)
 - Similar
   to [RxJava buffer](http://reactivex.io/RxJava/3.x/javadoc/io/reactivex/rxjava3/core/Observable.html#buffer-int-int-)
 
 Buffers the source `Flow` values until the size hits the maximum `bufferSize` given.
+Note, `chunked` is an alias to `bufferCount`.
 
 ```kotlin
 range(start = 0, count = 10)
diff --git a/api/FlowExt.api b/api/FlowExt.api
index c4c0b260..06efabd3 100644
--- a/api/FlowExt.api
+++ b/api/FlowExt.api
@@ -1,6 +1,7 @@
 public final class com/hoc081098/flowext/BufferCountKt {
 	public static final fun bufferCount (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
 	public static final fun bufferCount (Lkotlinx/coroutines/flow/Flow;II)Lkotlinx/coroutines/flow/Flow;
+	public static final fun chunked (Lkotlinx/coroutines/flow/Flow;I)Lkotlinx/coroutines/flow/Flow;
 }
 
 public final class com/hoc081098/flowext/CastKt {
diff --git a/src/commonMain/kotlin/com/hoc081098/flowext/bufferCount.kt b/src/commonMain/kotlin/com/hoc081098/flowext/bufferCount.kt
index af42719a..8b615324 100644
--- a/src/commonMain/kotlin/com/hoc081098/flowext/bufferCount.kt
+++ b/src/commonMain/kotlin/com/hoc081098/flowext/bufferCount.kt
@@ -27,18 +27,38 @@ package com.hoc081098.flowext
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.flow
 
+/**
+ * This function is an alias to [bufferCount] operator.
+ *
+ * @see bufferCount
+ */
+public fun <T> Flow<T>.chunked(bufferSize: Int): Flow<List<T>> = bufferCount(bufferSize)
+
 /**
  * Buffers the source [Flow] values until the size hits the maximum [bufferSize] given.
+ *
+ * Returns a [Flow] that emits buffers of items it collects from the current [Flow].
+ * It emits connected, non-overlapping buffers, each containing [bufferSize] items.
+ * When the current [Flow] completes, the resulting [Flow] emits the current buffer
+ * and propagates the complete event from the current [Flow].
+ * Note that if the current [Flow] throws an exception,
+ * that exception is passed on immediately without first emitting the buffer it is in the process of assembling.
+ *
  * @param bufferSize The maximum size of the buffer emitted.
  */
 public fun <T> Flow<T>.bufferCount(bufferSize: Int): Flow<List<T>> = bufferExact(bufferSize)
 
 /**
- * Buffers the source [Flow] values until the size hits the maximum [bufferSize] given.
+ * Buffers a number of values from the source [Flow] by [bufferSize]
+ * then emits the buffer and clears it, and starts a new buffer each [startBufferEvery] values.
+ *
+ * When the current [Flow] completes, the resulting [Flow] emits active buffers
+ * and propagates the complete event from the current [Flow].
+ * Note that if the current [Flow] throws an exception,
+ * that exception is passed on immediately without first emitting the buffer it is in the process of assembling.
  *
  * @param bufferSize The maximum size of the buffer emitted.
- * @param startBufferEvery Optional. Default is null.
- * Interval at which to start a new buffer.
+ * @param startBufferEvery Interval at which to start a new buffer.
  * For example if [startBufferEvery] is 2, then a new buffer will be started on every other value from the source.
  * A new buffer is started at the beginning of the source by default.
  */