Stream: ideas

Topic: "aka": APIs with multiple names

Joshua Warner (Jan 17 2025 at 05:51):

One thing we've discussed a lot is how exactly to name functions - e.g. Result.map_ok vs Result.map vs Result.combine, etc. Should we go with the name that a Rust developer will know? Or the name that a Javascript developer will know?

What if we didn't have to choose?

Imagine this syntax:

# in Result.roc
@aka(map, combine) # strawman syntax; probably much better ways to write this
map_ok : Result a e, (a -> b) -> Result b e
map_ok = ...

The behavior would be as if identical functions of all three names were defined.

However: we'd spiff up the formatter to always unify on the primary declared name (so, map_ok in this case). So, e.g. if you type a |> Result.combine SomeTag, that'll get converted to a |> Result.map_ok SomeTag for you.

This means you as a developer can get up to speed faster by using function/method names you know. Docs can show those "aka" names, which would then be visible when hovered in an editor.

It also has the benefit of encouraging iterating on function names for clarity, since that will no longer need to be a breaking change. (tho, this is a bit of a double-edge sword - point is, you're not forced to keep that same, old, terrible name for compatibility reasons).

Sam Mohr (Jan 17 2025 at 06:00):

One of the arguments that gets thrown out here is that we haven't considered whether to support attributes on types/defs, and individually those arguments come down to "we shouldn't support attributes for one usage" and "let's see if we can get away without them" for the most part

Tobias Steckenborn (Jan 17 2025 at 06:01):

Not sure if I like that. I‘d rather say let’s try to go the effort to find a name that describes the concept properly and not the easy route of all names that some people might thought were useful in the past.

Sam Mohr (Jan 17 2025 at 06:01):

But it seems like between this, deprecation warnings, compiler attributes for code deriving, etc. we could put together a list of all of the features that supporting attributes would unlock

Joshua Warner (Jan 17 2025 at 06:02):

To be clear, I'm not saying attributes are the right syntax here

Sam Mohr (Jan 17 2025 at 06:02):

I get that

Sam Mohr (Jan 17 2025 at 06:02):

My message was orthogonal to this proposal

Joshua Warner (Jan 17 2025 at 06:02):

@Tobias Steckenborn Agree we should still put in the effort to find the right name. This doesn't let us sit in our haunches.

Joshua Warner (Jan 17 2025 at 06:03):

What it does do is provide a really smooth upgrade path for existing users after we've decided

Tobias Steckenborn (Jan 17 2025 at 06:04):

Yeah, but then we optimize for the people using it now. That would only make sense if we expect the number of current users to be larger than the number of potential new future users.

Tobias Steckenborn (Jan 17 2025 at 06:10):

For the docs it might make sense to have some other typical names somehow searchable I assume. Otherwise I assume we‘d have different people of different background continuously using different names. Changing it after they’ve written it that way would be strange to me as probably they’d also search for the name they wrote.

Maybe there’s a way to use that just for propositions in the „typehelp“ but never the less have only one consistent name in the actual code?

Anthony Bullard (Jan 17 2025 at 10:52):

I’ll only say the idea of a formatter changing the _name_ of a function I wrote - even if it resolves to the same actual function is WILD to me.

Sam Mohr (Jan 17 2025 at 10:53):

Yeah, definitely would be better to have a warning along the lines of "the preferred name for this function is X", and maybe a code action to fix that for you

Anthony Bullard (Jan 17 2025 at 10:53):

How about this. In the doc comments we create a syntax for “alternative name suggestions “ that could be parsed and used by A) the reporter and B) the LSP to suggest the alternative

Sam Mohr (Jan 17 2025 at 10:54):

Not sure it belongs in the doc comments, but I'd be open to that

Sam Mohr (Jan 17 2025 at 10:54):

Rust has this convention of putting common docs sections like "when does this panic?"

Anthony Bullard (Jan 17 2025 at 10:54):

I think it’s the type of thing we would put in a doc comments

Sam Mohr (Jan 17 2025 at 10:55):

We could have specific headers like (#)+ Aliases that handle this

Sam Mohr (Jan 17 2025 at 10:55):

If we don't have attributes, then yes

Anthony Bullard (Jan 17 2025 at 10:55):

I think if you have keep_if, it would be reasonable to what to say “This is known an filter or select in other languages”

Anthony Bullard (Jan 17 2025 at 10:56):

I’m pretty anti-attribute

Anthony Bullard (Jan 17 2025 at 10:56):

When you have doc comments

Sam Mohr (Jan 17 2025 at 10:57):

Josh's suggestion is that we allow you to use filter or keep_if, but having all aliases from other popular languages in scope could lead to some annoying name clashes

Sam Mohr (Jan 17 2025 at 10:57):

Probably not a big deal :shrug:

Anthony Bullard (Jan 17 2025 at 10:58):

If you start typing filter, the LSP could show an entry for keep_if is all I’m saying

Anthony Bullard (Jan 17 2025 at 10:58):

If there is a filter function as well that fits the subject better (if a method) then we’d show that of course

Sam Mohr (Jan 17 2025 at 10:59):

I'm trying to figure out if you agree with Josh that we should allow people to call List.keep_if or List.filter interchangeably

Anthony Bullard (Jan 17 2025 at 11:00):

And if you type filter without paying attention to autocomplete like a Chad, then the error could say “I didn’t find a function called filter, but you may have been wanting “keep_if” which is called filter is some other languages”

Anthony Bullard (Jan 17 2025 at 11:00):

No I dont

Anthony Bullard (Jan 17 2025 at 11:01):

I think the editor and the error reporter should guide the user to the right one based on the advice of the function author

Sam Mohr (Jan 17 2025 at 11:01):

Well then, without the ability to use the aliases interchangeably, we are back to the problem of "should we name it Result.build or Result.map2 or Result.chain, we have to pick one even though different names are better in different contexts"

Anthony Bullard (Jan 17 2025 at 11:02):

Yes

Anthony Bullard (Jan 17 2025 at 11:02):

But we can choose the one that feels best to us

Sam Mohr (Jan 17 2025 at 11:04):

I mean sure, but then you're saying the problem this thread was created to solve isn't that big a deal

Sam Mohr (Jan 17 2025 at 11:04):

Which may be your intent

Sam Mohr (Jan 17 2025 at 11:04):

But if we think it's a real problem, we should come up with an alternative solution

Anthony Bullard (Jan 17 2025 at 11:06):

I don't think there is a "solution" outside of us creating a cohesive strategy for naming builtin APIs

Anthony Bullard (Jan 17 2025 at 11:06):

One of which would be "use the name that is most familiar to programmers coming to Roc"

Anthony Bullard (Jan 17 2025 at 11:07):

Another is "the name we think best describes what the function does, regardless of other language decisions"

Anthony Bullard (Jan 17 2025 at 11:07):

Like what would just make sense to a beginner who's never seen this (probably more advanced) idea before?

Norbert Hajagos (Jan 17 2025 at 13:34):

I wouldn't want to see different names for the same functions. Once the formatter rewrites the function name to the preferred one (so we still need to pick one for the builtins, which would set the scene for library authors), I would aim to always use that one. That extra (ideally one time) QoL functionality isn't worth a feature imo. I can see discussions that would come up during pair programming (Not to mention orgs without a CI pipeline to automatically run the formatter :trouble: ):
-I was confused for a second seeing filter on the screen, but realized you are using an alias! You know if you run the formatter that will be renamed.
-Oh, I actually use filter during local development, since that's the generally established name and I see the intent better. Should probably get used to keepIf, but the formatter makes it so convenient to stay.
-I see. Well, could you still run it for me, so that we have a common ground?

Norbert Hajagos (Jan 17 2025 at 13:34):

I agree with Anthony that the solution is to make the language server know about these aliases. The most interesting question for me is: Do we want to give a tool for others to define function aliases, or are we okay to hardcode it for builtins? I am leaning towards hardcoding them, since that would get us most of the benefit without a new feature. I could be convinced to use semantic doc-comments for this, but only for documentation and lsp, not for the formatter.
Also, aliases for types and constants seem wrong, but so does special casing them for functions.

Anton (Jan 17 2025 at 13:55):

This alias issue seems like something that will continue to become ever less of a problem with LLMs. I think a beginner will definitely be using an LLM to turn a description of a transformation into Roc code and an experienced user will know what the functions are called.

Richard Feldman (Jan 17 2025 at 14:10):

another problem with the autocomplete (which we've seen with the docs page) is that people don't type out filter - they type f and maybe fi and see that it's not in the list and then move on

Richard Feldman (Jan 17 2025 at 14:12):

but if we include a "redirect" filter entry every time anyone even types an f, we'll end up cluttering our results for advanced users forever with aliases they're never going to use

Anthony Bullard (Jan 17 2025 at 14:14):

Seems like that could be Plugin/LSP configurable option (enabled by default)

Anthony Bullard (Jan 17 2025 at 14:15):

And I'm not pushing for this at all, but if we wanted to provide something in this space, I would feel more comfortable with the design I'm proposing than the original proposal in this thread.

Anthony Bullard (Jan 17 2025 at 14:15):

I think even _just_ having it in reporting might be a win

Richard Feldman (Jan 17 2025 at 14:17):

I kinda wonder about just hardcoding a couple of new heuristics into the "Did you mean...?" message for naming errors

Richard Feldman (Jan 17 2025 at 14:18):

like if we see "filter" in the missing name, prioritize suggestions beginning with keep_

Richard Feldman (Jan 17 2025 at 14:19):

my general worry with something like this is that it ends up being something people spend time on across the ecosystem, and then it doesn't really move the needle in practice and the beginner experience is still approximately the same as before

Anthony Bullard (Jan 17 2025 at 14:23):

Sure, I think that's probably fine

Derin Eryilmaz (Jan 17 2025 at 18:53):

yeah i think auto complete should handle this

Paul Stanley (Jan 23 2025 at 23:21):

Please no. It's always so tempting, isn't it, to say "this is going to be just what you are used to, just what you love" ... but over time it produces a massive mess. The language ends up resembling one of those terrible hotel restaurants where they have pizza, they have noodles, they have chicken pot pie, they have a caesar salad, they have eight kinds of chilli ... 10 pages of food, and none of it really good. It's like those languages that can't help borrowing "good ideas" for "alternative expressive ways" to do things ... and you end up with something like loop in common lisp. And nobody's actually ever happy, because ... why can't they have a Hawaiian burger with the blue cheese if that's what they want.

People are not entirely dumb. They will learn that fold is called walk, quite quickly. They will learn quicker if there's no alternative.

Limiting (unimportant) choice is the path to freedom.

Last updated: Jun 16 2026 at 16:19 UTC