Changelog

All notable changes to catena are documented here. The format follows Keep a Changelog; versions follow semantic versioning.

[Unreleased]

Documentation only — no change to the library’s API or behaviour.

Documentation

The examples are real work now. Every operator’s example — the code the reference pages and pkg.go.dev show — is rewritten around a situation a reader will recognise: unpaid orders, access logs, config ports, CSV imports, health checks. They were mostly catena.Of(1, 2, 3). All are still verified by go test.
The parallel examples make real requests. They run against an HTTP server started for the tests, so the calls being run concurrently are genuine: loading the products for a page, racing three mirrors and taking the first to answer, purging a cache across edge nodes, batching click events for a bulk insert.
The concurrency example program is a nightly job that prepares shipments with two service calls per order, against a local HTTP server, including the case of running three different calls at once.
The landing page, the README and the getting-started guide open with what the library replaces — the grouping loop, the worker pool, the error plumbing — and the landing page now covers parallel, source and the linter, which it predated. Two stale claims on it are corrected: that there are no goroutines anywhere, and a memory figure from before 1.4.
The guides point out that a method expression such as Order.Country is already a callback, which a test now pins down.
Examples are complete. In the parallel examples the function being run concurrently is written out in the example rather than named and left to the imagination, and operators can now carry several examples: Map shows API calls, a link checker that keeps going past failures, and CPU work; ForEach shows running three different calls at once. Where an example in another package calls a shared helper, the reference shows the helper’s source beneath it.
The reference shows an operator’s cautions as one list instead of a stack of separate boxes, and the concurrency guide opens with a table of what the package is used for, each row linked to a runnable example.

1.5.0 — 2026-10-10

The largest release since the API froze: the places a chain had to stop are closed, and three packages now sit beside the core. Nothing existing changes behaviour.

This reverses three earlier decisions, on purpose. The original design ruled out parallel operators (“a different library”), capped the operator count, and kept everything in one package. Concurrency is still a different package — the core starts no goroutine it did not start before — but it is no longer someone else’s problem.

Added

Seq.Then applies a function to the sequence, so a function that takes one sits inside the chain instead of wrapping it. Every one-argument package function fits, with its types inferred: s.Then(catena.Distinct).Then(catena.Sorted).Take(10). It is also how the stages in catena/parallel attach.
Ordered, chainable grouping. Seq.FoldedBy and catena.GroupedBy are FoldBy and GroupBy that yield a Seq2 of pairs, keys in the order they were first seen, instead of returning a map: the result is deterministic and the chain keeps going. GroupedBy is a package function because Seq2[K, []T] leads back to Seq[[]T], the same instantiation cycle that makes Chunked one.
Joins that drop nothing. Seq.LeftJoinBy keeps a left element with no match and tells combine so; Seq.GroupJoinBy yields one result per left element with all of its matches together.
Five ideas from lo, in catena’s shape.
- Seq.FirstOr and Seq.LastOr return a fallback when the sequence is empty, so a lookup can sit inside an expression.
- IsSorted, Seq.IsSortedBy and Seq.IsSortedWith check order in one pass with no buffer, stopping at the first pair out of order.
- Duplicates and Seq.DuplicatesBy yield each repeated value once, at its second occurrence.
- Seq.Sample draws n elements uniformly at random in O(n) memory by reservoir sampling — 803 KB → 456 B against collecting 100k elements to shuffle them, and 4.4× faster. A seeded generator makes the choice repeatable.
Try.UntilErr stops at the first error, as Collect does, but as a sequence: the chain continues with the full Seq API and the error is left where you asked, to be checked once the pipeline has run. It is the policy exit Try was missing — Ignore keeps going and Must panics — and it is how a fallible source feeds a stage that takes a plain sequence, the concurrent ones included.
catena/parallel: concurrency. Six operators, each a stage for Then:
- Map, MapUnordered and ForEach run a callback up to n at a time. The source stays on the consumer’s goroutine; only the callback runs elsewhere. A failed call is a Try element, so Collect, CollectAll and Ignore choose the policy as they always have.
- Buffer reads ahead, ChunkedWithin batches by size or by time, and Merge interleaves several sequences by arrival; these run their sources on goroutines of their own.
Every one joins the goroutines it started before its iteration returns — on a normal end, an early break, a cancelled context and a panic alike. That is tested under testing/synctest, in virtual time, against callbacks that are deliberately slow to stop.
catena/source: producers that ship. Lines for the lines of a reader, of any length; Paginate for a paginated API, fetching a page only once the one before it has been yielded in full; and sqlsource.Rows for a query, in a package of its own so the others do not link database/sql. Each opens its resource inside the iteration and releases it on every exit — the pattern the error-handling guide taught, now code.
catena/lint: a linter, as a separate module so the library’s own still depends on nothing. catenalint runs as a go vet tool and reports the pipelines that are correct but wasteful — Sorted(s).Take(n) where TopN holds n elements, Sorted(s).First() where Min holds one, Distinct(Sorted(s)) where Dedupe holds none, a GroupBy used only to count — and the lazy sequence that is built and never consumed. It offers a fix only where the replacement returns the same values of the same type. It carries the library’s version, under its own prefix: lint/v1.5.0.
Guides for concurrency and linting, and a lookup from lo, Kotlin and LINQ names to catena’s, every entry of which a test checks against the library. Reference pages for the two new packages, and concurrency and sources examples.

Documentation

The v1.4.x series is archived at /1-4/, per the rule that a minor series is snapshotted when the next minor ships.

Changed

Terminals and grouping operators are faster, some of them much. Every operator consumed its source through an adapter that made a nil sequence behave as an empty one, and that made every source an opaque function value. The call now goes through a method small enough to inline, so a source built in the calling function is one the compiler can see through. Measured interleaved against 1.4, over 100k elements: Sum and Contains 71µs → 24µs, the speed of a hand-written loop; FoldBy 16% faster; GroupBy and JoinBy 10–13%; single-stage Map 5%. Multi-stage pipelines are unchanged. No API or behaviour change.
The published hand-loop baselines were too slow, and are corrected. They were written inline in the benchmark body, where nothing may be optimised away, which made a plain loop look up to four times slower than it is. Measured as functions of their own, the hand-written 4-stage pipeline takes 25µs, not 39µs — so a 4-stage catena pipeline is about 10× a hand loop on trivial arithmetic, not 6.6× as the README and the performance guide said. The library did not get slower; the earlier comparison flattered it.
The 100% coverage gate now covers parallel, source and sqlsource as well as the core package, and the linter’s module is gated to 100% separately. CI also runs the linter over the examples, which must come back clean.
The selection example’s leaderboard sorted every player to show four. The linter found it; it uses TopNBy now, with identical output.
The join example rolls up with FoldedBy in place of collecting map keys and sorting them, and shows the two new joins.
The operator reference is generated for the sub-packages too, and the README’s “exactly one goroutine” is now stated of the core package, which is where it is true.

1.4.0 — 2026-09-01

A performance release with no API change: the terminals that gather a slice stopped recopying what they had already gathered.

Changed

The gathering terminals no longer grow a slice with append. Its curve is the wrong shape at size: past 256 elements Go grows a slice by about a quarter, and every step reallocates and recopies everything gathered so far, so collecting 100k elements allocated 4.1 MB to produce 800 KB across 32 reallocations. Elements now go into fixed blocks that are never resized, then into one exact-sized slice.

Measured against v1.3.0, interleaved over 18 samples a side to cancel drift: Collect is 14% faster and allocates 59% less (3.91 MiB → 1.60 MiB), and the buffer behind Sorted* the same 59% less, at 3% faster. Three more allocation events, 2.3 MB fewer bytes. Nothing else in the suite moved. The returned slice also has exact capacity now, where append left up to 25% slack for the caller to retain.

Applies to Collect, ToList, Partition, Unzip, Try.Collect, Try.CollectAll, the Sorted* buffer and Cycle’s replay buffer. No API change, and no behaviour change beyond the capacity of the returned slice.

Fixed

docs/05-performance.md showed a hand-written clone-and-sort but quoted numbers measured from SortedDesc(s).Take(10) — catena’s own sort path, which pays for the pipeline too. Against the code actually printed, TopNBy is 12× faster and 803 KB → 1 KB; against the catena spelling it is 32× faster and 1.7 MB → 1 KB. Both are now stated, and both are measured: BenchmarkSortedTakeN_Hand is new so the printed code is covered by a benchmark rather than borrowing one.
The SortedDesc(s).Take(10) memory figure was 4.1 MB and is now 1.7 MB, because that path shares the gathering change above. List.Map versus Seq map-and-collect moves from 7× to 6× for the same reason — the thing it is compared against got faster.

Documentation

The v1.3.x series is archived at /1-3/, per the rule that a minor series is snapshotted when the next minor ships.

1.3.0 — 2026-08-31

Documentation and site only — no change to the library’s API or behaviour. The headline is that the docs are now versioned: a reader pinned to an older release can read that release’s documentation instead of the current one silently replacing it.

Added

Versioned documentation. The site serves the current release at the root and archived releases under their own prefix, with a switcher in the header. v1.1.0 is archived at /1-1/, and its pages carry a notice saying so. The snapshot is taken from the tag rather than the working tree — the versioning plugin archives whatever is currently checked out, which would have filed the newer API under the older version’s name.
A 1280×640 social preview card, wired as og:image and twitter:image across every page. Links to the site previously unfurled with no image at all. The same file is the repository’s GitHub social preview, which has no API and is uploaded by hand.

Changed

The documentation site is now published from released tags only. Its content is derived from the tree it is built from while its version label comes from the newest release, so publishing main put the two in disagreement the moment anything landed unreleased — the site briefly documented BottomN while announcing itself as v1.1.0, which does not have it. A push to main now builds the site and runs every check against it without deploying. A site-only change can still be published from a branch, guarded by a check that refuses unless docs/operators/ matches the latest release tag.
Canonical URLs, the sitemap and the og:image now name catena.nerdmenot.in. The site answers on both that and its Pages subdomain, and naming the subdomain made the branded domain the duplicate.
The version switcher is the site’s own component rather than the plugin’s native <select>, whose option list is drawn by the operating system and takes none of the site’s type or colour. Versions are links, so one can be opened in a new tab.
API and GitHub in the top navigation open in a new tab, on the landing page and in the docs header.
The README links the documentation site, which it never had.

Fixed

The theme toggle lost its selected state on documentation pages. It renders twice there — the header and the mobile menu — and both named their radios catena-theme; radios sharing a name form one group however far apart they sit, so the browser kept only the last checked one.
Switcher links pointed at pages that need not exist in every version. The 404 page’s switcher offered /404/ and /1-1/404/, neither a route. Links now fall back to a version’s front page where the same page is absent, and /1-1/ itself is a page rather than a 404.
scripts/sync.ts cleared all of src/content/docs/ on every run, which would have destroyed the archived versions permanently — nothing can regenerate a snapshot of a tree that no longer exists. It now clears only the directories it generates.

Removed

SPEC.md. The design document had become a second place where the library’s contracts were written down, and the two could disagree — as they did: its Try rule set contradicted the code, its symbol counts had drifted, and it specified a conformance harness shape that does not exist. Each operator’s contract lives in its own doc comment, where godoc shows it and the conformance suite enforces it. The document remains in the v1.2.0 tag for anyone who wants the rejected-alternatives history.

1.2.0 — 2026-08-31

One new operator and a substantial documentation pass. The pass came out of an ergonomics and cognitive-load audit whose finding was that the library’s most useful facts were written down where godoc discards them — so nothing about the API changed, but a good deal more of it is now visible from the place people read.

Added

BottomN(s, n) — the no-selector form of BottomNBy, completing the pair with TopN. Without it, wanting the smallest n meant either BottomNBy(n, catena.Self[T]) or, more likely, Sorted(s).Take(n), which quietly gives up the O(n) memory bound that makes the operator worth having. Routes through the same bounded heap, with the same stability and tie rules.

Fixed

Four generated List mirrors documented themselves as evaluating “eagerly” while returning a lazy value: WithIndex and ZipWithNext return a Seq2, MapErr and FilterErr return a Try. They now say so, and the claim in Concepts that no operator changes evaluation strategy names them as the exceptions.
The eager-operators page claimed List carries “the whole Seq operation set”. It carries the whole method set: the constraint-bound package functions take a Seq, so catena.Sorted(l.AsSeq()).ToList() is the round-trip, and Concat needs l2.AsSeq(). Both are now documented on the List type and on the page.
The package doc pointed at a “constructor table” that did not exist in godoc. The normative re-iterability table now lives on the Seq type, and the nine constructors that said nothing about re-iterability now state it — including Cycle, which is re-iterable iff its source’s first pass is.

Documentation

Try’s five error rules were cited by number eight times in godoc and defined nowhere in it: the block was a file-level comment, which godoc discards. R1–R5 now live on the Try type, along with the rule that Try is deliberately a small surface — carry errors one stage, then commit to a policy and continue on Seq. Same fix for Seq2’s “deliberately absent” list and the funcs.go explanation of why constraint-bound operations cannot be methods.
The method-versus-package-function split is now stated in the package doc and as a fourth rule in Getting started. It is the first thing that bites a newcomer, and the compiler cannot say it: s.Distinct() produces an error indistinguishable from a typo. The -By methods an IDE does surface (SortedBy, DistinctBy, SumOf, MaxBy, TopNBy) now name their unsuffixed package-level siblings.
Added the re-iterability guarantee to Concepts: operators build state inside the returned closure, so a chain is re-iterable exactly when its root producer is. This turns an open-ended worry into one lookup.
Added a cross-ecosystem name map (LINQ, Kotlin, Rust) to Getting started, an index page for the operator reference, and mutual cross-references for the confusable pairs — MaxBy/MaxOf, Distinct/Dedupe, Collect/ToList, Chain/Concat, Once/Once1, JoinBy/Join.
The [S] marker in the operator catalog read as a warning while certifying the opposite; it now says what it means. README notes that adopting catena raises a consumer’s own go directive to 1.27, and its two non-compiling snippets are fixed.
The naming law gained the eight suffix patterns it did not cover, its known exceptions (AssociateWith, WithIndex), and the third reason an operation lands at package level (receiver shape).

1.1.0 — 2026-08-31

The first usable release. v1.0.0 was published briefly and withdrawn; it is retracted in go.mod and should not be used. Start here.

The library

Seq[T] — lazy iter.Seq[T] with 84 methods (37 chainable), built on Go 1.27 generic methods; range works directly and conversion to and from the standard iterator types is free.
Try[T] — fallible sequences where the consumer chooses the error policy (Collect aborts, CollectAll gathers, Ignore skips), under five uniform rules for how errors flow through intermediates.
Seq2[K, V] — the stdlib pair bridge; List[T] — the eager mirror, generated and conformance-checked to agree with AsSeq().
The memory-class operators: FoldBy (grouped aggregation bounded by keys, not elements), TopNBy/BottomNBy (bounded stable heap), DedupeBy (O(1) streaming distinct), ChunkedBy, Windowed, JoinBy (relational inner join).
Every operator’s contract — argument edges, memory class, drain class, ordering and tie policy, error semantics — specified in each operator’s doc comment and enforced by the C1–C15 conformance suite, a completeness check that fails CI for any unregistered export, property tests, and 100% statement coverage of the library.
An operator reference covering all 182 operators, each with a worked example that go test runs and whose output it verifies.
examples/ — eight runnable programs, all executed in CI.
Performance measured three ways (hand loop / raw iter.Seq closures / catena) with the standing rule that catena meets the raw mechanism wherever the two compile on equal terms — it wins on multi-stage pipelines and terminals, and trails by 4–13% on single-stage shapes, where the baseline inlines into its consumer and a library call cannot. Operators compose by direct source invocation rather than range, which makes a 4-stage pipeline 25% faster than the same pipeline hand-built from raw closures.