DEV Community: ngnijland

How to trigger a GitHub action workflow in another repository

ngnijland — Wed, 07 Feb 2024 16:01:07 +0000

Do you need to trigger a GitHub action workflow from another workflow? This is possible! You can use the GitHub API to trigger a workflow from basically anywhere. Let's dive into how this works and think of some practical use cases where this could be handy.

In this blog post I'm going to trigger a GitHub action workflow from a workflow in another repository. I'll reference to these repository by "target repository" and "trigger repository".

The repository dispatch event

At the base of this is the "repository dispatch event". This is an event that can be triggered using the GitHub API and can be acted upon by listening to the repository_dispatch Webhook event payload.

Documentation about the GitHub API endpoint can be found here and documentation about triggering the workflow based on the event can be found here. This should be enough information to get you going. However, if you want a practical example, please read on!

Target action

This article is not about all the fancy stuff you can do with GitHub actions. This means that the target action will be an incredibly simple one that only serves to prove that the functionality is working.

According to the docs we need to use the repository_dispatch activity type and specify the type of the dispatch we want to listen to. Let's create the following action in the target repository:

name: Receive repository dispatch event

on:
  # Listen to a repository dispatch event by the name of `dispatch-event`
  repository_dispatch:
    types: [dispatch-event]

jobs:
  log:
    runs-on: ubuntu-latest
    steps:
      - name: Event received
        run: echo "Event received"

This action will start once it receives a repository dispatch message of the type dispatch-event. Then all it will do is log "Event received" to the shell, just to prove it works.

Trigger action

Next, we'll setup an action in the trigger repository that will be responsible for firing the repository dispatch event. This is done by sending a request to the [GitHub POST /repos/{owner}/{repo}/dispatches API endpoint])https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event). Let's use the following curl command to do this.

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/<OWNER>/<REPO>/dispatches \
  -d '{"event_type":"<EVENT-TYPE>"}'

There is a few things we need to replace to make the request work.

Personal access token

Replace <YOUR-TOKEN> with a personal access token. The access token needs to have full repo access and the account that is connected to the personal access token should at least have write access to the target repository. If either of these two things is not setup correctly the API will return Error: fatal: repository 'https://github.com/<OWNER>/<REPOSITORY>' not found.

Make sure to use a secret when using your personal access token in the GitHub action. This prevents leaking it.

Owner and repository

Replace <OWNER> and <REPO> with the target owner and the repository. In my case: https://api.github.com/repos/ngnijland/repository-dispatch-target-repo/dispatches.

Event type

Replace <EVENT-TYPE> with the name of the repository dispatch event that the target action will listen to. In this example: dispatch-event.

The trigger action

Now create an action in the trigger repository that executes the curl command. For our example this action looks like this:

name: Send repository dispatch event

on:
  workflow_dispatch:

jobs:
  trigger-event:
    runs-on: ubuntu-latest
    steps:
      - name: Fire event
        run: |
          curl -L \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.REPOSITORY_ACCESS_TOKEN }}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            https://api.github.com/repos/ngnijland/repository-dispatch-target-repo/dispatches \
            -d '{"event_type":"dispatch-event"}'

This action can be triggered manually. In its turn it will sent the repository dispatch request using the GitHub API.

Tip: You can use the Repository Dispatch action from the actions marketplace for better readability.

The result!

The workflow from the trigger repository triggers the workflow from the target repository. That's how it's done!

Passing context

To send extra information with the repository dispatch event you can send a payload in JSON format. Do this by adding the client_payload key to the data object and add a JSON object as value.

# ...
-d '{"event_type":"dispatch-event", "client_payload": {"message": "Hello from the trigger repository!"}}'

To read it in the target action use ${{ github.event.client_payload.<KEY> }}.

# ...
run: echo ${{ github.event.client_payload.message }}

Resulting in:

Note: If you want to send files you can upload the files as an artifact in the trigger repository, send ${{ github.run_id }} in the client_payload and then download the artifact in the target repository using the run-id option.

When to use this?

Now you know how it works you can unleash all your creativity to apply this to day to day tasks! Some ideas on where to apply this:

Open PR's in other repositories that update the dependency version of the dependency you just released using GitHub actions.
Upload e2e test reports as artifacts and download them in the target repository to deploy them to GitHub Pages (we do this at Polarsteps!).
Trigger a deployment of any sort of internal tool. Using this method you can move the source code of these tools to a separate repository. Preventing you from cluttering the main repository.
Don't restrict yourself to a trigger action. You can trigger an action from anywhere using the GitHub API. Did someone say something about a physical launch button?! ;)

Conclusion

I hope you learned how to use repository dispatch events to trigger GitHub workflow actions. Hopefully, it sparks some inspiration to start using it for day to day processes. Please let me know of any ways you will or already have implemented this via Twitter! I'm curious about all your implementations!

If you liked this article and want to read more make sure to check the my other articles. Feel free to contact me on Twitter with tips, feedback or questions!

Animating hamburger menu icons

ngnijland — Wed, 31 Jan 2024 16:43:39 +0000

Hamburger menu icons transforming into a close button are everywhere. Some are animated, some are not. One thing that always disrupts me is when the animation does not make any sense. When one of the three bars get animated away using opacity for example. Where does the bar go?! Welcome to this small rant on hamburger menu icon animations that includes a proper solution in the end.

What's out there?

There's three categories that I divide hamburger menu animations into:

1. No animation

No animation is better than a bad animation in my opinion.

2. Vanishing bars

When I see this animation I always think: "Where do the bars go?!"

3. Animations that could be possible in real life

These are the animations I love. Something is happening to the bars that could be reproduced in real life by playing with a camera angle an moving the bars for example. These animations will make me click the hamburger icon a couple of times to visualize what is happening.

My take

This is my take. It is one more implementation of an animation that could be possible in real life or that could be explained by the laws of physics.

Do you want to play around with it yourself? See the code below!

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Animated button icon</title>
    <style>
      :root {
        --bar-height: 10px;
        --bar-space: 12px;
        --transition-duration: 0.3s;
        --transition-step-duration: calc(var(--transition-duration) / 2);
      }

      html,
      body {
        height: 100%;
        margin: 0;
      }

      body {
        display: flex;
        align-items: center;
        justify-content: center;

        background-color: #82a7a6;
      }

      .button {
        position: relative;

        display: block;
        width: 100px;
        height: 100px;
        padding: 0;

        background-color: transparent;
        outline: none;
        border: none;

        cursor: pointer;
      }

      .button__bars {
        position: absolute;
        top: 50%;
        left: 50%;

        display: block;
        width: 74px;
        height: var(--bar-height);

        background-color: #fff;
        border-radius: var(--bar-height);

        transform: translate(-50%, -50%);
        transition: background 0s var(--transition-step-duration);

        &::before,
        &::after {
          position: absolute;
          left: 0;

          display: block;
          width: 100%;
          height: var(--bar-height);

          background-color: #fff;
          border-radius: var(--bar-height);
          content: "";

          transition-delay: var(--transition-step-duration), 0s;
          transition-duration: var(--transition-step-duration),
            var(--transition-step-duration);
        }

        &::before {
          top: calc(-1 * (var(--bar-height) + var(--bar-space)));

          transition-property: top, transform;
        }

        &::after {
          bottom: calc(-1 * (var(--bar-height) + var(--bar-space)));

          transition-property: bottom, transform;
        }
      }

      .button--open {
        .button__bars {
          background: none;

          &::before,
          &::after {
            transition-delay: 0s, var(--transition-step-duration);
          }

          &::before {
            top: 0;

            transform: rotate(45deg);
          }

          &::after {
            bottom: 0;

            transform: rotate(-45deg);
          }
        }
      }
    </style>
  </head>
  <body>
    <button id="button" class="button" type="button">
      <span class="button__bars"></span>
    </button>
    <script>
      const button = document.getElementById("button");

      button.addEventListener("click", () => {
        button.classList.toggle("button--open");
      });
    </script>
  </body>
</html>

Conclusion

Do you have more example of animated hamburger icons that do not make sense or that do make sense? Share them via Twitter! I know that sometimes devs do not have enough time to think about these kind of details or simply do not care about them. Take this blog post with a grain of salt! The most important part is the functionality anyway. However, sometimes it's just really nice to nitpick over these small and often unnoticable details.

If you liked this article and want to read more make sure to check the my other articles. Feel free to contact me on Twitter with tips, feedback or questions!

Iterators in JavaScript explained

ngnijland — Wed, 24 Jan 2024 15:16:05 +0000

Did you ever encounter a situation where a method or a library you were using returned an iterator (as typed in using TypeScript: IterableIterator)? Are you like me, early in my career, and tried to loop over iterators using .map(), .forEach(), .filter() or any other array method? Not being aware that this is not possible, all of a sudden you get a TypeError: iterator.map is not a function or a Property 'map' does not exist on type 'IterableIterator<string>'. thrown at you. And now you're thinking: "Why? Why can't I iterate over an iterator? What's going on?"

Let's find out.

What is an iterator?

According to mdn web docs: "In JavaScript an iterator is an object which defines a sequence and potentially a return value upon its termination. Specifically, an iterator is any object which implements the Iterator protocol by having a next() method that returns an object with two properties:"

The most important part of this description is that an iterator iterates over an object. Now try to picture what you're iterating over when you iterate over an object. Do you iterate over the keys, over the values, over values of values? That is exactly what you can establish by implementing the Iterator protocol into an object. Once an object has an Iterator protocol implemented the iterable protocol allows JavaScript objects to define or customize their iteration behavior, such as what values are looped over in a for...of statement.

Implement the Iterator protocol into an object

To implement the Iterator protocol into an object we first need an object:

const people = {
  0: {
    firstName: "Niek",
    lastName: "Nijland",
    age: 30,
  },
  1: {
    firstName: "Tim",
    lastName: "Cook",
    age: 63,
  },
};

To check if this object has an Iterator protocol implemented we can try to iterate over it using a for...of loop.

for (const person of people) {
  console.log(person);
}

// TypeError: people is not iterable

This results in a TypeError saying that people is not iterable.

Let's fix that by implementing the iterator function.

The iterator function

An iterator function should return a method named next() that on its turn returns an object with two properties:

value -> The value in this iteration sequence
done -> A boolean that that should be false when the iteration is not finished yet and true when the last value of the iteration is consumed.

In our case we want the individual person objects to be returned as value.

That translates to something like this:

function iterator() {
  let index = 0;

  return {
    next: () => {
      if (index > people.length - 1) {
        return {
          done: true,
          value: undefined,
        };
      }

      const person = this[index];

      index++;

      return {
        done: false,
        value: person,
      };
    },
  };
}

This raises two questions:

How does for...of know that it should execute this function?
Where does people.length come from? people is not an array after all..

To answer the first question: When JavaScript encounters a for...of loop it searches for the iterator function in the object's Symbol.iterator property. Let's add our iterator function to our people object.

const people = {
  // ...
  [Symbol.iterator]: function () {
    let index = 0;

    return {
      next: () => {
        if (index > people.length - 1) {
          return {
            done: true,
            value: undefined,
          };
        }

        const person = this[index];

        index++;

        return {
          done: false,
          value: person,
        };
      },
    };
  },
};

Running it now results in:

for (const person of people) {
  console.log(person);
}

// Output
// { firstName: 'Niek', lastName: 'Nijland', age: 30 }
// { firstName: 'Tim', lastName: 'Cook', age: 63 }
// undefined
// undefined
// undefined
// etc

An infinite loop!

This is where we answer the second question. people.length does not exist! That results in the done property never being set to true. Let's add it to our people object to finish the implementation of the Iterator protocol.

const people = {
  0: {
    firstName: "Niek",
    lastName: "Nijland",
    age: 30,
  },
  1: {
    firstName: "Tim",
    lastName: "Cook",
    age: 63,
  },
  length: 2,
  [Symbol.iterator]: function () {
    let index = 0;

    return {
      next: () => {
        if (index > people.length - 1) {
          return {
            done: true,
            value: undefined,
          };
        }

        const person = this[index];

        index++;

        return {
          done: false,
          value: person,
        };
      },
    };
  },
};

You could of course stop the iteration in numerous other ways. For example, by retrieving the length from Object.keys(people). How and when to stop the iteration is completely dependent on the implementation.

In this example we created a simplified implementation of the Array object. Does it ring a bell? How would you access an item in an array with index 1? Right: people[1]. How would you get the length of an array? people.length. Array's are objects in JavaScript! That's why we call it the Array object.

Running the for...of loop over the people object one last time results in:

for (const person of people) {
  console.log(person);
}

// Output:
// { firstName: 'Niek', lastName: 'Nijland', age: 30 }
// { firstName: 'Tim', lastName: 'Cook', age: 63 }

How does it work?

Let's say the for...of loop does not exist or you cannot use it for some reason. How do you iterate over the people object. Or phrased differently: What does for...of do to iterate over the people object?

First it initiates the iterator:

const iterator = people[Symbol.iterator]();

console.log(iterator);
// { next: [Function: next] }

Now it has the iterator as a constant. The next() method can be called to move to the next sequence in the iteration.

const iterator = people[Symbol.iterator]();
console.log(iterator.next());

/**
 * {
 *    done: false,
 *    value: { firstName: 'Niek', lastName: 'Nijland', age: 30 }
 * }
 */

As you can see this returns the iterator result object. The value can be accessed with .value and checking if the iteration is done by checking if done is true.

In this case done is false. That means next() can be called one more time.

// ...
console.log(iterator.next());

/**
 * {
 *    done: false,
 *    value: { firstName: 'Tim', lastName: 'Cook', age: 63 }
 * }
 */

Let's do it one more time to finish the iteration.

// ...
console.log(iterator.next());

/**
 * {
 *    done: true,
 *    value: undefined
 * }
 */

This is a bare bones representation of what happens when a for...of loop is called on an Iterator object.

Back to the intro example.. What was going on?

Why couldn't we loop over the iterator using array methods? Now that we now that an array is an object and we know what the structure is of such an object we can answer that question.

Let's say the iterator you were trying to loop over was our people object. We did not implement map, forEach or any other methods that an Array object has implemented. Trying to access people.map will result in TypeError: iterator.map is not a function since we did not implement that method.

You can use these methods on an Array object. Array is a type that is built-in into browsers. It has a built-in iterator protocol and built-in methods (e.g. map, forEach, etc). There are a lot more built-in types that already have default iteration behavior, like Map and Set. Now you know how it is possible to iterate over these types!

To give an example of a subset of browser API's that will provide you with an iterator you can check out the TypeScript source code.

Conclusion

I hope you learned the basics of iterators from this blog post. There's a lot more to iterators then the simple examples in this blog post. The next() method could optionally throw instead of return an iterator result for example or it could be implemented asynchronous using the async iterator and async iterable protocols. Those topics exceed the intentions of this blog post. I invite you to read these two MDN pages to learn more about it:

If you liked this article and want to read more make sure to check the my other articles. Feel free to contact me on Twitter with tips, feedback or questions!

Using FormData to process form input values

ngnijland — Wed, 17 Jan 2024 16:54:51 +0000

Before you reach out to a form library, I suggest to look at what browsers nowadays have to offer by default. In a lot of cases it will be overkill to include a form library that has implemented a ton of features that you're not going to use anyways. In this blog post I want to dive into the FormData instance.

What is it?

FormData is an instance that you can use to create a set of key/value pairs that works seamlessly together with other native browser methods, for example:

It can be used to directly send key/value pairs as body in POST requests via fetch or XMLHttpRequest.send().
It can be passed directly into URLSearchParams.

It is often used to retrieve and process data from form inputs.

Feed it with data

Either, you manually add data to it using its set or append methods, or you connect it to a form for it to automatically create it's key/value pairs based on the form.

Manually adding key/value pairs

To create a FormData instance from scratch you initialize it without passing any arguments. Then you use its append and/or set method to add data to the instance.

const userFormData = new FormData();

// Use set to create or overwrite a value for the key passed as the first argument
formData.set('name', name);
formData.set('age', age);

preferredFruits.forEach(fruit => {
  // Use append when a key can have multiple values
  formData.append('fruit', fruit);
});

You are responsible for managing the data and use it to cal these methods to feed the FormData instance.

Attach it to a form element

When you want the FormData instance to use data from a form element, you pass the form element as an argument to FormData.

<form id="user-form">
  <input name="name" type="text" />
  <input name="age" type="number" />
  <select name="preferred-fruits" multiple>
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
    <option value="grape">Grape</option>
  </select>
  <button>Submit</button>
</form>

<script>
  const form = document.getElementById("user-form");

  form.addEventListener("submit", () => {
    const userFormData = new FormData(form);

    // ...
  })

</script>

In React you use useRef to pass the form element, like so:

function UserForm() {
  const formRef = useRef<HTMLFormElement>(null);

  return (
    <form
      ref={formRef}
      onSubmit={(event) => {
        event.preventDefault();

        // We need to check for `formRef.current`, because it can be `undefined` according to TypeScript.
        if (!formRef.current) {
          return;
        }

        const userFormData = new FormData(formRef.current);

        // ...
      }}
    >
      <input name="name" type="text" />
      <input name="age" type="number" />
      <select name="preferred-fruits" multiple>
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
        <option value="grape">Grape</option>
      </select>
      <button>Submit</button>
    </form>
  );
}

Note: you can always add, change or remove data from the FormData instance after you initialise it by passing a form element as an argument.

Using the data

We have a FormData instance that contains all the data you need. Now we can start using it.

Specific value

To get and use the value of a specific key in the FormData instance you can use the get or getAll method.

/**
 * `get` returns the value associated to the key that is passed as an argument.
 * 
 * If the instance has more values for the key it return the first one.
 */
const name = userFormData.get("name");

/**
 * `getAll` returns an array of all the values associated to the key that is passed as an argument.
 */
const preferredFruit = userFormData.getAll('preferred-fruits');

// ...

Note: you could've seen this in action in my blog post about React's key attribute already. Read that blog post here.

Now you can use the value in any way you want.

If you just want to know if a specific key is present in the FormData instance you can use the has method.

if(userFormData.has('name')) {
  // ...
} else {
  // ...
}

Process all data

If you want to process the data as an iterator you can use the entries, keys and values method. These methods return an iterator that you can use to iterate over the FormData instance's data.

const keys = userFormData.keys();
const values = userFormData.values();
const entries = userFormData.entries();

// Now loop over them using the for..of statement
for(const key in keys /** or `values` or `entries` */) {
  // ...
}

Use it directly in other browser native methods

Now that you know how you can create, manipulate and use data in a FormData instance it time to look at applications that highlight why this instance is interesting to use. This is where it actually isolates away a lot of potentially complex code to get data from form inputs to a request that is send.

POST request

Let's assume that we want to send data from our form inputs to a POST endpoint. To realise that you have to do the following:

Create a form
Once a submit event is fired you need to initialise a FormData instance, passing the form element as an argument.
Manipulate the form data in any way you want.
Send the request

<form id="user-form">
  <input name="name" type="text" />
  <input name="age" type="number" />
  <select name="preferred-fruits" multiple>
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
    <option value="grape">Grape</option>
  </select>
  <button>Submit</button>
</form>

<script>
  const form = document.getElementById("user-form");

  form.addEventListener("submit", async () => {
    const userFormData = new FormData(form);

    // Edit `userFormData` in any way you like here

    const response = await fetch("https://your.api/api/post-endpoint", {
      method: "POST",
      // Add the `FormData` directly as the body for the request
      body: userFormData,
    });

    console.log(await response.json());
  });
</script>

Instead of worrying about trivial things, now you can focus on what matters for you. Editing the form data in any ways necessary.

Note: if you do not want to edit the form input data in any way you do not need to use JavaScript. You can simplify things even more by using the form element's method and action attributes.

GET request

Let's do the same thing, but with a GET request. A real world scenario here, could be a form that functions as a filter. For example, in a webshop where you can filter on color and size.

<form id="filter-form">
  <select name="color">
    <option value="red">Red</option>
    <!-- ... -->
  </select>
  <select name="size">
    <option value="s">Small</option>
    <!-- ... -->
  </select>
  <button>Submit</button>
</form>

<script>
  const form = document.getElementById("filter-form");

  form.addEventListener("submit", async () => {
    const filterFormData = new FormData(form);

    // Edit `filterFormData` in any way you like here

    // Pass the `FormData` instance directly into `URLSearchParams`
    const params = new URLSearchParams(filterFormData);

    // `params` resolves to `"color=red&size=s"`
    const response = await fetch(`https://your.api/api/get-endpoint?${params}`);

    console.log(await response.json());
  });
</script>

Again, all trivial things are isolated away and you can focus on the data.

Conclusion

I think it's always wise to stay as close to the browser as possible. The more abstractions between your code and the browser the clunkier, heavier and more complex it gets. I hope this blog post illustrates some use-cases where the browser already has some great API's ready for you to work with.

If you liked this article and want to read more make sure to check my other articles. Feel free to contact me on Twitter with tips, feedback or questions!

Why do we need to set a "key" prop in lists in React?

ngnijland — Wed, 10 Jan 2024 16:21:55 +0000

If you ever have rendered a list of items using a dynamic looping method in React you probably encountered either ESLint or a console error being thrown at you.

Is this error familiar to you? Let's find out why it's thrown and why React want us to add a "key" prop to our dynamic list items.

Why?

React uses the key prop to uniquely identify a component. Then it uses this information to decide what to do when the source list changes and a re-render is triggered.

As described in the React docs:

Keys tell React which array item each component corresponds to, so that it can match them up later. This becomes important if your array items can move (e.g. due to sorting), get inserted, or get deleted. A well-chosen key helps React infer what exactly has happened, and make the correct updates to the DOM tree.

Every time React encounters an unknown key it will (re-)create a component and the DOM.

I created a simple component that shows a list of countries with the options to add or remove a country.

const defaultCountries = [
  { name: "Argentina", capital: "Buenos Aires" },
  { name: "Belgium", capital: "Brussels" },
  { name: "The Netherlands", capital: "Amsterdam" },
  { name: "Brazil", capital: "Brasília" },
  { name: "Vietnam", capital: "Hanoi" },
];

function Countries() {
  const [countries, setCountries] =
    useState<{ name: string; capital: string }[]>(defaultCountries);

  return (
    <div className="center">
      <h1>Countries</h1>
      <ul>
        {countries.map((country) => (
          <Item
            name={country.name}
            capital={country.capital}
            onDelete={(name) => {
              setCountries((currentState) =>
                currentState.filter(
                  (currentCountry) => currentCountry.name !== name
                )
              );
            }}
          />
        ))}
      </ul>
      <form
        ref={formRef}
        onSubmit={(event) => {
          event.preventDefault();

          if (!formRef.current) {
            return;
          }

          const data = new FormData(formRef.current);

          const name = data.get("country");
          const capital = data.get("capital");

          if (typeof name !== "string" || typeof capital !== "string") {
            return;
          }

          setCountries((prev) => [...prev, { name, capital }]);

          formRef.current.reset();
          focusRef.current?.focus();
        }}
      >
        <input
          ref={focusRef}
          id="country"
          name="country"
          type="text"
          placeholder="Country"
        />
        <input id="capital" name="capital" type="text" placeholder="Capital" />
        <button className="button">Add</button>
      </form>
    </div>
  );
}

interface ItemProps {
  name: string;
  capital: string;
  onDelete: (name: string) => void;
}

export function Item({ name, capital, onDelete }: ItemProps) {
    return (
    <li className="item">
      <strong>{name}: </strong>
      {capital}
      <button
        className="button"
        type="button"
        onClick={() => {
          onDelete(name);
        }}
      >
        Remove
      </button>
    </li>
  );
}

Let's say we pass a random key value to the Item component on every render:

<Item
  key={Math.random()}
  // ...
/>

Let's look what happens in the Chrome inspector when we add or remove countries from the list.

The entire list, including the list items get re-created when a change is made to the countries list. Besides that this is sub-optimal, this can turn into the content flashing when the list items are more complex.

What should we pass to this "key" prop?

So, what should we pass into the "key" prop? We know that it should be a unique value, but where do we get this value?

The React docs give us two options:

Data from a database
Locally generated data (not generated on render!)

In our example this is easy. We add an id property to every item in our countries list and we make sure to increment from the highest id when we add a new country.

const defaultCountries = [
  { id: 1, name: "Argentina", capital: "Buenos Aires" },
  { id: 2, name: "Belgium", capital: "Brussels" },
  { id: 3, name: "The Netherlands", capital: "Amsterdam" },
  { id: 4, name: "Brazil", capital: "Brasília" },
  { id: 5, name: "Vietnam", capital: "Hanoi" },
];

function Countries() {
  // ...

  return (
    // ...
    <form
      onSubmit={(event) => {
        // ...

        setCountries((prev) => [
          ...prev,
          { id: prev[prev.length - 1].id + 1, name, capital },
        ]);

        // ...
      }}
    >
    </form>
  );
}

In a real world scenario where the countries data is retrieved from a backend you should discuss this with a backend engineer. They might require you to generate a unique id using the uuid NPM package for example. The above won't work in your scenario? You could always try to create some unique data by combining one or more properties into a unique value.

Note: React will use the array index when no key is passed to the component.

Now watch what happens to the list and list items in the inspector:

Only the list item that is interacted with will be created or removed from the DOM. Nice and easy optimization!

Note that all list item components are re-rendered on every change of the countries list. If you want to prevent this you can wrap the Item component in React.memo.

Use the array index

Although, it is not recommended by the React docs in some cases you could get away with using the array index to the key prop. To understand when, we should dive into what happens when we use the array index as key.

Let's remove the unique id again and use the array index for the key.

const defaultCountries = [
  { name: "Argentina", capital: "Buenos Aires" },
  { name: "Belgium", capital: "Brussels" },
  { name: "The Netherlands", capital: "Amsterdam" },
  { name: "Brazil", capital: "Brasília" },
  { name: "Vietnam", capital: "Hanoi" },
];

function Countries() {
  // ...

  return (
    // ...
    <ul>
      {countries.map((country, index) => (
        <Item
          key={index}
          // ...
        />
      ))}
    </ul>
    <form
      onSubmit={(event) => {
        // ...

        setCountries((prev) => [...prev, { name, capital }]);

        // ...
      }}
    >
    </form>
  );
}

Let's see what happens:

Exactly the same thing! Then why does React explicitly state that you should not use the array index as key? To show why, we need to add some state to the Item component.

export function Item({ name, capital, onDelete }: ItemProps) {
  const [isHighlighted, setIsHighlighted] = useState<boolean>(false);

  return (
    <li className="item">
      <div className={`country${isHighlighted ? " country--highlight" : ""}`}>
        <strong>{name}: </strong>
        {capital}
      </div>
      <button
        className="button"
        type="button"
        onClick={() => {
          setIsHighlighted((currentState) => !currentState);
        }}
      >
        Toggle highlight
      </button>
      <button
        className="button"
        type="button"
        onClick={() => {
          onDelete(name);
        }}
      >
        Remove
      </button>
    </li>
  );
}

Now, every country has a button that toggles a yellow background to the related list item when it is clicked. Now, the interesting part. Watch closely what happens when an item is deleted while a follow-up item is highlighted.

The highlight moves from The Netherlands to Brazil when Belgium is deleted. This is because we use the array index as keys. Deleting Belgium triggers the change of the value of the keys of all the following countries. Brazil will get the value that belonged to The Netherlands before.

React now compares the new keys to the previous render and identifies that the component with index 2 still exists. This means that for react the component with key value 2 is the same component as before the re-render. It will now update the component, but this time with different prop values (the values of Brazil). The Item component will be re-rendered and not re-created. The state value will remain the same, which means that the component keeps the yellow background.

In this example it would be better to explicitly use a value that you know will be unique to the piece of data you want to show.

Bugs like this are hard to spot and can be hard to debug. This is why the React docs recommend using an id as the value for keys.

Is there a valid use case for using the array index?

There are use cases that exploit React's behaviour by using the array index as key.

If the list items:

are pure components and...
do not have any local state that is kept between renders

you could use the array index to improve performance for certain actions.

One use case that will benefit from this is when you want to replace all or a great part of the items in the list. Instead of React removing these components and creating the new components React will now re-render the affected components instead. Especially when you items are more complex components this could visually improve the performance of this part of your application.

Do I recommend this? It depends.. If a smooth experience is incredibly important to you, I think this is valid. However, I recommend leaving a comment behind explaining why you use the array index and how it improves performance. This prevents confusion when the next engineer passes this piece of code.

Conclusion

Now we know why React wants us to set a key when rendering dynamic lists of data and what to use as a value for such key.

If you want to play around with the code yourself I created a small repository with a working example. By default it uses the array index as key, so you can experience the behavior yourself. Check the repository here.

If you liked this article and want to read more make sure to check the my other articles. Feel free to contact me on Twitter with tips, feedback or questions!

Make a responsive carousel with just CSS

ngnijland — Wed, 03 Jan 2024 09:48:37 +0000

Nowadays, with modern CSS it's incredibly easy to create a carousel. Where you had to rely on JavaScript to calculate the exact position of you carousel items on your screen, now all you have to do is create a container with overflowing content and change the scroll mode.

What is a carousel?

A carousels is an interactive slider that showcases multiple items. These items can be anything. A common use case is images or card components. A carousel lets you show a selection of these items on screen. Through interacting with it, it will show other items that were hidden before.

I personally needed to implement it for the orientation content of our Polarsteps guides:

See it live in action here (scroll a bit down and see the carousel in the "Visiting the Barossa Valley for..." section in action too)!

Other potential use cases of image carousels are:

Related items in a webshop
Rotating through news items
Image slider for product images

JavaScript implementation

To implement an image carousel up until just a couple of years ago you needed JavaScript. An implementation would include absolute positioning items inside a container using css. Then calculating the carousel wrapper size and item sizes in realtime using JavaScript. And then add interactions by either updating the left or right values or updating the transform value using JavaScript again. This leaves you with a very basic implementation of the carousel. Did you wish for any form of swipe interactions on a phone you'd probably better of by reaching to an external library.

So, how does this work with CSS only?

I was happy to find out that this is much easier nowadays. By using CSS scroll snap you wont need any external library or fancy JavaScript code to reproduce most of the carousel functionality.

Start by creating a HTML list with items that will function as your carousel wrapper and carousel items:

<ul class="list">
  <li class="item"><div class="content">Item 1</div></li>
  <li class="item"><div class="content">Item 2</div></li>
  <li class="item"><div class="content">Item 3</div></li>
  <li class="item"><div class="content">Item 4</div></li>
  <li class="item"><div class="content">Item 5</div></li>
</ul>

Then for the core behaviour:

apply scroll-snap-type to the wrapper with a value of mandatory for the axis you want the scroll snapping to happen.
apply scroll-snap-align to the items with a value of center to make sure the browser will align the active item to the center of your wrapper.

After including some styles to add spacing between and around the carousel and its items it will result in something like this:

.list {
  display: flex;
  gap: 8px;
  padding: 16px;

  list-style: none;
  overflow-x: scroll;
  scroll-snap-type: x mandatory;
}

.item {
  flex-shrink: 0;
  width: 80%;
  height: 90vh;

  background-color: #FFF;

  scroll-snap-align: center;
}

.content {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;

  font-family: sans-serif;
  font-size: 64px;
  font-weight: bold;
}

The result in the browser:

The coolest part is that this works using swipe guestures too. Make sure to test this in a browser on your mobile phone to feel how natural it feels!

Extras

Now that we have the core behaviour implemented in such a short amount of time we can focus and put our time in adding functionality according to our requirements!

Hide the scrollbar

Even though on most browsers nowadays scrollbars are not as intrusive as they used to be, you might want to hide them for a carousal. We can do that by applying a few lines of CSS to our list element:

.list {
  /* ... */

  /* Hide scrollbar in Firefox */
  scrollbar-width: none;

  /* Hide scrollbar in IE and Edge */
  -ms-overflow-style: none;
}

/* Hide scrollbar in webkit */
.list::-webkit-scrollbar {
  display: none;
}

Now the scrollbar will be hidden:

Arrow buttons

For a better user experience you can add arrow buttons to your carousel. They will help by giving an indication to your user that there is more content to see. This is were we have to cheat a bit, because we'll need a tiny bit of JavaScript.

First add the buttons to the HTML and style them. I chose to keep it extremely simple for the purposes of this blog post.

<div class="list-wrapper">
  <ul class="list">
    <li class="item"><div class="content">Item 1</div></li>
    <li class="item"><div class="content">Item 2</div></li>
    <li class="item"><div class="content">Item 3</div></li>
    <li class="item"><div class="content">Item 4</div></li>
    <li class="item"><div class="content">Item 5</div></li>
  </ul>
  <button class="button button--previous" type="button">➜</button>
  <button class="button button--next" type="button">➜</button>
</div>

.list-wrapper {
  position: relative;
}

.button {
  position: absolute;
  top: 50%;

  width: 3rem;
  height: 3rem;

  transform: translateY(-50%);
}

.button--previous {
  left: 1.5rem;

  transform: rotate(180deg);
}

.button--next {
  right: 1.5rem;
}

Now we have two simple arrow buttons floating on the left and right side of our carousel.

The next thing we want to do is to execute some JavaScript when these buttons are clicked.

<div class="list-wrapper">
  <ul class="list">
    <li class="item"><div class="content">Item 1</div></li>
    <li class="item"><div class="content">Item 2</div></li>
    <li class="item"><div class="content">Item 3</div></li>
    <li class="item"><div class="content">Item 4</div></li>
    <li class="item"><div class="content">Item 5</div></li>
  </ul>
  <!-- We're calling `handleClick` with a direction argument when the buttons are clicked -->
  <button onclick="handleClick('previous')" class="button button--previous" type="button">➜</button>
  <button onclick="handleClick('next')" class="button button--next" type="button">➜</button>
</div>
<script>
  const list = document.querySelector(".list");

  // We want to know the width of one of the items. We'll use this to decide how many pixels we want our carousel to scroll.
  const item = document.querySelector(".item");
  const itemWidth = item.offsetWidth;

  function handleClick(direction) {
    // Based on the direction we call `scrollBy` with the item width we got earlier
    if(direction === "previous") {
      list.scrollBy({ left: -itemWidth, behavior: "smooth" });
    } else {
      list.scrollBy({ left: itemWidth, behavior: "smooth" });
    }
  }
</script>

There's a few things going on here.

We want to decide by how many pixels we want the scroll container to be scrolled. In this example we do this by getting the width of the first item and using that number as the amount of pixels to scroll to. You can also use a static number here. In the Polarsteps implementation that I linked at the start of this article we use a static number (150). We found that it worked for all screen sizes, so no need to add extra functionality to get item sizes every time the screen or the scroll container changes size.

When calling scrollBy we pass "smooth" as value to the "behaviour" option. This tells the browser to smoothly scroll the amount of pixels we pass to the left option. Then scroll-snap takes over and makes sure the item is aligned nicely in the center.

The result:

More ideas

Talking about more functionality. Here is a list of ideas that you could add to this carousel:

Automatic rotation
Dots or thumbnails to scroll to using scrollIntoView
Hide arrows on mobile devices
Hide or disable arrows when there is no more items to scroll to
Add shadows or other styling to indicate the start and end of the carousel

Conclusion

That's it! That's all that's needed to create an image carousel with basic behaviour nowadays! Ofcourse, there is a lot more functionality that you could implement (see the ideas section), but I think it's incredible that we can achieve this nowadays in just a couple lines of HTML, CSS and JavaScript.

If you want to see the Polarsteps image carousel implementation live in action make sure to check it out here.

If you liked this article and want to read more make sure to check the my other articles. Feel free to contact me on Twitter @ngnijland with tips, feedback or questions!

How to write a Diagnostics TypeScript Language Service Plugin?

ngnijland — Tue, 21 Dec 2021 07:04:40 +0000

Do you recognize the fact that those beautiful TODO or FIXME comments you add to your code are forgotten and left as is until eternity? At our companies innovation day, we wanted to write a TypeScript compiler plugin that makes your build fail when a condition you provide in your TODO comments evaluates to true. Unfortunately, we came to the conclusion that TypeScript does not allow us to write a compiler plugin. It does however allow us to write a Language Service Plugin.

A TypeScript Language Service Plugin can be used to change the editing experience for TypeScript users. It doesn't interfere with the compiler. This means it can only guide or help, not enforce. This article will describe how to create a diagnostics plugin using our Todo Or Die use case as an example.

Just here for the code? Check out this repository.

Setup

First, you need a simple TypeScript project with a factory function and a decorator that we should return to our factory function.

Follow the steps Setup and Initialization and Decorator Creation in the Writing a Language Service Plugin article on the TypeScript wiki.

You'll end up with the following code:

function init(modules: { typescript: typeof import("typescript/lib/tsserverlibrary") }) {
  const ts = modules.typescript;

  function create(info: ts.server.PluginCreateInfo) {
    const proxy: ts.LanguageService = Object.create(null);

    for (let k of Object.keys(info.languageService) as Array<keyof ts.LanguageService>) {
      const x = info.languageService[k]!;
      // @ts-expect-error - JS runtime trickery which is tricky to type tersely
      proxy[k] = (...args: Array<{}>) => x.apply(info.languageService, args);
    }

    return proxy;
  }

  return { create };
}

export = init;

This is now just a pass-through plugin, but it enables us to start adding custom behavior for our comments.

Custom behavior

After setting up this decorator we are now able to overwrite TypeScript's Language Service functions. To make a change in the diagnostics service TypeScript defines three types of diagnostics.

Syntactic
Semantic
Suggestion

Each of them has a corresponding function that we can overwrite.

Deciding what function to overwrite

In the type files TypeScript gives us a detailed explanation of when to use these functions. All three will pass the current file name as an argument and return and require you to return an array of diagnostics. You need to shape the diagnostics depending on the type. Choose the one you want to overwrite.

Syntactic

getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[]

"Gets errors indicating invalid syntax in a file.

In English, "this cdeo have, erorrs" is syntactically invalid because it has typos, grammatical errors, and misplaced punctuation. Likewise, examples of syntax errors in TypeScript are missing parentheses in an if statement, mismatched curly braces, and using a reserved keyword as a variable name.

These diagnostics are inexpensive to compute and don't require knowledge of other files. Note that a non-empty result increases the likelihood of false positives from getSemanticDiagnostics.

While these represent the majority of syntax-related diagnostics, there are some that require the type system, which will be present in getSemanticDiagnostics."

Semantic

getSemanticDiagnostics(fileName: string): Diagnostic[]

Gets warnings or errors indicating type system issues in a given file.
Requesting semantic diagnostics may start up the type system and run deferred work, so the first call may take longer than subsequent calls.

Unlike the other get*Diagnostics functions, these diagnostics can potentially not include a reference to a source file. Specifically, the first time this is called, it will return global diagnostics with no associated location.

To contrast the differences between semantic and syntactic diagnostics, consider the sentence: "The sun is green." is syntactically correct; those are real English words with correct sentence structure. However, it is semantically invalid, because it is not true."

Suggestion

getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[]

"Gets suggestion diagnostics for a specific file. These diagnostics tend to proactively suggest refactors, as opposed to diagnostics that indicate potentially incorrect runtime behavior."

Overwrite the function

We can now use the proxy we set up to overwrite one of the above functions. I'm going to overwrite getSemanticDiagnostics, but make sure to choose the function that matches best what you want to achieve.

getSemanticDiagnostics gives us the name of the current file our user works in as an argument and it expects us to return a list of ts.Diagnostic.

This looks something like this:

proxy.getSemanticDiagnostics = (filename) => {
  return [];
}

Now the first thing we want to do is make sure to return other diagnostics that are already logged by TypeScript itself or another Language Service plugin. We can use info.languageService.getSemanticDiagnostics to do this.

proxy.getSemanticDiagnostics = (filename) => {
  const prior = languageService.getSemanticDiagnostics(filename);

  return [...prior];
}

Finally, we can add our own logic to return diagnostics. First, we need to get the contents of the file based on the filename argument. For this, we can use info.languageService.getProgram()?.getSourceFile(filename). Since the result of this function can be undefined we make sure to catch that case and return prior instead.

proxy.getSemanticDiagnostics = (filename) => {
  const prior = info.languageService.getSemanticDiagnostics(filename);
  const doc = info.languageService.getProgram()?.getSourceFile(filename);

  if (!doc) {
    return prior;
  }

  return [...prior];
}

After that, we can analyze the file and generate diagnostics based on it. In our case, we want to check every line of the file for to-do or die statements. To make it as simple as possible for this example, we'll just look for any lines that start with // TODO: and create a diagnostic for each of them.

The type of ts.Diagnostic is:

enum DiagnosticCategory {
  Warning = 0,
  Error = 1,
  Suggestion = 2,
  Message = 3
}

interface DiagnosticMessageChain {
  messageText: string;
  category: DiagnosticCategory;
  code: number;
  next?: DiagnosticMessageChain[];
}

interface Diagnostic {
  category: DiagnosticCategory;
  code: number;
  file: SourceFile | undefined;
  start: number | undefined; // Index of `doc` to start error from
  length: number | undefined;
  messageText: string | DiagnosticMessageChain;
}

Use this information to gather all necessary data to be able to put together a diagnostic. In our case, we want to keep track of the line number and the line itself including the TODO comment.

// Context
import { DiagnosticCategory } from "typescript";
// Context

proxy.getSemanticDiagnostics = (filename) => {
  const prior = info.languageService.getSemanticDiagnostics(filename);
  const doc = info.languageService.getProgram()?.getSourceFile(filename);

  if (!doc) {
    return prior;
  }

  return [
    ...prior,
    ...doc.text
      .split("\n")
      .reduce<[string, number]][]>((acc, line, index) => {
        if (line.trim().startsWith("// TODO:")) {
          return [...acc, [line, index]];
        }

        return acc;
      }, [])
      .map(([line, lineNumber]) => ({
        file: doc,
        start: doc.getPositionOfLineAndCharacter(lineNumber, 0),
        length: line.length,
        messageText: "This TODO comment should be fixed!",
        category: DiagnosticCategory.Error,
        source: "Your plugin name",
        code: 666
      }))
  ];
}

This code will mark full lines that start with // TODO: and shows the "This TODO commend should be fixed!" message in the details of the error.

End result

Now combine the setup code snippet with the mutating proxy behavior and you've got yourself a working diagnostics plugin!

import { DiagnosticCategory } from "typescript";

function init(modules: { typescript: typeof import("typescript/lib/tsserverlibrary") }) {
  const ts = modules.typescript;

  function create(info: ts.server.PluginCreateInfo) {
    const proxy: ts.LanguageService = Object.create(null);

    for (let k of Object.keys(info.languageService) as Array<keyof ts.LanguageService>) {
      const x = info.languageService[k]!;
      // @ts-expect-error - JS runtime trickery which is tricky to type tersely
      proxy[k] = (...args: Array<{}>) => x.apply(info.languageService, args);
    }

    proxy.getSemanticDiagnostics = (filename) => {
      const prior = info.languageService.getSemanticDiagnostics(filename);
      const doc = info.languageService.getProgram()?.getSourceFile(filename);

      if (!doc) {
        return prior;
      }

      return [
        ...prior,
        ...doc.text
          .split("\n")
          .reduce<[string, number][]>((acc, line, index) => {
            if (line.trim().startsWith("// TODO:")) {
              return [...acc, [line, index]];
            }

            return acc;
          }, [])
          .map(([line, lineNumber]) => ({
            file: doc,
            start: doc.getPositionOfLineAndCharacter(lineNumber, 0),
            length: line.length,
            messageText: "This TODO comment should be fixed!",
            category: DiagnosticCategory.Error,
            source: "Your plugin name",
            code: 666
          }))
      ];
    }

    return proxy;
  }

  return { create };
}

export = init;

Testing locally

Add at least the following to your package.json.

{
  "name": "your-plugin-name",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc -p .",
  },
  "dependencies": {
    "typescript": "^4.5.4"
  }
}

Install dependencies.

npm install

Build plugin.

npm run build

Setup link.

npm link

Link plugin in another repository.

cd ../path-to-repository
npm link "your-plugin-name"

Add plugin to tsconfig in a TypeScript project.

{
  "plugins": [
    { "name": "your-plugin-name" }
  ]
}

Restart your editor.
Check any TODO comments in your repository.

Note: If you're using Visual Studio Code, you'll have to run the "TypeScript: Select TypeScript Version" command and choose "Use Workspace Version", or click the version number next to "TypeScript" in the lower-right corner. Otherwise, VS Code will not be able to find your plugin.

Release the plugin

To release the plugin you need to refer to the file containing the above code in the package.json file using the main key. E.g. { "main": "dist/index.js" }. Now publish your plugin to npm and install it in another project!

Conclusion

Thanks for reading this article! Check out a boilerplate plugin in this repository. If you're interested in how we applied it in our to-do or die plugin you can find it at https://github.com/ngnijland/typescript-todo-or-die-plugin.

How to highlight countries with Mapbox

ngnijland — Mon, 21 Dec 2020 08:11:18 +0000

I'm working on a trips section on my personal website. To visualize the countries I have visited, I wanted to show a map and highlight every country I visited. Since this was not a straightforward task and it took me longer than expected I thought I would share how this works.

Just here for the code? Checkout this repository.

Setup Mapbox

First, we want a running instance of Mapbox. I choose to use Mapbox GL JS as I wanted a smooth experience for future animations and transitions on the map of my personal website. Mapbox GL JS is a JavaScript library that uses WebGL to promise this smooth experience.

Include sources

To render a Mapbox map you need to include the Mapbox GL JS library and styles in your code. You can either add it using Mapbox's CDN with a script and link tag or use a module bundler like npm or yarn.

To be able to setup up a bare minimum as an example I chose to use Mapbox's CDN. It is done by adding the following lines of code to the <head> of your HTML file:

<head>
  <!-- ... -->
  <script src='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.js'></script>
  <link href='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.css' rel='stylesheet' />
</head>

If you want to use a module bundler checkout their documentation.

Access token

To use a Mapbox map you need an access token. To get one, you need to create a Mapbox account (https://account.mapbox.com/auth/signup/) and retrieve an access token from your account page (https://account.mapbox.com/). Once you have your access token it is time to render a map on your page!

Render map

Mapbox needs an element to render its map in. Let's add one:

<div id="map"></div>

To make it fill the entire page add the following CSS to the <head> of your HTML file:

html,
body,
#map {
  height: 100%;
  margin: 0;
}

Now hand Mapbox your access token and initialize a new Map instance by adding the following script tag to the <body> of your HTML file:

<script>
  mapboxgl.accessToken = '<YOUR ACCESS TOKEN HERE>';

  var map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [5, 46],
    zoom: 3
  });
</script>

We now have a fully working Mapbox map running in our browser!

The complete code to achieve this:

<!DOCTYPE html>
<html lang='en'>
<head>
  <meta charset='UTF-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Highlight countries in mapbox</title>
  <script src='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.js'></script>
  <link href='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.css' rel='stylesheet' />
  <style>
    html,
    body,
    #map {
      height: 100%;
      margin: 0;
    }
  </style>
</head>
<body>
  <div id='map'></div>

  <script>
    mapboxgl.accessToken = '<YOUR ACCESS TOKEN HERE>';

    var map = new mapboxgl.Map({
      container: 'map',
      style: 'mapbox://styles/mapbox/streets-v11',
      center: [5, 46],
      zoom: 3
    });
  </script>
</body>
</html>

Highlight countries

Now we have a map, the next step is to highlight individual countries.

Tilesets

Mapbox works with layers where you can display tilesets. These tilesets consist of vectors that render on a specific place on the map. You can create your own tileset or use existing ones.

We will use this countries tileset supplied by Mapbox.

Add a layer

To render this tileset on top of our map we have to add a layer to our map. We can do this on the callback of the Map's load event.

map.on('load', function() {
  map.addLayer();
});

Now we add a config which will add the countries tileset to this layer:

map.on('load', function() {
  map.addLayer(
    {
      id: 'country-boundaries',
      source: {
        type: 'vector',
        url: 'mapbox://mapbox.country-boundaries-v1',
      },
      'source-layer': 'country_boundaries',
      type: 'fill',
      paint: {
        'fill-color': '#d2361e',
        'fill-opacity': 0.4,
      },
    },
    'country-label'
  );
});

After the tileset config, we add 'country-label' to make sure the country names render on top of the country tileset.

In the paint section of the config, you can choose the color and opacity in which countries should highlight. In this case #d2361e with an opacity of 0.4.

This results in all countries being highlighted:

Filter

Mapbox's country tileset identify countries with ISO 3166-1 country codes. You can add a filter to the country-boundaries layer and use these country codes to highlight specific countries. This should also be done in the Map's load event:

map.setFilter('country-boundaries', [
  "in",
  "iso_3166_1_alpha_3",
  'NLD',
  'ITA'
]);

This will highlight The Netherlands and Italy.

Now we achieved what we wanted! Check out all the code needed here:

<!DOCTYPE html>
<html lang='en'>
<head>
  <meta charset='UTF-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Highlight countries in mapbox</title>
  <script src='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.js'></script>
  <link href='https://api.mapbox.com/mapbox-gl-js/v2.0.0/mapbox-gl.css' rel='stylesheet' />
  <style>
    html,
    body,
    #map {
      height: 100%;
      margin: 0;
    }
  </style>
</head>
<body>
  <div id='map'></div>

  <script>
    mapboxgl.accessToken = '<YOUR ACCESS TOKEN HERE>';

    var map = new mapboxgl.Map({
      container: 'map',
      style: 'mapbox://styles/mapbox/streets-v11',
      center: [5, 46],
      zoom: 3
    });

    map.on('load', function() {
      map.addLayer(
        {
          id: 'country-boundaries',
          source: {
            type: 'vector',
            url: 'mapbox://mapbox.country-boundaries-v1',
          },
          'source-layer': 'country_boundaries',
          type: 'fill',
          paint: {
            'fill-color': '#d2361e',
            'fill-opacity': 0.4,
          },
        },
        'country-label'
      );

      map.setFilter('country-boundaries', [
        "in",
        "iso_3166_1_alpha_3",
        'NLD',
        'ITA'
      ]);
    });
  </script>
</body>
</html>

Conclusion

Thanks for reading this article! Check out all the code needed in this repository. If you're interested in how I applied it on my website you can find it at https://nieknijland.nl/trips.

Do you like this article? Maybe you'll like these as well:

Let's get in contact! Comment below on this article or follow me on Twitter @ngnijland.

Run asynchronous tasks in batches in NodeJS

ngnijland — Sun, 29 Nov 2020 18:12:01 +0000

Say you have a large list of items and you want to run an asynchronous task for every one of them. You can run these tasks one at a time, in parallel or in batches. In this blog post, I try to explain one way of how to run asynchronous tasks in batches.

Task

To run tasks in batches we need a task. So let's create a task that creates a Promise and waits between 0 and 5 seconds to solve it.

function task() {
  return new Promise((resolve) => {
    setTimeout(resolve, Math.floor(Math.random() * 5000 + 1));
  });
}

Run in parallel

Now we need a function which we can feed a list of items and run the task we just created for every item:

function executeTasksConcurrently(list) {
  for (const item of list) {
    task();
  }
}

When we feed this function a list of numbers it will run the task() function for each item in parallel.

To show in which order tasks run and finish we can add some console.log statements. Check the following code and console output.

Code:

function task(item) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`End task: ${item}`);
      resolve();
    }, Math.floor(Math.random() * 5000 + 1));
  });
}

const list = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

async function executeTasksConcurrently(list) {
  for (const item of list) {
    console.log(`Start task: ${item}`);
    task(item);
  }
}

executeTasksConcurrently(list);

Console output:

$ yarn start
Start task: 1
Start task: 2
Start task: 3
Start task: 4
Start task: 5
Start task: 6
Start task: 7
Start task: 8
Start task: 9
Start task: 10
End task: 7
End task: 9
End task: 6
End task: 2
End task: 3
End task: 8
End task: 5
End task: 10
End task: 1
End task: 4
✨  Done in 5.12s.

Run in batches

To run tasks in batches we first need to keep track of the currently active tasks. This list should be updated when starting a task and when a task is finished.

async function executeTasksConcurrently(list) {
  let activeTasks = [];

  for (const item of list) {
    console.log(`Start task: ${item}`);
    const activeTask = task()
      .then(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      })
      .catch(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      });
    activeTasks.push(activeTask);
  }
}

Now we have to decide how many tasks we want to run concurrently. In this example, we will allow three tasks to run concurrently. Then we need to force our for loop to wait until a task is finished before starting a new task when the amount of currently active tasks matches this limit. Since our activeTasks list is an array of promises we can use Promise.race to check which task finishes first.

async function executeTasksConcurrently(
  list,
  concurrencyLimit = 3
) {
  let activeTasks = [];

  for (const item of list) {
    if (activeTasks.length >= concurrencyLimit) {
      await Promise.race(activeTasks);
    }

    console.log(`Start task: ${item}`);
    const activeTask = task()
      .then(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      })
      .catch(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      });
    activeTasks.push(activeTask);
  }
}

Check out the complete code and console output when we run the script now:

Code:

function task() {
  return new Promise((resolve) => {
    setTimeout(resolve, Math.floor(Math.random() * 5000 + 1));
  });
}

const list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

async function executeTasksConcurrently(
  list,
  concurrencyLimit: number = 3
) {
  let activeTasks = [];

  for (const item of list) {
    if (activeTasks.length >= concurrencyLimit) {
      await Promise.race(activeTasks);
    }

    console.log(`Start task: ${item}`);
    const activeTask = task()
      .then(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      })
      .catch(() => {
        activeTasks.splice(activeTasks.indexOf(activeTask), 1);
        console.log(`End task: ${item}`);
      });
    activeTasks.push(activeTask);
  }
}

executeTasksConcurrently(list);

Console output:

$ yarn start
Start task: 1
Start task: 2
Start task: 3
End task: 3
Start task: 4
End task: 2
Start task: 5
End task: 1
Start task: 6
End task: 4
Start task: 7
End task: 5
Start task: 8
End task: 8
Start task: 9
End task: 6
Start task: 10
End task: 10
End task: 7
End task: 9
✨  Done in 11.27s.

Conclusion

Running tasks in batches can help to prevent an overload of your resources and is fairly simple to implement. If you don't want to maintain or write this code yourself you can use third-party libraries that have implemented this pattern. For example Supercharge's Promise Pool.

If you want to run this script yourself you can find the code on GitHub.

If you have any questions or feedback feel free to comment or contact me on Twitter!

Use multiple versions of an npm package at the same time

ngnijland — Fri, 27 Nov 2020 06:45:29 +0000

Sometimes the API of an npm package changes. And sometimes the package is not backward compatible. In big projects, it is sometimes hard to refactor all the code concerned with a new API of an npm package you just updated. You probably want to be able to refactor this code step by step.

Aliases

With npm or yarn, you can install a package under a custom alias. This enables you to install multiple versions of a package in the same project.

Read the documentation on aliasing with npm here and yarn here.

How to use?

To install a package under an aliased name run:

npm install <alias>@npm:<name>

yarn add <alias>@npm:<name>

When you want to install a specific version of the package append the command with @<version>.

Using multiple versions of the same package

So for example, if you want to use multiple versions of the react-helmet package run:

npm install react-helmet-old@npm:react-helmet@5.2.1
npm install react-helmet@npm:react-helmet

yarn add react-helmet-old@npm:react-helmet@5.2.1
yarn add react-helmet@npm:react-helmet

Npm or yarn will now add two folders to your node_modules folder, e.g. react-helmet and react-helmet-old, and lets you import from react-helmet-old and react-helmet in your project. Now you can start refactoring step by step.

Sidenote

Not all packages support the usage of multiple versions side by side. For example, we tried to install two versions of react-dnd for which you need to use a provider component which was changed in the newer version. The two providers collided when used together so we were forced to do the whole refactor at once.

Conclusion

Aliases are a convenient way to upgrade a package gradually. Although we couldn't use it in our specific use case maybe there are people out there who can!