Upcoming type-related deprecations

[josevalim]

This is a list of upcoming deprecations coming to Elixir. Most of those are anti-patterns anyway, which we kept in the language to avoid churn, but the addition of the type system will likely accelerate their deprecations anyway.

• [ ] Regex.replace/3 - this function allows a function of any arity to be given as argument, based on the amount of regex matches. Instead, this should have been written as a single function that receives a list of matches. We will need to address this by, most likely, introducing a new function, such as replace_indexes and replace_binaries.

• [ ] File.stat/1 - this function changes the return type based on an option which is, generally speaking, an anti-pattern. While the type system can model these return types using multiple clauses, it adds general complexity. Furthermore, I'd say this function has the wrong default, it should have defaulted to returning unix timestamps instead. The idea is to deprecate File.stat/1 and always force the time: :unix option to be given.

• [ ] Node.spawn and Process.spawn - Deprecate passing the :monitor option to both spawn and spawn_link. Add option support to spawn_monitor (we may want to deprecate Node.spawn_link in favor of passing an option to spawn, for consistency with Process).

• [ ] File.open!/2 - The return value (or the anonymous function) may receive either an IO device (PID) or a file descriptor. While all functions in the File module work with both, the functions in IO module may not, so may need to add File.descriptor or File.open_descriptor for when using the :raw option (most cases would be fine though).

One potential benefit is that the type system itself can help with the deprecation. Many of these deprecations would have be emitted at runtime but the type system will allow us to emit them during type-checking, which will aid migration.

PS: Do not send pull request for these yet. The goal of this issue is to accumulate those entries as examples and guidance.

[sabiwara]

Possible candidates, mostly due to the underlying OTP APIs, feel free to add to the list above or discard:

• https://hexdocs.pm/elixir/main/Node.html#spawn/3 pid | {pid, ref}
• https://hexdocs.pm/elixir/main/Process.html#info/2 tuple | [tuple]
• https://hexdocs.pm/elixir/main/Regex.html#run/3 [binary] | [{integer, integer}]
• https://hexdocs.pm/elixir/main/File.html#open!/2 io_device | file_descriptor (but this one feels OK)
• ~https://hexdocs.pm/elixir/main/Enum.html#with_index/2 (depends on fun_or_offset, but doesn't seem too bad?)~

[josevalim]

Thanks, I believe some of those will require looking into them at some point, they may be fine or they may be not, so the path forward is not yet clear.

• Node.spawn - added.

• Process.info - in this case the different return types are based on different argument types (list vs atom vs tuple), so we would be fine, but the Process.info(..., [...]) wont be a straight-forward API to type anyway. To be seen.

• Regex.run - yup, to be seen what is the best answer, as I am not sure we want to have run_indexes and run_binaries. We may need to accept the current APIs as is. One idea, suggested by @demerphq, is to make them return a Regex.Match structure, which would allow us to pick one or the other, but that would require introducing new functions that replace Regex.run and Regex.scan. To be seen.

• File.open!/2 - added.

• Enum.with_index/2 - this is fine as it is two different argument types. The issue is when you expect a different argument type or return type based on an option.