{"id":681,"date":"2026-09-14T05:04:54","date_gmt":"2026-09-14T05:04:54","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/go-1-27-generic-methods-the-listx-package-i-finally-deleted\/"},"modified":"2026-09-14T05:04:54","modified_gmt":"2026-09-14T05:04:54","slug":"go-1-27-generic-methods-the-listx-package-i-finally-deleted","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/go-1-27-generic-methods-the-listx-package-i-finally-deleted\/","title":{"rendered":"Go 1.27 Generic Methods: The Helper Package I Finally Deleted"},"content":{"rendered":"

Okay, this is going to sound dumb, but I have a package in a client’s Go codebase called listx<\/code> whose entire reason for existing is that Go methods couldn’t have their own type parameters. Fourteen exported functions, every one of them a verb I wanted to hang off a type and couldn’t. listx.Map<\/code>, listx.Filter<\/code>, listx.GroupBy<\/code>, listx.Uniq<\/code>. Every caller imports it, every caller has to remember the argument order, and every code review has had at least one “why isn’t this a method” comment from someone new.<\/p>\n

Go 1.27 shipped in August with generic methods<\/a>, and last weekend I deleted that package. This post is about what changed in the language, what the rule is that still says no, and the two places where I reached for the new feature and then backed out.<\/p>\n

What the old rule was and why it existed<\/h2>\n

Since generics landed in Go 1.18 you could write a generic type and a generic function, but a method could only use the type parameters its receiver already had. You could write func (l List[E]) Len() int<\/code> because E<\/code> came from List<\/code>. You couldn’t write func (l List[E]) Map[F any](f func(E) F) List[F]<\/code> because F<\/code> was new, and methods weren’t allowed to introduce new type parameters.<\/p>\n

The reason was interfaces. If a method could be generic, then a type with Map[F any]<\/code> might or might not satisfy an interface that asked for Map(func(int) string) List[string]<\/code>, and the compiler would have to decide that at every conversion site with type arguments it didn’t have. The Go team wrote that up years ago in the generics FAQ and the answer stayed “not yet” through nine releases.<\/p>\n

So we all wrote package-level functions instead. Here’s the shape of the thing I’ve been shipping since 2022, straight out of that listx<\/code> package:<\/p>\n

package listx\n\ntype List[E any] []E\n\nfunc Map[E, F any](l List[E], f func(E) F) List[F] {\n    out := make(List[F], 0, len(l))\n    for _, x := range l {\n        out = append(out, f(x))\n    }\n    return out\n}\n\nfunc Filter[E any](l List[E], keep func(E) bool) List[E] {\n    out := l[:0:0]\n    for _, x := range l {\n        if keep(x) {\n            out = append(out, x)\n        }\n    }\n    return out\n}\n<\/code><\/pre>\n
And here’s what a caller looks like. It works. It’s also backwards, which is the whole complaint.<\/p>\n
ids := listx.Map(\n    listx.Filter(orders, func(o Order) bool { return o.Paid }),\n    func(o Order) string { return o.ID },\n)\n<\/code><\/pre>\n
Read that aloud. You filter, then you map, but the code says map first. Every time.<\/p>\n
What Go 1.27 lets you write instead<\/h2>\n
The spec change<\/a> is one production rule: MethodDecl<\/code> now has an optional TypeParameters<\/code> clause after the method name. The example in the spec is almost exactly the function I’d been writing at package level:<\/p>\n
type List[E any] []E\n\n\/\/ Apply returns the list obtained from applying f to each element of l.\nfunc (l List[E]) Apply[F any](f func(E) F) List[F] {\n    r := make(List[F], len(l))\n    for i, x := range l {\n        r[i] = f(x)\n    }\n    return r\n}\n<\/code><\/pre>\n
So listx.Map<\/code> became a method, listx.Filter<\/code> became a method (that one never needed a new type parameter, it was in the package for consistency), and the call site reads in the order things happen:<\/p>\n
ids := orders.\n    Filter(func(o Order) bool { return o.Paid }).\n    Map(func(o Order) string { return o.ID })\n<\/code><\/pre>\n
Type inference works the way it does for generic functions. I never wrote Map[string]<\/code> anywhere; the compiler took F<\/code> from the closure’s return type. The spec is explicit that a generic method has to be instantiated before it’s called or used as a value, and in practice inference does that for you at every call site I converted. Fourteen functions, zero explicit type arguments.<\/p>\n
The standard library got one of these too. math\/rand\/v2<\/code> now has a generic method (*Rand) N[Int intType](Int) Int<\/code> alongside the top-level rand.N<\/code> function that has been there since 1.22. Small thing, but it’s the canonical example of what the feature is for: a function that belonged on a type and had to live in the package namespace until now.<\/p>\n
The rule that still says no<\/h2>\n
Here’s the part I got wrong for about a day.<\/p>\n
Interfaces cannot declare generic methods, and a generic method cannot be used to satisfy an interface method. The release notes say it in one sentence and I read past it. I had an interface in the same codebase:<\/p>\n
type Collection[E any] interface {\n    Filter(func(E) bool) Collection[E]\n    Len() int\n}\n<\/code><\/pre>\n
and I assumed I could add Map[F any](func(E) F) Collection[F]<\/code> to it now. I can’t. The interface satisfaction problem from the FAQ didn’t go away; the Go team drew the line at concrete types. A concrete List[E]<\/code> can have a generic Map<\/code>. An interface describing “things with a Map<\/code>” still can’t, because there’s no finite set of method signatures to check against.<\/p>\n
What that means in practice: generic methods are for concrete types you own. If your code is built around interfaces (repository interfaces, anything you mock in tests), the new feature won’t touch that layer. You still write the generic function that takes the interface as its first argument. I have four of those left in the codebase and they’re staying.<\/p>\n
I’m not sure I’d have designed it any other way, but I do wish the release notes had led with the restriction instead of putting it in the last clause of the paragraph. It’s the thing that decides whether the feature applies to your code at all.<\/p>\n
The struct literal change nobody is talking about<\/h2>\n
The same release changed composite literals in a way that’s easy to miss. A key in a struct literal<\/a> can now be any valid field selector, not only a top-level field name. So if you have an embedded struct, you can set its fields inline:<\/p>\n
type Base struct{ ID, Version int }\ntype Order struct {\n    Base\n    Total int\n}\n\n\/\/ Go 1.26 and earlier\no := Order{Base: Base{ID: 7, Version: 2}, Total: 900}\n\n\/\/ Go 1.27\no := Order{ID: 7, Version: 2, Total: 900}\n<\/code><\/pre>\n
I have a lot of Base<\/code>-style embedded structs, and a lot of test fixtures that repeat Base: Base{...}<\/code> a hundred times. gofmt<\/code> won’t rewrite these for you and neither will the new go fix<\/code> modernizers as far as I can tell, so I did it with a regex and a nervous go test .\/...<\/code>. It’s a small cleanup. It also made one bug visible: a fixture that set Base.ID<\/code> and then, four lines later, overwrote the whole Base<\/code>. With the flattened form the duplicate key is a compile error, because the spec says a key can’t name a promoted field when the embedded struct is also set by another key.<\/p>\n
One restriction to know before you regex your fixtures: the embedded fields you walk through to reach the promoted one can’t be pointers. type Order struct { *Base; Total int }<\/code> doesn’t get the shorthand, and the error message the compiler gives you is accurate but terse. I had three of those, and for them the old Base: &Base{...}<\/code> form stays.<\/p>\n
Where I used it and then took it back out<\/h2>\n
Two places.<\/p>\n
The first was a Result[T]<\/code> type I use for pipeline stages, with a package function Then[T, U any](r Result[T], f func(T) (U, error)) Result[U]<\/code>. I turned it into a method, the call sites got prettier, and then I looked at the stack traces from a failing stage. The method version inlined differently and the closure names in the trace changed. The release notes warn that the compiler now picks simpler names for function literals, and combined with the method conversion I lost the ability to tell two stages apart in pprof<\/code>. I could have fixed that with named functions instead of closures. I put the package function back instead, because the trace readability mattered more than the call-site syntax for that type. That’s a judgment call and I might reverse it in six months.<\/p>\n
The second was a generic Cache[K comparable, V any]<\/code> where I wanted func (c *Cache[K, V]) GetAs[T any](k K) (T, bool)<\/code> to do a type assertion on the way out. It compiles. It’s also a bad idea, because the type assertion fails at runtime and the generic signature makes it look like the compiler is checking something it isn’t. A method named GetAs[T]<\/code> reads as “this is type safe.” It’s not. The old func GetAs[T any](c *Cache[K, any], k K)<\/code> at least looked like the hack it was. I kept the hack looking like a hack.<\/p>\n
What I’d do this week<\/h2>\n
If you have a helpers package like my listx<\/code>, the migration is mechanical and worth an afternoon. Bump go.mod<\/code> to go 1.27<\/code>, move each Func[T, U](recv, args)<\/code> to func (recv) Func[U](args)<\/code>, and let the compiler find every call site. Type inference handled all of mine.<\/p>\n
Before you touch anything, run go vet<\/code> on the current tree, because Go 1.27’s go test<\/code> now runs the stdversion<\/code> check by default and it will flag any standard library symbol newer than your go.mod<\/code> directive. On the client codebase that turned up two uses of slices.Chunk<\/code> in a module still declaring go 1.22<\/code>. Nothing to do with generic methods, but you’ll hit it the moment you upgrade the toolchain, so hit it on purpose first.<\/p>\n
While you’re in there, check whether any of the package functions you’re converting are used as values. slices.SortFunc(xs, listx.ByID)<\/code> style code, or a function stored in a map. A method value works there too (orders.Map<\/code> is a valid expression once instantiated), but the receiver gets bound at the point you take the value, which is a different lifetime than a package function has. I had one of these, a registry of transforms keyed by name, and it needed a one-line wrapper. Not hard, but it’s the one place where the fix wasn’t a search and replace, so it’s the place to look at by hand.<\/p>\n
And don’t touch your interfaces. Read the one sentence in the release notes about them twice, then leave them alone.<\/p>\n
I wrote about where I actually use type parameters in Go generics in 2026<\/a> back when methods couldn’t have them; most of that post still holds, and the parts that don’t are the parts I’ve covered here. The Go work I take on for clients is described at abrarqasim.com<\/a>, if you have a listx<\/code> of your own and would rather someone else spent the afternoon.<\/p>\n","protected":false},"excerpt":{"rendered":"
Go 1.27 lets methods declare their own type parameters. I converted a 14-function helper package, hit the interface rule that still says no, and reverted two of them.<\/p>\n","protected":false},"author":2,"featured_media":680,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Go 1.27 lets methods declare their own type parameters. I converted a 14-function helper package, hit the interface rule that still says no, and reverted two of them.","rank_math_focus_keyword":"go 1.27","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[45],"tags":[285,46,752,47,753,413],"class_list":["post-681","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-programming","tag-generics","tag-go","tag-go-1-27","tag-golang","tag-refactoring","tag-type-parameters-2"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/681","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=681"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/681\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/680"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=681"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=681"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=681"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}