feat: introduce slice-backed v3 API

[cmilesio]

What

Collection v3 is now a Go 1.27-native, slice-backed API at github.com/goforj/collection/v3.

Slice[T] is a named slice, so it works directly with len, indexing, slicing, range, standard-library helpers, and iterator adapters. Generic methods now support type-changing fluent operations, while mutating hot paths remain explicit and allocation-free through Transform and Retain.

Every exported function and method has an executable example generated from its GoDoc. The complete method-by-method migration, including removed APIs and ownership changes, is in MIGRATING_TO_V3.md.

Module path

Before

import "github.com/goforj/collection"

After

import "github.com/goforj/collection/v3"

Items

Before

first := values.Items()[0]

After

first := values[0]

ItemsCopy

Before

copied := values.ItemsCopy()

After

copied := values.Clone()

Map

Before

values.Map(func(value int) int { return value * 2 })
// values is mutated

After

labels := values.Map(strconv.Itoa)
// values is unchanged

Transform

Before

values.Map(func(value int) int { return value * 2 })

After

values.Transform(func(value int) int { return value * 2 })

Filter

Before

values.Filter(func(value int) bool { return value%2 == 0 })
// values is compacted in place

After

evens := values.Filter(func(value int) bool { return value%2 == 0 })
// values is unchanged

Retain

Before

values.Filter(func(value int) bool { return value%2 == 0 })

After

values = values.Retain(func(value int) bool { return value%2 == 0 })

Concat

Before

values.Concat([]int{4, 5})
// values is mutated

After

combined := values.Concat([]int{4, 5})
// values is unchanged; combined owns independent storage

Why

Go 1.27 generic methods remove the compromise that shaped v2. The API can stay fluent while changing element types, without wrapper accessors, duplicate free functions, or specialized numeric collection types.

The result feels like ordinary Go: use native slice syntax when that is clearest, fluent methods when they improve readability, and explicit in-place methods in hot paths. v2 remains available for existing consumers, while v3 provides the clean major-version boundary needed to make those semantics consistent.

The benchmark suite now restores mutable input on every measured iteration for both implementations. Matched v2/v3 regression benchmarks cover mutable Retain, Transform, and Shuffle paths plus input-preserving Filter and pipeline workloads. The hot paths remain zero-allocation, while the generated README tables and regression module make broader performance and ownership trade-offs visible.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!