release: v2

[cmilesio]

Overview

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.

Construction & ownership

• Attach Removed. Redundant after borrow-by-default New.

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.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️