Matias Kinnunen – Blog

Better way to indent ordered lists in Markdown

2024-10-15T12:00:00+03:00

1. foo is annoying because the list item's text is indented with three spaces. Solution: add another space after the period.

Before:

1. Using **3** spaces of indentation.
2. ...
3. Code blocks are **especially annoying**:
   ```js
   // **3** spaces of indentation, yuck
   function foo() {
     // **5** spaces of indentation, yuck
     alert('lolz')
   }
   ```
4. ...
5. And when there are lots of list items:
6. ...
7. ...
8. ...
9. ...
10. ...the indentation **changes to 4 spaces** (nice but inconsistent)

After:

1.  Using **4** spaces of indentation.
2.  ...
3.  Code blocks are **now ok**:
    ```js
    // **4** spaces of indentation, sweet
    function foo() {
      // **6** spaces of indentation, sweet
      alert('lolz')
    }
    ```
4.  ...
5.  And when there are lots of list items:
6.  ...
7.  ...
8.  ...
9.  ...
10. ...the indentation **is still consistently 4 spaces**, yay!

This kind of indentation is also Prettier-compatible, nice! Maybe it should even be the default indentation style.

I noticed this accidentally when writing an answer on Stack Overflow, where the textarea formats ordered lists like this:

Notice the leading spaces:

 1. foo
 2. bar

I copy-pasted that to VS Code, then formatted the file in VS Code (using Prettier), and Prettier formatted the list like this:

1.  foo
2.  bar

A-ha!

Previewing HTML files directly on GitHub with a bookmarklet

2024-10-14T12:00:00+03:00

There's no built-in way to preview HTML files on GitHub, but you can use this nifty bookmarklet. (GitHub's project managers HATE it!)

Create a bookmark with this "URL":

javascript: (() => {
  const selector = '#read-only-cursor-text-area';
  const html = document.querySelector(selector)?.value;

  if (!html) {
    return alert(`Error: element ${selector} not found`);
  }

  document.open();
  document.write(html);
  document.close();
})();

Open an HTML file on GitHub.
Run the bookmarklet by "opening" the bookmark. It replaces the current page's contents with the HTML file's contents.

Works great with self-contained / zero-dependency HTML files generated with SingleFile.

Notes:

The bookmarklet breaks GitHub's client-side routing, so navigating back with the browser's Back button doesn't work. Reloading the page (F5) fixes the issue.
The bookmarklet doesn't work on raw.githubusercontent.com because of a strict Content Security Policy (CSP). (Plus the bookmarklet is looking for an element that's not present on this domain.)
The CSP used on github.com can also be too strict; in such cases, I would personally try an alternative solution on Stack Overflow by ostrokach.
The bookmarklet is brittle, i.e. it might need tweaking from time to time as GitHub gets updated.

Alternative bookmarklet code that retains the page's header and footer, so that running the bookmarklet doesn't break client-side routing:

javascript: (() => {
  const selector = '#read-only-cursor-text-area';
  const html = document.querySelector(selector)?.value;

  if (!html) {
    return alert(`Error: element ${selector} not found`);
  }

  const $iframe = document.createElement('iframe');
  $iframe.style.height = '100vh';
  $iframe.style.width = '100%';
  $iframe.srcdoc = html;

  document.querySelector('turbo-frame').replaceChildren($iframe);

  $iframe.scrollIntoView();
})();

The CSP on github.com blocks the iframe from loading most links, so with this version most links are effectively disabled (i.e. clicking a link doesn't do anything, at least on Firefox). In my case this is a feature, not a bug.

There are (at least) two relevant questions on Stack Overflow:

Neither question has as nice solutions as this one by me (until now). Bookmarklets are underrated!

Beware implicit `Content-Type: "application/json"`

2024-08-31T12:00:00+03:00

If you are sending a FormData body with fetch, things might not work correctly if you are (accidentally) setting the Content-Type request header to "application/json".

Problem

I was sending a FormData object to a 3rd party API:

const formData = new FormData()
formData.append('foo', someValue)

const response = await request('https://example.com/api/', {
  body: formData,
  method: 'POST',
})

The API responses were confusing/incorrect.

Culprit

I was using request, which is a thin wrapper around fetch. Something like this:

async function request(url: string, options?: RequestInit) {
  const response = await fetch(url, {
    ...options,
    headers: {
      Accept: 'application/json',
      apiKey: 'abc123',
      'Content-Type': 'application/json',
      ...options.headers,
    },
  })

  if (response.ok) {
    return response.json()
  }

  // Handle errors etc.
}

Notice how I'm defaulting the Content-Type header to "application/json".

This is handy because most of the time I'm sending JSON.

But now I was sending a FormData object, so the implicit "application/json" value caused problems.

It took me a while to realize that this was the culprit for the confusing API responses.

Fix attempt 1

First I tried to "clear" the default Content-Type value:



   const response = await request('https://example.com/api/', {
  body: formData,
  headers: {
    'Content-Type': undefined,
  },
  method: 'POST',
})

But whoops, it caused a TypeScript error (header values must be strings), and the value was set to the string "undefined". Not good.

Fix attempt 2

Then I tried to set the value to "multipart/form-data":




 const response = await request('https://example.com/api/', {
  body: formData,
  headers: {
    'Content-Type': 'multipart/form-data',
  },
  method: 'POST',
})

But this didn't work either.

Explanation

This snippet makes it clear why the 2nd fix attempt didn't work:

const formData = new FormData()

const req = new Request('https://example.com/api/', {
  body: formData,
  method: 'POST',
})

console.log(...req.headers)
//=> ['content-type', 'multipart/form-data; boundary=---------------------------26864524337159351664014536661']

So my Content-Type header value ("multipart/form-data") was missing a boundary value, which is automatically generated by the browser (or Node.js or whatever) and actually required.

From Content-Type on MDN:

For multipart entities, the boundary parameter is required. It is used to demarcate the boundaries of the multiple parts of the message. [...]

[A multipart/form-data] request looks something like the following example with some headers omitted for brevity. In the request, a boundary of ExampleBoundaryString is used for illustration, but in practice, a browser would create a string more like this ---------------------------1003363413119651595289485765.
POST /foo HTTP/1.1
Content-Length: 68137
Content-Type: multipart/form-data; boundary=ExampleBoundaryString

--ExampleBoundaryString
Content-Disposition: form-data; name="description"

Description input value
--ExampleBoundaryString
Content-Disposition: form-data; name="myFile"; filename="foo.txt"
Content-Type: text/plain

[content of the file foo.txt chosen by the user]
--ExampleBoundaryString--

Final fix

The implicit Content-Type: "application/json" was the root cause, so I got rid of it. Well, at least partially:







   async function request(url: string, options?: RequestInit) {
  const response = await fetch(url, {
    ...options,
    headers: {
      Accept: 'application/json',
      apiKey: 'abc123',
      ...(!(options.body instanceof FormData) && {
        'Content-Type': 'application/json',
      }),
      ...options.headers,
    },
  })

  // ...
}

Now if the body is a FormData object, fetch automatically sets the Content-Type header to multipart/form-data with an automatically generated boundary value.

Lessons

My first thought was that while this hand-rolled wrapper around fetch has been handy, maybe it would have been better to use a battle-tested library from the beginning. For example, Ky ("a tiny and elegant HTTP client based on the Fetch API") seems nice.

Or, at least, one should be careful about default/implicit values.

I wonder if the 3rd party API server should also be validating the request headers. The API endpoint expects a FormData body, so maybe it should also check that the Content-Type request header is valid. It would be a small thing to do, but it would have saved me a great amount of time.

Safari doesn't support `position: relative` on `` elements

2024-06-11T12:00:00+03:00

This is a problem if you want whole table rows to be clickable. Luckily there's a (hacky) workaround.

Problem

I want whole table rows (<tr>s) to be clickable.

I don't want to:

Wrap the <tr>s in <a> elements either because that wouldn't be semantic. (Not sure if this would even work; haven't tested.)
Use onClick on the <tr> elements because that wouldn't be accessible.
Use an <a> element in each table cell (<td>) because that's not the same thing and this wouldn't be accessible either (duplicate links).

So I use the ::after pseudo-element trick to expand a link's clickable area to cover the whole table row:

















   





   
    <table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Age</th>
      <th>Eye color</th>
      <th>
        <span class="visually-hidden">Read more</span>
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>John</td>
      <td>22</td>
      <td>Blue</td>
      <td>
        <a aria-label="Read more about John" href="#">→</a>
      </td>
    </tr>
    <!-- ... -->
  </tbody>
</table>

<style>
  tr {
    position: relative;
  }

  a::after {
    content: '';
    inset: 0;
    position: absolute;

    /* Debug outline */
    outline: 2px solid hotpink;
    outline-offset: -3px;
  }
</style>

Demo of the problem on Flems.io.

(This is a crude-ish example; see e.g. Don't Turn a Table into an ARIA Grid Just for a Clickable Row by Adrian Roselli for tips on accessibility.)

Works well e.g. in Firefox:

But Safari doesn't support position: relative on table rows, so the ::after element is way too big – it covers the whole viewport:

In effect, clicking anywhere on the page (above the fold if the page is scrollable) triggers the link on the last table row!

Solution

Step 1: alternative for `position: relative`

  tr {
-   position: relative;
+   transform: translate(0);
  }

I found this from a GitHub issue in the w3c/csswg-drafts repo: [css-position][css-tables] position doesn't apply on <tr> either, from a comment by Oriol Brufau.

Honza Kopecký commented in Oct 2023 that "both Safari and Chrome on iOS don't work and the hack doesn't help either," but in my testing (Jun 2024) the hack does work in Safari on iPadOS v17.4.1.

Two more relevant things that I found:

Step 2: still too big

Now the links' clickable areas are smaller, but still too big in Safari; they are as tall as the whole table:

In effect, the last link's clickable area expands below the table, but otherwise the table rows are properly clickable.

I found a solution from a GitHub comment by Loz Calver under the aforementioned GitHub issue:

If your only issue is absolutely positioned elements overflowing the table-row (e.g. absolutely positioned anchors to make a full row clickable), another possible workaround is to use tr { clip-path: inset(0); }. It causes some strange paint side-effects in Safari, like borders sometimes disappearing, but it does at least clip child elements as expected.

So:

  tr {
    transform: translate(0);
+   clip-path: inset(0);
  }

Step 3: focus outlines

Because of the clip-path used in step 2, make sure you use negative outline-offset for the table rows' focus styles, or the focus styles will also be clipped and invisible:

  tr {
   transform: translate(0);
   clip-path: inset(0);
  }
+ tr:focus-within {
+   outline: 2px solid hotpink;
+   outline-offset: -2px; /* Needs to be negative because of the `clip-path` above */
+ }

+ a:focus {
+   outline: 0; /* The focus styles are on the table row */
+ }
  a::after {
    content: '';
    inset: 0;
    position: absolute;

-   /* Debug outline */
-   outline: 2px solid hotpink;
-   outline-offset: -3px;
  }

Final code

tr {
  /*
    Safari doesn't support `position: relative` on `<tr>` elements,
    but these two properties can be used as an alternative.
    Source: https://mtsknn.fi/blog/relative-tr-in-safari/
  */
  transform: translate(0);
  clip-path: inset(0);
}
tr:focus-within {
  outline: 2px solid hotpink;
  outline-offset: -2px; /* Needs to be negative because of the `clip-path` above */
}

a:focus {
  outline: 0; /* The focus styles are on the table row */
}
a::after {
  content: '';
  inset: 0;
  position: absolute;
}

Demo of the final code on Flems.io.

Tested with:

Edge v125 on Mac
Firefox v126 on Mac
Safari v16.6 on Mac
Safari on iPadOS v17.4.1

"Slap" means "sounds like a plan"

2024-03-13T12:00:00+03:00

I came up with this acronym myself, and I'm proud of it!

I use it often when chatting and conversing with my fam & friends. Not with my parents though, they wouldn't understand.

Sometimes I go so far as to say "slapety slap."

How to use Azure AD authentication in DBeaver

2024-02-28T12:00:00+03:00

Alternative title: How to fix the "Failed to load MSAL4J Java library for performing ActiveDirectoryPassword authentication" error.

I'm using the free Community Edition of DBeaver, version 23.3.5.

In the "Connection Settings" pop-up window:

Select e.g. "Active Directory – MFA" as the authentication method and type your username
Click Driver Settings
Choose the "Libraries" tab
Click Add Artifact from the right

Paste the following XML

<!-- https://mvnrepository.com/artifact/com.microsoft.azure/msal4j -->
<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>msal4j</artifactId>
  <version>1.14.3</version>
</dependency>

Note: the latest version number can be found from the URL in the XML comment, though the exact version you use might not matter that much
I found this step from this GitHub comment

Click OK
Click Download/Update from the right and Download in the opening pop-up window
Click OK
Click Test Connection ... and authenticate in the opening browser window

`mailto:` links with `target="_blank"` are surprisingly tricky

2024-02-19T12:00:00+03:00

Only because Firefox ignores target="_blank" in mailto: links.

Let's say you have an email link that opens in a new tab:

<a href="mailto:hello@example.com" target="_blank">Email me</a>

✅ Clicking the link in Edge works correctly (opens an email client, e.g. Outlook).
✅ Clicking the link in Safari works correctly (opens an email client).
✅ If Firefox is configured to open an email client when clicking mailto: links, clicking the link works correctly (opens an email client).
❌ If Firefox is configured to open a webmail (e.g. Gmail) when clicking mailto: links, clicking the link opens the webmail in the current tab – Firefox ignores target="_blank" in mailto: links because of a long-standing bug. This buggy behavior can be quite annoying.

(I wanted to test how Edge and Safari behave if they have been configured to open a webmail when clicking mailto: links, but configuring this setting in those browsers turned out to be too difficult.^[1] smh)

Based on this Stack Overflow answer, I tried this kind of onClick trickery:

<a
  href="mailto:hello@example.com"
  onClick={(event) => {
    event.preventDefault()
    window.open(url.toString(), 'mail')
  }}
  // No `target="_blank"`
>
  Email me
</a>

✅ If Firefox is configured to open a webmail when clicking mailto: links, clicking the link works now correctly: the webmail is opened in a new tab.

But the UX is degraded in all other cases:

❌ Firefox, configured to open mailto: links in an email client: the new empty tab is left open.
❌ Edge: the new empty tab is immediately closed, which is great, but causes some jarring flashing.
❌ Safari: opens a new tab with a confirm dialog: "This website has been blocked from automatically composing an email."
- Clicking "Allow" opens an email client, but the new empty tab is left open.
- Clicking "Ignore" leaves the new empty tab open.

I was tempted to check if the user's browser is Firefox, and only then use the onClick trick. But trying to detect the user's browser would open another can of worms.

In the end I ended up doing nothing about this, which sucks for some Firefox users, but I don't know what I could do that wouldn't degrade the UX of any other users. 🤔

Footnotes

I did find instructions how configure Edge to open mailto: links in Gmail, but it would require logging in to Gmail, and I don't want to do that, because Edge is a shitty browser (see e.g. The dark defaults of Microsoft Edge and Edge sends images you view online to Microsoft). I use Edge only for testing and occasionally for some web development. Firefox ftw. ↩

Fix all requests timeouting in Burp Suite's Repeater

2024-02-18T12:00:00+03:00

Make sure you are not missing two empty lines after the request headers. There's a UX lesson here.

Problem

I was using Burp Suite (Community Edition, version 2023.12.1.5) for the first time.

Sending requests in the Repeater tab resulted only in timeouts:

HTTP/1.1 408 Request Time-out
Content-length: 110
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<html><body><h1>408 Request Time-out</h1>
Your browser didn't send a complete request in time.
</body></html>

Solution

Adding two empty lines after the request headers fixed it for me.

Before:

GET /wiki/Main_Page HTTP/1.1
Host: en.wikipedia.org
Accept: */*

After:

GET /wiki/Main_Page HTTP/1.1
Host: en.wikipedia.org
Accept: */*

I found the solution and an explanation from a thread on Burp Suite User Forum:

Andre: I found a solution to this. I was removing the 2 extra lines from the request when adding the new header. If I keep them, the requests go through. [...]

Diego: I was having the same issue, but like Andre said above, one of the blank lines of the request had been removed. Adding it back made requests in Repeater work again.

Uthman, PortSwigger Agent: Thanks for your feedback. You can find more information on why this (\r\n\r\n) is required in the RFC 2616 documentation.

UX lesson

That's terrible UX:

The UI doesn't tell that the two empty lines are required.
The problem (all requests timeouting) is confusing.
- I bet most users are not so intimately familiar with RFC 2616 that they can right off the bat deduct that "Oh, right, all requests seem to be timeouting, so I must have forgotten the two trailing newlines required in section 5 of RFC 2616!"

How I would fix this UX issue:

The UI should show a warning or an error if the empty lines are missing.
Or better yet, the app should add the missing empty lines automatically when the user sends a request.
- To be fair, the app seems to add the empty trailing lines automatically, but inconsistently (maybe only when using HTTP/2).

I guess the "UX lesson" can be generalized like so: communicate obscure requirements to the user, and auto-fix issues where possible.

Two great video games I played through in 2023

2024-02-03T12:00:00+03:00

I managed to find time to play Desperados III and Lost in Play (and Before Your Eyes too a bit).

Desperados III

(Screenshot taken from the game's official website.)

Desperados III is a story-driven, hardcore tactical stealth game, set in a ruthless Wild West scenario.

✅ Great visuals
✅ Nice gameplay (tactical stealth game)
✅ Plenty of content – Steam shows that I spent 27.5 hours playing the game

I have previously also played the game's predecessor, Shadow Tactics, which is from the same game studio and has a samurai theme. It was a great game too.

Looks like the game studio has released a third similar game last year – Shadow Gambit: The Cursed Crew – which has a "cursed pirate crew" theme. Maybe not the best theme for me, but at least the gameplay should be great.

➡️ Official website of Desperados III

Lost in Play

(Screenshot taken from the game's official website.)

Solve puzzles, riddles, and embark on an exciting journey of discovery! Join Toto and Gal as they explore dreamscapes and befriend magical creatures. Lost in their imagination, the brother and sister must stick together and solve puzzles to find their way home.

✅ Fantastic music – when I first opened the game, I got stuck in the main menu for a while because I was jamming to the music! (The characters' voices are also excellent)
✅ Fantastic visuals – I really like this kind of art; the game feels like a great cartoon movie, except you are in control
✅ Fun puzzles that got me thinking, but not too hard
✅ Good, childish humor

Steam shows I spent 4.7 hours playing the game, so it's a short game, but excellent!

➡️ Official website of Lost in Play (actually the game studio's website, but it doesn't have any subpages as of now)

Also: Before Your Eyes

(Screenshot taken from the game's official website.)

Embark on an emotional first-person narrative adventure where you control the story – and affect its outcomes – with your real-life blinks. With this innovative technique you will fully immerse yourself in a world of memories, both joyous and heartbreaking, as your whole life flashes before your eyes.

My bro gifted me this game as a birthday present (PS thx!).

Controlling the story with your "real-life blinks" means that you need a webcam (optional). Cool and likely quite unique technique, but a bit wonky and unreliable in the end, so I disabled it after a while.

I played this game a few times but dropped it eventually because it felt somehow felt so depressing. :D Maybe too much black all around (see the screenshot), and because spoiler (read backwards or ):

|: hcum oot deugra stnerap s'tsinogatorp ehT

➡️ Official website of Before Your Eyes (stupid site because there's zero textual information about the game, and the <meta name="description"> is empty too!)

Fiction books I read and liked in 2023

2024-01-31T12:00:00+03:00

I started a new hobby in 2023: reading fiction books! I started with fantasy: Harry Potter, Mistborn, and The Stormlight Archive.

Harry Potter

After several years of not reading fiction books (almost) at all, I started my new reading hobby with this classic heptalogy (= 7-book series) by J. K. Rowling.

I have written about Harry Potter before: I read all 7 seven Harry Potter books in 33 days.

Mistborn

This was a great series! I read all 7 books in the series (trilogy + novella + tetralogy (= 4-book series)). Brandon Sanderson is such a good writer.

Three things that are better in Mistborn than in Harry Potter:

The magic system is logical and there are clear rules, whereas in Harry Potter the magic system feels quite random and chaotic (everything seems possible).
Action scenes are described clearly in Mistborn, whereas in Harry Potter some scenes are quite unclear, like "many spells were flying here and there" (not a direct quote, but I recall especially one scene that was described very vaguely).
There are multiple viewpoints, which brings out people's different personalities, whereas in Harry Potter almost everything is written from the viewpoint of Harry Potter.

The Stormlight Archive

Also by Brandon Sanderson.

This series is much more heavy than Mistborn – there are much more characters and places and things etc.

I'm glad I read Mistborn before this one because had I started with this, this would probably have been way too overwhelming.

So far I have read books 1, 2 and 2.5 (novella), and I'm waiting for book 3 from the library.

Dislikes

I don't want to be Negative Nelly, so I'll just quickly note why I didn't like some books:

Hunger Games (trilogy)
- Silly premise
- Tacky romance
- First-person perspective (I seem to prefer third-person perspective)
- Present tense (feels weird; I prefer past tense)
- Spoiler (read backwards or ):
  
  gnitirw yzal ekil tlef dna gniyonna saw hcihw ,tnemom lacitirc yrev a ni drawrof deppiks yrots eht tniop eno tA
- I read the whole trilogy despite starting to dislike it quite soon after starting :D :|
The House in the Cerulean Sea (novel)
- I had quite high expectations for this as I had read that this is a good novel to read after Harry Potter
- But this was too slow/boring, so I dropped this after a few dozen pages
Malazan Book of the Fallen (series)
- I had read that this is a very heavy series; someone wrote that you need to read ~300 pages before you might start to get a grip of the plot
- So yeah, this indeed felt too heavy, so I dropped this after just a few dozen pages :D
Assassin's Apprentice (series)
- First-person perspective (I seem to prefer third-person perspective)
- Too slow/boring beginning, so I dropped this after a few dozen pages

Tweaking website styles with uBlock Origin filters

2023-11-13T12:00:00+03:00

Use the :style() operator in a uBlock Origin filter to apply CSS styles to the targeted elements.

Here's how I use the :style() operator:

Underline links on BazQux (RSS reader).
Hide points on hckr news.
Highlight visited comment links on hckr news.

Here are the filters (under the "My filters" tab in the uBlock Origin dashboard):

! underline links
bazqux.com##.post .mtext a:style(text-decoration: underline !important)

! hide points
hckrnews.com##.entry.row a:first-child span:style(opacity: 0)

! highlight visited comment links
hckrnews.com##.entry.row a:first-child:style(outline: 20px solid white; outline-offset: -20px)
hckrnews.com##.entry.row a:first-child:visited:style(outline-color: #eee)

I know there's also e.g. Stylus extension for Firefox, but the fewer extensions I need, the better.

"Else equals" in Handlebars (in SendGrid's Dynamic Templates)

2023-11-10T12:00:00+03:00

There's a way to do an "else equals" check in Handlebars (in SendGrid's Dynamic Templates), though it's undocumented and a bit tricky.

Context

Problem

I wanted to do something like this:

{{! Pseudo code, doesn't work }}

{{#if locale == 'en'}}
  <h1>New article: {{articleNameEn}}</h1>
{{else if locale == 'sv'}}
  <h1>Ny artikel: {{articleNameSv}}</h1>
{{else}}
  <h1>Uusi artikkeli: {{articleNameFi}}</h1>
{{/if}}

But it wasn't quite that simple.

Solution

Step by step

Handlebar's #if helper checks only the truthiness of a value; you can't use == or other operators, so {{#if locale == 'en'}} is invalid.
You can create custom Handlebars helpers. However, when using Handlebars in SendGrid, you are limited to SendGrid's Handlebars helpers.

Luckily SendGrid provides an #equals helper:

{{#equals locale 'en'}}
  <h1>New article: {{articleNameEn}}</h1>
{{else}}
  <h1>Uusi artikkeli: {{articleNameFi}}</h1>
{{/equals}}

But whoops, Handlebars helpers create new scopes, so {{articleNameEn}} and {{articleNameFi}} are "empty." Need to use the @root keyword:

 {{#equals locale 'en'}}
-  <h1>New article: {{articleNameEn}}</h1>
+  <h1>New article: {{@root.articleNameEn}}</h1>
 {{else}}
-  <h1>Uusi artikkeli: {{articleNameFi}}</h1>
+  <h1>Uusi artikkeli: {{@root.articleNameFi}}</h1>
 {{/equals}}

And how to do "else equals"? The documentation doesn't tell. But "else if" is documented, so let's try to imitate that:
```
 {{#equals locale 'en'}}
  <h1>New article: {{@root.articleNameEn}}</h1>
{{else equals locale 'sv'}}
  <h1>Ny artikel: {{@root.articleNameSv}}</h1>
{{else}}
  <h1>Uusi artikkeli: {{@root.articleNameFi}}</h1>
{{/equals}}
```
This code is syntactically valid and almost works:
- If locale is 'en', the first branch is executed.
- But if locale is 'sv', the third branch is executed. So the second branch ("else equals") is never executed.

Aha! Same gotcha as above. Because Handlebars is so eager to create new scopes, need to use the @root keyword here as well:

 {{#equals locale 'en'}}
   <h1>New article: {{@root.articleNameEn}}</h1>
-{{else equals locale 'sv'}}
+{{else equals @root.locale 'sv'}}
   <h1>Ny artikel: {{@root.articleNameSv}}</h1>
 {{else}}
   <h1>Uusi artikkeli: {{@root.articleNameFi}}</h1>
 {{/equals}}

Final code

{{#equals locale 'en'}}
  <h1>New article: {{@root.articleNameEn}}</h1>
{{else equals @root.locale 'sv'}}
  <h1>Ny artikel: {{@root.articleNameSv}}</h1>
{{else}}
  <h1>Uusi artikkeli: {{@root.articleNameFi}}</h1>
{{/equals}}

HTTP headers: Accept vs Content-Type

2023-11-09T12:00:00+03:00

I sometimes forget what these two headers do in requests vs responses, so here's a refresher for me.

Accept in request headers: What type of response the client expects from the server.
Accept in response headers: N/A
Content-Type in request headers: The type of the request data (e.g. in a POST or PUT request).
Content-Type in response headers: The type of the response data.

The Content-Type header is usually not needed if the request or response has no data (e.g. GET requests and 204 No Content responses). But apparently "some servers may require you to provide a Content-Type [header] in a request even if the request has no payload."

Cmd-tabing to Firefox on Mac gets progressively slower

2023-11-08T12:00:00+03:00

The longer Firefox is kept open, the longer it takes for Firefox to receive focus after Cmd-tabing to it. At some point it can take even about a second, which really kills the flow.

I initially thought that maybe the problem is in the AltTab app, which is an essential Mac app by they way. But nope, the problem exists even when not using AltTab.

Then I thought that maybe it's some kind of memory leak, caused/aggravated by keeping too many Firefox tabs open (a bad habit of mine). But nope, unloading tabs to free resources doesn't help either.

Only restarting Firefox helps, but that's cumbersome (takes several seconds to do :D).

Eventually I found a bug report on Bugzilla: cmd-tab back to Firefox window on macOS is slow. From a comment by Stephen A Pohl on Sep 25, 2023:

This bug is next on my list of priorities.

Yay! Now let's hope the fix is coming soon™.

JavaScript's default exports are a footgun

2023-11-07T12:00:00+03:00

It's too easy to accidentally import a default export with a misleading name.

Example:

What I have wanted:

import useSWR from 'swr'
// or
import useSWRImmutable from 'swr/immutable'

What I have accidentally done (more than once):
```
import useSWRImmutable from 'swr'
// or
import useSWR from 'swr/immutable'
```
Then I have wasted time being confused by SWR not working like I expect it to.

Named exports would prevent such silly mistakes:

// OK:
import { useSWR } from 'swr'
import { useSWRImmutable } from 'swr/immutable'

// Error:
import { useSWRImmutable } from 'swr'
import { useSWR } from 'swr/immutable'

This is why I think it's bad to use default exports (unless you have a good reason).

Besides, default exports have other issues as well.

Moving zeros to the end of an array in JavaScript

2023-11-06T12:00:00+03:00

Let's learn about anti-symmetry by solving this interview puzzle: "Move all zeros of an array of integers to the end while maintaining the relative order of all non-zeros."

Example:

moveZeros([1, 3, 0, 111, 57, 0, 5, 0, 9])
//=>      [1, 3,    111, 57,    5,    9, 0, 0, 0]

Ok, ez because there's a great visual mnemonic for an array sorter's return values, so we can simply™ sort() the values:

const moveZeros = (numbers: number[]) =>
  numbers.toSorted((a, b) => (a === 0 ? 1 : 0))

moveZeros([1, 3, 0, 111, 57, 0, 5, 0, 9])
//=>      [1, 3,    111, 57,    5,    9, 0, 0, 0]

I used the new toSorted() method to avoid mutating the original array.

Seems to work with the test input, but might break with other inputs, because the comparator function is not anti-symmetric. From sort() on MDN:

[I]f a comparator only returns 1 and 0, or only returns 0 and -1, it will not be able to sort reliably because anti-symmetry is broken.

So we need to also check if b === 0:

const moveZeros = (numbers: number[]) =>
  numbers.toSorted((a, b) => (a === 0 ? 1 : b === 0 ? -1 : 0))

Nested ternaries are icky though, plus returning 1 or -1 is not very clear without comments.

Final solution:

const moveZeros = (numbers: number[]) =>
  numbers.toSorted((a, b) => {
    if (a === 0) return +1 //   a->
    if (b === 0) return -1 // <-a
    return 0 // Keep order
  })

Though I have to admit that Juhani Kumara's solution using reduceRight is annoyingly clever!

const move0 = (arr) =>
  arr.reduceRight((acc, cur) => (acc[cur ? 'unshift' : 'push'](cur), acc), [])

Logging hours to Jira's "Work log" in bulk

2023-11-03T12:00:00+03:00

There's apparently no nice way to bulk-log hours in Jira. Use this One Weird Trick to do it anyway – Jira consultants HATE it!

Problem

Jira's UI for logging hours ("Work log" / "Time tracking") is clunky:

It requires lots of mouse clicks and/or key presses.
It gets very repetitive after a few times.
The UI keeps changing from time to time, breaking my workflow.

Officially hours can apparently be logged in bulk by importing data from a CSV file, but that sounds clunky and doesn't work if your user account doesn't have permission to import data from CSV files.

Solution

Overview:

Track hours in a JS file.
Log the hours by copy-pasting the code and running it in the browser's JS console.

Tracking hours

Create a JavaScript file and keep track of hours with this fancy format:

// @ts-check

/**
 * @type {Record<
 *   `${'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri'} 2023-11-${number}`,
 *   [ticketId: `FOO-${number}` | null, hours: number][]
 * >}
 */
const items = {
  // ...
  'Wed 2023-11-08': [
    ['FOO-123', 1.5], // pr fixes
    ['FOO-333', 5], // feature x
    ['FOO-444', 1], // pr review
  ],
  'Tue 2023-11-07': [
    ['FOO-222', 3], // yarn install investigation
    [null, 1], // backlog grooming
    ['FOO-333', 3.5], // feature x
  ],
  'Mon 2023-11-06': [
    ['FOO-123', 7], // nav revamp
    [null, 0.5], // daily
  ],
}

Notes:

Use JS instead of TS so that you can later copy-paste the code directly to the browser's JS console.
The // @ts-check comment at the top lets you still get the benefits of TS; it makes VS Code nag at you if you get some values wrong.
Adjust the date and ticket ID types accordingly; e.g. 2023-12-${number} when it's December and ABC-${number} if your Jira ticket IDs start with ABC-.
I'm using null instead of FOO-${number} for general stuff because I can't remember the "general stuff" ticket's ID.
The code comments are for you so you'll remember later how you have been spending your time.

Logging hours

Initial setup

This needs to be done only once.

Open the browser's DevTools.
Log hours manually in Jira (only one logging needed).
Select the Network tab of DevTools and look for the XHR request that was just made.

Right-click on the item and select "Copy as Fetch." The code might look something like this:

await fetch(
  'https://jira.example.com/rest/internal/3/issue/FOO-123/worklog?adjustEstimate=new&newEstimate=0m',
  {
    credentials: 'include',
    headers: {
      'User-Agent': 'redacted for privacy lolz',
      Accept: 'application/json,text/javascript,*/*',
      'Accept-Language': 'en-US,en;q=0.5',
      'Content-Type': 'application/json',
      'X-Atlassian-Capability': 'ISSUE_VIEW',
      'Sec-Fetch-Dest': 'empty',
      'Sec-Fetch-Mode': 'cors',
      'Sec-Fetch-Site': 'same-origin',
      Pragma: 'no-cache',
      'Cache-Control': 'no-cache',
    },
    referrer: 'https://jira.example.com/browse/FOO-123',
    body:
      '{"timeSpent":"30m","comment":{"type":"doc","version":1,"content":[]},"started":"2023-10-30T08:00:00.000+0200"}',
    method: 'POST',
    mode: 'cors',
  }
)

Add the following snippet to the JS file after the items object; notice how I have removed unnecessary Fetch options and replaced hardcoded values with template strings:

const items = {
  // ...
}

;(async () => {
  for (let [date, rows] of Object.entries(items)) {
    date = date.split(' ')[1] // E.g. "Mon 2023-10-23" -> "2023-10-23"

    for (let [ticketId, time] of rows) {
      ticketId ??= 'FOO-111' // "General stuff" ticket
      time *= 60 // Hours to minutes

      await fetch(
        `https://jira.example.com/rest/internal/3/issue/${ticketId}/worklog?adjustEstimate=new&newEstimate=0m`,
        {
          body: JSON.stringify({
            timeSpent: `${time}m`,
            comment: { type: 'doc', version: 1, content: [] },
            started: `${date}T08:00:00.000+0200`,
          }),
          headers: {
            Accept: 'application/json',
            'Content-Type': 'application/json',
          },
          method: 'POST',
          referrer: `https://jira.example.com/browse/${ticketId}`,
        }
      )
    }
  }
})()

There might still be some fluff (I don't know if e.g. the referrer is needed), but good enough.

Actually logging

Open Jira in the browser.
Copy-paste the code (including the items object) to the browser's JS console.
Press Enter in the JS console and switch to the Network tab to monitor whether the Fetch requests succeed or fail. (So far they have never failed for me (*knocks on wood*).)
Comment out the logged items in the JS file to avoid accidentally re-logging them the next time:
```
const items = {
  // 'Mon 2023-11-06': [
  //   ...
  // ],
}
```
(Or just remove the logged items.)

Nice and easy!

Pin exact dependency versions

2023-11-02T12:00:00+03:00

In a perfect world, minor- and patch-level version bumps don't have breaking changes. In the real world, things are complicated and shit happens.

Example: I recently witnessed yarn install starting to fail mysteriously after Node.js was automatically upgraded from v18.16 to v18.18.

I had thought that pinning the major-level version number of Node.js would have prevented this kind of sudden breakages, but nope.

Had the Node.js version been pinned to v18.16.1 or even just v18.16, yarn install wouldn't have started to suddenly fail.

Yes, yarn install would have probably started to fail later when upgrading Node.js manually, but that's not as bad. Sudden breakages are worse because they often require acute investigation, making your workdays more reactive than proactive.

So, note to self: pin exact dependency versions (x.y.z instead of just x.y or x) to be on the safe side.

`error.cause` needs to be logged manually to App Insights

2023-11-01T12:00:00+03:00

If you are logging errors to Azure App Insights, and an Error object has a cause property (which too could be an Error object), the cause Error's message and stack properties are not shown in Azure App Insights. But you can log them manually.

Problem

Use App Insights SDK for Node.js.

Use the trackException method to log an error with a cause property:

import * as appInsights from 'applicationinsights'

try {
  throw new Error('foo')
} catch (error) {
  appInsights.defaultClient.trackException({
    exception: new Error('bar', { cause: error }),
  })
}

Expected behavior: both Error's message and stack trace are shown in App Insights.

Actual behavior: only the second Error's message (= 'bar') and stack trace are shown in App Insights.

A less contrived example

router.get('/foo', async (req, res) => {
  try {
    const data = await database.getFoo() // This can throw
    res.json(data)
  } catch (error) {
    appInsights.defaultClient.trackException({
      exception: new Error('GET /foo failed', { cause: error }),
    })
  }
})

Solution

Log the first/original Error's stack property manually:






  try {
  // ...
} catch (error) {
  appInsights.defaultClient.trackException({
    exception: new Error('...'),
    properties:
      error instanceof Error ? { causeStack: error.stack } : undefined,
  })
}

Now the first/original Error's message and stack trace will be shown in App Insights under the "Custom Properties" heading.

Notes

The error instanceof Error check is needed because:

The value of cause can be of any type. You should not make assumptions that the error you caught has an Error as its cause, in the same way that you cannot be sure the variable bound in the catch statement is an Error either.

Source: Error: cause on MDN
No need to include error.message in the properties object, because in Node.js, error.stack also includes the error message.

`\d` in a regex isn't always equal to `[0-9]`

2023-10-31T12:00:00+03:00

In JavaScript, \d and [0-9] are equal and match only Arabic numerals (the numbers 0–9). But in some other languages, \d matches also non-Arabic numerals.

There are 680 Unicode characters in the "Number, Decimal Digit" category. For example:

Name	Characters
Digits (Arabic numerals)	0123456789
Arabic-Indic digits	٠١٢٣٤٥٦٧٨٩
Extended Arabic-Indic digits	۰۱۲۳۴۵۶۷۸۹
NKo digits	߀߁߂߃߄߅߆߇߈߉
Devanagari digits	०१२३४५६७८९

Testing on regex101.com:

\d in JavaScript matches 10 of them (Arabic numerals only)
\d in C# matches 370 of them
\d in Python matches 540 of them
\d in Rust matches all 680

(I haven't tested whether \d in those three languages matches also other characters than those 680.)

[0-9] matches only Arabic numerals in those four languages, but even [0-9] can't be always trusted (a few typos fixed in the quotation):

It is generally believed that [0-9] matches only the ASCII digits 0123456789. That is painfully false in some instances: Linux in some locale that is not "C" (June 2020) systems, for example:

Assume:
str='0123456789 ٠١٢٣٤٥٦٧٨٩ ۰۱۲۳۴۵۶۷۸۹ ߀߁߂߃߄߅߆߇߈߉ ०१२३४५६७८९'
Try grep to discover that it allows most of them:
$ echo "$str" | grep -o '[0-9]\+'
0123456789
٠١٢٣٤٥٦٧٨
۰۱۲۳۴۵۶۷۸
߀߁߂߃߄߅߆߇߈
०१२३४५६७८
sed has some troubles. Should remove only 0123456789 but removes almost all digits. That means that it accepts most digits but not some nines (???):
$ echo "$str" | sed 's/[0-9]\{1,\}//g'
 ٩ ۹ ߉ ९
Even expr suffers from the same issues as sed:
expr "$str" : '$[0-9 ]*$' # also matching spaces
0123456789 ٠١٢٣٤٥٦٧٨
And also ed:
printf '%s\n' 's/[0-9]/x/g' '1,p' Q | ed -v <(echo "$str")
105
xxxxxxxxxx xxxxxxxxx٩ xxxxxxxxx۹ xxxxxxxxx߉ xxxxxxxxx९

Huh. Curious.

I guess I'd better remember to avoid \d and prefer [0-9] or even [0123456789] when using other languages than JavaScript.

When writing JavaScript, I'll continue using \d as it's as clear (d = digit) as and shorter than [0-9].

`response.json()` can throw an error in JavaScript

2023-10-30T12:00:00+03:00

If the response body is not valid JSON, response.json() will throw, just like JSON.parse() would throw if the same data was passed to it.

Example:

const response = new Response('{ "foo": true }')
await response.json()
//=> { foo: true }

// vs

const response = new Response('OK')
await response.json()
//=> SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data

Quite obvious in hindsight, but I was wondering this and couldn't find an answer quickly (I tried googling "can response.json throw in js").

How about response.text() – can it throw? No, because it's akin to passing the same data to the String() function, which doesn't seem to throw according to the language specs. (Compare with the language specs of JSON.parse(); throwing is mentioned in step 2.)

`error.stack` includes the error message in some JS environments

2023-10-29T12:00:00+03:00

In V8-based JS environments (e.g. Chrome, Deno and Node.js) and in Bun, error.stack = error class name + error.message + stack frames.

Context

I was logging an Error object's message and stack properties to Azure App Insights (because error.cause needs to be logged manually to App Insights), and was baffled because error.stack seemed to contain not only the stack trace, but also the error message. I thought App Insights was doing something wonky to the Error object.

Culprit: V8

Eventually I realized that that's how the V8 JS engine works. From V8's Stack trace API docs:

Here's an example of a fully formatted stack trace:

ReferenceError: FAIL is not defined
   at Constraint.execute (deltablue.js:525:2)
   at Constraint.recalculate (deltablue.js:424:21)
   at Planner.addPropagate (deltablue.js:701:6)
   at Constraint.satisfy (deltablue.js:184:15)
   at Planner.incrementalAdd (deltablue.js:591:21)
   at Constraint.addConstraint (deltablue.js:162:10)
   at Constraint.BinaryConstraint (deltablue.js:346:7)
   at Constraint.EqualityConstraint (deltablue.js:515:38)
   at chainTest (deltablue.js:807:6)
   at deltaBlue (deltablue.js:879:2)

Node.js's error.stack docs say it more explicitly:

The first line is formatted as <error class name>: <error message>, and is followed by a series of stack frames (each line beginning with "at ").

(It's mentioned in Node.js v4 docs as well. Node.js v4 was released in 2015.)

Non-V8 environments

In Firefox and Safari, error.stack contains only the stack trace. Firefox's JS engine is SpiderMonkey; Safari's JS engine is JavaScriptCore.

Bun is interesting because it's also "powered by JavaScriptCore", but its error.stack includes the error class name and error message as well.

Non-standard

The Error.prototype.stack page on MDN says that it's a non-standard property:

Non-standard: This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

Using error.stack on the server is likely a-okay though (as long as you are familiar with how it works in your JS environment).

`yarn install` failing mysteriously on Node.js v18.18

2023-10-28T12:00:00+03:00

TL;DR: Upgrading Yarn from v1 to v4 fixed it for me.

Problem

Recently some CI pipelines^[1] started to fail at yarn install (v1.22.19) with cryptic error messages like these (the error message kept changing):

An unexpected error occurred:
"/path/to/project/node_modules/core-js-pure:
Cannot read properties of undefined (reading 'getOption')".

An unexpected error occurred:
"/path/to/project/node_modules/nodemon:
Cannot read properties of undefined (reading 'getOption')".

An unexpected error occurred:
"/path/to/project/node_modules/spawn-sync:
Cannot read properties of undefined (reading 'config')".

Googling those error messages didn't yield anything useful.

Solution

The errors seemed to began after Node.js was upgraded from v18.16 to v18.18.

Googling "yarn install fails on node.js 18.18.2" (:D) led me to this GitHub comment on yarnpkg/yarn#3728:

6 years later, NPM removes the node-gyp binary from its bundle with v9.7.2 which is released with Node 18.18. Breaking our builds because now yarn tries to install node-gyp automatically and runs every now and then into this issue. Time to move away from yarn v1. :)

npm/cli#6554 (comment)

Leaving a comment primarily for others running into this problem now.

Upgrading Yarn to Yarn v4, which was released just a few days ago, did indeed fix the yarn install errors.

Side comments

Upgrading to Yarn v2 or v3 might have worked as well (I didn't test).
I wasn't even aware that there are multiple versions of Yarn. Maybe because it's not a "normal" dependency.
yarn install on Yarn v1 typically took about ~1.5 minutes in the CI pipelines, whereas on Yarn v4 it takes only about ~1 minute. A nice improvement!

The real lesson

The real lesson here is to pin exact dependency version numbers.

In my case Node.js was automatically upgraded from v18.16 to v18.18 because the version of Node.js was pinned to v18.

Had the Node.js version been pinned to v18.16.1 or v18.16 instead of just v18, these errors wouldn't have started suddenly.

Footnotes

The CI pipelines were on Azure DevOps. That's likely irrelevant, but I still wanted to mention it, because:

When investigating this problem, at first I didn't know what's causing it. One of the Google searches I made was "azure devops yarn install Cannot read properties of undefined (reading 'config" (:D).

That search didn't yield any useful results. This page you are reading now would have been quite useful. ↩

Visual mnemonic for an array sorter's return values

2023-10-17T12:00:00+03:00

When sorting an array with a custom comparator function, the function should return <0, 0 or >0. But what do the values do? Use this weird visual mnemonic – sorting consultants HATE it!

First, recall that an array sorter compares two values, a and b:

array.sort((a, b) => {
  // ...
})

Second, because the sorter function should return a number, imagine an x-axis with the numbers -1, 0 and +1:

Now, realize that -1 is on the left side of the x-axis, and +1 is on the right side:

Returning -1 (or anything less than zero) from the array sorter moves a to the left (before b in the array).
Returning +1 (or anything greater than zero) from the array sorter moves a to the right (after b in the array).
(Returning 0 keeps the order of a and b.)

And why is a moved relative to b – because the array sorter compares two values (a and b), and a comes first in the function parameters ((a, b) => {}). First come, first served.

Like so:

That's it! To recap:

array.sort((a, b) => {
  return -1 // <-a
  return +1 //   a->
  return 0 // Keep order of `a` and `b`
})

(Illustrations mouse-drawn on tldraw.com.)

Strict object validation is handy for data exploration

2023-10-10T12:00:00+03:00

Alternative title: I finally found a good use case for z.object().strict() in Zod.

Zod's z.object() ignores unknown keys (= object keys not specified in a Zod schema) by default. Unknown keys can be disallowed with Zod's .strict() method.

When would .strict() be useful? From a GitHub comment by Kamil Trebunia:

For consuming APIs I would almost always pick z.object, but for data exploration as I am doing now z.strictObject is necessary and I am glad I found about it.

So: if you are exploring what data a poorly documented API returns, you can use z.object().strict() (or the shorthand z.strictObject()) to avoid missing any keys; unspecified keys will make Zod throw an error, so you can adjust the Zod schema accordingly.

There's no .deepStrict() method in Zod, but it's easy to search for .object( and replace all occurrences with .strictObject(.

Adding type-safety to Node-Cache

2023-08-22T12:00:00+03:00

Node-Cache (a JS library) has generic get and set methods, but it's easy to accidentally misuse them. I made a type-safer wrapper around the library.

Problem / Context

Node-Cache is a caching module for Node.js:

A simple caching module that has set, get and delete methods and works a little bit like memcached. Keys can have a timeout (ttl) after which they expire and are deleted from the cache. All keys are stored in a single object so the practical limit is at around 1m keys.

Node-Cache's get and set methods are generic, which is nice:

import NodeCache from 'node-cache'

const myCache = new NodeCache(options)

myCache.set<Foo>(cacheKey, value)
const foo = myCache.get<Foo>(cacheKey)

But the constructor is not generic, which is problematic; you can accidentally use wrong types when getting and setting values.

Example case

I was investigating a weird bug and was running out of ideas. Finally I noticed that a single cache was accidentally being used for two different things:
























  import NodeCache from 'node-cache'

const fooCache = new NodeCache(options)
const barCache = new NodeCache(options)

export function getFoo(id: number) {
  if (fooCache.has(id)) {
    return fooCache.get<Foo>(id)
  }

  const value = getFooFromSomewhere()

  fooCache.set<Foo>(id, value)
  return value
}

export function getBar(id: number) {
  if (barCache.has(id)) {
    return barCache.get<Bar>(id)
  }

  const value = getBarFromSomewhere()

  // ⚠️ Whoops! Accidentally using the wrong cache here
  fooCache.set<Bar>(id, value)
  return value
}

Solution

Goal

Ideally the constructor would be generic, so that a cache can contain only certain types:

const fooCache = new NodeCache<Foo>(options)

const foo = fooCache.get(cacheKey) //=> Foo | undefined
fooCache.set(cacheKey, value) // `value` must be of type `Foo`

Currently this is not possible; GitHub issue #273 is asking for this.

The issue was created in December 2021, and the latest commit to the project was made in November 2021, so the issue might never get solved.

I solved it myself by creating a type-safer wrapper around Node-Cache.

Code

// eslint-disable-next-line no-restricted-imports
import NodeCache, { Key, Options, ValueSetItem } from 'node-cache'

/**
 * A type-safer wrapper around [Node-Cache](https://github.com/node-cache/node-cache).
 *
 * Via https://mtsknn.fi/blog/type-safer-node-cache/
 *
 * @example
 * const myCache = Cache<MyType>(options)
 * myCache.set('foo', value)
 * myCache.get('foo')
 *
 * @example
 * // Error: Must provide a type parameter
 * const myCache = Cache(options)
 */
export function Cache<T = void>(
  // A fancy way to make the `T` parameter required:
  // https://stackoverflow.com/a/51173322/1079869
  options: Options &
    (T extends void
      ? 'Error: Must provide a type parameter (`Cache({})` -> `Cache<T>({})`)'
      : Options)
) {
  const cache = new NodeCache(options)

  return {
    // Type casting required to not lose some methods (e.g. `del`)
    ...(cache as Required<typeof cache>),

    // Only the generic methods of Node-Cache are overridden
    get: (key: Key) => cache.get<T>(key),
    mget: (keys: Key[]) => cache.mget<T>(keys),
    mset: (keyValueSet: ValueSetItem<T>[]) => cache.mset<T>(keyValueSet),
    set: (key: Key, value: T, ttl?: number | string) =>
      cache.set<T>(key, value, ttl as number | string),
    take: (key: Key) => cache.take<T>(key),
  }
}

Notes

Apparently there's no built-in way to mark generic type parameters as required. So instead of using <T> and options: Options:

export function Cache<T>(options: Options) {
  // ...
}

...I'm using a fancy way to make the generic T parameter required:

export function Cache<T = void>(
  options: Options &
    (T extends void
      ? 'Error: Must provide a type parameter (`Cache({})` -> `Cache<T>({})`)'
      : Options)
) {
  // ...
}

Cache({})
//    ^? Argument of type '{}'
//       is not assignable to parameter of type
//       'Options & "Error: Must provide a type parameter (`Cache({})` -> `Cache<T>({})`)"'.

Cache<Foo>({}) // OK

Unfortunately this also makes the options parameter required. Passing an empty object is OK.

Not ideal, but better than nothing.

For some reason the spread syntax causes some methods to be lost:





 





  export function Cache<T>(options: Options) {
  const cache = new NodeCache(options)

  return {
    ...cache,
    get: (key: Key) => cache.get<T>(key),
    // ...
  }
}

const fooCache = Cache<Foo>({})
fooCache.del('bar')
//       ^? Property 'del' does not exist on type '...'.

Type casting fixes the problem (I don't know why):


 return {
  ...(cache as Required<typeof cache>),
  get: (key: Key) => cache.get<T>(key),
  // ...
}

At first I used ...(cache as Omit<typeof cache, 'get' | 'mget' | 'mset' | 'set' | 'take'>), but ...(cache as Required<typeof cache>) and ...(cache as Readonly<typeof cache>) seem to work as well.

Only the generic methods of Node-Cache need to be overridden; there's nothing to fix in the non-generic methods (unless I'm missing something).

You might want to copy the JSDoc comments from Node-Cache's index.d.ts. For example (comment slightly clarified by me):

return {
  // ...

  /**
   * Get a cached key and remove it from the cache.
   * Equivalent to calling `get(key)` + `del(key)`.
   *
   * Useful for implementing "single use" mechanism such as OTP (one-time password),
   * where once a value is read it will become obsolete.
   */
  take: (key: Key) => cache.take<T>(key),
}

Bonus: ESLint

One more step: use ESLint to prevent importing Node-Cache so that everyone will use the type-safer wrapper instead.

There are two built-in ESLint rules for this:

no-restricted-imports to "disallow specified modules when loaded by import."
no-restricted-modules to "disallow specified modules when loaded by require"; useful if you are still using CommonJS modules.

Like so:

// .eslintc

{
  "rules": {
    "no-restricted-imports": [
      "error",
      { "name": "node-cache", "message": "Import the `Cache` utility instead." }
    ],
    "no-restricted-modules": [
      "error",
      { "name": "node-cache", "message": "Import the `Cache` utility instead." }
    ]
  }
}

Example:

// foo.ts

import NodeCache from 'node-cache'
//=> 'node-cache' import is restricted from being used.
//   Import the `Cache` utility instead.
//   eslint(no-restricted-imports)

YouTube's "Show transcript" tool is great for taking video notes

2023-06-28T12:00:00+03:00

Incidentally, it's also great for searching for certain words in a video.

Click the three dots under a video and then "Show transcript." Example screenshot from Agile Product Ownership in a Nutshell (15:51) by Henrik Kniberg:

This tool saves time and effort: I don't need to be a human speech-to-text machine; I can instead focus on fixing typos and errors in the transcript and splitting the text into several paragraphs and bullet points to make it easier to read. Two examples:

Side note: I opened an incognito window to take the screenshot, and uhh... YouTube looks so bloated. Protip: block the #related element (the "related videos" container on the right) with uBlock Origin (or use other tools to debloat YouTube).

Bookmarklet to download still images from YouTube videos

2023-06-27T12:00:00+03:00

Quick and dirty code to grab a single frame of a YouTube video. Might work with other video players too.

The bookmarklet

Drag and drop this to the browser's bookmarks bar:

YouTube: Download still image

Usage

Open a YouTube video
Maximize the browser window and use YouTube's "Theater mode" for a larger result
Pause the video at some point
Run the bookmarklet; it will download a PNG image

Code

Minified

javascript:(() => { const $video = document.querySelector('video'); const { height, width } = $video.getBoundingClientRect(); const $canvas = document.createElement('canvas'); const ctx = $canvas.getContext('2d'); ctx.canvas.height = height; ctx.canvas.width = width; ctx.drawImage($video, 0, 0, width, height); const $a = document.createElement('a'); $a.download = 'frame.png'; $a.href = $canvas.toDataURL(); $a.click(); })()

Unminified

javascript:(() => {
  const $video = document.querySelector('video');
  const { height, width } = $video.getBoundingClientRect();

  const $canvas = document.createElement('canvas');
  const ctx = $canvas.getContext('2d');
  ctx.canvas.height = height;
  ctx.canvas.width = width;
  ctx.drawImage($video, 0, 0, width, height);

  const $a = document.createElement('a');
  $a.download = 'frame.png';
  $a.href = $canvas.toDataURL();
  $a.click();
})()

Next steps

Your needs may be different from mine, but here's what I usually do:

Resize the image using Mac's Preview app
Compress the image with TinyPNG
Use the image in a blog post

The end result might have poor quality, but that's all right. I use this only for getting still images for video notes.

For an example, check out yesterday's post, Legacy code is code written by other people. Looks good enough for me.

Acknowledgements

I googled for "js video get frame screenshot." The first result was "Capture frames from video with HTML5 and JavaScript" question on Stack Overflow which gave me a good starting point.

Legacy code is code written by other people

2023-06-26T12:00:00+03:00

Legacy code means unfamiliar code. Legacy code has much more to do with unfamiliarity than the quality of the code itself.

From the Prioritizing Technical Debt as If Time & Money Matters talk by Adam Tornhill (28:42), from 19:53–22:14:

Legacy code is related to technical debt, but the two are not the same.

So what is legacy code?

There are many definitions out there. The definition I prefer is that:

Legacy code is code that somehow lacks in quality,

and more importantly, it's code that we didn't write ourselves.

Right.

And that second part is really important, so let me share a story with you. This is something that happened to me five years ago, and I've met it several times since then.

What happened here was that I was visiting our client. I did a workshop for one of their teams. We did a hotspot analysis of their code bases. And they had two code bases. So we analyzed them. We talked about them, discussed how we could address the findings.

And then, after a while,

someone in the team mentioned that "You know what? We actually have a third code base as well."

So I start to think "Okay, should we analyze that one too?"

And everyone kind of looked at each other and laughed a little bit like "Uh, no, we don't really have to do that."

So I said "Why not?"

"Because we know the third code base is a mess."

And I was like "Yeah, we really have to look at it," right?

So we did. And we looked at the hot spot[s], we looked at the code health metrics, cyclomatic complexity, all that stuff...

And guess what? Objectively there was absolutely no difference in code quality between the first two code bases and the third one.

And you know, when you bring up something like that, everyone starts to question it, that "Hey, maybe the tool is measuring the wrong thing; maybe you are measuring the wrong thing." Right?

So we had to spend a lot of time actually comparing code samples, and after a while everyone was fairly convinced – even though they didn't like it – that code base number three was indeed in no worse shape than the other two.

So why did everyone think that it was such a mess?

The reason of course was that code base number three turned out to be developed in a different part of the organization, in a team that has since been disbanded. And this team had simply inherited that code base, meaning they were now responsible for a piece of code that they didn't write themselves. They didn't understand the problem domain, and they didn't understand the solution.

So [legacy code] has much more to do with unfamiliarity than any properties of the code itself.

Makes sense! Low-quality code can be okay to work with if it's familiar enough. On the other hand, unfamiliar code can feel smelly and intimidating at first, even if it turns out to be of high quality.

When someone leaves a team or an organization, they leave behind legacy code (read: code that is unfamiliar to others), unless someone else happens to be familiar with all the current code authored by the leaving person.

`Date` objects are nicer to work with than date strings

2023-06-25T12:00:00+03:00

When parsing data, date strings should likely be converted to Date objects. But beware mutations.

Intended audience / Applicable languages

This post is for you if you are dealing with date strings.

This post uses JavaScript and TypeScript, but the main ideas are likely quite language-agnostic.

Context

Let's say some data from e.g. an API or database contains a date string in ISO format:

const data = {
  createdOn: '2023-06-25T01:23:45Z',
  // ...
}

When validating/parsing the data, the date string could at the same time be transformed to a Date object. (See Parsing data is nicer than only validating it.)

Example using Zod, a TypeScript validation library:

import { z } from 'zod'

const Schema = z.object({
  createdOn: z.string().datetime().pipe(z.coerce.date()),
  // ...
})

const result = Schema.parse(data)
//    ^? { createdOn: Date; ... }

Why `Date` objects are better

Semantically correct

A date string is not a date; it's a serialized format of a date.

When parsing data, it's semantically correct to convert/deserialize date strings to Date objects.

(Not sure if "semantically correct" is the correct term here, but anyway.)

Convert only once

If you convert a date string to a Date object right after receiving the data, you need to do the conversion only once.

This avoids shotgun parsing, or repeating and scattering date parsing here and there. (More about shotgun parsing in Parsing data is nicer than only validating it.)

`toLocaleString()` et al.

If you have a Date object, you can directly use Date.prototype.toLocaleString() and other Date methods.

If you have a date string, you first need to convert the string to a Date object – every time you want to use toLocaleString() (shotgun parsing).

Even if you have wrapper functions for formatting dates (probably a good thing), you could make the functions take a Date argument instead of a Date | string argument (simplicity).

date-fns et al.

date-fns is a JavaScript date utility library.

Most date-fns functions take Date arguments, not date string arguments, so you can do e.g. just startOfWeek(date) instead of startOfWeek(parseISO(dateString)) (shotgun parsing, again).

Beware mutations

One drawback is that Date objects are mutable. Accidental mutations can lead to hard-to-track bugs; deliberate mutations can lead to hard-to-reason code.

This might be not such a big issue if the object is not otherwise guarded; obj.createdOn.setFullYear(2000) might not be much worse than any of these:

obj.createdOn = '2000' + obj.createdOn.slice(4)
obj.name = 'foo'
obj.items.push('bar')

Anyhow, there are a few ways to avoid Date mutations (these are not specific to Zod):

Use a function

Instead of obj.createdOn, make it a function obj.getCreatedOn() that creates a new Date object every time:

const obj = {
  getCreatedOn: () => new Date('2023-06-25T01:23:45Z'),
}

const a = obj.getCreatedOn()
const b = obj.getCreatedOn()

a === b //=> false

Good: If you mutate the Date object returned by obj.getCreatedOn(), the mutation affects only the freshly-created Date object. That's better than the mutation affecting who knows how many places.

Bad: Some object properties are now functions and some are not, making the object asymmetrical (obj.name vs obj.getCreatedOn()).

Use a getter property

Very similar to above, but make obj.createdOn a getter property instead:

const obj = {
  get createdOn() {
    return new Date('2023-06-25T01:23:45Z')
  },
}

const a = obj.createdOn
const b = obj.createdOn

a === b //=> false

Good: Same as above + now the object is more symmetrical (obj.name vs obj.createdOn).

Bad: I don't like getters and setters because they are not transparent; they look like normal object properties, but they are not.

Use TypeScript

TypeScript doesn't have a built-in type for read-only Dates, but such a type can be easily created:

type ReadonlyDate = Readonly<
  Omit<
    Date,
    | 'setDate'
    | 'setFullYear'
    | 'setHours'
    | 'setMilliseconds'
    | 'setMinutes'
    | 'setMonth'
    | 'setSeconds'
    | 'setTime'
    | 'setUTCDate'
    | 'setUTCFullYear'
    | 'setUTCHours'
    | 'setUTCMilliseconds'
    | 'setUTCMinutes'
    | 'setUTCMonth'
    | 'setUTCSeconds'
  >
>

(Credit: Daniel Nixon; the type is from date-fns GitHub issue Suggestion: use a readonly Date type in TypeScript. Also, using Readonly<...> is probably unnecessary here.)

Good: Leverages the type system; doesn't affect runtime.

Bad: E.g. date-fns functions don't accept ReadonlyDate arguments:

Argument of type ReadonlyDate is not assignable to parameter of type number | Date.

Type ReadonlyDate is missing the following properties from type Date: setTime, setMilliseconds, setUTCMilliseconds, setSeconds, and 11 more.

Use ESLint

Date mutations could be theoretically banned with ESLint.

eslint-plugin-better-dates does this, but the plugin looks outdated. It would probably be quite easy to create a similar plugin from scratch.

Good: Sounds like a job suitable for ESLint.

Bad: The plugin looks outdated.

Using ESLint might be my choice to avoid Date mutations.

Summary

A date string is a serialized format of a date.
When parsing data, it's "correct" to deserialize date strings to Date objects.
Correctness aside, Date objects are also nicer to work with.
Beware accidental mutations of Date objects.

I read all 7 seven Harry Potter books in 33 days

2023-06-14T12:00:00+03:00

I don't know if I have ever read so much in so short time. I just liked the books so much.

Pages per day

Here's a table of my reading progress for my own amusement (books published by Bloomsbury, 2014 editions):

Book	Pages	Days	Average pages per day
1st	332	5	66
2nd	360	4	90
3rd	462	4	116
4th	617	5	123
5th	800	6	133
6th	542	6	90
7th	620	5	124
Total	3,733	33	113

There were 33 total days instead of 35 because I started the 4th and 6th books on the same day as I finished the previous book.

Lines per page

The 4th book's text felt smaller than the first three books' text, so I had to check:

28 lines per page
28
28
33
34 (!)
33
33

So my "pages per day" comparison table is flawed, meh.

Fun fact: the 5th book is the longest (800 pages), but it also has the most lines per page, so it's really a thick book.

Thoughts and spoilers

🚨 Spoilers below.

Easy English, weird words

The books were easy to read, but there were also many weird words; shows that Rowling's favorite school subject was English (it was mentioned at the end of one of the books).

Some new-for-me words that I still remember (these are far from the weirdest words though):

exasperated (maybe not a new word for me, but I had trouble remembering what this means)
kissing gate
palomino
pensieve
tabby cat

Consistent point of view

Everything revolves around Harry. If something happens or has happened elsewhere, it's explained from Harry's point of view; e.g. Harry has visions, or someone retells a story for Harry.

So, the point of view is always consistent, which makes the books feel coherent.

I noticed that the last two books break this rule a bit; they have non-Harry points of view in the first chapter(s). (I checked and the 1st and 4th books start from different points of view too.)

Biggest plot weakness

Some wizards and witches are totally isolated from the rest of the world (from the Muggle world). Feels silly.

Most boring scene

The 4th book (the Goblet of Fire, the one with the Quidditch World Cup) has long descriptions of various kinds of tents. So boring to read about fancy tents!

Most anxiety-inducing scene

When Harry, Ron and Hermione impersonated Ministry of Magic employees and infiltrated the Ministry of Magic, my heart was pounding hard, and not in a good way. I don't know why. I guess I was afraid that they were exposed, but I don't know why it was so uncomfortable.

The robbing of Gringotts Wizarding Bank was a similar scene and also anxiety-inducing, but not as bad. Possibly because I had already endured the Ministry of Magic scene.

Both scenes are from the 7th book (the Deathly Hallows).

Silly things

Why did Harry, Ron and Hermione have to wear the locket Horcrux at all?! Would have been better to keep it safe but not wear it.
Why and how did Dolores Umbridge survive from the centaurs' wrath?
Harry and others survived many times from very tight spots at the very last minute/second. Typical, but maybe the survivals could have been less obvious or something like that.

My favorite character

Dumbledore because he had so wise things to say.

My buddy Oskari made an interesting general point: a great discussion in a book can be very short, but it's possible that the author has worked on the lines for a long time (several days or even weeks).

Best girl

I was rooting for Harry and Cho Chang; a shame it didn't work out.

I guess Ginny was OK too in the end. Props for her for the funniest joke:

Funniest joke

The Weasley twins were often funny, but the single funniest joke was in the 6th book (the Half-Blood Prince), chapter 25:

The fact that Harry Potter was going out with Ginny Weasley seemed to interest a great number of people, most of them girls, yet Harry found himself newly and happily impervious to gossip over the next few weeks. After all, it made a very nice change to be talked about because of something that was making him happier than he could remember being for a very long time, rather than because he had been involved in horrific scenes of Dark Magic.

'You'd think people had better things to gossip about,' said Ginny, as she sat on the common-room floor, leaning against Harry's legs and reading the Daily Prophet. 'Three Dementor attacks in a week, and all Romilda Vane does is ask me if it's true you've got a Hippogriff tattooed across your chest.'

Ron and Hermione both roared with laughter. Harry ignored them.

'What did you tell her?'

'I told her it's a Hungarian Horntail,' said Ginny, turning a page of the newspaper idly. 'Much more macho.'

'Thanks,' said Harry, grinning. 'And what did you tell her Ron's got?'

'A Pygmy Puff, but I didn't say where.'

Ron scowled as Hermione rolled around laughing.

Sweetest thing

Also from the 6th book, chapter 5:

With a sudden exclamation she pointed at the clock's face. Mr Weasley's hand had switched to travelling.

'He's coming!'

And sure enough, a moment later there was a knock on the back door. Mrs Weasley jumped up and hurried to it; with one hand on the doorknob and her face pressed against the wood she called softly, 'Arthur, is that you?'

'Yes,' came Mr Weasley's weary voice. 'But I would say that even if I were a Death Eater, dear. Ask the question!'

'Oh, honestly …'

'Molly!'

'All right, all right … what is your dearest ambition?'

'To find out how aeroplanes stay up.'

Mrs Weasley nodded and turned the doorknob, but apparently Mr Weasley was holding tight to it on the other side, because the door remained firmly shut.

'Molly! I've got to ask you your question first!'

'Arthur, really, this is just silly …'

'What do you like me to call you when we're alone together?'

Even by the dim light of the lantern Harry could tell that Mrs Weasley had turned bright red; he himself felt suddenly warm around the ears and neck, and hastily gulped soup, clattering his spoon as loudly as he could against the bowl.

'Mollywobbles,' whispered a mortified Mrs Weasley into the crack at the edge of the door.

'Correct,' said Mr Weasley. 'Now you can let me in.'

What's next?

Now that I have read the books, I'm going to watch the Harry Potter movies. I have never watched them, except maybe the first one in elementary school.

I'm also going to continue this new hobby of reading non-fiction books. No idea about the next books yet though.

Parsing data is nicer than only validating it

2023-06-13T12:00:00+03:00

Parsing encompasses validation, plus it can increase type-safety, plus it can transform the data to a better format. Parse, don't just validate.

Validation

Validating data means checking if the data matches a certain shape or certain rules.

For example, when using Joi, a JavaScript validation library, you write a schema and check if some data matches the schema:

import Joi from 'joi'

const userSchema = Joi.object({
  createdOn: Joi.string().required().isoDate(),
  userName: Joi.string().required().min(2),
  userType: Joi.number().required().integer().min(1).max(3),
})

const response = await fetch('https://example.com/api/users/123')
const data: unknown = await response.json()

const validationResult = userSchema.validate(data)

if (validationResult.error) {
  console.error(validationResult.error)
} else {
  const user = validationResult.value
  //    ^? any
}

Validation is essentially a binary check: the data either is valid or it isn't.

Well, you do get descriptive validation error messages when using Joi.

But if the validation passes, you are none the wiser about the validated data, at least in terms of type-safety: the original data variable has still type unknown, and validationResult.value has type any.

While validating data is certainly useful, the result can be made more useful by parsing the data instead of only validating it.

Parsing

Parsing means processing some input and converting it to a more precise output.

Parsing does validation plus more: parsing = validating data + increasing type-safety + transforming data.

Parsing encompasses validation

Validation is a more-or-less implicit step of parsing: if the input data isn't valid (from the parser's perspective), the parsing can fail.

Examples:

JSON.parse parses a JSON string, and throws if the input is not valid JSON.
Date.parse parses a date string and returns a timestamp, or NaN if the input is not a valid date.
- By the way, Date.parse is quite bad at parsing dates.

Parsing can increase type-safety

In the Joi example above, Joi could in theory be able to know the result type.

For example, if an object schema contains a property with the value of Joi.string(), Joi could infer the type of that property to be string | undefined.^[1]

But Joi doesn't do that. It throws away the potential type knowledge acquired during validation.

Example: Joi vs Zod

One alternative to Joi is Zod, a TypeScript validation library.

On the surface, Zod is used similarly to Joi, but the critical difference is that Zod can infer the return type of the schema:

-import Joi from 'joi'
-
-const userSchema = Joi.object({
-  createdOn: Joi.string().required().isoDate(),
-  userName: Joi.string().required().min(2),
-  userType: Joi.number().required().integer().min(1).max(3),
-})

+import { z } from 'zod'
+
+const userSchema = z.object({
+  createdOn: z.string().datetime(),
+  userName: z.string().min(2),
+  userType: z.number().int().min(1).max(3),
+})
+type User = z.infer<typeof userSchema>
+//   ^? {
+//        createdOn: string
+//        userName: string
+//        userType: number
+//      }

 const response = await fetch('https://example.com/api/users/123')
 const data: unknown = await response.json()

-const validationResult = userSchema.validate(data)
-
-if (validationResult.error) {
-  console.error(validationResult.error)
-} else {
-  const user = validationResult.value
-  //    ^? any
-}

+const parsingResult = userSchema.safeParse(data)
+
+if (parsingResult.success) {
+  const user = parsingResult.data
+  //    ^? User
+} else {
+  console.error(parsingResult.error)
+}

The user variable, which is the result of successful parsing, has now type User, which is inferred from the Zod schema.

What about `JSON.parse`?

I used JSON.parse as an example above when talking about the validation step of parsing. But hmm, why doesn't JSON.parse increase any type-safety...?

Maybe JSON.parse should be thought of as a very high-level parser. The TypeScript compiler can't have visibility on things happening at runtime, like what's passed to JSON.parse. If you want type-safety, you need to be more specific what you ask for, e.g. by using a type-aware runtime parser like Zod.

Parsing can transform data

So far I have talked only about validation and type-safety. What really separates parsing from validation (type-safe or not) is data transformations (or "data mapping" or "data reserialization").

Transforming data means modifying the data to a better format. Not by mutating the input data^[2], but by returning a different shape than what was passed to the parser.

What a "better format" means is up to you. For example, you can:

Trim strings.
Convert values to different types, e.g. numerical strings to numbers, or date strings to Date objects.
Set default values for optional or nullable fields.
Transform object keys from PascalCase or snake_case (neither are JavaScript-y) to camelCase.
Rename object keys from a foreign language to English.
Rename object keys to words that are already used in your code base to avoid having multiple words for the same thing (data coherency); e.g. userId vs personId.
Compute/derive values from other values; e.g. construct fullName by combining firstName and lastName.
Simplify object structures, e.g. change Array<{ key: string; value: number }> to Record<string, number>.
Convert comma-separated strings to arrays, e.g. "1,2,3" to [1, 2, 3].
Convert number unions to string unions (see the userSchema example below).

The point is to modify the data so that it looks like you'd want it to look.

It's not fun to work with messy data, but if you transform the data to a nicer format right after receiving it:

You need to deal with the messy data only once.
The transformations are centralized to one place instead of being scattered around everywhere.
You can write business logic against the ideally shaped data (as opposed to writing business logic against "someone else's data").

Example: `userSchema`

In the Joi vs Zod example above, userSchema and the inferred type look like this:

import { z } from 'zod'

const userSchema = z.object({
  createdOn: z.string().datetime(),
  userName: z.string().min(2),
  userType: z.number().int().min(1).max(3),
})
type User = z.infer<typeof userSchema>
//   ^? {
//        createdOn: string
//        userName: string
//        userType: number
//      }

The User type is quite messy. If the data is coming from an external API, the data itself can't be changed... but the parsed data can be improved by:

Converting the createdOn string to a Date object, so you don't need to repeatedly do a conversion from a date string to a Date object. Date objects are nicer to work with than date strings.
Converting the userType number to a string union of 'admin' | 'moderator' | 'user'. A string union like that is much clearer, plus then you don't need to repeatedly do a conversion from a number to a string.
Renaming userName (uppercase N) to username (lowercase n) because "username" is often spelled as a single word.
Renaming userType to role because userType sounds redundant, and type would sound a bit too generic.

Like so:

type User = {
  createdOn: Date
  role: 'admin' | 'moderator' | 'user'
  username: string
}

function parseUser(data: unknown): User | ParseError {
  // Validate and transform `data`
}

How you transform the data is an implementation detail. Zod has means for transforming data (another blog post coming later); you could also transform the data manually.

Fuzzy terminology

What is parsing? What is validation?

Above I said that parsing = validating data + increasing type-safety + transforming data. This is based on other sources (see further resources below).

If the data is not transformed, I guess it could still be called just validation; be it "type-ignorant" validation (think of Joi) or type-aware validation (think of Zod).

In fact, Joi and Zod are both called validation libraries even though they also support data transformations. But that's also a bit confusing.

Practical guidelines

If your intention is to transform the data, make sure you call it parsing. Calling it validation would be confusing.
If your intention is to do only validation:
- Call it validation or parsing; choose whichever term and stick to it (be consistent). Calling it validation would distinguish it from parsing that transforms data, though I don't know if that would valuable.
- If you call it validation, make sure you don't transform the data (accidentally or deliberately); it would be confusing.

Further resources

My other blog posts on this topic:

Date objects are nicer to work with than date strings

More coming later; I like this topic.

Main inspiration

This blog post is largely inspired by the Parse, don't validate blog post by Alexis King. Her post has examples in Haskell, which I'm not familiar with, but the post was still easy to read.

These snippets resonated with me the most:

Validation vs parsing:

[I]n my mind, the difference between validation and parsing lies almost entirely in how information is preserved. [...] Both of [them] check the same thing, but [parsing] gives the caller access to the information it learned, while [validating] just throws it away.
What is parsing:

Consider: what is a parser? Really, a parser is just a function that consumes less-structured input and produces more-structured output. [...] Under this flexible definition, parsers are an incredibly powerful tool: they allow discharging checks on input up-front, right on the boundary between a program and the outside world, and once those checks have been performed, they never need to be checked again!
Beware "shotgun parsing":

Ad-hoc validation leads to a phenomenon that the language-theoretic security field calls shotgun parsing. [...]

Shotgun parsing is a programming antipattern whereby parsing and input-validating code is mixed with and spread across processing code [...].

[...] In other words, a program that does not parse all of its input up front runs the risk of acting upon a valid portion of the input, discovering a different portion is invalid, and suddenly needing to roll back whatever modifications it already executed in order to maintain consistency. Sometimes this is possible – such as rolling back a transaction in an RDBMS – but in general it may not be.

It may not be immediately apparent what shotgun parsing has to do with validation – after all, if you do all your validation up front, you mitigate the risk of shotgun parsing. The problem is that validation-based approaches make it extremely difficult or impossible to determine if everything was actually validated up front or if some of those so-called "impossible" cases might actually happen. The entire program must assume that raising an exception anywhere is not only possible, it's regularly necessary.

Parsing avoids this problem by stratifying the program into two phases – parsing and execution – where failure due to invalid input can only happen in the first phase. The set of remaining failure modes during execution is minimal by comparison, and they can be handled with the tender care they require.
Guidelines for parsing – the blog post contains lots of great points; these few resonated with me the most:
- Get your data into the most precise representation you need as quickly as you can. Ideally, this should happen at the boundary of your system, before any of the data is acted upon.
  
  If one particular code branch eventually requires a more precise representation of a piece of data, parse the data into the more precise representation as soon as the branch is selected.
- [W]rite functions on the data representation you wish you had, not the data representation you are given. The design process then becomes an exercise in bridging the gap, often by working from both ends until they meet somewhere in the middle.
- Don't be afraid to parse data in multiple passes. Avoiding shotgun parsing just means you shouldn't act on the input data before it's fully parsed, not that you can't use some of the input data to decide how to parse other input data. Plenty of useful parsers are context-sensitive.

After reading Alexis King's blog post, I wasn't sure of the relationship between parsing and validation. These Hacker News (HN) comments were helpful in realizing that "parse, don't validate" doesn't mean "parse data instead of validating it"; it means "parse data instead of only validating it":

An HN comment by lexi-labmda (Alexis King):

The idea really is that parsing subsumes validation. If you're parsing, you don't have to validate, because validation is a natural side-effect of the parsing process. And indeed, I think that's the very thesis of the blog post: parsing is validation, just without throwing away all the information you learned once you've finished!
An excerpt from an HN comment by danharaj:

The point is not that "parsing" and "validating" are distinct concepts, but that they're two different points of view on the same problem.
An HN comment by b3morales:

You seem to suggest that it's possible to parse without validating, which I'm not sure I follow. Surely validation is just one of the phases or steps of parsing?
An HN comment by nsajko:

The point is that validation is (or should/can be) a byproduct of parsing. I.e., you shouldn't "do both", rather the validation should be encompassed by the parsing, as much as it makes sense.
An excerpt from an HN comment by friendzis:

Validation happens during parsing implicitly: parser will either return a valid object or throw an error, but parsing has an added benefit that the end result is a datum of a known datatype.

Other sources

Other helpful things I have stumbled upon, with a few grammatical fixes:

An excerpt from a Lobsters comment by kevincox:

When accepting untrusted input you should not validate it, and accept or reject the user input. You should instead parse and reserialize the input. This ensures that you will only have data that you wrote yourself. It is also natural to throw away unknown fields and simply any odd formatting.
An excerpt from a Lobsters comment by jbert:

Is [the "Parse, don't validate" idea] fundamentally the same idea as "make invalid states unrepresentable"?

I.e. don't have a corner case of your type where you could have a value which isn't valid (like the empty list), instead tighten your type so that every possible value of the type is valid.

Looked at this way, any time you have a gap (where your type is too loose and allows invalid states) the consumer of the value of that type needs to check them again. This burden is felt everywhere the type is used.

If you do the check to ensure you haven't fallen into the gap, take the opportunity to tighten the type to get rid of the gap. I.e. make the invalid state unrepresentable.
An excerpt from a Lobsters comment by Axman6:

As a Haskell developer, I've spent a lot of time looking at unit test suites for other languages and thinking "why are you testing that? your type system should make that impossible", and coming to the realisation that for many languages, their test suite is their type system – but it is an incomplete, sometimes buggy one limited by what the developer was able to predict could go wrong.

I've always tried to make programs where only valid business logic is possible, and doing this relies heavily on the use of sum types to be precise about what is allowable – I was talking earlier today to someone on IRC about the difference between validating (a.k.a writing code that works with [booleans] to gate progress to other code) and parsing (writing code that produces valid values – perfectly summed up in Alexis King's Parse, don't validate).

At a previous job, we did this religiously, data coming into the program was parsed (in this case from SQS queues), such that we knew in the rest of the system that all our preconditions had been satisfied, and only valid data was allowed within the inner shell of the app. [...]

The rest of the program was basically implemented in a way that it was very difficult to write incorrect code, all alternatives were represented as subtypes [...].
An excerpt from Parse, don't validate, incoming data in TypeScript by Elias Nygren:

The "parse, don't validate" mantra is all about parsing incoming data to a specific type, or failing in a controlled manner if the parsing fails. It's about using trusted, safe and typed data structures inside your code and making sure all incoming data is handled at the very edges of your programs. Don't pass incoming data deep into your code, parse it right away and fail fast if needed.

Parsing is better than just validation because parsing forces you to explicitly handle all incoming data. It gives you a type safe way [of] working and makes it hard to pass around malicious content around your applications and data stores. However, it is true that parsing often includes validating the data.
Excerpts from Can types replace validation? by Mark Seemann:
- The naive take on validation is to answer the question: Is that data valid or invalid? Notice the binary nature of the question. It's either-or.
- This changes focus on validation. No longer is validation a true/false question. Validation is a function from less-structured data to more-structured data. Parse, don't validate.
  - The "This" at the beginning refers to "applicative validation" (I don't know what that is), but I think it would very well refer to parsing as well (i.e. "Parsing changes focus on validation"); the quote would still make sense.
An excerpt from Shotgun Semantics by Donny Winston:

Developers often resort to shotgun parsing: scattering data checks and fallback values in various places throughout the system's main logic.

The habit of scattering parser-like behaviour throughout an application's code and the resulting inconsistencies in data handling can often lead not just to annoying complications and bugs, but also security vulnerabilities.
An excerpt from a deleted user's comment on an /r/typescript post Has your team adopted TypeScript? How is it going?:

I joined a team 6 months ago that had recently adopted TypeScript to a fairly new (2 years old) project. [...]

People didn't really know why they were using it. They would create interfaces for objects coming over APIs (good), but would make them have slightly differently named fields, like mainId would be named main_id in the interface (bad). This resulted in pointless chunks of code to "convert" the API object to the front-end interface.
- A reply by monnef:
  
  In some languages (like Haskell) this is the recommended approach – separate types for API and rest of the application. When the API changes, you don't have to change all code which works with the type, just the convert functions. Even in TS, I really don't like reusing API types (generated in our case) for forms and a few other places, because more often than not the types aren't actually the same (e.g. null vs undefined, number vs string and so on).
- Another reply by pm_me_ur_happy_traiI:
  
  I actually encourage my team to do exactly this. Back-end APIs are optimized to be communicated over the wire. They need to be turned into something that works with front-end conventions and suits the needs of our app.
  
  We build our front-ends using data structures that make sense to the front-end, and there's usually a function to turn the back-end API response into that. The added upside is that if the back-end changes, we just need to fix the one function as opposed to renaming properties all over our code base.
An excerpt from Parsing REST API Responses in TypeScript using Zod by Matt Newhall:
The ["parse, don't validate"] concept boils down to the underlying assumption in validation that a type can have valid and invalid instances. Let's take an example of validating a type, T:
```
validateType: (T) => boolean
```
In this case, validateType takes a type T and then by evaluating it returns a boolean stating if the incoming object was a valid object of type T or not. However, this means that invalid instances of T can exist. Alternatively, using parsing:
```
parseType: (unknown) => T | Error
```
We can take some data of an unknown type, and check if this matches what is expected of type T. From this, we can output a guaranteed type T, or handle the error in the event that it is not. This makes the schema checking system more TypeScript-esque, making it more akin to a type guard than blindly assuming a variable's type.
- An interesting point that I hadn't considered: "[Validating instead of parsing] means that invalid instances of T can exist." On the other hand, shouldn't validateType take an unknown param, not a T param? Hmm...
An excerpt from Pushing Side Effects to the Side by Eric Weise:
Functional programming provides a treasure trove of useful patterns, one of which is pushing side effects to the edges of your application. Side effects are functions that have non-deterministic behavior. Examples include making an HTTP call or persisting data to the database. [...] By isolating these types of calls, we can more easily test our code. [...]

How many methods could you turn into simple pure function calls simply by removing side effect calls such as repositories from your business logic? Most projects I have worked on just sprinkle database calls throughout service layer.

In general the pattern I try to follow is;
- Retrieve all the data necessary to perform the business logic (side effect code).
- Perform the business logic using in-memory data (pure functions).
- Persist changes to the database (side effect code).
These three steps can't be followed every time but when they can, the code will be much easier to test.
- I think "pushing side effects to the side" doesn't benefit only testing, so "the code will be much easier to test" could also read "the code will be much clearer overall."
Slogan of the parse-dont-validate TypeScript library:

Validating data acts as a gatekeeper, parsing them into meaningful data types adds valuable information to raw data.
A tweet by Mateusz Kwaśniewski: Parse, don't validate – TypeScript edition
- Features Joi and Zod, which inspired me to use them in this blog post.
A GitHub discussion under the Zod project: Confusing terms – parse vs validate

Changelog

2023-06-13: Blog post published
2023-06-25: Added links to today's blog post Date objects are nicer to work with than date strings

Footnotes

The corresponding type of Joi.string() would be string | undefined, because in Joi, all values are optional by default. I find it a bit confusing. The type of Joi.string().required() would be string. ↩
I wonder if there's ever a good reason for a parser to mutate the input data. ↩

Auto-converting EPUB files to AZW3 instead of MOBI in Calibre

2023-04-29T12:00:00+03:00

MOBI is an old e-book format. AZW3 is a newer and apparently better format; for instance, it supports embedded fonts. Here's how to configure Calibre to prefer the better format.

Global settings
1. In Calibre, go to Preferences → Behavior
2. Change "Preferred output format" from MOBI to AZW3
Device settings might override global settings, so check device settings too
1. Plug in your device (via USB)
2. In Calibre, select Device → Configure this device
3. Under "Select available formats and their order for this device," move azw3 to the top
  - My old order was this:
    1. azw
    2. mobi
    3. azw3
    4. ...
  - So I moved azw3 to the top:
    1. azw3
    2. azw
    3. mobi
    4. ...

De-ACSM'ing and de-DRM'ing e-books for fun (but not profit)

2023-04-28T12:00:00+03:00

A reminder for myself how to make library e-books pleasant to use with the help of Calibre and two Calibre plugins.

Problem

My local library provides many e-books for free, which is great, but actually getting those e-books to my Kindle Paperwhite is a hassle:

Download an EPUB file (so the button says on the library site) – whoops, it's actually an ACSM file.
Download Adobe Digital Editions (ADE) software to open the ACSM file – whoops, ADE requires an Adobe account.
Create an Adobe account.
Get an EPUB file from ADE.
Upload the EPUB file to Kindle Paperwhite – whoops, Kindle doesn't support EPUB files.
Convert the EPUB file to a Kindle-supported format (e.g. MOBI) – whoops, the EPUB file is DRM-protected so it's not that simple.
Remove the DRM protection by using a shady website, probably risking leaking your personal info (likely stored in the DRM-protected EPUB file).
Finally upload the DRM-free, Kindle-compatible file to Kindle.

I don't actually know the exact process because I have never done it the "official way." Just too complicated, too much work, too annoying.

Solution

Initial setup

Needs to be done only once.

Download and install Calibre (e-book management software).
Download and install DeDRM_tools plugin for Calibre.
- This plugin will automatically remove DRM protection from EPUB files that you drag-and-drop to Calibre.
- noDRM's fork (linked to above) is up-to-date; the original is not.
- Be sure to install this before the next plugin, or you might need to do one extra step manually when configuring the next plugin.
Download, install and configure ACSM Input plugin for Calibre.
- This plugin will automatically convert ACSM files that you drag-and-drop to Calibre into EPUB files
  - No need for ADE (Adobe Digital Editions software).
  - No need for an Adobe account because you can create an anonymous authorization in the plugin's settings.
    - Make sure to back up the authorization data, just in case.
(Optional: Configure Calibre to auto-convert EPUB files to AZW3 instead of MOBI.)

E-book to Kindle

Download an ACSM file from library site.
Drag-and-drop the ACSM file to Calibre.
Plug in Kindle to computer (via USB).
Select the book in Calibre and click "Send to device."
Eject Kindle.
Go read and enjoy the book!

All steps except the 2nd one are fluff, so this is actually a one-step process (just drag-and-drop to Calibre). Nice and easy.

Sending (duplicate) emails to email aliases can be tricky

2023-04-21T12:00:00+03:00

If you send a single email to a bunch of email addresses, and some of the addresses are aliases, i.e. they point to the same email inbox, chances are high that only one copy of the email is delivered to that inbox.

Example problem

I had five test users and one email alias per test user; e.g.:
- Test user 1: foo@example.com
- Test user 2: foo+test-user-2@example.com
- Test user 3: foo+test-user-3@example.com
- Test user 4: custom-alias-1@example.com
- Test user 5: custom-alias-2@example.com
- All five email addresses pointed to the same email inbox: foo@example.com
I sent a single email to those five addresses.
I expected to receive five copies of the email to my email inbox, but I received only one copy.
- In some test runs I sometimes received two or maybe even three emails, but never all five.

Test users vs real users

In my case the users were test users, making testing email delivery difficult because only some test users received the emails.

But the problem would affect real users too. Example:

Somebody has registered to a service multiple times, each time using a different email alias.
The service sends an email to all its users.
That somebody should receive as many emails as they have users, but (if this problem exists in that service) they might get only one email.

Tangent: SendGrid

I used the sendMultiple() method of the SendGrid Node.js API, but that's tangential:

This isn't a JavaScript-specific problem.
This isn't a SendGrid-specific problem.
This is a general problem of delivering multiple copies of an email to multiple email aliases.
- The same problem would happen when sending a single email to multiple email aliases non-programmatically, e.g. directly from Gmail.

Still, I wanted to mention this because at first I thought that the problem was in SendGrid.

SendGrid's Activity Feed displayed the "Delivered" status for all emails, meaning that the receiving mail servers had successfully received the emails. Indeed, the problem wasn't that SendGrid failed to send all the emails (it didn't fail); the problem was that the receiving mail servers failed to deliver the duplicate emails to the inboxes.

The root cause: identical `Message-Id`s

Every email has a unique Message-Id.
- I asked Fastmail Support "Is the Message-Id always created/determined by the sender?" and they replied:
  
  Yes, that's correct. However, if the sender doesn't specify one, due to a bug, we will create one during email delivery.
All emails sent in a single batch share the same Message-Id.
Most mail servers silently discard duplicate emails (based on Message-Id). (But there's a precondition; keep on reading.)
- Based on my testing, this is true for at least these mail servers/providers:
  - Exchange / Outlook
  - Fastmail
  - Gmail / Google Workspace (formerly G Suite)
- For example, Fastmail's Why messages bounce back page states the following:
  
  Most messages have a unique identifier called the message ID. When a message arrives at an account, the message ID is noted. If a second message with the same ID arrives, it is ignored and silently discarded. This is used to stop infinite mail loops overloading your account or our system. However, it can result in odd behavior when the same message arrives from different sources, as only the first one will actually be delivered.
  
  Note the last sentence:
  
  However, it can result in odd behavior when the same message arrives from different sources, as only the first one will actually be delivered.
  
  Replacing "from different sources" with "to multiple email aliases" would keep the sentence correct and describe my problem better:
  
  However, it can result in odd behavior when the same message arrives to multiple email aliases, as only the first one will actually be delivered.

Solution

The solution is to send the emails sequentially (one at a time), e.g. at 1-second intervals.

One way would be to make one API request per recipient, but that would be slow and inefficient because there would be as many API requests as recipients. (Then each email would probably have unique Message-Id, which alone would fix the problem.)

Eventually I found a better way (I'm using SendGrid as mentioned above): specifying different sendAt values for each recipient makes SendGrid send the emails at different times, but allows making as few API requests as possible.

Curiously, the Message-Id is still the same in every email, but this still fixes the problem! That's because the emails don't arrive simultaneously. In other words (this is the precondition mentioned above):

Most mail servers seem to not discard duplicate emails (based on Message-Id) if the emails arrive at different times (not simultaneously).

I have successfully tested this with:

Exchange / Outlook
Fastmail
Gmail / Google Workspace (formerly G Suite)

Fastmail Support confirmed this for their part:

So it seems we ignore duplicate emails delivered in a very short period (e.g. within a second). These emails were delivered within a second apart which is why they were not filtered as duplicates. This is expected behavior.

Code

Using SendGrid:

const emails = [
  'foo@example.com',
  'foo+test-user-2@example.com',
  'foo+test-user-3@example.com',
  'custom-alias-1@example.com',
  'custom-alias-2@example.com',
]

// SendGrid expects a UNIX timestamp in seconds
const currentTimeInMilliSeconds = Date.now()
const currentTimeInSeconds = Math.ceil(currentTimeInMilliSeconds / 1000)

sendGrid.sendMultiple({
  personalizations: emails.map((email, index) => {
    // Send the emails at 1-second intervals
    // to ensure that delivery to email aliases works too.
    // Mail servers silently discard duplicate emails
    // that arrive to the same inbox at the same time,
    // so multiple emails going to the same email inbox (via email aliases)
    // need to be sent at different times.
    // Also add a few seconds just to be safe,
    // i.e. to avoid sending the first few emails simultaneously.
    // More info: https://mtsknn.fi/blog/tricky-email-aliases/
    const sendAt = currentTimeInSeconds + index + 5

    return {
      to: email,
      sendAt,
    }
  }),
  subject: 'Test email',
  html: '<p>Email body</p>',
})

Caveat

This fix/hack will make some recipients receive the email after a small delay.

If you have 1,000 recipients and send the emails at 1-second intervals, the last recipient will receive the email after about 1,000 seconds ≈ 17 minutes. In my case that's totally OK.

If that's too long, you could send the emails in smaller batches.

The maximum is anyway 1,000 recipients per one SendGrid API request. From SendGrid's Personalizations page:

You may not include more than 1000 personalizations per API request. If you need to include more than 1000 personalizations, please divide these across multiple API requests.

Tangent: −24 hours

I stated two things above:

Most mail servers silently discard duplicate emails (based on Message-Id).
Most mail servers seem to not discard duplicate emails (based on Message-Id) if the emails arrive at different times (not simultaneously).

As a test, I scheduled the emails to be sent at 1-second intervals like before, but also 24 hours in the past. Like this:



   sendGrid.sendMultiple({
  personalizations: emails.map((email, index) => {
    // ⚠️ Example, don't actually do this
    const twentyFourHoursInSeconds = 60 * 60 * 24
    const sendAt = currentTimeInSeconds + index - twentyFourHoursInSeconds

    return {
      sendAt,
      to: email,
    }
  }),
  // ...
})

I successfully received all emails – confusing!

I asked about this from Fastmail Support:

The timestamps in the Date headers are a second apart like expected; but the timestamps in the Received headers are exactly the same.

Doesn't this mean that SendGrid sent the five emails at the same time? I would expect SendGrid to do that because the Date headers were 24 hours in the past, but I can't know for sure.

And don't the identical Received timestamps also mean that you received all emails at the same time?

Their reply:

It's based on the received time at our end. Looking at the logs I can see that these emails came in almost within a second.

2022-11-06T23:30:33.991668-05:00 mx2 (info) postfix-mx/cleanup[630908]: F1DBE6A017A: message-id=<a7ZrAF9NQbeVa12gUVIbRd@geopod-ismtpd-3-1>

2022-11-06T23:30:33.992920-05:00 mx3 (info) postfix-mx/cleanup[725605]: F22DB1960153: message-id=<a7ZrAF9NQbeVa12gUVIbRd@geopod-ismtpd-3-1>

2022-11-06T23:30:34.039558-05:00 mx1 (info) postfix-mx/cleanup[774312]: 097E023C00C6: message-id=<a7ZrAF9NQbeVa12gUVIbRd@geopod-ismtpd-3-1>

2022-11-06T23:30:34.066426-05:00 mx3 (info) postfix-mx/cleanup[725548]: 100301960158: message-id=<a7ZrAF9NQbeVa12gUVIbRd@geopod-ismtpd-3-1>

2022-11-06T23:30:34.291125-05:00 mx1 (info) postfix-mx/cleanup[774312]: 46EA223C0074: message-id=<a7ZrAF9NQbeVa12gUVIbRd@geopod-ismtpd-3-1>

So, they were not discarded as duplicates.

So, SendGrid sent the emails at slightly different times even though they were scheduled to be sent 24 hours ago. Or at least Fastmail received them at slightly different times.

I wouldn't rely on this behavior, so I don't recommend this approach (scheduling the emails to be sent in the past), but this is interesting to know nonetheless.

Non-solutions

I tried these two things that didn't work:

Custom headers:

sendgrid.sendMultiple({
  personalizations: emails.map((email, index) => ({
    to: email,
    headers: { 'X-EmailBatchId': `${index + 1}` },
  })),
})

Custom subject per recipient:

sendgrid.sendMultiple({
  personalizations: emails.map((email, index) => ({
    to: email,

    subject: `Email ${index + 1}`,
    // or
    dynamicTemplateData: { subject: `Email ${index + 1}` },
  })),
})

Rant: SendGrid Support was meh

SendGrid Support couldn't help me solve this problem.

That's kind of okay because this is quite an obscure thing and not specific to SendGrid; on the other hand, I'd expect an email delivery service provider to have great knowledge about even the most obscure things related to delivering emails.

What's worse is that one of their "Senior Technical Support Engineers" even said something factually incorrect:

I believe the root of the issue here is that multiple recipients require multiple requests, unless you're including them as CC or BCC. At some point in 2021, our system began no longer accepting multiple "TO" recipients within one request. Whereas previously, you could have 1 request with multiple recipients listed in the TO portion. Now, to send 1 email to 10 recipients individually, this requires 10 individual requests.

I suggest that you and your team look into adjusting your system's workflow so that such situations result in multiple requests, rather than using "sendmultiple" within 1 request.

I don't understand that reply as it's simply false that you can't send an email to multiple recipients with a single request.

The SendGrid docs have a section Sending the same email to multiple recipients. At the top of the page, it's mentioned that you can send an email to max 1,000 recipients with a single request. That's much better and faster than doing 1,000 individual requests.

Plus I had already succeeded at sending an email to multiple recipients with a single request; I was just having problems with email aliases / duplicate emails.

Praise: Fastmail Support is great

Fastmail Support was very helpful in helping me solve and understand the problem.

They have been helpful in the past too, when I have had email problems.

Harry Potter, the Mirror of Erised, and mindless internet surfing

2023-04-14T12:00:00+03:00

Mindlessly surfing the internet is like staring at the Mirror of Erised from the Harry Potter books. (Minor Harry Potter spoilers ahead.)

Mindless surfing vs the Mirror of Erised

My bro shared me a Reddit post on /r/nosurf the other day.

Here's the full post (with a few typos fixed):

Mindless surfing is like the Mirror of Erised in Harry Potter

For those of you who haven't read Harry Potter, the Mirror of Erised is a mirror which shows the deepest desires of a person. In the story, Harry finds the mirror and sees his parents in it. He keeps returning every day until Dumbledore gently tells him to stop doing so.

This mirror will give us neither knowledge or truth. Men have wasted away before it, entranced by what they have seen, or been driven mad, not knowing if what it shows is real or even possible. It does not do well to dwell on dreams and forget to live.

This is a great parallel to mindless internet surfing. We watch our deepest desires on the internet like being rich, falling in love, living a certain lifestyle or even being in another country. I've spent a lot of time browsing nice apartment pics, vlogs, or even street view of nice cities where I wanna live, not because of curiosity or exploration but because of a desire to see my dream. This is actually preventing me from living fully and actually working to achieve my dreams in the first place.

I just found it interesting how similar the two of these are.

Longer Harry Potter quote

I recently started reading the Harry Potter books for the first time.

The first book, Harry Potter and the Philosopher's Stone, has 332 pages (Bloomsbury, 2014 edition), but I read it in just 5 days. It was that good!

The first book also introduces the Mirror of Erised. From pages 229–230:

'Let me explain. The happiest man on earth would be able to use the Mirror of Erised like a normal mirror, that is, he would look into it and see himself exactly as he is. Does that help?'

Harry thought. Then he said slowly, 'It shows us what we want … whatever we want …'

'Yes and no', said Dumbledore quietly. 'It shows us nothing more or less than the deepest, most desperate desire of our hearts. You, who have never known your family, see them standing around you. Ronald Weasley, who has always been overshadowed by his brothers, sees himself standing alone, the best of all of them. However, this mirror will give us neither knowledge or truth. Men have wasted away before it, entranced by what they have seen, or been driven mad, not knowing if what it shows is real or even possible.

'The Mirror will be moved to a new home tomorrow, Harry, and I ask you not to go looking for it again. If you ever do run across it, you will now be prepared. It does not do to dwell on dreams and forget to live, remember that. Now, why don't you put that admirable Cloak back on and get off to bed?'

Harry stood up.

'Sir – Professor Dumbledore? Can I ask you something?'

'Obviously, you've just done so,' Dumbledore smiled. 'You may ask me one more thing, however.'

'What do you see when you look in the Mirror?'

'I? I see myself holding a pair of thick, woollen socks.'

Harry stared.

'One can never have enough socks,' said Dumbledore. 'Another Christmas has come and gone and I didn't get a single pair. People will insist on giving me books.'

It was only when he was back in bed that it struck Harry that Dumbledore might not have been quite truthful. But then, he thought, as he shoved Scabbers off his pillow, it had been quite a personal question.

Video notes: Agile Product Ownership in a Nutshell

2023-04-11T12:00:00+03:00

This 16-minute video by Henrik Kniberg is a great overview of the agile software development process, but also contains lots of smaller great insights.

The video

Watch Agile Product Ownership in a Nutshell (15:51) on YouTube.

I found the video via Critter's blog post Pull methodology, flow time, and WIP limits: visualized.

Top 3 moments

The 16-minute video is packed with great insights. I guess different things would stand out when rewatching the video later; this time these three things resonated with me the most.

Knowledge focus vs customer value focus (8:12–9:16)

Knowledge can be seen as the opposite of risk, so when uncertainty is high, our focus is [on] knowledge acquisition; we focus on things like UI prototypes and technical spikes/experiments. Maybe not too exciting for the customers [(stakeholders)], but still valuable because we are reducing risk. From a customer value perspective, the curve [of customer value (y-axis) and time (x-axis)] looks [flat] in the beginning.

As uncertainty is reduced, we gradually focus more and more on customer value; we know what we are going to build and how, so just do it. And by doing the highest-value [user] stories first, we get this nice steep value curve.

And then gradually the value curve starts flattening out. We have built the most important stuff, and now we are just adding the bonus features; the toppings of an ice cream. This is a nice place to be [in] because at any point [the Product Owner] and the team may decide to "trim the tail," to cut right here and move on to another more important project. Or maybe start a whole new feature area within the same product. That is business agility.

So when I talk about value [of user stories], I actually mean knowledge value + customer value. And we need to continuously find the trade-off between these two.

Correct vs good vs fast (9:39–10:42)

Should we focus on:

building the right thing

or building the thing right

or perhaps building it fast?

Ideally we want all three, but it's hard to find the balance.

[...]

Product owners tend to focus on building the right thing.

Development teams tend to focus on building the thing right.

Scrum masters or agile coaches tend to focus on shortening the feedback loop.

Speed is actually worth emphasizing because a short feedback loop will accelerate learning, so you'll more quickly learn what the right thing is and how to build it right.

However, all three aspects are important, so keep trying to find the balance.

Reducing scope vs extending time (13:15–14:00)

Suppose a stakeholder says: "Can we get these features by Christmas?" Now, that's a fixed time, fixed scope question.

Looking at trend lines, [the Product Owner] says: "Nope, sorry, ain't gonna happen," followed by, "here's how much we can get done by Christmas" or "here's how much more time we would need to get everything done."

It's generally better to reduce scope than to extend time, because if we reduce scope first, we still have the option to extend the time later and add the rest of the [user] stories.

Vice versa doesn't work because, darn it, we can't turn the clock backwards. [...]

So, [the Product Owner] puts it this way: "We could deliver something [soon] and the rest later, or we could deliver nothing [soon] and the rest later; which do you prefer?"

Book notes: Atomic Habits

2023-04-07T12:00:00+03:00

Tiny good things accumulate into great things. Tiny bad things accumulate into horrible things. This book tells you how to do more of those good things and less of those bad things.

About the book

People do things out of habit all the time.

Atomic Habits tells you how to make good habits easy and effortless, and how to make bad habits difficult and unattractive.

Thoughts

I read this book in January 2023. This was the first book I read in a very long time (a few years maybe).

The book was great:

Interesting topic
Well written; not boring at all
Many examples and anecdotes
A good balance between theory and practical tips & tricks

I found the book to be a nice general overview of human behavior: why people do certain things (good or bad) and why people don't do certain things (good or bad). So the book isn't just about productivity.

Notes

These are the things that resonated with me the most.

I wrote these originally on post-it notes in January 2023. Now, almost 3 months later, I'm having difficulties understanding some of the post-its, so the notes below are partly confusing. 🙈

How to do a habit more

Make it:

Obvious
Attractive
Easy
Satisfying

(Note to self: examples would be nice...)

How to ditch a bad habit

Make it:

Invisible (out of sight, out of mind)
Unattractive
Difficult
Unsatisfying

The 1% rule

Getting 1% better at something (or improving something by 1%) every day for one year yields great dividends in the long run
- 1.01³⁶⁵ ≈ 37.78
- Progress is slow but exponential/compounding
Conversely: regressing 1% at something every day for one year destroys the original value
- 0.99³⁶⁵ ≈ 0.0255
- So bad habits, stress and negative thoughts compound too!

Focus on processes, not goals

Focusing on a process is living in the moment; focusing on a goal is living in the future
Enjoy what you are doing; treat goals as a bonus
Achieving a goal is a momentary change
- Focusing on a goal can feel discouraging and like nothing is happening
- Missing a goal can feel like failure even if you have made good progress
- Example: Melting an ice cube
  - Rising the temperature from −30 °C to −1 °C looks like it doesn't do anything to an ice cube
  - Finally rising the temperature one or two degrees more melts the ice cube
  - The "trick" wasn't to rise the temperature only one or two degrees – it was to rise it all those 30+ degrees
- Example: Stonemasonry
  - A stonemason might hit the same spot 99 times, and it might look the hitting doesn't do anything
  - Finally the 100th hit makes the rock to chip off
  - All 100 hits were required even though 99% of them looked like they did nothing

1 task per day

Do one task per day, and you have done 365 tasks at the end of the year.
Otherwise you'll have 365+ pending tasks at the end of the year!

(I don't remember if the book had this kind of example or whether this was my own though based on something else. 🤔)

Become your ideal person

Decide who you want to be(come).
Prove it to yourself with small wins.

→ It's not about the goals but the system/process and identities.

Habits shape identities.
Identities cause habits.
Family & friends, tribe (neighborhood, nationality etc.) and the powerful

(I'm not sure what the notes in this chapter mean. 🫣 Shitty notes.)

Habits free up mental juice

Build habits to free up mental space (conscious brain juice) for other things.
For example: it's great to not have to always think about what to eat or when to exercise etc.

Pointing-and-Calling

Pointing at things makes your thoughts more conscious.
Saying things aloud makes your thoughts more conscious.
Combine pointing and saying aloud for the best effect ("Pointing-and-Calling").

Aside: baseball bats

In the intro chapter, James Clear tells how he was once hit in the face by a flying baseball bat.

His skull fractured and brains swelled etc., causing him to almost die.

That's completely different what some movies and TV series portray. Sometimes a guy is hit dozens of times with a (metallic!) baseball bat, even to the head, and all it does is make the guy groan a little. Ridiculous. (I had been shaking my head at this stupidity before reading the book; James's anecdote just confirmed my hunch that even a single hit could be fatal.)

Verdict

Atomic Habits is a great book, go read it!

From a super ultrawide monitor to a regular 16:9 monitor

2023-03-23T12:00:00+03:00

After 2.5 years of using a 120 cm wide super ultrawide computer monitor with a 32:9 aspect ratio, I'm back to a boring 64 cm wide 16:9 monitor. The smaller monitor now feels better in every regard.

Super ultrawide

I bought Samsung CRG9 in July 2020 for 950 € (sale price). Some specs:

49", 120 cm wide
5120×1440 pixels (Dual QHD)
120 Hz
Curved VA panel

Nice: it's wide

I wanted to try a super ultrawide monitor because the wider the screen, the more windows can fit on it side by side.

I thought that would be useful, and it kind of is. Having VS Code, Terminal and Firefox side by side can be nifty when coding web apps.

Drawback: distractions

On the other hand, having more than one thing open at the same time can be distracting. At least subconsciously.

I hadn't considered this until I read Alexey Guzey's blog post My 2022 self (I don't know them) was very wrong about meditation, huge monitors, and... sleep.

In chapter 4, Alexey tells that he changed from his 4-monitor setup (49" + 34" + 24" + 16") to using just his 16" MacBook.

I'm actually distracted by [having] my task list, calendar, notes, etc. always visible.

[Now] I work on my 16" MacBook and do one thing at a time.

So: one or max two windows open at a time = more focus.

Other drawbacks

The super ultrawide monitor is annoyingly wide, so I had to turn my head quite a bit to look at the sides.
The monitor is very heavy and thus difficult to move around.
My microphone blocked about a third of the monitor when in voice calls.

If you play video games (I play only rarely):

Some games put certain UI elements in the corners, so they are way too far away from the center where the action usually happens. E.g. the minimap in Battlefield 4.
In some games dual QHD can theoretically be more taxing for the GPU than 4K even though dual QHD has less total pixels than 4K (7 372 800 vs 8 294 400). That's because in many games there's more heavy stuff to render horizontally (e.g. other players etc.) than vertically (e.g. mostly sky and clouds).

Testing smaller resolutions with a software

Before changing to a smaller monitor, I "converted" my super ultrawide monitor to a smaller monitor.

I found SwitchResX for Mac to be great: it allowed me to apply black bars to the sides of my monitor.

First I tried regular ultrawide resolution (3440×1440, WQHD, 43:18) for a couple of days. Definitely better! Less looking too far to the sides.

The regular ultrawide resolution started to quickly feel still too wide. Then I reduced the resolution to 2560×1440 (2K, 16:9). Perfect aspect ratio!

(16:10 could also work, but there aren't many external monitors available with that aspect ratio.)

Back to 16:9

I had bought BenQ BL2711U in November 2017 but had never sold it, so I already had a great monitor lying around. The perks of procrastination.

Some specs:

27", 64 cm wide
3840×2160 pixels (4K)
60 Hz
Flat (non-curved) IPS panel

Now I have less horizontal pixels (3840 vs 5120) but that's okay because it's why I wanted to change to a smaller monitor in the first place.

Two windows side by side, both taking 50% width, feels actually quite good now. On the other hand, placing two windows side by side on an ultrawide makes both windows a bit too wide.

As a bonus I have more vertical pixels (2160 vs 1440) and a nice IPS panel.

27" vs 32"

This 27" monitor feels perfect. Not too small, not too big.

A 32" monitor would probably be a little too big for my taste. I would again have to start turning my head around too much when looking at the sides. And either the bottom side of the screen would be too low, or the top side would be too high.

Meme

I'll conclude this post with this nice meme (idea by my bro).

I wrote a weekly log for half a year and it was stressful

2023-03-17T12:00:00+03:00

"Weekly log" basically meaning weekly blog posts with a specific structure. Today I removed the whole Weekly log.

Why I started a weekly log

I started the weekly log to reduce stress: by publishing short weekly log entries, I wouldn't need to stress so much about my blog.

Writing blog posts takes time, and I wanted to publish something regularly.

And I did publish regularly: I published the first entry on the first week of 2021 and then a new entry each week for 6 months for a total of 26 entries.

Why I ditched it

So I wanted to reduce stress, but here's what actually happened: I had two things to maintain; the blog and the weekly log.

Or actually three, because this site used to also have a Cookbook section with "technical recipes."

Publishing every week was nice for a while, but quickly started to feel like work. Having an obligation like that was stressful.

Plus I didn't manage to write short and quick weekly log entries, so it wasn't much easier or more enjoyable than writing blog posts.

How I ditched it

I moved the best bits to individual blog posts and deleted the rest (unnecessary ramblings etc.). I did this slowly, so looks like it took me almost two years.

Other issues

Bad discoverability and SEO

(SEO = search engine optimization)

The weekly log entries were on a separate "Weekly log" page. Someone going through my blog posts might miss entirely that the "Weekly log" page has more blog-like stuff.

Opening a weekly log entry was not a nice experience either because the page was long and had lots of mixed content to go through.

The weekly log entries appeared on Google with names like "22nd week of 2021 – Weekly log." Such titles aren't very clear nor inviting.

So it wasn't easy to discover what topics the weekly log entries actually cover.

Too rigid structure

My weekly log was mainly inspired by Sam Selikoff's Work journal in which he publishes weekly bullet points about work-related stuff, learnings and interesting stuff.

Piggybacking Sam's Work journal, I structured my weekly log entries around these four headings:

👨‍💼 Work
👨‍🚀 Personal
👨‍🎓 Learnings
🕵️‍♂️ Cool stuff

That's sort of nice, but also sort of rigid. I didn't have anything to say in each four category each week, so I either said something pointless anyway or felt bad that the section was empty.

Too much effort

I should have written only bullet points (and headings), but I wrote full paragraphs, and many of them. I put way too much time and effort into something I originally wanted to be a chill little side quest.

The reading experience could have been better too had I written more shortly. Sam Selikoff's Work journal (linked above) is nice to read because it's concise: it has only headings and bullet points, and most bullet points are short (even only one sentence). Who wants to read too lengthy ramblings? Yeah, like this very text here.

Also, the posts could have been regular blog posts with a "Weekly log" tag. Why complicate things?

Lessons learned

Next time I'll think twice before committing to an arbitrary schedule. Publishing something regularly is nice, but not if it starts to feel like work.

Next time I'll also try to keep things simple and flexible. My weekly log entries could have been regular blog posts with only headings and bullet points.

Switching to Mac after 20+ years of using Windows

2023-01-31T12:00:00+03:00

I have used Windows PCs since I was a kid. A year ago (Jan 2022) I got my first MacBook. While Mac isn't perfect, it's so much better that I'm not going back to Windows.

Why I switched to Mac

Three things:

I had long had the impression that many developers use and like Macs, so I was intrigued to try it myself.
Macs are relatively expensive (same amount of money gets you more horsepower if you buy a Windows PC, though I'm not sure if M1/M2 Macs have changed the game), and I'm a cheapo.
A year ago (Jan 2022) I switched jobs and could freely choose a work laptop (a great perk by the way), so I took the opportunity and chose a MacBook.

How long it took me to get familiar with Mac

Only about three days:

Thu: fetched my MacBook from the office
Fri–Sun: got to know the MacBook, configured things, installed apps
Mon: started my new consulting gig

The first work days consisted mostly of introductions to the customer's systems etc., but even if the very first work day was full of coding, I feel I wouldn't have been any more productive had I used a Windows PC (because of the pros of Mac, listed below).

It was a bit risky to switch from Windows to Mac with such a short time frame, but it was worth it.

Things I like in Mac

Unix

Mac is a Unix operating system, so:

Terminal works great and is fast
- Git Bash for Windows is slow in comparison
- WSL (Windows Subsystem for Linux) felt fragile and had performance issues last time I used it
Unix tools work out of the box
- Oh My Zsh gave me a nice Terminal experience very easily

Fast

The hardware matters as well; I switched from Lenovo ThinkPad X1 Carbon Gen 7 to MacBook Pro 16" M1 Pro (32 GB).

My MacBook is not as fast as I thought – I had read high praises from several sources, so my expectations were very high – but it's still fast.

Every time I use my Windows laptop I'm baffled how sluggish it is. So compared to that, yes, my MacBook is very fast.

Better keyboard shortcuts

Using the Cmd key (next to the space bar) with the left thumb is more ergonomic than reaching for the Ctrl key with the left pinky.

Things I miss from Windows

The Menu key is essential for comfortable keyboard navigation across Windows:

In computing, the menu key or application key (≣ Menu) is a key found on Microsoft Windows-oriented computer keyboards [...]. It is typically found on the right side of the keyboard between the right Windows logo key and the right control key [...].

The key's primary function is to launch a context menu with the keyboard rather than with the usual right-mouse button. It can be used when the right-mouse button is not present on a mouse.

[...] In many Windows applications, a similar functionality can be invoked with the ⇧ Shift+F10 keyboard shortcut [...].

I used the Menu key (or sometimes Shift+F10) all the time.

Mac doesn't have a Menu key. Such a shame. An accessibility issue as well.

Alt-tabbing

The default alt-tabbing experience on Mac is poor. No window previews like on Windows, and the keyboard shortcut for alt-tabbing to a hidden or minimized window is crazily complex.

Switching between the windows of a single app with Cmd+` is cool though.

I use a free app called AltTab which "brings the power of Windows's 'alt-tab' window switcher to macOS." Unfortunately it's a bit buggy (because "Mac development ecosystem is pretty terrible in general"), but it's 90% great and much better than the default alt-tabbing experience on Mac.

Middle-clicking on the trackpad

I'm used to middle-clicking by tapping the trackpad with three fingers. That's not possible on MacBook's trackpad though.

The free app called MiddleClick fixes that, but it's a bit buggy.

There are paid alternatives, but I'm not willing to pay several euros for a feature that should be part of core Mac. (I already said I'm a cheapo.)

It's baffling that I need a 3rd party app for this basic feature.

Gaming

I rarely play video games, but I miss Battlefield 4. I'd also love to try Age of Empires IV.

Mac runs some games, but of course not those two I'm interested in.

My bro recently built a Windows gaming PC, which made me want to build one too.

Things that are bad both in Windows and Mac

Focus stealing

I truly hated focus stealing on Windows. It's so annoying when you are doing something and another app/window suddenly steals focus, interrupting your typing/clicking/whatever.

Focus stealing is a problem on Mac too, albeit not as big a problem. Krisp is maybe the worst offender I have encountered so far.

I had reaperducer's Hacker News comment about focus stealing on Macs saved on my bookmarks. It's a good comment; here's a snippet:

I think allowing any pop-up to demand focus is a serious security flaw. I've sometimes found myself typing a password into a browser, or a word processor, because they've decided that they are the most important thing in my life at that moment.

So, focus stealing is not only an annoyance but a security risk as well.

Verdict

I like Mac because it's fast and a Unix system and generally just feels good.

Mac required some tweaking to make me feel at home, but what system doesn't require tweaking? The Windows experience isn't optimal out of the box either.

After a year of using Mac and touching Windows only a few times, I don't see myself going back to Windows, except maybe for gaming. Though it didn't take a full year for me to feel this way; only a few days or weeks.

Automatically retrying a failing function in JS/TS

2022-12-14T12:00:00+03:00

A little helper function to retry a function automatically a limited number of times (or until success) and with a certain delay between retries. Useful e.g. when working with a flaky API.

Starting point

After a bit of googling, I found Jaromanda X's answer on Stack Overflow to be a good starting point:

Using a couple of helper functions I've used a lot, this becomes very easy

The "helpers"

Promise.wait = (time) => new Promise(resolve => setTimeout(resolve, time || 0));
Promise.retry = (cont, fn, delay) => fn().catch(err => cont > 0 ? Promise.wait(delay).then(() => Promise.retry(cont - 1, fn, delay)) : Promise.reject('failed'));

The code:

function myMainFuntion() {
      var delay = 100;
      var tries = 3;
      Promise.retry(tries, tryAsync, delay);
}

Works well, but let's do better since the code wasn't immediately clear for me.

Refactoring step by step

Let's do an unsolicited code review and refactor the code along the way. You can also jump straight to the final result.

The general rule of code reviewing seems to apply here: the shorter the code, the more it receives comments.

Step 1: Prettier

The lines declaring the two helpers are very long: 80 and 161 characters.

Too long lines are difficult to read. Especially the retry method in this case.

Let's format the code with Prettier:

Promise.wait = (time) =>
  new Promise((resolve) => setTimeout(resolve, time || 0))

Promise.retry = (cont, fn, delay) =>
  fn().catch((err) =>
    cont > 0
      ? Promise.wait(delay).then(() => Promise.retry(cont - 1, fn, delay))
      : Promise.reject('failed')
  )

Now the structure of the code is much easier to see. Looks like Promise.retry is a recursive function.

Step 2: no monkey patching

Modifying global prototypes is generally not a good idea, so instead of adding the methods to the global Promise object, let's convert the methods to standalone functions.

Diff:

-Promise.wait = (time) =>
+const   wait = (time) =>
   new Promise((resolve) => setTimeout(resolve, time || 0))

-Promise.retry      = (cont, fn, delay) =>
+export const retry = (cont, fn, delay) =>
   fn().catch((err) =>
     cont > 0
-      ? Promise.wait(delay).then(() => Promise.retry(cont - 1, fn, delay))
+      ?         wait(delay).then(() =>         retry(cont - 1, fn, delay))
       : Promise.reject('failed')
   )

Result (formatted with Prettier; wait function moved to the end):

export const retry = (cont, fn, delay) =>
  fn().catch((err) =>
    cont > 0
      ? wait(delay).then(() => retry(cont - 1, fn, delay))
      : Promise.reject('failed')
  )

const wait = (time) => new Promise((resolve) => setTimeout(resolve, time || 0))

Step 3: what's "cont"?

What is the cont parameter for – what does "cont" mean?

I guess it means something like "continue/retry if this is greater than 0." In other words, it's the number of remaining retries.

Let's rename cont to retries:

-export const retry = (cont, fn, delay) =>
+export const retry = (retries, fn, delay) =>
 // ...

Step 4: order of parameters

Is the order of the parameters ideal?

Now the function reads like "retry with x retries the given fn with a delay of y milliseconds." Sounds clumsy.

If the first two parameters are swapped:

-export const retry = (retries, fn, delay) => {}
+export const retry = (fn, retries, delay) => {}

...the function reads like "retry the given fn with x retries and a delay of y milliseconds."

I think that's better – the fn parameter is the "main" parameter, and the other two parameters are configurable options, so it makes sense to pass the function as the first parameter.

Step 5: options parameter

Let's continue with the parameters.

When calling retry, the purpose of the two option parameters is not clear:

retry(myFn, 2, 200) // What 2? What 200?

Condensing the options into a single object makes the call site clearer:

-export const retry = (fn, retries, delay) => {}
+export const retry = (fn, { retries, delay }) => {}

 // Usage:
-retry(myFn, 2, 200) // huh?
+retry(myFn, { retries: 2, delay: 200 }) // oh

Step 6: delay parameter

Is the delay option clear? What does it delay – only the retries or also the initial function call?

Let's rename delay to retryInterval to make it clear that it's only about the retries, not the initial function call. Actually, let's use retryIntervalMs to also clarify that the unit is milliseconds:

-export const retry = (fn, { retries, delay }) => {}
+export const retry = (fn, { retries, retryIntervalMs }) => {}

 // Usage:
-retry(myFn, { retries: 2, delay: 200 })
+retry(myFn, { retries: 2, retryIntervalMs: 200 })

Another benefit: now the two options are sorted alphabetically. :D

Similarly, let's rename the wait function's time parameter to ms:

-const wait = (time) => new Promise((resolve) => setTimeout(resolve, time || 0))
+const wait = (ms)   => new Promise((resolve) => setTimeout(resolve, ms   || 0))

Step 7: function name

More bike-shedding: does the name retry tell clearly what the function does?

Yes, the function retries another function – but only after the initial try, which is a try, not a re-try.

Something like tryAndRetry or retryOnFail or tryMultipleTimes could be more descriptive. Though these are quite wordy and still not great.

Apparently this whole thing is called "retry pattern" or "retry design pattern" (more about this in the Further resources section), so let's actually keep the retry name.

But thinking about this was useful: we can deduce that because the first fn call is a try and not a retry, the maximum number of fn calls should be 1 + retries. And indeed it is. (If the maximum number was something else, the option name retries could be confusing.)

Here's what we have so far:

export const retry = (fn, { retries, retryIntervalMs }) =>
  fn().catch((err) =>
    retries > 0
      ? wait(retryIntervalMs).then(() =>
          retry(fn, { retries: retries - 1, retryIntervalMs })
        )
      : Promise.reject('failed')
  )

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms || 0))

Step 8: better error

If the last retry also fails, retry throws the string 'failed'. Re-throwing the error thrown by fn is likely more useful.

While at it, let's also rename err to error:

 export const retry = (fn, { retries, retryIntervalMs }) =>
-  fn().catch((err) =>
+  fn().catch((error) =>
     retries > 0
       ? wait(retryIntervalMs).then(() =>
           retry(fn, { retries: retries - 1, retryIntervalMs })
         )
-      : Promise.reject('failed')
+      : Promise.reject(error)
   )

Step 9: TypeScript

    export const retry = <T>(
  fn: () => Promise<T>,
  { retries, retryIntervalMs }: { retries: number; retryIntervalMs: number }
): Promise<T> =>
  fn().catch((error) =>
    retries > 0
      ? wait(retryIntervalMs).then(() =>
          retry(fn, { retries: retries - 1, retryIntervalMs })
        )
      : Promise.reject(error)
  )

const wait = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms))

The generic parameter T is used more than once in the function signature, so this is a good use of generics; see The Golden Rule of Generics.

Step 10: the need for `async`/`await`

So far so good, but there's a caveat:

The provided function must be async (marked with async or returns a Promise), or the function won't be retried.

Async functions

Async functions work well:

const options = { retries: 2, retryIntervalMs: 200 }

retry(async () => 42, options)
//=> returns 42

retry(() => Promise.resolve(42), options)
//=> returns 42

retry(async () => {
  console.log('hi')
  throw new Error('fail')
}, options)
//=> logs 'hi' (initial try)
//=> logs 'hi' (1st retry)
//=> logs 'hi' (2nd retry)
//=> throws [Error: fail]

retry(() => {
  console.log('hi')
  return Promise.reject(new Error('fail'))
}, options)
//=> logs 'hi' (initial try)
//=> logs 'hi' (1st retry)
//=> logs 'hi' (2nd retry)
//=> throws [Error: fail]

Non-async functions

Non-async functions don't work:

Non-async functions are not retried:

retry(() => {
  console.log('hi')
  throw new Error('fail')
}, options)
//=> logs 'hi' (initial try)
//=> throws [Error: fail]

If a non-async function succeeds, a TypeError will still be thrown:

retry(() => {
  console.log('hi')
  return 42
}, options)
//=> logs 'hi' (initial try)
//=> throws [TypeError: fn(...).catch is not a function]

`async`/`await` vs Promises

TypeScript won't allow passing a non-async function to retry, but I don't like that retry breaks at runtime if it's given a non-async function.

Let's eliminate the caveat by refactoring to async/await.

An alternative would be to make retry always return a Promise. The code wouldn't be as clear in my opinion, and there would be the extra caveat of having to avoid the pitfalls of the explicit Promise constructor anti-pattern.

Step 11: `async`/`await`

Diff:

-export const retry = <T>(
-  fn: () => Promise<T>,
+export const retry = async <T>(
+  fn: () => Promise<T> | T,
   { retries, retryIntervalMs }: { retries: number; retryIntervalMs: number }
-): Promise<T> =>
-  fn().catch((error) =>
-    retries > 0
-      ? wait(retryIntervalMs).then(() =>
-          retry(fn, { retries: retries - 1, retryIntervalMs })
-        )
-      : Promise.reject(error)
-  )
+): Promise<T> => {
+  try {
+    return await fn()
+  } catch (error) {
+    if (retries <= 0) {
+      throw error
+    }
+    await sleep(retryIntervalMs)
+    return retry(fn, { retries: retries - 1, retryIntervalMs })
+  }
+}

-const wait  = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms))
+const sleep = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms))

(Heh, only one non-empty line remained unchanged.)

Details:

I renamed wait to sleep because await wait() would look awkward.
This version works also with non-async functions because the await operator converts non-Promise values to resolved Promises.
return vs return await: "Outside of try/catch blocks, return await is redundant."

Final result

/**
 * Runs the function `fn`
 * and retries automatically if it fails.
 *
 * Tries max `1 + retries` times
 * with `retryIntervalMs` milliseconds between retries.
 *
 * From https://mtsknn.fi/blog/js-retry-on-fail/
 */
export const retry = async <T>(
  fn: () => Promise<T> | T,
  { retries, retryIntervalMs }: { retries: number; retryIntervalMs: number }
): Promise<T> => {
  try {
    return await fn()
  } catch (error) {
    if (retries <= 0) {
      throw error
    }
    await sleep(retryIntervalMs)
    return retry(fn, { retries: retries - 1, retryIntervalMs })
  }
}

const sleep = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms))

Looks quite good to me!

Usage

Happy cases:

const options = { retries: 2, retryIntervalMs: 200 }

retry(() => 42, options)
//=> 42

retry(() => Promise.resolve(42), options)
//=> 42

retry(async () => 42, options)
//=> 42

Error cases:

const options = { retries: 2, retryIntervalMs: 200 }

retry(() => {
  console.log('hi')
  throw new Error('fail')
}, options)
//=> logs 'hi' (initial try)
//=> logs 'hi' (1st retry)
//=> logs 'hi' (2nd retry)
//=> throws [Error: fail]

retry(() => {
  console.log('hi')
  return Promise.reject(new Error('fail'))
}, options)
//=> same as above

retry(async () => {
  console.log('hi')
  throw new Error('fail')
}, options)
//=> same as above

Further resources

This blog post was almost ready when I found Promise Retry Design Patterns on Stack Overflow. These three answers are interesting:

Red Mercury's answer uses the exponential backoff algorithm. This led me to find p-retry, a library that also uses the exponential backoff algorithm.
Bryan McGrane's answer is almost identical to my final result.
Nacho Coloma's answer is also similar, but uses a for loop instead of recursion. Though this version retries only if the given function returns undefined, not if it throws.

SWR (v1): show previous/stale data on revalidation errors

2022-11-08T12:00:00+03:00

If I'm already displaying data that I have successfully fetched with SWR, and then another fetch call fails (when revalidating the data), I don't want to replace the data view with an error view. Here's how to avoid that.

Problem

Basic usage of SWR (v1; I haven't upgraded to v2 yet):

export const useItems = () => {
  const { data, error } = useSWR('/api/items/', (url) =>
    fetch(url).then((res) => res.json())
  )

  return {
    items: data ?? [],
    isLoadingItems: !data && !error,
    failedToLoadItems: !!error,
  }
}

function Items() {
  const { items, isLoadingItems, failedToLoadItems } = useItems()

  return isLoadingItems ? (
    <p>Loading...</p>
  ) : failedToLoadItems ? (
    <p>Error</p>
  ) : items.length === 0 ? (
    <p>No items</p>
  ) : (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  )
}

My problem occurs with these steps:

SWR starts to fetch initial data, app shows loading state.
SWR has fetched data, app shows data.
SWR starts to fetch data again (revalidation), app still shows data.
SWR fails to fetch data (e.g. the API endpoint fails), app shows error state.
- Here I don't want the app to show error state; I want it to keep showing the previous (stale) data.

Solution

I spent some time looking for a solution until I realized that it's very simple – let the failed state be false only if there's no data (i.e. if data is not falsy):









  export const useItems = () => {
  const { data, error } = useSWR('/api/items/', (url) =>
    fetch(url).then((res) => res.json())
  )

  return {
    items: data ?? [],
    isLoadingItems: !data && !error,
    failedToLoadItems: !data && !!error,
    //                 ^^^^^^^^
  }
}

function Items() {
  // Same as before
}

Truth tables

I built these truth tables to be sure that the change works as expected.

Before the change

`data`	`error`	`isLoading` (`!data && !error`)	`failedToLoad` (`!!error`)	state description
falsy	falsy	`true`	`false`	initial state or revalidation succeeded
truthy	falsy	`false`	`false`	initial fetch succeeded
falsy	truthy	`false`	`true`	initial fetch failed
truthy	truthy	`false`	`true`	revalidation failed

After the change

Only the 4th column and the last row are different:

`data`	`error`	`isLoading` (`!data && !error`)	`failedToLoad` (`!data && !!error`)	state description
falsy	falsy	`true`	`false`	initial state or revalidation succeeded
truthy	falsy	`false`	`false`	initial fetch succeeded
falsy	truthy	`false`	`true`	initial fetch failed
truthy	truthy	`false`	`false` (`true` in the other table)	revalidation failed

LGTM!

Wild ideas to avoid burnout

2022-11-07T12:00:00+03:00

Care less, take a sabbatical, get a second job, get monster ear protection, hide behind your manager.

Someone recently asked on Hacker News if anyone has managed to find enjoyment in their work after burnout.

Excerpts from comments that I liked (not all are that wild, but anyway):

Care less (comment by highwaylights)

This advice is going to be hated by a lot of people but... care less.

You're in an industry that values your skills and seems to always have demand. Whether or not that's true in the future, it certainly is today, so the best thing you can do is put yourself first and worry less about work as a whole. Especially if it's not your own company.

Spend more time on you, on activities with friends and family, on hobbies. If you don't have particularly healthy hobbies, maybe start some. Getting away from your work more and more will make it all the more bearable.

These days work is close to the bottom of my list of concerns, which sounds really bad – BUT – I find I'm more productive than I've been in years because I'm not worrying if something takes longer than expected or is bigger than I realised. I can just enjoy the problem solving and shipping without the stress.

If you're burned out this badly I'd suggest it's your soul's way of telling yourself "hey this isn't working for me". As someone who has been to some pretty messed up depths with the anxiety monster, I'd heed that voice. Life isn't long enough to stay stuck in a rut like this for any amount of time at all.

Caring less doesn't mean doing sloppy work, nor does it mean not caring about the quality of your work.

It means not taking work things too seriously (no one's life is at stake), not having too strong opinions on everything (so you can avoid tiring debates; pick your battles), not involving in office politics.

It means focusing on the fun things, like technical challenges, clean code practices (yea I like them), documenting your learnings (and later blogging about them).

Another way of saying "care less" (comment by _fat_santa):

I think a better way of putting it is: "don't get too emotionally invested". Writing code I often times get emotionally invested in its success, but with a job you have to create that clear line of "I care, but I'm not emotionally invested". I really want to fix that bug in the system but if 5PM hits, I don't have the emotional investment to keep going into the night like with a side project, I can get to it in the morning.

Stopping early and continuing the next day is important, but sometimes I fail to do that. Like "one more turn" when playing Civilization, "ten more minutes" often gets out of hand (comment by SoftTalker):

I used to be the sort of person who would stay at work until I got to what felt like a "good" stopping point in what I was doing. If something wasn't working, and seemed like another 30 minutes might fix it, I would often do it. Of course 30 minutes often turned into 3 hours.

Now I'm much more likely to just go home at the end of the day. I don't really care what fires are burning, they will be there tomorrow and nobody will die.

Saying "care less" is like saying "stress less," but the latter is difficult to implement on its own; you need other tools for that (e.g. caring less).
Take a sabbatical (comments by samatman)

Can you afford a sabbatical?

The term has roots in "seven", just like Sabbath, so with 14 years in the industry, you've skipped one.

I think a solid half-year off every seven to ten years is an excellent practice for intellectually demanding labor.

Ooh, I suddenly feel like I'd like to take a sabbatical! Even 6 months would be nice.

A sabbatical is not a vacation; it's time to work on your passion projects:

What makes it a sabbatical is that it's a change of pace which furthers your career. I'd love to take a sabbatical and just work on building stuff, personally: from soldering, to designing boards, probing them, writing firmware, I'm a rank amateur, and I'd love to level up for a while, while free of the burden of justifying my salary in the process.

[...]

What it isn't, is a vacation, or a convalescence^[1]. It sounds like you haven't hit "can't work", just "sucks to work", which is a blessing.

[...]

I've known people who pushed "sucks to work" until it became "can't work", and they don't all make it back to the profession, a bit less than half in fact. Whatever you do, I urge you to take burnout seriously, because at the limit it's a serious medical condition which can cripple or kill you.

When looking for a job after the sabbatical, saying that you took a sabbatical sounds better than saying that you took a year off:

A sabbatical is not a gap in one's resume, it's a sabbatical. What's done with that time is open-ended, but one of the things it does is provide a useful line item.

[...]

A sabbatical is good if: you can write an open-source library in your niches which solves a problem, if you expand the breadth of your expertise, if what you're doing has a significant philanthropic angle. All of these can set someone up for a higher tier of job, something with better prospects.

Even if you wouldn't achieve anything tangible during your sabbatical, it should still bring great benefits: less stress, fresh mind, more energy.

If you are already burned out, taking a year off might be better for your health. If you are not, a sabbatical could be a good tool to avoid that.
Get a second job (comment by aspyct)

For me, switching to 4 days a week was a huge improvement in my quality of life. Now I've switched to 3, and have a completely different second job 2 days a week. And two days of rest.

I love both, for different reasons, but could never go back to a full week of IT, or switch to a full week of my new job. They balance fine, but I don't think they can exist on their own.

Interesting idea!

Having only one job and working only 3 or 4 days a week would be more optimal, but not always financially feasible. Getting a completely different second job would bring in more money and also variation to days.

Another good point:

I think working 5 days a week, 8h a day on the same topic is insane. I can't think of anything I would want to do for so many hours a day, almost every day.

It's crazy how much people usually work (including me, ouch).
Get monster ear protection (comment by larve)

Get monster ear protection. This has to be one of the revelations: noise stresses me out sooo much, and I have been repressing it for so long. I now have -35 dB + noise-cancelling earplugs and can basically live in complete silence, in the noisiest environment.

Noise stresses me out too, very much so, and I too have been ignoring that.

I walk on my treadmill for several hours every work day^[2], and it's not a particularly silent device, so I'm being exposed to a lot of noise. That's gotta do something to my mind, and not in a good way.

I already own Sony WH-1000XM3 wireless noise-cancelling headphones, and looks like RTINGS.com has rated them as having the best level of noise isolation among 697 headphones that they have tested (as of Nov 7, 2022). Nice! So I just need to learn to use my headphones more.
Hide behind your manager (comment by jnsaff2)^[3]

Whenever anyone asked me to stay late I referred them to my manager for them to approve paid overtime. Most of the time the discussion stopped there, but there were a few times when they decided to pay.

There'll always be people who'll try to shamelessly take advantage of you.

If setting boundaries on your own feels difficult, one strategy is to delegate unpleasant discussions to another person, like your manager.

That's not cowardice; that's saving your mental energy by avoiding discussions that shouldn't happen in the first place (no one should ask or except anyone to do unpaid overtime).

One more link: Do Nothing on YouTube (0:49) summarizes the "care less" category well.

Footnotes

Dictionary.com defines convalescence as "the gradual recovery of health and strength after illness." ↩
Walking is sooo much better than sitting or standing still. Blog post coming some day. ↩
To be clear, the comment doesn't directly say to "hide behind your manager." ↩

Four ways to use a fallback ref with `React.forwardRef`

2022-10-19T12:00:00+03:00

A component wrapped in React.forwardRef normally expects to receive a ref from its parent component. What if you want the component to have a ref even if it doesn't receive one from its parent?

The problem

React.forwardRef allows passing a ref to a child component:

function Parent() {
  const ref = useRef(null)

  useEffect(() => {
    console.log(ref.current)
  }, [])

  return <Child ref={ref} />
}

const Child = React.forwardRef((props, forwardedRef) => {
  useEffect(() => {
    console.log(forwardedRef?.current)
  }, [forwardedRef])

  return <div ref={forwardedRef}>...</div>
})

When rendering <Parent />, both useEffects log the <div> element from the Child component:

<Parent />
// Logs `<div>` twice

But when rendering <Child /> on its own, the Child's useEffect logs undefined because no ref is passed/forwarded:

<Child />
// Logs `undefined` once 😿

More specifically: forwardedRef is null, so forwardedRef?.current is undefined.

What if you want Child to have a ref to its <div> element even when no ref is forwarded to Child? You can create a new ref in Child, but you can't attach both refs to the <div>:

const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useRef(null)

  return (
    <div
      // 🛑 JSX elements cannot have multiple attributes with the same name
      ref={forwardedRef}
      ref={ref}
    >
      ...
    </div>
  )
})

Desired outcome

When rendering <Parent />, both useEffects should still log the <div> element from the Child component:

<Parent />
// Logs `<div>` twice

When rendering <Child> on its own, its useEffect should log the <div> element:

<Child />
// Logs `<div>` once

Four solutions

`useRef` + `||`

Create a fallback ref with useRef and use it if forwardedRef is null:


  




 const Child = React.forwardRef((props, forwardedRef) => {
  const fallbackRef = useRef(null)
  const ref = forwardedRef || fallbackRef

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

Or as a custom hook:


 







    const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useFallbackRef(forwardedRef)

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

function useFallbackRef(forwardedRef) {
  const fallbackRef = useRef(null)
  return forwardedRef || fallbackRef
}

Pros:

Very simple and clear. Maybe the simplest solution.

Cons:

The fallback ref is created even when it's not needed, but it's probably not a big deal.

I found this solution via brunoscopelliti/use-forward-ref on GitHub, which was the only npm package found via searching "react fallback ref" on npmjs.com.

Lazy `useState` + conditional `createRef`

Create a fallback ref with React.createRef if forwardedRef is null.

To avoid creating a new ref every time the Child component is re-rendered, wrap the conditional ref creation in useState and use lazy initial state:


 const Child = React.forwardRef((props, forwardedRef) => {
  const [ref] = useState(() => forwardedRef || React.createRef())

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

Or as a custom hook:


 







   const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useFallbackRef(forwardedRef)

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

function useFallbackRef(forwardedRef) {
  return useState(() => forwardedRef || React.createRef())[0]
}

Pros:

Simple and reads like English: use forwardedRef if it exists (i.e. if it's not null), otherwise create a new ref.
The fallback ref is created only when necessary. (Probably doesn't matter though.)

Cons:

It's mildly confusing to mix hooks and the non-hook createRef function.
Simple because uses only the useState hook, though you do need to know about and understand lazy initial state.

I came up with this solution myself. 🤙

`useImperativeHandle`

React's useImperativeHandle hook allows customizing the value of a forwarded ref.

The docs for the hook are very terse (emphasis added and example code slightly modified):

useImperativeHandle(ref, createHandle, [deps])
useImperativeHandle customizes the instance value that is exposed to parent components when using ref. As always, imperative code using refs should be avoided in most cases. useImperativeHandle should be used with forwardRef:
const FancyInput = React.forwardRef((props, forwardedRef) => {
  const ref = useRef()

  useImperativeHandle(forwardedRef, () => ({
    focus: () => ref.current.focus(),
  }))

  return <input ref={ref} />
})
In this example, a parent component that renders <FancyInput ref={inputRef} /> would be able to call inputRef.current.focus().

In the quoted example, inputRef.current has only the focus method.

To expose all methods and properties of the DOM element to the parent ref, expose ref.current as-is:

useImperativeHandle(forwardedRef, () => ref.current)

Then:

If a ref is forwarded, forwardedRef.current and ref.current will point to the same DOM element.
If a ref is not forwarded, forwardedRef will still be null, but ref will act as a fallback ref.

Put together:


  




  const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useRef(null)
  useImperativeHandle(forwardedRef, () => ref.current)

  useEffect(() => {
    console.log(ref.current)
  }, []) // `ref` is not needed here

  // Notice we are using `ref` here, not `forwardedRef`
  return <div ref={ref}>...</div>
})

Or as a custom hook:


 







     const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useFallbackRef(forwardedRef)

  useEffect(() => {
    console.log(ref.current)
  }, [ref]) // `ref` is needed again here

  return <div ref={ref}>...</div>
})

function useFallbackRef(forwardedRef) {
  const ref = useRef(null)
  useImperativeHandle(forwardedRef, () => ref.current)
  return ref
}

Pros:

The useImperativeHandle hook is designed for customizing the value of the forwarded ref, so using it like this feels correct.
ESLint knows that the ref variable is stable, so it doesn't need to be included in the useEffect's dependency array, making the code clearer. (Though ESLint won't know that ref is stable when using the custom hook.)

Cons:

The useImperativeHandle hook is exotic and probably only rarely used. If you have never heard of it before, you can't know how it works at a first glance. (Compared to useState, which is maybe the most basic hook and should be familiar to any React dev.)
The fallback ref is created even when it's not needed, but it's probably not a big deal.

I found this solution via Jake Trent's blog post Fallback Ref in React. It introduced me to the useImperativeHandle hook and has good musings about why the hook is lame.

Merge refs

Use a utility like react-merge-refs to merge the two refs:




 




 import mergeRefs from 'react-merge-refs'

const Child = React.forwardRef((props, forwardedRef) => {
  const ref = useRef()

  useEffect(() => {
    console.log(ref.current)
  }, [])

  return <div ref={mergeRefs([forwardedRef, ref])}>...</div>
})

Under the hood mergeRefs returns a callback ref:

function mergeRefs(refs) {
  return (value) => {
    refs.forEach((ref) => {
      if (typeof ref === 'function') {
        ref(value)
      } else if (ref != null) {
        ref.current = value
      }
    })
  }
}

If forwardedRef is null, mergeRefs simply skips it.

Pros:

More versatile because supports merging more than two refs.

Cons:

Requires a 3rd party library unless you re-implement the utility yourself. And if you are going to re-implement it yourself, there are simpler solutions (unless you need to merge more than two refs).

The use-callback-ref library provides a similar mergeRefs function as well as a useMergeRefs hook.

Which solution to use?

If you need to merge more than two refs, use a utility like react-merge-refs or use-callback-ref.

Otherwise I would prefer the first or the second solution. Both are simple and straightforward. No point in installing a dependency if you just want to create a fallback ref.

Initially the useImperativeHandle solution felt the most correct to me because the hook is designed for customizing the value of the forwarded ref. However, the solution is more difficult to understand because the hook is so exotic and rarely used.

One more point to consider: what if, during the lifecycle of Child (the component wrapped in React.forwardRef), forwardedRef is sometimes null and sometimes a ref object? I haven't tested how the different solutions would react to that. This might or might not be relevant in your case.

Invalid solutions

Knowing what doesn't work can be very useful as well.

Conditional `useRef`

Creating a fallback ref with useRef if forwardedRef is null might work:


   const Child = React.forwardRef((props, forwardedRef) => {
  // 🛑 Not allowed!
  // Calling hooks conditionally breaks the rules of hooks.
  const ref = forwardedRef || useRef()

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

...but it might also not work because calling hooks conditionally breaks the rules of hooks.

Conditional `createRef`

React.createRef is not a hook, so it can be called conditionally:


  


 const Child = React.forwardRef((props, forwardedRef) => {
  // 🛑 A new ref is created on every re-render if `forwardedRef` is `null`
  const ref = forwardedRef || React.createRef()

  useEffect(() => {
    console.log(ref.current)
  }, [ref])

  return <div ref={ref}>...</div>
})

However, if forwardedRef is null, a new ref is created every time the Child component is re-rendered.

Furthermore, ref is not stable, so it needs to be included in the useEffect's dependency array. Because of this, the useEffect will run on every re-render.

Omitting ref from the dependency array and ignoring the "exhaustive-deps" ESLint rule is not a proper solution. Ignoring the rule is confusing and opens the door for further problems.

`useRef` + conditional `createRef`

To make the ref from the previous invalid solution stable, we can wrap it in another useRef and immediately grab its current value (i.e. forwardedRef or the newly-created ref):


  const Child = React.forwardRef((props, forwardedRef) => {
  // 🛑 A new ref is created and discarded on every re-render if `forwardedRef` is `null`
  const ref = useRef(forwardedRef || React.createRef()).current

  useEffect(() => {
    console.log(ref.current)
  }, [ref]) // `ref` must be included here but is stable

  return <div ref={ref}>...</div>
})

However, if forwardedRef is null, a new ref is still created every time the Child component is re-rendered; it's just discarded immediately.

Plus the code looks ugly and unclear.

Further resources

This blog post contains these links:

Jake Trent's blog post Fallback Ref in React
Searching "react fallback ref" on npmjs.com
Projects on GitHub:
React docs:

Software for syncing internal and external hard drives

2022-10-15T12:00:00+03:00

I'm looking for a software that does 2-way syncing between my MacBook's hard drive and an external hard drive. Syncthing vs rsync vs Unison vs FreeFileSync vs Resilio Sync... oh my!

My use case

Problem

I have important files (photos and such) scattered on three computers:

A MacBook that I started using 9 months ago.
A Lenovo laptop (Windows) that I stopped using 9 months ago because I switched to the MacBook.
A custom-built desktop computer (Windows) that I stopped using 27 months ago because I switched to the Lenovo laptop.

It's a mess! And I don't have back-ups. 🙈

Solution

I want to:

Copy important files on my current computer to an external hard drive.
Copy/move important files on the two older computers to the same external hard drive.
Sync the external hard drive and my current computer's hard drive.

This way I'll have two copies of every important file:

One copy on my current computer's hard drive.
Another copy on my external hard drive.

That's a good start!

For this I'll need a software that does 2-way syncing.

Comparing software

Syncthing – nope

I have never used Syncthing, but I have heard it's good. Kinda like Dropbox:

Syncthing is a continuous file synchronization program. It synchronizes files between two or more computers in real time [...].

But Syncthing doesn't satisfy my needs at this point. From Syncthing's FAQ:

Does Syncthing support syncing between folders on the same system?

No. Syncthing is not designed to sync locally and the overhead involved in doing so using Syncthing's method would be wasteful. There are better programs to achieve this such as rsync or Unison.

Verdict: nope, can't use Syncthing in my case.

rsync – nope

Quick googling reveals that rsync doesn't support 2-way syncing. Or at least not in a straightforward way, and I'd like a simple solution for now.

I need 2-way syncing because if I add files to the external hard drive from my old computers, I want the new files to be synced/copied to my current computer.

Verdict: nope, can't use rsync in my case.

Unison – maybe

Unison was mentioned in Syncthing's FAQ and in the Stack Overflow page about rsync. And it indeed looks promising:

Supports 2-way sync.
Supports syncing between two (or more) folders on the same system.
Unison can be used with a daemon or cron, making future syncs automatic and easy.

One caveat that I came across with: Unison can't run on a "heterogeneous network." In other words, Unison binaries on your different devices must be "exactly the same version, compiled with exactly the same version of various libraries," or you'll run into problems. This caveat doesn't apply to me for now since I would be installing Unison only to my current computer, but this is good to know and makes me wary of using Unison (what if I would later like to install it on another device?).

Verdict: Unison might fit the bill, but is there anything better?

FreeFileSync – my choice

FreeFileSync apparently works quite much like Unison.

I found someone saying on Hacker News that FreeFileSync has better GUI than Unison. Since googling "FreeFileSync vs Unison" doesn't yield many results, I might go ahead and trust that single internet stranger's word about the GUI.

Verdict: FreeFileSync should fit the bill and might be better than Unison.

Resilio Sync – costs money

Resilio Sync is a "fast, reliable, and simple file sync and share solution, powered by P2P technology."

The Home edition costs $59.90 (one-time payment). That's not much, but I don't want to spend money on a syncing solution (at least not yet), so I'll skip Resilio Sync for now. (I don't even know if Resilio Sync would fit my needs.)

Verdict: Resilio Sync costs money, so I won't even consider it for now.

Next steps

All right, FreeFileSync is my choice.

After I have used it to have two copies of my important files, I want to:

Periodically (or preferably automatically) sync my current computer's hard drive and the external hard drive.
Periodically (or preferably automatically) back up the files to an off-site location, e.g. to Backblaze B2.

This way I'll satisfy the 3-2-1 back-up strategy:

Have at least 3 copies of data
with 2 of the copies on different local devices
and 1 copy in an off-site location.

But I'm getting ahead of myself... I should start by installing FreeFileSync.

Oh, but how about buying an external hard drive? Yeah, I've already got one – I bought it 3 years ago for this purpose but haven't even unboxed it yet. 🤡

Stashing only unstaged changes in Git

2022-10-12T12:00:00+03:00

git stash -k doesn't work as expected. Use a temporary commit instead.

Non-solution

git stash -k  # -k = --keep-index

What this does:

Keeps the staged changes: nice.
Stashes unstaged and staged changes: not nice since the stash entry will also contain the staged changes. This can be problematic as (in this blog post) we want to stash only unstaged changes.

Solution

Using my Git aliases:

git c -m wip to create a temporary commit
git stash to stash the remaining (unstaged/uncommitted) changes
- Optionally use -u (= --include-untracked) to also stash untracked files
git undo to undo the previous commit (the temporary commit done in step 1)
- Optionally use --soft to keep the changes in the staging area

If not using my Git aliases:

git c = git commit
git undo = git reset HEAD~

Source of the solution: Stephen Hanson's answer on Stack Overflow.

My point is that my Git aliases make the solution even nicer, especially git undo since I can't remember the underlying command, plus git reset is scary (but the alias makes it less scary).

JS solutions to the "coin combinations" interview puzzle

2022-10-10T12:00:00+03:00

"Given an array of coins and a target amount, return all combinations of coins that add up to the amount, or an empty array if no such combinations exist."

Example inputs and outputs

let coins = [1, 2, 1, 5, 5, 10]
let amount = 12
getCoinCombinations(coins, amount)
//=> [[1, 1, 5, 5],  [1, 1, 10],  [2, 5, 5],  [2, 10]]

coins = [2, 5, 5, 5]
amount = 13
getCoinCombinations(coins, amount)
//=> []

A slight variation to the puzzle is to return only one valid combination:

let coins = [1, 2, 1, 5, 5, 10]
let amount = 12
getCoinCombination(coins, amount)
// Any of the following is valid:
//=> [1, 1, 5, 5]
//=> [1, 1, 10]
//=> [2, 5, 5]
//=> [2, 10]

Let's solve both puzzles.

Why though

It was fun to solve this!

Initial naive solution

Find all possible coin combinations.
- I have a separate post for that: Generating array permutations of all lengths in JS.
Filter out the combinations whose sum doesn't match the target amount.

Getting all combinations

const coins = [1, 2, 1, 5, 5, 10]
const amount = 12

const getCoinCombinations = (coins, amount) =>
  getCombinations(coins).filter((combo) => sum(combo) === amount)

const sum = (numbers) => numbers.reduce((a, b) => a + b, 0)

// Via https://mtsknn.fi/blog/js-array-item-combinations/
const getCombinations = (items) =>
  items.reduce((combos, item) => {
    const newCombos = combos.map((combo) => combo.concat(item))
    combos.push([item], ...newCombos)
    return combos
  }, [])

Getting a single combination

Change .filter() to .find() and fall back to an empty array:

const getCoinCombination = (coins, amount) =>
  getCombinations(coins).find((combo) => sum(combo) === amount) || []

Why this is nice

Straightforward and simple.
No boring for loops.

Why this is naive

First all combinations are generated, then they are looped through again to find matching combinations. This is inefficient, especially when getting only a single combination.
- If coins is a large array (19+ items), getCombinations() gets very slow because the amount of total combinations (before filtering) will be huge.
  
  At some point (32+ coins) the code won't even work anymore because the unfiltered combinations won't fit in a single array.
  
  More details in a separate post: Finding array item combinations for large arrays is complex.
When looping through the combinations to find matching combinations, each combination's sum is calculated. The sums could be calculated earlier to avoid having to:
- loop through them again (in the filter() or find()).
- keep invalid combinations around.

Better solution for getting all combinations

Starting point

Here's the initial solution but without the separate getCombinations function:

const getCoinCombinations = (coins, amount) =>
  coins
    .reduce((combos, coin) => {
      const newCombos = combos.map((combo) => combo.concat(coin))
      combos.push([coin], ...newCombos)
      return combos
    }, [])
    .filter((combo) => sum(combo) === amount)

const sum = (numbers) => numbers.reduce((a, b) => a + b, 0)

Step 1

Each combination in combos is an array of numbers (coins), and each combination's sum is calculated in the filter method.

If the sums were calculated already in the reducer, there would be no need to loop through each combination's coins in the filter method.

This can be done by making each combination an object, like { coins: [1, 2, 1, 5], sum: 9 }:

const getCoinCombinations = (coins, amount) =>
  coins
    .reduce((combos, coin) => {
      const newCombos = combos.map((combo) => ({
        coins: combo.coins.concat(coin),
        sum: combo.sum + coin,
      }))

      combos.push(
        {
          coins: [coin],
          sum: coin,
        },
        ...newCombos
      )

      return combos
    }, [])
    .filter((combo) => combo.sum === amount)
    .map((combo) => combo.coins)

There's a new mapper function at the end, but we'll deal with that soon.

Step 2

Does every combination need to be stored in combos?

Example:

All coins: 1, 2, 1, 5, 5, 10.
Target amount is 12.
Current coin is the second last coin (value 5).
A previous combination has the coins 1, 2, 1 and 5 (→ sum 9).
Question: Does it make sense to create a new combination by adding the current coin (5) to the previous combination's coins?
Answer: The new combination's sum would be 14, which is greater than the target amount (12), so no: creating that combination wouldn't make sense.

Changing combos.map() to combos.forEach() allows conditionally pushing one valid combination at a time to combos:

const getCoinCombinations = (coins, amount) =>
  coins
    .reduce((combos, coin) => {
      combos.forEach((combo) => {
        const newSum = combo.sum + coin
        if (newSum <= amount) {
          combos.push({
            coins: combo.coins.concat(coin),
            sum: newSum,
          })
        }
      })

      if (coin <= amount) {
        combos.push({
          coins: [coin],
          sum: coin,
        })
      }

      return combos
    }, [])
    .filter((combo) => combo.sum === amount)
    .map((combo) => combo.coins)

There's some duplication (the codes inside combos.forEach() and below it look very similar), but we'll deal with that soon.

Step 3

combos contains both incomplete combinations like [2, 5] (sum 7) and complete combinations like [2, 5, 5] (sum 12).

If incomplete and complete combinations were stored separately, the filtering after the reducer would be unnecessary.

This can be done by changing the accumulator array (combos) to an object that contains two arrays ({ complete: [], incomplete: [] }). No need to store sums of the complete combinations (the sums should be equal to amount), so no need for the mapper function after the reducer either:

const getCoinCombinations = (coins, amount) =>
  coins.reduce(
    (combos, coin) => {
      combos.incomplete.forEach((combo) => {
        const newSum = combo.sum + coin

        if (newSum > amount) return

        const newCoins = combo.coins.concat(coin)

        if (newSum === amount) {
          combos.complete.push(newCoins)
        } else {
          combos.incomplete.push({
            coins: newCoins,
            sum: newSum,
          })
        }
      })

      if (coin === amount) {
        combos.complete.push([coin])
      } else if (coin < amount) {
        combos.incomplete.push({
          coins: [coin],
          sum: coin,
        })
      }

      return combos
    },
    { complete: [], incomplete: [] }
  ).complete

Step 4

Final step is to reduce duplication:

const getCoinCombinations = (coins, amount) => {
  return coins.reduce(
    (combos, coin) => {
      combos.incomplete.forEach((combo) => {
        keepComboIfValid(combos, combo.coins, coin, combo.sum + coin)
      })

      keepComboIfValid(combos, [], coin, coin)

      return combos
    },
    { complete: [], incomplete: [] }
  ).complete

  function keepComboIfValid(combos, previousCoins, coin, sum) {
    if (sum > amount) return
    const newCoins = previousCoins.concat(coin)
    if (sum === amount) combos.complete.push(newCoins)
    else combos.incomplete.push({ coins: newCoins, sum })
  }
}

keepComboIfValid mutates the reducer function's accumulator object. But I think that's OK because the mutations are restricted to the getCoinCombinations function, so the mutations are still local. Related blog post: Local mutations are all right.

Potential misstep

It would be tempting to simplify the keepComboIfValid function like this:

// ⛔️ Nope
const getCoinCombinations = (coins, amount) => {
  return coins.reduce(
    (combos, coin) => {
      combos.incomplete.forEach((combo) => {
        keepComboIfValid(combos, {
          coins: combo.coins.concat(coin),
          sum: combo.sum + coin,
        })
      })

      keepComboIfValid(combos, { coins: [coin], sum: coin })

      return combos
    },
    { complete: [], incomplete: [] }
  ).complete

  function keepComboIfValid(combos, combo) {
    if (combo.sum === amount) combos.complete.push(combo.coins)
    else if (combo.sum < amount) combos.incomplete.push(combo)
  }
}

However, this would be less efficient because new combinations are generated and then immediately discarded if they are not valid.

Better solution for getting a single combination

Similar to the previous code, but:

No need to store complete combinations in an array; we want to return the first complete combination immediately when it's found.
A reducer function can't be terminated early, so we need to use for loops instead.

const getCoinCombination = (coins, amount) => {
  const incompleteCombos = []

  for (let coin of coins) {
    if (coin > amount) continue
    if (coin === amount) return [coin]

    for (let i = 0, { length } = incompleteCombos; i < length; i++) {
      const combo = incompleteCombos[i]
      const newSum = combo.sum + coin
      if (newSum > amount) continue
      const newCoins = combo.coins.concat(coin)
      if (newSum === amount) return newCoins
      incompleteCombos.push({ coins: newCoins, sum: newSum })
    }

    incompleteCombos.push({ coins: [coin], sum: coin })
  }

  return []
}

Potential misstep

These wouldn't work for the inner for loop because we are pushing to incompleteCombos inside the loop:

for (let combo of incompleteCombos) {}

for (let i = 0; i < incompleteCombos.length; i++) {}

Both of these would process the newly-pushed combinations, which would be incorrect.

So, the length of incompleteCombos needs to be stored at the beginning of the looping. These two are effectively the same, the second one is just trying to be clever:

for (let i = 0, length = incompleteCombos.length; i < length; i++) {}

for (let i = 0, { length } = incompleteCombos; i < length; i++) {}

Local mutations are all right

2022-10-04T12:00:00+03:00

For example, mutating a reducer function's accumulator array can be better than religiously avoiding mutations and returning only new arrays from the reducer.

Example of a mutating code

I recently published a blog post about how to find all possible combinations of array items in JS. Here's the code:

const getCombinations = (items) =>
  items.reduce((combos, item) => {
    const newCombos = combos.map((combo) => combo.concat(item))
    combos.push([item], ...newCombos)
    return combos
  }, [])

Notice how I'm mutating the accumulator array (combos) in the reducer function by pushing items to it? Gasp!

Mutations can easily lead to confusing code. However, not all mutations are bad.

In this case, the mutations are local – mutations of combos happen only inside the reducer function. Keeping track (mentally) of the mutations is easy.

Avoiding that mutation

The mutations could be avoided e.g. like this:



  const getCombinations = (items) =>
  items.reduce(
    (combos, item) =>
      combos.concat([[item], ...combos.map((combo) => combo.concat(item))]),
    []
  )

Look ma, no mutation! (combos.concat() returns a new array instead of mutating the existing array.)

Or like this:



     const getCombinations = (items) =>
  items.reduce(
    (combos, item) => [
      ...combos,
      [item],
      ...combos.map((combo) => combo.concat(item)),
    ],
    []
  )

But both non-mutating versions are actually horrible:

Inefficient

A new accumulator array is created on each iteration. It doesn't matter with short input arrays, but it does matter with longer input arrays.

In my solution to the Advent of Code 2015/03 puzzle, I found that using the spread syntax made my code a hundred times slower (on my machine) compared to mutating the accumulator array – 10ms vs 1,000ms. (Advent of Code puzzles typically have large inputs.)

Less readable

In the first version (using combos.concat()), it's difficult to see at a glance what the non-mutating one-liner is doing.

Prettier also insists on formatting the reducer function's body on a single line. The following would be clearer (but still not as clear as the non-mutating version):




     const getCombinations = (items) =>
  items.reduce(
    (combos, item) =>
      // prettier-ignore
      combos.concat([
        [item],
        ...combos.map((combo) => combo.concat(item)),
      ]),
    []
  )

The second version (no combos.concat()) is better but still not great (debatable, I guess).

Unnecessary

The accumulator value is quite meant to be mutated – you create an array or an object to which you accumulate values on every iteration.

Saying that the accumulator is meant to be mutated is a bold statement, so I checked what MDN says about array reducers in JS (emphasis added by me):

reduce() is a central concept in functional programming, where it's not possible to mutate any value, so in order to accumulate all values in an array, one must return a new accumulator value on every iteration. This convention propagates to JavaScript's reduce(): you should use spreading or other copying methods where possible to create new arrays and objects as the accumulator, rather than mutating the existing one. [...]

Eh... I respect the MDN docs, but I don't buy that. If you are aiming for maximum purity etc., then maybe yeah. But I would prefer performance and clarity to a rigid functional programming mindset.

I wanted more opinions (:D), so I googled "js reduce mutate accumulator" and found Is mutating accumulator in reduce function considered bad practice? on Stack Overflow. The currently highest-scored answer by "customcommander" has a nice summary:

It isn't [a bad practice] if you own the accumulator.

And that's quite much what I mean by local mutations:

If you own the accumulator, the mutations are local (restricted to the reducer function's scope) and thus safe.
If you don't own the accumulator – if it's coming from elsewhere – the mutations won't be local anymore, so you need to be very careful with the mutations.

If the accumulator is coming from elsewhere, it's easy to shallow-copy it to avoid non-local mutations:






 






 array.reduce(
  (acc, val) => {
    // ...
    return acc
  },
  { ...objectComingFromElsewhere }
)

array.reduce(
  (acc, val) => {
    // ...
    return acc
  },
  [...arrayComingFromElsewhere]
)

But be wary of deep mutations, or do a deep clone instead.

Conclusion

I'll conclude by quoting the last two paragraphs of a relevant article by the author of the aforementioned Stack Overflow answer (two commas added by me for clarity):

Uncontrolled access to shared state can lead to complex bugs which is why immutability is so dear to functional programmers. However, immutability isn't only achieved through the cloning of data, in fact this is most likely to be a naive approach to it. Immutability is a quality of a data structure, not a process per se.

In this particular case the initial value of the reducing function is safe to mutate. The spread operator offers no additional protection against side effects.

In other words: local mutations are all right.

Generating permutations of large arrays is complex

2022-10-03T12:00:00+03:00

That's because it would take a very long time, and at some point you would have so many permutations that they wouldn't fit in an array.

Starting point

By "array permutations" I'm referring to my blog post from yesterday: Generating array permutations with all lengths in JS.

Here's the code:

const getPermutations = (items) =>
  items.reduce((permutations, item) => {
    const newPermutations = permutations.map((permutation) =>
      permutation.concat(item)
    )
    permutations.push([item], ...newPermutations)
    return permutations
  }, [])

getPermutations([1, 2, 3])
//=> [[1],  [2],  [1, 2],  [3],  [1, 3],  [2, 3],  [1, 2, 3]]

RangeErrors

The code throws if the input array's length is too long. In Firefox the limit is 20:

getPermutations(Array.from({ length: 19 })) // OK
getPermutations(Array.from({ length: 20 })) // RangeError

In Firefox, the error message is "too many function arguments."
In Chrome, Edge, Safari and Node.js, the error message is "Maximum call stack size exceeded."

Firefox's error message seems more helpful since the problem is that permutations.push() is called with too many arguments. In Firefox the limit is 500,000 items:

;[].push(...Array(500_000)) // OK
;[].push(...Array(500_001)) // RangeError

Avoiding RangeErrors

We could try to avoid the problem by avoiding the spread syntax altogether:

 const getPermutations = (items) =>
   items.reduce((permutations, item) => {
-    const newPermutations = permutations.map((permutation) =>
-      permutation.concat(item)
-    )
-    permutations.push([item], ...newPermutations)

+    permutations.forEach((permutation) =>
+      permutations.push(permutation.concat(item))
+    )
+    permutations.push([item])

     return permutations
   }, [])

(I thought that this would also increase performance, but it doesn't seem to. Makes sense though: we do avoid iterating through newPermutations which is good, but now we are calling permutations.push() many more times with only one argument.)

It's slow

Now larger input arrays work, but getting permutations for large input arrays is increasingly slow:

console.time()
getPermutations(Array.from({ length: 20 }))
console.timeEnd() //=> ~200ms (on my machine)

console.time()
getPermutations(Array.from({ length: 21 }))
console.timeEnd() //=> ~400ms (on my machine)

console.time()
getPermutations(Array.from({ length: 22 }))
console.timeEnd() //=> ~800ms (on my machine)

console.time()
getPermutations(Array.from({ length: 23 }))
console.timeEnd() //=> ~1800ms (on my machine)

console.time()
getPermutations(Array.from({ length: 24 }))
console.timeEnd() //=> ~4200ms (on my machine)

Ain't nobody got time to wait that long!

The input array's length is still limited

In Firefox, the maximum length of an array seems to be 2 ** 32 - 1:

Array(2 ** 32 - 1) // OK
Array(2 ** 32) // RangeError: invalid array length

The length of the array returned by getPermutations(items) is incidentally 2 ** items.length - 1:

getPermutations(Array.from({ length: 1 })).length === 2 ** 1 - 1 // true
getPermutations(Array.from({ length: 2 })).length === 2 ** 2 - 1 // true
getPermutations(Array.from({ length: 3 })).length === 2 ** 3 - 1 // true
// ...
getPermutations(Array.from({ length: 10 })).length === 2 ** 10 - 1 // true
getPermutations(Array.from({ length: 11 })).length === 2 ** 11 - 1 // true
getPermutations(Array.from({ length: 12 })).length === 2 ** 12 - 1 // true
// ...and so on

(Math for calculating the total number of permutations.)

In other words, the maximum length of the input array is 32.

But input arrays that long would be impractical since getting all permutations would take way too long. Plus there would be quite many permutations: 2 ** 32 - 1 = 4,294,967,295. Over 4 billion!

Think of alternatives

Okay, so the input array's length is limited to 32 (in Firefox at least), and getting all permutations would take a very long time, so think:

Do you need to generate all permutations?
Do you need to retain all permutations?

Some pointers:

If you only need permutations that are e.g. 2 or 3 items long, there's no point in generating longer permutations.
If you are looking for a single permutation that matches a certain criterion, terminate the process after finding your solution.
- Not possible if using an array reducer; use for loops and the break statement instead.
If you are looking for multiple permutations that match a certain criterion, skip non-matching permutations early, i.e. don't store them in the accumulator array.
- Example: JS solutions to the "coin combinations" interview puzzle.
I don't remember if I have ever used generator functions, but this could be a good use case for them. I got this idea from Evan Hahn's blog post Nested array permutations in JavaScript.

Generating array permutations of all lengths in JS

2022-10-02T12:00:00+03:00

Example: converting [1, 2, 3] into [[1], [2], [1, 2], [3], [1, 3], [2, 3], [1, 2, 3]].

Why?

I recall needing this a few times, maybe when solving Advent of Code puzzles.

Plus I really like my solution. I find it straightforward, maybe even obvious now. But it took me a while to come up with it – my first attempts were much more complex and didn't even work properly – and maybe that's why I'm keen on this simple solution.

Example input and output

const array = [1, 2, 3, 4]
getPermutations(array)
/* =>
  [
    [1],
    [2],
    [1, 2],
    [3],
    [1, 3],
    [2, 3],
    [1, 2, 3],
    [4],
    [1, 4],
    [2, 4],
    [1, 2, 4],
    [3, 4],
    [1, 3, 4],
    [2, 3, 4],
    [1, 2, 3, 4],
  ]
*/

Code

const getPermutations = (items) =>
  items.reduce((permutations, item) => {
    const newPermutations = permutations.map((permutation) =>
      permutation.concat(item)
    )
    permutations.push([item], ...newPermutations)
    returnpermutations
  }, [])

Probably not the most efficient solution, but straightforward and easy. And no for loops!

Order of permutations

The order of the final permutations change if you change the order of the push method's arguments:







 

 






 

 const items = [1, 2, 3]

items.reduce((permutations, item) => {
  const newPermutations = permutations.map((permutations) =>
    permutations.concat(item)
  )
  permutations.push([item], ...newPermutations)
  return permutations
}, [])
//=> [[1],  [2],  [1, 2],  [3],  [1, 3],  [2, 3],  [1, 2, 3]]

// versus

items.reduce((permutations, item) => {
  const newPermutations = permutations.map((permutations) =>
    permutations.concat(item)
  )
  permutations.push(...newPermutations, [item])
  return permutations
}, [])
//=> [[1],  [1, 2],  [2],  [1, 3],  [1, 2, 3],  [2, 3],  [3]]

In some cases the order might matter.

Beware too large input arrays

The code doesn't work if the input array's length is 20+:

getPermutations(Array.from({ length: 19 })) // OK
getPermutations(Array.from({ length: 20 })) // RangeError

More details in Part 2: Generating permutations of large arrays is complex.

Mutation

Notice how I'm mutating the accumulator array (permutations) in the reducer function?

Mutations can be bad, but in this case they are okay, because local mutations are all right.

I want a chat app with an "unreplied" message state

2022-09-28T12:00:00+03:00

Most chat apps have an "unread" message state to keep track of messages I haven't read yet. Why isn't there a different state for messages I haven't replied to yet?

I chat with my bro a lot. We always have several conversations ongoing at the same time.

We currently use Telegram, so all messages are in a single big list.

When replying to his messages, I basically have two options:

Reply to all unreplied messages in a single session. I don't like this because:
- It would often take a very long times, sometimes even several hours (like I said, we chat a lot!).
- Sometimes it's better to ponder things before replying.
Reply to some messages now and some messages later. I don't like this because:
- It gets very difficult to keep track of messages I have or haven't replied to.

And sometimes I want to start a new conversation and not reply to any previous messages. This alone makes keeping track of replied/unreplied messages difficult.

We have previously tried a private Discord server with several channels – one main topic per channel, e.g. "dev" or "health." Having several channels helps a bit, but the core problem is still the same: it's difficult to keep track of replied/unreplied messages in each channel.

One level deep sub-threads (like on Discord or Slack) don't help either: it's difficult to keep track of replied/unreplied messages in each sub-thread. Sub-threads might even make things more confusing.

A tree-like message structure (like on Reddit or Hacker News) could help organize messages because not all messages would be in a single big list (or several big lists if using channels), but it wouldn't solve the problem of keeping track of replied/unreplied messages. Plus maybe a tree-like structure would get in the way of quick, comfortable chatting.

So here's what I want:

An "unreplied" message state for keeping track of replied/unreplied messages.
Threads for organizing messages by conversation.
- New conversation = new thread.
- Flat threads (no nesting, i.e. no sub-threads or tree-like structure) to keep things simple.
- Threads are superior to channels: no need to think of the most suitable channel/topic for a new conversation; just start a new thread.

Maybe I should create my own chat app. 🤷‍♂️

LTeX: grammar/spell checker on steroids for VS Code

2022-09-20T12:00:00+03:00

Doesn't only look for typos but for grammar and style issues as well. Not to be confused with LaTeX.

About LTeX

LTeX is a grammar/spell checker for VS Code. It uses LanguageTool under the hood and supports LaTeX, Markdown and more.

I have been using LTeX for half a year now. It's great!

Note that LTeX is not the same as LaTeX, the "document preparation system."

Check out the LTeX extension for VS Code

Pros

Checks for spelling issues (typos)
Checks for grammar issues
Checks for style issues
- Example: "Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym." I get this often when starting too many sentences with the word "I" (maybe I love myself too much)
Explains why things are (or might be) wrong instead of just complaining
Works offline
Is privacy-friendly (because works offline)
Is easy to set up: install the VS Code extension and the rest will be auto-installed
Provides quick fixes (Meta+.)
Doesn't slow down VS Code (at least not on my machine; some other spell checker extensions have been horribly slow)
Works even if you split sentences to multiple lines
- Related: 4 + 1 wrapping styles for Markdown prose and code comments

Cons

Doesn't support Finnish
Doesn't support disabling checking for a single document/file
- There's "LTeX: Clear Diagnostics in Current Document" in VS Code's Command Palette, but the extension runs again when you type or erase even a single letter
Sometimes leaves stray Java processes behind
- It might be a good idea to manually terminate the stray processes from time to time, especially if you are low on RAM

Linen bedclothes are the best

2022-09-17T12:00:00+03:00

I recently switched from linen bedclothes (sheets, pillowcases, duvet covers) back to cotton bedclothes – bad idea. My sleep quality took a drastic hit.

Sometimes you notice the importance of something only after losing that thing. This is such a case.^[1]

I have been using linen bedclothes for almost two years.

Recently I started using a second set of bedclothes to make laundry days easier – no need to wash the bedclothes first thing in the morning if I have more than one set of bedclothes.^[2]

However, the second set of bedclothes is made of cotton. I didn't remember how bad cotton bedclothes are:

Cotton doesn't breathe properly.
Cotton feels "hard" (not soft).

It's possible that not all cotton bedclothes are bad, but mine are.

Last night I slept again with my linen bedclothes – and boy are they wonderful! I'll ditch the cotton bedclothes as soon as I have ordered a second set of linen bedclothes (so hopefully before next year).

Footnotes

I didn't lose my linen bedclothes. I lost my higher quality sleep for a while. ↩
It's not a big deal to wash the bedclothes first thing in the morning, but if you forget and do it later in the day, they might not get dry enough before the night. ↩

Updating a private Git submodule before builds in Netlify

2022-09-15T12:00:00+03:00

Automatically updating a private Git submodule before builds is convenient but requires some setup.

Why a private Git submodule

My website is open source, but the blog posts and other content reside in a separate, private Git repo.

Tania Rascia explains her rationale for her similar setup in her blog post Using Git Submodules for Private Content:

My website has been open source for as long as it has existed. Originally, it was a WordPress site, but only the layout was out there for everyone to see since the data was saved in a database. Once I moved to Gatsby, I kept all the images and posts in a content directory. This was way better, as my content is all conveniently stored in one easy-to-save folder and the posts are all in beautiful markdown.

However, people often like my layout and want to use it, so they clone and deploy this site. Sometimes they will just leave up all the posts and images and update the name and image. Although I subscribe to the Zenhabits Uncopyright philosophy towards content – my content is out there for the world to see and do what they want with it, and it doesn't bother me – I don't think I should make it quite so easy to just clone everything I've written in a moment. If you're going to plagiarize, you should at least have to do a bit of work.

Another benefit: I can store my sloppy drafts and scheduled posts in my private Git repo so that no one can see them (except me of course).

Why automatic updating

From the summary of the aforementioned blog post by Tania Rascia:

My current process for updating the site looks like:

Make changes to content repo.

Commit changes to content and push to private submodule hosted on GitHub: git commit && git push.

Pull new updates into local taniarascia.com repo: git submodule update --remote.

Commit the new submodule changes and push to public GitHub repo: git commit && git push.

Netlify deploys the new site.

That's cool, but I don't want to update my website repo after modifying my content repo. My process looks like this:

Same as above. (Make changes to content repo.)
Same as above. (Commit changes to content and push to private submodule hosted on GitHub: git commit && git push.)
Netlify deploys the new site automatically on the next day because I have set up automatic daily Netlify builds using GitHub Actions. Alternatively I can manually trigger a build on the Netlify dashboard if I want the content changes to go live immediately (in a few minutes).

There are two benefits to this way of working:

I need to work with only one Git repo (the content repo) to write content.
I can avoid the frequent "update content submodule" commits in my website repo.

My website repo points to a commit from 1st Jan 2021 on the content repo, meaning that I haven't needed an "update content submodule" commit on the website repo in almost two years. This is possible because Netlify automatically updates the private Git submodule (i.e. pulls the latest changes) before it builds the site.

How-to

First, check out the aforementioned blog post by Tania Rascia. It's a good primer on the subject.

When you have a private Git submodule set up, here are pointers how to make Netlify automatically update it before builds. These pointers are based on a support guide on Netlify Support Forums, but I had to trial and error quite a bit before I got it all working.

Deploy key + SSH key

You need to add two keys on your private Git repo's settings page on GitHub:

Netlify deploy key: this is needed so that Netlify can initially access the private submodule. Check the blog post by Tania Rascia for a guide.
A new SSH public key: this is needed so that Netlify can update the private submodule (i.e. pull the latest changes) before it starts building the site.

Steps:

Generate a new SSH key
- Example on Mac: ssh-keygen -t ed25519 -C "yoursite.com content repo / Netlify"
- The -C flag stands for "comment" – it's for you so you later know/remember what this SSH key is for
- Save the file e.g. to /Users/you/.ssh/yoursite.com-content-netlify
- Don't set a password or Netlify can't update the submodule
Add the public key (the shorter one) as a read-only deploy key on your private repo's settings page on GitHub
- Name it e.g. "SSH public key (Netlify)" so you can tell it apart from the other deploy key ("Netlify deploy key")

Note:

After changing the build image on Netlify (the previous one I was using was going to be deprecated), the Netlify deploy key changed too, so I had to add the new deploy key to the private Git repo's settings on GitHub. (I'm not 100% sure about this.)

Environment variable

Add the private SSH key (the longer one) to your Netlify site's environment variables. Before that though you need to modify the key because environment variables are single-line (not multi-line).

Your private key looks something like this:

-----BEGIN OPENSSH PRIVATE KEY-----
n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is
...
-----END OPENSSH PRIVATE KEY-----

Replace the newlines with underscores (e.g. in VS Code or Notepad) so that it looks like this:

-----BEGIN OPENSSH PRIVATE KEY-----_n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is_..._-----END OPENSSH PRIVATE KEY-----_

Note: it doesn't matter whether the private key has a trailing underscore or not.

Bash script

To let Netlify use the SSH key from the environment variables, create a file called e.g. netlify-setup.sh and save it to the website repo's root:

#!/usr/bin/env bash

# Credit goes to fool and hongaar at
# https://community.netlify.com/t/support-guide-using-an-ssh-key-via-environment-variable-during-build/2457

# Check if we're running in a Netlify environment
# See https://www.netlify.com/docs/continuous-deployment/#environment-variables
if [ ! -z "${DEPLOY_PRIME_URL}" ]; then
    # Init .ssh dir and expand $SSH_KEY
    mkdir -p ~/.ssh
    echo -e "${SSH_KEY//_/\\n}" > ~/.ssh/id_rsa
    chmod og-rwx ~/.ssh/id_rsa

    # Uncomment to debug
    # ls -la ~/.ssh
    # cat ~/.ssh/id_rsa

    # Add host keys
    ssh-keyscan -H github.com >> ~/.ssh/known_hosts
fi;

Build command

Last step! Modify your build command (e.g. npm run build) to first run the Bash script, then update the private Git submodule, and then build the site.

There might be several ways to do this. I did it by specifying this as my build command in the netlify.toml file:

[build]
  command = """
    bash ./netlify-setup.sh &&
    GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no" \
      git submodule update --init --remote &&
    npm run build
  """

Mortgage calculations in JS: annuity and fixed principal

2022-09-13T12:00:00+03:00

Instead of spending 5 minutes to look for and use an existing mortgage calculator, I wasted time figuring out how to do the calculations from scratch.

Annuity vs fixed principal

In annuity the monthly payment is fixed (until the interest rate changes).
In fixed principal the monthly payment gets smaller after each month; the first payment is the largest and larger than in annuity.
Fixed principal is cheaper over the whole mortgage period (less total interest fees), but annuity is more affordable in the short term.

I recall reading recently that annuity is used in like 99% of mortgages in Finland. I can't find that article anymore though, so I don't know if it's actually 99% or more like 90%.

Btw, MathJax

Enable MathJax by clicking the button below for a better reading experience. It's opt-in because it's a largish download (300+ KB).

(It would be nice to run MathJax during the website's build process, but I'm too lazy to do that now. I just want to publish this post.)

Annuity

Wikipedia has a clear annuity formula:

$$ A = \frac{P \times i} {(1 - (1 + i)^{-n})} $$

Where:

$A$ = monthly payment amount (= monthly principal + monthly interest)
$P$ = total loan amount
$i$ = monthly interest rate (percentage)
$n$ = total number of payments (= number of months)

On that same Wikipedia page, there's a formula for calculating the remaining loan amount after $t$ months (function $p(t)$):

$$ p(t) = Pr^t - A \frac{r^t - 1}{r - 1} $$

Where:

$$r = 1 + i$$

It's clearer to use $1 + i$ in place of $r$:

$$ p(t) = P(1 + i)^t - A \frac{(1 + i)^t - 1}{(1 + i) - 1} $$

Because now we can simplify $(1 + i) - 1$ to just $i$:

$$ p(t) = P(1 + i)^t - A \frac{(1 + i)^t - 1}{i} $$

In JavaScript, with an opening fee and extra monthly fees (not included in the formulas above):

const calculateAnnuity = ({
  loanAmount,
  monthlyFee,
  monthlyInterestPercentage,
  months,
  openingFee,
}) => {
  const monthlyAnnuity =
    (loanAmount * monthlyInterestPercentage) /
    (1 - (1 + monthlyInterestPercentage) ** -months)

  const monthlyPayment = monthlyAnnuity + monthlyFee
  const totalPayable = openingFee + monthlyPayment * months
  const totalFees = totalPayable - loanAmount

  const loanAmountLeftAfterOneYear =
    loanAmount * (1 + monthlyInterestPercentage) ** 12 -
    monthlyAnnuity *
      (((1 + monthlyInterestPercentage) ** 12 - 1) / monthlyInterestPercentage)

  return {
    monthlyPayment,
    totalPayable,
    totalFees,
    loanAmountLeftAfterOneYear,
  }
}

Fixed principal

The formulas are much simpler because the monthly principal amount is fixed:

monthly payment amount = monthly principal + interest for the remaining loan amount
- monthly principal = loan amount / number of months
- interest for the remaining loan amount = remaining loan amount × monthly interest rate
loan left after $t$ months = loan amount - monthly principal × $t$

In JavaScript:

const calculateFixedPrincipal = ({
  loanAmount,
  monthlyFee,
  monthlyInterestPercentage,
  months,
  openingFee,
}) => {
  const monthlyPrincipal = loanAmount / months

  const monthlyPayments = Array.from({ length: months }, (_, monthIndex) => {
    const interest =
      (loanAmount - monthlyPrincipal * monthIndex) * monthlyInterestPercentage
    return monthlyPrincipal + interest + monthlyFee
  })
  const firstMonthPayment = monthlyPayments[0]
  const lastMonthPayment = monthlyPayments.at(-1)

  const sum = (array) => array.reduce((a, b) => a + b, 0)
  const totalPayable = openingFee + sum(monthlyPayments)

  const totalFees = totalPayable - loanAmount
  const loanAmountLeftAfterOneYear = loanAmount - monthlyPrincipal * 12

  return {
    firstMonthPayment,
    lastMonthPayment,
    totalPayable,
    totalFees,
    loanAmountLeftAfterOneYear,
  }
}

Example

const referenceRate = 1.482 // E.g. Euribor 12
const margin = 0.55

const specs = {
  loanAmount: 135_000,
  monthlyFee: 2.5,
  monthlyInterestPercentage: (referenceRate + margin) / 12 / 100,
  months: 25 * 12,
  openingFee: 150,
}

calculateAnnuity(specs)
//=> {
//   monthlyPayment:                 576.81,
//   totalPayable:               173_192.65,
//   totalFees:                   38_192.65,
//   loanAmountLeftAfterOneYear: 130_812.64,
// }

calculateFixedPrincipal(specs)
//=> {
//   firstMonthPayment:              681.10,
//   lastMonthPayment:               453.26,
//   totalPayable:               170_304.30,
//   totalFees:                   35_304.30,
//   loanAmountLeftAfterOneYear: 129_600.00,
// }

As you can see, fixed principal is more expensive in the beginning but cheaper in the long term (less total fees). Also, at some point the monthly payments become less than in annuity.

Thoughts

At first I though that fixed principal would be better because it incurs less total fees, but on the other hand:

With my specs (see above) the difference in total fees is only 2,888.35 € over 25 years – that's only 115.53 € per year, or 9.63 € per month. Not very much.
Less than ten bucks per month is not a high price to pay to get consistent monthly payments and more affordable payments in the beginning. Especially the second point (more affordable payments in the beginning) feels more important than slightly smaller total fees over a long period of time (25 years! I'm hardly that old myself).

Here's why I wanted to calculate how much of the loan amount would be left after one year:

Interest rates have recently been increasing rapidly.
My reference rate is tied to Euribor 12, i.e. the rate is updated every 12 months.
I wanted to check how much the monthly payments would be after one year if the interest rate had raised to 6% (stress test) – would it matter whether I had been paying the first year with annuity or fixed principal?
The difference in the remaining loan amount after one year is only 1,212.64 €, so the effect on the stress test scenario is negligible. So no, it doesn't really matter which payment type I use in the first year.
- There is something I could do to make my life easier in a stress test scenario: choosing annuity would make the first monthly payments significantly cheaper (around 250 € in my case).

To help me choose:

I should choose fixed principal if I want to:
- Save less than 3k € in 25 years. Not a compelling reason.
- Pay less each month after some point. Not very interesting because that would be in the distant future.
I should choose annuity if I want to:
- Pay about 100 € less each month (in the beginning). This sounds good; I could instead invest the money (either in an index fund or in cheese! I like cheese).
- Pay less in a stress test scenario (6% interest rate). This would increase my peace of mind.

I think I might go with annuity.

Demo

I started building a calculator for comparing mortgages but lost interest quite quickly, so here's a half-baked demo:

Mortgage calculator on flems.io

Sorting a read-only array is OK if it has only 1 or 0 items

2022-09-01T12:00:00+03:00

Huh. But if the array has 2+ items, attempting to sort it will cause a TypeError.

Example 1

Object.freeze([]).sort() // OK
Object.freeze(['a']).sort() // OK
Object.freeze(['a', 'b']).sort() // TypeError

Errors in different browsers:

Chrome / Edge: "TypeError: Cannot assign to read only property '0' of object '[object Array]'"
Firefox: "TypeError: 0 is read-only"
Safari: "TypeError: Attempted to assign to readonly property."

Example 2

const arr = []
arr[1] = 'b'
Object.freeze(arr)
arr.sort() // TypeError

The errors are slightly different:

Chrome / Edge: "TypeError: Cannot add property 0, object is not extensible"
Firefox: "TypeError: can't define property 0: Array is not extensible"
Safari: same as in Example 1

Pondering

I use mainly Firefox. Its error message "0 is read-only" is not very enlightening, so when investigating a related bug, I didn't grasp at first that the problem was about a read-only array. Meh.

If an array is empty or has only one item, sorting the array won't modify the array because there are not enough items to move around. So no error even if the array is read-only. Makes sense but was surprising (hence this blog post).

On the other hand: if a read-only array has 2+ items and is already sorted, trying to sort it causes a TypeError, even though the array is already sorted! Makes sense but is also mildly confusing – why is the array being modified if it's already sorted?

If a read-only array has only empty slots, sorting it is OK, which is weird:

const arr = Object.freeze(Array(3))
arr.length //=> 3
arr.sort() // OK but weird

Fix 1

The sort() method sorts an array in-place, i.e. sorting an array modifies it.

You might want to first copy the array with slice() and then sort the copied array:

const arr = Object.freeze(['a', 'b'])
arr.sort() // TypeError
arr.slice().sort() // OK

Fix 2

TypeScript would have spotted the error for me right away:

const arr = Object.freeze(['a', 'b'])
arr.sort()
//  ^? Property 'sort' does not exist on type 'readonly string[]'.

On the other hand, the TypeScript compiler doesn't seem to know that sorting a read-only array is OK if the array has only 1 or 0 items:

const arr = Object.freeze(['a'])
arr.sort()
//  ^? Property 'sort' does not exist on type 'readonly string[]'.

// 👆 Compile-time error but no runtime error, so 🤷‍♂️

Ha! 😄

On a serious note: I think it's better that the TypeScript compiler always disallows sorting read-only arrays.

Correct tongue position in 3 steps

2022-08-16T12:00:00+03:00

Say "n" and cluck and relax. Easy! Correct tongue position makes nasal breathing easier.

Step 1: Find the right spot for the tip of the tongue

The right spot is in the roof of the mouth, behind the upper front teeth.

Saying the letter "n" aloud will guide the tip of the tongue to the right spot.

Step 2: Place the rest of the tongue against the roof of the mouth

Placing the whole tongue to the roof of the mouth will pull down the roof of the mouth (i.e. the hard palate). The roof of the mouth is also the floor of the nose, so this helps increase the nasal space, making breathing through the nose easier.

One way to guide the whole tongue to the roof of the mouth is to cluck with your tongue. (Check the video link below for an example.)

Step 3: Relax

Keep your lips together gently. Relax the whole head as well:

Relax the tongue
Relax the lips
Relax the jaws
Relax the eyes
Relax the face

Bonus: Relax the diaphragm

Keep the diaphragm relaxed as well and practice diaphragmatic breathing at all times.

Video guide

The three steps are from a YouTube video called STOP Mouth Breathing – Try This that I accidentally found when looking for something else. (I slightly expanded the 3rd step above and added the bonus step.)

The video starts by explaining some benefits of nasal breathing. The 3-step instructions start at 1:42 of the video.

Why?

Nasal breathing (i.e. breathing in and out through the nose) at all times is essential for your health. "At all times" includes breathing while sleeping and during exercise!

If you are into running, try running with the mouth closed. It will be hard at first, but try it for a month. I'm sure you'll like it so much more that you'll never want to run with an open mouth anymore.

The 2nd step is important

I'm calling it out because I have been practicing nasal breathing for several years, but I didn't know that the whole tongue should be against the roof of the mouth. Whoops. 🙉 I just recently learned it from the video.

Now nasal breathing without the 2nd step – i.e. with the tip of the tongue at the roof of the mouth but the rest of the tongue hanging at the floor of the mouth – feels somewhat weird. Probably because without the step the nasal space is reduced.

Don't make the mistake that I was doing for several years. 🤙

Running vs jogging

2022-08-15T12:00:00+03:00

Jogging is one type of running. When I run, I mostly jog, but I still think I'm a runner, not a jogger. Huh?

Here's one definition for jogging on Dictionary.com:

to run at a leisurely, slow pace, especially as an outdoor exercise

So, jogging is slow running.

Jogging is running, but not all running is jogging. For example, sprinting is also running (but sprinting is not jogging).

What is "slow running" is personal. If you are running and feel that you could easily run faster, maybe your current pace is a jogging pace (i.e. a slow pace).

It doesn't matter much which word you use. Though sometimes the distinction can be useful as someone writes on Reddit:

I feel like they're interchangeable for the most part.

But like, if I'm talking to a non-runner about my workouts for some reason, I might say something like "I'll run fast for a mile, then jog for a half mile, and repeat that six times" just because I feel like they'll get that "jog" means "run slower" in that instance.

"Running" also sounds cooler than "jogging," so I consider myself a runner, even though I almost always aim for easy runs.

Stop keeping your phone in your pocket

2022-08-04T12:00:00+03:00

A trouser pocket is way too easily reachable. I often find myself reaching for my phone automatically even if I don't have anything to do with the phone.

Discipline

Maybe you can reduce your phone usage with discipline, but then it doesn't make sense to keep your phone one hand gesture away. It won't be just about discipline anymore; it will also be about addiction and automatic habits.

Addiction

Addiction is easily more powerful than discipline. Especially if you need to be disciplined all the time, like if you have your phone always easily reachable (in your pocket). Trying to be disciplined all the time wastes mental energy.

It doesn't make sense for a drug addict to keep drugs in their pocket.

If you are addicted to your phone – and I think most people are – you are a junkie and your phone is your drug.

Automatic habits

Taking a phone from your pocket is just one step: put your hand in your pocket and grab the phone. It's easy to do that automatically, without even thinking about that.

Trying to avoid automatic habits wastes mental energy too. Instead, make the habit impossible – keep your phone away from your pocket.

If you are at home, keep your phone out of sight, like in a closet behind doors (but not in your bedroom!).

If you are elsewhere, keep your phone in a back bag. Taking your phone now requires more than one step: first you have to take the bag from your back, than open a zipper, and then can you grab the phone. Doing these steps probably isn't very automatic.

A fanny pack would be cool too, though I wonder if taking a phone from one would quickly become too easy and automatic.

Toggleable React state with a 1-line `useReducer`

2022-06-05T12:00:00+03:00

Say goodbye to useState and a silly toggler function calling the state setter. Be cool and use a tiny reducer instead.

Example: "enabled" state

Typical solution with `useState`

function Component() {
  const [enabled, setEnabled] = useState(true)
  const toggleEnabled = () => setEnabled((previous) => !previous)

  return <button onClick={toggleEnabled}>Toggle</button>
}

2 lines – so long and verbose!

Cool solution with `useReducer`

React's useReducer hook takes a reducer function and an initial value:

function Component() {
  const [enabled, toggleEnabled] = useReducer((previous) => !previous, true)

  return <button onClick={toggleEnabled}>Toggle</button>
}

Only 1 line. So cool! 😎

This is a bit cryptic at first, and maybe I wouldn't use it in any "real" code, but I found this intriguing and wanted to share it.

I picked this from TkDodo's blog post Things to know about useState (from the "Bonus 2" section).

Another example: toggling a numeric value

Toggling between 250 and 750:

function Component() {
  const [duration, toggleDuration] = useReducer(
    (previous) => (previous + 500) % 1000,
    250
  )

  return <button onClick={toggleDuration}>Toggle</button>
}

Whoops, 4 lines. 🥲 But I invented this myself! 😄

1 line of code to animate element additions, removals and moves

2022-05-28T12:00:00+03:00

AutoAnimate is a JS library that provides simple animations with no effort. Works with Mithril.js, React and any other JS app.

Highlights

AutoAnimate is a "zero-config, drop-in animation utility"
Improves UX very much
- Animated element modifications are easier to spot
Very easy to use: just a single function (or React hook)
- Great for business apps when you can't spend time on fancy stuff like animations (but great for other apps as well)
Very lightweight
- BundlePhopia reports AutoAnimate's minzipped size to be only 2.2 KB

React.js example

From AutoAnimate's website:

import { useAutoAnimate } from '@formkit/auto-animate/react'

function MyList() {
  const [animationParent] = useAutoAnimate()
  return <ul ref={animationParent}>{/* 🪄 Magic animations for your list */}</ul>
}

If the import statement is not counted, that's only two lines of code. Nice!

(The Mithril.js example below works with only one line of code.)

Empty `<ul>` is problematic

If you don't want to render an empty <ul> element, you need to use AutoAnimate on the <ul>'s parent element too:

import { useAutoAnimate } from '@formkit/auto-animate/react'

function MyList({ items }) {
  const [parent] = useAutoAnimate()
  const [list] = useAutoAnimate()

  return (
    <div ref={parent}>
      {items.length > 0 && <ul ref={list}>{/* Render items */}</ul>}
    </div>
  )
}

But there's currently an open React-specific GitHub issue that AutoAnimate doesn't work with containers that are not initially rendered.

Manual exit animations would be difficult

Animating the removal of an element is tricky in React because when React removes an element from the DOM, the element is removed immediately. There's no time to run CSS animations.

If I interpreted AutoAnimate's source code correctly, it animates element removal like this:

React (or whatever you're using) removes an element from the DOM.
AutoAnimate adds the element back to the DOM!
AutoAnimate triggers an animation for the element.
AutoAnimate removes the element from the DOM after the animation is finished.

Sounds a bit hacky and risky to modify a React-rendered DOM like this, but seems to work fine. Quite clever actually!

Mithril.js example

Mithril.js is so cool that you only need one line of code:

import autoAnimate from '@formkit/auto-animate'

function MyList() {
  return {
    view: () =>
      m('ul', { oncreate: (vnode) => autoAnimate(vnode.dom) }, [
        // Render items
      ]),
  }
}

The oncreate lifecycle hook in Mithril.js is like the good old componentDidMount lifecycle method in React.

vnode.dom points to the DOM element, so it's like a ref in React.

In Mithril.js, components and virtual DOM nodes have lifecycle hooks and "automatic" refs (no need for something like createRef or useRef). Super useful.

Empty `<ul>` is no problem

Like with React, you'll still need to use AutoAnimate on the <ul>'s parent element too if you don't want to render an empty <ul>:

import autoAnimate from '@formkit/auto-animate'

function MyList() {
  return {
    view: ({ attrs: { items } }) =>
      m('div', { oncreate: (vnode) => autoAnimate(vnode.dom) }, [
        items.length > 0 &&
          m('ul', { oncreate: (vnode) => autoAnimate(vnode.dom) }, [
            // Render items
          ]),
      ]),
  }
}

But the aforementioned React-specific issue is not a problem with Mithril.js, things just work. Did I say that Mithril.js is cool!

Manual exit animations would be... easy!

The onbeforeremove lifecycle hook in Mithril.js makes implementing exit animations easy. From the docs (code example slightly edited by me):

The onbeforeremove(vnode) hook is called before a DOM element is detached from the document. If a Promise is returned, Mithril.js only detaches the DOM element after the promise completes. [...]
const Fader = {
  onbeforeremove(vnode) {
    vnode.dom.classList.add('fade-out')
    return new Promise((resolve) => setTimeout(resolve, 1000))
  },
  view: () => m('div', 'Bye'),
}

AutoAnimate still has its place though – it's great for adding quick and easy animations with no effort.

Your Button component should default to `type="button"`

2022-05-27T12:00:00+03:00

A <button> element defaults to type="submit" which can cause accidental form submissions. Make type="button" the default in your Button component to make your life easier.

`type="button"` vs `type="submit"`

A <button> element without a type attribute defaults to type="submit". Clicking a submit button associated with a <form> submits the form unless event.preventDefault() is called.

A <button> element with type="button" on the other hand does nothing by default when clicked. Calling event.preventDefault() does nothing because there's no default action to prevent.

Setting your Button component to default to type="button" allows you to not worry about:

accidental form submissions
having to remember call event.preventDefault().

Also, using <Button type="submit"> makes it explicit that it's a submit button.

Example with React and TypeScript

type Props = React.ButtonHTMLAttributes<HTMLButtonElement> & { type?: 'submit' }

const Button = ({ children, type, ...props }: Props) => (
  <button {...props} type={type || 'button'}>
    {children}
  </button>
)

// Usage:

<Button /> // Defaults to `type="button"`
<Button type="submit" />

The type prop's value in React.ButtonHTMLAttributes<HTMLButtonElement> is "submit" | "button" | "reset" | undefined. I'm restricting the value to "submit" | undefined, so that only type="submit" is allowed. (Omitting the prop is also allowed.)

type="button" is not allowed because it's the default, so it would be unnecessary noise.
type="reset" is not allowed because reset buttons (i.e. buttons that empty the whole form) are so stupid. 🤡 Not on my watch!

Preventing "illegal invocation" errors in TypeScript

2022-04-17T12:00:00+03:00

The TypeScript compiler could help prevent "illegal invocation" errors at compile time, at least theoretically.

Illegal invocation errors?

Chromium browsers throw an "illegal invocation" error when calling a function whose this keyword isn't referring to the object where it originally did, i.e. when the "context" of the function is lost.

Other browsers and Node.js produce different error messages.

Check out my earlier blog post for more details: "Illegal invocation" errors in JavaScript.

TypeScript is of no help by default

By default, TypeScript doesn't balk at this code, resulting in runtime errors when calling the functions:

const abortController = new AbortController()
const { abort } = abortController

abort() //=> TypeError: Illegal invocation

const $ = document.querySelector
const $$ = document.querySelectorAll

$('#foo') //=> TypeError: Illegal invocation
$$('.bar') //=> TypeError: Illegal invocation

Declaring the type of `this`

TypeScript could spot the errors at compile time because you can declare the type of a function's this keyword in TypeScript.

For example, the default Document interface specifies the querySelector method like this:

interface Document {
  querySelector<K extends keyof HTMLElementTagNameMap>(
    selectors: K
  ): HTMLElementTagNameMap[K] | null
  querySelector<K extends keyof SVGElementTagNameMap>(
    selectors: K
  ): SVGElementTagNameMap[K] | null
  querySelector<E extends Element = Element>(
    selectors: string
  ): E | null

  // + many other methods and properties
}

(The querySelector method is specified three times on purpose; this is called function overloading.)

If the interface also specified the type of the querySelector method's this keyword, the TypeScript compiler wouldn't let you call the method illegally:



 


 


 






 interface Document {
  querySelector<K extends keyof HTMLElementTagNameMap>(
    this: Document,
    selectors: K
  ): HTMLElementTagNameMap[K] | null
  querySelector<K extends keyof SVGElementTagNameMap>(
    this: Document,
    selectors: K
  ): SVGElementTagNameMap[K] | null
  querySelector<E extends Element = Element>(
    this: Document,
    selectors: string
  ): E | null
}

document.querySelector('.foo') // OK

const $ = document.querySelector
$('.foo') // Compile-time error

// This method hasn't been patched:
const $$ = document.querySelectorAll
$$('.foo') // OK at compile time but results in a runtime error

The compile-time error would be something like this:

The 'this' context of type 'void' is not assignable to method's 'this' of type 'Document'.

Demo on TS Playground

Declaration merging

You could actually copy that partial interface (with only the patched querySelector methods) to your codebase. It would be merged with the default Document interface because of declaration merging.

However, to get comprehensive compile-time safety against "illegal invocation" errors, you would need to:

Specify the type of the this keyword for all applicable methods of the Document interface.
Do the same for other interfaces as well, e.g. the AbortController interface.

This doesn't feel like it belongs to application code.

Ideally the interfaces would be fixed in TypeScript. Or maybe there could be a library that exports patched interfaces that you could import once in your own code.

Note that in your own methods you can:

Declare strict types for the this parameter.
Use better error messages than "illegal invocation."
Avoid the this parameter altogether.

Client-side navigation and React's `dangerouslySetInnerHTML`

2022-04-03T12:00:00+03:00

To handle internal link clicks when using dangerouslySetInnerHTML, attach click event listeners to the rendered links. In the listener, push the link to the browser history.

Overview

Render the HTML with dangerouslySetInnerHTML. Remember to use only safe HTML!
When the component mounts, attach click event listeners to the links. In the event listener, push the link to the browser history if it's an internal link.
When the component unmounts, remove the click event listeners to avoid memory leaks.

Sample code

Using TypeScript:

import React, { RefObject, useEffect, useRef } from 'react'
import { useNavigate } from 'react-router-dom'

export default function HtmlContent({ html }: { html: string }) {
  const ref = useRef<HTMLDivElement>(null)
  useLinkClickHandlers(ref)

  return <div dangerouslySetInnerHTML={{ __html: html }} ref={ref} />
}

function useLinkClickHandlers(ref: RefObject<HTMLDivElement>) {
  const navigate = useNavigate()

  useEffect(() => {
    if (!ref.current) return

    const links = ref.current.querySelectorAll('a')
    links.forEach((link) => link.addEventListener('click', handleLinkClick))

    return () => {
      links.forEach((link) =>
        link.removeEventListener('click', handleLinkClick)
      )
    }

    function handleLinkClick(event: MouseEvent) {
      const link = event.currentTarget as HTMLAnchorElement
      const href = link.getAttribute('href')
      const target = link.getAttribute('target')
      const url = new URL(href || '', window.location.origin)

      const isInternalLink = url.origin === window.location.origin
      const isOpenedInSameWindow = !target || target === '_self'
      const isLeftButtonClick = event.button === 0

      // E.g. Ctrl-clicking a link opens it in a new tab
      // so let the browser handle such clicks
      const isModifierKeyPressed =
        event.altKey || event.ctrlKey || event.metaKey || event.shiftKey

      if (
        isInternalLink &&
        isOpenedInSameWindow &&
        isLeftButtonClick &&
        !isModifierKeyPressed
      ) {
        event.preventDefault()
        navigate(url.pathname + url.search + url.hash)
      }
    }
  }, [navigate, ref])
}

I'm using React Router's useNavigate hook. If you don't use React Router, you can do something similar yourself. The useNavigate hook pushes the link to the browser history (or replaces instead of pushes, depending on how the hook is used).

The handleLinkClick function is similar to React Router's useLinkClickHandler hook (which can't be used in this case since it takes a link address as a parameter).

Usage

// This could come from a content management system (CMS) for example
const myHtml = /* HTML */ `
  <p>Hello from HTML!</p>
  <p>
    Here's an internal link:
    <a href="/foo">foo</a>
  </p>
  <p>
    Another link:
    <a href="/bar" target="_blank">bar</a>
  </p>
`

function App() {
  return <HtmlContent html={myHtml} />
}

By the way, because of the /* HTML */ comment, Prettier formats the template literal as HTML.

Why not attach a click event listener to the parent?

Instead of finding all <a> elements and attaching click event listeners to them, you technically could attach a click event listener only to the parent <div>. In the listener function you could then check if the click was done over a link, and then handle the link click like in the code above. Like so:

















  

    import React, { RefObject, useEffect, useRef } from 'react'
import { useNavigate } from 'react-router-dom'

export default function HtmlContent({ html }: { html: string }) {
  const ref = useRef<HTMLDivElement>(null)
  useLinkClickHandler(ref)

  return <div dangerouslySetInnerHTML={{ __html: html }} ref={ref} />
}

function useLinkClickHandler(ref: RefObject<HTMLDivElement>) {
  const navigate = useNavigate()

  useEffect(() => {
    if (!ref.current) return

    ref.current.addEventListener('click', handleLinkClick)
    return () => ref.current.removeEventListener('click', handleLinkClick)

    function handleLinkClick(event: MouseEvent) {
      const link = (event.target as HTMLElement).closest('a')
      if (!link) return

      // Handle link click like in the previous example
    }
  }, [navigate, ref])
}

However, I don't recommend this because it would be confusing for screen reader users.

Attaching a click event listener to a non-interactive element like <div> makes some screen readers (e.g. NVDA) announce the element as "clickable."

In this case, the <div> element is not clickable per se even though a click handler has been attached to it – the links are clickable, not the <div> element – so announcing the <div> as "clickable" is confusing.

That's way it's better to attach click event listeners to the <a> elements instead.

Alternative approach

You can use a library like html-react-parser or htmr to convert the HTML string to React components. <a> elements could be converted e.g. to React Router's <Link> components.

Joi: checking against multiple values in `conditional()`

2022-03-09T12:00:00+03:00

Use { is: Joi.any().valid(...values) } to check if a value is included in an array.

Warm-up problem (no arrays)

You have two values: a and b.
You want to validate the data with these rules:
- a is a required string.
- If a equals 'foo', b is a required string; otherwise b is forbidden.

Solution to the warm-up problem

Use Joi.alternatives().conditional() to make the validation of b depend on the value of a:

import Joi from 'joi'

export const schema = Joi.object({
  a: Joi.string().required(),
  b: Joi.alternatives().conditional('a', {
    is: 'foo',
    then: Joi.string().required(),
    otherwise: Joi.forbidden(),
  }),
})

I'm using Joi 17.6.0 by the way.

Array problem

The same problem as above, but instead of checking if a equals 'foo', we want to check if a is included in an array:

You have two values: a and b.
You want to validate the data with these rules:
- a is a required string.
- If a is included in array, b is a required string; otherwise b is forbidden.

Solution to the array problem

We need to change the is condition.

To check against multiple values, use Joi.any().valid() (alias: Joi.any().equal()), which "adds the provided values into the allowed values list and marks them as the only valid values allowed":



 



 import Joi from 'joi'

export const array = ['foo', 'bar', 'baz']

export const schema = Joi.object({
  a: Joi.string().required(),
  b: Joi.alternatives().conditional('a', {
    is: Joi.any().valid(...array),
    then: Joi.string().required(),
    otherwise: Joi.forbidden(),
  }),
})

In this example case it's even better to use string() instead of any() to clarify the intent of the schema:

-is: Joi.any().valid(...array),
+is: Joi.string().valid(...array),

Unit tests

I wanted to be sure that my conditional Joi schema works, so I tested it like this using Jest:

import { array, schema } from './schema'

describe('schema', () => {
  test.each(array)('requires `b` if `a` is %s', (a) => {
    const validationResult = schema.validate({ a, b: undefined })
    const errorMessage = validationResult.error?.details[0].message
    expect(errorMessage).toBe('"b" is required')
  })

  test.each(array)('accepts `b` if `a` is %s', (a) => {
    const validationResult = schema.validate({ a, b: 'fleebles' })
    expect(validationResult).not.toHaveProperty('error')
  })

  it('forbids `b` if `a` is some other value', () => {
    const validationResult = schema.validate({ a: 'nibbles', b: 'fleebles' })
    const errorMessage = validationResult.error?.details[0].message
    expect(errorMessage).toBe('"b" is not allowed')
  })

  it('accepts missing `b` if `a` is some other value', () => {
    const validationResult = schema.validate({ a: 'nibbles' })
    expect(validationResult).not.toHaveProperty('error')
  })

  it('accepts undefined `b` if `a` is some other value', () => {
    const validationResult = schema.validate({ a: 'nibbles', b: undefined })
    expect(validationResult).not.toHaveProperty('error')
  })
})

Result of a test run:

$ NODE_OPTIONS=--experimental-vm-modules npx jest
PASS  ./schema.test.js
  schema
    ✓ requires `b` if `a` is foo
    ✓ requires `b` if `a` is bar
    ✓ requires `b` if `a` is baz
    ✓ accepts `b` if `a` is foo
    ✓ accepts `b` if `a` is bar
    ✓ accepts `b` if `a` is baz
    ✓ forbids `b` if `a` is some other value
    ✓ accepts missing `b` if `a` is some other value
    ✓ accepts undefined `b` if `a` is some other value

Test Suites: 1 passed, 1 total
Tests:       9 passed, 9 total
Snapshots:   0 total
Time:        0.12 s, estimated 1 s
Ran all test suites.

The tests are a bit questionable:

We depend on specific error messages. What if they change when Joi is updated?
We are almost testing that Joi works like it should. Should we be able to trust that Joi.alternatives().conditional() just works?

Nonetheless, I wanted to be sure that my schema works and these tests do the job for now.

Further resources

Joi:

Jest:

test.each()
expect().toHaveProperty()
Using ES Modules with Jest
- You might have noticed above that I had to use NODE_OPTIONS=--experimental-vm-modules npx jest instead of just npx jest.

`.mts` is a cool file extension (TypeScript ES modules)

2022-02-09T12:00:00+03:00

What's that, a file extension named after me?! Or a file extension for TypeScript files that are always ES modules?

I was reading the Prettier 2.5 announcement post the other day and noticed that "Prettier will now format files with .mts and .cts extensions as TypeScript."

Turns out .mts is not named after my first name (Matias). It's for TypeScript files that are always ES modules.

ES modules (ESM) are JavaScript or TypeScript files that use the import/export syntax.
CommonJS (CJS) modules are JavaScript or TypeScript files that use the require()/module.exports syntax.
- TypeScript might require special syntax for CommonJS modules (I'm not sure).

Usually JavaScript files use the .js extension and TypeScript files use the .ts extension. Such files can be either ES modules or CommonJS modules.

The TypeScript 4.5 Beta announcement post explains when the more precise file extensions can be useful (emphasis added):

Node.js supports a new setting in package.json called type. "type" can be set to either "module" or "commonjs".

This setting controls whether .js files are interpreted as ES modules or CommonJS modules, and defaults to CommonJS when not set.

[...]

The type field in package.json is nice because it allows us to continue using the .ts and .js file extensions which can be convenient; however, you will occasionally need to write a file that differs from what type specifies. You might also just prefer to always be explicit.

Node.js supports two extensions to help with this: .mjs and .cjs. .mjs files are always ES modules, and .cjs files are always CommonJS modules, and there's no way to override these.

In turn, TypeScript supports two new source file extensions: .mts and .cts. When TypeScript emits these to JavaScript files, it will emit them to .mjs and .cjs respectively.

There are more details in the first section of the TypeScript 4.5 Beta announcement post.

Some tools may also require or encourage the more precise file extensions. An analogy: Vite (a build tool) supports JSX by default only in .jsx and .tsx files (but not in .js and .ts files) for performance reasons.

Can you think of a file extension that's named after you?

React is a framework, not a library

2021-10-12T12:00:00+03:00

React is marketed as a view library, but it's more accurately a (view component) framework.

React is a framework because it's in control of when your code runs

A snippet from a GitHub gist by Peer Reynders (with minor grammatical edits by me):

The litmus test:

If your code calls it, it's a library.

If it calls your code, it's a framework.

Looking at the React tutorial's^[1] Starter Code, ReactDOM.render() is the only part of React that your code calls. The rest, i.e. the majority of your code, is called by React.

Ipso facto^[2] – React is a framework because it is in control when most of your code runs.

There you have it. I have thought for some time that React is a framework, not a library, but I haven't had the words to explain why.

React vs jQuery

It becomes clearer from Peer's comparison of jQuery (a library) and React (a framework). Both are tools for dealing with the DOM, but they are used differently:

jQuery for the most part is used as a layer between your code and the browser. Your code calls jQuery to fulfill some objective – and when it's done, it's done. jQuery doesn't do anything until your code calls it the next time. Some jQuery code may run due to being referenced in an event handler or because of an async callback, but that is just in the nature of browser operations. jQuery as such isn't in control, your code is. jQuery is called a library because it's simply a collection of useful helpers; after you call each method, your code is firmly back in charge.

With ReactDOM.render() your code hands over control to React. Past that point React is in full control and your code only runs when React decides to run it. React isn't a layer that your code calls to deal with the nitty-gritty of the browser, but an environment that isolates your components from the browser and uses your components when it deems it necessary – which is exactly what a framework does.

[...]

So both jQuery and React stand between your code and the browser('s DOM), but your code's pattern of interaction with them is very different:

jQuery is a collection of helpers that your code calls whenever it needs to.

React on the other hand calls your code. [...]

Go read Peer's GitHub gist; it has more great points but isn't too long.

Does it matter?

Does it matter whether React is marketed and thought of as a framework or a library?

Should React embrace the fact that it's a framework? Would it affect React's ecosystem?

Good questions. What do you think? Send me an email (my address is on the home page) and let me know!

Footnotes

Peer is referring to the React tutorial on reactjs.org. ↩
Wikipedia's definition of ipso facto:

Ipso facto is a Latin phrase, directly translated as "by the fact itself," which means that a specific phenomenon is a direct consequence, a resultant effect, of the action in question, instead of being brought about by a previous action. It is a term of art used in philosophy, law, and science.

↩

Why `compose()` is right-to-left

2021-09-28T12:00:00+03:00

Functions composed together with compose() are called from right to left. It feels unintuitive at first, but it's conventional and kind of makes sense.

What's `compose()`?

I was recently reading the book Professor Frisby's Mostly Adequate Guide to Functional Programming [in JavaScript].^[1] (It's a good book, but became too much for me somewhere around chapter 8 or 9. )

Chapter 5, Coding by Composing, introduces a compose() function for composing functions together:

const compose = (...fns) => (...args) =>
  fns.reduceRight((res, fn) => [fn.call(null, ...res)], args)[0]

(There's also Ramda's R.compose, and Lodash's _.flowRight which is aliased to _.compose in lodash/fp.)

Example usage from the book:

const toUpperCase = (x) => x.toUpperCase()
const exclaim = (x) => `${x}!`
const shout = compose(exclaim, toUpperCase)

shout('send in the clowns') // "SEND IN THE CLOWNS!"

shout is a function composed of the exclaim and toUpperCase functions: it first calls toUpperCase and then exclaim.

Calling shout is the same as calling the two functions "manually" (without using compose):

exclaim(toUpperCase('send in the clowns')) // "SEND IN THE CLOWNS!"

The order of the two functions doesn't matter in this case because the end result is the same with either order.

Another example (a bit contrived) from the book; here the order does matter:

const head = (x) => x[0]
const reverse = reduce((acc, x) => [x, ...acc], [])
const last = compose(head, reverse)

last(['jumpkick', 'roundhouse', 'uppercut']) // 'uppercut'

last is a function composed of the head and reverse functions: it first calls reverse and then head.

Again, calling last is the same as calling the two functions "manually":

head(reverse(['jumpkick', 'roundhouse', 'uppercut'])) // 'uppercut'

The order of the two functions matters in this case: calling head before reverse wouldn't work at all because reverse expects an array. (If reverse worked with strings as well, the result would be 'kcikpmuj', which is totally different from 'uppercut'.)

Why right-to-left is unintuitive

When you encounter compose(), you have to read its arguments backwards. JavaScript, like most human languages, is written from left to right, so having to read the arguments backwards is unintuitive.

When you encounter const myFn = compose(many, args, here), you have to jump to the last argument of compose to see what's the first function that myFn calls, and then backtrack to the left one argument at a time.

So, compose(A, B, C) does not mean "first call A, then B and then C" like one could expect. It's the opposite: "first call C, then B and then A." 🤸‍♂️

Compare also with method chaining, which works from left to right:

'send in the clowns'.toUpperCase().exclaim()
// vs
compose(exclaim, toUpperCase)('send in the clowns')

['jumpkick', 'roundhouse', 'uppercut'].reverse().head()
// vs
compose(head, reverse)(['jumpkick', 'roundhouse', 'uppercut'])

Why right-to-left makes sense (kind of)

The book justifies the right-to-left order very shallowly:

We could define a left to right version, however, we mirror the mathematical version much more closely as it stands. That's right, composition is straight from the math books.

It's been too long since high school math, so I had to look up Function composition (mathematical concept) on Wikipedia. An example^[2]:

(𝑓∘𝑔∘ℎ)(𝑧) = 𝑓(𝑔(ℎ(𝑧)))

Notice how the order of the functions 𝑓, 𝑔 and ℎ is the same on both sides of the equals sign.

This is true in JavaScript as well: compose(A, B, C)(arg) is the same as A(B(C(arg))). Put more visually:

compose(A, B, C)(arg)
//      ↓  ↓  ↓  ↓↓↓
        A( B( C( arg ) ) )

If you think of compose() this way, it kind of makes sense.

`pipe()` is left-to-right and more intuitive

A "left-to-right compose()" is called pipe().

For example, Ramda has R.pipe, and Lodash has _.flow which is aliased to _.pipe in lodash/fp. There's also an ECMAScript proposal for adding a pipe/pipeline operator (|>) to JavaScript.

An example from Ramda's documentation:

const f = R.pipe(Math.pow, R.negate, R.inc)
f(3, 4) // -(3^4) + 1

Compare with R.compose:

const f = R.compose(R.inc, R.negate, Math.pow)
f(3, 4) // -(3^4) + 1

Piping is so much more intuitive that I wonder what are the arguments for favoring compose. "That's how it works in math" is one argument, but how good an argument is it? If you know other arguments, please tell me!

Footnotes

The book is licensed under a CC BY-SA 4.0 license. Some code samples on this page are from the book; I have formatted them with Prettier. ↩
I was wondering why I couldn't find a Unicode symbol for "mathematical italic small h" (ℎ) even though I could find symbols for "mathematical italic small f" (𝑓) and "mathematical italic small g" (𝑔). Apparently because when the Unicode symbols for mathematical italic small letters were defined, ℎ had already a different name for it: "Planck constant." Interesting! Source: Why are there holes in the Unicode table? on Stack Overflow. ↩

Periods and commas belong inside quotes in American English

2021-09-25T12:00:00+03:00

Like so: "The name's Bourne," the man said, "JSON Bourne." Also when quoting single words, like "nibbles," "gronk" and "fleebles."

Why? Because it's a rule. Some sources:

If you are not convinced, consult your favorite style guide.

I write mainly American English. I avoid mixing in other flavors, like British English, to keep my English consistent.

An exception to the rule

Place periods and commas outside the quotes if placing them inside the quotes could make the text ambiguous or lead to errors, e.g. when quoting user inputs.

For example:

The password is "hunter2."

The above is ambiguous: does the password include the period or not?

Compare with this:

The password is "hunter2".

The above is unambiguous and thus preferable.

Sometimes it's better to change the sentence structure to avoid this problem.

I don't know if this exception is actually allowed in American English, but it's common sense.

React's ecosystem is a dumb necessity

2021-09-15T12:00:00+03:00

React's ecosystem is large, which is a good thing: lot's of great libraries to use. But it's also a bad thing: most of those libraries are compatible only with React.

Jordan Brennan's comment on dev.to beautifully sums up the downsides:

React's ecosystem is not a benefit. It's a dumb necessity grown from the need to create more stuff, much of it being React-only versions of existing stuff, because React is so incompatible and fussy.

And part of Jordan's another comment as well:

A large ecosystem is not a benefit. It is a sign that the library is too finicky and non-standard to play nice with the thousands of other libraries out there, hence all the special React versions of those libraries.

In other words: integrating vanilla JS libraries with React is difficult, so people create React-only libraries (react-this, react-that etc.).

What I'd prefer: integrating vanilla JS libraries with React is easy, so people don't need to create React-only libraries. Most effort and focus can be put to creating and improving vanilla JS libraries, and those libraries can easily be used with and without React. Win-win!

Mithril.js, a front-end framework with some similarities to React, takes a different approach. Its documentation has a dedicated (though currently very brief) page about integrating 3rd party libraries/code with Mithril.js.

It would be nice if React had a similar mindset and similar capabilities.

Scheduling vacations for maximal relaxation

2021-08-27T12:00:00+03:00

Try to schedule vacations so that they start and end in the middle of the week. You'll get two short work weeks around the vacation.

If your vacation starts in the middle of the week, the work week before the vacation will be a short one, so you won't be totally exhausted on the first day (Saturday) of the vacation.

If your vacation ends in the middle of the week, the first work week after the vacation will be more pleasant as it will be a short one. Returning from vacation won't be as stressful as you know you'll have to endure only two or three days before the weekend.

"Endure" only two or three days...? Maximize laziness and minimize work...?

Well yes, but actually no.

You see, a relaxed worker is a happy and productive worker. Win-win!

I learned this trick some years ago from my colleague. Thanks, Joonas!

JSX vs HTM (Hyperscript Tagged Markup)

2021-08-23T12:00:00+03:00

HTM provides a transpiler-free alternative to JSX via tagged templates. HTM has some limitations, but can be used in browsers and can be good for smaller projects.

JSX

JSX is a syntax extension to JavaScript. It's transpiled away before it's served to the browser.

For example:

// JSX:
return <div className="foo">bar</div>

// Output:
return React.createElement('div', { className: 'foo' }, 'bar')

JSX is the default choice in like 99% of React projects. It's not a pro or a con per se, but it raises the question: why wouldn't I just use JSX instead of some alternative?

JSX pros

Great editor support

Syntax highlighting.
IntelliSense, with or without TypeScript.

Syntax errors are actual errors

The transpiler won't let syntax errors pass. This is better than HTM failing silently on errors.

ESLint plugins

Great Prettier support

Prettier works better with JSX than with HTM, as we'll see below.

0 bytes and no runtime overhead

JSX is transpiled away.

Shorthand syntax for fragments

I.e. <>...</>.

JSX cons

Needs a transpiler

More tooling = more things to setup and maintain.

Babel can be run in the browser, but that would be slow.

New syntax to learn

JSX is not regular JavaScript; it's a syntax extension to JavaScript.

Personally I have no problems with the JSX syntax, but I have seen some people struggling with it: when to use curly braces etc.

HTM

HTM (Hyperscript Tagged Markup) is a JS library that provides a tagged template for writing JSX-like markup.

For example:

import { html } from 'htm/react'

return html`
  <div className="foo">bar</div>
`

HTM pros

No transpiler needed

Implications:

Can be run in the browser.
Less tooling to setup and maintain.

HTM is tiny and fast

Thus it's OK to use HTM in the browser, at least during development. Probably in production as well (just get started and optimize performance later if needed!).

0 bytes and no runtime overhead if compiled away

For production builds, consider compiling HTM away using babel-plugin-htm.

No new JavaScript syntax to learn

HTM is just standard tagged templates, i.e. regular JavaScript (as opposed to JSX, which is a syntax extension to JavaScript).

HTM needs to be used in a certain way, so you do need to learn "HTM syntax," but no new JavaScript syntax.

Syntax highlighting support in editors

See HTM's readme for an up-to-date list of editor extensions/plugins

OK Prettier support

Prettier supports HTM, and that's great. I wouldn't personally even consider using HTM if Prettier didn't support it.

But the outcome is not always very pretty, as we'll see below.

I recommend setting Prettier's htmlWhitespaceSensitivity option to 'ignore' because HTM strips (most) extra whitespace away like JSX does. (There might be some differences between how HTM and JSX handle whitespace; pay attention.)

Shorthand syntax for components' closing tags

E.g. <${Footer}>content<//>.

Using the shorthand much can make things hard to read, but it might anyway be better to split large components into smaller pieces.

Supports HTML-like comments

E.g. .

HTML-like comments are stripped out, which is a good or a bad thing depending on the situation.

Implicit fragments

Returning html`<div /><div />` automatically wraps the two divs inside a fragment. Or actually an array: HTM issue #175 on GitHub is about implicit fragments.

HTM cons

Fails silently on syntax errors

This can cause some head scratching. Related issues on GitHub:

No IntelliSense or TypeScript support

HTM issue #73 on GitHub is about TypeScript support.

On the other hand, if you use TypeScript, why not just use TSX? It's compiled away.

No ESLint plugins

Prettier quirk: `<pre>` tags are wonky

As mentioned above, HTM strips (most) extra whitespace away like JSX does.

However, inside <pre> tags Prettier treats some non-significant whitespace as significant, so the indentation can get really wonky.

Example (tested with Prettier 2.2.0 and 2.6.2); I have borked the indentation quite much for illustrative purposes:

// This code is formatted with Prettier but is very ugly!
return html`
  <pre>
 <code   className="foo"    dangerouslySetInnerHTML=${highlightedCode
    ? { __html: highlightedCode }
    : undefined}
>
      ${!highlightedCode || plainCode}

    </code  >
     </pre>
`

Workaround: use <${'pre'}> instead! Then Prettier won't treat non-significant whitespace as significant. Example:



 







 // This code is formatted with Prettier, looks OK
return html`
  <${'pre'}>
    <code
      className="foo"
      dangerouslySetInnerHTML=${highlightedCode
        ? { __html: highlightedCode }
        : undefined}
    >
      ${!highlightedCode || plainCode}
    </code>
  <//>
`

JSX for comparison (better formatting in my opinion):

// This code is formatted with Prettier, looks beautiful!
return (
  <pre>
    <code
      className="foo"
      dangerouslySetInnerHTML={
        highlightedCode ? { __html: highlightedCode } : undefined
      }
    >
      {!highlightedCode || plainCode}
    </code>
  </pre>
)

Obsolete: Prettier quirk: consecutive `${expressions}` can be messy

Update: I noticed that Prettier has this quirk only when formatting JS code blocks in Markdown files, not when formatting JS files. My bad!

Example of messy consecutive ${expressions} (click to toggle)

Tested with Prettier 2.2.0 and 2.6.2; notice how the two expressions end/start on the same line (but only when formatting a JS code block in a Markdown file!):






 return html`
  <div>
    ${foo &&
    html`
      <p>Foo...</p>
    `} ${bar &&
    html`
      <p>Bar...</p>
    `}
  </div>
`

Having to repeat html`...` is tedious

E.g. when mapping arrays or with conditional rendering.

I also dislike how Prettier spans the code on many more lines than with JSX.

Contrived example:

return html`
  <ul>
    ${items.length === 0 &&
    html`
      <li>No items</li>
    `}
    ${items.length > 0 &&
    items.map(
      (item) => html`
        <li key=${item.id}>${item.text}</li>
      `
    )}
  </ul>
`

JSX for comparison (much more compact):

return (
  <ul>
    {items.length === 0 && <li>No items</li>}
    {items.length > 0 &&
      items.map((item) => <li key={item.id}>{item.text}</li>)}
  </ul>
)

HTML entities are escaped

For example, the text inside html`<span>1–2</span>` gets rendered as 1–2 instead of 1–2. (– = en dash.)

HTM issue #76 on GitHub is about how HTML entities are handled.

This makes it more difficult to use special characters in components' text contents. You could type them out as-is, but having special characters in source code is bad because it can be difficult to distinguish between similar characters. For example between - (hyphen), – (en dash) and — (em dash).

A workaround is to create e.g. char.js and use it like this:

// char.js
export default {
  ndash: '–',
  mdash: '—',
  // ...
}

// Component.js
import char from './char.js'
export default () => html`
  <span>1${char.ndash}2</span>
`

No support for comments inside opening/closing tags

HTM supports only HTML-like comments, so you can't comment specific props or attributes.

In JSX you can comment props and attributes:



 
  <button
  className="foo"
  disabled // Disabled because x
  id="bar"
  // Using `baz` instead of `qux` because y
  onClick={baz}
>
  Click me
</button>

Can't use backticks in comments

Or they can be used but have to be escaped.

Backticks would be useful when referring to variables in comments. Escaped backticks and single quotes look silly:

return html`
  <div>
    <!-- 'foo' is something -->
    ${foo}

    <!-- But \`bar\` is something else -->
    ${bar}
  </div>
`

JSX for comparison:

return (
  <div>
    {/* `foo` is something */}
    {foo}

    {/* But `bar` is something else */}
    {bar}
  </div>
)

Verdict

I like the idea of HTM a lot: it's just JavaScript tagged templates, so there's no need for a transpiler and no need to learn new JavaScript syntax.

HTM can be a good choice for browser environments (when you can't or don't want to use a transpiler) and for smaller projects.

The limitations of HTM (no IntelliSense, no ESLint plugins, etc.) can however become too limiting in bigger projects. Or at least I would imagine so, I haven't used HTM in any large projects.

Here's my non-prescriptive rules for choosing between JSX and HTM:

Choose HTM if:
1. You can't or don't want to use a transpiler.
2. You can live without IntelliSense and ESLint plugins.
3. Optional: you struggle with JSX syntax. (In comparison, HTM is just JavaScript.)
Otherwise choose JSX. It requires a transpiler, but JSX is really robust.

But hey, what about another JSX alternative, hyperscript...? I'll leave the decision to you. 😁

FizzBuzz in JavaScript with infinite arrays and multimapping

2021-08-14T12:00:00+03:00

Fun way to solve the simple puzzle. Infinitely repeating arrays and mapping over multiple arrays almost makes the remainder/modulo operator (%) unnecessary.

TL;DR

Jump to the Finished result + playground section →

Rules of FizzBuzz

A FizzBuzz sequence consists of numbers and strings where:

every 3rd item is "Fizz"
every 5th item is "Buzz"
every 15th item is "FizzBuzz"
and other items are numbers.

So the first 15 items are:

1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz

After that, the cycle repeats. (The 16th item is 16 instead of 1, and so on.)

The challenge

Here's a typical solution, though without a for loop:

const result = Array.from({ length: 15 }, (_, i) => {
  const n = i + 1
  if (n % 15 === 0) return 'FizzBuzz'
  if (n % 3 === 0) return 'Fizz'
  if (n % 5 === 0) return 'Buzz'
  return n
})

console.log(result)
// [
//        1,      2, 'Fizz',      4,     'Buzz',
//   'Fizz',      7,      8, 'Fizz',     'Buzz',
//       11, 'Fizz',     13,     14, 'FizzBuzz',
// ]

It works a-okay, but let's solve FizzBuzz without using the remainder operator in the usual way, i.e. without these:

if (n % 15 === 0)
if (n % 3 === 0)
if (n % 5 === 0)

Before that, we need to acquire two new skills: creating infinite arrays and mapping over multiple arrays.

Infinite arrays

How arrays normally work (d'oh):

const array = ['A', 'B', 'C']

array.length //=> 3

array[0] //=> 'A'
array[1] //=> 'B'
array[2] //=> 'C'
array[3] //=> undefined
array[4] //=> undefined
// ...

What we want: when accessing an out-of-bounds numeric property of the array object, cycle back to the beginning of the array.

That can be achieved by creating a Proxy:

const proxyHandler = {
  get(target, prop) {
    // Accessing `target.length`
    if (prop === 'length') {
      return Infinity
    }

    // Accessing a numeric property of `target`, e.g. `target[5]`
    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
      return target[prop % target.length]
    }

    // Accessing whatever else, e.g. `target.foo`
    return target[prop]
  },
}

const cycle = (array) => new Proxy(array, proxyHandler)

I named the function cycle because I was inspired by Clojure's cycle function.

Usage:

const infiniteArray = cycle(['A', 'B', 'C'])

infiniteArray.length //=> Infinity

infiniteArray[0] //=> 'A'
infiniteArray[1] //=> 'B'
infiniteArray[2] //=> 'C'
infiniteArray[3] //=> 'A'
infiniteArray[4] //=> 'B'
infiniteArray[5] //=> 'C'
infiniteArray[6] //=> 'A'
// ...

Notes about the `typeof prop` check

Why is the `typeof prop === 'string'` check in the proxy handler's `get` method needed?

Otherwise the regex test would throw an error if prop was a Symbol.

For example, if prop was Symbol.iterator:

;/^\d+$/.test(Symbol.iterator)
//=> TypeError: Cannot convert a Symbol value to a string

The error is thrown because RegExp.prototype.test expects a string argument, and Symbols can't be implicitly converted to strings.

Symbol.iterator is used by for...of loops. So, using infiniteArray in a for...of loop would thus throw an error without the typeof check.

Using any other Symbol property key would throw as well without the typeof check.

Why check that `typeof prop` is `'string'` instead of `'number'`?

E.g. in infiniteArray[5] the property key is a number, right? Well yes, but actually no.

Numeric property keys are converted to strings. From Working with objects on MDN:

All keys in the square bracket notation are converted to string unless they're Symbols, since JavaScript object property names (keys) can only be strings or Symbols.

An alternative to the `typeof prop` check

I said above that Symbols can't be implicitly converted to strings. But a Symbol can be converted explicitly to a string by calling its toString() method. Doing so would make the typeof prop check unnecessary:

-if (typeof prop === 'string' && /^\d+$/.test(prop)) {
+if (/^\d+$/.test(prop.toString())) {
   return target[prop % target.length]
 }

Neither option is very clear without an explanation. I might prefer the toString() alternative.

Shortcomings

The cycle function is imperfect. For example, slicing doesn't work:

const infiniteArray = cycle(['A', 'B', 'C'])

// Current behavior:
infiniteArray.slice(0, 7)
//=> ['A', 'B', 'C', empty × 4]

// Ideal behavior:
infiniteArray.slice(0, 7)
//=> ['A', 'B', 'C', 'A', 'B', 'C', 'A']

Supporting all array methods would be interesting. I'll leave it to you as an exercise.

The current imperfect implementation is enough for solving FizzBuzz, so let's proceed.

Multimapping

Clojure's map function is similar to JavaScript arrays' map method, except in Clojure you can map over multiple arrays at once:

map returns a lazy sequence consisting of the result of applying [the function] f to the set of first items of each coll, followed by applying f to the set of second items in each coll, until any one of the colls is exhausted. Any remaining items in other colls are ignored.

A multimap function can be implemented in a few lines of JavaScript (I'm ignoring the part about returning a lazy sequence):

const multimap = (fn, ...arrays) => {
  const arrayLengths = arrays.map((array) => array.length)
  const smallestArrayLength = Math.min(...arrayLengths)

  return Array.from({ length: smallestArrayLength }).map((_, i) => {
    const items = arrays.map((array) => array[i])
    return fn(items, i)
  })
}

Usage:

// Same lenghts -> loop over 4 times
multimap(
  (args, i) => {
    console.log(i, args)
    return i
  },
  ['A', 'B', 'C', 'D'],
  ['W', 'X', 'Y', 'Z']
)
// Console loggings:
//   0, ['A', 'W']
//   1, ['B', 'X']
//   2, ['C', 'Y']
//   3, ['D', 'Z']
// Return value:
//   [0, 1, 2, 3]

// Different lengths -> loop over 3 times (the length of the shortest array)
multimap(
  (args, i) => {
    console.log(i, args)
    return args[i]
  },
  ['♠', '♡', '♢', '♣'],
  ['A', 'B', 'C', 'D', 'E'],
  ['♪', '♫', '☻']
)
// Console loggings:
//   0, ['♠', 'A', '♪']
//   1, ['♡', 'B', '♫']
//   2, ['♢', 'C', '☻']
// Return value:
//   ['♠', 'B', '☻']

Putting the pieces together: solving FizzBuzz

With our two new skills – creating (imperfect) infinite arrays and mapping over multiple arrays – we are ready to tackle the fearsomely challenging puzzle of FizzBuzz.

Step 1: rules of FizzBuzz as arrays

Let's translate the rules of FizzBuzz to arrays (if that makes sense). Let's also focus only on the first ten items of the FizzBuzz sequence for now.

"Every 3rd item is 'Fizz'" means that every 3rd item of an array is 'Fizz'. Other items are irrelevant, so they can be nulls:
```
[null, null, 'Fizz', null, null, 'Fizz', null, null, 'Fizz', null]
```

"Every 5th item is 'Buzz'" works similarly:

[null, null, null, null, 'Buzz', null, null, null, null, 'Buzz']

"Every 15th item is 'FizzBuzz'" can be ignored for now because the rule doesn't apply to a sequence of just ten items. But it would work similarly to the two previous rules/arrays.
"Other items are numbers" is simply an array of numbers starting from 1:
```
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
```

Let's see how they look when put into the multimap function:

multimap(
  (args) => {
    console.log(args)
  },
  [null, null, 'Fizz', null,   null, 'Fizz', null, null, 'Fizz',   null],
  [null, null,   null, null, 'Buzz',   null, null, null,   null, 'Buzz'],
  [   1,    2,      3,    4,      5,      6,    7,    8,      9,     10]
)
// Console loggings:
//   [null,     null,  1]
//   [null,     null,  2]
//   ['Fizz',   null,  3]
//   [null,     null,  4]
//   [null,   'Buzz',  5]
//   ['Fizz',   null,  6]
//   [null,     null,  7]
//   [null,     null,  8]
//   ['Fizz',   null,  9]
//   [null,   'Buzz', 10]
// Return value:
//   [undefined × 10]

Hmm, what if we take the first non-null item from each set of items?


 multimap(
  (args) => args.find((x) => x !== null),
  [null, null, 'Fizz', null,   null, 'Fizz', null, null, 'Fizz',   null],
  [null, null,   null, null, 'Buzz',   null, null, null,   null, 'Buzz'],
  [   1,    2,      3,    4,      5,      6,    7,    8,      9,     10]
)
//=> [1,    2, 'Fizz',    4, 'Buzz', 'Fizz',    7,    8, 'Fizz', 'Buzz']

Hey, FizzBuzz! 😎 (Every 15th item will be handled soon.)

Step 2: truthy vs falsy

The arrays contain only strings, numbers and nulls. Strings and numbers are truthy values, and nulls are falsy values.

Instead of taking the first non-null item, the first truthy item can be taken, and the result will be the same. This simplifies the callback function:


 multimap(
  (args) => args.find(Boolean),
  [null, null, 'Fizz', null,   null, 'Fizz', null, null, 'Fizz',   null],
  [null, null,   null, null, 'Buzz',   null, null, null,   null, 'Buzz'],
  [   1,    2,      3,    4,      5,      6,    7,    8,      9,     10]
)
//=> [1,    2, 'Fizz',    4, 'Buzz', 'Fizz',    7,    8, 'Fizz', 'Buzz']

Step 3: cycling 🚴‍♂️

The first two arrays are repeating, so they can be simplified with the new cycle function:



  multimap(
  (args) => args.find(Boolean),
  cycle([null, null, 'Fizz']),
  cycle([null, null, null, null, 'Buzz']),
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
)
//=> [1, 2, 'Fizz', 4, 'Buzz', 'Fizz', 7, 8, 'Fizz', 'Buzz']

Step 4: `range` function

The third array is lame because it's a manually-created range of numbers. Let's create a range function:

const range = (from, to) =>
  Array.from({ length: to - from + 1 }, (_, i) => i + from)

range(5, 8)
//=> [5, 6, 7, 8]

Usage:





 multimap(
  (args) => args.find(Boolean),
  cycle([null, null, 'Fizz']),
  cycle([null, null, null, null, 'Buzz']),
  range(1, 10)
)
//=> [1, 2, 'Fizz', 4, 'Buzz', 'Fizz', 7, 8, 'Fizz', 'Buzz']

Step 5: `index` argument and filler arrays

The range function is not actually even needed.

The callback function passed to the multimap function accepts index as its second argument. Just like the callback function passed to Array.prototype.map.

By using the index argument, the third array (range of numbers) is not needed, and thus the range function is not needed.

But the third array can't just be omitted as all of the remaining arrays would be infinite:


 


 multimap(
  (args, i) => args.find(Boolean) || i + 1,
  cycle([null, null, 'Fizz']),
  cycle([null, null, null, null, 'Buzz'])
)
//=> RangeError: Invalid array length

Remember that the multimap function continues going over the arrays until any of them is exhausted. In other words, multimap goes over the arrays n times where n is the length of the shortest array.

Thus, multimap can be provided a "filler" array with a certain length. Because the other arrays are infinite, the filler array's length determines how many times multimap goes over the arrays.

We are not interested in the filler array's values, so an array with ten empty slots is fine:


 

 multimap(
  (args, i) => args.find(Boolean) || i + 1,
  cycle([null, null, 'Fizz']),
  cycle([null, null, null, null, 'Buzz']),
  Array(10) // [empty × 10]
)
//=> [1, 2, 'Fizz', 4, 'Buzz', 'Fizz', 7, 8, 'Fizz', 'Buzz']

The range function might be clearer, but I'm going to continue using the filler array, because filler arrays will be useful in the next steps.

Step 6: left-padded arrays

The first two arrays are mostly fillers too. A more concise way of creating them is to create filler arrays and concatenating them with the last non-filler value:

// Before:
;[null, null, 'Fizz']
;[null, null, null, null, 'Buzz']

// After:
Array(2).concat('Fizz') // [empty × 2, 'Fizz']
Array(4).concat('Buzz') // [empty × 4, 'Buzz']

Kinda like left-padding arrays... Someone quickly publish left-pad-array on npm!

Usage:



  multimap(
  (args, i) => args.find(Boolean) || i + 1,
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  Array(10)
)
//=> [1, 2, 'Fizz', 4, 'Buzz', 'Fizz', 7, 8, 'Fizz', 'Buzz']

Step 7: the remaining rule

The code works so far with Fizzes and Buzzes, but not with FizzBuzzes. Every 15th item is "Fizz" instead of "FizzBuzz":





 














 multimap(
  (args, i) => args.find(Boolean) || i + 1,
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  Array(15)
)
//=> [1,
//    2,
//    'Fizz',
//    4,
//    'Buzz',
//    'Fizz',
//    7,
//    8,
//    'Fizz',
//    'Buzz',
//    11,
//    'Fizz',
//    13,
//    14,
//    'Fizz', // :( Should be 'FizzBuzz'
//   ]

An easy fix is to use another array based on the remaining rule ("every 15th item is 'FizzBuzz'"):



 

















 multimap(
  (args, i) => args.find(Boolean) || i + 1,
  cycle(Array(14).concat('FizzBuzz')),
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  Array(15)
)
//=> [1,
//    2,
//    'Fizz',
//    4,
//    'Buzz',
//    'Fizz',
//    7,
//    8,
//    'Fizz',
//    'Buzz',
//    11,
//    'Fizz',
//    13,
//    14,
//    'FizzBuzz', // :) Correct
//   ]

But the new array is not actually necessary because Fizz + Buzz = FizzBuzz:


 

















 multimap(
  (args, i) => args.join('') || i + 1,
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  Array(15)
)
//=> [1,
//    2,
//    'Fizz',
//    4,
//    'Buzz',
//    'Fizz',
//    7,
//    8,
//    'Fizz',
//    'Buzz',
//    11,
//    'Fizz',
//    13,
//    14,
//    'FizzBuzz', // Still correct
//   ]

Finished result + playground

const cycle = (array) =>
  new Proxy(array, {
    get(target, prop) {
      if (prop === 'length') return Infinity
      if (/^\d+$/.test(prop.toString())) return target[prop % target.length]
      return target[prop]
    },
  })

const multimap = (fn, ...arrays) => {
  const arrayLengths = arrays.map((array) => array.length)
  const smallestArrayLength = Math.min(...arrayLengths)

  return Array.from({ length: smallestArrayLength }).map((_, i) => {
    const items = arrays.map((array) => array[i])
    return fn(items, i)
  })
}

const range = (from, to) =>
  Array.from({ length: to - from + 1 }, (_, i) => i + from)

// Variation 1:
multimap(
  (args) => args.find(Boolean),
  cycle(Array(14).concat('FizzBuzz')),
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  range(1, 15)
)

// Variation 2:
multimap(
  (args, i) => args.join('') || i + 1,
  cycle(Array(2).concat('Fizz')),
  cycle(Array(4).concat('Buzz')),
  Array(15)
)

There are a lot more variations to discover. For example, these two are nice:

multimap(
  ([fizz, buzz, number]) => [fizz, buzz].join('') || number,
  cycle([null, null, 'Fizz']),
  cycle([null, null, null, null, 'Buzz']),
  range(1, 15)
)

multimap(
  ([word], i) => word || i + 1,
  cycle([null, null, 'Fizz', null, 'Buzz', 'Fizz', null, null, 'Fizz', 'Buzz', null, 'Fizz', null, null, 'FizzBuzz']),
  Array(15)
)

Play around with the code on flems.io

What kind of cool variations can you come up with? Send me an email! 😎 (Address on the home page.)

Acknowledgements

The approach and code in this blog post were like 90% inspired by the YouTube video FizzBuzz in Clojure with & without modulus/remainder/rest by Fred Overflow (cool name!).

I wanted to call this blog post "FizzBuzz in JS without the remainder operator," but I couldn't as I had to use the operator in the cycle function. ¯\(ツ)/¯

Memoized Fibonacci function in 1 line of JavaScript

2021-08-05T12:00:00+03:00

Using recursion, logical OR assignment operator (||=), BigInts and more!

What's Fibonacci?

From Fibonacci number on Wikipedia:

In mathematics, the Fibonacci numbers, commonly denoted F_n, form a sequence, called the Fibonacci sequence, such that each number is the sum of the two preceding ones, starting from 0 and 1. That is,

F₀ = 0,
F₁ = 1,

and

F_n = F_n-1 + F_n-2

for n > 1.

The sequence starts:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, …

What's memoization?

From Memoization on Wikipedia:

In computing, memoization or memoisation is an optimization technique used primarily to speed up computer programs by storing the results of expensive function calls and returning the cached result when the same inputs occur again.

Step 1: Recursive function without memoization

const fib = (n) => {
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

Negative inputs are returned as-is, and non-number inputs may break the function. This is addressed in the 3rd bonus section; for now, let's just live with it.

Usage:

fib(0) //=> 0
fib(1) //=> 1
fib(2) //=> 1
fib(3) //=> 2
fib(4) //=> 3
fib(5) //=> 5
fib(6) //=> 8
fib(7) //=> 13
fib(8) //=> 21

fib(20) //=> 6_765

console.time()
fib(38) //=> 39_088_169
console.timeEnd() //=> ~450ms on my machine 😬

Demonstration of the lack of memoization:

 
 const log = {}
const fib = (n) => {
  log[n] = log[n] + 1 || 1
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

fib(10) //=> 55

Object.entries(log)
  .reverse()
  .forEach(([n, times]) => {
    console.log(`fib(${n}) was called ${times} times`)
  })
//=> fib(10) was called 1 times
//=> fib(9) was called 1 times
//=> fib(8) was called 2 times
//=> fib(7) was called 3 times
//=> fib(6) was called 5 times
//=> fib(5) was called 8 times
//=> fib(4) was called 13 times
//=> fib(3) was called 21 times
//=> fib(2) was called 34 times
//=> fib(1) was called 55 times
//=> fib(0) was called 34 times

It's funny that those numbers – how many times fib(n) was called – follow the Fibonacci sequence! (Excluding the last one; looks like the numbers could continue decrementing at the same rate? Interesting.)

No wonder calculating fib(38) takes half a second. fib(1) gets called 39,088,169 times!

Step 2: Memoization

Diff:

+const cache = {}
 const fib = (n) => {
   if (n < 2) return n
+  cache[n] = cache[n] || fib(n - 1) + fib(n - 2)
   return cache[n]
 }

Result:

const cache = {}
const fib = (n) => {
  if (n < 2) return n
  cache[n] = cache[n] || fib(n - 1) + fib(n - 2)
  return cache[n]
}

cache is a "global" object for now. We'll change it later.

Performance is much better now:

console.time()
fib(38) //=> 39_088_169
console.timeEnd() //=> Less than 1ms on my machine 😎

Demonstration of the presence of memoization:


 
 const cache = {}
const log = {}
const fib = (n) => {
  log[n] = log[n] + 1 || 1
  if (n < 2) return n
  cache[n] = cache[n] || fib(n - 1) + fib(n - 2)
  return fib(n - 1) + fib(n - 2)
}

fib(20)

Object.entries(log)
  .reverse()
  .forEach(([n, times]) => {
    console.log(`fib(${n}) was called ${times} times`)
  })
//=> fib(10) was called 1 times
//=> fib(9) was called 1 times
//=> fib(8) was called 2 times
//=> fib(7) was called 2 times
//=> fib(6) was called 2 times
//=> fib(5) was called 2 times
//=> fib(4) was called 2 times
//=> fib(3) was called 2 times
//=> fib(2) was called 2 times
//=> fib(1) was called 2 times
//=> fib(0) was called 1 times

Step 3: Golf ⛳

Code golfing = striving for the shortest possible source code.

Step 3.1: Logical OR assignment operator (`||=`)

The logical OR assignment operator was introduced in the ECMAScript 2021 spec^[1] and is perfect for our case.

Diff:

 const cache = {}
 const fib = (n) => {
   if (n < 2) return n
-  cache[n] = cache[n] || fib(n - 1) + fib(n - 2)
+  cache[n] ||= fib(n - 1) + fib(n - 2)
   return cache[n]
 }

Result:

const cache = {}
const fib = (n) => {
  if (n < 2) return n
  cache[n] ||= fib(n - 1) + fib(n - 2)
  return cache[n]
}

Step 3.2: Return value of the assignment operator

In JavaScript, assignments have return values:

Like most expressions, assignments like x = y have a return value.

[...]

That means that (x = y) returns y, (x += y) returns the resulting sum x + y, (x **= y) returns the resulting power x ** y, and so on.

In the case of logical assignments, (x &&= y), (x ||= y), and (x ??= y), the return value is that of the logical operation without the assignment, so x && y, x || y, and x ?? y, respectively.

Diff:

 const cache = {}
 const fib = (n) => {
   if (n < 2) return n
-  cache[n] ||= fib(n - 1) + fib(n - 2)
-  return cache[n]
+  return (cache[n] ||= fib(n - 1) + fib(n - 2))
 }

Result:

const cache = {}
const fib = (n) => {
  if (n < 2) return n
  return (cache[n] ||= fib(n - 1) + fib(n - 2))
}

The outermost parentheses in the return statement are added by Prettier, but they are optional.

Step 3.3: Ternary operator

Diff:

 const cache = {}
-const fib = (n) => {
-  if (n < 2) return n
-  return (cache[n] ||= fib(n - 1) + fib(n - 2))
-}
+const fib = (n) => (n < 2 ? n : (cache[n] ||= fib(n - 1) + fib(n - 2)))

Result:

const cache = {}
const fib = (n) => (n < 2 ? n : (cache[n] ||= fib(n - 1) + fib(n - 2)))

Step 3.4: Pass cache as a parameter

Diff:

-const cache = {}
-const fib = (n) => (n < 2 ? n : (cache[n] ||= fib(n - 1) + fib(n - 2)))
+const fib = (n, _cache = {}) =>
+  n < 2 ? n : (_cache[n] ||= fib(n - 1, _cache) + fib(n - 2, _cache))

Result:

const fib = (n, _cache = {}) =>
  n < 2 ? n : (_cache[n] ||= fib(n - 1, _cache) + fib(n - 2, _cache))

Yay, we got rid of the "global" cache object.

The downside of passing cache as a parameter is that the cache is discarded afterwards. This reduces performance if fib() is called many times:

// Before (global cache):
console.time()
Array.from({ length: 50_000 }, () => fib(1_000))
console.timeEnd()
//=> ~5ms

// After (cache as parameter):
console.time()
Array.from({ length: 50_000 }, () => fib(1_000))
console.timeEnd()
//=> ~2,000ms

Okay, that's silly. Who would call fib(1_000) 50,000 times? 😅 But the point remains that the performance is worse.

The new function parameter is prefixed with an underscore to denote that it's a "private" parameter not meant to be used by the user of the function.

Though it can be used, and doing so will fix the performance problem:

console.time()
const cache = {}
Array.from({ length: 50_000 }, () => fib(1_000, cache))
console.timeEnd()
//=> ~5ms

I think an optional cache parameter is the best of both worlds: you can just call fib(n) and not have to care about creating a cache object, but you can also easily create a persistent cache if you need to.

Step 3.5: Obfuscate the code to fit on a single line 😅

We are almost there! The code from the previous step could already be placed on a single line, but I want to let Prettier format my code.

Renaming _cache to c almost makes the code fit on a single line:

const fib = (n, c = {}) =>
  n < 2 ? n : (c[n] ||= fib(n - 1, c) + fib(n - 2, c))

It's only 1 character too long!

We can further reduce the code's length by using the decrement operator instead of n - 1 and n - 2. Note that we have to use it in prefix position:

const fib = (n, c = {}) => (n < 2 ? n : (c[n] ||= fib(--n, c) + fib(--n, c)))

Now the code fits on a single line! 💪

We could golf more by changing const to let, renaming fib to f, and removing unnecessary spaces and parentheses:

let f=(n,c={})=>n<2?n:c[n]||=f(--n,c)+f(--n,c)

But that would be silly.

In fact, this whole step 3.5 is kind of silly. I would prefer the code from step 3.4. It spans on two lines, but at least it's readable.

Bonuses

These are bonuses, so we don't necessarily have to aim for the line length of one. 😜

Bonus 1: Arbitrarily large integers with BigInts

The Number.MAX_SAFE_INTEGER constant represents the maximum safe integer in JavaScript (2^53 - 1).

Safe in this context refers to the ability to represent integers exactly and to correctly compare them. For example, Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2 will evaluate to true, which is mathematically incorrect.

2^53 - 1 sounds large, but it's exceeded quite quickly when calculating Fibonacci numbers:

fib(78)                 //=>  8_944_394_323_791_464
Number.MAX_SAFE_INTEGER //=>  9_007_199_254_740_991
fib(79)                 //=> 14_472_334_024_676_220 (incorrect!)

A quick Duck search shows that our result for fib(79) is incorrect; the correct value is our result plus one.

We should instead use BigInt values, introduced in the ECMAScript 2020 spec^[2]. BigInts can be used for arbitrarily large integers.

BigInts can be created in two ways:

by appending n to the end of an integer literal (100n)
by calling the BigInt() constructor without the new operator (BigInt(100), BigInt(100n) or BigInt('100')).

BigInts can't be mixed with regular numbers, so we have to change n - 1 to n - 1n and n - 2 to n - 2n. However, BigInts can be compared with regular numbers, so we don't have to change n < 2.

After introducing BigInts to the code from step 3.4, the code looks like this:

const fib = (n, _cache = {}) =>
  n < 2 ? n : (_cache[n] ||= fib(n - 1n, _cache) + fib(n - 2n, _cache))

fib(78n)                //=>  8_472_334_024_676_464n
Number.MAX_SAFE_INTEGER //=>  9_472_334_024_676_991
fib(79n)                //=> 14_472_334_024_676_221n (correct!)

fib(1_000n) //=> 43_466_557_686_937_472_334_024_676_675_472_334_024_676_660_472_334_024_676_481_472_334_024_676_417_472_334_024_676_879_472_334_024_676_295_472_334_024_676_634_472_334_024_676_239_472_334_024_676_642_472_334_024_676_187_472_334_024_676_928_472_334_024_676_137_472_334_024_676_875n 😅

Performance seems about the same. The above code runs in less than 2ms on my machine.

Note that our function has to be called with a BigInt. Calling it with a regular number will throw a TypeError:

fib(100)
//=> Chrome: "Uncaught TypeError: Cannot mix BigInt and other types, use explicit conversions"
//=> Firefox: "Uncaught TypeError: can't convert BigInt to number"

We'll change this in the 3rd bonus section.

Bonus 2: Avoiding stack overflows

We can now support arbitrarily large integers, except we can't because too large inputs cause stack overflow errors:

fib(10_000n)
//=> Chrome: "Uncaught RangeError: Maximum call stack size exceeded"
//=> Firefox: No problem on my machine!

fib(100_000n)
//=> Chrome: "Uncaught RangeError: Maximum call stack size exceeded"
//=> Firefox: "Uncaught InternalError: too much recursion"

Here's what we can do:

Make our function async.
Periodically pause our function with await, Promises and timeouts, so that the call stack can be periodically emptied.

Like so; I put a log statement for demonstration (notice also the non-highlighted async and await keywords):



    const fib = async (n, _cache = {}) => {
  if (n < 2) return n
  if (n % 1_000n === 0n) {
    console.log('Pausing at n =', n)
    await new Promise((resolve) => setTimeout(resolve))
  }
  _cache[n] ||= (await fib(n - 1n, _cache)) + (await fib(n - 2n, _cache))
  return _cache[n]
}

Using await inside the second if statement pauses the function until the new Promise is resolved, i.e. until resolve() is called.

Using setTimeout() puts the calling of resolve() to the end of the browser's task queue. Tasks are processed only when the call stack is empty. In other words, our function resumes only after the call stack has been emptied, so now we won't get stack overflow errors.

If you are not following, please read Jake Archibald's great article Tasks, microtasks, queues and schedules.

Usage:

console.time()

await fib(100n)
//=> 354_224_848_179_261_915_075n

console.timeEnd()
//=> ~10ms

console.time()

await fib(5_000n)
//=> Pausing at n = 5000n
//=> Pausing at n = 4000n
//=> Pausing at n = 3000n
//=> Pausing at n = 2000n
//=> Pausing at n = 1000n
//=> Pausing at n = 1000n
//=> Pausing at n = 2000n
//=> Pausing at n = 3000n
//=> Pausing at n = 4000n
//=> (returns a big-ass number)

console.timeEnd()
//=> ~1,200ms

Two problems though:

The function is now very slow.
The page becomes janky with large inputs (e.g. fib(5_000n)).

Jankiness could be reduced by pausing more often (e.g. if (n % 100n === 0n)), but it would make the function even slower (more pausing means more waiting).

At this point it would anyway be better to use a non-recursive function (see the 4th bonus section). It would be much faster and would have no stack overflow problems. Move it to a Web Worker and the page wouldn't become janky even with enormous inputs.

Sidetrack: `await new Promise(setTimeout)`

If we were code golfing, we could shorten our pausing code like this:

// Before
await new Promise((resolve) => setTimeout(resolve))

// After
await new Promise(setTimeout)

The shortened code works because the Promise constructor takes one function parameter (executor), which in turn takes two function parameters (resolutionFunc and rejectionFunc). So, new Promise(setTimeout) expands to:

new Promise((resolutionFunc, rejectionFunc) =>
  setTimeout(resolutionFunc, rejectionFunc)
)

setTimeout's second parameter (delay in milliseconds) gets coerced into a number, so basically Number(rejectionFunc)^[3], which is NaN, which is the same as omitting the second parameter.

Of course, the shorter code shouldn't be generally used because it's too cryptic.

Bonus 3: Input validation and TypeScript types

As mentioned in step 1, negative inputs are returned as-is, and non-number inputs may break the function. Let's add input validation:


 







  const fib = async (n, _cache = {}) => {
  if (n < 0) throw new Error('n must be non-negative')
  if (n < 2) return n
  if (n % 1_000n === 0n) {
    await new Promise((resolve) => setTimeout(resolve))
  }
  _cache[n] ||= (await fib(n - 1n, _cache)) + (await fib(n - 2n, _cache))
  return _cache[n]
}

await fib(-1) //=>  Error: n must be non-negative
await fib(-1n) //=> Error: n must be non-negative

It would be nice to accept regular numbers as well. It would be no "validation," but let's add that:




 






  const fib = async (n, _cache = {}) => {
  if (n < 0) throw new Error('n must be non-negative')
  if (n < 2) return BigInt(n)
  if (typeof n !== 'bigint') n = BigInt(n)
  if (n % 1_000n === 0n) {
    await new Promise((resolve) => setTimeout(resolve))
  }
  _cache[n] ||= (await fib(n - 1n, _cache)) + (await fib(n - 2n, _cache))
  return _cache[n]
}

await fib(10) //=>  55n
await fib(10n) //=> 55n

Now that our function is ready, let's add TypeScript types:


   





 
 const fib = async (
  n: number | bigint,
  _cache: { [key: string]: bigint } = {}
): Promise<bigint> => {
  if (n < 0) throw new Error('n must be non-negative')
  if (n < 2) return BigInt(n)
  if (typeof n !== 'bigint') n = BigInt(n)
  if (n % 1_000n === 0n) {
    await new Promise((resolve) => setTimeout(resolve))
  }
  _cache[n.toString()] ||=
    (await fib(n - 1n, _cache)) + (await fib(n - 2n, _cache))
  return _cache[n.toString()]
}

Eh, quite ugly and way more than 1 line (14). 😅

Note that instead of _cache[n] I had to explicitly use _cache[n.toString()]. A reason for this can be found in the TypeScript Index Signature section of the TypeScript Deep Dive book.

Bonus 4: Non-recursive non-memoized function

I wanted to see how much faster a non-recursive function would be:

const fib = (n) => {
  let a = 0n
  let b = 1n
  let c = 0n
  while (n--) [a, b, c] = [b, c, b + c]
  return c
}

fib(10) //=> 55n (correct)

console.time()
fib(5_000)
console.timeEnd() //=> ~3ms

console.time()
fib(100_000)
console.timeEnd() //=> ~90ms

Much faster, so this whole blog post was a bit silly in the end. 🙈

Footnotes

See list of finished ECMAScript proposals on GitHub. ↩
See previous footnote. ↩
See Dr. Axel Rauschmayer's article Type coercion in JavaScript for details. ↩

11ty vs Eleventy

2021-08-01T12:00:00+03:00

The two names are often used interchangeably, but there's a slight difference: 11ty is the organization, Eleventy is the static site generator.

I used to use the name "11ty" when talking about Eleventy, the static site generator. Apparently that's slightly wrong; from a GitHub comment by Zach Leatherman (the author of Eleventy):

11ty is the org and eleventy is the software. I know that's confusing. In retrospect it may have been nicer to use 11ty/11ty but I didn't 😅.

There you have it. From now on I'm going to use the name "Eleventy" when talking about the static site generator. A bit shame, since "11ty" looks better.

When to use the name "11ty" then? Dunno, I rarely talk about the organization.

By the way, some extra confusion before you go:

Eleventy's website is at 11ty.dev.
Eleventy's GitHub page has a big "11ty" logo at the top.
Eleventy's Twitter account has an "11ty" avatar.

How to render Optimizely Content Recommendations using React

2021-06-24T12:00:00+03:00

Also known as Episerver/Idio Content Recommendations. The usual way of using a Mustache template can be circumvented by using a JavaScript proxy.

What is Optimizely Content Recommendations?

Episerver's marketing page describes Web Content Recommendations like so:

Serve each visitor the most relevant content automatically. AI-powered recommendations act upon the unique interests of each visitor in real-time to help you deliver personalization with minimal manual effort.

Optimizely's developer docs describe Content Recommendations maybe slightly more clearly:

Optimizely Content Recommendations automatically generates a personalized content feed for each visitor based on the individual's site activity.

Content Recommendations uses Natural Language Processing (NLP) to understand the meaning of each piece of content at a granular level and builds a real-time interest profile for each visitor based on their interactions with the NLP-generated topics. Content Recommendations uses this information to recommend articles, blog posts, or other specified content sections that are most relevant to the visitor's interest profile.

TL;DR: Personalized content recommendations based on visitor tracking and natural language processing of the content pages.

Optimizely vs Episerver vs Idio

Optimizely Content Recommendations have been previously called Episerver Content Recommendations, and before that Idio Content Recommendations. Some context:

Usual implementation: Mustache template

On pages where you want to see intelligent content recommendations:

Add a Mustache template with the class idio-recommendations. Example:

<script
  class="idio-recommendations"
  data-api-key="..."
  type="text/x-mustache"
>
  <div class="recommendation">
    {{#content}}
      <h2>
        <a href="{{link_url}}">{{title}}</a>
      </h2>
      <img alt="" src="{{main_image_url}}" />
      <p>{{abstract}}</p>
      <p>
        Published on <span class="date">{{published}}</span>
      </p>
    {{/content}}
  </div>
</script>

Load ip.js script ("Idio Personalization").

When the page is loaded, the ip.js script will look for the Mustache template, and if found, load content recommendations via an Ajax request and render the Mustache template with the loaded data.

Quite straightforward. If this works for you, great!

Problems when using with React

Rendering a Mustache template to the page using React is not a problem. Some other basic things are however difficult:

How to format dates in the Mustache template? They are rendered in the ISO 8601 format by default and I haven't found a way to customize that.
How to handle links in the Mustache template so that the links are handled like SPA (single page app) links?

I suspect that other basic things would also be difficult.

Naive and hacky React implementation (not recommended)

I don't recommend this approach. Check the next section for a better approach. I'm documenting this here because this is what I tried first.

Content Recommendations offers a way to run your own logic after the Mustache template has been populated with data.

After ip.js has loaded the data via Ajax and rendered the Mustache template, it will look for a window._ipc object (apparently stands for "Idio Personalization Config") and call its complete function (if it exists) with two arguments: a reference to the DOM element containing the recommendations, and a status code of the Ajax response.

By utilizing the window._ipc object, it should be possible to do these steps after the Mustache template has been rendered:

Format dates inside the DOM element by mutating them.
Attach click event listeners to the links inside the DOM element for SPA-like navigation.

Something like this (quick and dirty code):

function ContentRecommendations() {
  useIdioPersonalizationConfig()

  return (
    <script
      className="idio-recommendations"
      data-api-key="..."
      type="text/x-mustache"
    >
      ...
    </script>
  )
}

function useIdioPersonalizationConfig() {
  useEffect(() => {
    let links = []

    window._ipc = {
      complete(element, statusCode) {
        if (!element || statusCode !== 200) return

        element.querySelectorAll('.date').forEach((date) => {
          date.textContent = new Date(date.textContent).toLocaleString('en')
        })

        links = element.querySelectorAll('a')
        links.forEach((link) => {
          link.addEventListener('click', handleLinkClick)
        })
      },
    }

    return () => {
      links.forEach((link) => {
        link.removeEventListener('click', handleLinkClick)
      })
    }
  }, [])
}

Notice how I have to remove the links' click event listeners in the useEffect's cleanup function to avoid memory leaks.

Is this good? Nah, it's very hacky. I don't like to see this kind of code in a React project.

If there are more things that you have to do like this – things that you can't do with just the Mustache template – the code becomes even uglier.

Better (albeit still hacky) React implementation (recommended)

It would be nice if we could do the Ajax requests ourselves, but that's not possible. Plus in the end I think it's best to leave the request logic to ip.js.

It would be even better if we could get the Ajax response's data directly instead of letting ip.js use it to render the Mustache template. But that's not possible... unless we use a certain hack. 🤪

The flow of things

I did some digging, and the flow goes like this:

After the page has loaded, ip.js does some initializations like this:

window.idio = window.idio || {}
window.idio.render = function () { /* ... */ }
window.idio.load = function () { /* ... */ }
// ...

Notice how ip.js doesn't override the window.idio object if it already exists.

ip.js looks for Mustache templates with the class idio-recommendations. (Actually, it looks for any script elements with that class.)
If a template is found, ip.js does an Ajax request to get content recommendations for the user.

The Ajax response contains JavaScript code like this:

window.idio.r0(
  {
    total_hits: 1234,
    content: [
      { /* ... */ },
      { /* ... */ },
    ],
    // ...
  },
  200
)

I.e. the returned code calls window.idio.r0 with the content recommendations data and a status code of the Ajax response.

window.idio.r0 renders the Mustache template with the data.

If the page contains more than one Mustache template, the first Ajax response calls window.idio.r0, the second one calls window.idio.r1, and so on. So the "r" is apparently "render" or "result," and the number is a 0-based index.

The hack: proxying `window.idio`

So, everything is fine to us except the last step. If only we could do something else than let ip.js render the Mustache template when window.idio.r0 is called...

Well, that's what JavaScript proxies are for! We can use one to make window.idio.r0 return something else when it's accessed.

As we saw earlier, ip.js doesn't override the window.idio object if it already exists. So we can define it ourselves before loading ip.js:

window.idio = new Proxy(
  {},
  {
    get(target, prop) {
      return prop === 'r0' ? handleAjaxResponse : target[prop]

      // Alternatively, if the page can contain more than one Mustache template:
      return /^r\d+$/.test(prop.toString()) ? handleAjaxResponse : target[prop]
      // The `toString()` is needed because `prop` can be a Symbol,
      // and the `test()` method would otherwise throw:
      // "Cannot convert a Symbol value to a string"
    },
  }
)

function handleAjaxResponse(data, statusCode) {
  // Do whatever with the data 🤘
}

Here I'm setting window.idio to a proxy object which:

Returns my own handleAjaxResponse function when window.idio.r0 is accessed (instead of returning what window.idio.r0 actually is).
Otherwise makes window.idio work normally.

In other words, I can do whatever I like in handleAjaxResponse. Check the next section for an example what to do with the data.

Heh, this is hacky and fragile, but so is the Mustache + React combo. At least now I don't have to have a mix of Mustache, React and procedural DOM mutations.

Goodbye Mustache!

Sample code

I'll leave it as an exercise for you to clean up and properly comment the code. 🙂

function ContentRecommendations() {
  const recommendations = useContentRecommendations()

  return (
    <>
      {/*
        Content recommendations are loaded
        only if a Mustache template with this class is found on the page.
      */}
      <script
        className="idio-recommendations"
        data-api-key="..."
        data-rpp="5" // Results per page
        type="text/x-mustache"
      />

      {recommendations.length > 0 && (
        <>
          <h2>Recommended content</h2>
          <ContentRecommendationsList recommendations={recommendations} />
        </>
      )}
    </>
  )
}

function ContentRecommendationsList({ recommendations }) {
  const formatDate = (date) =>
    new Date(date).toLocaleString('en', { dateStyle: 'medium' })

  return recommendations.map((recommendation) => (
    <div key={recommendation.id}>
      <h3>
        {/* Look ma, can use router links! */}
        <RouterLink href={recommendation.link_url}>
          {recommendation.title}
        </RouterLink>
      </h3>
      <img alt="" src={recommendation.main_image_url} />
      <p>{recommendation.abstract}</p>
      <p>
        {/* Look ma, date formatting! */}
        Published on {formatDate(recommendation.published)}
      </p>
    </div>
  ))
}

/**
 * Get content recommendations loaded by `ip.js` ("Idio Personalization").
 *
 * Hacky! Read on for details.
 *
 * What `ip.js` does:
 *
 * 1. Look for a Mustache template with the class `idio-recommendations`.
 * 2. If found, load content recommendations data via Ajax.
 * 3. Call `window.idio.r0(data, statusCode)`
 *    with the Ajax response data and status code.
 *
 * Normally `window.idio.r0` compiles the Mustache template,
 * but `useIdioProxy` intercepts calls to `window.idio.r0`
 * so that we can handle the data ourselves.
 *
 * More detailed description and original code at
 * https://mtsknn.fi/blog/how-to-render-optimizely-content-recommendations-using-react/
 *
 * @returns {object[]}
 */
function useContentRecommendations() {
  const [recommendations, setRecommendations] = useState([])

  useIdioProxy(setRecommendations)
  useIdioPersonalizationScript()

  return recommendations
}

/**
 * Create a proxy object for `window.idio`
 * to intercept calls to `window.idio.r0`.
 *
 * Must be run before loading `ip.js`
 * to ensure that the proxy is in place
 * when loading the content recommendations data.
 *
 * `ip.js` sets `window.idio = window.idio || {}`,
 * so our proxy isn't overridden.
 *
 * @param {React.Dispatch<React.SetStateAction<object[]>>} setRecommendations
 * React state setter.
 */
function useIdioProxy(setRecommendations) {
  const handleAjaxResponse = useCallback(
    (data, statusCode) => {
      if (statusCode !== 200) {
        // Show error or do logging or whatever
        return
      }

      setRecommendations(data.content)
    },
    [setRecommendations]
  )

  useEffect(() => {
    window.idio = new Proxy(
      {},
      {
        get(target, property) {
          return property === 'r0' ? handleAjaxResponse : target[property]
        },
      }
    )

    return () => delete window.idio
  }, [handleAjaxResponse])
}

/**
 * Load `ip.js` ("Idio Personalization")
 * which loads Optimizely Content Recommendations.
 */
function useIdioPersonalizationScript() {
  useEffect(() => {
    const script = document.createElement('script')
    script.async = true
    script.src = 'https://.../ip.js'

    document
      .querySelector('script')
      .insertAdjacentElement('beforebegin', script)

    return () => script.remove()
  }, [])
}

How to trigger daily Netlify builds using GitHub Actions

2021-06-22T12:00:00+03:00

Or any other automatic periodic builds. I'm using daily builds to automatically publish scheduled blog posts on my Eleventy site.

Create a build hook on Netlify. Name it e.g. "Daily build from GitHub Actions."

"Build hooks are URLs you can use to trigger new builds and deploys." To trigger a build, you can send a POST request to the URL.
Create an encrypted secret for your GitHub repository. Name it e.g. NETLIFY_DAILY_BUILD_HOOK and use the URL from step 1 as the value.

We are storing the URL as a secret because otherwise someone could spam the URL and rob you from your Netlify account's build minutes.
Create a cron schedule expression using e.g. Crontab.guru or any of the other cron generators that can be easily found via Google.

E.g. 50 5 * * * means "every day at 5:50 AM UTC." Crontab.guru has more cron examples.

Create a .github/workflows/daily-build.yml file with the following contents (replace the cron expression with your own):

name: Daily Netlify build trigger

on:
  schedule:
    # Run at 5:50 AM UTC every day
    - cron: '50 5 * * *'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Curl request to Netlify's build hook
        env:
          BUILD_HOOK: ${{ secrets.NETLIFY_DAILY_BUILD_HOOK }}
        run: |
          curl -X POST -d {} "$BUILD_HOOK"

And that's it! GitHub will automatically run the Action every day around the specified time. The Action will do a POST request to the build hook which will trigger a build on Netlify.

Note about scheduled GitHub Actions events:

The schedule event can be delayed during periods of high loads of GitHub Actions workflow runs. High load times include the start of every hour. To decrease the chance of delay, schedule your workflow to run at a different time of the hour.

Further resources

Two ways to use absolute import paths in Node.js

2021-06-17T12:00:00+03:00

Say goodbye to ../ times million and use absolute import paths from the app's root directory instead. Two contenders: Basetag and Sultan's sexy-require! 🤺

Sultan's `sexy-require`

Example usage of the sexy-require npm package by Sultan:

// Before, unclear what's being required 👎
const user = require('../../../database/user')

// After, absolute path from the app's root dir 👍
const user = require('/database/user')

// Alternatively, using an alias configured in a `.paths` file 👍
const user = require('$db/user')

sexy-require overrides Module.prototype.require, so in other files require() points to sexy-require's require function which supports absolute paths and path aliases.

Pros

Simple to set up: install the package and require it in your main application file.
Supports path aliases.
The name!

Cons

Breaks VS Code's IntelliSense.
Breaks path autocompletion in VS Code.
Supports only require(), not import.

Basetag

Example usage of the Basetag npm package by Jannik:

// Before, unclear what's being required 👎
import user from '../../../database/user'
const user = require('../../../database/user')

// After, $ points to the app's root dir 👍
import user from '$/database/user'
const user = require('$/database/user')

Basetag creates a symlink, or something called a junction on Windows, so that node_modules/$ points to the app's root directory.

Pros

Works with VS Code's IntelliSense.
Path autocompletion works in VS Code.
Supports both require() and import.

Cons

No way to configure path aliases.
The symlink gets removed by npm when installing or removing packages, so you need to e.g. create a postinstall npm script as instructed in the package's readme. Not difficult, but a little hassle.

Which one to use

I'm not sure which one I like more:

Better VS Code support of Basetag.
The name Sultan's sexy-require.

Just kidding – use Basetag, good IDE support is more important. Plus it also supports import statements.

Update in 2023

There are probably better solutions than these two. Besides, I wrote this post mainly because I found the name "Sultan's sexy-require" so sweet.

Some time ago I came across a blog post saying that Node.js supports import aliases natively since v14. I haven't tested that, but it looks promising.

Smoke testing is quick and dirty testing

2021-06-13T12:00:00+03:00

Smoke testing is cursory or "quick and dirty" testing to see that the software works correctly.

Smoke testing

I recently heard the term "smoke testing" when we were talking about production deployments at work. Let's see what Wikipedia tells us about Smoke testing (software):

In computer programming and software testing, smoke testing (also confidence testing, sanity testing, build verification test (BVT) and build acceptance test) is preliminary testing to reveal simple failures severe enough to, for example, reject a prospective software release. Smoke tests are a subset of test cases that cover the most important functionality of a component or system, used to aid assessment of whether main functions of the software appear to work correctly.

So: smoke testing is cursory or "quick and dirty" testing to see that the software works correctly. Or appears to work correctly – there's no extensive testing.

For example, if you do extensive testing in your integration or staging environment (or whatever your non-production test environment is called), there might be no need to repeat the extensive tests in production. So, during production deployments it's enough to verify that everything looks good at a cursory glance. That's smoke testing.

Sanity testing

The Wikipedia quote above says that smoke testing is also called sanity testing. This may or may not be true – check out What is the difference between smoke testing and sanity testing? on Stack Overflow for different opinions.

Origin of the term

I was curious why smoke testing was called like that. Wikipedia's page about Smoke testing (electrical) explains it clearly:

The expression probably was first used in plumbing in referring to tests for the detection of cracks, leaks or breaks in closed systems of pipes. By metaphorical extension the term is used in electronics. In Lessons Learned in Software Testing, Cem Kaner, James Bach, and Brett Pettichord provided the origin of the term: "The phrase smoke test comes from electronic hardware testing. You plug in a new board and turn on the power. If you see smoke coming from the board, turn off the power. You don't have to do any more testing."

So: plumbing → electronic hardware testing → software testing.

React + TypeScript: Interdependent prop types

2021-06-13T12:00:00+03:00

I.e. props that depend on other props. You can require and forbid certain prop combinations by utilizing TypeScript's union and intersection types.

Example problem

Let's say we want to create a Shape React component with the following requirements:

It takes a color prop.
It takes a type prop with the value of 'circle', 'square' or 'rectangle'.
Depending on the type prop's value, it takes the following props as well:
- radius when the type is 'circle'.
- width when the type is 'square'.
- width and height when the type is 'rectangle'.

A naive type for the props object would look like this:

type ShapeProps = {
  color: string
  type: 'circle' | 'square' | 'rectangle'
  radius: number
  width: number
  height: number
}

function Shape(props: ShapeProps) {
  return /* ... */
}

It's naive because we could specify all of those props:

<Shape color="red" type="circle" radius={10} width={20} height={30} />

That makes no sense because a circle shape doesn't have a width or a height; it only has a radius.

The other shapes have similar problems.

Union type to the rescue

We instead want to create a union type:

type ShapeProps =
  | { color: string; type: 'circle'; radius: number }
  | { color: string; type: 'square'; width: number }
  | { color: string; type: 'rectangle'; width: number; height: number }

Now TypeScript won't let us specify invalid props.

For example, when the type is 'circle':

We can (and must) specify only the color and radius props.
We can't specify the width or height props; doing so would produce an error.

Simplify with an intersection type

Notice how we are repeating the color prop in all three types.

We can reduce duplication by using an intersection type:

type ShapeProps = { color: string } & (
  | { type: 'circle'; radius: number }
  | { type: 'square'; width: number }
  | { type: 'rectangle'; width: number; height: number }
)

More tricks

I learned this trick from Bruno Antunes's YouTube video React.js TypeScript Conditional Props – Props that depend on other Props (26:13). Check it out, it has more advanced examples as well.

The 5 rules of ARIA

2021-06-13T12:00:00+03:00

Five simple rules for using ARIA attributes, straight from W3C.

W3C's Using ARIA document has a Notes on ARIA Use in HTML section.

It's a short section, and here's an even shorter summary:

If you can use a native HTML element or attribute [...] instead of [...] an ARIA role, state or property [...], then do so.
Do not change native semantics, unless you really have to.

For example: Developer wants to build a heading that's a tab.

Do not do this:
<h2 role="tab">heading tab</h2>
Do this:
<div role="tab"><h2>heading tab</h2></div>
All interactive ARIA controls must be usable with the keyboard.

Do not use role="presentation" or aria-hidden="true" on a focusable element.

Using either of these on a focusable element will result in some users focusing on 'nothing'.

All interactive elements must have an accessible name.

Inspired by Bramus's summary of the five rules.

Goodbye Cookbook, hello more blog posts

2021-06-12T12:00:00+03:00

I ditched my website's Cookbook section and converted existing recipes to blog posts. Mostly to reduce stress and make things clearer.

Up until today, my website had a Cookbook section which contained "technical recipes": short tips, tricks and code snippets.

Today I converted all existing cookbook recipes to blog posts.

I wasn't sure which articles should be cookbook recipes and which articles should be blog posts. Some blog posts already felt like they should be cookbook recipes, and vice versa.

The cookbook just caused extra stress in the end because I had two things to maintain: the blog and the cookbook. Or actually three things, since I am (update: was) also writing a weekly log.

At some point I almost had the idea to make two versions of some articles: a long and detailed blog post, and a short and straight-to-the-point cookbook recipe.

But that would have been silly: double work for no apparent reason. If a blog post is long, I'll rather include a short summary or split it into smaller posts. If a blog post is short, that's fine too!

The "downside" of removing the cookbook is that I really like the terms "cookbook" and "recipe." I think I was inspired by Kirby CMS's cookbook section.

Another source of inspiration was Zander Martineau's Code Notes. I found it a year ago via his blog post Announcing Code Notes. Cool! I have now tried out something similar (though much simpler), and I'll rather keep my code notes under my blog.

All right, now I have more time and energy to write blog posts... or at least I hope so. 😅

My favorite mnemonics for American vs British English

2021-06-11T12:00:00+03:00

Use these weird tricks to remember which words are American English and which are British English. Linguists HATE them!

Learned vs learnt

"Learned" is American English, "learnt" is British English.

Mnemonic: Englishmen like to drink tea, so the word ends in a t.

Source of the mnemonic: Learned or Learnt? on Grammarly

Words ending in "-er" vs "-re"

Many words end in "-er" in American English and in "-re" in British English.

Examples:

American English	British English
center	centre
fiber	fibre
liter	litre
meter	metre
theater or theatre	theatre

Note that in American English, theater is the standard spelling, but the -re spelling is also commonly used, especially in proper names (the Lunt-Fontanne Theatre).

Source of the rule and the quote: Words ending in "-re" and "-er" on Lexico

Mnemonic: in Am-er-ican English, many words end in "-er."

Source of the mnemonic: me!

Squircley is an SVG squircle generator

2021-06-06T12:00:00+03:00

A squircle is a rounded square with no straight edges; the shape is a continuous curve.

Squircley is a simple tool for creating SVG "squircles."

From the author's (George Francis) dev.to article Soften up your designs with a Squircle!:

A Squircle, unlike an element with border-radius set, has no straight edges at all. The shape is a continuous curve! Apple love this trick and use it in both physical and digital design.

I love how squircles look! 🤩 Though funnily my brother doesn't like them, apparently because at some point they have been popular in Android as well so he has already received an overdose of them. 🤔

But I like them so check out Squircley and see the dev.to article for an interactive example!

Kayaking is fun

2021-06-06T12:00:00+03:00

I kayaked for the first time in my life and quite liked it. Then I ate pizza.

Kayaking

We went kayaking with our team on Tuesday. Here's a photo that I took using my phone's (Unihertz Jelly) potato camera:

And here's a quick selfie that I snapped for my wife (nice picture 😂):

It was my first time kayaking. It was quite fun but also surprisingly effortful as I had to use my legs to maintain balance and my arms and upper torso to move the kayak forward.

I can definitely recommend trying out kayaking.

Pizza

Afterwards we went eating. Some chose fancy foods like entrecôte, but I chose an exotic pizza. 😋 No picture of it, sadly, but here are the ingredients:

tomato sauce
mozzarella cheese
spreadable Nduja salami
hot Spianata salami
blood grapefruit marmalade
rocket/arugula
parmesan cheese
virgin olive oil.

It wasn't very delicious, but I wanted something exotic, and it was exotic. ¯\(ツ)/¯

I can definitely recommend trying out pizza too!

`useStateMachine`: ½ kB state machine hook for React

2021-05-30T12:00:00+03:00

A state machine is a bit like useReducer, but with greater constraints (in a good way). This state machine hook is tiny.

Cassio Zen's useStateMachine hook for React is a tiny (less than half a kilobyte) package for creating state machines. Pair it with Preact, and you have a very small yet powerful bundle for creating stateful UIs.

If you are not familiar with state machines, Cassio explains them in his YouTube video Getting your act together with State Machines (12:35).

State machines are somewhat similar to reducers. From one comment by Cassio under the video:

It's similar, but with one important distinction: with useReducer/redux you can always dispatch any action, and it will always reach the reducer. With state machines, the current state dictates which transitions you can "dispatch" next.

And this small change has a big impact because it empowers you to create your own constraints in the code to make a more robust application.

In the video, Cassio uses a popular state machine library called XState, but the main idea is the same. Sidenotes:

XState is more featureful, but also weighs more, about 19 kB (including the @xstate/react package required by React). Other differences are mentioned in useStateMachine's Wiki page XState comparison.
There's also @xstate/fsm, a 1 kB implementation of XState. Some differences are mentioned in useStateMachine's issue #27.

Two more good videos by Cassio on the topic:

Custom State Machine Hook with useReducer & useEffect (28:36) goes through implementing useStateMachine from scratch. The latest version of the library is a bit more robust (and also a bit more cryptic since it's written in fancy TypeScript).
React useStateMachine hook (18:17) shows two examples how to use the useStateMachine hook.

Sprint-centric vs people-centric daily stand-up meetings

2021-05-30T12:00:00+03:00

A daily stand-up should focus on the sprint. But it should also be about the team members.

In January, I read Critter's (Mike Crittenden) blog post Zombie standups? Try walking the board. Since then, we have been practicing sprint-centric daily stand-ups in our team. Instead of going person by person, we go ticket by ticket.

I think it was a step in the right direction. Previously our daily stand-ups were more chaotic, often not focusing on the sprint enough.

But there's a but. The downside is that there's no good opportunity to discuss ad hoc things. Critter does cover this in his blog post:

But what about general announcements the team needs to hear? After you walk the board, ask "any general things we need to discuss?" and let people speak up.

...but that hasn't worked well. Maybe opening your mouth at the end is just too difficult. For example, some people are shy.

This week we changed back to people-centric daily stand-ups. To help us keep the main focus on the sprint and its goals, I created quick filters in Jira for each person. For example, when it's my turn to speak, I activate the "Matias" quick filter so that only tasks assigned to me are showing on the board. Then it's easy for me to talk about my tasks plus state any other things I have on my mind because I'm already speaking.

The upside so far has been that there has been more ad hoc discussion, meaning more sharing of information relevant to the team.

We'll see in the coming weeks whether this "new old" way of doing daily stand-ups is better or worse.

Cursive (Clojure IDE) supports Parinfer out of the box

2021-05-30T12:00:00+03:00

It's not mentioned in the docs or anywhere, but you can enable Parinfer from Cursive's settings. Works great with IdeaVim.

Paredit bad (for me)

Cursive, the IDE for Clojure and ClojureScript, uses Paredit for structural editing.

Editing code in Cursive has been a hassle because I'm using IdeaVim (a Vim plugin for Cursive and other IntelliJ-based IDEs) and haven't configured keybindings for Paredit. I haven't found any good tutorials on that, so it feels overwhelming. (Otherwise I have liked Cursive when doing Clojure exercises on Exercism.)

Parinfer good (and how to enable it in Cursive)

I have dreamed of using Parinfer in Cursive. Parinfer seems so much easier to use than Paredit.

Today my dreams came true because turns out that Cursive supports Parinfer out of the box! Go to Settings → Editor → General → Smart Keys → Clojure and choose "Parinfer Smart mode" from the "Structural editing style" dropdown.

Rant

What's infuriating is that there's zero mention of Parinfer in the Cursive docs or in Cursive's GitHub Wiki. 🤦‍♂️ I have wasted so much time trying to google "cursive ide parinfer" and finding only a few mentions that "Cursive supports Parinfer" but no information how to enable that. I found the setting today by accident because I was just going to disable Paredit.

Scrolling to top on page changes in React Router (v5)

2021-05-23T12:00:00+03:00

A common solution is to scroll to top every time the page changes. That's incorrect: the page should be scrolled to top only when navigating to new pages, not when navigating back or forward.

Common but wrong solution

When navigating in a Single Page Application (SPA), you have to handle scrolling manually. Here's a solution that's often recommended, but this is wrong:

import { useLocation } from 'react-router-dom'

// Use this hook in some top-level component
// which is inside a `<Router>` component
function useOnPageChange() {
  const { pathname } = useLocation()

  useEffect(() => {
    window.scrollTo(0, 0)
  }, [pathname])
}

It's wrong because the page is scrolled to top on all page changes – even when using the browser's back and forward navigation buttons.

Compare with any non-SPA site, like my website or Wikipedia. When using the browser's back/forward buttons, the previous/next page's scrolling position should be restored. The page should be scrolled to top only when navigating to new pages.

Correct solution

The fix is to check the value of the history object's action parameter:

 

 


  

 import { useHistory, useLocation } from 'react-router-dom'

function useOnPageChange() {
  const { action } = useHistory()
  const { pathname } = useLocation()

  useEffect(() => {
    // Do nothing when using the browser's back/forward buttons
    if (action === 'POP') return

    window.scrollTo(0, 0)
  }, [action, pathname])
}

You could (and probably should) also do other things in the hook, like focus the main heading of the new page.

`` and `` should be treated as progressive enhancement

2021-05-23T12:00:00+03:00

Screen readers don't announce emphasized text, so your text should be understandable even without the emphases.

Martin Underhill writes that bold and italics aren't read by screen readers.

Interestingly, the NVDA screen reader added support for emphasis [in 2015], only to remove it following complaints by users.

I had noticed before that screen readers indeed don't announce if the currently read text is bold or italics.

But I hadn't considered this mindset:

Text-level semantics like italics and bold should be treated as a progressive enhancement. In other words, your sentences should make sense without emphasis; those <em> and <strong> wrappers should just offer a nice added extra for [sighted users].

Makes sense.

Strikethrough is a similar but more difficult case because it adds content. Read Martin's another post Be careful with strikethrough for more details. The post contains several good points why strikethrough is better avoided entirely.

Delegate types in C#: `Action` vs `Func` vs `Predicate`

2021-05-22T12:00:00+03:00

Action doesn't return anything, Func does. Predicate takes one parameter and returns a boolean.

Action<T1, T2, T3, ...>

Action has no return value.

The types T1, T2, T3 and so on specify the parameters' types.

There can be between 0 and 16 parameters:

Action

Action<T1>

Action<T1, T2>

Action<T1, T2, T3>

...

Action<T1, T2, T3, ..., T16>

Examples:

Action takes no parameters and returns nothing.

Action<int> takes one int parameter and returns nothing.

Action<int, bool, int> takes three parameters of types int, bool and int, in that order, and returns nothing.

Action lambda1 = () => { Console.WriteLine("lambda1 was called"); // No return value }; Action<int> lambda2 = (int param1) => { Console.WriteLine($"lambda2 was called with {param1}"); // No return value }; Action<int, bool, int> lambda3 = (int param1, bool param2, int param3) => { Console.WriteLine($"lambda3 was called with {param1}, {param2} and {param3}"); // No return value };

Func<T1, T2, T3, ..., TResult>

Func returns a value of type TResult.

The types T1, T2, T3 and so on specify the parameters' types.

There can be between 0 and 16 parameters:

Func<TResult>

Func<T1, TResult>

Func<T1, T2, TResult>

Func<T1, T2, T3, TResult>

...

Func<T1, T2, T3, ..., T16, TResult>

TResult is always in the last position, i.e. the last type always specifies the return value's type.

Examples:

Func<string> takes no parameters and returns a string.

Func<int, string> takes one int parameter and returns a string.

Func<int, bool, int, string> takes three parameters of types int, bool and int, in that order, and returns a string.

Func<string> lambda1 = () => { return "lambda1 was called"; }; Func<int, string> lambda2 = (int param1) => { return $"lambda2 was called with {param1}"; }; Func<int, bool, int, string> lambda3 = (int param1, bool param2, int param3) => { // `null` return value is ok too // because strings can be null if (!param2) return null; return $"lambda3 was called with {param1}, {param2} and {param3}"; };

Predicate<T>

Predicate returns a boolean.

Predicate takes one parameter of type T.

Examples:

Predicate<int> takes one int parameter and returns a boolean.

Predicate<string> takes one string parameter and returns a boolean.

Predicate<int> IsPositive = (int param) => { return param > 0; }; Predicate<string> StartsWithFoo = (string param) => { return param?.StartsWith("foo") ?? false; };

Predicate<T> vs Func<T, bool>

Predicate<T> is effectively the same as Func<T, bool>. They both take a single parameter of type T and return a boolean.

That said, they are not assignment-compatible. Example from the linked Stack Overflow answer by Daniel Earwicker (slightly modified):

public static bool IsNegative(int x) { return x < 0; } static void Main(string[] args) { Predicate<int> p = IsNegative; Func<int, bool> f = IsNegative; p = f; // Doesn't work f = p; // Doesn't work }

Which one to use, Predicate<T> or Func<T, bool>?

If you can choose, my hunch is that Func is better because:

Func has overloads that take more than one input type, so it's more flexible than Predicate.

Func<T, bool> is clear (given that you know how Funcs work), whereas Predicate is more niche and makes sense only if you know what a "predicate" is.

On the other hand, Predicate<T> is short and descriptive, so I don't have a strong opinion which one to prefer.

Further resources

This blog post was inspired by Scott Steffes's YouTube video Generic Delegate Types (Action, Func, Predicate), in C#. There's interesting discussion about the delegate keyword versus lambda syntax in a Reddit thread around the video.

See also these pages in the .NET docs:

Action Delegate

Func<TResult> Delegate

Predicate<T> Delegate

Comment terminal commands to find them later more easily

2021-05-15T12:00:00+03:00

If you append a comment (like # foo) to a terminal command, you can search by the comment text when using Ctrl+R.

Full example:

curl http://1.2.3.4/linux.iso # Fred's distribution of Linux

Later you can press Ctrl+R and search for e.g. "Fred" to find the command.

The example is from climagic's YouTube video Using comments in the interactive shell (3:32).

4 + 1 wrapping styles for Markdown prose and code comments

2021-05-12T12:00:00+03:00

A paragraph per line, a sentence per line, or hard wrapping at e.g. 80 characters? These days I prefer a fourth option: semantic line breaks.

Context

For a long time I used to hard wrap my Markdown prose and code comments at 80 characters. It looked quite neat.

When a certain colleague touched the same files, he always changed the wrapping style to a sentence per line. Not necessarily for the whole documents, but for the parts that he had modified, e.g. a section in a Markdown file.

I didn't like it at first. My beautiful hard wrapped prose! I was too shy to complain about it, and it wasn't actually that big of a deal.

Eventually I started to like the new style. Now I think it was a step in the right direction.

Benefits of a consistent wrapping style

Why does it matter how you wrap Markdown prose and code comments? While pondering over something like this may seem superficial, a good wrapping style does provide benefits:

Readability.

Code is read more often than it's written, so readability is important. Readability also helps with writing and editing longer pieces of text.

Maintainability.

For example: if you hard wrap at 80 characters, anyone editing the text has to manually update and tweak the wrapping, which can be annoying. Or you can use a tool, but finding a suitable tool and installing and configuring it is one more thing to worry about.

Diffability (version controlling).

For example: if you have a long paragraph on a single line, changing one word highlights the whole paragraph in a Git diff. If you instead have a single sentence or even half a sentence on a single line, changing one word highlights just that single sentence / half a sentence.

Not limited to Markdown

So far I have talked about Markdown (and code comments), but these wrapping styles can be applied to many other lightweight markup languages as well. Here's a non-exhaustive list of other compatible lightweight markup languages:

AsciiDoc, "a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs."

Org mode, "a GNU Emacs major mode for convenient plain text markup – and much more."

reStructuredText, "an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system."

Wikitext, "consists of the syntax and keywords used by the MediaWiki software to format a page." The best known MediaWiki site (or "software") is Wikipedia.

The above list is adapted from a similar list on the website of Semantic Line Breaks specification. The descriptions are copied from the linked pages.

The 4 + 1 wrapping styles

Let's use the following examples for comparing the different wrapping styles:

The following paragraph from my blog post Switch statements: default doesn't have to be the last case:

After some thought, it's actually logical to present the game states (switch cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the default case is at the beginning.

The following code comment from my AutoHotkey script special_characters.ahk:

No need to define separate hotstrings for uppercase letters because hotstrings are "case-conforming" by default. Applies to the ;aring → å hotstring as well.

The Markdown paragraph is rendered in the same way with all wrapping styles. The difference is in how the text looks like in the source code.

(Code comments are often read only in the source code, so the above doesn't apply as well.)

A paragraph per line

Readability

Possibly annoying to read because lines are so long. Depends on the window width of the IDE and whether long lines are hard wrapped automatically.

Maintainability

Paragraphs are easy to identify, so the style is easy to follow.

On the other hand, editing long lines is cumbersome as you can't e.g. rearrange the sentences of a paragraph by rearranging lines.

Diffability

Git diffs are noisy, especially for long paragraphs, because changing a single word highlights the whole paragraph. It looks like the whole paragraph has been touched, and it kind of has because it's on a single line, so you have to manually check what has actually changed.

Markdown example

The line is very long (329 characters), causing a horizontal scroll bar to appear.

After some thought, it's actually logical to present the game states (`switch` cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the `default` case is at the beginning.

Code comment example

Same here: a wild horizontal scroll bar appears!

; No need to define separate hotstrings for uppercase letters because hotstrings are "case-conforming" by default. Applies to the `;aring` → `å` hotstring as well.

A sentence per line

Readability

Better than in the "a paragraph per line" style. The problem is that a sentence can contain multiple points and ideas, so you have to check the whole line to see what's it about.

Long sentences might be annoying to read if they are not automatically hard wrapped by the IDE.

Maintainability

Sentences are easy to identify, so the style is easy to follow.

Sentences can be easily rearranged by rearranging lines.

Might encourage not-too-long sentences because very long lines stand out.

Diffability

Better than in the "a paragraph per line" style. Some lines might still be too long, making diffs noisy.

Markdown example

I like this better than putting the whole paragraph on the same line. The first and last lines are still too long, though.

After some thought, it's actually logical to present the game states (`switch` cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the `default` case is at the beginning.

Code comment example

Same here: this is better, but the first line is too long.

; No need to define separate hotstrings for uppercase letters because hotstrings are "case-conforming" by default. ; Applies to the `;aring` → `å` hotstring as well.

Hard wrapping at e.g. 80 characters

Hard wrapping used to be my favorite wrapping style. My rationale back then:

If you are hard wrapping your code at n characters, it's logical to hard wrap code comments at the same width. And why not hard wrap Markdown prose as well?

(If you are not hard wrapping your code, maybe you should. Configure Prettier or a similar tool and you don't have to think about it manually.)

Readability

Hard wrapped text often looks neat on the surface as the text has a uniform width. There are no horizontal scroll bars or automatic hard wrapping done by the IDE, unless there are very long words (like links) or the window is very narrow.

On the other hand, the text is often annoying to read because hard wrapping doesn't factor in sentence structures and such. It's difficult to see where sentences start and end and what points and ideas the whole paragraph contains.

Sometimes hard wrapping can break syntax highlighting, e.g. when a Markdown link spans on two lines like this:

Here's some intro text, followed by a [link with quite a long text so that it spans on two lines](https://duck.com/).

Lastly: orphan words are annoying, i.e. single words that end up on their own lines. Can be seen in the code comment example below. Also see Widows and orphans on Wikipedia.

Maintainability

Very cumbersome to maintain manually. Change a single word in the middle of a paragraph, and you might have to adjust the wrapping of several lines.

On the other hand, can be done easily with certain tools. For example:

Prettier, works at least with Markdown prose (not sure about code comments).

Rewrap extension for VS Code.

Rewrap extension for Visual Studio.

The downside of using tools is that you also have to get your teammates to install, configure and use them.

Diffability

Often abysmal. Change a single word in the middle of a paragraph, and you might have to adjust the wrapping of several lines. This makes diffs very noisy.

Markdown example

Looks nice on the surface, but is not very nice to read. The two words inside the parentheses unfortunaly end up on different lines.

Looking at the left side of the code block (the first words of the lines) doesn't make much sense: "After... cases... dead... waiting to start... the beginning."

After some thought, it's actually logical to present the game states (`switch` cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the `default` case is at the beginning.

Code comment example

The last line contains an orphan word. It looks lonely and makes the whole comment look unbalanced.

Looking at the second line only, the beginning of it doesn't make sense: "are 'case-conforming' by default." What is it talking about? You need to check the previous line to see that it's talking about hotstrings.

; No need to define separate hotstrings for uppercase letters because hotstrings ; are "case-conforming" by default. Applies to the `;aring` → `å` hotstring as ; well.

Semantic line breaks

The Semantic Line Breaks specification is introed like this:

When writing text with a compatible markup language, add a line break after each substantial unit of thought.

Semantic line breaks are my favorite! I have been using them at least since Nov 2020, i.e. for at least half a year at the time of this writing.

Readability

Lines tend to be short, which reduces the amount of horizontal eye movement, making the text easier to read.

It's also easy to jump around the text vertically looking for capital letters, i.e. where sentences begin and end.

Maintainability

A single line contains a "substantial unit of thought" like a clause or an idea. This makes editing text more powerful because it's easy to rearrange clauses and ideas by rearranging lines. Compare with e.g. hard wrapping: you can't just rearrange lines, because the text wouldn't make sense anymore.

Another benefit, copied from the specification's FAQ section:

Semantic line breaks make it easier to identify grammatical mistakes and find opportunities to simplify and clarify without altering original intent.

And yet another, copied from a comment by Rich Morin in Brandon Rhodes's blog post Semantic Linefeeds:

Another benefit of this technique is that it gives the author (or editor) a chance to examine the text in two very different formats: monospace with line breaks and proportional without. This helps greatly in finding errors.

One drawback is that it might be difficult to decide/learn what is a semantic line break, or what is a "substantial unit of thought." Thus, different people might wrap the same text differently.

If you are working in a team, it might lead to slight inconsistencies.

If you are working solo, it's not a problem. You'll quickly come up with your own style.

Diffability

Excellent. Small changes tend to produce clean diffs.

For a visual example, see Brandon Rhodes's blog post Semantic Linefeeds.

Markdown example

The text looks a bit unbalanced, but each line contains a single thing. I'm sure someone else would wrap this code differently, even if we both used semantic line breaks. :-)

After some thought, it's actually logical to present the game states (`switch` cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the `default` case is at the beginning.

Code comment example

Yay, the orphan word is gone.

The second line makes sense on its own: "(because) hotstrings are 'case-conforming' by default."

; No need to define separate hotstrings for uppercase letters ; because hotstrings are "case-conforming" by default. ; Applies to the `;aring` → `å` hotstring as well.

+1: Chaos

If you don't deliberately choose a specific style for wrapping code comments and prose, you'll eventually have lots of inconsistencies. Inconsistencies lead to chaos, and chaos means poor readability and maintainability.

Further resources

Hat tip to the Semantic Line Breaks specification for teaching me a better alternative to hard wrapping. My earlier blog post RFC 2119 in a nutshell might be helpful for interpreting the specification.

Brandon Rhodes's blog post Semantic Linefeeds from 2012 covers the same general idea as semantic line breaks. It has an example of the diffing benefits and musings on the history of semantic line breaks.

Two-way data binding in React

2021-05-08T12:00:00+03:00

Normally you would use one-way data binding in React apps: parent components own data and pass it to children. You can mimic two-way data binding with a custom hook.

One-way data binding

React uses one-way data binding for controlled components: a parent passes to its child the current state value and a function to update the value. For example:

function App() { const [value, setValue] = useState('John') const update = (e) => setValue(e.target.value) const reset = () => setValue('') return ( <> <input value={value} onChange={update} /> <div>Hello {value}</div> <button onClick={reset}>Reset</button> </> ) }

This way the input element (the child) never mutates the state. Instead it calls the update function (via the onChange event), so that the parent can update the state and pass the new value to the input element.

So far this is very basic stuff.

AngularJS 1 used to have two-way data binding: a parent passes only the state to its child, and the child can directly mutate the state!

If the parent updates the state, the child will receive the new value.

If the child updates the state, the parent will receive the new value.

When the parent receives a new value, it can't know where the new value is coming from, and it can't prevent the child from updating the value.

Two-way data binding is nowadays considered a bad practice because it can easily lead to unpredictability (can't know what's changing state) and poor performance. Possibly for other reasons too.

Two-way data binding

On the upside, two-way data binding makes code cleaner as you don't have to manually deal with event listeners and stuff. Just pass a state to a child and you're done.

Sandro Roth's blog post Two-way Data Binding in React shows how you can mimic two-way data binding in React by writing a custom hook. Like this:

function useModel(initialValue = '') { const [value, setValue] = useState(initialValue) const update = (e) => setValue(e.currentTarget.value) return { model: { value, onChange: update }, setModel: setValue, } } function App() { const { model, setModel } = useModel('John') const reset = () => setModel('') return ( <> <input {...model} /> <div>Hello {model}</div> <button onClick={reset}>Reset</button> </> ) }

Notice how we are passing (via spreading) only a "model" to the input element. The model contains the current value and a function to update the value from the child.

This is ultimately still one-way data binding – the parent is still the single source of truth for the state – but it looks cleaner and allows reusage of the logic contained in the useModel hook.

Check out Sandro's article for more details!

(Also thanks to Sandro for our email exchange over this topic. 😊)

Site-specific components in a (React) multi-site

2021-05-01T12:00:00+03:00

A multi-site React project has likely two kinds of components: common components and site-specific components. There are a few ways to handle site-specific logic in common components.

Common components are used by two or more sites and reside e.g. under the src/common/ folder.

Site-specific components are used only by one site and reside e.g. under the folders src/site-a/, src/site-b/ and so on.

An example of a common component is Link: a hyperlink with certain styles and logic, used on all sites for most links.

Let's say that Site A, and only that site, requires some extra logic in the Link component. What are my options? Let's think:

Add the extra logic to the common Link component. This would be messy, because the common component would then have site-specific logic in it.

Create an entirely separate, site-specific Link component for Site A. I don't like this option because the common and site-specific Link components would have lots of duplicate code. Links are very common, so any future changes would have to be made to two components.

Create a "child component" for Site A, so that the site-specific component ultimately renders the common Link component. This would be nice, but the problem would be that developers would need to remember to import the site-specific component when working on Site A's code, and to import the common component when working on the other sites' codes.

I eventually found a way to avoid the problem in the third option! Behold: Using ESLint to restrict where files can be imported from.

Using ESLint to restrict where files can be imported from

2021-05-01T12:00:00+03:00

There's an ESLint rule to prevent importing certain files in certain folders. I needed this in a multi-site project to prevent importing site-specific components in other sites' folders.

I'm talking about the no-restricted-paths ESLint rule, provided by the eslint-plugin-import plugin:

Some projects contain files which are not always meant to be executed in the same environment. For example consider a web application that contains specific code for the server and some specific code for the browser/client. In this case you don't want to import server-only files in your client code.

In my case I needed the rule to make using site-specific components more convenient. Context: Site-specific components in a multi-site (React) project.

Here's what I added to the project's ESLint config to solve the problem discussed in the linked blog post:

module.exports = { 'import/no-restricted-paths': [ 'error', { zones: [ { target: 'src/site-a/', from: 'src/common/Link.js', message: 'Import the site-specific Link component instead.', }, ], }, ], }

The config makes ESLint throw an error if src/common/Link.js is imported in any file under src/site-a/. Plus ESLint will show the custom message so no one has to guess why importing the common Link component fails. Excellent!

To prevent importing certain npm packages, you could use ESLint's native rule no-restricted-imports. A useful example case is if you want developers to import your own Link component instead of React Router's Link component.

My new webcam: Logitech BRIO

2021-04-24T12:00:00+03:00

Maybe a bit of an overkill, but much more convenient than using my iPad as a webcam or my laptop's integrated webcam.

My previous webcams

I have previously used my iPad mini as a webcam via the EpocCam app. It has worked well, but it's always a hassle to set up a stand for the iPad. The iPad is also blocking a big portion of my monitor.

My laptop has an integrated webcam, but it's too far to the side when using an external monitor, so I haven't used it. I suspect it wouldn't even have good quality.

Logitech BRIO

Some months ago I bought a new microphone.

This week I bought a new webcam: Logitech BRIO.

I already used the BRIO in one Teams meeting, and it worked well.

I like that the BRIO just stays on top of my monitor. There's no setting it up and opening an app every time I want to use it, unlike when using iPad via EpocCam.

Frequency illusion

2021-04-24T12:00:00+03:00

That cool thing you just heard about – is it suddenly gaining popularity, or are you just noticing the topic more?

After learning about a new topic, it sometimes seems to quickly surge in popularity. Like "wow, this topic is nowadays being covered everywhere" or "awareness of this topic is clearly increasing, nice."

That's possible. Or, it's also possible that you are just noticing the topic more.

Here's what Wikipedia tells us about frequency illusion:

Frequency illusion, also known as the Baader–Meinhof phenomenon, is a cognitive bias in which, after noticing something for the first time, there is a tendency to notice it more often, leading someone to believe that it has a high frequency (a form of selection bias). It occurs when increased awareness of something creates the illusion that it is appearing more often. Put plainly, the frequency illusion is when "a concept or thing you just found out about suddenly seems to crop up everywhere."

I had been looking for a term for this phenomenon. Now let's see if I start to notice lots of coverage of the frequency illusion.

\*Vertical* centering in CSS with `margin: auto`

2021-04-24T12:00:00+03:00

margin: auto is not only for horizontal centering.

margin: auto normally centers a block element only horizontally. To achieve vertical centering, it's common to reach for e.g. flexbox.

Turns out that margin: auto can in some cases center vertically as well. The element must also have:

position: absolute or position: fixed

top: 0 and bottom: 0

an explicit height (e.g. height: 200px).

This can be very useful for modals.

Note that for only vertical centering, only margin-top and margin-bottom need to be set to auto; margin-right and margin-left can be anything. This is similar to horizontal centering: only margin-right and margin-left need to be set to auto; margin-top and margin-bottom can be anything.

See an example on flems.io.

I learned this from Josh W Comeau's CSS for JavaScript developers course (Module 2).

`position: fixed` breaks if any of its ancestors uses `transform`

2021-04-24T12:00:00+03:00

Or perspective or filter. This can easily cause confusing bugs.

position: fixed works mostly the same way as position: absolute does.

position: absolute is positioned relative to its closest positioned ancestor.

position: fixed is positioned relative to the viewport.

However, in the case of position: fixed, if any of the element's ancestors (i.e. parent or any of the grandparents) has a transform property set to something else than none, the element's positioning "breaks." The fixed element is then positioned relative to that ancestor, i.e. position: fixed behaves like position: absolute.

This can easily cause confusing bugs.

I learned this from Josh W Comeau's CSS for JavaScript developers course (Module 2).

MDN's documentation on position: fixed mentions that the perspective and filter properties also break position: fixed, but "there are browser inconsistencies with perspective and filter contributing to containing block formation."

JavaScript functions have a `length` property

2021-04-17T12:00:00+03:00

A bit exotic, but can be useful for currying.

Function.length

The length property of a function returns the number of required arguments:

(() => {}).length //=> 0 ((a) => {}).length //=> 1 ((a, b) => {}).length //=> 2 ((a, b, c) => {}).length //=> 3 ((a, b, c = 'default') => {}).length //=> 2 ((a, ...args) => {}).length //=> 1 ((...args) => {}).length //=> 0

I learned this from a tweet by Mikael Ainalem.

See also Function.length on MDN.

Trust issues

Robin Pokorny says that the length property is not to be trusted because it can be overridden:

const fn = (a, b) => {} fn.length //=> 2 Object.defineProperty(fn, 'length', { value: 3 }) fn.length //=> 3

But don't do that. 😄

Example: currying

One practical use of Function.length is to use it to create a currying function:

const curry = (fn, ...args) => fn.length > args.length ? curry.bind(null, fn, ...args) : fn(...args) const mul = (a, b, c) => a * b * c curry(mul, 1, 2, 3) //=> 6 curry(mul, 1, 2)(3) //=> 6 curry(mul, 1)(2, 3) //=> 6 curry(mul, 1)(2)(3) //=> 6 curry(mul)(1, 2, 3) //=> 6 curry(mul)(1, 2)(3) //=> 6 curry(mul)(1)(2, 3) //=> 6 curry(mul)(1)(2)(3) //=> 6

Source of the curry function: Babak's reply to Mikael's tweet.

Different logics behind heights and widths in CSS

2021-04-17T12:00:00+03:00

height and width work somewhat differently in CSS. height looks "down" the tree whereas width looks "up" the tree.

Full quote:

height tends to look "down" the tree, to determine its size based on the natural size of its contents, while width tends to look "up" the tree, basing its size on the space made available by the parent.

The quote is from Josh W Comeau's CSS for JavaScript developers course (Module 1).

I don't know if the quote makes sense on its own (without more context). But I thought it describes the difference between height and width very clearly yet succinctly, so I wanted to share it here.

Block vs inline directions in CSS

2021-04-10T12:00:00+03:00

Block elements stack on top of each other. Inline elements are placed side by side.

Web pages vs paper documents

Web pages are like paper documents.

Individual words are inline and placed side by side, from left to right (or right to left in some languages).

Some words are combined into blocks (e.g. headings and paragraphs) that stack on top of each other, from top to bottom (or bottom to top in some obscure languages).

So, that's the two directions of CSS: block and inline. And that's how display: block and display: inline work too:

Block elements (display: block) take the full available width by default so that they stack on top of each other. Think of e.g. headings, paragraphs and <div> elements.

Inline elements (display: inline) are placed side by side. Think of e.g. individual words and <span> elements.

This is very basic, but explaining block and inline directions by comparing a web page to a regular paper document was somehow eye-opening to me. I like this mental model that I learned from Josh W Comeau's CSS for JavaScript developers course (Module 1).

Logical properties

Understanding the two directions is also essential for understanding logical properties in CSS.

For example, when working with right-to-left (RTL) languages, you might want to use margin-inline-start and margin-inline-end instead of margin-left and margin-right. The latter properties would be in reverse or "wrong" order when working with RTL languages.

Updating React context outside of a component

2021-04-03T12:00:00+03:00

React context is normally updated inside the React app. Here's a hacky way how I circumvented that restriction in a test file.

Example problem

Let's say I have a React component called MyComponent which uses a React context called MyContext.

When the value of the context changes, the component does something, e.g. makes an Adobe Analytics tracking call:

function MyComponent() { const myContext = useContext(MyContext) useEffect(() => { window._satellite.track(myContext) }, [myContext]) return null }

And then I want to write unit tests for that... But how can I do that since React contexts can't be easily updated outside of React components?

Hacky workaround

I realized that in the test file, I can pass an empty object for the wrapper component (App in this case) as a prop (named contextUpdater).

Inside App, I can store a reference to the context value setter function (setValue in this case) under the given prop object.

Then, in a test case, I can call contextUpdater.setValue – outside of the component!

Like so:

/* MyComponent.test.js */ describe('MyComponent', () => { function App({ contextUpdater = {} }) { const [value, setValue] = useState('initial value') // This hack allows us to update the context value outside of the component contextUpdater.setValue = setValue return ( <MyContext.Provider value={[value, setValue]}> <MyComponent /> </MyContext.Provider> ) } beforeEach(() => { global._satellite = { track: jest.fn() } }) it('makes a tracking call when MyContext changes', () => { const contextUpdater = {} render(<App contextUpdater={contextUpdater} />) expect(global._satellite.track).toHaveBeenCalledTimes(1) act(() => contextUpdater.setValue('new value')) expect(global._satellite.track).toHaveBeenCalledTimes(2) act(() => contextUpdater.setValue('third value')) expect(global._satellite.track).toHaveBeenCalledTimes(3) }) })

It works! IQ 200! Proud moment of the week.

Too hacky?

So yeah, actually this feels very hacky, probably because this is hacky.

Another question is whether the test is too implementation-specific. On the other hand, MyComponent directly depends on MyContext, so I'm not sure.

Anyway, the test passes, so I think this is good enough for now.

Excel stores time durations as days

2021-04-03T12:00:00+03:00

For example, 6 hours is stored as 0.25 days. To format a duration as hh:mm:ss.000, first convert the duration to days.

Example problem

A friend of mine consulted me with this problem: he was copy-pasting a bunch of time durations to Excel and wanted to calculate their average duration.

The values were not in Excel-friendly format, and he didn't want to modify them by hand, so Excel's AVERAGE function didn't work out of the box.

Here's an example of a single time duration:

1:39.811

That's one minute, 39 seconds and 811 milliseconds.

Failed attempts

I first tried to change the formatting of the data, hoping that Excel would correctly identify the data as time durations. But I couldn't get that to work.

I then tried to parse the text and pass its parts to the TIME function which takes three parameters: hours, minutes and seconds. But passing a decimal number (i.e. seconds with milliseconds) as the third parameter didn't work.

Solution

Converting the raw data to milliseconds

In the end, I found it easiest to convert the raw data to milliseconds using Excel's LEFT, MID and RIGHT functions.

Here's the formula for the B column, assuming that the original data resides in the A column:

// A1 contains a duration, e.g. "1:39.811" // B1 contains the duration in milliseconds. // In this case it would be "99811" = // Minutes: // the first character from the left. // Doesn't support 10+ minute durations, // but that's probably OK with this data. LEFT(A1; 1) * 1000 * 60 // Seconds: // starting from the third character (1-indexed), // take two characters in the middle. + MID(A1; 3; 2) * 1000 // Milliseconds: // the three rightmost characters. + RIGHT(A1; 3)

Now that the B column contains the time durations in milliseconds, it's easy to calculate the average value:

=AVERAGE(B1:B999)

But how to format the result as a time duration?

Displaying milliseconds as a duration

Luckily, someone had asked "[How to] convert milliseconds to hh:mm:ss.000" on Reddit four years ago, and someone called sqylogin had shared this nugget of wisdom (formatted for clarity):

Excel stores data in days.

Therefore, 1 millisecond = 1/24/60/60/1,000 = 1/86,400,000.

To convert 586 milliseconds to an Excel "day," divide it by 86.4 million, and in the resulting cell, use this custom number format: HH:MM:SS.000.

Ah, so calculating the average time duration is as easy as this:

=AVERAGE(B1:B999) / 86400000

Plus the formatting of the cell displaying the average value needs to be set to this:

m:ss.000

Egg-cellent! Now my friend can keep copy-pasting values to the A column, and the average value will be updated automatically. He can even hide the B column since it's only used as an intermediate step to calculate the average value.

The actual learning

Excel is often a very powerful and quick tool to use. But sometimes it doesn't work like I would want it to, so I end up fighting it and coming up with hacky solutions like this.

To be fair, maybe that applies to all tools and even programming in general.

"Blocked plug-in" error in Safari when opening a PDF file

2021-03-20T12:00:00+03:00

Try to add object-src 'self'; to the Content Security Policy. Then your users don't have to download the file to view it.

The problem

I was investigating an issue where Safari failed to display a PDF file. It instead just showed the text "Blocked plug-in."

The problem occurred only in desktop Safari.

The fix

The user could download the file to view it, but that would be cumbersome.

I did some quick googling but didn't find any good results.

Then I noticed that Safari's console showed an error message related to Content Security Policy (CSP).

In the end, the fix was to add object-src 'self'; to the CSP.

Interesting that other browsers don't require that setting.

Read about the object-src CSP directive on MDN.

Broken CSS-animated SVG files in Safari and iOS Safari

2021-03-20T12:00:00+03:00

Some parts of an SVG were missing and some parts were distorted. I had to render the SVG via an <svg> element instead of loading it via an <img> element.

The problem

I was loading an SVG file via an <img> element. The SVG file had CSS animations embedded in it.

Safari and iOS Safari rendered the SVG in a very buggy way: some parts were missing and some parts were distorted.

The fix

I did some quick googling but didn't find a clear cause. I did find some speak along the lines of "Safari is bad at rendering SVGs."

In the end, the fix was to inline the SVG file. I.e. render it directly via an <svg> element instead of loading it via an <img> element.

The downside is that now the file can't be cached by the browser.

Firefox DevTools can explain why some CSS styles have no effect

2021-03-20T12:00:00+03:00

It's frustrating when a CSS declaration is technically valid (not crossed out in the browser's DevTools) but has no effect for some reason. Firefox DevTools can often tell you why and also how to potentially fix those issues! (Update: Chrome 108+ can too.)

Starting from Firefox 70 (released in October 2019), its DevTools contain "inactive CSS rules indicators" that explain why some styles have no effect:

I use Firefox as my daily browser, but usually switch to Chrome when doing web development because Firefox DevTools often feel buggy. Good to know that Firefox DevTools can be very helpful in these frustrating CSS situations.

I learned this trick from Josh W Comeau's CSS for JavaScript Developers course (Module 0).

Later I also found Elijah Manor's video explaining the feature.

Update on Oct 13, 2022: Jecelyn Yeen just tweeted that Chrome Canary has now a similar feature.

Update on Dec 5, 2022: The feature is now part of stable Chrome: What's New In DevTools (Chrome 108).

4+ types of documentation

2021-03-20T12:00:00+03:00

Splitting documentation into multiple categories can make the documentation much clearer.

4 types

Divio's documentation system splits documentation into four types:

Tutorials are learning-oriented; they teach how to get started.

How-to guides are problem-oriented; they guide how to achieve a certain goal.

Explanations are understanding-oriented; they clarify a certain topic.

References are information-oriented; they describe the system and how to use it. (E.g. what methods are available, what parameters they take and what they return.)

The four types are quite similar to each other.

But if you don't realize that there are these different types of documentation, the types get mixed very easily, and the documentation gets messy.

Alternative descriptions

From a Reddit comment by Kinrany:

Tutorial: practical steps for learning.

How-to guide: practical steps for working.

Explanation: theoretical knowledge for learning.

Reference: theoretical knowledge for working.

Different names

A good point from a related discussion on Hacker News: the different types may have different names.

For example, explanations could also be called:

Backgrounds

Deep dives

Discussions

Overviews

Rationales.

More types

Another good point from the Hacker News discussion: there can be other types of documentation as well.

For example:

Introduction

Announcements

Case studies

Code samples

Release notes.

These types might fit into one of the four categories, or they might not.

Turning constructor params into class props in TypeScript

2021-03-13T12:00:00+03:00

"Parameter properties" reduce boilerplate in classes, but they can also make the code hard to read.

Definition of parameter properties

Parameter Properties are defined in the TypeScript docs like so:

TypeScript offers special syntax for turning a constructor parameter into a class property with the same name and value. These are called parameter properties and are created by prefixing a constructor argument with one of the visibility modifiers public, private, protected, or readonly.

Example

The two classes below are effectively identical.

Before: ordinary class properties

// Ordinary class properties class Foo { public readonly x: number protected y: number private z: number constructor(x: number, y: number, z: number) { this.x = x this.y = y this.z = z } }

After: parameter properties

// Parameter properties class Foo { constructor( public readonly x: number, protected y: number, private z: number ) {} }

Verdict

I like that parameter properties reduce boilerplate and verbosity. But they are potentially confusing if they are mixed with ordinary class properties – it might be hard to see at a glance all the properties that the class has.

Cool way to check for leap years in JavaScript

2021-03-13T12:00:00+03:00

Spoiler: new Date(year, 1, 29).getDate() === 29.

I stumbled upon a tweet by Colin DeCarlo about a cool way to check if a given year is a leap year (code by JleCoRyl3):

function isLearYear(year) { return new Date(year, 1, 29).getDate() === 29 }

Quite clever! Though a bit confusing at first because months are 0-indexed. Maybe a code comment would be in order.

The tweet is what inspired me to start doing TypeScript exercises on Exercism.

Cleaner unit test mocking in C# with NSubstitute

2021-03-13T12:00:00+03:00

The NSubstitute package simplifies how mock implementations are created and how mocks are used.

Moq

I have previously used Moq, "the most popular and friendly mocking library for .NET," to do mocking in unit tests.

Example from Nick Chapsas's video on the Moq package (_sut = system under test):

private readonly CustomerService _sut; private readonly ICustomerRepository _customerRepositoryMock = new Mock<ICustomerRepository>(); private readonly ILoggingService _loggerMock = new Mock<ILoggingService>(); public CustomerServiceTests() { _sut = new CustomerService(_customerRepositoryMock.Object, _loggerMock.Object); } [Fact] public async Task GetByIdAsync_ShouldReturnCustomer_WhenCustomerExists() { // ... // Mock implementation _customerRepositoryMock.Setup(x => x.GetByIdAsync(customerId)) .ReturnsAsync(customerDto); // ... }

NSubstitute

Nick Chapsas's video on the NSubstitute package convinced me that NSubstitute, "a friendly substitute for .NET mocking libraries," could be nicer.

Example from the video:

private readonly CustomerService _sut; private readonly ICustomerRepository _customerRepository = Substitute.For<ICustomerRepository>(); private readonly ILoggingService _logger = Substitute.For<ILoggingService>(); public CustomerServiceTests() { _sut = new CustomerService(_customerRepository, _logger); } [Fact] public async Task GetByIdAsync_ShouldReturnCustomer_WhenCustomerExists() { // ... // Mock implementation _customerRepository.GetByIdAsync(customerId).Returns(customerDto); // ... }

Differences to Moq

No need to use .Object in various places.

Creating mock implementations is more straightforward.

Cleaner unit test assertions in C# with Fluent Assertions

2021-03-13T12:00:00+03:00

The Fluent Assertions package makes unit test assertions read like English and also improves the error messages.

Watching Nick Chapsas's video on the Fluent Assertions package made me want to start using Fluent Assertions at work.

Example from the video (_sut = system under test):

// Before Assert.Equal(expected, result); Assert.StartsWith("The result is: ", _sut.Text); Assert.EndsWith(result.ToString(), _sut.Text); // After result.Should().Be(expected); _sut.Text.Should().StartWith("The result is: "); _sut.Text.Should().EndWith(result.ToString());

So much better. Reads like English.

Another benefit is that the messages from failed assertions are more detailed.

How to disable ImageProcessor's upscaling feature

2021-03-10T12:00:00+03:00

Disabling the upscaling feature (by default or completely) can be done via ImageProcessor's ValidatingRequest event. It's not possible via a config file.

What's upscaling?

ImageProcessor's resize method lets you modify the dimensions of an image on the fly, by using URL parameters. For example:

<img alt="" src="/my-image.jpg?width=2000&height=1000" /> <img alt="" src="/my-image.jpg?width=2000&heightratio=0.5625" />

Upscaling means that an image is resized to dimensions greater than its original dimensions. This can cause blurry images, so you might want to disable the upscaling feature.

You can disable upscaling on a case-by-case basis with the upscale URL parameter:

<img alt="" src="/my-image.jpg?width=2000&height=1000&upscale=false" /> 

Doing so manually will however quickly become cumbersome. Let's see how to disable it programmatically.

Not possible via a config file

According to GitHub issue #583 and issue #767, it's not possible to disable the upscaling feature via a config file.

Disable via an event

The disabling of the upscaling feature needs to be done via ImageProcessor's ValidatingRequest event. See the Events section in ImageProcessor's docs.

Add the code maybe to the Application_Start event in Global.asax. Or if using Episerver, create an initialization module:

[InitializableModule] public class ImageProcessorEventsInitialization : IInitializableModule { public void Initialize(InitializationEngine context) { ImageProcessingModule.ValidatingRequest += DisableUpscalingByDefault; // or ImageProcessingModule.ValidatingRequest += DisableUpscaling; } public void Uninitialize(InitializationEngine context) { ImageProcessingModule.ValidatingRequest -= DisableUpscalingByDefault; // or ImageProcessingModule.ValidatingRequest -= DisableUpscaling; } private void DisableUpscalingByDefault(ImageProcessingModule sender, ValidatingRequestEventArgs args) { // ... } // or private void DisableUpscaling(ImageProcessingModule sender, ValidatingRequestEventArgs args) { // ... } }

Disable by default

/// <summary> /// Disable ImageProcessor's upscaling feature by default. /// Upscaling can be enabled for individual images /// with the <c>upscale=true</c> URL parameter. /// </summary> /// <remarks> /// Not possible via configuration: /// <list type="bullet"> /// <item>https://imageprocessor.org/imageprocessor-web/imageprocessingmodule/#events</item> /// <item>https://github.com/JimBobSquarePants/ImageProcessor/issues/583</item> /// <item>https://github.com/JimBobSquarePants/ImageProcessor/issues/767</item> /// </list> /// /// Code from https://mtsknn.fi/blog/how-to-disable-imageprocessors-upscaling-feature/ /// </remarks> private void DisableUpscalingByDefault(ImageProcessingModule sender, ValidatingRequestEventArgs args) { if (String.IsNullOrWhiteSpace(args.QueryString)) { return; } var queryCollection = HttpUtility.ParseQueryString(args.QueryString); // The URL parameter has already been set, // so let's not modify it if (queryCollection.AllKeys.Contains("upscale")) { return; } queryCollection.Add("upscale", "false"); args.QueryString = queryCollection.ToString(); }

Disable completely

/// <summary> /// Disable ImageProcessor's upscaling feature completely. /// Image URLs' <c>upscale</c> URL parameter won't have any effect. /// </summary> /// <remarks> /// Not possible via configuration: /// <list type="bullet"> /// <item>https://imageprocessor.org/imageprocessor-web/imageprocessingmodule/#events</item> /// <item>https://github.com/JimBobSquarePants/ImageProcessor/issues/583</item> /// <item>https://github.com/JimBobSquarePants/ImageProcessor/issues/767</item> /// </list> /// /// Code from https://mtsknn.fi/blog/how-to-disable-imageprocessors-upscaling-feature/ /// </remarks> private void DisableUpscaling(ImageProcessingModule sender, ValidatingRequestEventArgs args) { if (String.IsNullOrWhiteSpace(args.QueryString)) { return; } var queryCollection = HttpUtility.ParseQueryString(args.QueryString); queryCollection.Set("upscale", "false"); args.QueryString = queryCollection.ToString(); }

Notice the usage of queryCollection.Set() instead of queryCollection.Add().

Source

Original solution found in the GitHub issue #583.

My notes on two nice .NET refactoring videos

2021-03-06T12:00:00+03:00

YouTube recommended me a two-part video series that was fun to watch and gave me a few lightbulb thoughts.

Part 1: preparations

YouTube recommended me Nick Chapsas's video (part 1) about refactoring some .NET code. It was great.

In the first part of the two-part video series, Nick makes the code testable by extracting its dependencies and injecting them back via constructor injection. This way the dependencies can be mocked in unit tests.

Then he creates unit tests for the code before doing any refactoring. Otherwise it would be too easy to accidentally modify the logic of the code.

Part 2: refactorings

In the part 2 video, Nick does the actual refactoring. Three things struck in my mind.

Renaming method parameters can cause backwards incompatibility in C#

One method parameter has a typo in its name. It would be tempting to rename it, but it would be a breaking change to the consumers of the code (warranting a major version increment) because C# supports named arguments. That's a good point that I would have missed.

When are interfaces needed?

Nick creates interfaces for the extracted dependencies to make them mockable, expect for one class. That class doesn't need mocking, so it doesn't necessarily need an interface.

Using tuples instead of creating simple classes

One method needs to return two values. You could create a simple class for the return value, but Nick uses a tuple, skipping the need for creating that simple class.

Smoother CSS animations with the `will-change` property

2021-03-06T12:00:00+03:00

The will-change property makes the browser render an element with the GPU, which can reduce jankiness and also allows utilizing sub-pixel rendering. But use the property sparingly.

CPU vs GPU

The beginning and ending of CSS animations can sometimes be glitchy because some property transitions (like transform) are rendered with the GPU, whereas the elements are otherwise rendered with the CPU.

I learned about the will-change CSS property from Josh W Comeau's comprehensive article An Interactive Guide to CSS Transitions. From the Hardware acceleration section:

GPUs and CPUs render things slightly differently. [...]

We can fix this problem by adding the following CSS property:

.btn { will-change: transform; }

will-change is a property that allows us to hint to the browser that we're going to animate the selected element, and that it should optimize for this case.

In practice, what this means is that the browser will let the GPU handle this element all the time. No more handing-off between CPU and GPU, no more telltale "snapping into place".

Sub-pixel rendering

There's another benefit to hardware acceleration: we can take advantage of sub-pixel rendering.

Properties like margin-top can't sub-pixel-render, which means they need to round to the nearest pixel, creating a stepped, janky effect. transform, meanwhile, can smoothly shift between pixels, thanks to the GPU's anti-aliasing trickery.

Use will-change sparingly

Note however that you shouldn't overuse the will-change property, like Josh later mentions. It's also mentioned on the will-change page on MDN:

Important: will-change is intended to be used as a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems.

If everything (every animation or transition) is prioritized, nothing is.

CSS: `display: flow-root` is better than the clearfix hack

2021-03-06T12:00:00+03:00

The flow-root value is clearer (no hacks!) and has great browser support.

display: flow-root is described on Can I use like so:

The element generates a block container box, and lays out its contents using flow layout. It always establishes a new block formatting context for its contents. It provides a better solution to the most use cases of the "clearfix" hack.

The browser support of the flow-root value is excellent (supported by all modern browsers). That's quite funny, because I don't remember hearing about this value before. I also don't remember where I found it.

Action-driven CSS animations

2021-03-06T12:00:00+03:00

Polish your animations by animating based on actions or events, like mouse-enter and mouse-leave, instead of animating based on states, like default and hover state.

I got the idea from Josh W Comeau's comprehensive article An Interactive Guide to CSS Transitions. From the Action-driven motion section:

I believe most developers think in terms of states: for example, you might look at this situation and say that we have a "hover" state and a default state. Instead, what if we thought in terms of actions? We animate based on what the user is doing, thinking in terms of events, not states. We have a mouse-enter animation and a mouse-leave animation.

Example: modals

Another common example is modals. It can be useful for modals to enter with an ease-out animation, and to exit with a quicker ease-in animation.

This is a small detail, but it speaks to a much larger idea.

Exiting a modal quickly is great because if the user has closed the modal, they are not interested in it anymore. Having to watch the modal slide away slowly would be pointless.

Casting in C#: cast expression vs `as` and `is` operators

2021-03-03T12:00:00+03:00

A cast expression like (string)foo throws if the types don't match. The as operator doesn't throw and defaults to null. The is operator doesn't throw and ignores nulls.

Cast expression

Sometimes called "direct casting."

try { var bar = (string)foo; // `bar` is a `string` (can be `null`) } catch (InvalidCastException) { // `foo` is not a `string` }

If foo is not a string: throws InvalidCastException.

Otherwise assigns foo to bar (can be null).

Use when you are sure that the type is correct.

as operator

var bar = foo as string; if (bar != null) { // `bar` is a `string` and not `null` }

If foo is not a string: assigns null to bar; doesn't throw.

Otherwise assigns foo to bar (can be null).

Use when the type might be correct.

is operator

if (foo is string) { // `foo` is a `string` and not `null` } if (foo is string bar) { // `bar` is a `string` and not `null` }

If foo is not a string or is null: returns false.

Otherwise returns true.

Also in the second example above: assigns foo to a new variable bar.

Use in if statements to combine the usage of the as operator and null check.

Use in switch statements for type pattern matching.

Mnemonic: cast expression vs as operator

Use the as operator when you only as-sume^[1] that the type is correct. If your assumption is incorrect, that's okay! You'll get a null and no exception will be thrown.

Conversely, if you are sure that the type is correct, use a cast ex-pression. You'll be punished with an ex-ception if you are wrong.

Sources / Further resources

Direct casting vs 'as' operator? on Stack Overflow

Cast expression on Microsoft Docs

as operator on Microsoft Docs

is operator on Microsoft Docs

Type testing with pattern matching on Microsoft Docs

Footnotes

See English: assume vs presume. ↩

Name front-end test cases from user perspective

2021-02-27T12:00:00+03:00

Such naming helps you create tests that resemble the way your users use your app.

I noticed that a colleague from another team had named their test cases from user perspective, like this:

describe('<FooComponent>', () => { test('user can see all options', () => { // ... }) test('user can toggle between options', () => { // ... }) // etc. })

I was already familiar with the primary guiding principle of React Testing Library:

The more your tests resemble the way your software is used, the more confidence they can give you.

But I hadn't thought of naming test cases from this perspective. Makes sense, though! Naming test cases from user perspective helps you create good tests – tests that resemble the way your users use your app.

Episerver + AutoMapper is a confusing combo

2021-02-27T12:00:00+03:00

Blocks in Episerver implement the IContent interface only during runtime which makes using AutoMapper difficult.

A few weeks ago I started using AutoMapper in an Episerver (.NET CMS) project to map models to view models semi-automatically.

My initial feelings: 😻

It was quite nice until I started creating mappings for blocks (reusable pieces of content).

My feelings now: 😿😾

Whereas page models implement Episerver's IContent interface "normally," block models implement the IContent interface only during runtime.

This means that creating a mapping from IContent to a block type is not possible. At least not possible in this way that I tried:

          // Base view model for pages and blocks public interface IContentViewModel { string ContentLink { get; set; } string ContentType { get; set; } // etc. } public class IContentProfile : Profile { public IContentProfile() { CreateMap<IContent, IContentViewModel>(); } } public class MyPageViewModel : IContentViewModel { // ... } public class MyPageProfile : Profile { public MyPageProfile() { CreateMap<MyPage, MyPageViewModel>() // `MyPage` implements `IContent`, so this is ok: .IncludeBase<IContent, IContentViewModel>(); } } public class MyBlockViewModel : IContentViewModel { // ... } public class MyBlockProfile : Profile { public MyBlockProfile() { CreateMap<MyBlock, MyBlockViewModel>() // Error! `MyBlock` doesn't implement `IContent` until runtime, // so this doesn't work: .IncludeBase<IContent, IContentViewModel>(); } }

I eventually came up with a solution, but it feels very complex and very verbose.

I don't know if AutoMapper should be this difficult. If you are working on an Episerver project, my suggestion would be to research alternative mappers or do mappings manually.

Prefer accessible queries with (React) Testing Library

2021-02-27T12:00:00+03:00

Accessible queries take into account the semantic meaning of HTML elements. Such queries help you write more accessible apps.

Your app probably has lots of text in various kinds of HTML elements:

headings (<h1> – <h6>),

paragraphs (<p>),

form labels (<label>)

etc.

What is the semantic meaning of each element?

Does your app have, or should it have, meaningful text in elements without a semantic meaning? Apart from plain paragraphs, probably not!

Testing Library's methods getByText(), queryByText() and findByText() search for all elements; they don't care about the elements' semantic meanings. Because most text should be in elements with specific semantic meanings, these methods should be used sparingly.

For example, don't look for a button using the getByText() method because the test could pass even if the button was implemented in a hacky way^[1]. Use the getByRole() method instead:

getByRole('button', { name: /submit/i })

This ensures that the button you are looking for is implemented properly and in an accessible way.

So: prefer more specific queries than the basic *ByText() methods. See list of recommended prioritizations of the different queries.

Footnotes

Think of a <div> with a click handler. Don't do it, kids – use a <button>. ↩

Assume vs presume in English

2021-02-25T12:00:00+03:00

Both are guesses. Assume is weaker (little or no evidence), presume is stronger (reasonable evidence). But how to remember which is which?

Definitions

Assume

Make a guess based on little or no evidence.

Presume

Make an informed guess based on reasonable evidence.

Source for the word definitions: Are 'Assume' and 'Presume' Synonyms? on Merriam-Webster.

Mnemonics

When you ass-ume something, it's just a guess that you have pulled from your ass.

When you pre-sume something, you have some pre-knowledge or pre-information to support your guess.

Source for the mnemonics: I pulled them from my ass!

Suppose?

I suppose I should add a third word to the comparison: suppose. Coming soon™.

How to quickly count (source) lines of code using `npx cloc`

2021-02-24T12:00:00+03:00

Run npx cloc [options] <files/dirs>. E.g. npx cloc src/ or npx cloc foo.js bar.css.

The cloc npm package by Kent C. Dodds is a wrapper around the cloc command line program by Al Danial.

Example from this repo:

$ npx cloc . \ --exclude-dir=_sample-content,_site,node_modules \ --not-match-f=package-lock.json npx: installed 1 in 1.085s 172 text files. 162 unique files. 49 files ignored. github.com/AlDanial/cloc v 1.90 T=0.22 s (707.6 files/s, 59215.9 lines/s) ------------------------------------------------------------------------------- Language files blank comment code ------------------------------------------------------------------------------- Markdown 100 1947 0 8129 JavaScript 27 114 110 848 Pug 18 78 123 789 CSS 1 34 31 328 TOML 1 31 2 127 JSON 2 0 0 67 YAML 1 2 2 12 XML 1 0 0 8 Bourne Shell 1 4 9 7 SVG 1 0 0 1 ------------------------------------------------------------------------------- SUM: 153 2210 277 10316 -------------------------------------------------------------------------------

Run npx cloc or npx cloc --help for more options and information.

Excluding your own mobile browser visits from Plausible Analytics

2021-02-17T12:00:00+03:00

Use a bookmarklet to stop Plausible Analytics from counting your own visits made using mobile devices.

Excluding desktop browsers

TL;DR: Run localStorage.plausible_ignore = true in the browser's console to start excluding your own visits.

More specific instructions in Plausible docs.

Excluding mobile browsers

We need to set the localStorage item mentioned in the previous section.

However, running code in a browser's console on an Android device is a hassle^[1]. Running code in iOS Safari's console is also a hassle^[2], and only possible if you have a Mac as far as I know.

What doesn't work

You could try pasting the following code to the browser's URL bar and then executing it by "visiting" the URL:

javascript:localStorage.plausible_ignore=true

It's the same code as the code that should be run on desktops, but prefixed with javascript:.

But it doesn't work on my iPad. I don't know about Android devices; you could try.

What does work: a bookmarklet

A bookmark with the location set to a javascript: URL is a bookmarklet. So, create a browser bookmark with the location set to the code from the previous section, and then run it. Here's how:

How to create a bookmarklet in iOS Safari. Then run it by "opening" the bookmark/bookmarklet.

How to create and run a bookmarklet in Android Chrome.

Note that Firefox for iOS doesn't support bookmarklets.

I confirmed that the bookmarklet worked by looking at my site's analytics; my own visits from my iPad were not counted anymore.

You can make the bookmarklet a bit friendlier by showing an alert box after setting the localStorage item:

javascript:localStorage.plausible_ignore=true&&alert('OK')

Then you don't have to wonder whether the bookmarklet was run or not.

Footnotes

If you want to run code in a browser's console on an Android device, see these articles for pointers:

Get Started with Remote Debugging Android Devices

Debugging Firefox for Android with WebIDE

↩

See How to Debug on iPhone Safari. ↩

How to get component's HTML without mounting in Mithril.js

2021-02-10T12:00:00+03:00

Create a DocumentFragment and render the component to it. Then there's no need to mount the component to the DOM.

const App = { view: () => m('.foo', 'bar'), } const fragment = new DocumentFragment() m.render(fragment, m(App)) console.log(fragment.firstChild) //=> Element object console.log(fragment.firstChild.outerHTML) //=> Just the HTML: `<div class="foo">bar</div>`

Test the code on flems.io

DocumentFragment on MDN

Coding SVG icons by hand

2021-02-05T12:00:00+03:00

Creating icons and simple figures by handcrafting SVG code is not as hard as it sounds.

Aleksandr Hovhannisyan has written a good primer on the topic called SVG Tutorial: How to Code SVG Icons by Hand.

Here's a quick Moomintroll that I created using my new and refreshed SVG skills:

Code:

<svg viewBox="0 0 24 24" style=" stroke: currentColor; stroke-linecap: round; stroke-linejoin: round; " >  <path d=" M 1 23 s 3 -35.5 7 -16 h 3 s 3 -15 5 3 a 7 6 0 1 1 -7 8 " fill="none" />  <circle cx="8" cy="12" r="2" fill="none" stroke-width="0.5" /> <circle cx="8.5" cy="11.5" r="0.5" />  <circle cx="13" cy="12" r="2" fill="none" stroke-width="0.5" /> <circle cx="13.5" cy="11.5" r="0.5" /> </svg>

I used smooth cubic Bézier curves (not covered in Aleksandr's article) which required some trial and error. But look how lovely he is!

Read Aleksandr's SVG Tutorial and start coding icons by hand!

How to debounce events in Mithril.js

2021-02-04T12:00:00+03:00

Disable auto-redraw with event.redraw = false and use a timeout.

Disabling auto-redraw is mentioned on the Auto-redraw system page in Mithril docs:

Mithril automatically redraws after DOM event handlers that are defined in a Mithril view. You can disable an auto-redraw for specific events by setting e.redraw to false.

Example using an oninput event:

const App = () => { let timeout let value = '25' function oninput(e) { e.redraw = false // Update state because we are using a controlled component value = e.currentTarget.value clearTimeout(timeout) timeout = setTimeout(() => { // Do something more here if needed // Plus probably redraw manually m.redraw() }, 1000) } return { view: () => [ m('input[type=text]', { oninput, value }), // Updating of this value is debounced m('p', Math.sqrt(value)), ], } }

Test the code on flems.io

Another example on flems.io

I'm not sure how much I like this solution because it feels like it's not proper debouncing. What if a global auto-redraw is triggered elsewhere? It might be a problem in some cases.

Can you think of a better way to debounce events in Mithril.js? Lemme know!

How to nest selectors in Mithril.js for extra brevity

2021-02-02T12:00:00+03:00

m.nest('ul > li', 'Item') can be achieved with reduceRight().

m.nest = (selector, ...args) => { const tags = selector.split('>') const innermost = m(tags.pop().trim(), ...args) return tags.reduceRight((child, tag) => m(tag.trim(), child), innermost) } // Usage: m.nest('ul.foo > li.bar > a[target=_blank]', { href }, 'Link') // The same as: m('ul.foo', m('li.bar', m('a[target=_blank]', { href }, 'Link'))) // Output in both cases: <ul class="foo"> <li class="bar"> <a target="_blank" href="...">Link</a> </li> </ul>

Test the code on flems.io

Benefits:

cleaner

clearer

cooler!

Source

Original code on GitHub, by fuzetsu (Daniel Loomer). Variables renamed on this page for clarity.

Earlier version on Mithril's Gitter room, also by fuzetsu. Here the array is looped twice (map() + reduceRight()), whereas in the newer version (on this page) there's only one loop (reduceRight()).

Lazy and greedy quantifiers in regular expressions

2021-01-29T12:00:00+03:00

Greedy quantifiers (the default, e.g. *) match as much as possible. Lazy quantifiers (e.g. *?) match as little as possible.

Greedy quantifiers

Greedy quantifiers keep looking until the condition is not satisfied. They match as much as possible.

Quantifiers are greedy by default.

Lazy quantifiers

Lazy quantifiers stop looking when the condition is satisfied. They match as little as possible.

Quantifiers can be made lazy by appending a question mark.

Table of quantifiers

Greedy quantifier Lazy quantifier Description

* *? zero or more

+ +? one or more

? ?? zero or one

{n} {n}? exactly n

{n,} {n,}? n or more

{n,m} {n,m}? between n and m

Example: getting the name of an HTML tag

const html = '<div>foo</div>' // Greedy html.match(/<.+>/)[0] //=> '<div>foo</div>' // Lazy html.match(/<.+?>/)[0] //=> '<div>'

As you can see, the greedy quantifier is too greedy in this case, whereas the lazy quantifier matches just enough but not too much. It's like smart laziness. Nice!

Alternative

Sometimes an alternative is to use a negated character class:

html.match(/<[^>]+>/)[0] //=> '<div>'

In this case the result is the same as when using the lazy quantifier, but the performance is better because "the negated character class can only match one way for a given input."

Formatting lists with JavaScript's `Intl.ListFormat`

2021-01-29T12:00:00+03:00

Pass an array of strings and get back a string with the array items separated by commas, except with the last comma replaced with the word "and" or "or." Like "item 1, item 2 and item 3."

Using locales

Intl.ListFormat enables "language-sensitive list formatting," so you can use different locales:

const list = ['Ham', 'Spam', 'Eggs'] /* en-US */ new Intl.ListFormat('en-US', { style: 'long', type: 'conjunction', }).format(list) //=> Ham, Spam, and Eggs new Intl.ListFormat('en-US', { style: 'short', type: 'disjunction', }).format(list) //=> Ham, Spam, or Eggs /* en-GB */ new Intl.ListFormat('en-GB', { style: 'long', type: 'conjunction', }).format(list) //=> Ham, Spam and Eggs new Intl.ListFormat('en-GB', { style: 'short', type: 'disjunction', }).format(list) //=> Ham, Spam or Eggs /* ja-JP */ new Intl.ListFormat('ja-JP', { style: 'long', type: 'conjunction', }).format(list) //=> Ham、Spam、Eggs new Intl.ListFormat('ja-JP', { style: 'short', type: 'disjunction', }).format(list) //=> Ham、Spam、またはEggs

Notice how the en-US locale uses Oxford commas and en-GB does not.

Formatting to parts

There's also a formatToParts() method that "returns an Array of objects representing the different components that can be used to format a list of values in a locale-aware fashion":

const list = ['Ham', 'Spam', 'Eggs'] new Intl.ListFormat('en-US', { style: 'long', type: 'disjunction', }).formatToParts(list) //=> [ // { type: 'element', value: 'Ham' }, // { type: 'literal', value: ', ' }, // { type: 'element', value: 'Spam' }, // { type: 'literal', value: ', or ' }, // Oxford comma 👀 // { type: 'element', value: 'Eggs' }, // ] new Intl.ListFormat('en-GB', { style: 'short', type: 'disjunction', }).formatToParts(list) //=> [ // { type: 'element', value: 'Ham' }, // { type: 'literal', value: ', ' }, // { type: 'element', value: 'Spam' }, // { type: 'literal', value: ' or ' }, // No Oxford comma // { type: 'element', value: 'Eggs' }, // ] new Intl.ListFormat('ja-JP', { style: 'short', type: 'disjunction', }).formatToParts(list) //=> [ // { type: 'element', value: 'Ham' }, // { type: 'literal', value: '、' }, // { type: 'element', value: 'Spam' }, // { type: 'literal', value: '、または' }, // { type: 'element', value: 'Eggs' }, // ]

I'm using formatToParts() on this site to format lists of tag links.

Browser support

Browser support of Intl.Listformat is nicely green, though Safari and iOS Safari have only recently (April 2021) added support for Intl.ListFormat.

Episerver + TinyMCE + React = uh oh!

2021-01-29T12:00:00+03:00

Thoughts on how to efficiently use React to render Episerver blocks embedded in TinyMCE fields.

This week at work I was pondering how to mount a React component to a <div> whose contents are defined using the dangerouslySetInnerHTML prop. Sounds ugly, and it is, but hear me out:

Episerver (.NET CMS) uses the TinyMCE editor for rich text editing and allows drag-and-dropping "blocks" (reusable pieces of content) into TinyMCE fields. By default, blocks are rendered as empty <div>s, like this (simplified example):

<p>Normal content</p> <div data-epi-block-id="123"></div> <p> More normal content. Block inside a paragraph: <div data-epi-block-id="456"></div> And more text. </p>

Now, I could:

render the HTML as-is,

retrieve the blocks' data using Ajax requests after the component has been mounted,

and then mount other React components to the <div>s.

But I don't want to, because that would be slow and incur an extra HTTP request per each block.

I'm thinking of including the blocks' data in the HTML before sending it to the front-end:

<p>Normal content</p> <div data-epi-block='{ "id": 123, "blockType": "FooBlock", "title": "Hello block", ... }'></div> <p> More normal content. Block inside a paragraph: <div data-epi-block='{ "id": 456, "blockType": "BarBlock", "title": "Another block", ... }'></div> And more text. </p>

Then I could use JSON.parse() to turn those JSON attributes into props objects. Mounting React components to those <div>s could be done as suggested in these Stack Overflow answers:

React: using React component inside of dangerouslySetInnerHTML

Render custom React component within HTML string from server

Like I said: ugly! And still just a theory. But necessary. We shall see later if this feasible.

How to pretty print JSON in JavaScript

2021-01-28T12:00:00+03:00

Run JSON.stringify(object, null, 2). Adjust the number for a different level of indentation.

Example:

const object = { foo: 'bar', ham: { spam: [10, 20], }, } JSON.stringify(object) // {"foo":"bar","ham":{"spam":[10,20]}} JSON.stringify(object, null, 2) // { // "foo": "bar", // "ham": { // "spam": [ // 10, // 20 // ] // } // }

Read more about JSON.stringify() on MDN

3 ways to convert a path into cumulative segments in JavaScript

2021-01-26T12:00:00+03:00

How to convert '/foo/bar/baz/' into an array of '/', '/foo/', '/foo/bar/', and '/foo/bar/baz/'. Example use case: building breadcrumb navigations.

The problem

Given a path like /foo/bar/baz/, we want to convert it into an array like this:

['/', '/foo/', '/foo/bar/', '/foo/bar/baz/']

Starting from the left, each array item grows until the next forward slash in the path. The path could be a directory path or an URL pathname.

I needed this when creating breadcrumb navigations for this website, so the paths were URL pathnames.

The 3 solutions

Split and reduce

This was my initial solution:

const getCumulativePathSegments = (path) => path .split('/') .filter(Boolean) // Drop empty strings caused by the splitting .reduce( (segments, segment) => { const previous = segments[segments.length - 1] segments.push(`${previous}${segment}/`) return segments }, ['/'] ) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/']

Simplistic, but works.

One caveat though: the last array item will have a trailing slash even if the input string doesn't have a trailing slash. This may or may not be a problem in your case.

If you want to omit the first array item (the slash):

set '/' as the default value of previous

change the initial array from ['/'] to [].

const getCumulativePathSegments = (path) => path .split('/') .filter(Boolean) .reduce( (segments, segment) => { - const previous = segments[segments.length - 1] + const previous = segments[segments.length - 1] || '/' segments.push(`${previous}${segment}/`) return segments }, - ['/'] + [] ) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) -//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] +//=> ['/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) -//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] +//=> ['/foo/', '/foo/bar/', '/foo/bar/baz/']

Test the split and reduce solution on flems.io

Map with a bit of curry

Who doesn't like curry? It makes chicken taste so much better. Currying also makes this cool solution possible:

const getCumulativePathSegments = (path) => { const cumulativePath = (acc) => (value) => (acc += `${value}/`) return path.split('/').filter(Boolean).map(cumulativePath('/')) } const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/foo/', '/foo/bar/', '/foo/bar/baz/']

Wait, what? Let's see how it works by adding console loggings:

const getCumulativePathSegments = (path) => { const cumulativePath = (acc) => (value) => { console.log({ acc, value }) return (acc += `${value}/`) } return path.split('/').filter(Boolean).map(cumulativePath('/')) } getCumulativePathSegments('/foo/bar/baz') //=> { acc: '/', value: 'foo' } // { acc: '/foo/', value: 'bar' } // { acc: '/foo/bar/', value: 'baz' }

The outer function's acc parameter acts as an accumulator, like when using an array reducer.

We are reassigning the parameter, which by the way violates the ESLint rule no-param-reassign. This is not a problem per se, but it's a potential source of confusion.

We could avoid reassigning the parameter by getting rid of the currying and creating an acc variable:

const getCumulativePathSegments = (path) => { - const cumulativePath = (acc) => (value) => { + let acc = '/' + const cumulativePath = (value) => { return (acc += `${value}/`) } return path.split('/').filter(Boolean).map(cumulativePath) }

There's one more oddity: the cumulativePath function's return statement contains an addition assignment. This violates the ESLint rule no-return-assign, which again is not a problem per se but is confusing.

Assignment operators have return values, meaning that these two are effectively equivalent:

const cumulativePath = (acc) => (value) => (acc += `${value}/`) const cumulativePath = (acc) => (value) => { acc += `${value}/` return acc }

With all the magic stripped out, here's the full function:

const getCumulativePathSegments = (path) => { let acc = '/' const cumulativePath = (value) => { acc += `${value}/` return acc } return path.split('/').filter(Boolean).map(cumulativePath) }

Or maybe in a clearer form:

const getCumulativePathSegments = (path) => { let acc = '/' return path .split('/') .filter(Boolean) .map((value) => { acc += `${value}/` return acc }) }

Now it's quite easy to see what's happening. Though it's not as cool anymore, is it?

This is also very similar to the split and reduce solution. Both solutions have the same caveat: the last array item will have a trailing slash even if the input string doesn't have a trailing slash.

Here's one way to have a slash as the first item of the resulting array:

const getCumulativePathSegments = (path) => { const cumulativePath = (acc) => (value) => (acc += `${value}/`) - return ( + return ['/'].concat( path.split('/').filter(Boolean).map(cumulativePath('/')) ) } const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) -//=> ['/foo/', '/foo/bar/', '/foo/bar/baz/'] +//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) -//=> ['/foo/', '/foo/bar/', '/foo/bar/baz/'] +//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/']

Test the map and curry solution on flems.io

All credit of the cleverness goes to Nina Scholz's post on Stack Overflow which I found via another post on Stack Overflow.

Regex to the rescue

If all you have is a hammer, everything looks like a nail. What I mean is that this problem looks like it's made to be solved with a regular expression!

Basically, when we encounter a forward slash or the end of the string ((\/|$)), we want to capture it plus everything before that (.*).

We could try something like this:

const getCumulativePathSegments = (path) => path.match(/.*(\/|$)/g) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/foo/bar/baz/', ''] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/foo/bar/baz', '']

Or a lazy quantifier:

const getCumulativePathSegments = (path) => path.match(/.*?(\/|$)/g) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/', 'foo/', 'bar/', 'baz/', ''] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/', 'foo/', 'bar/', 'baz', '']

Or a positive lookbehind assertion:

const getCumulativePathSegments = (path) => path.match(/(?<=.*)(\/|$)/g) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/', '/', '/', '/', ''] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/', '/', '/', '']

All three regexes fail miserably because we have to do overlapping matches, and this is not how they are done. Check out my previous blog post How to do overlapping matches with regular expressions for a walkthrough.

To do overlapping matches, we have to use matchAll() and a positive lookbehind assertion with a capturing group inside of it:

const getCumulativePathSegments = (path) => Array.from(path.matchAll(/(?<=(.*(\/|$)))/g)) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> [ // ["", "/", "/", index: 1, input: "/foo/bar/baz/", groups: undefined], // ["", "/foo/", "/", index: 5, input: "/foo/bar/baz/", groups: undefined], // ["", "/foo/bar/", "/", index: 9, input: "/foo/bar/baz/", groups: undefined], // ["", "/foo/bar/baz/", "/", index: 13, input: "/foo/bar/baz/", groups: undefined], // ] getCumulativePathSegments(pathWithoutTrailingSlash) //=> [ // ["", "/", "/", index: 1, input: "/foo/bar/baz", groups: undefined], // ["", "/foo/", "/", index: 5, input: "/foo/bar/baz", groups: undefined], // ["", "/foo/bar/", "/", index: 9, input: "/foo/bar/baz", groups: undefined], // ["", "/foo/bar/baz", "", index: 12, input: "/foo/bar/baz", groups: undefined], // ]

Looks good. Let's get only the second array items, i.e. the matches from the capturing group inside the lookbehind assertion:

const getCumulativePathSegments = (path) => Array.from( path.matchAll(/(?<=(.*(\/|$)))/g), (match) => match[1] ) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) //=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) //=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz']

Egg-cellent! As you can see, whether the last item of the resulting array has a trailing slash depends on whether the input string has a trailing slash. This is better than the other two solutions; they always include a trailing slash in the last item of the resulting array.

If you want to omit the first array item (the slash), you need to only change .* to .+:

const getCumulativePathSegments = (path) => - Array.from(path.matchAll(/(?<=(.*(\/|$)))/g), (match) => match[1]) + Array.from(path.matchAll(/(?<=(.+(\/|$)))/g), (match) => match[1]) const pathWithTrailingSlash = '/foo/bar/baz/' const pathWithoutTrailingSlash = '/foo/bar/baz' getCumulativePathSegments(pathWithTrailingSlash) -//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz/'] +//=> ['/foo/', '/foo/bar/', '/foo/bar/baz/'] getCumulativePathSegments(pathWithoutTrailingSlash) -//=> ['/', '/foo/', '/foo/bar/', '/foo/bar/baz'] +//=> ['/foo/', '/foo/bar/', '/foo/bar/baz']

Test the regex solution on flems.io

Which solution is the best?

The split and reduce solution might be the most straightforward solution. It's not as elegant as the other two, but at least it's readable.

The map and curry solution is fancy – actually, it's so fancy that I still find it quite confusing. It seems to work, but personally I wouldn't use it.

The regex solution is the shortest solution, but requires the reader to know some regex trickery. It's also the only solution which respects the input string's trailing slash. You could modify the other two solutions to do that too, but they would become more complex and less readable.

I'm a rebel, so I'm using the regex solution on this website. 🤘

Bonus: Using for breadcrumb navigations

Here's a quick example using React how the getCumulativePathSegments() function could be used for generating breadcrumb navigations:

const pageNames = { '/': 'Home', '/foo/': 'Foo', '/foo/bar/': 'BAR', '/foo/bar/baz/': 'Bäz', } function Breadcrumb() { const pageUrl = '/foo/bar/baz/' // or e.g. `window.location.pathname` const items = getCumulativePathSegments(pageUrl).map((segment) => ({ href: segment, text: pageNames[segment], })) return ( <nav aria-label="Breadcrumb"> <ul> {items.map((item) => ( <li key={item.href}> <a href={item.href}>{item.text}</a> </li> ))} </ul> </nav> ) }

Result:

<nav aria-label="Breadcrumb"> <ul> <li><a href="/">Home</a></li> <li><a href="/foo/">Foo</a></li> <li><a href="/foo/bar/">BAR</a></li> <li><a href="/foo/bar/baz/">Bäz</a></li> </ul> </nav>

Two types of skills and two types of learning

2021-01-22T12:00:00+03:00

Expiring skills vs permanent skills and just-in-time learning vs just-in-case learning.

TL;DR of Mike Crittenden's blog post Learning a technology you don't need right now is a waste of time:

Two types of skills:

Expiring skills: hard skills, e.g. TypeScript, React, Kubernetes

Permanent skills: soft skills, e.g. attitude, discipline, charisma

Two types of learning:

Just-in-time: learn when you need the skill/knowledge

Just-in-case: learn in case you need the skill/knowledge in the future

Hard skills expire, so learning them just-in-case is a waste of time

Soft skills are permanent and compound over time, so learning them just-in-case is wise

This is why I'm not eager to take courses if they are about hard/expiring skills that I know I won't need in the near future.

Read the full blog post by Mike Crittenden

`new Date()` and `Date.parse()` are bad at parsing dates

2021-01-22T12:00:00+03:00

Use them only with certain date time formats, and use a library for parsing fancy formats.

They used to be discouraged

From Date() constructor on MDN:

Parsing of date strings with the Date constructor (and Date.parse(), which works the same way) is strongly discouraged due to browser differences and inconsistencies.

Update: the MDN page was updated in June 2022. Now the page doesn't say anymore that the Date() constructor and Date.parse() are "strongly discouraged." From the linked pull request:

I think parsing ISO date strings is useful enough to not be completely discouraged.

Fancy formats are poorly supported

For example, the string "2021-01-10 12:47:29 UTC" is parsed correctly on Chrome, but results in "Invalid Date" on Firefox and iOS Safari (as of Jan 22, 2021):

new Date('2021-01-10 12:47:29 UTC') //=> Chrome: Sun Jan 10 2021 14:47:29 GMT+0200 (Eastern European Standard Time) // Firefox: Invalid Date // iOS Safari: Invalid Date

Certain formats are well-supported

Compare with a proper format that works in all three browsers:

new Date('2021-01-10T12:47:29.000Z') // Z = UTC //=> Chrome: Sun Jan 10 2021 14:47:29 GMT+0200 (Eastern European Standard Time) // Firefox: Sun Jan 10 2021 14:47:29 GMT+0200 (Eastern European Standard Time) // iOS Safari: Sun Jan 10 2021 14:47:29 GMT+0200 (EET)

For proper formats, see Date time string format on MDN.

Moment.js vs others

If you have to parse fancy formats, consider using a library for that.

Probably don't choose Moment.js for new projects because Moment.js is in maintenance mode.

Consider Moment.js alternatives instead. I have been satisfied with date-fns.

"Illegal invocation" errors in JavaScript

2021-01-22T12:00:00+03:00

The error is thrown when calling a function whose this keyword isn't referring to the object where it originally did, i.e. when the "context" of the function is lost.

Example problems

I encountered the "illegal invocation" error when calling the destructured abort method of an AbortController:

const abortController = new AbortController() const { abort } = abortController abort() //=> TypeError: Illegal invocation

Another case: trying to implement jQuery-like shorthands for document.querySelector and document.querySelectorAll:

const $ = document.querySelector const $$ = document.querySelectorAll $('#foo') //=> TypeError: Illegal invocation $$('.bar') //=> TypeError: Illegal invocation

(By the way: most, if not all, modern browsers have the $ and $$ shorthands built into the browser's JS console.)

Description of the error

"Invocation" is the act invoking a function, which is the same as calling a function. Invoke = call.

An "illegal invocation" error is thrown when calling a function whose this keyword doesn't refer to the object where it originally did. In other words, the original "context" of the function is lost.

Chromium browsers call this error an "illegal invocation."

Firefox produces more descriptive error messages:

TypeError: 'abort' called on an object that does not implement interface AbortController.

TypeError: 'querySelector' called on an object that does not implement interface Document.

So does Safari:

TypeError: Can only call AbortController.abort on instances of AbortController

TypeError: Can only call Document.querySelector on instances of Document

Node.js (v16) produces clearly the best error messages, e.g.:

TypeError [ERR_INVALID_THIS]: Value of "this" must be of type AbortController

Deno uses V8 – the same JS engine as Chromium browsers do – so Deno also calls the error an "illegal invocation."

Manual implementation of an "illegal invocation" check

For demonstration purposes:

   const foo = { bar: function () { console.log('Calling foo.bar; `this` refers to', this) if (this !== foo) { throw new TypeError('Illegal invocation 🛑') } console.log('Successfully called foo.bar ✅') }, } foo.bar() //=> Calling foo.bar; `this` refers to foo //=> Successfully called foo.bar ✅ const { bar } = foo bar() //=> Calling foo.bar; `this` refers to window //=> TypeError: Illegal invocation 🛑 const bar2 = foo.bar bar2() //=> Calling foo.bar; `this` refers to window //=> TypeError: Illegal invocation 🛑

Notes:

In real code, you should use better error messages. "Illegal invocation" is not clear.

In strict mode, this would be undefined instead of window in the error cases.

Why does the this keyword change?

Because the this keyword in JavaScript is confusing!

The gist is in the difference between method invocations and function invocations.

Method invocations

A method is a function stored as a property of an object. When invoking (i.e. calling) a method using the dot notation or square bracket notation, the this keyword is bound to the object:

const foo = { bar() { console.log(this) }, } const method = 'bar' // Method invocations: foo.bar() //=> foo foo['bar']() //=> foo foo[method]() //=> foo

Function invocations

When invoking (i.e. calling) a function that is not the property of an object, the this keyword is:

bound to the global object (window) in sloppy mode.

undefined in strict mode.

In either mode, the original context is lost because the this keyword doesn't refer to the object where it originally did:

const { bar } = foo const bar2 = foo.bar const bar3 = foo['bar'] // Function invocations: bar() //=> window (in sloppy mode) / undefined (in strict mode) bar2() //=> window (in sloppy mode) / undefined (in strict mode) bar3() //=> window (in sloppy mode) / undefined (in strict mode)

As to why the context is lost – let's quote Douglas Crockford's book JavaScript: The Good Parts (1st ed., p. 28; emphasis added):

When a function is not the property of an object, then it is invoked as a function:

var sum = add(3, 4) // sum is 7

When a function is invoked with this pattern, this is bound to the global object. This was a mistake in the design of the language.

Sidetrack: arrow functions

The quote from the book continues (pp. 28–29; text split into paragraphs and code block slightly edited):

Had the language been designed correctly, when the inner function is invoked, this would still be bound to the this variable of the outer function.

A consequence of this error is that a method cannot employ an inner function to help it do its work because the inner function does not share the method's access to the object as its this is bound to the wrong value.

Fortunately, there is an easy workaround. If the method defines a variable and assigns it the value of this, the inner function will have access to this through that variable. By convention, the name of that variable is that:

var myObject = { value: 3, } // Augment myObject with a double method myObject.double = function () { var that = this // Workaround var helper = function () { that.value = add(that.value, that.value) } helper() // Invoke helper as a function } myObject.double() // Invoke double as a method console.log(myObject.value) //=> 6

Nowadays you can alternatively use arrow functions:

myObject.double = function () { const helper = () => { this.value = add(this.value, this.value) } helper() // Invoke helper as a function } myObject.double() // Invoke double as a method console.log(myObject.value) //=> 6

Arrow functions increase the complexity around the this keyword; or reduce complexity, depending on the viewpoint.

Anyhow, the this keyword in JavaScript is confusing. I personally try to avoid it. It has many potential pitfalls, and often there are better alternatives.

Three ways to fix the error

Here's the original, problematic example code:

const abortController = new AbortController() const { abort } = abortController const $ = document.querySelector const $$ = document.querySelectorAll

The gist of the problem is that calling abort, $ or $$ is a function invocation, not a method invocation, so the context is lost.

Create a function that calls a method

As we learned above, with a method invocation (as opposed to a function invocation), the this keyword is bound to the object.

So, create an abort function that calls the abortController.abort method:

const abortController = new AbortController() const abort = () => abortController.abort() abort() // OK!

Calling abort is a function invocation, but abort in turn calls abortController.abort using method invocation, so the context is not lost.

Similarly for $ and $$:

const $ = (selectors) => document.querySelector(selectors) const $$ = (selectors) => document.querySelectorAll(selectors) $('#foo') // OK! $$('.bar') // OK!

(By the way: notice how the function parameters are in the plural form: selectors instead of selector. That's because document.querySelector and document.querySelectorAll accept a comma-separated list of CSS selectors.)

Use bind() to change the this keyword

A more convoluted solution is to use Function.prototype.bind() to set the this keyword to point to the correct object:

const abortController = new AbortController() const abort = abortController.abort.bind(abortController) const $ = document.querySelector.bind(document) const $$ = document.querySelectorAll.bind(document) abort() // OK! $('#foo') // OK! $$('.bar') // OK!

There's also Function.prototype.apply() and Function.prototype.call(), but they are also convoluted because they deal with the this keyword.

I recommend the previous solution which doesn't deal with the this parameter: Create a function that calls a method.

Export the whole object

(Maybe an obvious solution, but mentioning it anyway.)

In the AbortController case, I originally destructured the abort method because I wanted to export only that method, not the whole AbortController.

If you are fine with exporting the whole AbortController, calling its abort method directly is fine too (because it'll be a method invocation):

export const abortController = new AbortController() // In another file: import { abortController } from '...' abortController.abort() // OK!

This solution doesn't apply to the $ and $$ functions because document is anyway available in all modules.

Sources / Further resources

I learned about "illegal invocation" errors via these Stack Overflow questions:

"Uncaught TypeError: Illegal invocation" in Chrome

Why are certain function calls termed "illegal invocations" in JavaScript?

Uncaught TypeError: Illegal invocation in JavaScript

I learned about the differences between method invocations and function invocations from Douglas Crockford's book JavaScript: The Good Parts. Chapter 4, "Functions," has more details, and also describes two other invocation patterns in JavaScript:

the constructor invocation pattern

the apply invocation pattern.

Lastly, see also my theoretical musings about preventing "illegal invocation" errors in TypeScript.

Dynamic tag names in Pug

2021-01-22T12:00:00+03:00

Use string interpolation at the beginning of a line, e.g. #{myVariable}.

Example:

- const tag = 'article' #{tag} #{tag}.foo #{tag}(class="foo") #{tag}.foo(class="bar") #{tag}(class="foo").bar // Output: <article></article> <article class="foo"></article> <article class="foo"></article> <article class="foo bar"></article> <article class="foo bar"></article>

Works even inside tag interpolation:

- const tag = 'em' p Bacon #[#{tag}.foo ipsum]! // Output: <p>Bacon <em class="foo">ipsum</em>!</p>

Dynamic tag names allow you to use fancy, probably invalid tag names. Like these:

#{':foo'} bar #{'^'} baz // Output: <:foo>bar</:foo> <^>baz</^> // Compare with: :foo bar // Error: unknown filter ":foo" ^ baz // Error: unexpected text "^ baz"

Not sure why you would want that though!

Read more about interpolations in Pug

Mnemonic for `array.shift()` vs `array.unshift()` in JavaScript

2021-01-21T12:00:00+03:00

shift() removes the first array item, and unshift() prepends items to the array. But how to remember which is which?

First, you need to remember pop() vs push(). If you don't, try these mnemonics:

pop() removes the last array item by popping it like a bottle cap.

push() appends items to the array by... eh, pushing stuff to it?

I think they are quite intuitive.

All right, now the mnemonic for shift() vs unshift() (and incidentally also for pop() vs push()):

The method with the shorter name removes an item.

So, pop() and push():

pop() has a shorter name than push().

pop() removes the last array item.

push() appends items to the array.

Similarly, shift() vs unshift():

shift() has a shorter name than unshift().

shift() removes the first array item.

unshift() prepends items to the array.

Using non-default locales with `toLocaleString()` in Node.js

2021-01-15T12:00:00+03:00

With Node.js 13+, it should just work. With earlier Node.js versions, you need to install and use the full-icu package.

The problem

Using Node.js version 12 or earlier, Date.prototype.toLocaleString() and Number.prototype.toLocaleString() don't always produce correct results, at least with non-English (or non-default) locales. For example:

const date = new Date('2021-11-22') console.log(date.toLocaleString('en')) //=> Actual/expected: 11/22/2021, 2:00:00 AM (🆗) console.log(date.toLocaleString('fi')) //=> Actual: 2021-11-22 2:00:00 (❗) //=> Expected: 22.11.2021 klo 2.00.00 const number = 1234.56 console.log(number.toLocaleString('en', { style: 'currency', currency: 'USD' })) //=> Actual/expected: $1,234.56 (🆗) console.log(number.toLocaleString('fi', { style: 'currency', currency: 'USD' })) //=> Actual: US$ 1,234.56 (❗) //=> Expected: 1 234,56 $

The solution

The results depend on the ICU data (= localization data) used by Node.js. From site.icu-project.org:

ICU is a mature, widely used set of [...] libraries providing Unicode and Globalization support for software applications. ICU is widely portable and gives applications the same results on all platforms [...].

Node.js 13+

Starting from version 13.0.0, Node.js comes with full ICU support by default, so toLocaleString() should produce correct results.

From version 13.0.0 changelog:

Node.js releases are now built with default full-icu support. This means that all locales supported by ICU are now included and Intl-related APIs may return different values than before (Richard Lau) #29887.

Issue #19214 has also relevant discussion about this.

Note: version 13 is not an LTS (long-time support) version. Even-numbered versions – 14, 16, 18 and so on – are LTS versions and thus a better choice. See Node.js Releases.

Node.js 12 and earlier

You need to install and enable full ICU data manually:

Run npm install full-icu cross-env to install the following packages:

full-icu: the full ICU data

cross-env: needed by Windows users to set the environment variable in the next step.

Update the scripts section of package.json to set the environment variable NODE_ICU_DATA. For example:

{ "scripts": { // Before "start": "react-scripts start", "test": "react-scripts test", // After "start": "react-scripts start", "test": "cross-env NODE_ICU_DATA=node_modules/full-icu react-scripts test" } }

Now when you run npm test, Node.js will load the full ICU data from node_modules/full-icu, and toLocaleString() should produce correct results.

In the example above, you could also modify the start script, but it might be unnecessary; depends on what the script does. In this case the script opens a browser, so modifying the script would be unnecessary.

Further resources

The same info can be found in my Stack Overflow answer.

My new microphone: RØDE Procaster

2021-01-15T12:00:00+03:00

Much better than a Jabra headset, but also much pricier. Why a dynamic XLR microphone instead of a condenser USB microphone? Read on to find out.

Huge upgrade from a Jabra headset

I have previously used a Jabra Evolve 65 headset. My new RØDE Procaster microphone has so much better audio quality.

I always thought that the Jabra has quite good audio quality – and it kind of has; everything is relative.

But then I compared my voice recorded with the Jabra to my brother's voice recorded with a decent condenser microphone. The difference in audio quality was immense. No way I'm going back to the Jabra (unless I need portability).

I have worked mostly remotely for the past few years and plan to continue working remotely, so having high quality audio equipment benefits my colleagues as well.

Another reason to buy a decent microphone was that my brother and I were planning to start a podcast. (Nowadays our Finnish podcast Koodikrapula is up and running.)

And finally, high-quality audio makes you sound smarter! (The linked article was published a few months after I had already bought the microphone, so it didn't affect my purchasing decision. Cool nonetheless. 🤙)

What did it cost?

Everything. :thanos:

No but seriously, these are the prices I paid in Finland in January 2021:

Product Price

RØDE Procaster (microphone) 179€

Focusrite Scarlett Solo 3rd Gen (USB audio interface) 110€

RØDE PSA1 (studio arm) 70€

RØDE PSM1 (shock mount) 40€

Cordial Silver Line (2.5m XLR–XLR cable) 21€

RØDE WS2 (pop filter / wind shield) 16€

Total price: 436€ 🙈

In comparison, the Jabra Evolve 65 headset costs about 130€.

I got the RØDE PSA1 studio arm on sale (70€); normally it costs ~90€.

Different kinds of microphones

When deciding what microphone to buy, I watched some videos.

XLR vs USB

From Podcastage's video XLR vs USB Microphones, Which Should You Buy?, I learned that:

USB microphones are easier to use.

XLR microphones offer better audio quality and more choices, but they require an USB audio interface.

Thus, I opted for an XLR microphone. There's no such thing as overkill when it comes to audio stuff, right?

Dynamic vs condenser

From Podcastage's video Dynamic vs Condenser Microphones, What's the Difference?, I learned that:

Condenser microphones are more sensitive so they pick up more background noises, like the sound of the keyboard, air conditioner etc.

Dynamic microphones are better at suppressing background noises at the cost of reduced audio quality.

In my case, I'm sure no one (including me) would notice the difference in audio quality between a dynamic and a condenser microphone. But background noises are always annoying, so I opted for a dynamic microphone.

Locality of Behavior / Co-location

2021-01-15T12:00:00+03:00

These two similar principles state that the behavior of code should be obvious on inspection and that code should be located where it's relevant.

Locality of Behavior

The Locality of Behavior principle states that the behavior of code should be obvious on inspection. Or more formally:

The behavior of a unit of code should be as obvious as possible by looking only at that unit of code.

An example from the linked article:

Consider two different implementations of an AJAX request in HTML, the first in htmx:

<button hx-get="/clicked">Click Me</button>

and the second in jQuery:

$('#d1').on('click', function () { $.ajax({ /* AJAX options... */ }) })

<button id="d1">Click Me</button>

In the former, the behavior of the button element is obvious on inspection, satisfying the Locality of Behavior principle.

In the latter, the behavior of the button element is spread out amongst multiple files. It is difficult to know exactly what the button does without a total knowledge of the code base. This "spooky action at a distance" is a source of maintenance issues and stands in the way of developers understanding of the code base.

The htmx example demonstrates good Locality of Behavior, while the jQuery example has poor Locality of Behavior.

Read more about the Locality of Behavior principle from htmx's docs.

Co-location

The Co-location principle states that code should be located where it's relevant. Or more formally:

Place code as close to where it's relevant as possible.

And in other words:

Things that change together should be located as close as reasonable.

Some examples from the linked article:

Code comments are usually "co-located" with the code they are explaining instead of being somewhere else entirely, e.g. in a separate docs/ folder. (This is a contrived example, but demonstrates the importance of the Co-location principle well.)

React/Vue/etc. components often contain both the view logic and the view template.

If unit test files are located next to the source files, it's very easy to locate the unit tests for a source file. For example, Button.js and Button.test.js in the same folder are co-located, but src/.../Button.js and tests/.../Button.test.js are not.

Read more about the Co-location principle from Kent C. Dodds's blog.

Example: Tailwind 🥰

The Locality of Behavior and Co-location principles partly explain why I feel productive and happy when using Tailwind.

For example, when using Tailwind with React, a single component file can contain everything relevant about the component^[1]:

HTML structure (JSX)

event listeners (onClick etc.)

logic and state (hooks etc.)

styles (Tailwind classes amongst the JSX).

With Tailwind, I can stay in the component's JS file. Without Tailwind, I would need to jump between the component's JS and CSS files.

To be fair, CSS-in-JS could offer similar benefits as Tailwind.

CSS modules would be worse (separate CSS file), but at least they would be imported from components' JS files, so it would be easy to locate a component's styles.

Global CSS files would be the worst option from the viewpoint of the Locality of Behavior and Co-location principles.

Footnotes

I have heard that Vue provides a similarly pleasant experience with its single-file components. ↩

Calculating week numbers in JS is surprisingly complex

2021-01-15T12:00:00+03:00

JavaScript doesn't provide a native way to get the week number of a date. Just use a library instead.

It might be complex because week numbering itself is complicated.

In my case, I ended up using the getWeek() function from date-fns. This piece from its implementation on GitHub is amusing:

// Round the number of days to the nearest integer // because the number of milliseconds in a week is not constant // (e.g. it's different in the week of the daylight saving time clock shift) return Math.round(diff / MILLISECONDS_IN_WEEK) + 1

I'm glad I haven't had to deal with date stuff much in the past.

How to do overlapping matches with regular expressions

2021-01-13T12:00:00+03:00

E.g. how to capture overlapping pairs of letters from the string 'abcde', i.e. 'ab', 'bc', 'cd' and 'de'. Spoiler: with lookahead and lookbehind assertions.

Consuming characters vs looking ahead/behind

We could try matching two letters at a time, like this:

'abcde'.match(/[a-z][a-z]/g) //=> ['ab', 'cd']

But it doesn't work. Why not?

Turns out that when the regular expression matches the first two letters (a and b), it consumes them, meaning that the next match will be done against the rest of the input string, i.e. 'cde'. That's why the above regular expression doesn't capture overlapping pairs of letters.

This is what lookahead and lookbehind assertions are for: they look ahead or behind to assert (check) that the input contains some characters, but they don't consume those characters.

We have two options:

const lookahead = /(?=[a-z][a-z])/g const lookbehind = /(?<=[a-z][a-z])/g

The first regular expression above has a lookahead assertion. When it's used to loop through the input string, it asserts that the current position is followed by two letters. It doesn't consume them because they are inside the lookahead assertion. In fact, the regular expression doesn't consume any characters because all matchable characters are inside the lookahead assertion.

The second regular expression above has a lookbehind assertion. It works similarly, but it asserts that the current character is preceded by two letters.

Here's a table of the lookahead/lookbehind assertion results using the two regular expressions above for the string 'abcde':

Index Position (|) Match Lookahead Lookbehind

0 |abcde nothing ab nothing

1 a|bcde nothing bc nothing

2 ab|cde nothing cd ab

3 abc|de nothing de bc

4 abcd|e nothing nothing cd

5 abcde| nothing nothing de

How does this help us? It does if we use capturing groups.

Capturing groups inside lookahead/lookbehind assertions

We now know how to loop through the input string and look ahead/behind to find all (overlapping) pairs of letters. We can capture the pairs by using capturing groups inside the lookahead/lookbehind assertions:

// Before const lookahead = /(?=[a-z][a-z])/g const lookbehind = /(?<=[a-z][a-z])/g // After const lookahead = /(?=([a-z][a-z]))/g // ^ ^ const lookbehind = /(?<=([a-z][a-z]))/g // ^ ^

One caveat, though: String.prototype.match() ignores capturing groups when using the global flag (g). So these don't work:

'abcde'.match(/(?=([a-z][a-z]))/g) //=> ['', '', '', ''] 'abcde'.match(/(?<=([a-z][a-z]))/g) //=> ['', '', '', '']

They don't work because:

all matchable characters are inside the lookahead/lookbehind assertions, so the regular expressions capture nothing

match() ignores capturing groups when using the global flag (g).

Luckily for us, String.prototype.matchAll() does not ignore capturing groups:

'abcde'.matchAll(/(?=([a-z][a-z]))/g) //=> RegExpStringIterator {} 'abcde'.matchAll(/(?<=([a-z][a-z]))/g) //=> RegExpStringIterator {}

But oh, matchAll() returns an iterator. Let's convert the iterators to arrays:

Array.from('abcde'.matchAll(/(?=([a-z][a-z]))/g)) //=> [ // ["", "ab", index: 0, input: "abcde", groups: undefined], // ["", "bc", index: 1, input: "abcde", groups: undefined], // ["", "cd", index: 2, input: "abcde", groups: undefined], // ["", "de", index: 3, input: "abcde", groups: undefined], // ] Array.from('abcde'.matchAll(/(?<=([a-z][a-z]))/g)) //=> [ // ["", "ab", index: 2, input: "abcde", groups: undefined], // ["", "bc", index: 3, input: "abcde", groups: undefined], // ["", "cd", index: 4, input: "abcde", groups: undefined], // ["", "de", index: 5, input: "abcde", groups: undefined], // ]

We can see that each array item is an array with additional properties. The first items are the matches – they are empty strings because all matchable characters are inside the lookahead/lookbehind assertions. The second items are the matches from the capturing groups.

Because we are using Array.from(), we can easily get only the second array items:

Array.from('abcde'.matchAll(/(?=([a-z][a-z]))/g), (match) => match[1]) //=> ['ab', 'bc', 'cd', 'de'] Array.from('abcde'.matchAll(/(?<=([a-z][a-z]))/g), (match) => match[1]) //=> ['ab', 'bc', 'cd', 'de']

And that's how we can do overlapping matches with regular expressions. Or that's the gist of it; depending on your needs, you can also:

use negative lookahead/lookbehind assertions

put stuff outside the lookahead/lookbehind assertion.

Practical applications

Using overlapping regex matches is one way to convert a directory path or URL pathname into cumulative segments; e.g. converting '/foo/bar/baz/' into an array of '/', '/foo/', '/foo/bar/' and '/foo/bar/baz/'.

Anthony Labarre emailed me about another interesting use case:

I used this as an exercise in bash scripting for Chinese students, where I had them extract Chinese "proverbs" from books. A faster solution than searching the book for each proverb in a list consists in generating all possibly overlapping subsequences of 4, 5, … characters from the book, and then using comm to identify which subsequences match known proverbs from our list. On my machine, this brought the running time from about 15 seconds to about 1 second.

For completeness, here's how I did it in bash [...]. (Except \w does not work for Chinese characters, you need to substitute it with \p{Han} and add the -u flag to pcregrep.)

Have you found overlapping regex matches useful in other scenarios? Let me know! (Email on the front page.)

Browser support

As of March 2022:

Lookahead assertions are supported by all browsers because they "are part of JavaScript's original regular expression support."

Lookbehind assertions are supported by all modern browsers except Safari and iOS Safari.

String.prototype.matchAll() is supported by all modern browsers.

Further resources

Wiktor Stribiżew's answer to How can I match overlapping strings with regex? on Stack Overflow shows how to do overlapping matches by using RegExp.prototype.exec() and modifying the regular expression instance's lastIndex property. This is useful if you can't use matchAll(), which isn't supported by Internet Explorer.

Wiktor's answer also shows the solution that I have presented here; I actually learned it from Wiktor's answer (thanks!). This blog post is mainly me teaching myself the topic by teaching it to you.

`fn.apply()` vs `fn.call()` in JavaScript + better alternative

2021-01-11T12:00:00+03:00

Mnemonic: "a" (apply()) for an array, "c" (call()) for commas. But Reflect.apply() is better.

fn.apply() vs fn.call()

The apply() method takes arguments as an array, and the call() method takes multiple arguments:

function foo() {} const thisArg = {} const args = [1, 2, 3] foo.apply(thisArg, args) foo.apply(thisArg, [1, 2, 3]) foo.call(thisArg, ...args) foo.call(thisArg, 1, 2, 3)

Mnemonic:

a (apply()) for an array

c (call()) for commas.

Source for the mnemonic: What is the difference between call and apply? on Stack Overflow.

The better alternative

Reflect.apply() is better. Like fn.apply(), it takes arguments as an array:

function foo() {} const thisArg = {} const args = [1, 2, 3] Reflect.apply(foo, thisArg, args) Reflect.apply(foo, thisArg, [1, 2, 3])

It's "arguably less verbose and easier to understand" than fn.apply(). "In addition, when you accept arbitrary methods, it's not safe to assume .apply() exists or is not overridden."

Source: Prefer Reflect.apply() over Function#apply() ESLint rule from eslint-plugin-unicorn.

A note about verbosity

This is not verbose:

foo.apply(thisArg, [1, 2, 3])

But it's not safe either as stated above.

This is safe but also verbose:

Function.prototype.apply.call(foo, thisArg, [1, 2, 3])

Now it's easy to see why Reflect.apply() is "arguably less verbose and easier to understand":

Reflect.apply(foo, thisArg, [1, 2, 3])

Further resources

Test the code on flems.io

Recent (December 2020) Reddit discussion about eslint-plugin-unicorn

When to use the `xmlns` and `version` SVG attributes

2021-01-08T12:00:00+03:00

The xmlns attribute is required for SVG files but optional for inlined SVGs. The version attribute is always optional.

The xmlns and xmlns:xlink attributes

The xmlns and xmlns:xlink attributes are optional for inlined SVGs in HTML.

The xmlns attribute is required for SVG files.

The xmlns attribute is required for SVGs in CSS, e.g.:

background-image: url( 'data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg">...</svg>' );

The xmlns:xlink attribute is required for SVG files that contain xlink: attributes. Similarly for SVGs in CSS.

The version attribute

The version attribute is ignored and thus always optional. Plus it's deprecated since SVG 2.

Source

Are SVG parameters such as 'xmlns' and 'version' needed? on Stack Overflow

Uncontrolled form inputs in React

2021-01-08T12:00:00+03:00

If you need form input values only at the time of form submission, uncontrolled inputs can be nice to work with.

From Uncontrolled Components on React docs:

In most cases, we recommend using controlled components to implement forms. In a controlled component, form data is handled by a React component. The alternative is uncontrolled components, where form data is handled by the DOM itself.

I previously thought that using uncontrolled inputs in React is very rare or even a bad practice.

But then I found this tweet by Josh W. Comeau:

🌠 I've been really enjoying using uncontrolled form inputs recently. Set an initial value with React, and then collect the values using standard JS when the form is submitted.

No fussing with state required 🔥

CodeSandbox demo

function EditUser({ user }) { function saveUser(ev) { ev.preventDefault() const elementsArray = [...ev.target.elements] const formData = elementsArray.reduce((acc, elem) => { if (elem.id) acc[elem.id] = elem.value return acc }, {}) // Do a `fetch` or whatever with `formData`! // Has the shape: `{ name: string, email: string }` } return ( <form onSubmit={saveUser}> <label> Name <input type="text" id="name" defaultValue={user.name} /> </label> <button>Save</button> </form> ) }

It makes sense to use uncontrolled form inputs if the input values are needed only at the time of form submission. I'd imagine the performance must be better as well.

From the replies on Twitter: creating a FormData object simplifies the saveUser function even more:

function saveUser(ev) { ev.preventDefault() - const elementsArray = [...ev.target.elements] - const formData = elementsArray.reduce((acc, elem) => { - if (elem.id) acc[elem.id] = elem.value - return acc - }, {}) + const formData = new FormData(ev.target) // Do a `fetch` or whatever with `formData`! }

Note that form inputs need to have a name prop/attribute or they won't end up in the formData object (if using new FormData(ev.target)).

Usage of the formData object:

             function saveUser(ev) { ev.preventDefault() const formData = new FormData(ev.target) // `Content-Type` will implicitly be `multipart/form-data` fetch(url, { body: formData, method: 'POST', }) // or const pojo = Object.fromEntries(formData) const json = JSON.stringify(pojo) fetch(url, { body: json, headers: { 'Content-Type': 'application/json' }, method: 'POST', }) }

Demo on flems.io

My notes on "Tail Call Optimization: The Musical!"

2021-01-08T12:00:00+03:00

My quick notes on a funny but informative video (11:27) that explains how tail call optimization (TCO) works. Bonus: does JS support TCO? Spoiler: yes but no.

The video

Watch the video on YouTube

(Note to self: embed the video using Lite YouTube Embed.)

My notes

Tail call = a function call at the very end of a function, i.e. the function call has to be the very last thing that the function does.

Tail call optimization (TCO) = if the language (and engine) supports TCO, tail calls are removed from the call stack because they are kind of unnecessarily there (because of the tail position).

Pro: You don't get errors saying "Maximum call stack size exceeded" (Chrome) or "Too much recursion" (Firefox) or "Stack overflow" (some other contexts).

Con: Stack traces have less information (because tail calls have been removed from the call stack), making debugging errors potentially more difficult.

Bonus: Does JavaScript support TCO?

Not in the video but relevant: ECMAScript 6 offers TCO, but TCO "isn't supported by many [JavaScript] engines and that may never change." Source: Tail call optimization in ECMAScript 6 by Dr. Axel Rauschmayer.

The ECMAScript 6 compatibility table shows that there indeed are not many browsers/engines that support TCO – only these (as of Aug 26, 2021):

Safari 14+

iOS Safari 12+

WebKit, the browser engine used by Safari and iOS Safari

Kinoma XS6, "a JavaScript runtime optimized for the applications that power IoT devices"

How to sort `package.json` automatically

2021-01-06T12:00:00+03:00

Just run npx sort-package-json.

This takes about 4–8 seconds on my machine because npx has to first download the sort-package-json package. If that's too slow for you, install the package globally:

# i = install # -g = --global npm i -g sort-package-json

Then you can run just:

sort-package-json

And it will take less than a second.

You can also install the package locally and even run it in Git's pre-commit hook (using Husky or Lefthook) or in your CI pipeline. More options are mentioned in sort-package-json's documentation.

Source: My own Stack Overflow answer

How to force push in Git with style (and some safety)

2021-01-04T12:00:00+03:00

Never run git push --force. Instead run git push --force-with-lease or alias it to git please.

Please be polite

Never run git push --force or you might overwrite commits pushed by others. Instead run:

git push --force-with-lease

Or if using my Git aliases:

git please

Please = force push with lease. So polite!

(Unfortunately I don't remember where I found this alias, so I can't give proper credit.)

--force vs --force-with-lease

Git's manual is too wordy, so I'm relying on the answers to git push --force-with-lease vs --force on Stack Overflow.

chevybow writes (slightly modified and shortened):

--force overwrites a remote branch with your local branch.

--force-with-lease is a safer option that will not overwrite any work on the remote branch if more commits were added to the remote branch (by another team member or coworker or what have you). It ensures you don't overwrite someone else's work by force pushing.

I just think of --force-with-lease as the option to use when I want to make sure I don't overwrite any teammate's code. A lot of teams at my company use --force-with-lease as the default option for a fail-safe. It's unnecessary in most circumstances but will save you lots of headache if you happen to overwrite something that another person contributed to remote.

Warning: fetching is risky

G. Sylvie Davies writes:

There's a sad implication here: since git fetch updates all refs under "refs/remotes/origin/*" to their latest versions, this combination of commands is essentially identical to git push --force:

git fetch # The command below behaves identically to "git push --force" # if a "git fetch" just happened! git push --force-with-lease

To work around this inherent weakness in git push --force-with-lease I try to never run git fetch. Instead I always run git pull --rebase whenever I need to sync with upstream, since git pull only updates a single ref under refs/remotes, keeping the "lease" of --force-with-lease useful.

Does your code editor or IDE do automatic fetching? You might want to disable that unless you can accept the risk.

When to force push (with lease)

Some say that one should never force push. I say that's bollocks.

If you are working on your own short-lived branch (not master or main), feel free to rewrite its history: rebase, squash etc. After rewriting a branch's history, a force push is needed.

The "if" in the previous paragraph is a misnomer. Of course you are working on short-lived branches and not directly on the master/main branch, right? If you are not yet doing trunk-based development, look it up.

How to undo the last / previous / most recent commit in Git

2021-01-02T12:00:00+03:00

Run git reset HEAD~ or alias it to git undo. Bonus: how to use the commit message from the undoed commit.

TL;DR

Undo the last/previous/most recent commit while preserving the changes:

# Keep the undoed changes git reset HEAD~ # or # Keep the undoed changes in the staging area git reset HEAD~ --soft

Afterwards, to do a commit and use the commit message from the undoed commit:

git commit -c ORIG_HEAD

If using my Git aliases:

git undo # or git undo --soft # Use the commit message from the undoed commit git redo

Explanation

Undoing

HEAD is your current "position" in Git's history; it points to the commit that you have currently checked out.

HEAD~ points to HEAD's parent commit, i.e. to the previous commit of your current position.

git reset HEAD~ resets the head to HEAD~, i.e. to the previous commit.

From git reset's documentation:

git reset [<mode>] [<commit>]

This form resets the current branch head to <commit> and possibly updates the index (resetting it to the tree of <commit>) and the working tree depending on <mode>. If <mode> is omitted, defaults to --mixed. The <mode> must be one of the following:

--soft

Does not touch the index file or the working tree at all (but resets the head to <commit>, just like all modes do). This leaves all your changed files "Changes to be committed", as git status would put it.

--mixed

Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action.

"The index" refers to the staging area (the "Changes to be committed" area).

--mixed is the default mode, so git reset HEAD~ resets the index, meaning that the undoed changes are not kept in the staging area (but the changes are preserved).

git reset HEAD~ --soft on the other hand doesn't touch the index file, meaning that the undoed changes are kept in the staging area.

Should you use the --soft flag? Depends on whether you want the undoed changes to be in the staging area.

Redoing

From git commit's documentation:

-C <commit>

--reuse-message=<commit>

Take an existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit.

-c <commit>

--reedit-message=<commit>

Like -C, but with -c the editor is invoked, so that the user can further edit the commit message.

From gitrevisions's documentation:

ORIG_HEAD is created by commands that move your HEAD in a drastic way, to record the position of the HEAD before their operation, so that you can easily change the tip of the branch back to the state before you ran them.

In other words, ORIG_HEAD points to the previous HEAD – in this case to the undoed commit.

Thus, git commit -c ORIG_HEAD uses the commit message from the undoed commit and opens the editor so you can edit the message before committing.

Further resources

git commit's documentation

git reset's documentation

gitrevisions's documentation

What is HEAD in Git? on Stack Overflow

What's the difference between HEAD^ and HEAD~ in Git? on Stack Overflow

How to chunk an array in JavaScript

2021-01-01T12:00:00+03:00

A simple reducer to chunk (split) an array into smaller arrays.

For example, with a chunk size of 3:

// Before [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] // After [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]

Here's how:

const chunk = (array, size) => array.reduce((acc, _, i) => { if (i % size === 0) acc.push(array.slice(i, i + size)) return acc }, []) // Usage: const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] const chunked = chunk(numbers, 3) console.log(chunked) //=> [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]

At every nth iteration (where n = size; starting at the first iteration), the accumulator array (acc) is appended with a chunk of the array (array.slice(i, i + size)) and then returned. At other iterations, the accumulator array is returned as-is.

If size is zero, the method returns an empty array. If size is negative, the method returns broken results. So, if needed in your case, you may want to do something about negative or non-positive size values.

Further resources

Test the code on flems.io

More info in my Stack Overflow answer

How to bypass Episerver's Content Delivery API when doing Ajax requests

2020-12-23T12:00:00+03:00

Requests with the Accept header set to application/json are automatically routed to Content Delivery API. Here's how to bypass it and make the request go to a page controller instead.

Starting from Content Delivery API version 2.3.0, requests with the Accept header set to application/json are automatically routed to Content Delivery API. This is called "Using friendly URLs" in the documentation.

This is a nice feature. But what if you want to make an Ajax request to a page controller instead? For example, if you have a Single Page Application, you might want to retrieve the next page's data in JSON format from the page type's controller using an Ajax request.

In the controller you can do something like this:

     public class MyPageController : PageController<MyPage> { public ActionResult Index(MyPage currentPage) { if (Request.IsAjaxRequest()) { var data = /* ... */; return Json(data); } return View("Index", new MyPageViewModel(currentPage)); } }

But, because the Ajax request's Accept header will be set to application/json, the request will be automatically routed to Content Delivery API, and the request will never reach the controller.

The value of the Accept header can't be changed to another MIME type if the desired format for the response data is JSON. So what to do?

Turns out that it's possible to specify a relative quality value for the MIME type: application/json;q=1. From MDN:

Quality values, or q-values and q-factors, are used to describe the order of priority of values in a comma-separated list. It is a special syntax allowed in some HTTP headers and in HTML. The importance of a value is marked by the suffix ';q=' immediately followed by a value between 0 and 1 included, with up to three decimal digits, the highest value denoting the highest priority. When not present, the default value is 1.

Now that the value of the Accept header doesn't strictly equal to application/json, the request is not routed to Content Delivery API. Instead, it reaches the controller. Egg-cellent!

Since only one MIME type is specified, and since the default quality value is anyway 1, appending ;q=1 to the Accept header's value doesn't have any side effects.

You should probably document this somewhere. For example, if you are using fetch(), you can write something like this:

function getPageData(url) { return fetch(url, { headers: { // Requests with the `Accept` header set to `application/json` // are automatically routed to Content Delivery API. // The `;q=1` here is a "relative quality value" // and doesn't have any effects other than // tricking the request to go to the controller // instead of Content Delivery API. Accept: 'application/json;q=1', }, }).then((response) => response.json()) }

This way some overly enthusiastic developer won't remove the quality value thinking that it's unnecessary (since there's only one MIME type and since the default quality value is anyway 1).

TFA stands for "The Featured Article"

2020-12-01T12:00:00+03:00

And RTFA/RTFM stands for "Read The Fine Article/Manual." Who likes profanity, anyway?

Some people on sites like Reddit and Hacker News tend to use the abbreviation TFA to refer to the discussed article. If the comment is otherwise non-negative or even positive, I'm always baffled – why the hostility? Why the profanity?

Luckily, with some quick googling, I found that the letter "F" in the abbreviations TFA, RTFA and RTFM can be interpreted as "fine" or "featured." Genius! Now I don't have to get triggered from reading other people's comments on the Internet.

Bonus: Android's Log util has Log.d(), Log.e(), Log.i(), Log.v() and Log.w() methods for different levels of logging: debug, error, information, verbose and warning, respectively. And there's one more: Log.wtf() to "report an exception that should never happen." But what does "wtf" mean here? What a terrible failure. Terrific!

RFC 2119 in a nutshell

2020-11-17T12:00:00+03:00

RFC 2119 defines key words such as "MUST," "MUST NOT," "REQUIRED" and "SHALL" that are often used in specifications. Here's a summary of the key word definitions.

Some specifications, like Semantic Line Breaks and Semantic Versioning, include this piece of text at the beginning – as RECOMMENDED by RFC 2119:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Here's a summary of what each of the key words mean:

MUST = REQUIRED = SHALL

An absolute requirement.

MUST NOT = SHALL NOT

An absolute prohibition.

SHOULD = RECOMMENDED

Ignore only with good reasons.

SHOULD NOT = NOT RECOMMENDED^[1]

Ignore only with good reasons.

MAY = OPTIONAL

Truly optional, but if included, the implementation MUST be interoperable with another implementation which does not include the option, and vice versa.

The RFC also raises these points for specification authors:

The key words MUST be used only when required for interoperability or limiting potentially harmful behavior.

The security implications between MUST and SHOULD, as well as between MUST NOT and SHOULD NOT, may be very subtle, so the differences SHOULD^[2] be elaborated.

Now go read the RFC, it's actually very short and clear.

Footnotes

The key word "NOT RECOMMENDED" is missing from the recommended introductory phrase, but it's paired with "SHOULD NOT" in the RFC. ↩

The word "should" is not capitalized in this part of the RFC, but it seems like a missed opportunity so I capitalized it. ↩

Hyperscript: hyperior alternative to JSX

2020-11-03T12:00:00+03:00

JSX is just JS under the hood. Hyperscript is like that JS, but better. Example: h('a.link', { href }, 'Click me') is nicer than <a className="link" href={href}>Click me</a>, right? Right?!

How JSX works

JSX is not valid JS – it's a syntax extension to JS. Let's consider the following imaginary React component written using JSX:

function Header({ links }) { return ( <header id="my-header" className="header"> <div className="logo"> <a href="/">mtsknn.fi</a> </div> <nav> <ul className="header__links"> {links.map(({ href, text }) => ( <li key={href}> <a href={href}>{text}</a> </li> ))} <li> <DarkModeToggle /> </li> </ul> </nav> </header> ) }

The code gets compiled by Babel before it's served to the browser^[1], so that JSX gets replaced with React.createElement() function invocations^[2]:

function Header({ links }) { return ( React.createElement('header', { id: 'my-header', className: 'header' }, React.createElement('div', { className: 'logo' }, React.createElement('a', { href: '/' }, 'mtsknn.fi') ), React.createElement('nav', null, React.createElement('ul', { className: 'header__links' }, links.map(({ href, text }) => ( React.createElement('li', { key: href }, React.createElement('a', { href: href }, text) ) )), React.createElement('li', null, React.createElement(DarkModeToggle, null) ) ) ) ) ) }

Uh, that's a bit annoying to read. Let's make that a bit more readable by assigning React.createElement() to a new variable h. ("h" as in hyperscript – though note that this is not yet proper hyperscript.) Let's also simplify { href: href } into { href } because OCD:

import { createElement as h } from 'react' function Header({ links }) { return ( h('header', { id: 'my-header', className: 'header' }, h('div', { className: 'logo' }, h('a', { href: '/' }, 'mtsknn.fi') ), h('nav', null, h('ul', { className: 'header__links' }, links.map(({ href, text }) => ( h('li', { key: href }, h('a', { href }, text) ) )), h('li', null, h(DarkModeToggle, null) ) ) ) ) ) }

Now we can more clearly see that

the first argument of React.createElement() is the tag name or component;

the second argument is the props object (or null if the element doesn't get any props);

and the rest of the arguments are the children of the element.

So, under the hood, JSX is just regular JS. And it's not specific to React. Babel could as well replace JSX with something else than React.createElement() function invocations.

What hyperscript is and looks like

I couldn't find a proper definition for hyperscript, but think of it as the JS equivalent of JSX. You can use hyperscript to declare the structure of your (React) components in plain JS. Hyperscript is like the code in the previous code block, but better.

Let's take a look at two real-world hyperscript implementations to see what they look like.

Example 1: React with react-hyperscript

Looking at our previous code example, it would be nice if we could at least:

omit the second argument if it's null. This would make the code easier to read by reducing visual noise.

optionally wrap the children in an array. This would make indentation more logical and Prettier-compatible (is that a word?). It would also allow you to use trailing commas if that's your thing.

The react-hyperscript library supports that. It also supports:

using CSS selectors in the tag names to specify CSS classes and IDs. For example, h('header#my-id.foo.bar') is the same as h('header', { id: 'my-id', className: 'foo bar' }).

omitting the tag name if it's div, i.e. the default tag name is div. For example, h('.logo') is the same as h('div.logo').

Let's see what our component looks like when using react-hyperscript:

import h from 'react-hyperscript' function Header({ links }) { return ( h('header#my-header.header', [ h('.logo', [ h('a', { href: '/' }, 'mtsknn.fi'), ]), h('nav', [ h('ul.header__links', [ links.map(({ href, text }) => ( h('li', { key: href }, [ h('a', { href }, text), ]) )), h('li', [ h(DarkModeToggle), ]), ]), ]), ]) ) }

That looks pretty good! We got rid of null props and some other prop objects as well by using CSS syntax. Children that are not on the same line as their parent are wrapped in arrays. This makes the indentation clearer.

(Side note: at the end of the code example, the DarkModeToggle component needs to be in an array because it's a component instead of a string. There's an open issue on GitHub about that. Unfortunately the library hasn't received any updates in a couple of years, but this issue is not a biggie.)

To start using react-hyperscript,

run npm install react-hyperscript (or npm i react-hyperscript for short)

add import h from 'react-hyperscript' to your code

start replacing that filthy JSX with the h() function.

Example 2: Mithril

Mithril is a small (<10kb gzip) yet mighty JS framework. I prefer using Mithril over React in my own projects because it's so good. (I should write a blog post about it.)

Anyway, Mithril uses hyperscript by default. Mithril's hyperscript flavor has two main extra features compared to react-hyperscript:

Besides CSS classes and IDs, you can also specify static attributes in the tag name (first parameter) using CSS syntax. For example, m('a[href=/foo]') is the same as m('a', { href: '/foo' }). (Notice how Mithril uses m() instead of h(), but that doesn't matter in practice.)

It's more flexible about its input parameters – children can be in an array, but they don't have to. In our header component example, the DarkModeToggle component doesn't need to be in an array (unlike when using react-hyperscript).

Our component would look like this when using Mithril:

import m from 'mithril' function Header({ links }) { return ( m('header#my-header.header', [ m('.logo', [ m('a[href=/]', 'mtsknn.fi'), ]), m('nav', [ m('ul.header__links', [ links.map(({ href, text }) => ( m('li', { key: href }, [ m('a', { href }, text), ]) )), m('li', m(DarkModeToggle)), ]), ]), ]) ) }

That's almost identical than when using react-hyperscript, only a bit more terse. (I have highlighted the two lines that are different.) But being able to specify static attributes using CSS syntax is nifty, especially when you have more of them; the example header component has just one. And the increased flexibility regarding the input parameters means one thing less to worry about, i.e. whether children need to be wrapped in arrays or not.

Since Mithril uses hyperscript by default, there's no steps to enable hyperscript. Read the Mithril tutorial and start using it.

Pros and cons of hyperscript

Okay, that's nice and all, but why would you use hyperscript over JSX?

Pros

Here's a non-exhaustive list of the good sides of hyperscript:

No need for context switching between JS and XML because hyperscript is just JavaScript.

Hyperscript could also make it easier to understand how your JS framework of choice (be it React or Mithril or something else) works. When learning React and JSX, a possibly common frustration is "why can't I use if statements and for loops in my JSX?" When using hyperscript, it's probably clearer why you can't have if statements and for loops as function arguments.

CSS classes and IDs can be specified in the tag name which leads to terser code. Very nice when using e.g. Tailwind: h('img.h-16.md:h-24') etc.

In some flavors of hyperscript (e.g. Mithril), other CSS-like shorthands are also possible, like m('a[href=/foo].bar.baz').

Hyperscript is less verbose (CSS-like tag names, no closing tags). This leads to shorter code – without sacrificing readability if you ask me.

No need for JSX compilation. This leads to simpler tooling, simpler build processes and fewer dependencies.

You can start prototyping without having to setup complex build processes et cetera. (Though in the case of React, using Create React App is also easy and quick. But still much more complex!)

Simpler tooling also means that your code editor doesn't have to support or have plugins for JSX parsing, highlighting etc. Just open notepad.exe and start hacking like any advanced programmer.

Cons

Hyperscript is not as common as JSX (at least in the React world). Unless you can convince your team to choose hyperscript, JSX is likely the easier choice. If you use JSX, it might also be easier to attract new developers to your team due to familiarity. Though learning hyperscript shouldn't be at all difficult.

The syntax might take some time to get used to. While hyperscript is just JavaScript, there are a lot of different kinds of brackets. But like said: learning hyperscript shouldn't be difficult.

Because there aren't closing tags like in JSX, you can't see as well where tags end. I haven't personally found this to be a problem though.

Android Studio solves this problem nicely for Flutter projects. It automatically shows code comments at the end of widgets (think of React components) like this:

return new MyWidget( child: Container( color: Colors.pinkAccent, height: 200, width: 200, child: Center( child: Text( 'Bacon ipsum', style: TextStyle( color: Colors.white, fontSize: 24, fontWeight: FontWeight.bold, ), ), // Text ), // Center ), // Container ); // MyWidget

There's runtime overhead of parsing the CSS-like selectors. This is unlikely a major performance problem unless you have lots of complex selectors, but something to be aware of.

If you use Mithril, you can setup a Babel plugin called mopt to statically optimize m() function invocations. Look ma, no more runtime overhead!

Bottom line

Hmm, looks I listed as many pros as I listed cons. Didn't I say that hyperscript is hyperior?!

If you ask me, the pros greatly outweight the cons. Give my hyperscript over JSX any day, thank you.

In the end it's a matter of personal preference and what works for you and your team. Because this is a personal blog, I'm free to call hyperscript hyperior anyhow, so checkmate, atheists. ;-)

Further resources

The React docs have a couple of pages about JSX:

Introducing JSX

JSX In Depth

React Without JSX

Mithril docs' section about JSX vs hyperscript

hyperscript-helpers and react-hyperscript-helpers offer even terser hyperscript syntax. I'm not a fan of this style, but check them out, you might like them.

@thi.ng/hdom and ijk are hyperscript alternatives based on arrays. I haven't tried these, but they look interesting.

Footnotes

It's also possible to use Babel in the browser to compile code on the fly. That would be slow and in most cases just unnecessary. ↩

React 17 introduced a new JSX transform that makes the output look different. This doesn't change the idea behind hyperscript. ↩

`contenteditable` + `::first-letter` + Chrome = buggy combo

2020-10-13T12:00:00+03:00

This combination causes weird behavior and data loss because of a bug in Chrome, so it's best not to use contenteditable and ::first-letter together.

What's contenteditable?

The contenteditable HTML attribute makes an element's contents editable in the browser.

Demo:

I'm a blockquote with the `contenteditable` attribute. Select and edit me!

For example, TinyMCE is a WYSIWYG ("what you see is what you get") HTML editor that uses the contenteditable attribute under the hood.

What's ::first-letter?

The ::first-letter CSS pseudo-element can be used to stylize "the first letter of the first line of a block-level element, but only when not preceded by other content (such as images or inline tables)."

Initial on Wikipedia:

In a written or published work, an initial or drop cap is a letter at the beginning of a word, a chapter, or a paragraph that is larger than the rest of the text.

Example:

article > p:first-child::first-letter { font-size: 2em; font-weight: bold; }

Demo:

This paragraph has an initial / drop cap letter, meaning that the first letter ("T") should be large and bold.

This paragraph has a regular first letter.

What's Chrome?

Just kidding, I know you know. 😄

Example use case for the combination

Your website shows drop cap letters (::first-letter) somewhere.

Your website's content creators create content with TinyMCE (which uses the contenteditable attribute under the hood).

The TinyMCE editor has been stylized (using CSS) to show drop cap letters so that the content looks the same in the TinyMCE editor and on the live site.

Your website's content creators use Chrome.

That's how you end up with the buggy combination that's contenteditable + ::first-letter + Chrome.

Problems with the combination

Note: in my case I had a TinyMCE editor in which the first paragraph had a drop cap letter and other paragraphs were normal (no drop caps). In other cases the problems might be different.

Also note: the problems are not related to TinyMCE per se; it just happens to use the contenteditable attribute under the hood.

Incorrect caret position

When the caret is in the drop cap paragraph, the caret's position is one character too much to the right. This is confusing.

Update in November 2021: this seems to no longer be an issue as of Chrome 95 (though I don't know in which version the issue has been fixed).

Minor data loss

When the caret is at the end of the first paragraph, pressing Delete removes two characters:

the line break between the paragraphs

the last character of the first paragraph.

Normally only the line break between the paragraphs should be removed, so that the contents of the second paragraph are moved to the end of the first paragraph.

The same issue happens (two characters are removed instead of one) when the caret is at the beginning of the second paragraph and Backspace is pressed.

In addition to causing minor data loss, this buggy behavior is also confusing.

Extra confusion: if the drop cap covers more than one character^[1], the operations above remove more than one extra character.

Major data loss

When the caret is at the end of the drop cap paragraph, pressing Backspace empties the whole paragraph! Looking at Chrome DevTools, the <p> tag is still there, but it's empty.

Normally only the last character of the paragraph should be removed.

The same issue happens (the whole paragraph is emptied) when the caret is at the second last position of the first paragraph and Delete is pressed.

In addition to causing major data loss, this buggy behavior is also confusing.

The root cause: a bug in Chrome

Long story short: this is a bug in Chrome. The "Contenteditable with :first-letter styling" Chromium issue was reported in 2013 (almost 9 years ago as of November 2021) and hasn't been fixed yet.

The fix: don't use the combination

In practice you should avoid using the contenteditable HTML attribute and the ::first-letter CSS pseudo-element together.

Avoiding the bug might not be a "fix" per se, but since the bug is in Chrome itself, there's not much else to do.

How I investigated the issue

This was a simple 30-minute investigation, but I hope that this short story will be helpful to some by showing one way of investigating these kind of bugs.

I first tested what styles of the ::first-letter pseudo-element cause the problems by tweaking the styles of the buggy TinyMCE editor in Chrome DevTools. After quick fiddling, it was apparent that any single valid style causes the problems. Because of this, it looked unlikely that the issue was in the CSS styles.

Thinking that this was an issue in TinyMCE, I googled for queries like "tinymce first-letter" to look for bug reports and solutions. But all I could find was one TinyMCE issue on GitHub from 2016 which was closed in 2018 without a solution. "It seems to be a problem with CSS and not TinyMCE itself" they said.

Hmm, what could I try next... I was using TinyMCE version 4 and the latest was version 5. So maybe the issue had been fixed ages ago (in TinyMCE version 5) and everyone had already upgraded to version 5, so that's why no one was talking about this? Note that I was still thinking that the issue was in TinyMCE.

Well, let's try. I remembered that there was a live demo of TinyMCE on TinyMCE's homepage (update: the demos are not anymore on the homepage as of November 2021). I added drop cap stylings to the demo using Chrome DevTools, and... Bleh, version 5 had the same problems.

But wait! While tweaking the styles, I noticed that the TinyMCE demo used the contenteditable attribute. Could it be that this was not a styling issue (despite the GitHub issue suggesting otherwise) but related to the contenteditable attribute?

I created a quick 2-minute fiddle of the contenteditable + ::first-letter combo at flems.io – and voilà! My quick fiddle had the same problems.

Because the contenteditable attribute is more common than TinyMCE, I now had higher hopes of finding relevant results. When googling for "contenteditable first-letter," the first SO question that I opened had this snippet of wisdom in the top-voted answer by Marc J (thanks Marc!):

I just noticed that there is a bug in Chrome that causes the cursor to become in the wrong spot with contenteditable and ::first-letter.

And that was it! Some fiddling, googling, and a little bit of luck.

Footnotes

If a drop cap paragraph starts e.g. with the word "I'm," the drop cap covers both the letter "I" and the apostrophe. "The first letter of an element is not always trivial to identify," as mentioned on the ::first-letter page on MDN. ↩

How to change Modified date programmatically in Episerver

2020-10-08T12:00:00+03:00

When migrating content from another platform to Episerver, I wanted to set a specific datetime for each content's Modified date (Saved property). Sounds simple, but it was only possible by using Episerver's internal, undocumented API.

How to do it

Setting the current date

This should be straightforward.

Set a content's SetChangedOnPublish property to true:
(content as IChangeTrackable).SetChangedOnPublish = true;

Publish the content.

From Episerver's support page Cannot programmatically set modified date:

[S]etting the SetChangedOnPublish property to true and then [publishing] the page [will] trigger an update of the modified date in the database. So it will set the date to the same one as when you publish the page.

Setting an arbitrary date

This is more complicated and this is what this blog post is about.

First, here's the code:

using EPiServer.Framework; using EPiServer.DataAccess.Internal; // ... // Update the "Modified" datetime. // A hacky solution that uses Epi's internal, undocumented, possibly unstable API. // Tested with EPiServer.CMS 11.14.0 and 11.19.0. ContextCache.Current[ContentSaveDB.UseIChangeTrackingSavedKey] = new object(); (content as IChangeTrackable).Saved = data.PublishedAt; (content as IChangeTrackable).SetChangedOnPublish = true;

And here's a rough explanation:

Use Episerver's internal ContentSaveDB API to change an internal setting. (Or something like that – I don't really know what's going on since the internal API is internal and undocumented).

Set the content's Saved property to your desired datetime value. (Yes, the Saved property is the correct one even though we are modifying the Modified date. There's no Modified property.)

Set the content's SetChangedOnPublish property to true. Otherwise the new value of the Saved property won't take effect. (Yes, it's SetChanged* and not "SetSaved*" which doesn't even exist. I guess naming things is difficult.)

That's it! Now publish the content or do whatever you were doing.

But before you go, remember this:

The code might stop working when you do any NuGet package updates. That's because the API you are using is internal and thus unsupported. From the ContentSaveDB class's documentation:

Unsupported INTERNAL API! Not covered by semantic versioning; might change without notice.

Is this a good idea?

Not really, but do you have any better ideas?

In my case, I was migrating content from another platform (Contentful, but that's irrelevant) to Episerver. After I was done, I didn't need the code anymore, so it didn't matter that I was using an internal, undocumented, possibly unstable API.

You too shouldn't use this hacky method in any long-living code.

Should this be even possible?

Well, that's a funny question! According to Episerver's support page Cannot programmatically set modified date from October 2017, this shouldn't be possible. From the page:

It is not possible to set the modified date to a specific date programmatically.

The date can only be changed by setting the SetChangedOnPublish property to true and then publish the page. This will in turn trigger an update of the modified date in the database. So it will set the date to the same one as when you publish the page.

But like I explained above, it is possible to set the Modified date to a specific date programmatically.

(Fun fact: Google decided to choose the misleading quote above as a Featured snipped (screenshot below). Thanks Google. 😂 I have since wrapped the <blockquote> in a <div data-nosnippet> element.)

How I found the solution

"Oh, damn," I thought to myself after reading that Episerver's support page. But fortunately I didn't give up just yet.

After googling a bit more, I found a GitHub gist by Kim Gunnarsson from April 2016. (Funnily, the gist was created 1.5 years before that Episerver's support page.)

The following lines of code from the gist are relevant, the first line being the most important:

EPiServer.Framework.ContextCache.Current[EPiServer.DataAccess.ContentSaveDB.UseIChangeTrackingSavedKey] = new object(); var clone = page.CreateWritableClone(); clone.Saved = clone.StartPublish; clone.SetChangedOnPublish = true;

The gist is currently 4.5 years old (as of October 2020) and thus didn't work out of the box for me – I was using EPiServer.CMS version 11.14.0 and soon after version 11.19.0. But this did work:

EPiServer.Framework.ContextCache.Current[EPiServer.DataAccess.Internal.ContentSaveDB.UseIChangeTrackingSavedKey] = new object(); (content as IChangeTrackable).Saved = data.PublishedAt; (content as IChangeTrackable).SetChangedOnPublish = true;

I.e. the ContentSaveDB class has been changed into an internal class at some point.

The first line can be simplified into this with proper using statements:

using EPiServer.Framework; using EPiServer.DataAccess.Internal; ContextCache.Current[ContentSaveDB.UseIChangeTrackingSavedKey] = new object();

Finally, you may want to slap a comment saying that this is a hacky solution. Behold, we ended up with the code that I already presented to you at the very beginning:

using EPiServer.Framework; using EPiServer.DataAccess.Internal; // ... // Update the "Modified" datetime. // A hacky solution that uses Epi's internal, undocumented, possibly unstable API. // Tested with EPiServer.CMS 11.14.0 and 11.19.0. ContextCache.Current[ContentSaveDB.UseIChangeTrackingSavedKey] = new object(); (content as IChangeTrackable).Saved = data.PublishedAt; (content as IChangeTrackable).SetChangedOnPublish = true;

Hmm, did someone say this isn't possible? Ha, checkmate!

Switch statements: `default` doesn't have to be the last case

2020-10-03T12:00:00+03:00

Non-last default cases are confusing but perfectly valid. Sometimes it makes sense to place them at the beginning or in the middle.

Huh, that's possible?

If you think about all the switch statements you have ever seen in your life, I guess that in most of them, the default case has been the last or almost last one.

I still remember how dumbfounded I was when a friend of mine sent me the following snippet of Unity code (C#) that he had ~~copy-pasted~~ picked up from a course he was following at the time:

void Update() { switch (state) { default: case State.WaitingToStart: if (Input.GetKeyDown(KeyCode.Space) || Input.GetMouseButtonDown(0)) { state = State.Playing; rb.bodyType = RigidBodyType2D.Dynamic; Jump(); } break; case State.Playing: if (Input.GetKeyDown(KeyCode.Space) || Input.GetMouseButtonDown(0)) { Jump(); } break; case State.Dead: break; } }

As you can see, the default case is at the very top.

My initial thought was: dude, wtf, does this even compile?

I was so used to seeing the default case at the bottom that I couldn't comprehend this. It looked like an if statement where the else branch is at the beginning.

I think my inner logic circuit deduced that since the default case is the first one, the other cases are not even checked.

But turns out that's not the case (no pun intended). The code above is perfectly valid and even makes sense when you think about it. (We'll come back to this code snippet in the What about the Unity code? section.)

The position of the default case doesn't matter (unless there's a fallthrough)

After recovering from the shock of seeing that Unity code, I had to do some digging.

Like the old saying goes, "all programming-related Google searches lead to Stack Overflow." Here's the highest-voted relevant SO question that I could find. Let's see what the accepted answer by Secure says:

The C99 standard is not explicit about this, but taking all facts together, it is perfectly valid.

A case and default label are equivalent to a goto label. [...]

All cases are evaluated, then it jumps to the default label, if given.

(The actual answer is more thorough with excerpts from the C99 standard.)

Here's what's said about JavaScript's switch statements on MDN:

A switch statement first evaluates its expression. It then looks for the first case clause whose expression evaluates to the same value as the result of the input expression [...]

If no matching case clause is found, the program looks for the optional default clause [...] By convention, the default clause is the last clause, but it does not need to be so.

One more: here's what Paul Dixon has answered to a relevant SO question in the context of PHP and o'boy do I agree:

It is an unusual idiom, it causes a little pause when you're reading it, a moment of "huh?". It works, but most people would probably expect to find the default case at the end.

Okay, you get the point: the position of the default case doesn't matter in C, C#, JavaScript, PHP, and probably many other C-style languages as well – if there are no fallthroughs.

If there are fallthroughs in a switch statement, i.e. there's no break or return statement between some cases, the position of the default case might matter. This is a common concept in switch statements, but if it's still confusing how they work with non-last default cases, the following code examples should clarify this.

Situations where a non-last default case can be useful

While putting the default case to the end is usually the most intuitive option, I found four situations where a non-last default case can be useful.

(If you can think of other useful situations, please tell me!)

Cases in logical order

Let's say you have cases from 1 to 3, and the default case is number 2.

If you specify the cases so that the default case is the last one, the order would be 1, 3 and 2/default. It might instead be more intuitive to specify the cases in logical order: 1, 2/default and 3. Like so:

switch (foo) { case 1: // do something... break; case 2: default: // do something... break; case 3: // do something... break; }

The more cases there are and the longer they are, the more sense this likely makes. On the other hand, if the default case is in the middle of a long and complex switch statement, it might be easy to miss it.

I got this idea from an SO answer by Salil.

Normal case first

Let's say you have a situation where there's a normal/default case and a bunch of error cases.

If you put the normal case to the end, it emphasizes the error cases. Unnecessarily so, especially if the error cases are uncommon.

I got this idea from an SO answer by kriss which included this code example:

switch (poll(fds, 1, 1000000)) { default: // here goes the normal case : some events occured break; case 0: // here goes the timeout case break; case -1: // some error occurred, you have to check errno }}

kriss also talks about how the order of cases can affect performance, but I'll just skip over this since it smells like premature optimization. (Maybe it can be important if you are working with low-level, performance-critical code and not thinking about this prematurely.)

Flow control with fallthroughs

If you are using a switch statement for flow control (a series of steps) and don't break between cases, putting default to the beginning makes for a clear switch statement.

The following code example is adapted from an SO answer by DanielM:

switch (step) { default: case STEP_1: // do some stuff for step one // fallthrough case STEP_2: // this follows on from step 1 or you can skip straight to it }

Another good example is "a state machine where an invalid state should reset the machine and proceed as though it were the initial state," from an SO answer by supercat:

switch (widget_state) { default: /* Fell off the rails--reset and continue */ widget_state = WIDGET_START; /* Fall through */ case WIDGET_START: // ... break; case WIDGET_WHATEVER: // ... break; }

This is not limited to state machines. Take this example, adapted from an SO answer by Dan Larsen:

switch (color) { default: printf("No color selected so defaulting to "); // Fallthrough case COLOR_RED: printf("red"); break; case COLOR_BLUE: printf("blue"); break; case COLOR_GREEN: printf("green"); break; }

If color is red, blue or green, the code will print just the color. Otherwise (if color is e.g. yellow) the code will print "No color selected so defaulting to red."

Though maybe it would be clearer to move the default case closer to the bottom (unless you want to sort the cases in logical order):

switch (color) { case COLOR_BLUE: printf("blue"); break; case COLOR_GREEN: printf("green"); break; default: printf("No color selected so defaulting to "); // Fallthrough case COLOR_RED: printf("red"); break; }

This is now similar to supercat's "alternative arrangement [of the state machine where] an invalid state should not reset the machine but should be readily identifiable as an invalid state":

switch (widget_state) { case WIDGET_IDLE: widget_ready = 0; widget_hardware_off(); break; case WIDGET_START: // ... break; case WIDGET_WHATEVER: // ... break; default: widget_state = WIDGET_INVALID_STATE; /* Fall through */ case WIDGET_INVALID_STATE: widget_ready = 0; widget_hardware_off(); // ... do whatever else is necessary to establish a "safe" condition }

Preventing accidental fallthroughs to the default case

If the default case is the first one, it's impossible for other cases to accidentally fall through to the default case.

This idea is from an SO answer by JaredPar. He continues to clarify: "This means default will run if, and only if, the value matches no case statements in the switch block."

Using a linter would also help you catch accidental fallthroughs, so I don't know whether the confusion caused by placing the default case to the top outweighs the benefits. (To be fair, JaredPar also writes: "Note I'm not saying I agree with it, this is simply the logic others have presented to me in the past.")

So, should you use non-last default cases?

Unless you have a good reason to do otherwise, it's safest to put the default case to the end. This way anyone familiar with switch statements can more easily understand the structure of your switch statement.

But if you have a good reason, go ahead. Just be prepared that your code might be initially rather confusing to other developers.

What about the Unity code?

I would put the mindboggling code sent to me by my friend to the Cases in logical order category. It also somewhat belongs to the Flow control with fallthroughs category.

After some thought, it's actually logical to present the game states (switch cases) in the order they have been presented: "waiting to start," "playing" and "dead." That's the natural flow of the game states. The initial game state is "waiting to start," so the most logical position for the default case is at the beginning.

In the end, the code was actually quite clever!

Mnemonic for Markdown's link syntax (and image syntax)

2020-09-28T12:00:00+03:00

Was it [text](url) or (text)[url]? Use this one weird trick to remember – Markdown consultants HATE it! Spoiler: it's the former since it looks like a function call.

Link syntax looks like a function call

The first part looks like an array of words: [link text].

The second part looks like it's used to call a function with one parameter: (url).

Put together:

[I'm an array of words](/and-im-a-parameter-to-a-function-call) [Link text with **bold words**](https://example.com/)

Optional second parameter

Thinking of functions, you can also provide a title as the second parameter. These are all valid and identical (according to the CommonMark Spec):

[Link text](/some-url "And a title") [Link text](/some-url 'And a title') [Link text](/some-url (And a title))

Output (×3):

<a href="/some-url" title="And a title">Link text</a>

The title attribute is not very accessible, so you shouldn't rely on it too much.

Anti-mnemonic

(link text)[url] would look like you are using the url key to access a value from... hmm, from the expression (link text), which isn't even a valid expression? That wouldn't make as much sense.

Alternative link syntaxes

For completeness, let's see other ways of specifying links in Markdown. Reference links are also related to Markdown's image syntax.

Autolinks

These are simple: wrap an absolute URI or an email address in angle brackets.

Example:

<https://example.com/foo/bar> <mail@example.com>

Output:

<a href="https://example.com/foo/bar">https://example.com/foo/bar</a> <a href="mailto:mail@example.com">mail@example.com</a>

Reference links

A reference link consists of link text and a link label.

The link label should have a corresponding "link reference definition" somewhere in the document, for example at the end of a section or at the end of the whole document. Link labels are case-insensitive.

Example:

Check out [foo][1], [bar][2] and [baz][3]. [1]: https://example.com/foo [2]: https://example.com/bar [3]: https://example.com/baz Do you know what's [my favorite search engine][duck]? I like it more than [Microsoft's search engine][bing]. [duck]: https://duck.com/ [bing]: https://bing.com/

Output:

Check out <a href="https://example.com/foo">foo</a>, <a href="https://example.com/bar">bar</a> and <a href="https://example.com/baz">baz</a>. Do you know what's <a href="https://duck.com/">my favorite search engine</a>? I like it more than <a href="https://bing.com/">Microsoft's search engine</a>.

Collapsed reference links

If the link text and label are the same (labels are case-insensitive), you can use "collapsed reference links" and drop the label:

Check out [foo][], [Bar][] and [BAZ & qux][]. [foo]: https://example.com/foo [bar]: https://example.com/bar [baz & qux]: https://example.com/baz

Shortcut reference links

"Shortcut reference links" take a step further by allowing you to drop the empty brackets as well:

Check out [foo], [Bar] and [BAZ & qux]. [foo]: https://example.com/foo [bar]: https://example.com/bar [baz & qux]: https://example.com/baz

Image syntax = ! + link syntax

The image syntax is the same as the link syntax, except that there's a bang (!) at the beginning, and the link text is the image's alt text:

![A nice pic](/image-url) ![A nice pic][a nice pic] ![A nice pic][] ![A nice pic] [a nice pic]: /image-url

Output (×4):

<img src="/image-url" alt="A nice pic" />

Omitting the alt text produces alt="":

![](/image-url) ![][a nice pic] [a nice pic]: /image-url

Output (×2):

<img src="/image-url" alt="" />

Image link

Nothing special; just the same link syntax where the link text is an image:

[![A nice pic](/image-url)](/link-url) [![A nice pic][a nice pic]](/link-url) [![A nice pic][]](/link-url) [![A nice pic]](/link-url) [![A nice pic](/image-url)][some page] [![A nice pic][a nice pic]][some page] [![A nice pic][]][some page] [![A nice pic]][some page] [a nice pic]: /image-url [some page]: /link-url

Huh, quite busy syntax.

Output (×8):

<a href="/link-url"> <img src="/image-url" alt="A nice pic" /> </a>

Further resources

The CommonMark Spec has more examples and edge cases covered. Check out these sections of the spec:

Links

Autolinks

Reference links

Images

Greedy quantifier	Lazy quantifier	Description
`*`	`*?`	zero or more
`+`	`+?`	one or more
`?`	`??`	zero or one
`{n}`	`{n}?`	exactly n
`{n,}`	`{n,}?`	n or more
`{n,m}`	`{n,m}?`	between n and m

Product	Price
RØDE Procaster (microphone)	179€
Focusrite Scarlett Solo 3rd Gen (USB audio interface)	110€
RØDE PSA1 (studio arm)	70€
RØDE PSM1 (shock mount)	40€
Cordial Silver Line (2.5m XLR–XLR cable)	21€
RØDE WS2 (pop filter / wind shield)	16€

Index	Position (`\|`)	Match	Lookahead	Lookbehind
0	`\|abcde`	nothing	`ab`	nothing
1	`a\|bcde`	nothing	`bc`	nothing
2	`ab\|cde`	nothing	`cd`	`ab`
3	`abc\|de`	nothing	`de`	`bc`
4	`abcd\|e`	nothing	nothing	`cd`
5	`abcde\|`	nothing	nothing	`de`

Matias Kinnunen – Blog

Better way to indent ordered lists in Markdown

Previewing HTML files directly on GitHub with a bookmarklet

Beware implicit `Content-Type: "application/json"`

Safari doesn't support `position: relative` on `` elements

"Slap" means "sounds like a plan"

How to use Azure AD authentication in DBeaver

`mailto:` links with `target="_blank"` are surprisingly tricky

Footnotes

Fix all requests timeouting in Burp Suite's Repeater

Two great video games I played through in 2023

Fiction books I read and liked in 2023

Tweaking website styles with uBlock Origin filters

"Else equals" in Handlebars (in SendGrid's Dynamic Templates)

HTTP headers: Accept vs Content-Type

Cmd-tabing to Firefox on Mac gets progressively slower

JavaScript's default exports are a footgun

Moving zeros to the end of an array in JavaScript

Logging hours to Jira's "Work log" in bulk

Initial setup

Actually logging

Pin exact dependency versions

`error.cause` needs to be logged manually to App Insights

`\d` in a regex isn't always equal to `[0-9]`

`response.json()` can throw an error in JavaScript

`error.stack` includes the error message in some JS environments

`yarn install` failing mysteriously on Node.js v18.18

Footnotes

Visual mnemonic for an array sorter's return values

Strict object validation is handy for data exploration

Adding type-safety to Node-Cache

Notes

YouTube's "Show transcript" tool is great for taking video notes

Bookmarklet to download still images from YouTube videos

Minified

Unminified

Legacy code is code written by other people

`Date` objects are nicer to work with than date strings

I read all 7 seven Harry Potter books in 33 days

Parsing data is nicer than only validating it

Example: Joi vs Zod

What about JSON.parse?

Example: userSchema

Footnotes

Auto-converting EPUB files to AZW3 instead of MOBI in Calibre

De-ACSM'ing and de-DRM'ing e-books for fun (but not profit)

Sending (duplicate) emails to email aliases can be tricky

What about `JSON.parse`?

Example: `userSchema`