My goal was to learn more about Effect, in the details: all methods, no matter how advanced, how to use them and why.
Documentation is not enough. How can I do without it? π€·πΌββοΈ
This is how I go about learning a library, when documentation is not enough π
Tech stack
- Effect: when a project is open source you can literally view and search all the code π
- Github: you'll be surprised how helpful Github can be when searching and reading code, it's your best friend π€
- vitest: I write unit tests for myself when learning, this helps making sure that an API works as I expect
Setup
Welcome to 2024 π
The tools for the web are so great nowadays. You have countless of options to setup a project, especially when the goal is to learn by yourself:
- Cloud: StackBlitz, CodeSandbox, Github Codespaces
- Local: Vite, ts-node,
- Github
I opted for my local setup with typescript + ts-node.
Get started
First step: collect all the available documentation and resources.
This is the foundation. I keep these 3 tabs always open as I write code.
These form the core reference for my exploration.
There is more π€©
Timeless coding principles, practices, and tools that make a difference, regardless of your language or framework, delivered in your inbox every week.
Implementation
Exploration is unconstrained. I literally opened the API reference and clicked on the first module that caught my attention.
For example, I happened to be working with Base64 the day before, so I searched for it in the API ππΌββοΈ
Turns out Effect has an Encoding
module that implements Base64 encode and decode.
Now, the official documentation doesn't have a chapter about "Base64". The API reference in this case was enough:
This was easy since the signature is straightforward and simple to read
I wrote a test to make sure it works as I expected:
describe("Base64", () => {
describe("decode", () => {
it("should decode from Base64 to string", () => {
const result = Base64.Base64Service.pipe(
Effect.flatMap((base64) => base64.decode("Zm9vYmFy")),
Effect.provide(Base64.Base64ServiceLive),
Effect.runSync
);
expect(result).toBe("foobar");
});
});
});
Advanced API
Next stop was Context
and Tag
.
I used these modules in the past, but I had no idea how they worked internally.
The documentation usually focuses on concrete usecases, and not on implementation details ππΌββοΈ
Nonetheless, the best way to learn a technology is to understand the why and how from the internal implementation details
This is where Github and open source shine β¨
Search "Context" on the repository on Github. You will find all the information that you need. Specifically, the internal implementation and the tests
Github then helps you explore the code by giving references to all methods:
Click on any reference in the code and you will get links to sources and examples
Don't forget about tests! Every method is tested. This means that you will find for sure at least 1 example of how to use any API in the test file:
Search and open the test file and look for the API that interests you. You will find for sure 1 or more examples
Community support
Effect also has an awesome community over on Discord.
When I got stuck on some detail I sent a message to ask for help. Everyone is super friendly and willing to help, not matter how trivial is your question (thanks everyone ππΌ):
Ask for support from the community on Discord. Everyone is willing to help
I wrote down all my notes on the README of the open source repository, where you can read all the details of my exploration with links to all the APIs
Contribute back
The last step is always to contribute and share my learnings!
I wrote a complete getting started guide to Effect.
This is the guide I would give myself when I started learning about Effect π₯
Takeaways
- You can learn about any technology, no matter how complex
- Open source is awesome: you can read and search the internal implementation of your favorite libraries
- If the official documentation is not enough you can look at the API or at the internal documentation
- Tests are your best friend: you can always find at least 1 example of any API
- The Effect community is awesome: you should join
At the end I was able to explore only a very small set of modules. Effect has indeed a lot to offer:
Tweet not found
The embedded tweet could not be foundβ¦
This means that more will come, I will continue sharing my journey as I learn more and more π
See you next π