Skip to content

v2.0.0

Choose a tag to compare

View all tags
@cmilesio cmilesio released this 02 Jan 19:56
· 28 commits to main since this release
v2.0.0
b638ff1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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.

Assets 2
Loading