v4.0.0

Collection v4 is the supported Go 1.27-native release of collection, rebuilt around a slice-backed API.

Highlights

• Slice[T] is a named slice, so len, indexing, slicing, range, standard-library helpers, and iterator adapters work directly.
• Generic methods keep type-changing transformations fluent.
• Pure operations have consistent ownership semantics.
• Transform and Retain provide explicit, zero-allocation mutation for hot paths.
• Every exported function and method has an executable example.
• The benchmark suite includes direct lo comparisons and permanent v2/v4 regression coverage.

Upgrade

v4 requires Go 1.27 and uses the major-version module path:

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

Existing v2 consumers can upgrade when ready; v2 remains available.

See the v4 migration guide for method-by-method before-and-after examples, removed APIs, and ownership changes.

v3.0.0 (superseded)

Superseded: Use v4.0.0 for new integrations. The v3.0.0 module archive contains a repository-only test that fails when the nested examples module is absent. The tag remains immutable; v4 is the corrected release line.

Collection v3 is the Go 1.27-native release of collection, rebuilt around a slice-backed API.

Highlights

• Slice[T] is a named slice, so len, indexing, slicing, range, standard-library helpers, and iterator adapters work directly.
• Generic methods keep type-changing transformations fluent.
• Pure operations have consistent ownership semantics.
• Transform and Retain preserve explicit, zero-allocation mutation for hot paths.
• Every exported function and method has an executable example.
• The benchmark suite includes direct lo comparisons and permanent v2/v3 regression coverage.

Upgrade

v3 requires Go 1.27 and uses the major-version module path:

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

This is a deliberate major-version boundary. v2 remains available for existing consumers.

See the v3 migration guide for method-by-method before-and-after examples, removed APIs, and ownership changes.

v2.0.0

This release finalizes the v2 API direction with a focus on explicit behavior, predictable performance, and reduced surface area.

The primary change is a move to borrow-by-default semantics, along with API cleanup, clarified mutability rules, and transparent benchmarking. Several legacy helpers and ambiguous behaviors were deprecated or removed to simplify usage and eliminate hidden costs.

Breaking & Behavioral Changes

Borrow-by-default construction

• New and NewNumeric no longer perform defensive copies.
• Collections now borrow the provided slice by default.
• This aligns behavior with standard Go slice semantics and removes hidden allocations.

c := collection.New(items) // borrows items, no copy

Explicit copying

• Copying is now opt-in.
• Use Clone() or ItemsCopy() to explicitly take ownership.

owned := collection.New(items).Clone()

API Simplifications & Deprecations

The following APIs were removed or deprecated to reduce redundancy, ambiguity, and overlapping semantics.

Querying & filtering aliases

• FindWhere Removed. Use FirstWhere.
• Where Removed. Alias of Filter.
• Predicate-based Contains Removed. Replaced with value-based Contains(collection, value).

Transformation aliases

• Pluck Removed. Use MapTo.

Mutation helpers (important)

• Push Removed. Use Append.
• PushFront Removed. Use Prepend.

These methods duplicated slice semantics and obscured whether an operation was mutating or allocating. Their removal makes mutation explicit and consistent across the API.

Mutability & Method Classification

Methods are now consistently documented and classified as:

• terminal – end a chain and return a value
• chainable – return a collection for fluent pipelines
• mutable – modify the backing slice in place
• immutable – return a new collection

Notable clarifications:

• Map is explicitly mutable
• Each is readonly and chainable
• Many query helpers are terminal rather than fluent

This makes side effects explicit and easier to reason about.

Benchmarks & Performance

Dedicated benchmark documentation

• Added BENCHMARKS.md containing full raw benchmark data.
• Includes comparisons for:
  • collection.New (borrowed) vs lo
  • collection.New().Clone() (explicit copy) vs lo

Condensed README benchmarks

• README now presents grouped, condensed tables:
  • Read-only operations
  • Transforming operations
  • Pipelines
  • Mutating operations
• Raw numbers remain available for auditability and transparency.

Key observations

• Single operations are intentionally close to lo
• Chained pipelines often benefit significantly by avoiding intermediate allocations
• Copy costs are never normalized away or hidden

Documentation Improvements

• Clear explanation of borrow-by-default behavior
• Explicit guidance on when to use Clone() and ItemsCopy()
• Improved examples and clarified semantics throughout
• Consistent terminology across the API and README

Miscellaneous

• Increased test coverage
• Refined README layout and examples
• Minor wording and grammar corrections

Summary

This release establishes a stable, predictable foundation going forward:

• Borrow by default
• Copy only when explicit
• Make mutation visible
• Measure real-world performance
• Reduce unnecessary API surface

It is intended as a long-term, coherent baseline for future evolution of the library.

v1.3.0

Full Changelog: v1.1.0...v1.3.0

v1.2.0

Full Changelog: v1.0.0...v1.2.0

v1.1.0

Full Changelog: v1.0.0...v1.1.0

v1.0.0

Full Changelog: https://github.com/goforj/collection/commits/v1.0.0