Migrating away from v1 Macro

[yordis]

Disclaimer: the issue will no be removed any time soon. No rush.

The migration away from the use Tesla macro is an important step forward for the Tesla library. If you have any questions, please share them here.

Why are we deprecating the macro?

1. Improved Clarity: The macro approach can be confusing for newcomers as it hides implementation details behind magic. The new approach makes the client construction explicit and easier to understand.

2. Better Testing: With explicit client creation, it's easier to inject different middleware stacks or adapters during testing. You have full control over the client configuration.

3. Runtime Configuration: The macro approach makes it harder to configure clients at runtime since the middleware stack is defined at compile time. The new approach allows for dynamic client configuration based on runtime conditions.

4. Middleware Reusability: By defining middleware as a regular function returning a list, you can easily share and compose middleware configurations across different modules.

How-Tos

• https://hexdocs.pm/tesla/v1-macro-migration.html

References

• [Proposal] Lower the usage of macros #612
• Make runtime middleware more prominent in docs #377

[nomorepanic]

Hello, I just found out about this from a compile-time warning...and I can't believe it. Is it a trend now to make Elixir as useless as possible?

The macros are incredibly convenient, they're the reason I ended up using Tesla over other libraries.

1: I don't see how macros are not explicit. It's also the same mechanism as Plug, which a newcomer would have to learn anyway.

2: Excoverage doesn't count the code generated by macros in coverage. That means there's no need to test the macro-configured parts of a Tesla client, at least at the unit level.

From the examples I can see that with runtime configuration, the client has to be passed to the function. It makes Tesla a bit more inconvenient for those that use meck for unit testing.

The examples also suggest creating a private client function. Private functions can't be called, so they can't be tested on their own. Another inconvenience for meck-style unit-tests.

3: Hmm I don't see how this drives the deprecation of the macros. One could just use whichever mechanism is convenient for their case.

4: Why re-usability for complex clients must make writing smaller clients harder?

[yordis]

Private functions can't be called, so they can't be tested on their own.

It is a guide, feel free to adjust however you feel fit. Also, I would recommend to read https://hexdocs.pm/tesla/0-client.html since such private function's ins't encourage per se https://hexdocs.pm/tesla/0-client.html#comparing-single-client-and-multi-client-patterns

[nomorepanic]

Yes, of course it can be written as regular function. I mentioned it because I found it counterintuitive to say in one place "we're doing this change for testability" and then use a private function in the docs.

My feedback is that the macros have their use cases and you don't have to remove them to support the runtime configuration.