feat: add group functions

[devalexandre]

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

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:

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:

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

Local coverage after these changes is 88.7%.