Created
October 20, 2022 11:13
-
-
Save SeanMcP/015446a7bcadd2f3debc01af9fd32b5d to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[https://redd.one RSS Feed]]></title><description><![CDATA[Learn the latest trends in web development, as well as the ageless basics, on this clean ad-free personal blog.]]></description><link>https://redd.one</link><generator>GatsbyJS</generator><lastBuildDate>Thu, 20 Oct 2022 11:08:41 GMT</lastBuildDate><item><title><![CDATA[Practical Guide to Custom Jest Matchers]]></title><description><![CDATA[What is a matcher? In Jest , functions like .toEqual() or .toHaveProperty() are called matchers . While Jest comes with an extensive…]]></description><link>https://redd.one/practical-guide-to-custom-jest-matchers</link><guid isPermaLink="false">https://redd.one/practical-guide-to-custom-jest-matchers</guid><pubDate>Wed, 22 Jun 2022 00:00:00 GMT</pubDate><content:encoded><h2 id="what-is-a-matcher">What is a matcher?</h2><p>In <a href="https://jestjs.io/">Jest</a>, functions like <code>.toEqual()</code> or <code>.toHaveProperty()</code> are called <em>matchers</em>. While Jest comes with an extensive amount of default matchers, you can also create your own to encapsulate repetitive assertions in your tests.</p><h2 id="symmetric-and-asymmetric-matchers">Symmetric and Asymmetric matchers</h2><p>There are two types of matchers in Jest: symmetric and asymmetric.</p><p>A <em>symmetric matcher</em> is the one that asserts data in its entirety. In other words, it&#x27;s a strict comparison matcher. Here&#x27;s an example:</p><pre><code class="language-ts">expect(myObject).toEqual({ id: 123 }) | |
| </code></pre><p>In this assertion, the <code>myObject</code> must equal to the <code>{ id: 123 }</code> object. If it doesn&#x27;t have the required &quot;id&quot; property or has additional properties that are not present in the expected object, the assertion will fail. In that regard, this matcher is symmetric because it reflects the expected value in its entirety.</p><p>An <em>asymmetric matcher</em> is a kind of a matcher that asserts data partially. Here&#x27;s the same object assertion as above but using an asymmetric matcher now:</p><pre><code class="language-ts">expect(myObject).toEqual( | |
| expect.objectContaining({ | |
| id: 123, | |
| }) | |
| ) | |
| </code></pre><p>The symmetric <code>.toEqual</code> matcher remains but you may notice that instead of accepting an object as its argument, it now accepts the call to <code>expect.objectContaining()</code> function. The latter is the asymmetric matcher, as it describes a subset of properties that must exist on <code>myObject</code>, ignoring any additional properties.</p><h2 id="creating-a-custom-matcher">Creating a custom matcher</h2><p>Jest provides the <code>expect.extend()</code> API to implement both custom symmetric and asymmetric matchers. This API accepts an object where keys represent matcher names, and values stand for custom matcher implementations.</p><p>Extending the default <code>expect</code> function can be done as a part of the testing setup. Make sure you have your Jest configuration file created and pointing to the custom setup file:</p><pre><code class="language-ts">export default { | |
| // Let Jest know that there&#x27;s an additional setup | |
| // before the tests are run (i.e. matcher extensions). | |
| setupFilesAfterEnv: [&#x27;./jest.setup.ts&#x27;], | |
| } | |
| </code></pre><p>Let&#x27;s start by implementing a custom symmetric matcher.</p><h2 id="custom-symmetric-matcher">Custom symmetric matcher</h2><p>In our application, we often assert that a number lies within the range of numbers. To reduce the repetition and make tests reflect the intention, let&#x27;s implement a custom <code>.toBeWithinRange()</code> matcher.</p><pre><code class="language-ts">// jest.setup.ts | |
| expect.extend({ | |
| toBeWithinRange(actual, min, max) { | |
| if (typeof actual !== &#x27;number&#x27;) { | |
| throw new Error(&#x27;Actual value must be a number&#x27;) | |
| } | |
| const pass = actual &gt;= min &amp;&amp; actual &lt;= max | |
| }, | |
| }) | |
| </code></pre><p>Here, we&#x27;ve extended the Jest&#x27;s <code>expect</code> global function with a new function called <code>toBeWithinRange</code>. Jest will always provide our matchers with the actual data as the first argument, and we can utilize the remaining arguments for the matcher to accept additional input (for example, the allowed range of numbers).</p><p>Since anything can be passed to the <code>expect()</code> in the test run, don&#x27;t forget to check for the <code>actual</code> type. In this matcher, we ensure that the provided <code>actual</code> value is a number.</p><p>We are checking whether the <code>actual</code> number is within the <code>min</code> and <code>max</code> range, and writing the result to the <code>pass</code> variable. Now we need to let Jest know how to respect that variable and mark assertions as passed or failed based on its value.</p><p>To do that, custom matchers must return an object of the following shape:</p><pre><code class="language-ts">{ | |
| pass: boolean | |
| message(): string | |
| } | |
| </code></pre><p>Let&#x27;s do just that:</p><pre><code class="language-ts">// jest.setup.ts | |
| expect.extend({ | |
| toBeWithinRange(actual, min, max) { | |
| if (typeof actual !== &#x27;number&#x27;) { | |
| throw new Error(&#x27;Actual value must be a number&#x27;) | |
| } | |
| const pass = actual &gt;= min &amp;&amp; actual &lt;= max | |
| return { | |
| pass, | |
| message: pass | |
| ? () =&gt; `expected ${actual} not to be within range (${min}..${max})` | |
| : () =&gt; `expected ${actual} to be within range (${min}..${max})`, | |
| } | |
| }, | |
| }) | |
| </code></pre><p>Now, whenever our matcher returns <code>{ pass: false }</code>, the test assertion will fail, and Jest will communicate the failure to us as it usually does.</p><p>Notice how we&#x27;re returning a conditional <code>message</code> value, even if the matcher has passed. That is done due to <em>inverse matches</em>, with which you are also very likely familiar:</p><pre><code class="language-ts">expect(5).not.toBeWithinRange([3, 5]) | |
| </code></pre><p>For our matcher, <code>5</code> is indeed within the given range of <code>[3, 5]</code>, so it will return <code>{ pass: true }</code>. But it&#x27;s the <code>.not.</code> chain that makes this assertion inverted, flipping it upside down. Jest knows that inverse matches must return <code>{ pass: false }</code>, and whenever that&#x27;s not the case, it will print the <code>message</code> that we&#x27;ve defined for that case. And that is why we still return a message when the matcher passes, and why that message says that &quot;the number must <em>not</em> be within range&quot;.</p><p>The final touch is to let TypeScript know that we&#x27;ve just extended a globally exposed function of a third-party library. To do that, create a <code>jest.d.ts</code> file and extend <code>jest.Matchers</code> and <code>jest.ExpectExtendMap</code> interfaces there:</p><pre><code class="language-ts">type OwnMatcher&lt;Params extends unknown[]&gt; = ( | |
| this: jest.MatcherContext, | |
| actual: unknown, | |
| ...params: Params | |
| ) =&gt; jest.CustomMatcherResult | |
| declare global { | |
| namespace jest { | |
| interface Matchers&lt;R, T&gt; { | |
| // Note that we are defining a public call signature | |
| // for our matcher here (how it will be used): | |
| // expect(5).toBeInRange(3, 7) | |
| toBeWithinRange(min: number, max: number): T | |
| } | |
| interface ExpectExtendMap { | |
| // Here, we&#x27;re describing the call signature of our | |
| // matcher for the &quot;expect.extend()&quot; call. | |
| toBeWithinRange: OwnMatcher&lt;[min: number, max: number]&gt; | |
| } | |
| } | |
| } | |
| </code></pre><p>Also, let&#x27;s make sure that this definition is included in <code>tsconfig.json</code>:</p><pre><code class="language-json">{ | |
| &quot;include&quot;: [&quot;jest.d.ts&quot;] | |
| } | |
| </code></pre><p>We can now use our custom matcher in tests:</p><pre><code class="language-ts">it(&#x27;asserts the number is within range&#x27;, () =&gt; { | |
| expect(5).toBeWithinRange(3, 5) // ✅ | |
| expect(3).toBeWithinRange(10, 20) // ❌ | |
| }) | |
| it(&#x27;asserts the number is not within range&#x27;, () =&gt; { | |
| expect(10).not.toBeWithinRange([3, 5]) // ✅ | |
| expect(5).not.toBeWithinRange([1, 10]) // ❌ | |
| }) | |
| </code></pre><h2 id="custom-asymmetric-matcher">Custom asymmetric matcher</h2><p>Similar to symmetric matchers, asymmetric ones are defined via <code>expect.extend()</code> in your test setup file.</p><p>Let&#x27;s create a custom asymmetric matcher that asserts that a given <code>Set</code> has a subset of values.</p><pre><code class="language-ts">// jest.setup.ts | |
| expect.extend({ | |
| // ...any other custom matchers. | |
| setContaining(actual, expected) { | |
| if (!(actual instanceof Set)) { | |
| throw new Error(&#x27;Actual value must be a Set&#x27;) | |
| } | |
| const pass = expected.every((item) =&gt; actual.has(item)) | |
| return { | |
| pass, | |
| message: pass | |
| ? () =&gt; `expected Set not to contain ${expected.join(&#x27;, &#x27;)}` | |
| : () =&gt; `expected Set to contain ${expected.join(&#x27;, &#x27;)}`, | |
| } | |
| }, | |
| }) | |
| </code></pre><p>Since the <code>setContaining</code> matcher is asymmetric, it should be exposed as <code>expect.setContaining()</code> and not <code>expect(x).setContaining()</code>. Let&#x27;s make sure we extend the <code>jest.Expect</code> type with our asymmetric matcher instead of extending the <code>jest.Matchers</code> type like we did with <code>toBeWithinRange</code>.</p><pre><code class="language-ts">// jest.d.ts | |
| import { MatcherFunction } from &#x27;expect&#x27; | |
| declare global { | |
| namespace jest { | |
| // ...any other extensions, like &quot;Matchers&quot;. | |
| interface Expect { | |
| // Once again, here we describe how our matcher | |
| // will be used in our tests: | |
| // expect.setContaining([&#x27;john&#x27;]) | |
| setContaining&lt;T extends unknown&gt;(expected: Set&lt;T&gt;): Set&lt;T&gt; | |
| } | |
| interface ExpectExtendMap { | |
| // Let&#x27;s keep our extension signature type-safe. | |
| setContaining: MatcherFunction&lt;[expected: unknown[]]&gt; | |
| // ...any other matcher definitions. | |
| toBeWithinRange: MatcherFunction&lt;[min: number, max: number]&gt; | |
| } | |
| } | |
| } | |
| </code></pre><p>Once this is done, we can use our custom asymmetric matcher in tests:</p><pre><code class="language-ts">it(&#x27;asserts a subset of the given Set values&#x27;, () =&gt; { | |
| expect({ friends: new Set([&#x27;john&#x27;, &#x27;kate&#x27;]) }).toEqual({ | |
| friends: expect.setContaining([&#x27;kate&#x27;]), // ✅ | |
| }) | |
| // Annotating the actual data will give us type-safety | |
| // down to each individual asymmetric matcher. | |
| interface User { | |
| friends: Set&lt;string&gt; | |
| } | |
| expect(user).toEqual&lt;User&gt;({ | |
| friends: expect.setContaining([5]), | |
| // TypeError: &quot;number&quot; is not assignable to type &quot;string&quot;. | |
| }) | |
| }) | |
| </code></pre><blockquote><p>You may have noticed that the <code>expect.extend()</code> part is identical for both types of matchers. In fact, even our asymmetric matcher will be exposed as <code>expect(v).setContaining(subset)</code> during test runtime. However, to preserve semantic names, I highly recommend describing symmetric matchers by extending <code>jest.Matchers</code>, and the asymmetric ones by extending <code>jest.Expect</code> separately. It&#x27;s a type limitation only but it will produce more consistent test matcher semantics.</p></blockquote><h2 id="conclusion">Conclusion</h2><p>And that&#x27;s how you extend Jest with both symmetric and asymmetric matchers while preserving the type-safety of your tests. Custom matchers are certainly not a beginner-friendly topic but they are indispensable when it comes to designing a custom testing vocabulary in somewhat larger projects.</p><p>You can browse through the source code from this article in this repository:</p><div owner="kettanaito" repo="jest-custom-matchers"></div><p>As a cherry on top, here are a few resources that can expand your knowledge about Jest matchers:</p><ul><li><a href="https://jestjs.io/docs/expect"><code>expect</code></a></li><li><a href="https://jestjs.io/blog/2018/05/29/jest-23-blazing-fast-delightful-testing#custom-asymmetric-matchers">Custom asymmetric matchers</a></li><li><a href="https://github.com/facebook/jest/blob/bb0956589f9dbddcc13db0f42b2d4d9ff642b2cd/examples/expect-extend/toBeWithinRange.ts#L11">Example of <code>.toBeWithinRange()</code> from Jest</a></li></ul><p>Thank you for reading! Make sure to <a href="https://twitter.com/kettanaito">follow me on Twitter</a> if you wish to stay in tune when I publish more pieces like this. You can also share this one with your coworkers and friends, I&#x27;d highly appreciate that.</p></content:encoded></item><item><title><![CDATA[The Dark Side of Open Source]]></title><description><![CDATA["Contribute to open source, it's the best thing that's happened to me!" I hear more and more often on Twitter these days. While I don't…]]></description><link>https://redd.one/the-dark-side-of-open-source</link><guid isPermaLink="false">https://redd.one/the-dark-side-of-open-source</guid><pubDate>Mon, 13 Jun 2022 00:00:00 GMT</pubDate><content:encoded><p>&quot;Contribute to open source, it&#x27;s the best thing that&#x27;s happened to me!&quot; I hear more and more often on Twitter these days. While I don&#x27;t object to the statement itself, I feel that it unintentionally (or intentionally) omits a decent chunk of truth about contributing and authoring open source. It sounds like you&#x27;re recommending a hiking route that, eventually, opens up to an unforgettable view but you fail to mention the number of challenges and the preparation this hike requires. I know there will be people who will take this route and will find themselves overwhelmed, if not unprepared, in the face of what a life of an open source maintainer actually is. As I&#x27;ve created this blog with the purpose to write about things I think people should talk about more often, it&#x27;s time for me to touch the vast and alluring plane of open source.</p><hr/><h2 id="status-check">Status check</h2><p>I&#x27;m going to write from an open source author&#x27;s standpoint. Partially, because this is where I have the most experience and can spotlight the issues I&#x27;ve faced myself. But mainly because I believe it&#x27;s a matter of a single commit when a contributor becomes an author.</p><p>There is a significant difference between the contributor&#x27;s and the author&#x27;s experience when it comes to open source. Visiting a park on a weekend to do some voluntary maintenance isn&#x27;t quite the same as being that park&#x27;s keeper, cutting grass every day, arranging repairs, nurturing, and treating the animals that dwell in the area. It&#x27;s like living in two different worlds that, eventually, will collide.</p><p>I should mention that I have no goal to discourage you from diving into open source and becoming whomever of these two you wish to be. Open source is a great place to learn and make friends—that&#x27;s what you&#x27;ve been told correctly. It&#x27;s been my primary way of learning for half a decade now, and it would be foolish for me to prevent you from learning yourself. So, if you&#x27;re considering landing that first contribution—<strong>do that by all means</strong>. See you at the end of the article.</p><h2 id="enjoy-being-undiscovered">Enjoy being undiscovered</h2><p>I say this without the slightest hints of sarcasm. Enjoy the time when your projects are just that—yours—for that is truly magical. Once they get discovered and picked up, things will change based on the adoption rate, so don&#x27;t miss out on the fresh air of a new project that nobody knows about.</p><p>Here, I&#x27;m tempted to say &quot;build something great and people will follow&quot; but that is very far from the truth. It&#x27;s like making a name in the music industry: it has nothing to do with the genre and quality of music you&#x27;re writing. It&#x27;s a matter of getting lucky once, twice, and then a couple of times more. Because it takes a tremendous amount of effort just to convince people to look at what you&#x27;re building, let alone adopt and contribute to it.</p><p>Once again, enjoy being undiscovered. There&#x27;s a unique touch to playing your songs from your garage, maybe even with a band of friends. Not everyone needs to gather big stadiums or sell platinum records. The life of a famous musician is more than hoarding piles of cash and drinking mega pints of wine. There are challenges and struggles, so enjoy while those aren&#x27;t on your daily list yet.</p><p>If, in the end, you decide to go all-in and seek attention, employ any tools available to you: social marketing, speaking at conferences, joining existing communities, and making friends on the network. The latter was what worked the best for me, and I&#x27;ve got lucky beyond measure to get my work featured multiple times by incredible people in the community. Your journey, however, is yours to make.</p><p>You will learn a lot about marketing while promoting your open source work. Well, no wonder. You won&#x27;t be promoting open source, to be frank, you will be promoting…</p><h2 id="its-a-product-not-a-feature">It&#x27;s a product, not a feature</h2><p>Think about an open source project that associates with &quot;successful&quot; in your mind. Now, what are the chances that this project is:</p><ul><li>Acquihired;</li><li>Owned by a corporation;</li><li>Serving as an entry point to a paid product;</li><li>Won a lottery ticket of getting adequate number of voluntary sponsorships;</li><li>Any combination of the above.</li></ul><p>In the JavaScript ecosystem, the chances of that are roughly around 100%. And if it seems you&#x27;ve thought of an exception, then it&#x27;s surely headed into one of these directions without you knowing.</p><div>Open source libraries <u>are</u> products.</div><p>It&#x27;s even customary to brand them, drawing logotypes, designing unique styles, and indulging in other forms of branding of a product. This isn&#x27;t bad, it&#x27;s just something that can slip past your passionate eyes, and something I rarely see the authors of those projects mentioning.</p><p>Many of such projects are still built by enthusiastic and endlessly creative people but despite that, they are all destined to become a product one way or another.</p><div>Enthusiasm is great but it makes for a poor dinner.</div><p>In addition to that, any enthusiasm needs to be kept alive. And so, in the light of preserving the embers of their inspiration, it&#x27;s natural that authors seek ways to sustain their projects financially. There&#x27;s only one catch.</p><p>If you look at the list above, not a single point has anything to do with the actual open source work you&#x27;re doing. The financial stability of authors comes from external sources—often built by themselves in addition to the titanic effort they&#x27;ve already put into their projects.</p><h2 id="money-in-open-source">Money in open source</h2><p>Anytime I mention &quot;money&quot; and &quot;open source&quot; in a single sentence everybody suddenly gets quiet in the room. For whichever abnormal reason, it&#x27;s an unspoken taboo to associate what is legally and infinitely free with such a dirty thing as money. I, honestly, don&#x27;t get this. How can we taboo something that is not there, to begin with?</p><div>Because there&#x27;s no money in open source.</div><p>Certainly, no contributors get into projects with the sole purpose to get a financial gain out of them. Open source has never been about money either. But for you as an author, the lack of funds to sustain your ideas and pay for even a small portion of the time you&#x27;re spending on them is—I&#x27;m not going to lie—devastating. It may not be your concern at first but it will inevitably become one when your ideas gain popularity, demanding significantly more time than there are hours in a day.</p><p>That being said, there are unicorn projects that exist with the support of their users. Whether your project will become one of those is a separate discussion. I&#x27;d say you have a higher chance of winning multiple lotteries in a row than getting stable financial support out of voluntary sponsorships. The entire open source culture is designed so that there would be no need nor urge to sponsor creators, and there hasn&#x27;t been a single shift in this direction for decades. Like a still windmill on a windless day, the financial state of open source hangs in the air, unresolved, unsought, stagnating.</p><p>That is why about everybody builds a product within or around their open source ideas. I can&#x27;t say I share this direction but it&#x27;s certainly the only one that is available to everybody. I do think that product-izing ideas leads to a priority shift, which often ends up in decisions that are best for the product and not for its users. In the end, when it comes to product, it&#x27;s the revenue that&#x27;s driving it, and so everybody is stuck in the infinite tug-o-war of attracting the users to their product and their product alone.</p><h2 id="plan-your-exit">Plan your exit</h2><p>The sooner you begin thinking of your ideas like products, the healthier your open source (and personal) life will become. And with any product, it&#x27;s worthwhile to consider your exiting options. In the context of open source, those are the options that will keep your product afloat, and your creativity fed.</p><p>It&#x27;s not a coincidence that most of the projects I can think of have a clear maintenance strategy in place. I&#x27;m not advocating for you to go and write a SaaS in parallel to your other ideas but if you can, then certainly go ahead. In other cases, consider the future of your project and think about the ways for that future not to become your second job. If I was able to carry at least some of my point across in the previous section, then you&#x27;d be able to answer by yourself exactly how well that job will be paid.</p><p>To make things somewhat more challenging, not all ideas translate to paid products. You may come up with fantastic tools that won&#x27;t sell both on their own or as a part of another product, leaving you in a state of limbo. Don&#x27;t wait for that to happen, devise a sensible maintenance plan for your projects early on, and stick to it.</p><p>I would love to recommend specific things or give you a sense of direction to follow when it comes to sustainable open source. But I can&#x27;t. Not because I want to keep the secrets of the universe from you but because I haven&#x27;t quite figured this out myself (hi from the limbo! 👋). My projects stagnate, and I&#x27;m burning out spending so much of my free time on them. Once I make sense of it, I will write another piece, but for now, the best I can do is to warn you and hope that you will be better prepared that I was.</p><h2 id="establish-a-healthy-balance">Establish a healthy balance</h2><p>Even from the earliest of days when you&#x27;re building something for fun with no intention or hope that it will ever be discovered by anybody, keep a healthy balance in the time you spend on open source. When your project does get discovered, and people will start demanding more, it&#x27;d be too late to think about things like this.</p><p>Open source is a vast sea of possibilities, and it&#x27;s easy to drown in it, watching as hours and weeks fly by, and your ideas gradually take form. It&#x27;s captivating and, frankly, addicting to do open source but be careful not to sacrifice your personal and family time to that addiction. This may sound silly to you but I know how easy it is to get a light panic attack whenever I see someone reporting an issue on my project. It also gets unnerving to realize that I cannot move as fast with my ideas as I want to simply because there are too many of them. Mental health is not something to joke about, and it&#x27;s different things that make us happy, sad, nervous, or uplifted. That&#x27;s where a proper balance and attitude towards open source is crucial.</p><p>Honestly, I would recommend just setting a time limit on the open source activities you do during the day. &quot;Okay, it&#x27;s 5 PM so I have one and a half hours to contribute to open source,&quot; that&#x27;s where a good balance starts. Sure, you may grow to afford more time, but it&#x27;s the idea of clear activity boundaries that makes it healthy. Don&#x27;t work in the evenings or nights. Don&#x27;t forget about your friends and your loved ones. Trust me, they matter more than all the code in the world.</p><p>And once you get &quot;big&quot;, try keeping things simple. Don&#x27;t let it get into your head. Don&#x27;t stress out about silly things. And yes, the code we write, in the end, is just a silly thing. It doesn&#x27;t make it uninteresting or pointless, but it&#x27;s just that—bytes in the computer. Funny enough, switching your attitude to a more distant one will also have a positive effect on the work you do. Everybody wins when the creator is healthy.</p><hr/><h2 id="closing-thoughts">Closing thoughts</h2><p>There is no better place to learn engineering than open source. There is also no better place to sacrifice your personal life and mental health than open source. And the way you balance between these two purely depends on you and the culture you establish about <em>your</em> open source work. Make your ideas happen. Help others. And, above all, remember to take a week off of open source once in a while, it will pay off.</p></content:encoded></item><item><title><![CDATA[Why I wouldn't want to have an engineering degree]]></title><description><![CDATA[Coming from a software engineer, the title of this article is rather uncalled for. That's the thing—I am not an engineer. Well, at least…]]></description><link>https://redd.one/why-i-wouldnt-want-to-have-an-engineering-degree</link><guid isPermaLink="false">https://redd.one/why-i-wouldnt-want-to-have-an-engineering-degree</guid><pubDate>Mon, 23 Aug 2021 00:00:00 GMT</pubDate><content:encoded><p>Coming from a software engineer, the title of this article is rather uncalled for. That&#x27;s the thing—I am <em>not</em> an engineer. Well, at least that&#x27;s not what my diploma says. I&#x27;ve been programming since childhood and was extremely lucky to see my bedroom hobby evolve into professional employment about half a decade ago. All that without reading a single programming book or completing an online course (which isn&#x27;t bragging, it&#x27;s rather sad, really). And, of course, without having a respective degree. Thinking about it now, I&#x27;d rather not have an engineering education, and I&#x27;m going to tell you why.</p><p>First of all, I have nothing against education in general and engineering degrees in particular. Official education, although variable in affordability and quality, is a great chance to expand one&#x27;s knowledge in a subject of their interest and an unmatched way to connect with hundreds of like-minded folks. It used to be a requirement to land a job in IT but I&#x27;m happy to see the trend of degreeless offers from the industry giants like Google and Microsoft.</p><div>The world is slowly coming to realize that a diploma is a receipt for education, but by no means a guarantee of time or effort invested.</div><p>People studying something they aren&#x27;t excited about are the people I fear the most. I&#x27;ve witnessed hundreds of students ignoring lectures, paying off exams, and looking for each and every opportunity not to study. Nothing unusual, right? Students are students and this kind of behavior is more than common and (sadly) accepted everywhere. Only the people I saw indulging in such behavior were medical students—surgeons, pediatricians, dentists—people you trust with your <em>life</em>. Seeing this made me realize how important it is to love what you do, and how no amount of education can spark an interest where there is none.</p><blockquote><p>Of course, there are exceptions to the rules. I did, and still do, have an interest in medicine, and that was the main reason I&#x27;ve studied to be a doctor. I do believe people may enjoy multiple things in life, and me becoming a software engineer is living proof of that.</p></blockquote><p>I have plenty of interest in engineering, yet I still wouldn&#x27;t want to study it in school. No, not because it may be expensive or may not bring enough practical value for its worth. I wouldn&#x27;t want to have an engineering degree because it would rid me of the feeling of <em>discovery</em>.</p><div>I won&#x27;t deny that coming from a non-technical background is challenging.</div><p>Extremely challenging. From people looking down on you for lacking a colorful paper saying you&#x27;re as smart as them, to the sheer lack of knowledge in various domains—there were numerous times when I thought that having a relevant education might&#x27;ve helped. I&#x27;m sure it would&#x27;ve helped, but it&#x27;d mask the problem, not solve it.</p><p>Okay, what about that &quot;discovery&quot; this random human from the internet mentioned? To explain to you what I mean by that I need to tell you about one particular lunch I had.</p><p>Back in the early days of my open-source <del>countless unpaid weekend hours to make the world a better place</del> endeavors, I met one of my colleagues for a lunch. He is a rather unordinary person and one of the smartest engineers I know. I&#x27;d often bring up some struggles I had with my projects both to <a href="/blog/how-to-ask-questions">learn to ask questions</a> and to, hopefully, get some help. I remember that time well because I was having trouble with one of the libraries I&#x27;d been writing.</p><p>&quot;I struggle with orchestrating multiple dependent asynchronous events,&quot; I said.</p><p>&quot;Good. Tell me about it,&quot; replied my colleague.</p><p>For the next fifteen minutes, I&#x27;d tried my best to explain the context and the issue, and it appeared that I succeeded. Now to bring some more context to you, I&#x27;m not a fan of one-way conversations, so whenever I ask for help, I try to mention at least a few things I&#x27;ve tried, and suggest my hypothesis as to why they failed. And thus I went through each approach I took that hadn&#x27;t been successful.</p><p>Suddenly, my colleague stopped me and said: &quot;You&#x27;ve just described CQRS.&quot;</p><p>&quot;CQ-what-what, excuse me?&quot; I asked, blinking like a donkey.</p><p>&quot;Command Query Responsibility Segregation—CQRS. That&#x27;s what you&#x27;ve just said,&quot; he reassured me. &quot;That&#x27;s something you can try to tackle your problem.&quot;</p><p>He described CQRS to me, projecting the concept on my very use case, and then it struck me. I was describing that very pattern, although in my limited and extremely abstract vocabulary, all along. Something people may have studied or read in books came to me as a logical approach to the problem. Sure, had I known this, I wouldn&#x27;t have had the issue to begin with, but then I&#x27;d have missed an incredible discovery moment, which I still remember long years after.</p><div>Coming to a realization of certain concepts within your natural learning curve is the most wonderful thing about learning that no book or lecture can teach.</div><p>I&#x27;ve tried implementing that new shiny abbreviation and, needless to say, I&#x27;ve enjoyed the entire routine, mainly because I felt like I&#x27;ve come to the solution myself. It&#x27;s the personal achievements like this that stick in your mind the best. The result matters, I can&#x27;t argue with that, but it&#x27;s the <em>path</em> that led us to that result that advances our understanding.</p><p>You may be thinking I&#x27;ve just got a certain inclination or a habit of mind, and that&#x27;s why some concepts click for me. That cannot be farther from the truth. I&#x27;m a linguistic sponge to the core of my bones and catch on grammatic intricacies tenfold faster than on the most basic mathematic laws and rules. I don&#x27;t even see software engineering as mathematics, objectively lacking in profound understanding, but keeping my thinking process clear, almost child-like, nonetheless.</p><p>We, humans, are incredibly proficient at justifying our lack of will. There is no such lie in the world that we wouldn&#x27;t tell ourselves just not to admit that we&#x27;ve given up. Nobody likes to admit their flaws, I get it. Yet how would you improve without acknowledging you need an improvement first?</p><p>In conclusion, I want to encourage you to learn, and, before all, learn how to learn. Let the lack of a degree not stop you. Let the complexity not scare you. Come to conclusions, make mistakes, have fun. You&#x27;ve got this.</p><div>And remember: when you hit a wall, don&#x27;t focus on the shortest most efficient way around it. Focus on trying to understand the nature of the wall and why it&#x27;s there.</div></content:encoded></item><item><title><![CDATA[Writing a custom webpack loader]]></title><description><![CDATA[Introduction This article uses the latest webpack version, which at the moment of writing is webpack v5 . webpack is a backbone that…]]></description><link>https://redd.one/writing-custom-webpack-loader</link><guid isPermaLink="false">https://redd.one/writing-custom-webpack-loader</guid><pubDate>Sun, 06 Jun 2021 00:00:00 GMT</pubDate><content:encoded><h2 id="introduction">Introduction</h2><blockquote><p>This article uses the latest webpack version, which at the moment of writing is <strong>webpack v5</strong>.</p></blockquote><p><a href="https://webpack.js.org/">webpack</a> is a backbone that powers most of the modern frontend tooling: Create React App, NextJS, Gatsby, —the list can go on and on. Over the years webpack had grown a reputation of being hard to configure, which is rather unfortunate, because no matter how abstracted webpack is in your setup, you can always benefit from knowing how to customize it.</p><p>Today I&#x27;d like to speak about one specific way of customizing webpack: writing a custom loader. I&#x27;m surprised to find this topic rather undocumented, so most of the information you read in this article is a result of reverse-engineering multiple existing loaders to let you and me learn.</p><hr/><h2 id="basics">Basics</h2><p>A <a href="https://webpack.js.org/concepts/loaders/"><em>loader</em></a> in webpack is a function that transforms a source code of imported modules.</p><p>Think of a loader as a function of a module&#x27;s content that creates or augments that module&#x27;s export:</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">const styles = cssLoader(require(&#x27;./styles.css&#x27;)) | |
| </code></pre><p>Loaders are the heart and soul of how webpack compiles TypeScript to JavaScript, turns SASS into CSS, and JSX into <code>React.createElement</code> calls. In fact, webpack doesn&#x27;t really do all that, loaders do! Meanwhile, webpack is responsible for establishing a transformation chain for your source code and making sure that the loaders are executed at the right stage of the build process.</p><p>Here&#x27;s how you apply loaders to files in a webpack configuration:</p><pre><code class="language-js">// webpack.config.js | |
| module.exports = { | |
| module: { | |
| rules: [ | |
| { | |
| // Capture all &quot;*.js&quot; imports, | |
| test: /\.js$/, | |
| // ...and transform them via &quot;babel-loader&quot;. | |
| use: [&#x27;babel-loader&#x27;], | |
| }, | |
| { | |
| // Capture all the &quot;*.css&quot; imports, | |
| test: /\.css$/ | |
| // ...and transform them via &quot;css-loader&quot;. | |
| use: [&#x27;css-loader&#x27;] | |
| } | |
| ], | |
| }, | |
| } | |
| </code></pre><p>In the configuration above, all <code>*.js</code> files that you import are passed through the <code>babel-loader</code>, while all <code>*.css</code> files are transformed via the <code>css-loader</code>. You can provide a list of loaders for the same subset of modules, in which case the loaders are applied from <strong>right to left</strong>:</p><pre><code class="language-js">{ | |
| test: /\.ext$/ | |
| use: [&#x27;third-loader&#x27;, &#x27;second-loader&#x27;, &#x27;first-loader&#x27;] | |
| } | |
| </code></pre><p>This makes more sense once you look at a loader as a function that passes its result (transformed code) to the next loader in the chain:</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">third(second(first(source))) | |
| </code></pre><h2 id="limitations">Limitations</h2><p>Loaders are designed to transform code. Unlike plugins, loaders cannot affect the build process, but rather transform individual imported modules during the build.</p><p>Generally, anything that lies outside of processing and generating code can be achieved through <a href="https://webpack.js.org/concepts/#plugins">plugins</a>. At the same time, one thing that a plugin shouldn&#x27;t do is transform code, making the boundary between a loader and a plugin rather clear.</p><p>For example, here are some of the use-cases to write a custom loader:</p><ul><li>Support imports of a custom file format (i.e. <code>*.graphql</code> or <code>*.prisma</code>);</li><li>Append meta data to the transformed files (i.e. inject frontmatter to <code>*.mdx</code> files).</li><li>Transform imported modules (i.e. auto-prefix imported <code>*.css</code> files).</li></ul><hr/><h2 id="writing-a-custom-loader">Writing a custom loader</h2><p>In this article we&#x27;re going to write an MP3 loader that would turn any <code>*.mp3</code> import into a <a href="https://reactjs.org/">React</a> component for playing that audio file.</p><pre><code class="language-js">import AudioPlayer from &#x27;./audio.mp3&#x27; | |
| function MyComponent { | |
| return ( | |
| &lt;AudioPlayer /&gt; | |
| ) | |
| } | |
| </code></pre><h3 id="declaration">Declaration</h3><p>A loader is a function that accepts a source code and returns a transformed source code. Let&#x27;s start from that: create a <code>mp3-loader.js</code> file and declare a new function in there:</p><pre><code class="language-js">// src/mp3-loader.js | |
| module.exports = function (source) { | |
| return source | |
| } | |
| </code></pre><p>At the current state, your loader is going to return the imported source (MP3 file binary) as-is.</p><p>We will be using the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio"><code>&lt;audio&gt;</code></a> HTML element to play an imported audio file. For that, we need to know the path of the imported MP3 file, emit it in the webpack&#x27;s build directory, and provide that file path as the <code>src</code> attrbiute of the <code>&lt;audio&gt;</code> element.</p><p>We can get an absolute path of the imported module by accessing the <code>this.resourcePath</code> property in a loader&#x27;s context. For example, given the following import:</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">import AudioPlayer from &#x27;./audio.mp3&#x27; | |
| </code></pre><p>The <code>this.resourcePath</code> will contain the absolute path to the <code>./audio.mp3</code> file. Knowing this, let&#x27;s emit an mp3 file with the same name:</p><pre><code class="language-js">// src/mp3-loader.js | |
| const path = require(&#x27;path&#x27;) | |
| module.exports = function (source) { | |
| // webpack exposes an absolute path to the imported module | |
| // under the &quot;this.resourcePath&quot; property. Get the file name | |
| // of the imported module. For example: | |
| // &quot;/User/admin/audio.mp3&quot; (this.resourcePath) -&gt; &quot;audio.mp3&quot;. | |
| const filename = path.basename(this.resourcePath) | |
| // Next, create an asset info object. | |
| // webpack uses this object when outputting the build&#x27;s stats, | |
| // so you could see info about the emitted asset. | |
| const assetInfo = { sourceFilename: filename } | |
| // Finally, emit the imported audio file&#x27;s &quot;source&quot; | |
| // in the webpack&#x27;s build directory using a built-in | |
| // &quot;emitFile&quot; method. | |
| this.emitFile(filename, source, null, assetInfo) | |
| // For now, return the mp3 binary as-is. | |
| return source | |
| } | |
| </code></pre><blockquote><p>Note that you need to remain in the webpack&#x27;s context in order to access <code>this.resourcePath</code> and <code>this.emitFile</code>. Ensure your loader is <em>not</em> an arrow function, because that&#x27;s going to re-assign the loader&#x27;s context and you&#x27;ll lose access to the properties and methods that webpack exposes to your loader.</p></blockquote><p>Now the imported audio file will be emitted alongside our JavaScript modules. Let&#x27;s proceed to the next step—returning a React component in our loader.</p><pre><code class="language-js">// src/mp3-loader.js | |
| const path = require(&#x27;path&#x27;) | |
| module.exports = function (source) { | |
| const filename = path.basename(this.resourcePath) | |
| const assetInfo = { sourceFilename: filename } | |
| this.emitFile(filename, source, null, assetInfo) | |
| return ` | |
| import React from &#x27;react&#x27; | |
| export default function Player(props) { | |
| return &lt;audio controls src=&quot;${filename}&quot; /&gt; | |
| } | |
| ` | |
| } | |
| // Mark the loader as raw so that the emitted audio binary | |
| // does not get processed in any way. | |
| module.exports.raw = true | |
| </code></pre><blockquote><p>Keep the imports that your loader needs in the loader&#x27;s scope, while the imports that your <em>transformed code</em> needs in its scope, inlined. Everything that a loader imports and does is an implementation detail of the build, and won&#x27;t be accessible in the compiled bundle.</p></blockquote><p>Both input and output of a loader&#x27;s function must be a <em>string</em>. That&#x27;s why we declare a new <code>Player</code> React component in a string, including all the necessary imports inside it. Now, whenever our application imports an MP3 file, instead of importing its binary, it&#x27;ll import the <code>Player</code> component that the loader generated.</p><p>Congratulations! You&#x27;ve just written a custom webpack loader that turns MP3 files into interactive audio players. Now let&#x27;s configure your webpack configuration to apply that loader to all the <code>*.mp3</code> files.</p><h2 id="using-a-custom-loader">Using a custom loader</h2><p>There are two ways to use a loader: tell webpack to resolve it from a local file, or publish it and install as a regular dependency. Unless your loader&#x27;s purpose is generic, or you plan to reuse it across multiple projects, I strongly recommend using the loader from a local file.</p><h3 id="from-a-local-file">From a local file</h3><p>To use a local webpack loader you need to alias it in the <code>resolveLoader</code> property in your webpack configuration:</p><pre><code class="language-js">// webpack.config.js | |
| const path = require(&#x27;path&#x27;) | |
| module.exports = { | |
| module: { | |
| rules: [ | |
| { | |
| test: /\.mp3$/, | |
| // Reference the loader by the same name | |
| // that you aliased in &quot;resolveLoader.alias&quot; below. | |
| use: [&#x27;babel-loader&#x27;, &#x27;mp3-loader&#x27;], | |
| }, | |
| ], | |
| }, | |
| resolveLoader: { | |
| alias: { | |
| &#x27;mp3-loader&#x27;: path.resolve(__dirname, &#x27;src/mp3-loader.js&#x27;), | |
| }, | |
| }, | |
| } | |
| </code></pre><blockquote><p>Since we&#x27;ve returne JSX from our loader, we need to tell webpack to transform it into regular JavaScript. That&#x27;s why we&#x27;ve included <code>babel-loader</code> as the next loader to apply after our <code>mp3-loader</code> is done (remember loaders are applied from right to left).</p></blockquote><h3 id="from-a-package">From a package</h3><p>If you decide to distribute your loader as a node module, you can use it just as any other Node.js dependency.</p><blockquote><p>It&#x27;s a common convention to distribute loaders in the <code>[name]-loader</code> format. Consider this when publishing your loader.</p></blockquote><p>Let&#x27;s say you&#x27;ve published your loader under a <code>mp3-loader</code> package on NPM. This is how you would use it in your project:</p><pre><code class="language-bash" metastring="showLineNumbers=false" showLineNumbers="false">npm install mp3-loader | |
| </code></pre><pre><code class="language-js">// webpack.config.js | |
| module.exports = { | |
| module: { | |
| rules: [ | |
| { | |
| test: /\.mp3$/, | |
| use: [&#x27;babel-loader&#x27;, &#x27;mp3-loader&#x27;], | |
| }, | |
| ], | |
| }, | |
| } | |
| </code></pre><blockquote><p>Notice that you don&#x27;t have to import your loader, webpack will resolve it from <code>node_modules</code> automatically.</p></blockquote><h2 id="trying-your-loader">Trying your loader</h2><p>To see the <code>mp3-loader</code> in action, run the <code>webpack</code> CLI command, given you&#x27;ve configured your <code>webpack.config.js</code> to use the custom loader:</p><pre><code class="language-bash" metastring="showLineNumbers=false" showLineNumbers="false">$ npx webpack | |
| asset audio.mp3 2.38 MiB [compared for emit] [from: src/audio.mp3] (auxiliary name: main) | |
| asset main.js 858 KiB [compared for emit] (name: main) | |
| webpack 5.37.0 compiled successfully in 1347 ms | |
| </code></pre><p>You can inspect the end result of the <code>mp3-loader</code> in this example repository:</p><div owner="redd-developer" repo="webpack-custom-loader"></div><h2 id="testing-your-loader">Testing your loader</h2><p>Since loaders depend on the compilation context, I recommend testing them as a part of webpack&#x27;s compilation, making such tests integration tests. Your tests&#x27; expectations will depend on what your loader does, so make sure to model them accordingly.</p><p>In the case of our <code>mp3-loader</code> we expect two things to happen:</p><ul><li>Imported audio file must be emitted in the build assets;</li><li>Compiled code must create an <code>&lt;audio&gt;</code> React component.</li></ul><p>Let&#x27;s reflect those expectations in a test:</p><pre><code class="language-js">// test/mp3-loader.test.js | |
| const path = require(&#x27;path&#x27;) | |
| const webpack = require(&#x27;webpack&#x27;) | |
| const { createFsFromVolume, Volume } = require(&#x27;memfs&#x27;) | |
| // A custom wrapper to promisify webpack compilation. | |
| function compileAsync(compiler) { | |
| return new Promise((resolve, reject) =&gt; { | |
| compiler.run((error, stats) =&gt; { | |
| if (error || stats.hasErrors()) { | |
| const resolvedError = error || stats.toJson(&#x27;errors-only&#x27;)[0] | |
| reject(resolvedError.message) | |
| } | |
| resolve(stats) | |
| }) | |
| }) | |
| } | |
| it(&#x27;converts &quot;*.mp3&quot; import into an audio player&#x27;, async () =&gt; { | |
| // Configure a webpack compiler. | |
| const compiler = webpack({ | |
| mode: &#x27;development&#x27;, | |
| entry: path.resolve(__dirname, &#x27;../src/index.js&#x27;), | |
| output: { | |
| filename: &#x27;index.js&#x27;, | |
| }, | |
| module: { | |
| rules: [ | |
| { | |
| test: /\.mp3$/, | |
| use: [&#x27;babel-loader&#x27;, require.resolve(&#x27;../src/mp3-loader.js&#x27;)], | |
| }, | |
| { | |
| test: /\.js$/, | |
| use: [&#x27;babel-loader&#x27;], | |
| }, | |
| ], | |
| }, | |
| }) | |
| // Create an in-memory file system so that the build assets | |
| // are not emitted to disk during test runs. | |
| const memoryFs = createFsFromVolume(new Volume()) | |
| compiler.outputFileSystem = memoryFs | |
| // Compile the bundle. | |
| await compileAsync(compiler) | |
| // Expect the imported audio file to be emitted alongside the build. | |
| expect(compiler.outputFileSystem.existsSync(&#x27;dist/audio.mp3&#x27;)).toEqual(true) | |
| // Expect the compiled code to create an &quot;audio&quot; element in React. | |
| const compiledCode = compiler.outputFileSystem.readFileSync( | |
| &#x27;dist/index.js&#x27;, | |
| &#x27;utf8&#x27; | |
| ) | |
| expect(compiledCode).toContain(&#x27;.createElement(\\&quot;audio\\&quot;&#x27;) | |
| }) | |
| </code></pre><hr/><h2 id="recipes">Recipes</h2><h3 id="loader-options">Loader options</h3><p>Loaders can accept options to change their behavior.</p><p>You can pass options to a loader in the webpack configuration:</p><pre><code class="language-js">// webpack.config.js | |
| module.exports = { | |
| module: { | |
| rules: [ | |
| { | |
| test: /\.mp3$/, | |
| use: [ | |
| { | |
| loader: &#x27;mp3-loader&#x27;, | |
| options: { | |
| maxSizeBytes: 1000000, | |
| }, | |
| }, | |
| ], | |
| }, | |
| ], | |
| }, | |
| } | |
| </code></pre><p>Above, we&#x27;ve created a custom <code>maxSizeBytes</code> option for the loader. The <code>options</code> object can later be accessed in the loader by calling <code>this.getOptions()</code>:</p><pre><code class="language-js">// src/mp3-loader.js | |
| module.exports = function (source) { | |
| const options = this.getOptions() | |
| console.log(options.maxSizeBytes) | |
| // ...parametrize your loader&#x27;s behavior. | |
| } | |
| </code></pre><h4 id="validating-options">Validating options</h4><p>It&#x27;s a good tone to validate your loader&#x27;s options to prevent improper usage and narrow down issues.</p><p>webpack comes with a <code>schema-utils</code> dependency installed, which you can use to validate your loader&#x27;s options:</p><pre><code class="language-js" metastring="focusedLines=4-11,16-17" focusedLines="4-11,16-17">// src/mp3-loader.js | |
| const { validate } = require(&#x27;schema-utils&#x27;) | |
| // Describe your loader&#x27;s options in a JSON Schema. | |
| const schema = { | |
| properties: { | |
| maxSizeBytes: { | |
| type: &#x27;number&#x27;, | |
| }, | |
| }, | |
| } | |
| module.exports = function (source) { | |
| const options = this.getOptions() | |
| // Validate the options early in your loader. | |
| validate(schema, options) | |
| // ...the rest of your loader. | |
| } | |
| </code></pre><blockquote><p>The <code>schema</code> object is defined using the <a href="https://json-schema.org/">JSON Schema</a> format.</p></blockquote><h3 id="logger">Logger</h3><p>Here&#x27;s an example of how we can take the custom <code>maxSizeBytes</code> <a href="#loader-options">loader option</a> into account, and produce a warning if the imported audio file exceeds the maximum allowed size:</p><pre><code class="language-js" metastring="focusedLines=6,10" focusedLines="6,10">// src/mp3-loader.js | |
| const fs = require(&#x27;fs&#x27;) | |
| module.exports = function (source) { | |
| const options = this.getOptions() | |
| const logger = this.getLogger() | |
| const assetStats = fs.statSync(this.resourcePath) | |
| if (assetStats.size &gt; options.maxSizeBytes) { | |
| logger.warn(&#x27;Imported MP3 file is too large!&#x27;) | |
| } | |
| } | |
| </code></pre><blockquote><p>Learn more about the webpack&#x27;s <a href="https://webpack.js.org/api/logging/">logger interface</a>.</p></blockquote><h3 id="context-properties">Context properties</h3><table><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><code>this.resourcePath</code></td><td>Absolute path to the imported module.</td></tr><tr><td><code>this.rootContext</code></td><td>Compilation <a href="https://webpack.js.org/configuration/entry-context/#context">context</a>.</td></tr></tbody></table><blockquote><p>See all the available properties by inspecting <code>this</code> in your loader.</p></blockquote><h3 id="context-methods">Context methods</h3><table><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td><code>this.emitFile()</code></td><td>Emits a file to the build directory.</td></tr><tr><td><code>this.getLogger()</code></td><td>Returns an internal webpack <a href="https://webpack.js.org/api/logging/">logger instance</a>.</td></tr><tr><td><code>this.emitWarning()</code></td><td>Emits a warning during the compilation.</td></tr><tr><td><code>this.getOptions()</code></td><td>Returns the loader&#x27;s options.</td></tr></tbody></table><blockquote><p>See all the available methods by inspecting <code>this</code> in your loader.</p></blockquote><hr/><h2 id="references">References</h2><p>The topic of webpack customization is rather undocumented and difficult to scout for. When learning about writing webpack loaders, I&#x27;ve referred to multiple existing loaders that I&#x27;ve used in the past to see how they work. Below you can find the list of such loaders to reference yourself:</p><ul><li><a href="https://webpack.js.org/loaders/"><strong>Featured webpack loaders</strong></a></li><li><a href="https://github.com/webpack-contrib/file-loader/">file-loader</a></li><li><a href="https://github.com/webpack-contrib/css-loader">css-loader</a></li></ul></content:encoded></item><item><title><![CDATA[Thinking in Functions, Part II: Higher-order functions]]></title><description><![CDATA[In the previous article, we have learned about the Input/Output pattern and how to use it when writing functions Today I'd like to…]]></description><link>https://redd.one/thinking-in-functions-higher-order-functions</link><guid isPermaLink="false">https://redd.one/thinking-in-functions-higher-order-functions</guid><pubDate>Sun, 07 Mar 2021 00:00:00 GMT</pubDate><content:encoded><p>In the previous article, we have learned about the <a href="/blog/thinking-in-functions">Input/Output pattern</a> and how to use it when writing functions Today I&#x27;d like to continue the series by talking about one of the most powerful concepts of functional programming—higher-order functions.</p><hr/><h2 id="higher-order-function">Higher-order function</h2><p>A <em>higher-order function</em> is a function that accepts another function as an argument or returns a function. Or both.</p><p>Here&#x27;s an example of a higher-order function:</p><pre><code class="language-js">// Function `fn` accepts `anotherFn` as an argument, | |
| function fn(anotherFn) { | |
| // ...and calls it with `x` to get the value of `y`. | |
| const y = anotherFn(x) | |
| } | |
| </code></pre><p>While this example is rather abstract and may look unfamiliar, there are multiple higher-order functions that you&#x27;re already using on a daily basis. In JavaScript, a lot of standard data types methods are higher-order functions. For example:</p><ul><li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map"><code>Array.prototype.map</code></a></li><li><a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/replace"><code>String.prototype.replace</code></a></li><li><a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce"><code>Array.prototype.reduce</code></a></li></ul><p>All those functions accept another function as an argument and that makes them higher-order functions. Let&#x27;s analyze what that means by taking a closer look at <code>Array.prototype.map</code>:</p><pre><code class="language-js">const numbers = [1, 2, 3] | |
| // Go through each number in the `numbers` array | |
| // and multiply it by 2. | |
| numbers.map((number) =&gt; number * 2) // [2, 4, 6] | |
| </code></pre><p>You know that the <code>.map()</code> method goes (iterates) through each array member and applies some transformation to it. Notice how you never see the &quot;goes through each array member&quot; logic while using this method, you only describe the transformation to apply. That&#x27;s because <code>.map()</code> is responsible for iteration, and when it comes to the point to map each value, it executes the function accepted as an argument.</p><p>This is the key principle of higher-order functions: <em>logic encapsulation</em>.</p><div>Higher-order functions encapsulate certain behavior, delegating the other behavior to the function(s) they accept as an argument.</div><p>By doing so, the <code>.map()</code> function establishes a usage contract with us. As with any contract, there are some terms to make it work:</p><ul><li>A higher-order function controls when to call a passed function;</li><li>A higher-order function controls what arguments are to the accepted function.</li></ul><p>Both those requirements are related to the fact that higher-order functions accept a <em>function definition</em>, in other words: instruction for the action. The given function definition is accessed by the higher-order function as an argument, making it in charge of when and how to call a given function.</p><p>To better understand this concept, let&#x27;s build our own <code>map</code> function.</p><pre><code class="language-js" metastring="focusedLines=8-10" focusedLines="8-10">function map(arr, mapFn) { | |
| let result = [] | |
| for (let i = 0; i &lt; arr.length; i++) { | |
| // Get the current array member by index. | |
| const member = arr[i] | |
| // Call the `mapFn` function we accept as an argument, | |
| // and provide the current array member to it. | |
| const mappedValue = mapFn(member) | |
| // Push the result of the `mapFn` function | |
| // into the end array of transformed members. | |
| result.push(mappedValue) | |
| } | |
| return result | |
| } | |
| </code></pre><p>Our custom <code>map</code> function can be used like so:</p><pre><code class="language-js">map([1, 2, 3], (number) =&gt; number * 2) | |
| // Identical to: | |
| // [1, 2, 3].map((number) =&gt; number * 2) | |
| </code></pre><p>You can see that the iteration details like the <code>for</code> cycle and the internal <code>results</code> array are not exposed to the <code>mapFn</code> function, and our custom <code>map</code> function controls precisely when to call the given <code>mapFn</code> argument and what data to provide it:</p><pre><code class="language-js" metastring="lineNumberStart=10" lineNumberStart="10">const mappedValue = mapFn(member) | |
| </code></pre><div>Higher-order functions control when and how to call an argument function.</div><p>The point of our <code>map</code> function is that it can do much more than the multiplication of numbers. In fact, as it accepts a function that controls what to do with each array member, I dare say our <code>map</code> function can do anything!</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">map([&#x27;buy&#x27;, &#x27;gold&#x27;], (word) =&gt; word.toUpperCase()) | |
| // [&quot;BUY&quot;, &quot;GOLD&quot;] | |
| </code></pre><p>But why this function is so powerful? Because it encapsulates the <em>how</em> (iteration) and accepts the <em>what</em> (transformation). It keeps the logic that&#x27;s a part of its contract hidden, but provides a way to customize a certain behavior via arguments to remain versatile.</p><h3 id="returning-a-function">Returning a function</h3><p>A higher-order function may also return a function. In that case, it acts opposite: instead of being in charge of when and how to call a given function, it generates a function and makes <em>you</em> in charge of when and how that function is called.</p><p>Let&#x27;s use the same <code>map</code> function we&#x27;ve written earlier, but now rewrite it so it returns a function:</p><pre><code class="language-js" metastring="focusedLines=2,4" focusedLines="2,4">// Instead of accepting the array straight away, | |
| function map(mapFn) { | |
| // ...we return a function that accepts that array. | |
| return (arr) =&gt; { | |
| let result = [] | |
| // ...leaving the iteration logic as-is. | |
| for (let i = 0; i &lt; arr.length; i++) { | |
| const member = arr[i] | |
| const mappedValue = mapFn(member) | |
| result.push(mappedValue) | |
| } | |
| return result | |
| } | |
| } | |
| </code></pre><p>Since the <code>map</code> now accepts only one argument, we need to change the way we call it:</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">map((number) =&gt; number * 2)([1, 2, 3]) | |
| </code></pre><p>The <code>fn(x)(y)</code> call signature is not common in JavaScript. Moreover, it&#x27;s rather confusing.</p><blockquote><p><strong>History digression:</strong> Not a long time ago such, call signature was used in <a href="https://reactjs.org/">React</a> to describe higher-order components, so it may ring some distant hook-less bells.</p><pre><code class="language-js" metastring="showLineNumbers={false}" showLineNumbers="{false}">export default connect(options)(MyComponent) | |
| </code></pre></blockquote><p>Don&#x27;t worry, we don&#x27;t have to abide by this unusual call signature. Instead, let&#x27;s break that <code>map</code> function call into two separate functions.</p><pre><code class="language-js">// Calling `map` now returns a new function. | |
| const multiplyByTwo = map((number) =&gt; number * 2) | |
| // That returned function already knows it should | |
| // multiply each array item by 2. | |
| // Now we only call it with the actual array. | |
| multiplyByTwo([1, 2, 3]) // [2, 4, 6] | |
| // We can reuse the `multiplyByTwo` function | |
| // without having to repeat what it does, | |
| // only changing the data it gets. | |
| multiplyByTwo([4, 5, 6]) // [8, 10, 12] | |
| </code></pre><p>Our <code>map</code> function doesn&#x27;t do any iteration on its own anymore, yet it <em>generates</em> another function (<code>multiplyByTwo</code>) that <em>remembers</em> what transformations to do, only waiting for us to provide it with data.</p><hr/><h2 id="applications">Applications</h2><p>A higher-order function is a great instrument to use when designing functions. The point of higher-order functions is to encapsulate logic. That encapsulation may solve one or more purposes:</p><ul><li>Abstract implementation details in favor of declarative code.</li><li>Encapsulate logic for versatile reuse.</li></ul><h3 id="abstract-logic">Abstract logic</h3><p>The most basic example is when you need to repeat a certain action N amount of times. Functional abstractions can come in handy compared to a lengthy <code>for</code> loop. Of course, it would still be using the loop internally, abstracting the iteration as it matters not when you use the function.</p><pre><code class="language-js">function repeat(fn, times) { | |
| for (let i = 0; i &lt; times; i++) { | |
| fn() | |
| } | |
| } | |
| // Where are not concerned with &quot;how&quot; (iteration), | |
| // but focus on the &quot;what&quot; (declaration), making | |
| // this function declarative. | |
| repeat(() =&gt; console.log(&#x27;Hello&#x27;), 3) | |
| </code></pre><p>By moving the imperative code to the implementation details of a higher-order function, we often gain improved code readability, making our logic easier to reason about. Compare these two examples: one with imperative code and another with declarative higher-order function:</p><pre><code class="language-js">// Imperative | |
| const letters = [&#x27;a&#x27;, &#x27;b&#x27;, &#x27;c&#x27;] | |
| const nextLetters = [] | |
| for (let i = 0; i &lt; letters.length; i++) { | |
| nextLetters.push(letters[i].toUpperCase()) | |
| } | |
| </code></pre><pre><code class="language-js">// Declarative | |
| const letters = [&#x27;a&#x27;, &#x27;b&#x27;, &#x27;c&#x27;] | |
| const nextLetters = map(letters, (letter) =&gt; letter.toUpperCase()) | |
| </code></pre><p>While both examples map Array letters to upper case, you need much less cognitive effort to understand that intention behind the second example.</p><div>It&#x27;s not about the amount of code, but about the code that describes implementation vs. the code that describes an intention.</div><p>It&#x27;s also about reusing and composing—creating new logic by combining existing functions. Take a look at how the abstractions below give you an idea of what&#x27;s happening without you peaking into how they are written:</p><pre><code class="language-js">map(ids, toUserDetail) | |
| map(users, toPosts) | |
| reduce(posts, toTotalLikes) | |
| </code></pre><h3 id="encapsulate-logic">Encapsulate logic</h3><p>Let&#x27;s say we have a <code>sort</code> function in our application:</p><pre><code class="language-js">function sort(comparator, array) { | |
| array.sort(comparator) | |
| } | |
| </code></pre><p>We are using this function to sort multiple things by rating: products, books, users.</p><pre><code class="language-js">sort((left, right) =&gt; left.rating - right.rating, products) | |
| sort((left, right) =&gt; left.rating - right.rating, books) | |
| sort((left, right) =&gt; left.rating - right.rating, users) | |
| </code></pre><p>You can see how the comparator function is the same for each call, regardless of what data we&#x27;re working with. We sort by rating <em>a lot</em> in our app, so let&#x27;s abstract that comparator into its own function and reuse it:</p><pre><code class="language-js" metastring="focusedLines=1-3" focusedLines="1-3">function byRating(left, right) { | |
| return left.rating - right.rating | |
| } | |
| sort(byRating, products) | |
| sort(byRating, books) | |
| sort(byRating, users) | |
| </code></pre><p>That&#x27;s better! Our sorting calls, however, still operate on the criteria-agnostic <code>sort</code> function. It&#x27;s a minor thing, but we also have to import two functions (<code>sort</code> and <code>byRating</code>) anywhere we need to sort by rating.</p><p>Let&#x27;s take the comparator out of the equation and lock it in a <code>sortByRating</code> function that sorts a given array by rating straight away:</p><pre><code class="language-js">function sortByRating(array) { | |
| sort(byRating, array) | |
| } | |
| sortByRating(products) | |
| </code></pre><p>Now the rating comparator is built-in into the <code>sortByRating</code> function and we can reuse it anywhere we sort by rating. It&#x27;s a single function, it&#x27;s short, it&#x27;s great. Case closed.</p><p>Our application grows in size and requirements, and we find ourselves sorting not only by rating, but also by reviews and downloads. If we follow the same abstraction strategy further, we&#x27;ll stumble upon a problem:</p><pre><code class="language-js" metastring="focusedLines=2,6,10" focusedLines="2,6,10">function sortByRating(array) { | |
| sort(byRating, array) | |
| } | |
| function sortByReviews(array) { | |
| sort(byReviews, array) | |
| } | |
| function sortByDownloads(array) { | |
| sort(byDownloads, array) | |
| } | |
| </code></pre><p>Because we&#x27;ve moved out the comparator from the <code>sortBy*</code> arguments, whenever we need to encapsulate a different comparison logic, we inevitably create a new function. By doing so, we&#x27;re introducing a different kind of problem: neither of the <code>sortBy*</code> functions above <em>share</em> the intention of sorting an array, instead they repeat the implementation (<code>sort</code>) all over the place.</p><p>We can approach this abstraction task with higher-order functions, which would allow us to create exactly <em>one</em> concise and deterministic function to satisfy our requirements.</p><pre><code class="language-js">function sort(comparator) { | |
| return (array) =&gt; { | |
| array.sort(comparator) | |
| } | |
| } | |
| </code></pre><p>The <code>sort</code> function accepts a <code>comparator</code> and returns an applicator function that does the sorting. Notice how the nature of <code>comparator</code> and <code>array</code> are variative, coming from arguments, yet the function&#x27;s intention (<code>array.sort</code>) does not repeat despite that dynamic nature.</p><p>Now we can create multiple sorting functions encapsulating different criteria like so:</p><pre><code class="language-js">const sortByRating = sort(byRating) | |
| const sortByReviews = sort(byReviews) | |
| const sortByDownloads = sort(byDownloads) | |
| sortByRating(products) | |
| sortByReviews(books) | |
| sortByDownloads(songs) | |
| </code></pre><p>This is a great example of logic encapsulation and reuse. It&#x27;s <em>beautiful</em> also.</p><h3 id="mention-currying">Mention: Currying</h3><p>Higher-order functions are also fundamental to <em>partial application</em> and <em>currying</em>—two techniques that are irreplaceable in functional programming. Don&#x27;t worry if they sound alien to you, we are going to talk about them in the future chapters of this series.</p><hr/><h2 id="putting-it-into-practice">Putting it into practice</h2><p>Just as with any other function, applying the <a href="/blog/thinking-in-functions">Input/Output pattern</a> is a great place to start when writing a higher-order function. With that, there are a few additional questions to ask yourself:</p><ol><li>What action is being delegated to the argument function?</li><li>When should the argument function be called?</li><li>What data is provided to the argument function?</li><li>Does the returned data of the argument function affects the parent function?</li></ol><p>It&#x27;s crucial to establish a clear separation between the responsibilities of a higher-order function and the argument function it accepts.</p><blockquote><p><strong>Exercise:</strong> Try to write your own <code>filter()</code> function: it accepts an array and a function that returns a <code>Boolean</code>. It returns a new array, with the members for which the argument function returned <code>true</code>:</p><pre><code class="language-js" metastring="showLineNumbers=false" showLineNumbers="false">filter([1, 3, 5], (number) =&gt; number &gt; 2) // [3, 5] | |
| </code></pre><p>Use the <code>map</code> function we&#x27;ve created earlier in this article as a reference.</p></blockquote><hr/><h2 id="real-life-example">Real-life example</h2><p>While working on one of my projects, I&#x27;ve decided to create a custom function that would allow me to handle an <a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest"><code>XMLHttpRequest</code></a> instance as a Promise. The intention was to make such requests declaration shorter and support the <code>async/await</code> syntax. I&#x27;ve started by creating a helper function:</p><pre><code class="language-js">function createXHR(options) { | |
| const req = new XMLHttpRequest() | |
| req.open(options.method, options.url) | |
| return new Promise((resolve, reject) =&gt; { | |
| req.addEventListener(&#x27;load&#x27;, resolve) | |
| req.addEventListener(&#x27;abort&#x27;, reject) | |
| req.addEventListener(&#x27;error&#x27;, reject) | |
| req.send() | |
| }) | |
| } | |
| </code></pre><p>I would then use that <code>createXHR</code> function in my tests like this:</p><pre><code class="language-js">test(&#x27;handles an HTTPS GET request&#x27;, async () =&gt; { | |
| const res = await createXHR({ | |
| method: &#x27;GET&#x27;, | |
| url: &#x27;https://test.server&#x27;, | |
| }) | |
| }) | |
| </code></pre><p>Thing is, I also needed to configure the request differently for various testing scenarios: set headers, send request body, or attach event listeners. To support that, I went to my <code>createXHR</code> function and extended its logic:</p><pre><code class="language-js" metastring="focusedLines=3,5-9,11,15" focusedLines="3,5-9,11,15">function createXHR(options) { | |
| const req = new XMLHttpRequest() | |
| req.responseType = options.responseType || &#x27;text&#x27; | |
| if (options?.headers) { | |
| Object.entries(options.headers).forEach([header, value] =&gt; { | |
| req.setRequestHeader(header, value) | |
| }) | |
| } | |
| req.addEventListener(&#x27;error&#x27;, options.onError) | |
| return new Promise((resolve, reject) =&gt; { | |
| // ... | |
| req.send(options.body) | |
| }) | |
| } | |
| </code></pre><p>As the test scenarios grew in diversity, my <code>createXHR</code> function grew in complexity. It resulted in an overly complex function that was hard to read and even harder to use. Why did that happen?</p><p>My mistake was to assume that the <code>createXHR</code> function should configure a request on its own. Describing a request configuration as the <code>options</code> object wasn&#x27;t a sound choice either, since the object is a finite data structure and cannot represent all the variety of how a request can be declared.</p><p>Instead, my helper function should have allowed for each individual call to configure a request instance it needs. And it could do that by becoming a higher-order function and accepting an action that configures a request instance as an argument.</p><pre><code class="language-js" metastring="focusedLines=1-2,5-6" focusedLines="1-2,5-6">// Accept a `middleware` function, | |
| function createXHR(middleware) { | |
| const req = new XMLHttpRequest() | |
| // ...that configures the given `XMLHttpRequest` instance, | |
| middleware(req) | |
| // ...and still promisifies its execution. | |
| return new Promise((resolve, reject) =&gt; { | |
| req.addEventListener(&#x27;loadend&#x27;, resolve) | |
| req.addEventListener(&#x27;abort&#x27;, reject) | |
| req.addEventListener(&#x27;error&#x27;, reject) | |
| }) | |
| } | |
| </code></pre><blockquote><p>The reason <code>XMLHttpRequest</code> instance is declared within the function and not accepted as an argument is because you cannot change certain options once a request has been sent.</p></blockquote><p>Notice how cleaner that function becomes as it delegates the request configuration to a <code>middleware</code> function. With that, each test can provide its own way to set up a request and still receive a Promise in return.</p><pre><code class="language-js" metastring="focusedLines=3-5,11-13" focusedLines="3-5,11-13">test(&#x27;submits a new blog post&#x27;, async () =&gt; { | |
| const req = await createXHR((req) =&gt; { | |
| req.open(&#x27;POST&#x27;, &#x27;/posts&#x27;) | |
| req.setRequestHeader(&#x27;Content-Type&#x27;, &#x27;application/json&#x27;) | |
| req.send(JSON.stringify({ title: &#x27;Thinking in functions&#x27;, part: 2 })) | |
| }) | |
| }) | |
| test(&#x27;handles error gracefully&#x27;, async () =&gt; { | |
| const req = await createXHR((req) =&gt; { | |
| req.open(&#x27;GET&#x27;, &#x27;/posts/thinking-in-functions&#x27;) | |
| req.addEventListener(&#x27;error&#x27;, handleError) | |
| req.send() | |
| }) | |
| }) | |
| </code></pre><hr/><h2 id="afterword">Afterword</h2><p>High-order functions may be a hard concept to grasp at first, but give it some time, apply it in practice, and the understanding will come. It&#x27;s a crucial part of functional programming and a great step towards thinking in functions. I hope this article has contributed to your knowledge, and you feel an extra tool in your arsenal now.</p><p>Looking forward to seeing you in the next part of the &quot;Thinking in Functions&quot; series!</p></content:encoded></item><item><title><![CDATA[How to ask questions?]]></title><description><![CDATA[Being a beginner software engineer you are often tasked with implementing real-world features and fixing tricky bugs. Sometimes you may feel…]]></description><link>https://redd.one/how-to-ask-questions</link><guid isPermaLink="false">https://redd.one/how-to-ask-questions</guid><pubDate>Fri, 04 Sep 2020 00:00:00 GMT</pubDate><content:encoded><p>Being a beginner software engineer you are often tasked with implementing real-world features and fixing tricky bugs. Sometimes you may feel that you lack knowledge or aren&#x27;t sure how to approach the task entirely. That is perfectly fine, even the most experienced engineers suffer from the occassional struggle and nobody truly knows everything, despite how wise they may appear. Asking for help (as well as giving one) is an inseparable part of programming, just as writing code or <a href="/blog/the-art-of-code-review">giving code reviews</a>. However, asking questions is a discipline on its own, and it will take some time to learn how to do that in a way that yields more results with less effort invested.</p><p>There are multiple blockers that beginner engineers face when it comes to asking for help. Today I would like to bring some of them up and share my personal experience of how I dealt with those blockers.</p><hr/><h2 id="asking-is-learning">Asking is learning</h2><p>I know how it feels to be afraid or ashamed to ask a question, worrying that your colleagues may grade you as less intelligent, frown upon you asking something they find obvious, or even bully you, demanding you should have known the answer by now. If you ever felt like your surrounding doesn&#x27;t encourage questions, <strong>you are in a toxic environment and you need to escape it</strong>. People who despise interest, experiment, and question, are seldom bright, as they block themselves and others from knowledge. Knowledge comes from learning, and learning comes from asking questions. Make sure you are travelling your journey amongst the people who understand that.</p><p>However, if you are shy or insecure when it comes to asking for help, I have a lifehack for you: don&#x27;t treat your question as a sign that you don&#x27;t know something, treat it as a sign that you would like to learn more. Asking a question, in my opinion, is the most efficient way to learn in any field. Doing so advances you in the grand art of asking, and has a bigger chance to remember the answer, as we best remember solutions to the problems we face first-hand.</p><div>Do not deprive yourself of the best way to learn: asking a question.</div><h2 id="the-grand-art-of-asking">The grand art of asking</h2><p>The skill of asking the right question is extremely hard to master. Nevertheless, you won&#x27;t get better at it without practicing and keeping track of the details and phrases that got you closer to the answer. This topic deserves a thick book to even scratch the surface, but right now let&#x27;s explore one of the most common issues when asking questions: <em>specificity</em>.</p><p>Specificity in questions is often ambiguous, and may bring you both closer and farther away from the answer. Let&#x27;s take a look at why that happens.</p><h3 id="irrelevant-specificity">Irrelevant specificity</h3><p>Here&#x27;s an example of a question:</p><blockquote><p>How do I persist an authentication token from Google between page refreshes in React?</p></blockquote><p>While this may be a valid question, it contains too much details that are not useful when it comes to answering it. For example, instead of binding the authentication process to Google, consider asking about authentication persistency in general, as it&#x27;s going to be vastly the same on your side for Google, Amazon, or any other provider. Instead of scoping the answer to the React ecosystem, try dropping the framework from the question, to learn about the persistency in JavaScript in general. That way the answer you get is more likely to be reused for other frameworks and libraries, making it much more valuable. Lastly, when it comes to persistency, it matters little if you persist an auth token, a unique ID, or any kind of information. Even the &quot;authentication&quot; part of the question can be replaced with &quot;how to persist data&quot;, <em>any</em> data.</p><p>While the context you are working in may be important, dropping it often helps to find the beginning of a thread that will eventually lead you to the right answer.</p><div>Look for knowledge, not answers. Knowledge is how the answers are produced.</div><p>Once the contextual specificity is omitted, notice how broader and at the same time shorter this question becomes:</p><blockquote><p>How do I persist data between page refreshes?</p></blockquote><p>Surely, the kind of answer you get may be incomplete for your particular context, but it will be a complete answer on its own. It may direct you to using cookies, or a session storage in JavaScript to presist arbitrary data. Then, you may want to ask a follow up question or two about using those API in the context of React. Chances are you are not the first person facing this, and there may be a useful article or a library that could help you achieve your goal.</p><div>Asking is investigating: you find clues that move you to more specific questions and, eventually, the answer.</div><p>When you need to turn a red sphere into a blue pointy cube, don&#x27;t expect to find a solution to that task straight away. Learn how to transform a sphere into cube first, then how to make any cube blue, and then how to make blue things pointy. Any programming task can be broken into a sequence of smaller tasks, researching which will be a more rewarding process in the long run. You may realize you didn&#x27;t even need your cube to be pointy somewhere in the middle of this process.</p><p>The reason I highly recommend dropping the context from your question is because it gives you a better chance at finding the answer. This also teaches you that a question rarely has a single direct answer. Get use to starting broad and narrowing the specificity with each piece of knowledge you find. You will be surprised how much you learn that way.</p><h3 id="relevant-specificity">Relevant specificity</h3><p>Including a name of the library, a browser version, or a particular option name is extremely likely to narrow the investigation scope and bring you closer to the answer. There is one important thing in providing such technical specificity: <strong>you must know what is relevant</strong>.</p><p>Take a look at this question:</p><blockquote><p>Axios fails on a POST request in <code>componendDidMount</code>.</p></blockquote><p>Evaluating the usefulness of those technical details is entirely impossible, as they may be both relevant and irrelevant, depending on the particular use case. It becomes your responsibility to know what to include and what to omit in your question. Truth be told, that is one of the things that makes it difficult to ask the right questions, and one of the skills you acquire with time and practice.</p><div>When including technical details, you must know what is relevant and what is not.</div><p>Unfortunately, mentioning irrelevant details may lead your investigation effort astray. Fortunately, if the person you asked it familiar with the topic, they may help you filter those details by relevancy.</p><p>As the time goes by and you keep asking questions, you will begin to notice how certain technical details shine for you, while others fade away. There is no other master-advice I can give you on this, just to encourage you to keep asking questions!</p><h2 id="the-15-minutes-rule">The 15 Minutes Rule</h2><p>When asking questions one should be careful not to develop a habit of delegating one&#x27;s problems to somebody else. Reaching out for help in a dire situation is a rightful thing to do, yet none of us truly enjoys the struggle, so it&#x27;s natural that we experience satisfaction and joy when the long-awaited help arrives. For that help to last longer try to learn to evaluate the situation before asking, which would prevent occassionally unnecessary questions and give you the sense of standalone accomplishment.</p><div>In the end, expect the quality of the answer to be proportionate to the time you were willing to spend finding it.</div><p>What helped me during my career is adopting the 15 minutes rule. Whenever I find myself in a struggle, I dedicate 15 minutes of highly focused time to solve the matter at hand by myself. By the end of that time I check if the question I had is still relevant, and if it&#x27;s not I tackle the next question that arose with another 15 minutes. Only when my effort proves unfruitful I raise a question to a colleague or a fellow developer.</p><p>This rule is extremely useful, because it brings value to your question. Often you may learn a thing or two while attempting to solve the issue, if not find the answer. The knowledge you acquire and the approaches you try may help your future advisor to tackle your question more precisely, and the effort you put into looking into it acts as a solid foundation for compassionate and emphathetic response.</p><h2 id="be-patient">Be patient</h2><p>Software engineering can be stressful: a customer losing their revenue due to an issue, a manager enraged over a missed deadline—we&#x27;ve all been there. Getting stressed doesn&#x27;t really solve those situations, neither will it find the answer to your question.</p><p>Remember that explaining is equally difficult as asking the right question, and a person that put down their time to help you may struggle to find the right way to bring it to you. Patience and kindness go a long way.</p><h2 id="help-others">Help others</h2><p>No matter how inexperienced you may think you are, there is always a person one step behind you. That person is following a similar journey, but may not have got their head around certain concepts or patterns as you did. Keep that in mind next time you see somebody confused over a topic you find utterly clear. Offer them help.</p><div>Offering help is just as useful as asking for one.</div><p>Altruism isn&#x27;t the only reason to offer others help. Explaining is perhaps the best way to ensure your understanding. As we all think and remember things differently, at first it will be challenging to broadcast your thoughts to the person in need. Sometimes it would require you to validate the material you&#x27;ve learned, lest you give a false or incomplete answer. It may help you locate a few blind spots in your own knowledge!</p><h2 id="draw-a-conclusion">Draw a conclusion</h2><p>Getting the answer is sure thing rewarding, yet try to keep it in your head for a while. A problem isn&#x27;t a burning furnace, and throwing one answer after another won&#x27;t do any good, as the purpose of asking is to learn. Getting a valuable information from the answer may require to look back at the original problem and draw a conclusion. What caused the problem? What was the solution? Did the solution affect the cause directly or indirectly? Is there any supplimentary knowledge that could have helped in solving this problem?</p><p>Believe me or not, learning is a skill of its own, as we all learn, remember, and explain things in a drastically different manner. So while at it, why not to boost another skill when the answer is already in your hands? Experiment and find the way of learning that works the best for you, be it drawing a diagram, writing a small documentation, or hoarding useful links in your bookmarks. Next time a question pops out, your learning vault is a great place to start with the 15 minutes rule!</p></content:encoded></item><item><title><![CDATA[The Plague of Linters]]></title><description><![CDATA[You have a project and you want to maintain its code style, prevent typos and other mistakes to land in your repository, and get suggestions…]]></description><link>https://redd.one/the-plague-of-linters</link><guid isPermaLink="false">https://redd.one/the-plague-of-linters</guid><pubDate>Fri, 10 Jul 2020 00:00:00 GMT</pubDate><content:encoded><p>You have a project and you want to maintain its code style, prevent typos and other mistakes to land in your repository, and get suggestions that can occassionally improve your application&#x27;s logic. Most likely, you use linters for that task.</p><blockquote><p>Linter is a program that analyzes your code against a set of defined rules. One of the most popular linters in JavaScript is <a href="https://eslint.org">ESLint</a>.</p></blockquote><p>With tools like JSHint, JSLint and ESLint, checking (linting) our JavaScript code became possible and widespread. Unfortunately, its popularity was followed by what I call the Plague of Linters.</p><p>Today I would like to discuss with you the purpose of linting, go through the most common mistakes people make when setting up a linter in their projects, and spread a few thoughts that I wish were more present in our ever-evolving ecosystem.</p><hr/><h2 id="if-you-like-it-then-you-shoulda-ctrlc-on-it">If you like it, then you shoulda <code>Ctrl+C</code> on it</h2><p>The biggest and most dreadiest mistake developers make when introducing and maintaining their linter is copy-pasting a linting configuration from another projects. Let me elaborate.</p><p>Imagine you&#x27;re bootstrapping a new app, and you want to have code consistency and basic quality assurance at place. You reach for your favorite linter and, while installing it, your fingers subconsciously type:</p><pre><code class="language-bash">$ npm install eslint-config-airbnb | |
| </code></pre><p><em>&quot;Well, why shouldn&#x27;t I use AirBnB&#x27;s linting setup?&quot;</em> you stop for a moment, <em>&quot;They are a world-known successful company, they must know something about code quality, and I want to use their experience!&quot;</em></p><p>There is one issue, though: you are not AirBnB. Adopting their linter configuration doesn&#x27;t make you AirBnB, and doesn&#x27;t automatically make your code better and your project successful. All you are doing by using their configuration is blindly copying the result of their journey without taking one of your own.</p><p>Settle with the idea that each project may require a different set of linting rules, and that&#x27;s perfectly fine. Moreover, it&#x27;s much more preferable and thoughtful than copy-pasting code in general.</p><hr/><h2 id="choose-what-works-best-for-you">Choose what works best for you</h2><p>What I&#x27;m about to say may bring you into a state of shock, but bear with me:</p><div>Go through <u>each</u> ESLint rule and configure it so it works for <u>your</u> team.</div><p><em>&quot;What?! That&#x27;s going to take forever! Why should I waste my time on this?&quot;</em> I hear you exclaim in fury. But wait, you already spend time on configuring your CI pipeline, API clients, or state management. Why do you think that spending time on a tool that ensures the overall code consistency is not worth of your time? Having a set of rules that support your code style is an absolute must to establish a solid and pleasant developer experience.</p><p>If time is your main concern, organize this as a team activity. In the end, all developers will be using these rules on a daily basis, so they should participate in deciding what would suit them. Overall, <a href="https://eslint.org/docs/rules/">revisiting each rule</a> and making a choice won&#x27;t take you more than 1 hour, but will inevitably ensure your developer comfort and code consistency for years.</p><p>The best part is that once you&#x27;re settled on the rules, you can try them out and abstract those that work into your own ESLint configuration (just like AirBnb did!). This would give you a solid linting foundation and minimize the bootstrapping time of the next project. You don&#x27;t really want to adopt dramatically different coding style across projects, as that would be against the concistency that you strive towards.</p><hr/><h2 id="its-not-written-in-stone">It&#x27;s not written in stone</h2><p>Here&#x27;s another totally crazy statement:</p><div>If a linting rule doesn&#x27;t help you—remove it.</div><p>The only purpose of a linter is to make your life as a developer easier and help you develop with confidence. However, in reality it&#x27;s often the contrary: developers treat their linting rules like a law, no matter how obscure, rejoicing that it can be occassionally broken with <code>/* eslint-disable */</code>.</p><p>The rules you configure are for you. If you, or your team, struggle because of a certain linting rule, discuss it and disable it, if necessary. You are <strong>not</strong> compromising on code&#x27;s quality by disabling linting rules. The harm an obscure rule can do is tenfold higher than any implications of removing it.</p><p>Staying objective and respectful of your team&#x27;s previous choices is crucial when discussing linting rules that you struggle with. Certain decisions have a history behind them, and you can get used to them (or even adopt them yourself) through time. That being said, if you do struggle, voice that and provide some meaningful arguments to why you find a specific rule obstructing in your work.</p><div>Developers don&#x27;t have time to think about user experience if their developer experience suffers.</div><blockquote><p>This point is especially critical when there is no code formatting tool to support your stylistic choices. The fact that I need to think whether I&#x27;ve added a semicolon, removed a trailing comma, or forgot to put a shorthand object property first—that&#x27;s a time waste. This time can be spent on getting a linting config that works, or even better—getting the work done.</p><p>Generally, I highly recommend using tools like <a href="https://prettier.io">Prettier</a> to format your code and forget about stylistic choices altogether. It will feel weird at first, but you will thank me later.</p></blockquote><p>Try to understand and encourage that linting is something configured by you, maintained by you, and aimed to help you. There are no such things as conventions, good, or bad practices in the automatic code checks. There are no bad decisions in linting rules, apart from those blindly copied and those that obscure and block your working process.</p><hr/><h2 id="iterate-iterate">Iterate, iterate!</h2><p>Imagine that one day you&#x27;ve decided to start brewing coffee at home. You had no idea how to do that, so you looked up some articles, watched some videos, and the overall idea of the brewing process has shapened up in your head. Although you wouldn&#x27;t call the first few times ideal, you can feel how it slowly begins to click for you with each next try. A couple of months pass and you can make your favorite espresso in a matter of minutes, almost effortless! You also noticed that you&#x27;ve slightly adjusted the initial process to your specific needs. That adjustment, that adaptation, is an important part of any learning process.</p><p>There&#x27;s a notion amongst developers that a linting configuration is something written once and never touched again. I don&#x27;t know where it comes from, but let my demystify it once and for all:</p><div>Linting rules is about your choice. Your choices change as you evolve. Let your linter reflect that.</div><p>It is only by iterating over your configuration that you prove your choices with time, and filter out those that are not relevant anymore, or didn&#x27;t last. As a developer, don&#x27;t hesitate to express your unease with linting. Remember, linter is here to help you, not the other way around.</p><hr/><h2 id="summary">Summary</h2><ul><li>Configure a set of rules that work for your/your team;</li><li>Iterate on your config: replace or remove rules that block the process, or add the rules that could&#x27;ve saved you;</li><li>Isolate common rules into your custom configuration preset;</li><li>Set up <code>pre-commit</code>/<code>pre-push</code> Git hooks to lint your code automatically (invalid code must never be committed to Git);</li><li>Get a feedback from your team on the linting setup.</li></ul><h2 id="afterword">Afterword</h2><p>Thanks for reading through this article! I hope I managed to show you how important it is to treat your linting setup a something you have control over. Share these tips with your team and have a great developer experience when working on amazing products.</p><p>Let me know on <a href="https://twitter.com/kettanaito">Twitter</a> if you would like to read more insights on efficient linting setup, or how to use Git hooks to bring linting to the next level. I&#x27;d love to know if this resonates with you. Thanks.</p></content:encoded></item><item><title><![CDATA[Building a tree-shakable library with RollupJS]]></title><description><![CDATA[There are multiple reason to pick RollupJS as your bundler of choice when creating a JavaScript library: a minimalistic configuration…]]></description><link>https://redd.one/building-a-tree-shakable-library-with-rollupjs</link><guid isPermaLink="false">https://redd.one/building-a-tree-shakable-library-with-rollupjs</guid><pubDate>Sun, 28 Jun 2020 00:00:00 GMT</pubDate><content:encoded><p>There are multiple reason to pick <a href="https://rollupjs.org">RollupJS</a> as your bundler of choice when creating a JavaScript library: a minimalistic configuration, built-in way to compile into various formats, and extensive tree-shaking support. Today we are going to look at tree-shaking from the perspective of a library author, rathen than a consumer.</p><hr/><h2 id="what-is-tree-shaking">What is tree-shaking?</h2><p><em>Tree-shaking</em> (also known as <em>dead code elimination</em>) is a bundling technique that allows to remove an unused code from the build. The unused code is the one nothing else depends on. That dependency relation is determined by a bundler/compiler on build time, making tree-shaking a build technique.</p><p>Tree-shaking is often approached on a consumer&#x27;s level, meaning that our <em>built application</em> does not ship an unused code. While this is a perfectly valid concern, those third-party tools (i.e. open source libraries) we use must support tree-shaking as well, otherwise there&#x27;s nothing we can do about a dead code.</p><blockquote><p>This article will refer to any JavaScript application using a library as a <em>consumer</em>.</p></blockquote><h3 id="what-do-we-want">What do we want?</h3><p>Let&#x27;s say we are writing a library called <code>my-lib</code> that exports two functions: <code>funcA</code> and <code>funcB</code>. Neither of those can be tree-shaken when building our library, because we don&#x27;t know which functions the constumer will require. However, we need to bundle our library the way that everything that the consumer doesn&#x27;t use gets dropped.</p><p>Here&#x27;s an example of what we expect from the source and built code of the consumer:</p><pre><code class="language-js">// consumer/src/index.js | |
| // Although &quot;my-lib&quot; exports both &quot;funcA&quot; and &quot;funcB&quot;, | |
| // since we only rely on &quot;funcA&quot;, we expect &quot;funcB&quot; | |
| // to get tree-shaken (removed) from our application&#x27;s build. | |
| import { funcA } from &#x27;my-lib&#x27; | |
| funcA() | |
| </code></pre><pre><code class="language-js">// consumer/build/index.js | |
| ;(function (factory) { | |
| typeof define === &#x27;function&#x27; &amp;&amp; define.amd ? define(factory) : factory() | |
| })(function () { | |
| &#x27;use strict&#x27; | |
| function funcA() { | |
| console.log(&#x27;Hello from the module A!&#x27;) | |
| } | |
| funcA() | |
| }) | |
| </code></pre><blockquote><p>Notice how the <code>funcB</code> is nowhere to be found in the application&#x27;s build. <em>That</em> is our end goal.</p></blockquote><p>As natural as it may look, this is not the default behavior, and it requires a certain setup on both the library&#x27;s and consumer&#x27;s sides. So what do we, library authors, need to do in order to ship a tree-shaking support to our users?</p><hr/><h2 id="build-format">Build format</h2><p>First of all, we need to bundle our library using a proper build format.</p><p>Choosing a proper format is crucial, because certain formats make our library&#x27;s dependencies impossible to statically analyze. For example, if we ship a library in a CommonJS format, a consumer won&#x27;t be able to figure out which modules can be tree-shaken, because their dependnecies may change on runtime.</p><pre><code class="language-js">// my-lib/build/cjs/index.js | |
| function funcA(moduleName) { | |
| // Impossible to analyze what &quot;funcA&quot; depends on, | |
| // because the &quot;require&quot; statement below will change | |
| // depending on the &quot;moduleName&quot; argument. | |
| require(`./utils/${moduleName}`) | |
| } | |
| module.exports = { funcA } | |
| </code></pre><p>When a bundler (i.e. webpack or Rollup) transforms our library&#x27;s code, it must meet <em>static import statements</em> (<code>import</code>) to determine which modules can be safely removed. Static import statements are such that cannot change on runtime (thus, &quot;static&quot;).</p><div>In order for our library to be tree-shakable, it must preserve static import statements.</div><p>To preserve those imports we need to distribute our library using <strong>ESM</strong> format. ESM (ECMAScript Module) format comes with a <a href="https://exploringjs.com/es6/ch_modules.html#static-module-structure">static module structure</a>, which means that a module&#x27;s dependencies can be determined by looking at the code, without having to run it.</p><p>We can use a <code>format</code> output option in the Rollup configuration to build our library into ESM:</p><pre><code class="language-js" metastring="focusedLines=6,7" focusedLines="6,7">// my-lib/rollup.config.js | |
| module.exports = { | |
| // ..., | |
| output: [ | |
| { | |
| dir: &#x27;library/build&#x27;, | |
| format: &#x27;esm&#x27;, | |
| }, | |
| ], | |
| } | |
| </code></pre><p>However, a right format is not enough for our library to become fully tree-shakable. We also need to specify a proper relation between the modules in our library by configuring its entry points.</p><h2 id="entry-points">Entry points</h2><p>It&#x27;s often for a code to be reused between the parts of a library. If such code comes from a module that you would want to tree-shake, it may get problematic. Consider this:</p><pre><code class="language-js">// my-lib/src/a.js | |
| // Here we are importing a helper function from the module B, | |
| // making it a dependency of the module A (current module). | |
| import { print } from &#x27;./b&#x27; | |
| export function funcA() { | |
| print(&#x27;Hello from module A!&#x27;) | |
| } | |
| </code></pre><pre><code class="language-js">// my-lib/src/b.js | |
| // A helper function that semantically belongs to module B, | |
| // but can be imported and used in other modules as well. | |
| export function print(message) { | |
| console.log(message) | |
| } | |
| export const funcB = () =&gt; { | |
| print(&#x27;Hello from module B!&#x27;) | |
| } | |
| </code></pre><p>With the <code>a.js</code> module importing the <code>print</code> function from <code>b.js</code>, the latter effectively becomes its dependency. Now, even if our consumer doesn&#x27;t use <code>funcB</code>, they would still import and ship the entire <code>b.js</code>, because <code>a.js</code> relies on its helper function.</p><p>Surely, we can isolate the <code>print</code> function into its own module and reuse it between any other pieces of the library. However, this delegates dependency management into our hands, which makes it prone to mistakes. Instead, we can configure our library&#x27;s entry points, so that Rollup figures out the cross-module dependencies for us.</p><p>To set multiple entries we need to provide a Rollup config with the <code>input</code> option that has a list of modules.</p><pre><code class="language-js" metastring="focusedLines=3" focusedLines="3">// my-lib/rollup.config.js | |
| module.exports = { | |
| input: [&#x27;src/index.js&#x27;, &#x27;src/a.js&#x27;, &#x27;src/b.js&#x27;], | |
| // ... | |
| } | |
| </code></pre><p>Such build configuration will not only generate separate chunks for each given input, but can also figure out their dependency between each other, putting a shared code into common chunks.</p><p>With the entry points configured, our build folder structure may look as follows:</p><pre><code class="language-bash" metastring="focusedLines=4" focusedLines="4">└─build | |
| └─esm | |
| ├─a.js | |
| ├─a-deps.js # `print` from `src/b.js` would be here | |
| └─b.js | |
| </code></pre><p>Now, if the <code>b.js</code> module is never used by the consumer, it will get tree-shaken, because neither consumer, nor internal library&#x27;s modules rely on it.</p><h2 id="distribution">Distribution</h2><p>Although ESM is the future of the modules distribution, we are not quite ready for that future yet. With that in mind, it&#x27;s not a good decision to specify the ESM bundle as the <code>main</code> entry of your package. Instead, there&#x27;s a dedicated <code>module</code> property in <code>package.json</code> that modern tools, like webpack and Rollup, can pick up and use.</p><p>Provide the path to your ESM build in the <code>module</code> property of your library&#x27;s <code>package.json</code>:</p><pre><code class="language-json" metastring="focusedLines=7" focusedLines="7">// my-lib/package.json | |
| { | |
| // CommonJS build as default | |
| &quot;main&quot;: &quot;lib/cjs/index.js&quot;, | |
| // ESM build for modern bundlers | |
| &quot;module&quot;: &quot;lib/esm/index.js&quot; | |
| } | |
| </code></pre><hr/><h2 id="summary">Summary</h2><p>Building a tree-shakable library with RollupJS consists of these steps:</p><ol><li>Choose a proper build target format (ESM);</li><li>Specify the library&#x27;s entry points (to analyze their inter-dependencies);</li><li>Provide the ESM build path as the <code>module</code> property of the library&#x27;s <code>package.json</code>.</li></ol><p>Below you can find a GitHub repository that contains a library setup and the example of a consumer application that is using that library. Follow the instructions in this repository to see the tree-shaking for yourself:</p><div owner="Redd-Developer" repo="rollup-tree-shakable-library"></div><h2 id="afterword">Afterword</h2><p>Thanks for reading through! I hope you&#x27;ve learned a thing of two about JS modules and tree-shaking, and wish you to ship awesome libraries to your users! Let me know on Twitter about your experience with creating and shipping libraries.</p></content:encoded></item><item><title><![CDATA[Efficient CircleCI debugging with SSH]]></title><description><![CDATA[Introduction I have been actively using CircleCI in my projects for years now and I love it! However, I'm ashamed to admit that most of…]]></description><link>https://redd.one/efficient-circleci-debugging-with-ssh</link><guid isPermaLink="false">https://redd.one/efficient-circleci-debugging-with-ssh</guid><pubDate>Mon, 11 May 2020 00:00:00 GMT</pubDate><content:encoded><h2 id="introduction">Introduction</h2><p>I have been actively using <a href="https://circleci.com/">CircleCI</a> in my projects for years now and I love it! However, I&#x27;m ashamed to admit that most of the failed jobs took me up to 1 hour to get right. By the time I saw CI pass, I had grew an unrivaled hatred towards the red color.</p><p><span class="gatsby-resp-image-wrapper" style="position:relative;display:block;margin-left:auto;margin-right:auto;max-width:1200px"> | |
| <a class="gatsby-resp-image-link" href="/static/1acec2762e974b679d3f326111325338/7575b/ci-failed.png" style="display:block" target="_blank" rel="noopener"> | |
| <span class="gatsby-resp-image-background-image" style="padding-bottom:69.66666666666667%;position:relative;bottom:0;left:0;background-image:url(&#x27;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAOCAYAAAAvxDzwAAAACXBIWXMAAAsSAAALEgHS3X78AAAB3ElEQVQ4y5WSyU7kQBBE/WUIsd7hxPoBSHwfMwckNkEfQKyH4dRST/c0HHpxlfctJqKMGTPISFh6yrQ7MjIrq70qCJA/PtY8PdUov7lBfn+P/Pa25u7uY97Wi4cHlL4PL+MP/upqzdpaHdfXERwcwGxuwu7twe7u1uzvE77v7DhNU2OULy4iPTujIZ3N8jLsygosBS5SFB0eItjYQEiTUKZbW7W52N6GT52/tASftUb5wgLS01N4pTGIez2El5ewFxd1PD+HOT5GwI725AQhY05NfnVVo/z6+gMJvxeTCbwKQE6CosArdzCNYxf/zOd4UZzNMIkiSNf1lCSqKqfxyrJEHIYIOGnCwoiXpHdQ0KbM804qDiNK4lUUG5qNRiOMx2MMh0P0+32o0Xce+QhPLz+PfqCnvbDbjEeMOGnIKZWrmc+jK59zDYrWWlfcafj86xmDwcB9kFGapo6Y+0ySxKFcjRSzLPu3P56kjdccTSJNoO6i8wKoV7PpdOrM29M5QyUpzWJ2l2jCqxeNqI0KCi5ehobNszT5bNiIMt3Sf5O0UYF0Tk+CvICfZq6uMXufsOBl2IQ7owhvP3ZNqIuLaTSyIX6bEIlqNED7yM7grYOm+Ipmkvf/Z6tGXn8BdNwKKMedoeEAAAAASUVORK5CYII=&#x27;);background-size:cover;display:block"></span> | |
| <img class="gatsby-resp-image-image" alt="CircleCI failed job" title="CircleCI failed job" src="/static/1acec2762e974b679d3f326111325338/c1b63/ci-failed.png" srcSet="/static/1acec2762e974b679d3f326111325338/5a46d/ci-failed.png 300w,/static/1acec2762e974b679d3f326111325338/0a47e/ci-failed.png 600w,/static/1acec2762e974b679d3f326111325338/c1b63/ci-failed.png 1200w,/static/1acec2762e974b679d3f326111325338/7575b/ci-failed.png 1608w" sizes="(max-width: 1200px) 100vw, 1200px" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0" loading="lazy"/> | |
| </a> | |
| </span></p><p>In this post I would like to share a mind-blowing technique of debugging failed CircleCI jobs suggested by <a href="https://twitter.com/FelicianoTech">Ricardo Feliciano</a>. As the time passed, I have adopted this technique even outside of CI, but I believe there are developers who are as alien to this approach just as I once was. I will also add a few personal tricks and tips to make the most out of this topic. Let&#x27;s learn how to resolve failed jobs in a fast and efficient manner.</p><hr/><h2 id="reproducing-an-issue">Reproducing an issue</h2><p>Reliable issue verification is the absolute must in order to resolve any problem. We follow steps not only to reproduce an issue, but also to verify when it&#x27;s been successfully fixed. There is a myriad of things that can affect an issue&#x27;s reproduction: environment, connection speed, asynchronicity, dark magic. When your CI runs remotely, all of those factors are, inevitably, at play.</p><div>The issue that cannot be reproduced cannot be fixed.</div><p>Thus, whenever a remote job fails, it&#x27;s in our best interest to match the context in witch it failed as close as possible to provide a viable fix. Gladly, there is a way to connect to the very machine that&#x27;s running our job and explore its state. Enter SSH.</p><h2 id="ss-what">SS-what?</h2><p><strong>Secure Shell</strong> (also SSH) is a network protocol that encrypts data packages sent over an insecure connection. SSH establishes a tunnel between a verified client and a server, encrypting any data that flow in-between.</p><p>Originally designed by <a href="https://twitter.com/tjssh">Tatu Ylönen</a> in Helsinki University of Technology, SSH has been widely adopted, gradually becoming a standard in software engineering. Most of the websites you visit today use SSH for various purposes, like sendind and acceptind traffic, or transfering files.</p><p>In this tutorial we are primarily interested in these applications of SSH:</p><ul><li>Logging to a shell on a remote host (machine);</li><li>Transferring files.</li></ul><h2 id="ssh-setup">SSH setup</h2><p>Connecting to a remote host via SSH is like openning a door: one requires a key. An SSH key allows a remote machine to recognize a connecting host and decide whether to grant access. For the purpose of this tutorial I presume that your CircleCI is connected with your <strong>GitHub acount</strong>. This means that GitHub will be responsible for providing your SSH key to CI.</p><blockquote><p>You can skip this section if you are familiar with SSH keys and have an SSH key generated and connected to your CircleCI account.</p></blockquote><h3 id="check-existing-ssh-keys">Check existing SSH keys</h3><p>First, check if you don&#x27;t have any SSH keys already on the <a href="https://github.com/settings/keys">SSH and GPG keys</a> page in your GitHub account. In case you do, you should see the list of your active SSH keys:</p><p><span class="gatsby-resp-image-wrapper" style="position:relative;display:block;margin-left:auto;margin-right:auto;max-width:1200px"> | |
| <a class="gatsby-resp-image-link" href="/static/f7f580a52882346bd701a0324e8f5b07/d2433/github-ssh-keys.png" style="display:block" target="_blank" rel="noopener"> | |
| <span class="gatsby-resp-image-background-image" style="padding-bottom:17.333333333333336%;position:relative;bottom:0;left:0;background-image:url(&#x27;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAADCAYAAACTWi8uAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAgElEQVQI13WMywrCMBRE+/9f6MaNirRN0OadNvf2KLG40oHDwDAzwyYbp8eZycxcrjfu44ixFuc9MSZSSoQYCSGQS+GXVBU/W2ouDK01allxyTM5w7QYjLM880IqmcV5al2/433ffyJbQ0QY5P3eA5UD7TT5FFqT7nrk+o/+obwAY2zqXoni+cYAAAAASUVORK5CYII=&#x27;);background-size:cover;display:block"></span> | |
| <img class="gatsby-resp-image-image" alt="GitHub SSH keys list" title="GitHub SSH keys list" src="/static/f7f580a52882346bd701a0324e8f5b07/c1b63/github-ssh-keys.png" srcSet="/static/f7f580a52882346bd701a0324e8f5b07/5a46d/github-ssh-keys.png 300w,/static/f7f580a52882346bd701a0324e8f5b07/0a47e/github-ssh-keys.png 600w,/static/f7f580a52882346bd701a0324e8f5b07/c1b63/github-ssh-keys.png 1200w,/static/f7f580a52882346bd701a0324e8f5b07/d61c2/github-ssh-keys.png 1800w,/static/f7f580a52882346bd701a0324e8f5b07/97a96/github-ssh-keys.png 2400w,/static/f7f580a52882346bd701a0324e8f5b07/d2433/github-ssh-keys.png 2600w" sizes="(max-width: 1200px) 100vw, 1200px" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0" loading="lazy"/> | |
| </a> | |
| </span></p><p>Alternatively, check for any existing SSH keys on your local machine by running:</p><pre><code class="language-bash">$ ls -la ~/.ssh | |
| </code></pre><p>Running the command above will list the available SSH keys, if any. SSH keys file names usually look like this:</p><pre><code>id_rsa.pub | |
| id_ecdsa.pub | |
| </code></pre><p>In case you don&#x27;t have any SSH keys, or would like to create a new one for the sake of this tutorial, please follow the instructions below.</p><h3 id="cretate-new-ssh-key">Cretate new SSH key</h3><p>First, let&#x27;s generate a new SSH key:</p><pre><code class="language-bash">$ ssh-keygen -t rsa -b 4096 -C &quot;your_email@domain.com&quot; | |
| </code></pre><blockquote><p>Use your GitHub user email.</p></blockquote><ul><li><code>-t</code>, a type of a key to create (<code>dsa</code>, <code>ecdsa</code>, <code>ed25519</code>, <code>rsa</code>);</li><li><code>-b</code>, the number of bits in the key (for the <code>rsa</code> key type should be greater than <code>768</code>);</li><li><code>-C</code>, a key comment. The value of this comment is an email that is going to be validated to identify your connections.</li></ul><p>Running the <code>ssh-keygen</code> command above will ask you where to save a newly created SSH key, and you can choose the default option, which would be in the <code>~/.ssh</code> directory. You may also choose to encrypt your new SSH key with a pass-pharse, just bear in mind you would have to enter it each time you use that key.</p><p>Verify that a new SSH key has been created by running the following command:</p><pre><code class="language-bash">$ ls -la ~/.ssh | |
| # Should return the list of files that includes your newly created SSH key: | |
| # | |
| # -rw------- 1 username staff 1234 Feb 1 2020 id_rsa | |
| # -rw-r--r-- 1 username staff 1234 Feb 1 2020 id_rsa.pub | |
| </code></pre><h3 id="add-ssh-key-to-ssh-agent">Add SSH key to ssh-agent</h3><p>Regardless of which SSH key you&#x27;ve decided to use, it must be added to yout ssh-agent. Think of SSH agent as a keychain that stores your SSH keys.</p><p>Start the agent in the background:</p><pre><code class="language-bash">$ eval &quot;$(ssh-agent -s)&quot; | |
| # Agent pid 12345 | |
| </code></pre><p>Modify your <code>~/.ssh/config</code> file by adding the following section:</p><pre><code class="language-bash">Host * | |
| AddKeysToAgent yes | |
| UseKeychain yes | |
| # Point to the generated SSH key | |
| IdentityFile ~/.ssh/id_rsa | |
| </code></pre><p>Lastly, add the SSH key to the agent:</p><pre><code class="language-bash">$ ssh-add -K ~/.ssh/id_rsa | |
| </code></pre><ul><li><code>-K</code>, is a MacOS-specific option that tells ssh-agent to store your key in the keychain. Skip this option when using a different OS.</li></ul><p>Verify that you have got your SSH key loaded to the agent by running this command:</p><pre><code class="language-bash">$ ssh-add -l | |
| # 4096 SHA256:03eb924754b981b2aed90b699ff513cb0b6f4f93c35 your.email@host.com (RSA) | |
| </code></pre><h3 id="add-ssh-key-to-github">Add SSH key to GitHub</h3><p>Please follow the official instructions on <a href="https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account">Adding a new SSH key to your GitHub account</a>. Once successful, you should see the SSH key in your <a href="https://github.com/settings/keys">SSH and GPG keys</a> page.</p><hr/><h2 id="running-circleci-job-with-ssh">Running CircleCI job with SSH</h2><p>Once our SSH setup is done, let&#x27;s switch to the CI part. In order to ssh into a remote host responsible for a particular job, that job must be run with SSH first. You can do that directly from the CircleCI UI by following these instructions:</p><ol><li>Open a failed job&#x27;s detail page.</li><li>Locate the &quot;<strong>Rerun workflow</strong>&quot; button.</li><li>Open the dropdown and choose &quot;<strong>Rerun job with SSH</strong>&quot; option.</li></ol><p><span class="gatsby-resp-image-wrapper" style="position:relative;display:block;margin-left:auto;margin-right:auto;max-width:1200px"> | |
| <a class="gatsby-resp-image-link" href="/static/213fb48c6f4fd5155ea04451f9bfc5e3/ac25d/circleci-rerun-ssh.png" style="display:block" target="_blank" rel="noopener"> | |
| <span class="gatsby-resp-image-background-image" style="padding-bottom:39.666666666666664%;position:relative;bottom:0;left:0;background-image:url(&#x27;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAICAYAAAD5nd/tAAAACXBIWXMAABYlAAAWJQFJUiTwAAABkklEQVQoz4WPy05aURSGz2tAuISBQLiMSJg1+gReJoxNDU8kktoYrQ+giTisMe2wjZREbodboXCOEBA8nHPAQUk+995RB+2AwZe117///a+1tUAgwL/4/X5CoRCZTIZIJILP5/vPEwwG8Xg87Ozt8mFrE6/Xy0Z4Ay0WixGPx5H17SxJJpNks1nS6TTRaFRpiUTi3Sfvw+Ew+wcf2d7bUYNTqRRas9mkWq0ia6PRoFarqV6eS6USlUrlXS+Xy+i6rpC61Ip3RX4Vi8rTarXQbNtWYaZp0u12qdfrqg4GAzqdjno0Ho8ZjUa0221msxnT6ZRer0e/31e69E0mE1arFZo0PxgGv4W5LYJbDR1LPNJFUOX+nj8ifPb4yLPrshQsHIeFWGL52i9FL6s7n+MIXTOGQ+piUlNsqMtgMcAUl4Y1ZyQDAFfgrEF63L9yw1qV4fk55skJRu4QM5djmM/zkD9ifPwJ6/QU62wNX86wPh9j396iPYkvLb5/w735inN9LShgv1EoMC9crUX5Li9wfv7gBY1K5lgMD5XSAAAAAElFTkSuQmCC&#x27;);background-size:cover;display:block"></span> | |
| <img class="gatsby-resp-image-image" alt="Rerun job with SSH" title="Rerun job with SSH" src="/static/213fb48c6f4fd5155ea04451f9bfc5e3/c1b63/circleci-rerun-ssh.png" srcSet="/static/213fb48c6f4fd5155ea04451f9bfc5e3/5a46d/circleci-rerun-ssh.png 300w,/static/213fb48c6f4fd5155ea04451f9bfc5e3/0a47e/circleci-rerun-ssh.png 600w,/static/213fb48c6f4fd5155ea04451f9bfc5e3/c1b63/circleci-rerun-ssh.png 1200w,/static/213fb48c6f4fd5155ea04451f9bfc5e3/d61c2/circleci-rerun-ssh.png 1800w,/static/213fb48c6f4fd5155ea04451f9bfc5e3/ac25d/circleci-rerun-ssh.png 2342w" sizes="(max-width: 1200px) 100vw, 1200px" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0" loading="lazy"/> | |
| </a> | |
| </span></p><p>Clicking on the option will run the respective job anew, yet this time CircleCI will issue an SSH connection to the remote machine. You can notice that a new step has been added that describes details of that connection:</p><p><span class="gatsby-resp-image-wrapper" style="position:relative;display:block;margin-left:auto;margin-right:auto;max-width:1200px"> | |
| <a class="gatsby-resp-image-link" href="/static/2e05b31bec3d7c2c5d15cf400327822a/d4e7f/ci-enable-ssh.png" style="display:block" target="_blank" rel="noopener"> | |
| <span class="gatsby-resp-image-background-image" style="padding-bottom:47.66666666666667%;position:relative;bottom:0;left:0;background-image:url(&#x27;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAKCAYAAAC0VX7mAAAACXBIWXMAAAsSAAALEgHS3X78AAAByklEQVQoz52Ry27aUBCGvWfByhUgbibFF2x8wbZCMJA9NkQV6iOhhotUVd2DgBfgRXiMhA1quAhDFKE/nkOFsqiqqpY+zZmL5/xzhns7vuLp+Rmr1Qrb7Rb/853PZ6zXa4RhCO71cMSvlxdsNhvs93scj8e/EoYXPsYOhwN2ux1OpxO4r1+68AMf7XY7IkCn04bvtyL8K61WC0EQ4OGhc4V8qqP/ut0ums0mFosFOPmziKJYhGkaKJUUOE4Ful6GZZnMEooiI5/PQxDyuLkpMMjP5XJRTIAkiYjH45hMJuBMrcwaKooCWZZZU01ToaolFiOfEEXxA0VmqV6SpChfQjKZxGw2A+fdVmGYeqTMwf19I1JmoVzWWFNqpKrqH6E8qdc0DZWKxRpOp1NwtmExhXQjKSJ7GU9goxUKl/Gy2SzS6XRE5jdpZDIZNjbleZ6/KKw6LmreHarVW9Rqd6jXPXZ2XQeeV0OjUWeWVOi6zt7WMPTozU0mgC4kEYlEAvP5HFxRKMBx7esSqNiyDLYkOtOS3ChPDR3Hhm1XWI5itAye/4RUKoVYLIbxeAzu5/cf+Pb4iMFgcKXf7/8TVDscDjEajdDr9bBcLvEOEjWyV70hhWoAAAAASUVORK5CYII=&#x27;);background-size:cover;display:block"></span> | |
| <img class="gatsby-resp-image-image" alt="SSH connection details" title="SSH connection details" src="/static/2e05b31bec3d7c2c5d15cf400327822a/c1b63/ci-enable-ssh.png" srcSet="/static/2e05b31bec3d7c2c5d15cf400327822a/5a46d/ci-enable-ssh.png 300w,/static/2e05b31bec3d7c2c5d15cf400327822a/0a47e/ci-enable-ssh.png 600w,/static/2e05b31bec3d7c2c5d15cf400327822a/c1b63/ci-enable-ssh.png 1200w,/static/2e05b31bec3d7c2c5d15cf400327822a/d4e7f/ci-enable-ssh.png 1416w" sizes="(max-width: 1200px) 100vw, 1200px" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0" loading="lazy"/> | |
| </a> | |
| </span></p><p>Those details are likely be different in your case, but your primarily interest should fall onto the machine&#x27;s host (<code>100.26.97.124</code>) and port number (<code>64536</code>). Remember those. CircleCI would also print out a shorthand connection command, which we are going to use in the next step.</p><h2 id="into-the-remote">Into the remote!</h2><h3 id="using-default-key">Using default key</h3><p>(Recommended) If your main SSH key is the one associated with your GitHub account, execute the SSH command CircleCI printed out in the &quot;Enable SSH&quot; step:</p><pre><code class="language-bash">$ ssh -p 64536 100.26.97.124 | |
| </code></pre><h3 id="using-explicit-key">Using explicit key</h3><p>In case you have got multiple SSH keys you would have to specify which one to use to connect to the remote machine. Provide the path to the same SSH key you use for GitHub as the value of the <code>-i</code> flag in <code>ssh</code> command:</p><pre><code class="language-bash">$ ssh -i ~/.ssh/id_rsa -p 64536 100.26.97.124 | |
| </code></pre><h3 id="establishing-connection">Establishing connection</h3><p>Using a UNIX-based computer, you can connect to a remote SSH server by running <code>ssh</code> command:</p><pre><code class="language-bash">$ ssh -p 64536 100.26.97.124 | |
| </code></pre><blockquote><p>Answer &quot;yes&quot; if prompted with &quot;Are you sure you want to continue connecting&quot;.</p></blockquote><p>When successfully executed, you will notice your terminal&#x27;s working directory changing to the remote machine&#x27;s name. Any commands issued in this process from now on are executed on the remote machine. For example, we can run the entire build again, or each command in isolation (i.e. <code>npm test</code>, or <code>npm run build</code>).</p><p><span class="gatsby-resp-image-wrapper" style="position:relative;display:block;margin-left:auto;margin-right:auto;max-width:1200px"> | |
| <a class="gatsby-resp-image-link" href="/static/34c1a5f6ff980431fa72c80b1905bead/f793b/terminal-remote.png" style="display:block" target="_blank" rel="noopener"> | |
| <span class="gatsby-resp-image-background-image" style="padding-bottom:57.333333333333336%;position:relative;bottom:0;left:0;background-image:url(&#x27;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAALCAYAAAB/Ca1DAAAACXBIWXMAABYlAAAWJQFJUiTwAAABqklEQVQoz6WQXUvCUBjHNezufI0+R11Ed9adFFFQXmgJ0qVZ1KUV1EdQ6DOoQUrgVW5q5mrtRaxDRBGZus1tzrY9bctG9EbSH37n4Tyc/+/ieDxWDicmfftrY2hqZxItBhfQzMI0WomF0ezSLJqbm0eBQACtRiIokUigaDSKQqEQCofDKGLtloNB5Pf7USwW83neUzk6DvK1QrPMkI3z0jm+pGhcO6MwWSQxQRKYJElM0zSuVCq4XC5jgiAcSqUSpiiqwXFcq1qtLrvCk9PC5mO3DcwdD/VnDm5FDGzzCm6eruG52YZOpwO6roMoiqCqKsiy7Mxer+dgh2GYDVdYKBbjt00R6Dvcx0rDwMq10ZB540G5N9otwVBVxbA6P6HZQpZl113hBVuL28uuIeiC1jGlvghtrQXdvgSKrICmOR0wTcPC/Iidl4Ew7gp5jt94a4DunN/kk+h3oX0ZlF7M4fOtcH0g1Cz0Iel9+cN6vb4N/wzP81uuMJVKjedyuf1MJrObzWb3rPkn7LfpdHo3n88fJJPJcUcmCILXGjYjFqND4htMu+uVJMn7CmGhZkbvPxPEAAAAAElFTkSuQmCC&#x27;);background-size:cover;display:block"></span> | |
| <img class="gatsby-resp-image-image" alt="Remote machine opened in terminal" title="Remote machine opened in terminal" src="/static/34c1a5f6ff980431fa72c80b1905bead/c1b63/terminal-remote.png" srcSet="/static/34c1a5f6ff980431fa72c80b1905bead/5a46d/terminal-remote.png 300w,/static/34c1a5f6ff980431fa72c80b1905bead/0a47e/terminal-remote.png 600w,/static/34c1a5f6ff980431fa72c80b1905bead/c1b63/terminal-remote.png 1200w,/static/34c1a5f6ff980431fa72c80b1905bead/f793b/terminal-remote.png 1404w" sizes="(max-width: 1200px) 100vw, 1200px" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0" loading="lazy"/> | |
| </a> | |
| </span></p><p>By default you are going to see the <code>/home/circleci/</code> directory opened. Depending on your CircleCI configuration you will have a different directory tree there. In my case I have configured my job to run in the <code>~/release</code> folder:</p><pre><code class="language-yml">version: 2 | |
| jobs: | |
| build: | |
| working_directory: ~/release | |
| steps: | |
| - checkout | |
| - ... | |
| </code></pre><p>Pay attention to your setup and directory structure when applying commands used in this article. I am going to list those according to my setup to remain consistent.</p><h2 id="taking-a-snapshot">Taking a snapshot</h2><p>Working with a remote file-system is helpful, but you might quickly find yourself limited. It is a different environment that lacks your favorite IDE and other helpful tools you use for debugging. It may be helpful to know how to download directories and files from the remote machine.</p><p>Although you should strive towards your project being reproducible, I highly recommend to download a complete snapshot of the file-system, <em>including installed dependencies</em>. This way you eliminate any possible deviations and operate on the 1-1 instance of your project from the failed job. Depending on the project&#x27;s (and its dependencies) size, transferring its entire directory may take a significant amount of time. We can compress the working directory into a tarball to decrease its size and make the download procedure faster.</p><p>Being on the remote machine let&#x27;s compress the current working directory into a tarball archive:</p><pre><code class="language-bash">$ tar -czvf snapshot.tar.gz ./release | |
| </code></pre><ul><li><code>-c</code> create an archive;</li><li><code>-z</code> compress the archive using gzip;</li><li><code>-v</code> display progress in the terminal (verbose);</li><li><code>-f</code> accept a file name of the archive.</li></ul><p>After the archive is created you can transfer <code>snapshot.tar.gz</code> using SCP (<a href="https://en.wikipedia.org/wiki/Secure_copy">Secure Copy Protocol</a>). Open a new terminal window, because <strong>you need to be on the local machine</strong> to do this step.</p><pre><code class="language-bash">$ scp &lt;OPTIONS&gt; &lt;USER&gt;@&lt;HOST&gt;:/&lt;SRC_PATH&gt; &lt;DEST_PATH&gt; | |
| </code></pre><pre><code class="language-bash">$ scp -P 64536 circleci@100.26.97.124:/home/circleci/snapshot.tar.gz ~/Desktop | |
| </code></pre><ul><li><code>-P</code> connection port to use (default is <code>20</code>).</li></ul><p>This command will copy the file at <code>/home/circleci/snapshot.tar.gz</code> from the remote machine to your local <code>~/Desktop</code>. Unarchive the snapshot of the CI and debug it as if it was a regular folder, because it is now.</p><h2 id="afterword">Afterword</h2><p>Thanks for reading through this article! I hope it will be of good use to you when debugging the next failed CI. Let me know your thoughts on the topic <a href="https://twitter.com/kettanaito">on Twitter</a>!</p><hr/><h2 id="links--materials">Links &amp; Materials</h2><ul><li><a href="https://circleci.com/docs/2.0/ssh-access-jobs/">Debugging with SSH</a> (CircleCI documentation)</li><li><a href="https://jumpcloud.com/blog/what-are-ssh-keys/">What are SSH keys?</a> by JumpCloud</li><li><a href="https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh">Connecting to GitHub with SSH</a></li></ul></content:encoded></item><item><title><![CDATA[Debounce vs Throttle: Definitive Visual Guide]]></title><description><![CDATA[Introduction When it comes to debounce and throttle developers often confuse the two. Choosing the right one is, however, crucial, as they…]]></description><link>https://redd.one/debounce-vs-throttle</link><guid isPermaLink="false">https://redd.one/debounce-vs-throttle</guid><pubDate>Mon, 23 Dec 2019 00:00:00 GMT</pubDate><content:encoded><h2 id="introduction">Introduction</h2><p>When it comes to debounce and throttle developers often confuse the two. Choosing the right one is, however, crucial, as they bear a different effect. If you are a visual learner as myself, you will find this interactive guide useful to differentiate between <code>throttle</code> and <code>debounce</code> and better understand when to use each.</p><h2 id="first-things-first">First things first</h2><p>Throttling and debouncing are two ways to optimize event handling. Before we begin, let&#x27;s take a moment to briefly revise the basics of events. In this article I&#x27;m going to use JavaScript in all examples, yet the conepts they illustrate are not bound to any specific language.</p><p>Event is an action that occurs in the system. In front-end development that system is usually a browser. For example, when you resize a browser window the &quot;resize&quot; event is fired, and when you click on a button the &quot;click&quot; event is. We are interested in events to attach our own logic to them. That logic is represented as a function that is called a handler function (because it handles the event). Such handler functions may handle a UI element update on resize, display a modal window upon a button click, or execute an arbitrary logic in response to any event.</p><p>In JavaScript you can react to events using event listeners. <em>Event listener</em> is a function that listens to the given event on a DOM element and executes a handler function whenever that event occurs. To add an event listener to an element (target) you should use the <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener"><code>addEventListener</code></a> function:</p><pre><code class="language-js">target.addEventListener(eventName, handler, options) | |
| </code></pre><h2 id="lets-throw-a-ball">Let&#x27;s throw a ball!</h2><p>Let&#x27;s build a ball throwing machine. Our machine would have a button that, when pushed, throws a ball. To describe this cause-and-effect relation between the button click and a ball throw we can use <code>addEventListener</code> on our button element:</p><pre><code class="language-js">const button = document.getElementById(&#x27;button&#x27;) | |
| button.addEventListener(&#x27;click&#x27;, function () { | |
| throwBall() | |
| }) | |
| </code></pre><p>This reads as: <em>whenever the button is clicked, execute the <code>throwBall()</code> function</em>. The details of <code>throwBall</code> function are not important, as it represents <em>any logic</em> bound to an event.</p><p>Hinges are tightened and the screws are steady—let&#x27;s put our ingenious invention to the test!</p><div class="sc-AxirZ iRFNfH"><div width="100%" class="sc-AxjAm VendingMachine__VendingMachineContainer-sc-5h4te9-1 hcqTIA"><div class="VendingMachine__RawButtonContainer-sc-5h4te9-2 eYdQkF"><button aria-label="Throw a ball" class="VendingMachine__RedButton-sc-5h4te9-4 lhbXti"></button></div><img src="static/vendingMachine-9a0d0ccbb1d6ce4dc8911fbbb6275dca.png" alt="Ball vending machine" class="VendingMachine__StyledImage-sc-5h4te9-3 bljudg"/><canvas height="145" width="115" class="VendingMachine__RawStyledCanvas-sc-5h4te9-0 kcAVSi"></canvas></div><div><p><small>← Press the red button of the machine.</small></p><table><tbody><tr><td>Button clicked:</td><td><strong>0 time(s)</strong></td></tr><tr><td>Event handler called:</td><td><strong>0 time(s)</strong></td></tr></tbody></table></div></div><p>Whenever we press the button we produce the &quot;click&quot; event, to which event listener reacts with the <code>throwBall()</code> function. In other words, one button click results into one handler function call and one ball being thrown.</p><div>By default, event handler function executes with 1-1 ratio to the event call.</div><p>There are cases when such direct proportion may become undesired. For instance, what if throwing a ball was an expensive operation, or we couldn&#x27;t afford to throw more than 1 ball in half a second? In those cases we would have to limit the amount of times our handler function is being called.</p><p><strong>Throttling</strong> and <strong>debouncing</strong> are two most common ways to control a handler function response rate to an event. Let&#x27;s analyze each of them more closely by tweaking our ball machine.</p><hr/><h2 id="throttle">Throttle</h2><p>A throttled function is called once per <em>N</em> amount of time. Any additional function calls within the specified time interval are ignored.</p><h3 id="implementing-throttle">Implementing throttle</h3><pre><code class="language-js">function throttle(func, duration) { | |
| let shouldWait = false | |
| return function (...args) { | |
| if (!shouldWait) { | |
| func.apply(this, args) | |
| shouldWait = true | |
| setTimeout(function () { | |
| shouldWait = false | |
| }, duration) | |
| } | |
| } | |
| } | |
| </code></pre><blockquote><p>Depending on the use case such simplified implementation may not be enough. I recommend looking into <a href="https://www.npmjs.com/package/lodash.throttle"><code>lodash.throttle</code></a> and <a href="https://underscorejs.org/#throttle"><code>_.throttle</code></a> packages then.</p></blockquote><p>The <code>throttle</code> function accepts two arguments: <code>func</code>, which is a function to throttle, and <code>duration</code>, which is the duration (in ms) of the throttling interval. It returns a <em>throttled function</em>. There are implementations that also accept the <code>leading</code> and <code>trailing</code> parameters that control the first (leading) and the last (trailing) function calls, but I&#x27;m going to skip those to keep the example simple.</p><p>To throttle our machine&#x27;s button click we need to pass the event handler function as the first argument to <code>throttle</code>, and specify a throttling interval as the second argument:</p><pre><code class="language-js" metastring="focusedLines=3,5" focusedLines="3,5">button.addEventListener( | |
| &#x27;click&#x27;, | |
| throttle(function () { | |
| throwBall() | |
| }, 500) | |
| ) | |
| </code></pre><p>Here&#x27;s how our patched ball machine would work with the throttling applied:</p><div class="sc-AxirZ iRFNfH"><div width="100%" class="sc-AxjAm VendingMachine__VendingMachineContainer-sc-5h4te9-1 hcqTIA"><div class="VendingMachine__RawButtonContainer-sc-5h4te9-2 eYdQkF"><button aria-label="Throw a ball" class="VendingMachine__RedButton-sc-5h4te9-4 lhbXti"></button></div><img src="static/vendingMachine-9a0d0ccbb1d6ce4dc8911fbbb6275dca.png" alt="Ball vending machine" class="VendingMachine__StyledImage-sc-5h4te9-3 bljudg"/><canvas height="145" width="115" class="VendingMachine__RawStyledCanvas-sc-5h4te9-0 kcAVSi"></canvas></div><div><p><small>← Press the red button of the machine.</small></p><table><tbody><tr><td>Button clicked:</td><td><strong>0 time(s)</strong></td></tr><tr><td>Event handler called:</td><td><strong>0 time(s)</strong></td></tr></tbody></table><fieldset><legend>Throttle options</legend><label for="throttleDuration">Duration: 500ms</label><input type="range" id="throttleDuration" min="0" max="2000" step="100" value="500"/></fieldset></div></div><p>No matter how often we press the button a ball won&#x27;t be thrown more than once per throttled interval (500ms in our case). That&#x27;s a great way to keep our ball machine from overheating during the busy hours!</p><div>Throttle is a spring that throws balls: after a ball flies out it needs some time to shrink back, so it cannot throw any more balls unless it&#x27;s ready.</div><h3 id="when-to-use-throttle">When to use throttle?</h3><p>Use <code>throttle</code> to <em>consistently</em> react to a frequent event.</p><p>This technique ensures consistent function execution within a given time interval. Since throttle is bound to a timeframe, a dispatched event handler should be ready to accept an intermediate state of event.</p><p><strong>Common use cases for a throttled function:</strong></p><ul><li>Any consistent UI update after window <code>resize</code></li><li>Performance-heavy operations on the server or client</li></ul><hr/><h2 id="debounce">Debounce</h2><p>A debounced function is called after <em>N</em> amount of time passes since its last call. It reacts to a seemingly resolved state and implies a delay between the event and the handler function call.</p><h3 id="implementing-debounce">Implementing debounce</h3><pre><code class="language-js">function debounce(func, duration) { | |
| let timeout | |
| return function (...args) { | |
| const effect = () =&gt; { | |
| timeout = null | |
| return func.apply(this, args) | |
| } | |
| clearTimeout(timeout) | |
| timeout = setTimeout(effect, duration) | |
| } | |
| } | |
| </code></pre><blockquote><p>For more complicated scenarios consider <a href="https://www.npmjs.com/package/lodash.debounce"><code>lodash.debounce</code></a> and <a href="https://underscorejs.org/#debounce"><code>_.debounce</code> </a> packages then.</p></blockquote><p>The <code>debounce</code> function accepts two arguments: <code>func</code>, which is a function to debounce, and <code>duration</code>, which is the amount of time (in ms) to pass from the last function call. It returns a <em>debounced function</em>.</p><p>To apply debouncing to our example we would have to wrap the button click handler in the <code>debounce</code>:</p><pre><code class="language-js" metastring="focusedLines=3,5" focusedLines="3,5">button.addEventListener( | |
| &#x27;click&#x27;, | |
| debounce(function () { | |
| throwBall() | |
| }, 500) | |
| ) | |
| </code></pre><p>While the call signature of <code>debounce</code> is often similar to the one in <code>throttle</code>, it produces a much different effect when applied. Let&#x27;s see how our machine will behave if its button clicks are debounced:</p><div class="sc-AxirZ iRFNfH"><div width="100%" class="sc-AxjAm VendingMachine__VendingMachineContainer-sc-5h4te9-1 hcqTIA"><div class="VendingMachine__RawButtonContainer-sc-5h4te9-2 eYdQkF"><button aria-label="Throw a ball" class="VendingMachine__RedButton-sc-5h4te9-4 lhbXti"></button></div><img src="static/vendingMachine-9a0d0ccbb1d6ce4dc8911fbbb6275dca.png" alt="Ball vending machine" class="VendingMachine__StyledImage-sc-5h4te9-3 bljudg"/><canvas height="145" width="115" class="VendingMachine__RawStyledCanvas-sc-5h4te9-0 kcAVSi"></canvas></div><div><p><small>← Press the red button of the machine.</small></p><table><tbody><tr><td>Button clicked:</td><td><strong>0 time(s)</strong></td></tr><tr><td>Event handler called:</td><td><strong>0 time(s)</strong></td></tr></tbody></table><div><fieldset><legend>Debounce options</legend><label for="debounceDuration">Duration: 500ms</label><input type="range" id="debounceDuration" min="0" max="2000" step="100" value="500"/></fieldset></div></div></div><p>If we keep pressing the button fast enough no balls will be thrown at all, unless a debounce duration (500ms) passes since the last click. It is if our machine treats any amount of button clicks within a defined time period as <em>a single event</em> and handles it respectively.</p><div>Debounce is an overloaded waiter: if you keep asking him your requests will be ignored until you stop and give him some time to think about your latest inquiry.</div><h3 id="when-to-use-debounce">When to use debounce?</h3><p>Use debounce to <em>eventually</em> react to a frequent event.</p><p>Debounce is useful when you don&#x27;t need an intermediate state and wish to respond to the end state of the event. That being said, you need to take into account an inevitable delay between the event and the response to it when using <code>debounce</code>.</p><p><strong>Common use cases for a debounced function:</strong></p><ul><li>Asynchronous search suggestions</li><li>Updates batching on the server</li></ul><hr/><h2 id="common-problems">Common problems</h2><h3 id="re-declaring-debouncedthrottled-function">Re-declaring debounced/throttled function</h3><p>One of the most common mistakes when working with these rate limiting functions is <em>repeatedly re-declaring them</em>. You see, both <code>debounce</code> and <code>throttle</code> work due to <em>the same (debounced/throttled) function reference</em> being called. It is absolutely necessary to ensure you declare your debounced/throttled function only once.</p><p>Allow me to illustrate this pitfall. Take a look at this click event handler:</p><pre><code class="language-js">button.addEventListener(&#x27;click&#x27;, function handleButtonClick() { | |
| return debounce(throwBall, 500) | |
| }) | |
| </code></pre><p>It may look fine at first, but in fact nothing is going to be debounced. That is because the <code>handleButtonClick</code> function is not debounced, but instead we debounce the <code>throwBall</code> function.</p><p>Instead, we should debounce an entire <code>handleButtonClick</code> function:</p><pre><code class="language-js" metastring="focusedLines=3,5" focusedLines="3,5">button.addEventListener( | |
| &#x27;click&#x27;, | |
| debounce(function handleButtonClick() { | |
| return throwBall() | |
| }, 500) | |
| ) | |
| </code></pre><div>Remeber that the event handler function must be debounced/throttled only once. The returned function must be provided to any event listeners.</div><h4 id="react-example">React example</h4><p>If you are familiar with <a href="https://reactjs.org">React</a> you may also recognize the following declaration as being invalid:</p><pre><code class="language-jsx" metastring="focusedLines=8" focusedLines="8">class MyComponent extends React.Component { | |
| handleButtonClick = () =&gt; { | |
| console.log(&#x27;The button was clicked&#x27;) | |
| } | |
| render() { | |
| return ( | |
| &lt;button onClick={debounce(this.handleButtonClick, 500)}&gt; | |
| Click the button | |
| &lt;/button&gt; | |
| ) | |
| } | |
| } | |
| </code></pre><p>Since <code>debounce</code> is called during the render, each MyComponent&#x27;s re-render will produce a new instance of a debounced <code>handleButtonClick</code> function, resulting into no effect being applied.</p><p>Instead, the <code>handleButtonClick</code> <em>declaration</em> should be debounced:</p><pre><code class="language-jsx" metastring="focusedLines=2,7" focusedLines="2,7">class MyComponent extends React.Component { | |
| handleButtonClick = debounce(() =&gt; { | |
| console.log(&#x27;The button was clickeds&#x27;) | |
| }, 500) | |
| render() { | |
| return &lt;button onClick={this.handleButtonClick}&gt;Click the button&lt;/button&gt; | |
| } | |
| } | |
| </code></pre><h3 id="finding-optimal-duration">Finding optimal duration</h3><p>With both <code>debounce</code> and <code>throttle</code> finding a duration time optimal for UX <em>and</em> performance is important. Choosing a fast interval will not have impact on performance, and picking a too long interval will make your UI feel sluggish.</p><p>The truth is, there is no magical number to this, as time interval will differ for each use case. The best advice I can give you is to not copy any intervals blindly, but test what works the best for your application/users/server. You may want to conduct A/B testing to find that.</p><hr/><h2 id="afterword">Afterword</h2><p>Thank you for reading through this guide! Of course, there&#x27;s much more to events handling, and throttling and debouncing are not the only techniques you may use in practice. Let me know if you liked this article by reposting or retweeting it.</p><blockquote><p>Special thanks to <a href="https://codepen.io/AlexRA96">Alexander Fernandes</a> for &quot;Ball Bouncing Physics&quot; project used for balls physics in the vending machine example.</p></blockquote></content:encoded></item><item><title><![CDATA[Thinking in Functions, Part I: The Input/Output pattern]]></title><description><![CDATA[Introduction I was lucky to work with some great minds in the industry. Once I’ve befriended a brilliant Java developer and we spent a…]]></description><link>https://redd.one/thinking-in-functions</link><guid isPermaLink="false">https://redd.one/thinking-in-functions</guid><pubDate>Mon, 09 Sep 2019 00:00:00 GMT</pubDate><content:encoded><h2 id="introduction">Introduction</h2><p>I was lucky to work with some great minds in the industry. Once I’ve befriended a brilliant Java developer and we spent a decent amount of lunches chatting over patterns and approaches in programming. At that time I was working on a schema design for the forms validation in my project, which involved a lot of functional heavy-lifting. Each time we discussed a particular problem I was fascinated by the way he approached functional design. I’ve adopted one of his thinking patterns during the process, and it has changed the way I comprehend functions since then.</p><p>If you are coming from a functional programming background the things I’m about to say may bear no novelty for you. However, I know there are developers who are not accustomed to strong types and Hindley-Milner’s notation isn’t exactly the first thing that pops up in their heads when they think of a function. I address this article to those people.</p><hr/><h2 id="the-inputoutput-pattern">The Input/Output pattern</h2><p>We know that a function accepts arguments and returns a value. What we sometimes overlook is that this characteristic is an incredibly powerful design pattern we can use to write better functions.</p><p>Try to write any function by answering these two questions first:</p><ol><li><strong>What is this function’s input (what arguments it accepts)?</strong></li><li><strong>What is this function’s output (what data it returns)?</strong></li></ol><p>Doing so allows you to put technical details aside and focus on a function as an input/output operation, which, in fact, it is. The answers you give may hint certain implementational details, but, most importantly, they define clear constrains over a function’s responsibilities long before any actual code is being written.</p><blockquote><p>You may use abstract types for your answers. For example, a function may accept a list of apples and return a happy fox. Such type abstractions detach the call signature from the implementation even further.</p></blockquote><p>Let’s put this into practice. Say, you need to write a function that validates a form field. There are myriad of things that can affect a field’s validation, but you can leave those aside and answer the Input/Output questions first:</p><ol><li>My function accepts a <em>field</em>;</li><li>My function returns a <em>validation verdict</em> (<code>boolean</code>).</li></ol><p>When written down, these answers represent the function’s call signature:</p><pre><code class="language-ts">function validate(field: Field): boolean | |
| </code></pre><p>You may have no idea what the <code>Field</code> type may be at this point, but you know what it represents. The same can be said about the <code>validate</code> function in total: no matter which factors affect a field’s validity, you have to resolve to the boolean verdict in the end. Defined input and output act as a restriction that prevents our function from becoming too smart along the deadline-driven development. That ensures that the logic we write lies within the function’s responsibility and remains simple, satisfying both single responsibility and KISS principles.</p><p>Adopting this pattern doesn’t mean you should immediately rewrite your code in <a href="https://www.typescriptlang.org/">TypeScript</a> or any other strongly-typed language. First of all, it is the way of thinking about your functions. It’s fine to keep the input and output noted in a JSDoc block or in your sketchbook. Start from changing the way you think, and the tools will follow.</p><div>Similar to how you put the user’s needs first before making proper UX decisions, you think about what data your function accepts and returns in order to establish the boundaries of its future implementation.</div><h3 id="pattern-at-scale">Pattern at scale</h3><p>Thinking of functions using this pattern is great, but what about real-world operations that often consist of multiple functions and represent more complex logic?</p><p>The truth is, even the most complex function can be written as a set of consecutively executing smaller functions. When you approach the task this way you can focus on designing each individual function at a time. However, keeping functions in isolation is dangerous, as you may end up with multiple puzzle pieces that don’t fit together. There is a rule of functional composition to avoid that problem:</p><blockquote><p>Two functions are composable if the output of one can serve as the input to another.</p></blockquote><p>Knowing that, let’s implement a fairly complex operation that accepts a user and returns the amount of likes under all of their posts. To prevent the complexity, we can describe this operation as a sequence of steps:</p><blockquote><p>Get a user → get user’s posts → get the amount of post’s likes</p></blockquote><p>Each of these steps is a function, and we can apply the Input/Output pattern to design its call signature, keeping in mind the composition principle.</p><pre><code class="language-ts">const getUser = (id: string) =&gt; User | |
| const getPosts = (user: User) =&gt; Post[] | |
| const getTotalLikes = (posts: Post[]) =&gt; number | |
| </code></pre><p>Such high-level overview of a functional chain allows you to follow the data flow without distractions and highlight potential problems in the logic. Moreover, it is just a fun exercise to do.</p><div>In the end, functions are about transforming the data, so use all means available to ensure that transformation is coherent and efficient.</div><h3 id="one-more-thing">One more thing!</h3><p>There is one more hidden gem about the Input/Output approach. Let’s say you answer those primary questions with &quot;<em>my function accepts a list of strings and returns a number</em>&quot;. Congratulations, you have just written a unit test for your function!</p><pre><code class="language-ts">expect(myFunc([&#x27;a&#x27;, &#x27;b&#x27;])).toEqual(2) | |
| </code></pre><p>The result of this pattern may be reflected in a test scenario, backing up function design decisions with an actual unit test. This encourages TDD (test-driven development) and BDD (behavior-driven development), since we express our function’s intent by describing its input and output.</p><hr/><h2 id="summary">Summary</h2><p>Focusing on a function’s input and output types defines a concise specification of that function:</p><ol><li>A function’s call signature;</li><li>A minimal unit test for that function.</li></ol><p>Implementing things according to the specification is a pleasant and safe experience I absolutely recommend you to get accustomed to.</p><h2 id="afterword">Afterword</h2><p>I hope this pattern helps you next time you decide to write a function. Let me know if you would like to know more practical patterns and approaches to functional design by liking this post and letting me know in the comments.</p></content:encoded></item><item><title><![CDATA[The Art of Code Review: From hatred to acceptance]]></title><description><![CDATA[Introduction Hi! My name is Artem, and I am a software engineer who spent the last 2,5 years developing a multi-country e-commerce solution…]]></description><link>https://redd.one/the-art-of-code-review</link><guid isPermaLink="false">https://redd.one/the-art-of-code-review</guid><pubDate>Thu, 27 Dec 2018 00:00:00 GMT</pubDate><content:encoded><h2 id="introduction">Introduction</h2><p>Hi! My name is Artem, and I am a software engineer who spent the last 2,5 years developing a multi-country e-commerce solution with millions of euro of annual revenue. During that journey I had a chance to work with more than 15 front-end engineers of different seniority level, teaching them what I knew and learning from them what I didn’t. Today I would like to share my experience being a code reviewer, and give you some pieces of advice to become a good one.</p><p>I have been known for my notorious code reviews within the team, which some people hated, and others hated even more. In the end, it’s a joy to see the people who despised my reviews coming back and thanking me for a great time we both spent improving. Undoubtedly, my reviewing skills have a long way to go, but the positive feedback I’ve received over time motivated me to write this article. I would like to explore what made people love and hate my reviews, and how you can learn from that to become a better reviewer in your team.</p><hr/><h2 id="code-review-is-a-part-of-development">Code review is a part of development</h2><p>I will start from assuring you that a code review by no means bears a lesser priority in your work than actual coding. I would argue that it’s even more important, since it’s one of the most useful feedback loops you can get for free. A flaw in the logic discovered at the review phase can save unnecessary stress for you and wasted money for your customer.</p><img src="static/man-computer.25d56e7a.svg" alt="Image of a man behind computers"/><p>Understanding an importance of a code review as a part of your job is great, but make sure the other team members are on the same page with you. That doesn’t concern developers only, but project managers, scrum masters, product owners, and, most importantly, clients.</p><div>Code review is not a voluntary activity, but a righteous duty that must be accounted, respected, and paid.</div><p>Don’t be afraid to dive deeper into the code you’re reviewing, open a source code and browse through the related files to understand the nature of the changes better. With more pull requests behind your back, you will be able to perform that much faster, thus, delivering a profound in-depth feature analyzis. On the contrary, neglecting things in a review may backfire into much more work that it would’ve taken to get your head around the changes.</p><p>Here are a few arguments I find useful when explaining how code review contributes to a product:</p><ul><li>It ensures quality of the code, thus, quality of a product;</li><li>It reduces the amount of technical debt in the future, making the maintenance cost lower;</li><li>It provides knowledge sharing between developers, resulting into more effective work, and eliminating the bus factor.</li></ul><hr/><h2 id="polite-reviewer-sensible-issuer">Polite reviewer, sensible issuer</h2><p>Be polite in your code reviews. We are all humans doing our job and we strive to do it the best we can. While this sounds obvious, you may find a lot about your colleague if you ask them for a code review at 5PM on Friday before their long-awaited vacation.</p><img src="static/pair-programming.d540cd78.svg" alt="Image of a woman and a man pair programming"/><p>One of the hardest parts of giving a code review is when your suggestions are taken as a personal offense. It’s understandable that nobody likes to spend a week on a feature and hear that they need to redo everything. That hurts for both the issuer and the reviewer. <strong>Let’s not do that</strong>.</p><p>In my practice such situations happen for two reasons, which I&#x27;m going to describe below.</p><h3 id="reason-1-bad-start">Reason #1: Bad start</h3><p>This often happens to people who rush into development without properly thinking the changes through. I am strongly convinced that a day of thinking saves a week of work.</p><div>Don’t be afraid to ask and discuss! It either confirms your approach, or saves a week of work in a wrong direction.</div><p>While this is feasible in a team, those who work alone may struggle to get their ideas evaluated. Bear in mind that there are plenty of people who can help you. You are not alone.</p><p><strong>Here are the links to some of my favorite engineering communities:</strong></p><ul><li><a href="https://discord.gg/yNcseDS">Reactiflux</a></li><li><a href="https://discord.gg/y5ksVAS">Nodeiflux</a></li></ul><h3 id="reason-2-the-way-you-say-it">Reason #2: The way you say it</h3><p>There is a fine line between “it&#x27;s aweful, redo it” and a meaningful explanation of why there is a better way to do it. Remember that a reviewer’s role is to act as a fresh pair of eyes. Trying to understand the changes, and showing compassion when something needs to be reworked, are the keys to maintaining healthy working relationship between the issuer and the reviewer.</p><div>Code review is a conversation, not a queue of commands.</div><p>It’s a good gesture to include technical explanations and links to useful articles or resources whenever requesting a change. Because a change request shouldn’t be taken as your sole desire, but as a necessary measure that benefits everybody. Had the time been critical, it’s useful to give your colleague a hand or, perhaps, pair program to achieve the common goal, which is a quality code being merged. Turning an unpleasing fact of redoing your work into a supportive opportunity to learn is a great twist of events!</p><hr/><h2 id="review-logic-not-semicolons">Review logic, not semicolons</h2><p>There was a time I had been evaluating missing commas and semicolons during my reviews. What a shame. This is redundant and contributes to absolutely nothing, but it’s a good example of how a technical debt is paid by wasting everybody’s time. We didn’t have any code auto-formatting, and people often ignored ESLint warnings in the console. Eh, those dark times.</p><img src="static/typewriter.70eeeff5.svg" alt="Image of two women near a big typewriter"/><div>Automation reduces the amount of needless checks, and let’s you focus on the logic behind the changes, rather than syntax errors and typos.</div><p>Using tools like <a href="https://prettier.io/">Prettier</a> and integrating linter checks into your CI can filter out typos and syntax issues as the first automated part of any pull request. That also helps to keep a codebase unified without putting to much thought into it. Time saved by automating the routine can be well spent on verifying the actual logic behind the changes.</p><hr/><h2 id="dealing-with-big-changes">Dealing with big changes</h2><p>Developing a big product may lead into big pull request. The more massive the scope of a change becomes, the harder it is to evaluate its affect. Nobody wants to spend an entire day reviewing a single pull request, having a bunch of other tasks to finish.</p><img src="static/version-control.ba7ddc84.svg" alt="Image of a man behind a computer, and a Git commit tree"/><p>As a rule of thumb let&#x27;s try to prevent big pull requests from happening as such.</p><div>Plan your work in small, deliverable, meaningful pieces. Iterate and learn from your planning.</div><p>However, the scope of a feature isn’t the only factor that affects a pull request’s size. There is also a technical depth, which may render you changing hundreds of files simply to adjust the hue of that one tiny icon.</p><div>Have a clear picture of your changes prior to making them. Think it through and discuss with your colleagues whenever in doubt.</div><p>What if a feature is small and has a clear development plan in mind, yet still requires to change the half of the entire codebase? How to handle that?</p><p>I can recommend an approach we’ve used for such pull requests in our team that we called <strong>intermediate code reviews</strong>. It aims to resolve the amount of changes a reviewer should evaluate, thus resulting into short iterative review sessions. As an issuer, that means a rule to create a pull request, no matter the changes status, not later than the next morning after the first commit. For a reviewer it acts as a rule to always resolve assigned pull requests not later than the next morning. Of course, any necessary communication could also take place so that things are reviewed sooner, or later.</p><p>To eradicate huge diffs in your version control system try to issue pull requests from a child feature branch into a single parent feature branch. That way each review iteration ends with the changes being merged into the parent branch. Once the work is done, you can often merge parent branch into your master branch without any preceding code review.</p><hr/><h2 id="afterword">Afterword</h2><p>Please take all my suggestions with the grain of salt. I understand that a single approach may work differently for different teams, and that’s perfectly fine. It never hurts to know how others do — at worst you can learn from their mistakes.</p></content:encoded></item><item><title><![CDATA[Advanced forms in React made easy]]></title><description><![CDATA[Foreword Form is one of the most important interaction elements on the website. It’s easy to create a simple form. It’s hard to create a…]]></description><link>https://redd.one/advanced-forms-in-react-made-easy</link><guid isPermaLink="false">https://redd.one/advanced-forms-in-react-made-easy</guid><pubDate>Mon, 14 May 2018 00:00:00 GMT</pubDate><content:encoded><h2 id="foreword">Foreword</h2><p>Form is one of the most important interaction elements on the website. It’s easy to create a simple form. It’s hard to create a real-world form. For more than two years my team and I have been working on a huge e-commerce solution, and for more than two years we have struggled to fit the requirements into the form library we have chosen at the very beginning.</p><p>Refactoring was out of question. To our deepest surprise each of the modern solutions felt like walking into the same water. Instead, we have decided to create the one that would suit our needs foremost, eliminating present issues and focusing on missing functionality.</p><p>Today I am glad to share with you the outcome and demonstrate how it helped us to make the implementation cleaner and more maintainable.</p><hr/><h2 id="the-problems">The problems</h2><p>Each of the points below can be dealt with to a certain extent. My emphasis here is that those can rather be handled on a form’s level, dramatically improving developer’s experience.</p><h3 id="boilerplate">Boilerplate</h3><p>Our team hates writing boilerplate, so we couldn’t tolerate with providing blocks of configuration to high-order components around each form, or obscurely defining which fields a form will have before it renders.</p><p>Of course, you can abstract. Especially when you wish to end up in the hell of non-maintainable abstractions. The bottom line is, if a third-party solution results into you creating abstractions over it, then, probably, it never solved your problems in the first place.</p><h3 id="obscure-declaration">Obscure declaration</h3><p>Back in the day we needed to create an array of strings, which would represent the fields, and pass it to the high-order component before the form is even mounted. Today I see fields declared as Objects, or even worse, proving that this point is as valid as never.</p><p>Declaration of a form and its fields must be simple. I cannot stress more on how devastating an obscure declaration is to the code you write.</p><h3 id="responsibility-delegation">Responsibility delegation</h3><p>Form libraries tend to ask a developer to manage so many things that the one forgets about using a library at all. Maintaining and updating fields’ state, writing repetitive “validate” functions, or manually handling submit statuses — don’t be fooled to believe managing all this is your responsibility.</p><p>I value a solution being dynamic and flexible, but there is a fine line between being in control whenever you need to, and being forced to manage things when you shouldn’t.</p><hr/><h2 id="getting-started">Getting started</h2><p>That being said, it’s time to offer some solutions to those problems.</p><p>You and me are going to have a pair programming session right now, implementing a real-world registration form in our application. This is not going to be a short session, but, hopefully, a noteworthy one.</p><h2 id="declaration">Declaration</h2><p>A lot of solutions overcomplicate even at this starting point, but we are going to keep things simple. Clarity on the declaration level is a must and is an unrivaled privilege when working with a big code base.</p><p>Declaring the form’s layout must be simple:</p><pre><code class="language-jsx">// src/app/RegistrationForm.jsx | |
| import React from &#x27;react&#x27; | |
| import { Form } from &#x27;react-advanced-form&#x27; | |
| import { Input } from &#x27;...&#x27; | |
| export default class RegistrationForm extends React.Component { | |
| render() { | |
| return ( | |
| &lt;Form&gt; | |
| &lt;Input name=&quot;userEmail&quot; type=&quot;email&quot; required /&gt; | |
| &lt;Input name=&quot;userPassword&quot; type=&quot;password&quot; required /&gt; | |
| &lt;Input name=&quot;confirmPassword&quot; type=&quot;password&quot; required /&gt; | |
| &lt;Input name=&quot;firstName&quot; /&gt; | |
| &lt;Input name=&quot;lastName&quot; /&gt; | |
| &lt;button&gt;Register&lt;/button&gt; | |
| &lt;/Form&gt; | |
| ) | |
| } | |
| } | |
| </code></pre><p>No high-order components, no configurations. Nothing to subtract to make it even more simple.</p><blockquote><p>Throughout this article I am going to refer to the pre-defined Input component. Creating a set of composite fields is an essential step when building an application, however, I will skip it for the sake of the article’s length.</p></blockquote><h2 id="third-party-integration">Third-party integration</h2><p>We often use great third-party fields libraries in our applications. React Advanced Form makes it easy to integrate any third-party library to work together. Take a look at the integration examples of one of the popular libraries:</p><ul><li>react-select</li><li>react-slider</li><li>react-datepicker</li></ul><h2 id="validation">Validation</h2><p>Exposing a single validate function is as good as leaving you to implement repetitive logic over and over, covering something that form refused to cover.</p><p>We are going to take a different approach. The form is going to provide a versatile validation algorithm built-in, allowing developers to focus on actually writing validation rules, instead of repeating themselves in those “validate” functions.</p><p><strong>There is a defined logic applicable to any validation of any form:</strong></p><ol><li>Any required field must have a value. In case it has any extra rules defined, those must be satisfied as well.</li><li>Any field must be validated in case it has some value and has applicable validation rules, regardless of whether it’s required or optional. Whenever the rules are provided, they must be satisfied.</li><li>Any asynchronous validation must execute only if the synchronous validation passed. Would you ever wanted to asynchronously validate a value of a wrong format?</li></ol><p>I am convinced that any sane implementation already has this or similar logic achieved on top of the form. But our goal is to make this a part of the form, preventing the repetition and controlling the necessity of the validation. Finally, we can say goodbye to the meaningless conditions like this one:</p><pre><code class="language-js">if (fields.email &amp;&amp; !!field.email.value) { | |
| validateEmail(email) | |
| } | |
| </code></pre><h2 id="validation-schema">Validation schema</h2><p>We have ditched a “validate” function, so how are we going to perform the validation then? After years of work on a multi-country platform, where each country demands specific validation rules, we have found that the most efficient way of writing and maintaining them is a <em>validation schema</em>.</p><p>Validation schema is a plain Object of a defined structure, which allows to select fields and predicate their validity. It does not control when to apply the validation, but which validation to apply. The relevance of the validation (that would be applying the rules for present fields only, and the unified logic we have discussed above) is ensured by the form solution.</p><h3 id="benefits-of-the-validation-schema">Benefits of the validation schema</h3><ul><li><strong>Simple</strong>. Objects are easy to read, maintain and compose dynamically.</li><li><strong>Centralized</strong>. Validation schema is meant to be defined on the root level of the app and serve as a global validation manifesto. Validation rules is something you want to apply application-wide in most of the cases (form-specific schemas are supported as well).</li><li><strong>Decoupled</strong>. Validation schema is decoupled from the validation messages to have a clear separation of concerns. Mixing validation rules and messages is the same as mixing business and view logic in your app. | |
| Pure. Each rule is a pure function that can access the field’s value, fieldProps, and form — everything to craft the most complex validation logic without leaving the schema.</li></ul><h3 id="schema-declaration">Schema declaration</h3><p>Continuing on our Registration form, let’s define some clear validation requirements, and put them into a list:</p><ul><li><code>[type=&quot;email&quot;]</code> fields must have a correct e-mail format,</li><li><code>[type=&quot;password&quot;]</code> fields must contain at least one capital letter,</li><li><code>[type=&quot;password&quot;]</code> fields must contain at least one number,</li><li><code>[type=&quot;password&quot;]</code> fields must be at least 6 characters long,</li><li><code>[name=&quot;confirmPassword&quot;]</code> value must equal to <code>[name=&quot;userPassword&quot;]</code>.</li></ul><blockquote><p>Note how userPassword and confirmPassword comparison is a part of the validation logic. Their equality essentially defines the validity of the confirmPassword field and, therefore, must be a part of the validation rules.</p></blockquote><p>Putting those rules into the validation schema is simple. First, we would need to select a field, or a group of fields, by their type or their name. Then, we add a resolver, or a group of resolvers, to that selector.</p><p>This is how those criteria would look using a validation schema:</p><pre><code class="language-jsx">// src/app/validation-rules.js | |
| import isEmail from &#x27;validator/lib/isEmail&#x27;; | |
| export default { | |
| type: { | |
| email: ({ value }) =&gt; isEmail(value), | |
| password: { | |
| capitalLetter: ({ value }) =&gt; /[A-Z]/.test(value), | |
| oneNumber: ({ value }) =&gt; /[0-9]/.test(value), | |
| minLength: ({ value }) =&gt; (value.length &gt; 5) | |
| } | |
| }, | |
| name: { | |
| confirmPassword: { | |
| matches: ({ value, get }) =&gt; { | |
| return (value === get([&#x27;userPassword&#x27;, &#x27;value&#x27;]); | |
| } | |
| } | |
| } | |
| }; | |
| </code></pre><p>Note how we have managed to declare fairly complex requirements using just a few single-line functions. Now let’s analyze each of them in more detail.</p><pre><code class="language-js">{ | |
| type: { | |
| email: ({ value }) =&gt; isEmail(value) | |
| } | |
| } | |
| </code></pre><p>Here we select all fields with the <code>type=&quot;email&quot;</code> and declare the resolver function, which takes the field’s <code>value</code> and provides it to the third-party <code>isEmail</code> validator function. The resolver must always return Boolean, which determines the validity of the field.</p><pre><code class="language-js">{ | |
| type: { | |
| password: { | |
| capitalLetter: ({ value }) =&gt; /[A-Z]/.test(value), | |
| oneNumber: ({ value }) =&gt; /[0-9]/.test(value), | |
| minLength: ({ value }) =&gt; (value.length &gt; 5) | |
| } | |
| } | |
| } | |
| </code></pre><p>This selector is similar to the previous one, as we are getting all fields with the <code>type=&quot;password&quot;</code>, yet instead of a single resolver, we have declared a group of resolver functions, each having its unique name (those are referred to as &quot;<em>named rules</em>&quot;). This way we can manage several rules related to a single selector and can provide resolver-specific validation messages by their names (<code>capitalLetter</code>, <code>oneNumber</code>, <code>minLength</code>).</p><blockquote><p>Rule resolvers of the same selector are executed in parallel.</p></blockquote><pre><code class="language-js">{ | |
| name: { | |
| confirmPassword: { | |
| matches: ({ value, get }) =&gt; { | |
| return (value === get([&#x27;userPassword&#x27;, &#x27;value&#x27;]); | |
| } | |
| } | |
| } | |
| } | |
| </code></pre><p>This one is the most complex so far. We are taking the field with the <code>name=&quot;confirmPassword&quot;</code> and declaring a matches named rule. Inside that rule we compare the field’s value to the value prop of the <code>name=&quot;userPassword&quot;</code> field, using the get function. The get function analyzes the resolver and creates Observable for each referenced field. Whenever the referenced props change, the resolver function is re-evaluated automatically. So, whenever <code>userPassword.value</code> changes, <code>name=&quot;confirmPassword&quot;</code> field is re-validated on-the-fly.</p><h3 id="rules-relation">Rules relation</h3><p>A single field may have both type- and name-specific rules associated with it. For example, our <code>confirmPassword</code> field has both <code>type.password</code> and <code>name.confirmPassword</code> rules defined in the schema. It is important to understand the relation between those rules, and the priority of their execution.</p><p>The execution of the rules in a validation schema abides by the following principles:</p><ol><li><code>name</code> specific rules have a higher priority and, therefore, are executed before the <code>type</code> specific rules.</li><li>Whenever a <code>name</code> specific rule rejects, no <code>type</code> specific rules are going to be executed at all.</li><li>Sibling rules groups (i.e. rules under <code>type.password</code>) are executed in parallel, and continue to run regardless of the resolving status of the preceding rule.</li></ol><blockquote><p>This is only a brief look at the <a href="https://redd.gitbook.io/react-advanced-form/validation/logic">layered validation algorithm</a> provided by React Advanced Form. Reading through it will help you to understand the logic better, and thus use it more efficiently in your application.</p></blockquote><h2 id="validation-messages">Validation messages</h2><p>Without being properly reflected in the UI, any validation is useless.</p><p>Similar to the validation schema, validation messages reside in the dedicated manifest responsible for describing the rule-message bindings. Declaration of validation messages is very similar to the validation schema: selecting a field by its type or name, and providing the respective messages or message resolvers.</p><p>Isolating validation messages has the very same benefits as the validation schema. One of those, for example, is the ability to compose validation messages on runtime, serving different schemas per locale, while keeping the rules intact.</p><p>Take a look at the validation messages declaration:</p><pre><code class="language-js">// app/validation-messages.js | |
| export default { | |
| generic: { | |
| missing: &#x27;Please provide the required field&#x27;, | |
| invalid: &#x27;The value you have provided is invalid&#x27;, | |
| }, | |
| type: { | |
| email: { | |
| missing: &#x27;Please provide the e-mail&#x27;, | |
| invalid: ({ value }) =&gt; &#x27;The e-mail &quot; + value + &quot; has invalid format&#x27;, | |
| }, | |
| password: { | |
| invalid: &#x27;The password you entered is invalid&#x27;, | |
| rule: { | |
| capitalLetter: &#x27;Include at least one capital letter&#x27;, | |
| minLength: &#x27;Password must be at least 6 characters long&#x27;, | |
| }, | |
| }, | |
| }, | |
| name: { | |
| confirmPassword: { | |
| rule: { | |
| matches: &#x27;The passwords do not match&#x27;, | |
| }, | |
| }, | |
| }, | |
| } | |
| </code></pre><p>All validation messages are divided into three groups (listed by their priority):</p><ul><li><code>name</code> — messages applied based on the field’s name.</li><li><code>type</code> — messages applied based on the field’s type.</li><li><code>generic</code> — the least specific, fallback messages used when no other specific messages are found.</li></ul><p>Each group above can contain the next reserved keys:</p><ul><li><code>missing</code> — applied when the field is missing (that is required, but empty).</li><li><code>invalid</code>— applied when the field is invalid (has unexpected value).</li><li><code>rule</code>— collection of the messages corresponding to the named validation rules listed in the ruleName: message format.</li></ul><p>Messages can be resolved using a plain string, or a resolver function (see <code>type.email.invalid</code>), which has the same interface as the rule resolver. The difference is that the message resolver must always return a String. This allows to have dynamic validation messages depending on the field props, another fields, or asynchronous validation response, with ease.</p><h3 id="messages-relation-and-fallback">Messages relation and fallback</h3><p>Whenever the higher specific message is provided, it is being used to the respective validity state.</p><p>Let’s say our <code>name=&quot;confirmPassword&quot;</code> field is invalid because its <code>matches</code> rule has been rejected. This is the order in which the form will attempt to get the corresponding validation message:</p><ol><li><code>name.confirmPassword.rules.matches</code> the message directly related to the rejected rule’s name (if it’s a named rule that rejected).</li><li><code>name.confirmPassword.invalid</code> the general invalid message related to the invalid field’s name.</li><li><code>type.password.invalid</code> the general invalid messages related to the invalid field’s type.</li><li><code>generic.invalid</code> the fallback invalid message applicable to any invalid field.</li></ol><p>It is not only the resolving order, but also a fallback sequence for the messages. That means, that whenever a more specific message is not found, the form attempts to get the next message in the specificity order, and return it during the rendering.</p><h2 id="asynchronous-validation">Asynchronous validation</h2><p>Building a modern form will inevitably lead you to the point of asynchronous validation. Unlike the synchronous validation rules that reside in a schema, asynchronous rules are declared on the field components directly, using the <code>asyncRule</code> prop.</p><p>Let’s use it to validate the entered e-mail on-the-fly:</p><pre><code class="language-jsx">import React from &#x27;react&#x27; | |
| import { Form } from &#x27;react-advanced-form&#x27; | |
| export default class RegistrationForm extends React.Component { | |
| validateEmail = ({ value, fieldProps, fields, form }) =&gt; { | |
| return fetch(&#x27;https://backend/&#x27;, { body: value }) | |
| .then((res) =&gt; res.json()) | |
| .then((res) =&gt; { | |
| return { | |
| /* Determine if the e-mail is valid based on response */ | |
| valid: res.statusCode === &#x27;SUCCESS&#x27;, | |
| errorCode: res.errorCode, | |
| } | |
| }) | |
| } | |
| render() { | |
| return ( | |
| &lt;Form&gt; | |
| &lt;Input | |
| name=&quot;userEmail&quot; | |
| type=&quot;email&quot; | |
| asyncRule={this.validateEmail} | |
| required | |
| /&gt; | |
| {/* Rest fields */} | |
| &lt;/Form&gt; | |
| ) | |
| } | |
| } | |
| </code></pre><p>Notice the Object shape returned when the request is resolved. Relying on the Promise status alone is not sufficient to determine the validity of the field. Therefore, there is an explicit valid property to control that. Any additional properties provided to the resolved Object are propagated to async validation message resolver, so the error message can be based on the data received from the validation response:</p><pre><code class="language-jsx">// src/validation-messages.js | |
| export default { | |
| ..., | |
| name: { | |
| userEmail: { | |
| async: ({ value, errorCode }) =&gt; { | |
| return &#x27;E-mail &#x27; + email + &#x27; is already registered. Error code: &#x27; + errorCode | |
| } | |
| } | |
| } | |
| }; | |
| </code></pre><blockquote><p><strong>Tip:</strong> You may want to consider moving async validation functions into some utils, since those are, essentially, a bunch of pure functions.</p></blockquote><h2 id="applying-the-validation">Applying the validation</h2><p>In most of the cases we want to apply the validation logic (both rules and messages) application-wide. Of course, being able to customize the validation behavior of a specific form must be possible as well.</p><p>With React Advanced Form there are two options, which you can combine:</p><ul><li>Use a <code>&lt;FormProvider&gt;</code> component to wrap your whole application and supply the validation rules and messages to all forms it renders (<em>recommended</em>).</li><li>Provide rules and messages to the <code>&lt;Form&gt;</code> component. This way we can extend or completely override the rules exposed by the provider.</li></ul><blockquote><p><strong>Tip:</strong> Combining these two options is perfectly fine.</p></blockquote><p>For our form we are going to use the first option, and introduce the provider component on the root level of our application:</p><pre><code class="language-jsx">// app/index.js | |
| import React from &#x27;react&#x27; | |
| import ReactDOM from &#x27;react-dom&#x27; | |
| import { FormProvider } from &#x27;react-advanced-form&#x27; | |
| import rules from &#x27;./validation-rules&#x27; | |
| import messages from &#x27;./validation-messages&#x27; | |
| import Root from &#x27;./Root&#x27; | |
| const renderApp = () =&gt; ( | |
| &lt;FormProvider rules={rules} messages={messages}&gt; | |
| &lt;Root /&gt; | |
| &lt;/FormProvider&gt; | |
| ) | |
| ReactDOM.render(renderApp, document.getElementById(&#x27;root&#x27;)) | |
| </code></pre><p>Now all the forms in our application abide by the defined <code>rules</code> schema and the respective validation <code>messages</code>.</p><h2 id="interdependent-fields">Interdependent fields</h2><p>The <code>firstName</code> and <code>lastName</code> fields of our form are optional. However, it wouldn’t make much sense to allow having one of them blank in case the other is provided. How should the <em>form</em> handle such a scenario? Let’s take a sneak peek on the feature called <a href="https://redd.gitbook.io/react-advanced-form/architecture/reactive-props">reactive props</a>.</p><p>Briefly, it is a props change subscription system using RxJS. Whenever some field is referenced within the prop resolver function, that prop’s value is automatically updated whenever the referenced prop changes.</p><p>Okay, that sounds complicated. Some example to the rescue:</p><pre><code class="language-jsx">&lt;Input | |
| name=&quot;firstName&quot; | |
| required={({ get }) =&gt; { | |
| // resolves any time &quot;value&quot; prop of &quot;lastName&quot; changes | |
| return !!get([&#x27;lastName&#x27;, &#x27;value&#x27;]); | |
| }} /&gt; | |
| &lt;Input | |
| name=&quot;lastName&quot; | |
| required={({ get }) =&gt; { | |
| // resolves any time &quot;value&quot; prop of &quot;firstName&quot; changes | |
| return !!get([&#x27;firstName&#x27;, &#x27;value&#x27;]); | |
| }} /&gt; | |
| </code></pre><blockquote><p>Note that the getter function returns the <em>actual value</em> of the prop.</p></blockquote><p>Using simple one-line reactive props resolvers, our <code>firstName</code> and <code>lastName</code> fields are interdependent and reactive, while still stateless. Read more on <a href="https://redd.gitbook.io/react-advanced-form/architecture/reactive-props">Reactive props</a> feature to understand its full potential.</p><h2 id="skipping-fields">Skipping fields</h2><p>The <code>confirmPassword</code> field is beneficial for validation, but its value doesn’t contribute to the serialized object in any way. Being able to skip certain fields during the serialization is such an essential part of the form’s functionality it makes me ashamed we still need to do some workarounds to achieve that.</p><p>No more. There is the <code>skip</code> prop designed for that very purpose. Once provided, a field is bypassed during the serialization process.</p><pre><code class="language-jsx">&lt;Input name=&quot;confirmPassword&quot; type=&quot;password&quot; required skip /&gt; | |
| </code></pre><p>A skipped field behaves just as any other field, meaning it gets validated and can prevent the form from being submitted.</p><h2 id="field-grouping">Field grouping</h2><p>Our registration form is nice and shiny, but what a bummer — we have just got a message from a back-end developer, saying that the fields <code>email</code>, <code>firstName</code> and <code>lastName</code> must be sent under the primaryInfo key.</p><p>We’ve all been there. Well, we can easily introduce some custom logic somewhere during the serialization and… Stop! Stop thinking of tweaks and start expecting the form to do more than just field rendering. Use <em>field grouping</em>.</p><p>Field grouping allows to control the data structure of the layout level. This significantly reduces the amount of additional transformations when the form layout is not aligned with the API (which, from my experience, happens too often). I believe that it should be possible to tell the serialized structure of the form by simply looking at its layout, without having to venture around in attempts to find where it might have been manually changed.</p><p>In our case we would simply add a <code>primaryInfo</code> field group:</p><pre><code class="language-jsx">// src/app/RegistrationForm.jsx | |
| import React from &#x27;react&#x27; | |
| import { Form, Field } from &#x27;react-advanced-form&#x27; | |
| import { Input } from &#x27;...&#x27; | |
| export default class RegistrationForm extends React.Component { | |
| render() { | |
| return ( | |
| &lt;Form&gt; | |
| &lt;Field.Group name=&quot;primaryInfo&quot;&gt; | |
| &lt;Input name=&quot;userEmail&quot; type=&quot;email&quot; required /&gt; | |
| &lt;/Field.Group&gt; | |
| &lt;Input name=&quot;userPassword&quot; type=&quot;password&quot; required /&gt; | |
| &lt;Input name=&quot;confirmPassword&quot; type=&quot;password&quot; required /&gt; | |
| &lt;Field.Group name=&quot;primaryInfo&quot;&gt; | |
| &lt;Input name=&quot;firstName&quot; /&gt; | |
| &lt;Input name=&quot;lastName&quot; /&gt; | |
| &lt;/Field.Group&gt; | |
| &lt;button&gt;Register&lt;/button&gt; | |
| &lt;/Form&gt; | |
| ) | |
| } | |
| } | |
| </code></pre><p>The layout above will be serialized into the following JSON:</p><pre><code class="language-json">{ | |
| &quot;primaryInfo&quot;: { | |
| &quot;userEmail&quot;: &quot;...&quot;, | |
| &quot;firstName&quot;: &quot;...&quot;, | |
| &quot;lastName&quot;: &quot;...&quot; | |
| }, | |
| &quot;userPassword&quot;: &quot;...&quot; | |
| } | |
| </code></pre><p>Notice how multiple <code>&lt;Field.Group&gt;</code> components with the same name are automatically merged together upon serialization. Moreover, the fields with the same names under different groups are completely allowed.</p><blockquote><p>Technically, field grouping allows to treat groups as different forms with a single control point. Sending any group to any end-point is now a matter of simply grabbing a proper key in the serialized Object.</p></blockquote><h2 id="submit">Submit</h2><p>It’s been a long way, and now we have come to submitting the data.</p><p>As clear as this process appears, it is still surprising how outdated and obsolete it is in terms of handling the submit itself. Nowadays form submit must — and I emphasize — <em>must</em> be handled asynchronously. That is not for the technical advantage alone, but also for a greater performance and user experience.</p><p>That being said, it’s safe to assume that submit <code>action</code> would return an instance of Promise. Once that assumption is made, it becomes easy to handle submit start, success, failure or end relying on the Promise status.</p><p>Moreover, it is also essential to validate the form before submitting, and expose some essential information — like the serialized fields — into the <code>action</code>, as this is something the one would always expect.</p><h3 id="submit-action">Submit action</h3><p>First, we are going to use an action prop to handle the submit of our form. That prop expects a function which returns a Promise. It also provides the data you need during the submit as the arguments to the action function.</p><pre><code class="language-jsx">import React from &#x27;react&#x27; | |
| import { Form } from &#x27;react-advanced-form&#x27; | |
| import { Input } from &#x27;...&#x27; | |
| export default class RegistrationForm extends React.Component { | |
| registerUser = ({ serialized, fields, form }) =&gt; { | |
| return fetch(&#x27;https://backend.dev/user&#x27;, { | |
| method: &#x27;POST&#x27;, | |
| body: JSON.stringify(serialized), | |
| }) | |
| } | |
| render() { | |
| return ( | |
| &lt;Form action={this.registerUser}&gt; | |
| &lt;Input name=&quot;userEmail&quot; type=&quot;email&quot; required /&gt; | |
| &lt;Input name=&quot;userPassword&quot; type=&quot;password&quot; required /&gt; | |
| &lt;/Form&gt; | |
| ) | |
| } | |
| } | |
| </code></pre><blockquote><p><strong>Tip:</strong> You can return a Redux action, as long as it returns a Promise. You would need a dedicated middleware to ensure that (i.e. <a href="https://github.com/gaearon/redux-thunk"><code>redux-thunk</code></a>).</p></blockquote><p>Notice how we are not doing any manual validation or serialization, because we <em>shouldn’t</em>. Why would any form allow to submit itself without being validated beforehand? Why would any form call a submit handler and don’t provide the serialized fields, when you always need them?</p><p>Of course, manual validation and serialization is there when you need it. In other cases expect the form to behave as it must.</p><h3 id="submit-callbacks">Submit callbacks</h3><p>Since we know our action returns a Promise, the form can provide a standardized way to handle the status of that Promise using the respective props. So, instead of chaining the logic directly to the action dispatch, it can be declared in using the callback methods:</p><ul><li><strong>onSubmitStart</strong>. Dispatched immediately once the submit begins. This is a good place to have any UI loading logic, for example.</li><li><strong>onSubmitted</strong>. Dispatched when the <code>action</code> Promise has resolved.</li><li><strong>onSubmitFail</strong>. Dispatched only when the action has rejected.</li><li><strong>onSubmitEnd</strong>. Dispatched when the submit is finished, regardless of the Promise status (similar to Bluebird’s <code>.finally()</code>).</li></ul><p>Apart from being called at the proper moment, those methods provide useful data through arguments, such as a <code>req</code> or <code>res</code> references, as well as the standard callback payload (<code>fields</code> and <code>form</code>).</p><p><a href="https://redd.gitbook.io/react-advanced-form/components/form/callbacks">Read more on submit callback handlers</a>.</p><h2 id="summary">Summary</h2><p>Hence, in a matter of minutes we have created the registration form with the clean layout, multi-layer validation, interdependent <code>required</code> logic, dealt with the inconsistency between design and the API, and submitted it to the latter. Without having to configure myriad of things. Without any crazy tweaks or hacks. Without even making our form stateful.</p><p>The best part is that the most of the code is reusable, which makes the implementation of next forms faster and easier.</p><p>Take a look at the working example of our registration form:</p><p><a href="https://codesandbox.io/embed/n7l025m5y4?module=%2Fsrc%2FRegistrationForm.jsx">https://codesandbox.io/embed/n7l025m5y4?module=%2Fsrc%2FRegistrationForm.jsx</a></p><h2 id="afterword">Afterword</h2><p>That was only a glimpse of what React Advanced Form is to offer. See the <a href="https://redd.gitbook.io/react-advanced-form">Official documentation</a> for more features like custom styling, integration of third-party libraries, controlling various behaviors, and much more.</p><p>Of course, no example can match the experience of trying something yourself. Go ahead and give it a try:</p><div owner="kettanaito" repo="react-advanced-form"></div><p>Your feedback and thoughts are highly appreciated! Thank you.</p><h2 id="materials">Materials</h2><ul><li><a href="https://github.com/kettanaito/react-advanced-form">React Advanced Form</a></li><li><a href="https://redd.gitbook.io/react-advanced-form">Official documentation</a></li><li><a href="https://redd.gitbook.io/react-advanced-form/getting-started/installation">Getting started guidelines</a></li></ul></content:encoded></item></channel></rss> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment