Merge pull request #12 from devalexandre/feat/group

# Release Notes

## Go 1.24 Functional Helpers Update

This release updates `gofn` for Go 1.24 and expands the library with helpers focused on working with large slices of records in a cleaner, functional style.

### Highlights

- Updated the module target to Go 1.24.
- Modernized internal implementations with Go standard library helpers such as `slices`, `cmp`, and `math/rand/v2`.
- Added row-oriented aggregation helpers to reduce repetitive `for` and `if` blocks.
- Improved grouping behavior so `GroupBy` now stores the grouped rows instead of returning empty groups.
- Added more tests around grouping, aggregation, sorting, partitioning, pagination, and batching.

### New Array Helpers

The `array` package now includes:

- `GroupSumBy`: group rows by a key and sum a numeric value.
- `GroupSumByWhere`: filter, group, and sum in a single pass.
- `GroupCountBy`: count rows by key.
- `GroupReduceBy`: build custom aggregate summaries by key.
- `GroupStatsBy`: calculate count, sum, min, max, and average by key.
- `DistinctBy`: keep the first row for each key.
- `IndexBy`: create a map by key, keeping the last row for duplicate keys.
- `Partition`: split a slice into matching and non-matching rows.
- `SortBy`: sort by a selected ordered field without mutating the original slice.
- `Take`: return the first `n` rows.
- `Skip`: skip the first `n` rows.
- `Chunk`: split rows into batches.

### Chaining Support

The `array.Array[T]` chain API now includes practical methods for common record workflows:

- `GroupSumBy`
- `GroupSumByWhere`
- `GroupCountBy`
- `GroupStatsBy`
- `DistinctBy`
- `IndexBy`
- `Partition`
- `SortByString`
- `SortByFloat64`
- `Take`
- `Skip`
- `Chunk`

Because Go does not currently support method-specific type parameters, some chained helpers use practical fixed key/value types. For fully generic keys and numeric value types, use the package-level functions.

### Pipe Support

The `pipe` package now includes adapters for the new helpers:

- `GroupSumBy`
- `GroupSumByWhere`
- `GroupCountBy`
- `GroupReduceBy`
- `GroupStatsBy`
- `DistinctBy`
- `IndexBy`
- `Partition`
- `SortBy`
- `Take`
- `Skip`
- `Chunk`

### Example

```go
type Item struct {
	Name  string
	Price float64
	Qty   int
}

items := []Item{
	{"Item 1", 10.0, 1},
	{"Item 4", 40.0, 10},
	{"Item 4", 40.0, 15},
	{"Item 4", 40.0, 25},
}

totalByName := array.GroupSumBy(items,
	func(item Item) string { return item.Name },
	func(item Item) float64 { return item.Price },
)

fmt.Println(totalByName["Item 4"]) // 120
```

For custom summaries:

```go
type Summary struct {
	TotalPrice float64
	TotalQty   int
}

summaryByName := array.GroupReduceBy(items,
	func(item Item) string {
		return item.Name
	},
	func(acc Summary, item Item) Summary {
		acc.TotalPrice += item.Price
		acc.TotalQty += item.Qty
		return acc
	},
)

fmt.Println(summaryByName["Item 4"]) // {120 50}
```

### Compatibility

The existing public APIs remain available. The changes are intended to preserve the current usage style while adding new helpers and improving correctness.

One behavioral fix to note: `GroupBy` now returns populated groups. Previous behavior created the group keys but did not append the matching rows.

### Verification

The release was validated with:

```sh
go test -count=1 ./...
go vet ./...
```

Local coverage after these changes is `88.7%`.

Author: devalexandre

.github/workflows/coverage.yml

@@ -12,17 +12,17 @@ jobs:
     name: Update coverage badge
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
           fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
 
       - name: Setup go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          go-version: '1.18'
+          go-version: '1.24.x'
 
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           path: ~/go/pkg/mod
           key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
@@ -58,4 +58,4 @@ jobs:
         uses: ad-m/github-push-action@master
         with:
           github_token: ${{ github.token }}
-          branch: ${{ github.head_ref }}
+          branch: ${{ github.head_ref }}

.github/workflows/go.yml

@@ -14,12 +14,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Set up Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v5
       with:
-        go-version: 1.18
+        go-version: '1.24.x'
 
     - name: Test
       run: go test -v ./...

README.md

@@ -1,5 +1,5 @@
 # gofn
-![Coverage](https://img.shields.io/badge/Coverage-87.7%25-brightgreen)
+![Coverage](https://img.shields.io/badge/Coverage-88.7%25-brightgreen)
 [![Go](https://github.com/devalexandre/gofn/actions/workflows/go.yml/badge.svg)](https://github.com/devalexandre/gofn/actions/workflows/go.yml)
 
 # library to use golang functional
@@ -31,6 +31,16 @@
         - [array.Shift](#arrayshift)
         - [array.Sort](#arraysort)
         - [array.GroupBy](#arraygroupby)
+        - [array.GroupSumBy](#arraygroupsumby)
+        - [array.GroupSumByWhere](#arraygroupsumbywhere)
+        - [array.GroupCountBy](#arraygroupcountby)
+        - [array.GroupReduceBy](#arraygroupreduceby)
+        - [array.GroupStatsBy](#arraygroupstatsby)
+        - [array.DistinctBy](#arraydistinctby)
+        - [array.IndexBy](#arrayindexby)
+        - [array.Partition](#arraypartition)
+        - [array.SortBy](#arraysortby)
+        - [array.Take, array.Skip, array.Chunk](#arraytake-arrayskip-arraychunk)
     - [chaining functions](#chaining-functions)
 
 
@@ -379,6 +389,160 @@ type Itens struct {
 	fmt.Println(len(grouped)) // 4
 
 ```
+
+### array.GroupSumBy
+Group items by a key and sum a numeric value for each group.
+
+```go
+type Itens struct {
+	Name        string
+	Price       float64
+	Description string
+	Qty         int
+}
+
+itens := []Itens{
+	{"Item 1", 10.0, "Description 1", 1},
+	{"Item 2", 20.0, "Description 2", 2},
+	{"Item 3", 30.0, "Description 3", 3},
+	{"Item 4", 40.0, "Description 4", 10},
+	{"Item 4", 40.0, "Description 4", 15},
+	{"Item 4", 40.0, "Description 4", 25},
+}
+
+priceByName := array.GroupSumBy(itens,
+	func(item Itens) string { return item.Name },
+	func(item Itens) float64 { return item.Price },
+)
+
+qtyByName := array.GroupSumBy(itens,
+	func(item Itens) string { return item.Name },
+	func(item Itens) int { return item.Qty },
+)
+
+fmt.Println(priceByName["Item 4"]) // 120
+fmt.Println(qtyByName["Item 4"])   // 50
+```
+
+### array.GroupSumByWhere
+Filter, group and sum in one pass.
+
+```go
+priceByName := array.GroupSumByWhere(itens,
+	func(item Itens) bool { return item.Qty > 3 },
+	func(item Itens) string { return item.Name },
+	func(item Itens) float64 { return item.Price },
+)
+
+fmt.Println(priceByName["Item 4"]) // 120
+```
+
+### array.GroupCountBy
+Count rows by a key.
+
+```go
+countByName := array.GroupCountBy(itens, func(item Itens) string {
+	return item.Name
+})
+
+fmt.Println(countByName["Item 4"]) // 3
+```
+
+### array.GroupReduceBy
+Build custom summaries by group.
+
+```go
+type Summary struct {
+	TotalPrice float64
+	TotalQty   int
+}
+
+summaryByName := array.GroupReduceBy(itens,
+	func(item Itens) string {
+		return item.Name
+	},
+	func(acc Summary, item Itens) Summary {
+		acc.TotalPrice += item.Price
+		acc.TotalQty += item.Qty
+		return acc
+	},
+)
+
+fmt.Println(summaryByName["Item 4"]) // {120 50}
+```
+
+### array.GroupStatsBy
+Calculate count, sum, min, max and average by group.
+
+```go
+statsByName := array.GroupStatsBy(itens,
+	func(item Itens) string { return item.Name },
+	func(item Itens) float64 { return item.Price },
+)
+
+fmt.Println(statsByName["Item 4"].Count) // 3
+fmt.Println(statsByName["Item 4"].Sum)   // 120
+fmt.Println(statsByName["Item 4"].Avg)   // 40
+```
+
+### array.DistinctBy
+Keep the first row for each key.
+
+```go
+uniqueByName := array.DistinctBy(itens, func(item Itens) string {
+	return item.Name
+})
+
+fmt.Println(len(uniqueByName)) // 4
+```
+
+### array.IndexBy
+Create a map by key. If a key repeats, the last row wins.
+
+```go
+itemByName := array.IndexBy(itens, func(item Itens) string {
+	return item.Name
+})
+
+fmt.Println(itemByName["Item 4"].Qty) // 25
+```
+
+### array.Partition
+Split rows into matched and unmatched slices.
+
+```go
+highQty, lowQty := array.Partition(itens, func(item Itens) bool {
+	return item.Qty > 3
+})
+
+fmt.Println(len(highQty)) // 3
+fmt.Println(len(lowQty))  // 3
+```
+
+### array.SortBy
+Sort rows by a selected field without mutating the original slice.
+
+```go
+byQty := array.SortBy(itens, func(item Itens) int {
+	return item.Qty
+})
+
+fmt.Println(byQty[0].Qty) // 1
+```
+
+### array.Take, array.Skip, array.Chunk
+Use these helpers for pagination and batch processing.
+
+```go
+firstPage := array.Take(itens, 2)
+nextRows := array.Skip(itens, 2)
+batches := array.Chunk(itens, 2)
+
+fmt.Println(len(firstPage)) // 2
+fmt.Println(len(nextRows))  // 4
+fmt.Println(len(batches))   // 3
+```
+
 ## chaining functions
 
 You can chain the functions together.
@@ -398,3 +562,60 @@ data := array.Array[int]{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
     fmt.Println(a) // [4 8 12 16 20]
 
 ```
+
+You can also group and sum values after filtering.
+
+```go
+type Itens struct {
+	Name        string
+	Price       float64
+	Description string
+	Qty         int
+}
+
+data := array.Array[Itens]{
+	{"Item 1", 10.0, "Description 1", 1},
+	{"Item 2", 20.0, "Description 2", 2},
+	{"Item 3", 30.0, "Description 3", 3},
+	{"Item 4", 40.0, "Description 4", 10},
+	{"Item 4", 40.0, "Description 4", 15},
+	{"Item 4", 40.0, "Description 4", 25},
+}
+
+priceByName := data.
+	Filter(func(item Itens) bool {
+		return item.Qty > 3
+	}).
+	GroupSumBy(
+		func(item Itens) string { return item.Name },
+		func(item Itens) float64 { return item.Price },
+	)
+
+fmt.Println(priceByName["Item 4"]) // 120
+```
+
+Some helpers are also available in chain form.
+
+```go
+countByName := data.GroupCountBy(func(item Itens) string {
+	return item.Name
+})
+
+statsByName := data.GroupStatsBy(
+	func(item Itens) string { return item.Name },
+	func(item Itens) float64 { return item.Price },
+)
+
+uniqueByName := data.DistinctBy(func(item Itens) string {
+	return item.Name
+})
+
+highQty, lowQty := data.Partition(func(item Itens) bool {
+	return item.Qty > 3
+})
+
+page := data.
+	SortByFloat64(func(item Itens) float64 { return item.Price }).
+	Skip(10).
+	Take(10)
+```

array/array.go

@@ -61,3 +61,58 @@ func (a Array[T]) Sort(f func(i, j int) bool) Array[T] {
 func (a Array[T]) GroupBy(f func(T) string) map[string][]T {
 	return GroupBy(a, f)
 }
+
+func (a Array[T]) GroupSumBy(key func(T) string, value func(T) float64) map[string]float64 {
+	return GroupSumBy(a, key, value)
+}
+
+func (a Array[T]) GroupSumByWhere(where func(T) bool, key func(T) string, value func(T) float64) map[string]float64 {
+	return GroupSumByWhere(a, where, key, value)
+}
+
+func (a Array[T]) GroupCountBy(key func(T) string) map[string]int {
+	return GroupCountBy(a, key)
+}
+
+func (a Array[T]) GroupStatsBy(key func(T) string, value func(T) float64) map[string]GroupStats[float64] {
+	return GroupStatsBy(a, key, value)
+}
+
+func (a Array[T]) DistinctBy(key func(T) string) Array[T] {
+	return DistinctBy(a, key)
+}
+
+func (a Array[T]) IndexBy(key func(T) string) map[string]T {
+	return IndexBy(a, key)
+}
+
+func (a Array[T]) Partition(f func(T) bool) (Array[T], Array[T]) {
+	matched, unmatched := Partition(a, f)
+	return matched, unmatched
+}
+
+func (a Array[T]) SortByString(key func(T) string) Array[T] {
+	return SortBy(a, key)
+}
+
+func (a Array[T]) SortByFloat64(key func(T) float64) Array[T] {
+	return SortBy(a, key)
+}
+
+func (a Array[T]) Take(n int) Array[T] {
+	return Take(a, n)
+}
+
+func (a Array[T]) Skip(n int) Array[T] {
+	return Skip(a, n)
+}
+
+func (a Array[T]) Chunk(size int) []Array[T] {
+	chunks := Chunk(a, size)
+	result := make([]Array[T], len(chunks))
+	for i, chunk := range chunks {
+		result[i] = chunk
+	}
+
+	return result
+}