DEV Community: iO

Storyblok live editing with Next.js App Router and React Server Components

iO — Tue, 04 Jun 2024 00:00:00 +0000

The problem

When working with Storyblok there are two ways to set up your Next.js app if you use the app router. The first way is to wrap your entire app in a provider which then takes care of updating the app when you edit anything in the preview environment of Storyblok, thus giving you live editing. Live editing is a cool feature because an editor can directly see the changes they made without constantly saving the page.

The second approach keeps everything server-side. This is nice because we can then leverage the full power of server components. But this approach comes with a big limitation... you lose the live editing support and the editor can only see their changes after they've hit the save button.

Or is there a way...

I found this Gist from someone who stumbled across the same issue and solved it with a clever solution. I expanded on their solution and replaced their database (@vercel/kv) with something free and local. Let's dive in on how I did it!

The solution

When you are in the live editing environment of Storyblok, they add a class to the browser's window object called StoryblokBridge. This bridge allows you to listen to live editing events happening with on():

const sbBridge = new window.StoryblokBridge(options)

sbBridge.on(['input', 'published', 'change '], (event) => {
  const story = event.story
  // ...
})

The event returned contains the updated story with the live editing data the user entered. Awesome! We can use this live story and save it somewhere, then revalidate the page using Next.js' revalidatePath() API. Let's see how:

Let's first tackle the "save it somewhere" part of the solution. I used node-cache for this.

Create an instrumention.ts file in the root or src folder of your project:

import type NodeCache from 'node-cache'

export async function register() {
  const NodeCache = (await import('node-cache')).default
  const config = {
    stdTTL: 100,
  }

  global.storyblokCache = new NodeCache(config)
}

Add this to next.config:

 experimental: {
  instrumentationHook: true,
 },

This setup makes sure the cache won't be reset with each request, only on server startup.

Next, let's take a look at how we get the live editing data from Storyblok and save it in this cache. For this we first need to create a custom Storyblok bridge:

export const registerStoryblokBridge = ({ onInput }) => {
  const isServer = typeof window === 'undefined'
  const isBridgeLoaded = !isServer && typeof window.storyblokRegisterEvent !== 'undefined'

  if (!isBridgeLoaded) {
    return
  }

  window.storyblokRegisterEvent(() => {
    const sbBridge = new window.StoryblokBridge()
    sbBridge.on(['input'], (event) => {
      if (!event?.story) return

      onInput(event.story)
    })
  })
}

This function listens to live editing events, as we found out above, and makes a callback with the story containing the latest live editing data.

We then use this function in a client component

"use client";

import { previewUpdateAction } from "@/actions/previewUpdateAction";
import { registerStoryblokBridge } from "@/utils/storyblok";
import { useEffect, startTransition } from "react";

export const StoryblokPreviewSyncer = ({ pathToRevalidate }) => {
  function handleInput(story) {
    startTransition(() =>
      previewUpdateAction({
        story,
        pathToRevalidate,
      })
    );
  }

  useEffect(() => {
    registerStoryblokBridge({
      onInput: handleInput,
    );
  }, []);

  return null;
};

This client component makes sure the window event is fired with useEffect. The handleInput function uses React's startTransition to call a Next.js Server Action containing the latest data. Let's find out what this server action looks like.

'use server'

import { revalidatePath } from 'next/cache'
import { ISbStoryData } from '@storyblok/react'

export async function previewUpdateAction({ story, pathToRevalidate }) {
  if (!story) {
    console.error('No story provided')
    return
  }

  try {
    global.storyblokCache.set(story.slug, JSON.stringify(story))

    if (pathToRevalidate) {
      revalidatePath(pathToRevalidate)
    }
  } catch (error) {
    console.log(error)
  }
}

This function takes the story with the live editing data and saves it to our cache. It then calls revalidatePath to make sure Next.js knows it needs to update the page.

We now only need one more piece to solve the puzzle and that is the function that takes care of fetching the story:

export const getStoryblokData = async (slug) => {
  const storyblokApi = getStoryblokApi()

  try {
    const story = global.storyblokCache?.get(slug)

    if (!story) {
      const result = await storyblokApi.get(`cdn/stories/${slug}`, { version: 'draft' })

      return result.data.story
    }

    return JSON.parse(story)
  } catch (e) {
    console.log(e)
  }
}

This function first tries to fetch the story from the database (this would be the story with the latest live editing). If this fails it falls back to the Storyblok API.

We can then use this function on a page together with our <StoryblokPreviewSync /> component:

import { StoryblokComponent } from '@storyblok/react/rsc'

import { StoryblokPreviewSyncer } from '@/components/StoryblokPreviewSync'
import { getStoryblokData } from '@/utils/storyblok'

export default async function Home() {
  const story = await fetchData()

  return (
    <main>
      <StoryblokPreviewSyncer pathToRevalidate={'/'} />
      <StoryblokComponent blok={story?.content} />
    </main>
  )
}

function fetchData() {
  return getStoryblokData('home')
}

There you go! Now you should have live editing support, with the full power of React Server Components!

Deferrable Views, skeletons and named chunks in Angular

iO — Fri, 24 Nov 2023 00:00:00 +0000

Deferrable Views

To be fair lazy-loading is not a new thing in Angular. It has been provided for modules, based on the routes a long time ago. This feature still exists. But since the moment the Angular team presented standalone components that don't require modules at all, it looks like the next logical step is to provide lazy-loading for them as well. So they did and called it Deferrable Views.

Another feature of Deferrable Views is the opportunity to show a placeholder as the component is loaded. To avoid the fast flickering of the placeholder in the case that the deferred component was fetched quickly, it's possible to provide a minimum timer.

This is how to implement that using standalone wrapper component template, @defer block and @placeholder block:

@defer {
    <app-huge />
} @placeholder (minimum 1s) {
    <p>Loading...</p>
}

Skeletons

The next thing that could improve user experience is the skeleton shown as the placeholder. Instead of building it from scratch, I would recommend using the package called NGX Skeleton loader.

This package is easy to configure and it supports ARIA attributes to keep it accessible.

To prevent the content of the screen from moving as the placeholder would be replaced with the component (so called layout shift), we need to pass the height of the skeleton. That height needs to be equal to the component height.

Suppose that component height is 200px. This is how you can implement skeleton with the same height:

@defer {
    <app-huge />
} @placeholder (minimum 1s) {
    <ngx-skeleton-loader [theme]="{height: '200px'}" />
}

I found that one more step is required to adjust default styling for NGX Skeleton loader. It contains redundant margin and it's displayed as inline-block. Let's fix that in order to have consistent height of all skeletons in the app:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgxSkeletonLoaderModule } from 'ngx-skeleton-loader';

import { AppComponent } from './app.component';
import { WrapperComponent } from './wrapper/wrapper.component';
import { HugeComponent } from './huge/huge.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxSkeletonLoaderModule.forRoot({
      theme: {
        extendsFromRoot: true,
        display: 'block',
        margin: 0,
      },
    }),
    WrapperComponent,
    HugeComponent,
  ],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Named chunks

The last thing that goes well together with Deferrable Views is named chunks. By default, the lazy-loaded modules and components are shown in dev tools as .js files with non-human-readable names. For example chunk-IVE23K2G.js is a terrible name for debugging purposes.

Let's fix that by adding "namedChunks": true into angular.json file:

  content omitted
  ...
  "projects": {
    "angular-defer-test": {
      "architect": {
        "build": {
          "configurations": {
            "development": {
              "optimization": false,
              "extractLicenses": false,
              "sourceMap": true,
              "namedChunks": true
  ...

After that chunk names would look like that: huge.component-HRZM3FTC.js

Final result

Here's how final result looks like:

And here's the code if you would like to play with it:

https://stackblitz.com/~/github.com/GanjaGanja/angular-defer-test

Reducing latency in AI Speech Synthesis

iO — Thu, 16 Nov 2023 00:00:00 +0000

In my previous article, I showed how you can interact with ChatGPT through Voice UI on the web. If you haven’t already, read that article first to know what I built. What sells the illusion of having a real-time conversation with the AI is the low latency. Because the response is so quick, it doesn’t feel like the AI needs to process your information and create an audio file to playback to you. Even though this part feels realistic, the robotic voice for the speech synthesis doesn’t. My colleague Christofer Falkman pointed me to a way I could make Aiva, the ChatGPT-powered assistant, even more realistic. Using ElevenLabs’s AI-powered speech synthesis I can replace this robotic voice with an incredibly realistic voice. Time to upgrade Aiva!

Let’s implement it

As you might remember from the previous article, Aiva works like this:

Instead of using the native SpeechSynthesis Web API, we now replace it with a call to the ElevenLabs API where we get returned binary data in the form of a buffer. Or, simplified, we get a bit of data we can play as audio. As soon as the entire piece of text is sent to that API, returned to the application, and played as audio, the user gets to talk again. This yields a pretty cool result with an incredibly realistic voice:

It’s slow!

You might notice that the AI-powered speech synthesis is quite a bit slower. The latency increases with the length of the text. It first needs to turn all of the text into audio before it can play the first sentence. The longer the text, the slower the response. This is breaking the user experience of having a natural conversation.

Low latency over realistic voice

In my opinion, having a low-latency robotic voice in a real-time conversation is a better user experience. It doesn’t take you out of the conversation as much. So what now? Don’t use the AI version? Of course not, let’s fix this!

Time to take some well-known approaches

First, I looked into whether the audio could be streamed from the API. Unfortunately, I couldn’t find this option and didn’t want to limit my choice of which AI-power speech synthesis products I could use. Then, I thought about how, as a developer, I would normally handle large slow requests. Imagine you are making a dashboard with 10.000 rows of data. You could opt for pagination where you click a button to go to the next page of results. Chunking the data in pages of rows works great. Taking this into a conversation, we could chunk the text into sentences and play the audio for each sentence. Whilst this is the approach I took, this posed a new problem. Let’s imagine I retrieve audio for a sentence of the text, play the audio, and then do this over and over again for the entire piece of text. This means that the latency is pretty much just split up, but still present:

As you can see, there is quite a bit of time while the audio is playing which I could utilize to retrieve the audio data for the next sentence. This is pretty similar to how humans talk. You think of what to say and while you are talking you’re already thinking of the next sentence. This results in a fluent flow where there is always audio playing:

The end result

That did the trick! The latency is now low enough to not intrude on the natural flow of the conversation:

Interacting with ChatGPT through Voice UI on the web

iO — Thu, 02 Nov 2023 00:00:00 +0000

I probably don’t have to tell you what an enormous impact the rise of AI has had on the industry in recent times. It’s amazing to see all the progress that is being made. I knew when I was looking at an upcoming two-day hackathon at iO, I just needed to build something cool with ChatGPT. More particularly, the way you interact with ChatGPT.

Why create a different way to interact with ChatGPT

Personally, I don’t develop AI. I do however interact with it a lot. Like most of you reading, I interact the most with ChatGPT. While the chat interface is great to use while working, It always felt slightly awkward to interact with. When given the choice, I will always rather walk over to someone (or have a call) than use chat to discuss something. It feels a bit more natural as it is the way of communicating that is powered by our natural hardware: speaking and listening. So, if ChatGPT requires me to input text and read outputted text, can’t I just do that by speaking and listening?

I’ve wanted to build a demo application that enables just that. A user can start a conversation with ChatGPT and just talk. Once they’re done talking, ChatGPT processes the text and sends back a response. This response is then read out loud to the user after which the cycle continues.

Being a developer for the web, I naturally gravitated to the techniques I would use there. As it turned out in the end, this gave a surprising advantage in the user experience. Here is a quick glimpse of the result called “Aiva”:

What techniques to use?

For front-end frameworks, any will do. I’m most comfortable with React.js and Next.js so decided to use those. Also, I always want to try out at least one new thing when creating a demo. This time, that was the component library Radix which focusses on important aspects as accessibility. Also, I can highly recommend using a component library when building demos so building a nice UI doesn’t take away from your time and focus on the thing you are actually trying to build.

Input: SpeechRecognition Web API

For the input, I used the SpeechRecognition Web API. Fun fact, I built an application over six years ago called PresiParrot to automatically create captions when giving a presentation. What I find awesome about using web standards is that even after six years, the application still runs perfectly fine, perhaps even better, as it will always be supported by the browser.

In essence, the SpeechRecognition Web API provides you with a way to use the user’s microphone to capture audio and once they’re done talking, provide you with a text string to use. You can even use interim, or live updated, results if needed.

Why use this?

A big upside for me is the before-mentioned benefit that you get with using a web standard. Another major benefit of using the Web API that is built into the browser is that it’s incredibly quick. This goes for the SpeechRecognition Web API (input) but especially for the SpeechSynthesis Web API (output) which we’ll look at in a bit. Your browser already ships with the logic and voices that you might need, mitigating the need for another service that takes time. This greatly benefits the performance which is always important. But as it turned out, it became a nice surprise while building the demo. Have you ever tried to talk with your Google/Apple/Amazon home device? Whenever you ask something, there is always a few seconds of delay. This takes you out of the illusion that you’re actually having a conversation. As this Web API is so quick and needs no loading time, it feels nearly instant helping to sell the conversation effect.

How to use this?

Using the SpeechRecognition Web API is fairly straightforward. You first see if the Web API is supported in the user’s browser:

if (!('SpeechRecognition' in window || 'webkitSpeechRecognition' in window)) {
  // handle fallback
}

Next, as seen in the example above, the Web API can either named SpeechRecognition or webkitSpeechRecognition. We assign it like this and set it up:

const SpeechRecognition = window.SpeechRecognition || window.webkitSpeechRecognition

const recognition = new SpeechRecognition()
recognition.interimResults = true
recognition.lang = 'en-US'

We change two settings, first we set interimResults to true so we can receive the interim results while the user is speaking. Next, we set the language the user is going to speak in. Naturally, you can provide UI to alter this, but for the demo english is fine.

With everything configured, our next step is to create an onresult and onend callback:

recognition.onresult = (event) => {
  const { transcript } = event.results[0][0]
  // do something with transcript
}

recognition.onend = (event) => {
  const { transcript } = event.results[0][0]
  // do something with transcript
}

Now, for every interim result while the user is talking, you can do something with that transcript string once onresult is called. For instance, you show some live feedback on the screen with what text the Web API interpreted the user’s speech as. Once the user stops talking, the onend is called with the end result. Great! We now have turned speech into a text string to use as input!

Output: SpeechSynthesis Web API

What the SpeechRecognition Web API is for input, the SpeechSynthesis Web API is for output. In it’s simplest form, the Web API allows your computer to read a text string out loud.

Why use this?

As mentioned before, this Web API comes with the browser already built-in! It’s not just the Web API itself, but also a wide range of voices to use. These voices can be from difference countries and even different accents.

How to use this?

Let’s make it read out a text string. First we check whether the user’s browser supports the Web API again and create a constant to use later on. Finally, we need to make a SpeechSynthesisUtterance which is basically a unit of text that the Web API needs to read out loud:

if (!('speechSynthesis' in window && 'SpeechSynthesisUtterance' in window)) {
  // handle fallback
}

const synth = window.speechSynthesis

const voices = synth.getVoices()
const preferredVoice = voices.find((voice) => voice.voiceURI === 'Karen')

const utterance = new SpeechSynthesisUtterance('Hello from the computer!')
utterance.rate = 1
utterance.pitch = 1

if (preferredVoice) {
  utterance.voice = preferredVoice
}

As you can see, I can retrieve a list of all the supported voices on the user’s browser. I like the one named "Karen" so decided to store that one if found. Naturally, you can create a dropdown with voices for the user to select the one they like.

Next, we create a SpeechSynthesisUtterance with the text string to read out loud. We can then tweak the utterance a bit more by changing the rate (or speed) and the pitch of the voice. Finally, if our preferred voice is available, we assign it to the utterance as the voice to use.

Now all that is left is to speak:

utterance.onend = () => {
  // do something once all the text has been spoken
}

window.speechSynthesis.speak(utterance)

That’s it! We now have both input and output covered.

Tying the two together

I’ve created a useSpeechRecognition hook that exposes utilities to:

get the interim result to display in the UI
check whether there is permission to use the microphone to show UI whether it is available or not
request listening permission to the user
know whether the Web API is currently listening the the user
start listening to the user
stop listening to the user

I’ve also created a useSpeechSynthesis hook that exposes a utility to speak to the user with a passed text string.

Finally, I’ve created a useConversation hook that:

Keeps track of the conversation state
- "UNPERMITTED" - there is no permission yet to listen to the user’s microphone
- "IDLING" - the application is currently not listening or responding
- "LISTENING" - the useSpeechRecognition hook is listening the to the user’s microphone
- "RESPONDING" - the useSpeechSynthesis hook is speaking to the user
- "STOPPED" the user stopped the application
Uses the utilities exposed by the useSpeechRecognition and useSpeechSynthesis hooks to create a turn-based conversation

ChatGPT integration

So far, the application has yet to be hooked up to the ChatGPT API and is just responding with a fake answer. Let’s make the magic happen. All I need to do is create an API route in my Next.js application that receives two things in the form of a POST request:

messages - an array that consists of objects with a key of
- role - who is the message from? The "user" or the "assistant".
- content - the text string
aivaRole - what is the role of the AI to give it a bit of context on what it should behave like
- "assistant" - a general AI assistant that can virtually take up any role as long as the user instructs it to
- "tech-interviewer" - behave like a tech interviewer so a developer can practice an interview
- "scrum-master" - act like a scrum master and help a team with their scrum sessions
- "counselor" - be a counselor to the user providing them with a listening ear or advice

I added the aivaRole to give people using the demo an idea on what Aiva could be used for.

The user sends over a list of the whole conversation for context for the AI as it needs this for every request. I prepend this list with a bit of context for the AI so it knows it runs in a Voice UI, how it should behave/respond and finally the role the user set the AI to. This request then goes to the ChatGPT API, returns a response, returns that response to the front-end to finally be consumed by the useConversation hook.

React Three Fiber Visualisation

So yes, much like the OpenAI solution, you can now speak with the conversation. Besides mine feeling a bit more natural in the sense that it responds a lot quicker (~800ms), it still feels like you are talking with a ChatGPT API. We’ve stripped the need for traditional UI like inputs and text on the screen, but created a great new opportunity to give some personality to Aiva and simultaneously provide the needed feedback to the user (is it listening, responding etc.).

Why use this?

A few weeks back at the Frontmania Conference, Tim Beeren showed some amazing examples of Three.js using React Three Fiber. Another opportunity to try out something I haven’t worked with before! React Three Fiber basically allows a simpeler integration for using Three.js in a React.js application. This was good for me as I was not only using React.js to render the application, but also have the state of the conversation there which I wanted the visualisation to respond to.

How to use this?

I quickly realised that creating an awesome interactive visualisation would take quite a bit knowledge on subjects like shaders. Due to my incredibly short timeframe of two days to build the entire application, I took an existing visualisation and made it interact with the state of the conversation. I had control over two parameters:

speed the speed of the movement of the blob
intensity the intensity of the spikes in the blob

I could then create a little hook to change these values based on the conversation state:

useEffect(() => {
  switch (conversationState) {
    case 'RESPONDING':
      speed = 2
      intensity = 0.75
      break
    case 'LISTENING':
      speed = 1.25
      intensity = 0.35
      break
    case 'STOPPED':
    case 'IDLING':
      speed = 0.8
      intensity = 0.1
      break
    case 'UNPERMITTED':
    default:
      speed = 0.5
      intensity = 0.05
      break
  }
}, [conversationState])

The end result

With all the parts connected, I now have an application that caters a turn-based conversation where the state of the conversation is visualised through an interactive data visualisation. All of that without the need of a single piece of text or required user interaction on the screen! To showcase how these conversation can go, I’ve recorded this short screencast:

What are some practical use cases?

In this article I already highlighted a few use cases for demo purposes. The easy answer is that it can cater all use cases. If I boil down my application to its simplest form I created a nice input-output system for a conversation. Whatever the user wants to use it for they can tell the AI and it will, if appropriate, follow. A few more examples (which I naturally asked ChatGPT for):

Customer Support : ChatGPT can be used as a virtual customer support agent, handling common queries, providing information, and resolving issues.
Sales Assistance : ChatGPT can act as a virtual sales assistant, engaging with potential customers, answering questions about products or services, and providing recommendations.
Personal Assistant : ChatGPT can assist individuals in managing their schedules, setting reminders, making appointments, and helping with day-to-day tasks.
Content Creation : ChatGPT can generate blog posts, social media captions, or marketing copy, helping businesses with their content creation needs.
Language Translation : ChatGPT can facilitate real-time language translation, allowing users to communicate with individuals who speak different languages.
Lead Generation : ChatGPT can engage website visitors, qualify leads, and collect contact information, enhancing lead generation efforts for businesses.
Training and Education : ChatGPT can be utilized as a virtual tutor or trainer, providing personalized learning experiences, answering questions, and delivering educational content.
Market Research : ChatGPT can conduct surveys, gather feedback, and analyze customer preferences, helping businesses gain insights for market research purposes.
Virtual Event Host : ChatGPT can serve as a virtual event host, guiding attendees, answering questions, and providing information about the event agenda or sessions.
Personal Entertainment : ChatGPT can engage users in entertaining conversations, tell jokes, share interesting facts, or even play interactive storytelling games for personal enjoyment.

The sky(net) is the limit!

What are the takeaways?

ChatGPT, or AI in general, is being developer at an incredible pace. What we mustn’t forget is that we also need to take into account how the user interacts with AI. By creating a more natural conversation with the use of voice and sound we vastly improve the user experience in interacting with these products. By no means is a regular chat interface bad, it just is really good for quite some use cases. That doesn’t mean we shouldn’t explore other possibilities and create awesome new user experiences!

I feel like the match between AI and voice is great! As mentioned earlier, I’ve created an application that used the SpeechRecognition Web API over six years ago and never since! Even though I found it cool, I hadn’t find the actual use case for the technique up until creating this demo application. Sometimes combining older techniques and principles with new state-of-the art technology can lead to some magic.

Take my concept, think about some practical applications you might have (at your company) and try it out! Let’s make super cool products!

Make awesome animated interactions with two lines of code

iO — Wed, 18 Oct 2023 00:00:00 +0000

You might have heard about the View Transitions API in the context of animating between web pages. Whilst this is certainly awesome, you can apply this approach on a way smaller level to create awesome animated interactions in your web applications!

A few weeks ago I was lucky enough to visit the Google Campus in San Francisco through the Google Developer Expert program I am part of.

There, Una Kravets showed a demo she built using the View Transitions API to animate the deletion of cards. This excited me to look at using the API for not just page transitions, but more for micro animations!

Give feedback to the user

As always, I made to see what we can do with this approach:

View on CodePen

First, I created a layout like I would normally do. Next, I wrote some JavaScript to remove a list item with a small delay to see it get the checked state first. Removing an item looked like this:

list.addEventListener('change', (e) => {
  setTimeout(() => {
    removeListItemFromInputChangeEvent(e)
  }, 300)
})

The user experience of removing an item is not great. Because the item is removed, the item next to it now takes it place. Suddenly, this item is in the place of the removed one which makes it look like it was always there. What if we can remove it, have all the items neatly animate to their new position and by doing that give the user the proper feedback they need? In the past, this took quite a bit of JavaScript to do and even then it worked a bit janky. Now let’s (technically) add two lines of code. First, wrap the call of the remove function in a startViewTransition. For good measure, we’ll also feature check to progressively enhance the user experience. Meaning, if the View Transitions API is supported, we enhance the default behaviour with a nice animation:

list.addEventListener('change', (e) => {
  setTimeout(() => {
    if (!document.startViewTransition) {
      removeListItemFromInputChangeEvent(e)
    } else {
      document.startViewTransition(() => {
        removeListItemFromInputChangeEvent(e)
      })
    }
  }, 300)
})

Next, we add a unique name to each of the list items:

<li style="view-transitions-name: card-1">
  <label>
    <input type="checkbox" />
    Check this card
  </label>
</li>

Now if we delete an item, we see this behaviour:

With just adding the document.startViewTransition and a unique view-transitions-name for each list item, the entire grid repositioning is animated providing better feedback to the user. Awesome, right? One of the biggest benefits I find of this approach is that the View Transitions API just takes a before and after state. It doesn’t matter how you build your layout, what properties change or how different the two views are. As long as before and after your change (the removal of the one list item node) items have matching view-transitions-name properties, the browser will animate between them.

Now, let’s add a button that allows you to add a new item:

addButton.addEventListener('click', () => {
  addListItem()
})

We see the same unanimated behaviour as previously when deleting an item. Now let’s add the document.startViewTransition again:

addButton.addEventListener('click', () => {
  if (!document.startViewTransition) {
    addListItem()
  } else {
    document.startViewTransition(() => {
      addListItem()
    })
  }
})

As you can see, now when an item is added, the rest of the items animate to their new position. We can even add a bit of JavaScript that will randomly reorder the list and see what this technique will do:

Some other use cases

While having a grid of cards that may be filtered is a pretty common use case, you can naturally take this approach to other interactions as well. More than likely, you are working/have worked with tables. When adding to, removing from, sorting or filtering these tables the rows may change position. When calling the startViewTransition you can animate the changing of the rows like so:

You may have noticed I added a toggle to this demo for showing the items in a grid or underneath each other. When switching, that looks like this:

I though to myself, why not use this technique when switching between the two views?

Start using this now

It has never been easier to animate between different views on the page. Whilst animating between pages might be a bit much to start with, try implementing the View Transitions API on a smaller part of a page to make smoother experiences in your web application whilst simultaneously providing feedback for a user’s interactions through animation. It only takes a line or two!

View on CodePen

JavaScript Module Systems

iO — Wed, 11 Oct 2023 00:00:00 +0000

What is a JavaScript module?

In JavaScript, a module system allows developers to organize code into reusable pieces or components, which can be imported and used in other application parts. The module system provides a way to encapsulate code, manage dependencies, and control the scope of variables and functions.

Why do we need module systems?

Using a module system in JavaScript, or in any programming language, is crucial for several reasons, especially as applications grow in complexity. Here are some of the key reasons why a module system is essential:

1. Code Organization:

Modules allow developers to split their code into smaller, more manageable pieces, each responsible for a specific feature or functionality. This makes the codebase more organized, readable, and maintainable.

2. Scope Management and Collision Avoidance

Each module has its own scope, meaning variables and functions defined in a module are not globally accessible unless explicitly exported. This helps in avoiding variable conflicts and polluting the global namespace.

3. Dependency Management

Dependency management is clearer with modules, as dependencies are explicitly imported, making it easier to track and manage the relationships between different parts of an application.

Suppose you have three JavaScript files: utility.js, dataProcessor.js, and app.js. The dataProcessor.js file depends on a function from utility.js, and app.js depends on a function from dataProcessor.js.

Available module systems in JavaScript

In JavaScript, there are several module systems that allow developers to organize and structure their code. Here are the most commonly used module systems:

CommonJS (CJS)
Asynchronous Module Definition (AMD)
Universal Module Definition (UMD)
ES6 Modules (ESM)
SystemJS

1. CommonJS (CJS)

CommonJS is a module system implemented by Node.js for organizing and sharing JavaScript code. Before the advent of ES6 modules, CommonJS was the primary way to include and manage dependencies in Node.js applications. While browsers primarily use the ES6 module system, tools like Browserify and Webpack can transform CommonJS modules to be browser-compatible.

Key Concepts:

Module Definition: In CommonJS, every file is its own module. The variables, functions, and objects you define in a file are local to that file unless explicitly exported.
Export: To make parts of your code available for use in other files, you use module.export.
Import: To use a module in another file, you use the require function. This function returns whatever the target module exported.
Synchronous Loading: Modules are loaded synchronously, meaning the program waits for the module to be fully loaded and executed before moving on.
Module Caching: Modules are cached after the first time they are loaded, improving performance and ensuring that module initialization only happens once.
No tree shaking: because when you import a module you get an object.

How to use CommonJS?

Setting up:

Ensure you have Node.js installed. If not, download and install it from Node.js official website.

Step 1:

Create a file named counter.js:

let count = 0

function increment() {
  count++
}

function getCount() {
  return count
}

module.exports = {
  increment,
  getCount,
}

Step2:

Create a file named app.js:

const counter = require('./counter.js')

console.log(counter.getCount()) // Outputs: 0
counter.increment()
console.log(counter.getCount()) // Outputs: 1

Running the Code:

In your terminal, run the file using Node.js node app.js. You’ll see that the count variable in the counter.js module retains its state between function calls.

2. Asynchronous Module Definition (AMD)

It is a specification for the modular development of JavaScript applications and libraries. It allows developers to define modules and their dependencies asynchronously , making it particularly well-suited for the browser environment where synchronous loading of modules can result in performance issues. The most popular implementation of AMD is the RequireJS library.

Key Concepts:

Define a Module: Use the define function to specify a module, its dependencies, and a factory function that returns the module's exports.
Load and Use a Module: Use the require function to load a module and its dependencies.
Asynchronous Loading: One of the primary benefits of AMD is its support for asynchronous module loading. This means that modules and their dependencies can be fetched in parallel, which can lead to faster page loads in a browser environment.
Module ID: Each module can have a unique module ID, which is typically its file path (minus the .js extension). This ID is used when specifying dependencies.

How to use AMD?

Setting up:

Include RequireJS in your HTML file:

<script data-main="scripts/app" src="path/to/require.js"></script>

The data-main attribute points to the main script of your application.

Step 1:

Create a file named scripts/math.js:

// math.js

define([], function () {
  function add(a, b) {
    return a + b
  }

  function subtract(a, b) {
    return a - b
  }

  return {
    add: add,
    subtract: subtract,
  }
})

Here, we’ve defined a module without any dependencies (empty array) and exported two functions.

Step 2:

Create a file named scripts/app.js (your main script):

// app.js

require(['math'], function (math) {
  console.log(math.add(5, 3)) // Outputs: 8
  console.log(math.subtract(5, 3)) // Outputs: 2
})

Here, we’re loading the math module and using its functions. Once the math module is loaded, the function will be called.

Running the Code:

Simply open the HTML file containing the RequireJS script tag in a browser. The main script (app.js) will be executed, and it will asynchronously load the math.js module.

3. Universal Module Definition (UMD)

It is a pattern for writing JavaScript modules that can work both in the browser and on the server. The idea behind UMD is to make a module compatible with the most popular script loaders of the day. In fact, it is a combination of CommonJs + AMD.

Key Concepts:

Compatibility: UMD aims to support the three most popular module formats:

AMD (Asynchronous Module Definition): Used by browsers and includes libraries like RequireJS.

CommonJS (CJS): Used primarily on the server side, especially with Node.js.

Global variable definition: For browsers without any module loader.
Flexibility: UMD allows developers to write a module once and have it work in many environments without modification.
Wrapper Pattern: UMD typically wraps the module definition inside a function that can detect the module system in use and act accordingly.

How to use UMD?

Here’s a basic example of how you might define a module using UMD:

1. Define a UMD module:

Create a file named my-umd.js:

;(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD. Register as an anonymous module.
    define([], factory)
  } else if (typeof module === 'object' && module.exports) {
    // Node. Does not work with strict CommonJS, but
    // only CommonJS-like environments that support module.exports,
    // like Node.
    module.exports = factory()
  } else {
    // Browser globals (root is window)
    root.myModule = factory()
  }
})(this, function () {
  return {
    hello: function () {
      return 'Hello, World!'
    },
  }
})

2. Running the UMD module:

a. In the Browser:

Include the UMD module in a script tag:

<script src="my-umd.js"></script>
<script>
  console.log(myModule.hello()) // Outputs: "Hello, World!"
</script>

b. Using AMD (e.g., RequireJS):

First, set up RequireJS and then define the module:

<script src="path_to_require.js"></script>
<script>
  require(['my-umd'], function (myModule) {
    console.log(myModule.hello()) // Outputs: "Hello, World!"
  })
</script>

c. In Node.js:

First, set up Node.js and then just require the file:

const myModule = require('./my-umd.js')
console.log(myModule.hello()) // Outputs: "Hello, World!"

4. ES6 Modules (ESM)

It is the native module system introduced in ECMAScript 6 (ES6), also known as ECMAScript 2015 (ES2015). ESM allows you to modularize your JavaScript code, making it more maintainable, scalable, and organized for both the browser and the server. With its native support in modern environments and tools, it’s become an essential part of the JavaScript ecosystem.

Key Concepts:

Export & Import: The core of ESM is the ability to export and import functions, objects, or primitives from one module to another.
Static Analysis: Imports and exports are determined statically at compile time, rather than runtime. This means tools can analyze a module’s dependencies without executing it.
File-based Modules: In ESM, each file is its own module. Anything not exported remains private to that module.
Dynamic Imports: Introduced later, dynamic imports allow you to load modules on the fly using promises.
Static Structure: One of the defining characteristics of ESM is its static structure. This means you can’t conditionally import/export inside functions or conditionals. The structure is determined at compile time, not runtime.
Cyclic Dependencies: ESM handles cyclic (or circular) dependencies between modules. If module A imports from module B, and module B imports from module A, the language has mechanisms to handle this without causing errors.
Module Caching: If multiple modules import from a single module, that module will only be executed once. This ensures that side effects in a module (like setting up an event listener) don’t occur multiple times.
Tree shakeable: because of static analysis supported by ES6.

How to use it?

Exporting from a module:

// math.js
export const add = (a, b) => a + b
export const subtract = (a, b) => a - b

Importing into another module:

// app.js
import { add, subtract } from './module.js'
console.log(add(2, 3)) // Outputs: 5

Using Default Exports:

Each module can have one default export, which can be imported without curly braces.

// greet.js
export default function () {
  return 'Hello!'
}

// app.js
import greet from './greet.js'
console.log(greet()) // Outputs: Hello!

Combining Imports:

// app.js
import greet, { add, subtract } from './module.js'

Renaming Imports:

// app.js
import { add as addition } from './math.js'
console.log(addition(2, 3)) // Outputs: 5

Dynamic Imports:

Useful for code-splitting and lazy-loading modules.

const loadModule = async () => {
  const module = await import('./dynamicModule.js')
  module.someFunction()
}

5. SystemJS

SystemJS is a dynamic module loader that provides a way to load ES6 modules, CommonJS, AMD, and global scripts. It’s a powerful tool that bridges the gap between different module formats and allows developers to write code that can be loaded in various environments without modification.

Where do we use SystemJs?

SystemJS is primarily designed for the browser to handle module loading in environments that may not natively support certain module formats. However, it's not limited to just the browser. You can use SystemJS on the server side, particularly with Node.js, but there are some considerations to keep in mind:

Native Module Support in Node.js: Node.js has built-in support for CommonJS modules, and recent versions of Node.js also support ES6 modules natively. This often reduces the need for a module loader like SystemJS on the server side.
Use Cases on the Server: One potential use case for SystemJS on the server is when you have a mixed module environment (e.g., a combination of CommonJS, AMD, and ES6 modules) and you want a unified way to load them. Another scenario might be dynamically loading modules at runtime based on certain conditions.
Integration with Other Tools: If you’re considering using SystemJS on the server side, you might also want to look into how it integrates with other server-side tools and frameworks you’re using.

Key Concepts:

Universal Module Loading: can load multiple module formats, including: — ES6 modules — CommonJS — AMD — UMD — Global scripts (non-modular scripts)
Dynamic Loading: allows for the dynamic loading of modules at runtime. This is particularly useful for applications that load modules based on certain conditions or user interactions.
Transpilation Support: can be integrated with transpilers like Babel or TypeScript. This means you can write code in modern ES6 or TypeScript and have SystemJS load and transpile it on the fly in browsers that only support ES5.
Plugin System: supports plugins, enabling it to load not just JavaScript modules but also other resources like JSON, CSS, text, and images as modules.
Configuration and Flexibility: provides a rich configuration system, allowing developers to specify paths, aliases, default extensions, and other settings to control how modules are loaded and resolved.
Production Optimizations: Because of its dynamic loading features, SystemJS thrives in development contexts, but it also gives options to optimize for production. Tools like systemjs-builder can be used to bundle modules into fewer files, reducing the number of HTTP requests and improving load times.
Compatibility: provides a way to use modules in environments that don't natively support them. For instance, before ES6 module support was widespread in browsers, SystemJS allowed developers to use ES6 module syntax and load them effectively.
Production Bundles: While SystemJS is great for development with its dynamic loading capabilities, for production, it's often recommended to create bundles to reduce the number of requests and improve performance.

How to use it?

Installation:

You can include SystemJS via a script tag or install it via npm npm install systemjs.

<script src="path-to-systemjs/dist/system.js"></script>

Configuration:

Set up a configuration for SystemJS. This tells SystemJS where to find modules and how to load them.

SystemJS.config({
  map: {
    jquery: 'path-to-jquery',
  },
  packages: {
    app: {
      defaultExtension: 'js',
    },
  },
})

Loading Modules:

Use SystemJS to load your main module.

SystemJS.import('app/main.js').then(function (module) {
  // Use the module here
})

Conclusion

JavaScript has seen various module systems over the years, each with its unique strengths. However, ESM Modules stand out due to their efficiency and widespread adoption in modern frameworks. For developers aiming for streamlined and future-ready applications, using ESM Modules is a clear choice.

I want it in my terminal!

iO — Tue, 10 Oct 2023 00:00:00 +0000

I Don't Want to Leave My Terminal

The terminal, often called the command line or shell, is a powerful interface for interacting with your computer. While it may appear daunting to newcomers, mastering the terminal can significantly enhance your productivity and open up a world of possibilities. In this article, we'll explore a few handy tools that can be accessed directly from the terminal, providing valuable information and shortcuts for various tasks.

Cheat Sheets for Tools and Languages

Whether you're a programmer, developer, or system administrator, you often need quick access to syntax, commands, and documentation for various programming languages and tools. curl cht.sh offers an extensive collection of cheat sheets, making it easier to find the information you need without leaving the terminal.

To access a cheat sheet, use the following command:

curl cht.sh/[Tool or Language]

Replace [Tool or Language] with the name of the programming language or tool you want a cheat sheet for. For example, to get a cheat sheet for Git, use:

curl cht.sh/git

Get information about aws-cli or gcloud:

curl cht.sh/aws
curl cht.sh/gcloud

You can get language-specific syntax quickly:

curl cht.sh/go/web-server
curl cht.sh/rust/loops
curl cht.sh/typescript/generic-type

There can be many examples since this command will provide concise and relevant information about the language or tool, including commonly used commands, syntax, and examples. If you need assistance or more options, you can use the :help feature like this:

curl cht.sh/:help

Weather Information

Are you curious about the current weather in your city or planning a trip and need to check the forecast? The curl command and wttr.in can be your go-to tool.

To get the weather information for a specific location, type the following command into your terminal:

curl wttr.in/[Location]

Replace [Location] with the name of your city or the location you want to check. For instance, to get the weather in Amsterdam, you would type:

curl wttr.in/Amsterdam

This command will return a detailed weather report, including current conditions, temperature, humidity, wind speed, and more. If you need help or want to explore additional options, you can use the :help feature by appending it to the URL like this:

curl wttr.in/:help

Cryptocurrency Information

Cryptocurrency markets are known for their rapid fluctuations, and staying updated on the latest prices and trends is essential for traders and enthusiasts. curl rate.sx is a handy tool that allows you to retrieve cryptocurrency information directly from the terminal.

To check the price of a specific cryptocurrency on a specific date, use the following command:

curl rate.sx/[Token]@[Date]

Replace [Token] with the cryptocurrency symbol or name and [Date] with the date you want to check. For example, to get the price of XRP on October 1st, you can use:

curl rate.sx/btc
curl rate.sx/xrp@2023-10-01

This command will provide historical data for the selected cryptocurrency on the specified date.

To seek help or explore additional options, use the :help feature as follows:

curl rate.sx/:help

Authorship

It's important to acknowledge the creator of these useful tools. All the tools mentioned in this article were built by @igor_chubin, who has contributed significantly to the open-source community by creating accessible and efficient terminal-based utilities.

In conclusion, these terminal-based tools, offer quick and convenient ways to access weather information, cheat sheets for various tools and languages, and cryptocurrency data. Mastering these commands and exploring their capabilities can enhance your command-line skills and streamline your daily tasks. So, embrace the terminal's power and make your computing experience more efficient and informative.

Speedup unit tests development in Angular with NG-Mocks

iO — Wed, 04 Oct 2023 00:00:00 +0000

Why does it take so much time to create unit tests?

Unit tests are an important part of any application. However, the development of robust unit tests takes time. One of the things that takes a lot of that time is mocking all the dependencies. Angular CLI doesn't help you a lot, because it only generates the initial .spec file with default TestBed configuration. So how can you speed up unit test development in Angular?

Mock the dependencies with NG-Mocks library

NG-Mocks is a testing library that helps to mock all the dependencies. It has plenty of helper functions. I would like to show you two of them that might help you the most.

Speedup TestBed module configuration with MockProvider function

Each component or service might depend on other components and services. Here's an example of a service that depends on HttpClient, Router and OAuthService:

@Injectable({
    providedIn: 'root',
})
export class AuthService {
    constructor(
        private http: HttpClient,
        private router: Router,
        private oauthService: OAuthService,
    ) {
        this.configureSSO();
    }

    /**
     * OAuthService needs to be configured in order to use its Single Sign-On feature
     */
    private configureSSO() {
        this.oauthService.configure(authConfig);
        this.oauthService.tokenValidationHandler = new JwksValidationHandler();
        this.oauthService.loadDiscoveryDocumentAndTryLogin();
    }

    loginWithSSO(): void {
        // ...
    }

    logoutWithSSO(): void {
        // ...
    }

    loginUserAndRedirect(): Observable<boolean> {
        return this.http.post('http://localhost:4200/', 'some payload').pipe(
            switchMap(() => {
                this.router.navigate(['/dashboard']);
                return of(true);
            }),
        );
    }
}

Let's implement the test config for that service. The default approach would be to use the TestBed.configureTestingModule() function to configure all the dependencies. What needs to be passed into that function:

HttpClientTestingModule, which configures HttpClientTestingBackend used by HttpClient.
Mock of OAuthService.

describe('AuthService', () => {
  let service: AuthService;
  let router: Router;
  let httpMock: HttpTestingController;
  let oAuthService: OAuthService;

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [HttpClientTestingModule],
      providers: [
        {
          provide: OAuthService,
          useValue: {
            configure: () => {},
            loadDiscoveryDocumentAndTryLogin: () => {},
            tokenValidationHandler: new JwksValidationHandler(),
          },
        },
      ],
    });

    router = TestBed.inject(Router);
    httpMock = TestBed.inject(HttpTestingController);
    oAuthService = TestBed.inject(OAuthService);
    service = TestBed.inject(AuthService);
  });
});

At least two tests need to be added. Both of them would contain spyOn functions to detect when a specific method gets called on an instance of a specific class:

describe('AuthService', () => {
    let service: AuthService;
    let router: Router;
    let httpMock: HttpTestingController;
    let oAuthService: OAuthService;

    beforeEach(() => {...});

    it('should configure SSO on initialization ', () => {
        // Arrange
        const configureSpy = spyOn(oAuthService, 'configure');
        const tokenValidationHandlerSpy = spyOnProperty(oAuthService, 'tokenValidationHandler', 'set');
        const loadDiscoveryDocumentAndTryLoginSpy = spyOn(oAuthService, 'loadDiscoveryDocumentAndTryLogin');
        const httpClientSpy: HttpClient = jasmine.createSpyObj(['post']);

        // Act
        new AuthService(httpClientSpy, router, oAuthService);

        // Assert
        expect(configureSpy).toHaveBeenCalledWith(authConfig);
        expect(tokenValidationHandlerSpy).toEqual(new JwksValidationHandler());
        expect(loadDiscoveryDocumentAndTryLoginSpy).toHaveBeenCalled();
    });

    it('should send a POST request to the server and navigate to "/dashboard" on success', () => {
        // Arrange
        const navigateSpy = spyOn(router, 'navigate');

        // Act
        service.loginUserAndRedirect().subscribe();

        // Assert
        const req = httpMock.expectOne('http://localhost:4200/');
        expect(req.request.method).toBe('POST');
        req.flush({}); // Simulate a successful response

        expect(navigateSpy).toHaveBeenCalledWith(['/dashboard']);
    });
});

Now let's replace the mock of OAuthService in TestBed with NG-Mocks MockProvider helper function:

beforeEach(() => {
    TestBed.configureTestingModule({
        imports: [HttpClientTestingModule],
        providers: [MockProvider(OAuthService)],
    });

    //...
});

MockProvider(OAuthService) creates empty dummies as methods of OAuthService which is totally ok for implemented tests.

Spy all methods of services using ngMocks.autoSpy

ngMocks.autoSpy is an awesome feature if you want to get rid of all spied methods in your tests. In order to use it in the specific test, it needs to be added on top of the .spec file:

ngMocks.autoSpy('jasmine');

describe('AuthService', () => {
    //...
})

After that tests need to be updated:

ngMocks.autoSpy('jasmine');

describe('AuthService', () => {
    let service: AuthService;
    let router: Router;
    let httpMock: HttpTestingController;
    let oAuthService: OAuthService;

    beforeEach(() => {
        TestBed.configureTestingModule({
            imports: [HttpClientTestingModule],
            providers: [MockProvider(OAuthService), MockProvider(Router)],
        });

        router = TestBed.inject(Router);
        httpMock = TestBed.inject(HttpTestingController);
        oAuthService = TestBed.inject(OAuthService);
        service = TestBed.inject(AuthService);
    });

    it('should configure SSO on initialization ', () => {
        // Assert
        expect(oAuthService.configure).toHaveBeenCalledWith(authConfig);
        expect(oAuthService.tokenValidationHandler).toEqual(new JwksValidationHandler());
        expect(oAuthService.loadDiscoveryDocumentAndTryLogin).toHaveBeenCalled();
    });

    it('should send a POST request to the server and navigate to "/dashboard" on success', () => {
        // Act
        service.loginUserAndRedirect().subscribe();

        // Assert
        const req = httpMock.expectOne('http://localhost:4200/');
        expect(req.request.method).toBe('POST');
        req.flush({}); // Simulate a successful response

        expect(router.navigate).toHaveBeenCalledWith(['/dashboard']);
    });
});

As you can see, now it's a bit less code in the tests.

Make tests more maintainable

One more exciting thing from NG-Mocks is a proposal on how to make tests more maintainable. The idea is to write tests without scoped variables. Basically, specific arrangements need to be applied to specific tests so that each test is self-sufficient and does not rely on scoped variables:

ngMocks.autoSpy('jasmine');

describe('AuthService', () => {
    let service: AuthService;

    beforeEach(() => {
        TestBed.configureTestingModule({
            imports: [HttpClientTestingModule],
            providers: [MockProvider(OAuthService), MockProvider(Router)],
        });

        service = TestBed.inject(AuthService);
    });

    it('should configure SSO on initialization ', () => {
        // Arrange
        const oAuthService = TestBed.inject(OAuthService);

        // Assert
        expect(oAuthService.configure).toHaveBeenCalledWith(authConfig);
        expect(oAuthService.tokenValidationHandler).toEqual(new JwksValidationHandler());
        expect(oAuthService.loadDiscoveryDocumentAndTryLogin).toHaveBeenCalled();
    });

    it('should send a POST request to the server and navigate to "/dashboard" on success', () => {
        // Arrange
        const httpMock = TestBed.inject(HttpTestingController);
        const router = TestBed.inject(Router);

        // Act
        service.loginUserAndRedirect().subscribe();

        // Assert
        const req = httpMock.expectOne('http://localhost:4200/');
        expect(req.request.method).toBe('POST');
        req.flush({}); // Simulate a successful response

        expect(router.navigate).toHaveBeenCalledWith(['/dashboard']);
    });
});

As you can see now arrangements are applied to specific tests. That should make them more maintainable as we add other tests into that .spec file.

Conclusion

I hope NG-Mocks will help you with unit test development and improve your overall developer experience as you create Angular applications. Happy coding!

Generate unit tests using CodiumAI

iO — Wed, 27 Sep 2023 00:00:00 +0000

What is Unit testing

Unit testing ensures that pieces of code work the way you expect them to. Performing unit tests is designed to be simple, generally, the tests are written in the form of functions that will determine whether a returned value equals the value you were expecting.

CodiumAI for unit tests generation

I've recently tried unit tests generation with CodiumAI. It's an extension for VS Code and Intellij Idea that is free to use for independent developers. It supports JavaScript, TypeScript and a variety of other programming languages. Let me show you how it works.

How to install CodiumAI in VS Code

First of all, you need to install it. CodiumAI supports VS Code. Open VS Code Extensions section, search for "CodiumAI" and install it.

How to install CodiumAI in IntelliJ Idea

To install CodiumAI in IntelliJ Idea, go to Settings -> Plugins -> search for "CodiumAI", install it and then restart IntelliJ Idea:

How to generate unit tests

Here's an example of TypeScript code that will be used for unit tests generation:

export interface User {
  userId: string
  userName: string
}

export class AuthService {
  searchUsersByName(users: User[], userName: string) {
    return users.filter((user) => user.userName.toLowerCase().includes(userName.toLowerCase()))
  }
}

Tests generation with CodiumAI works similarly in VS Code and IntelliJ Idea. Here's how to do it in VS Code:

And here's how you can do the same thing in IntelliJ Idea:

Starting from here I will use VS Code only for tests generation. It works similarly in IntelliJ Idea.

Generate custom unit test

Let's say we need a custom unit test that would make our test users have name and surname separated by space as part of their "userName" string. Example: "Jane Doe". So this test:

returns an array of users, users should have names that contain name and surname separated by space

We can generate that custom test using the Behaviours Coverage section:

Now, a custom unit test is generated and added to the list of tests.

Run all unit tests

Time to run the tests!

That might require you to have one of the testing libraries (Jest, Mocha, Karma Jasmine, etc.) installed and configured in your project. The only available Test Framework from the Configuration section that worked without any configuration with my simple code example is "React Testing Library". Here's how it works:

Fix the code with CodiumAI suggestions

You might find one of the tests broken, due to edge case. CodiumAI would suggest you to fix the code. Here's one of CodiumAI's suggestions that could fix several edge cases:

Now it's time to apply the code suggestion:

Suggestion is applied, and all unit tests are generated. Now you can copy-paste unit tests into your project.

That was the last feature that I wanted to share with you. There are many others that you can try as well.

CodiumAI is not perfect

You should always double-check the tests CodiumAI generates

That's the warning from the CodiumAI team. They've made an amazing tool to make you more productive as you develop unit tests. But don't forget to check what AI generated for you. Happy coding!

ECMAScript Explicit Resource Management early implementation in TypeScript 5.2

iO — Mon, 18 Sep 2023 09:18:02 +0000

This article on "ECMAScript Explicit Resource Management Early Implementation in TypeScript 5.2" is for developers who are interested in managing resources explicitly in their JavaScript programs. It explains how this feature works and how it can simplify resource management code.

Explicit Resource Management indicates a system whereby the lifetime of a “resource” is managed explicitly by the user. This can be done either imperatively (by directly calling a method like Symbol.dispose) or declaratively (through a block-scoped declaration like using).

A "Resource" is something that has a specific lifespan. When that lifespan is over, the program needs to perform a specific action, like closing a file or freeing up memory, so that the program can continue running smoothly. Examples of resources include file handles and network sockets.

At the moment of writing, the ECMAScript proposal for Explicit Resource Management is at stage 3 which means it will be launched within a few months. However, the TypeScript community has already implemented it in TypeScript version 5.2.

This implementation will add a feature to the JavaScript language similar to other languages such as C# using syntax [link], Python with syntax [link], or try [link] in Java.

// C# example of the 'using' statement
using (var file = File.OpenRead(“path-to-file”))
{
    // use the file
}
// file.dispose() method has been called now to release resources.

In general, without using this new feature, a conventional free-up pattern is by using the try/finally syntax:

var obj
try {
  obj = someResource()
  // ...
} finally {
  obj.release() // or any other clean-up method provided by the resource
}

Now this can be written in this way in TypeScript 5.2:

using obj = someResource();
// ...

When the program's execution goes outside of the block that the obj has been defined, the object will no longer be needed and the dispose method will be called.

TypeScript introduced an interface called Disposable that can be used to implement the using statement. To do this, your class should implement the Disposable interface, which requires the class to have a [Symbol.dispose] method. This method is responsible for freeing up any resources used by the class when it is no longer needed. By implementing the Disposable interface, the TypeScript compiler knows how to translate the using syntax into a try/finally block that the current JavaScript engine can understand.

class MyResource implements Disposable {
    [Symbol.dispose]() {
      // clean-up logic
    }
}

using obj = new MyResource();
// ...

Or, if you have a function instead of a class, your function should return an object that has the Symbol.dispose method:

function myResource(): Disposable {
    return {
        [Symbol.dispose](){ /* clean-up logic */}
    }
}

using obj = myResource();

Good to know that after compilation, the above code will become something like this:

class MyResource {
  [Symbol.dispose]() {
    // clean-up logic
  }
}
var obj
const env_1 = { stack: [], error: void 0, hasError: false }
try {
  obj = __addDisposableResource(env_1, MyResource(), false)
} catch (e_1) {
  env_1.error = e_1
  env_1.hasError = true
} finally {
  __disposeResources(env_1)
}

As you can see here the TypeScript compiler has compiled the using statement into the traditional try/finally pattern that I mentioned before and of course, with some simple functions to manage the allocated resources(__addDisposableResource and __disposeResources will be generated by the compiler in the output file).

Nested scopes and using

Objects can be created in the nested scopes:

function work() {
    using a = resource();
    {
        using b = resource();
    }
}

work();
// b.dispose()
// a.dispose()

In this case, after leaving the scope, the dispose methods will be called respectively.

DisposableStack class

Implementing the Symbol.dispose method can be a good pattern to use when you have a class or function that needs to be disposed of at some point. However, there are a few potential problems to consider. Firstly, implementing the dispose method can add unnecessary abstraction to your code in some cases, which can make it more difficult to read and understand. Secondly, many existing libraries and modules may not have implemented the dispose method yet, in which case you will need to create a wrapper around them and implement the clean-up code (dispose) yourself. Keep these considerations in mind when deciding whether or not to implement the dispose method in your code.

Here is an example from the TypeScript blog:

class TempFile implements Disposable {
    #path: string;
    #handle: number;

    constructor(path: string) {
        this.#path = path;
        this.#handle = fs.openSync(path, "w+");
    }

    // other methods

    [Symbol.dispose]() {
        // Close the file and delete it.
        fs.closeSync(this.#handle);
        fs.unlinkSync(this.#path);
    }
}

function doSomeWork() {
    using file = new TempFile("path-to-file");
}

This class has been implemented (with all of its sophistication that it might have later) to only have a Symbol.dispose method that would be called by the engine. However, TypeScript 5.2 introduces the DisposableStack class, which makes it simpler to use Explicit Resource Management.

Here is how:

function doSomeWork() {
    const path = "path-to-file";
    const file = fs.openSync(path, "w+");

    using cleanup = new DisposableStack();
    cleanup.defer(() => {
        fs.closeSync(file);
        fs.unlinkSync(path);
    });

    // use file...
}

Here we’ve created an instance of DisposableStack right after opening the file; It has the defer method that accepts a callback function which is suitable for clean-up that will be invoked at the moment of disposing the cleanup object.
After the above code is compiled, the resulting JavaScript code will include a finally block. This finally block will call the callback function that was passed to the defer method. This ensures that the callback function is always executed, even if an error occurs in the try block.

Async dispose method

Sometimes for your dispose logic you might need to use asynchronous operations using async/await. In this case, you can simply use the await before the using keyword:

await using file = OpenFile('...');

In this case, in the OpenFile function or class, you should implement the dispose method using Symbol.asyncDispose like below:

import * as fs from 'fs'

function OpenFile(path): AsyncDisposable {
  const file = fs.open(path)

  return {
    file,
    async [Symbol.asyncDispose]() {
      await fs.anAsyncOperation()
    },
  }
}

Polyfills

Because this feature is so recent, most runtimes will not support it natively. To use it, you will need runtime polyfills for the following:

Symbol.dispose
Symbol.asyncDispose
DisposableStack
AsyncDisposableStack
SuppressedError

Symbol.dispose and Symbol.asyncDispose can be polyfilled like this:

Symbol.dispose ??= Symbol('Symbol.dispose')
Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose')

The compilation target in the tsconfig file should be es2022 or below and the library setting to either include "esnext" or "esnext.disposable"

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022", "esnext.disposable", "dom"]
  }
}

For more information on this feature, take a look at the work on GitHub!

TIL: The CSS order Property Requires Each Grid/Flex Item to be ordered

iO — Tue, 12 Sep 2023 00:00:00 +0000

I was today years old when I learned something new about the CSS order property. I didn't learn about the existence of the property today, mind you. I just learned about a constriction which, in my opinion, makes it a little bit less usable. You see... when you want to order a flex or grid item, you have to order all of them. You can't just order one of them. Let me show you what I mean.

According to its formal definition on MDN, order's inital value is 0 (zero).

When you order an item, it will be visually ordered according to its value compared to its siblings's order value. Any item with the same order value will be visually ordered by its place in the DOM. Have a look at this example:

<style>
  .flex-container {
    display: flex;
  }
</style>
<div class="flex-container">
  <div class="flex-item">Item 1</div>
  <!-- order: 0 // default -->
  <div class="flex-item">Item 2</div>
  <!-- order: 0 // default -->
  <div class="flex-item" style="order: 1">Item 3</div>
  <!-- order: 1 // explicitly assigned -->
</div>

<!-- Expected visual result -->
Item 1 Item 3 Item 2

<!-- Actual visual result -->
Item 1 Item 2 Item 3

You would expect Item 2 and Item 3 to be visually swapped. However, they are not swapped, despite Item 3 having an order: 1. Sort of like zero-index Arrays, 1 comes after 0. If you want to actually order one item, you have to order all of them. This is true for both flex and grid.

To order any element, you have to order all of them. This is not a big problem, as you usually generate lists of items with a loop (like v-for in Vue or *ngFor in Angular or Array.prototype.map in JSX). You can easily retrieve the current iteration index and use that for order. It's just weird to me that it is necessary. I would expect order to have a default value of auto, making the visual order default to the DOM order.

So, to make sure that Item 3 is visually ordered before Item 2, you have to explicitly set order: 2 on Item 2 (or any value higher than 1).

<div class="flex-container">
  <div class="flex-item" style="order: 1">Item 1</div>
  <div class="flex-item" style="order: 2">Item 2</div>
  <div class="flex-item" style="order: 1">Item 3</div>
</div>

<!-- Visual result -->
Item 1 Item 3 Item 2

No big deal, but something to keep in mind when you want to use the order property.

Consistent CSS spacing is hard, but it does not have to be

iO — Tue, 15 Aug 2023 00:00:00 +0000

I've been around for a while, and it has been rewarding to witness CSS develop into a powerful styling tool. Many of the complexities we used to face are now being solved by single CSS properties (tip of the hat to box-shadow), while newly added capabilities give us powers far beyond our wildest dreams. We can whip out sub grids, container queries, and page transitions without breaking a sweat, so we can finally focus on the finer design details.

Not all of our past problems have been laid to rest though, which is what prompted me to write this article. One of the oldest and most common sets of CSS properties are still causing major headaches, and our projects suffer the consequences. Spacing is hard , and the repercussions (i.e. increased maintenance complexity and time/money spent on bugs) are grim.

Before I dig into two simple guidelines that will alleviate the most pressing spacing concerns, let's find out why CSS spacing is such a minefield.

Whack-a-mole problems

When CSS spacing goes wrong, it creates a whack-a-mole situation. For those who don't know, whack-a-mole is an old arcade game in which moles randomly rise up from holes in the ground. Players need to hit them with a hammer, doing so will cause the mole to disappear, while another one pops up in a different location.

In development terms: squashing one bug will invariably introduce a new one. The client reports an issue and the following code dive will leave a slightly confused developer pondering. He'll make a change and all will appear dandy, but unknowingly he created a new bug. When the new bug is discovered another ticket is created, resulting in increased frustration of all parties involved. And that cycle repeats itself. Ad infinitum. In other words: whack-a-mole.

There is no single reason why spacing is so vulnerable to this type of slip-up, but there are some obvious causes why we keep tripping up:

Developers don't possess the needed design DNA to spot spacing issues.
Spacing is everywhere, so the opportunities to mess up are plentiful.
It's easy to mend spacing problems with crappy code, and people looking at the resulting layout will be none the wiser.
Beware of the cascade. A trivial rule that adds 12px of vertical padding to a plain paragraph can ruin an entire project.
There are several properties that create spacing, and a handful of context-specific hacks on top of that. Picking the right solution isn't always obvious.
The setup of most projects is inadequate to assess layout impact, meaning developers are working in the dark (and just hoping for the best).

CSS is free-form in the sense that there are always various ways to solve a problem. No two solutions are ever truly equal though, so let's run through the most common spacing options we have at our disposal.

Using the right tool for the job

There are various ways to create space, each with its own strengths and weaknesses, but it generally comes down to these three:

padding : creates space within an element. Works on pretty much everything, but top/bottom paddings are ineffective on inline elements.
gap : creates consistent spacing between the direct children of an element. It only works with grid and flexbox.
margin : creates space around elements. Works on pretty much everything, but top/bottom margins are ineffective on inline elements.

I am a big fan of gap, but its one big limitation is that it can't be overruled for specific children. It is perfect for creating a fixed grid, yet it is rigid, and changing one specific space is hacky. This severely limits its use.

Paddings are useful for creating space between an element's edge and its contents. They come in handy when an element has a clear visual definition (think backgrounds, borders, box-shadow, ...), when you want to expand the interactive area of an element (hover, click, ...), or when you want to reserve space for absolutely positioned elements.

Margin is the most versatile, and the go-to property when you need flexible space between elements. You should only switch out margin to a better-fitting property when it adds extra value. We are of course talking CSS and there will be specific use cases that require craftier solutions. As a starting point though, margin is your best bet.

Two Simple guidelines

It is very difficult to recover from a spacing setup mid-crumble, and usually, the only way out is to rework the entire deal from the ground up. So how can we shield ourselves from these types of reputation-damaging solutions? Well, if you stick to the following guidelines, you are certain to end up with far fewer problems than before.

1. A space is defined by a single CSS value

DRY and/or the single-responsibility principle, I'm not quite sure what fits best here, but the guideline should be clear enough. If you need to create space, make sure it is defined and can be changed from a single property value in your CSS. That means:

no collapsing or adjoining margins
no adjoining margins and paddings
no adjoining paddings
no borders in the same color as the background (or other, equally ugly hacks)
...

Just none of it. When you see this happening, stop yourself and take an extra minute to figure out a better solution (and if you can't find one, flag to your PM that the CSS needs a more profound looking at).

2. The parent controls the layout of its children

This guideline may sound a bit more abstract, but it's not that difficult to grasp. As we construct pages from reusable building blocks, our CSS needs to mimic that setup. That's why a component should never come with built-in spacing. There is no way to predict in which context a component will be used, so we really shouldn't be making any assumptions on the spacing it needs.

It's the parent element that decides the position of a component. That's the only one who knows how its children should be arranged. Layout systems like grid and flexbox allow us to do exactly that (gap goes on the parent element), if you're using margins then the child selector is your friend. And if you're using utility class-based frameworks, the burden shifts to the templating logic, which should make sure no excess spacing exists (for example by removing spacing classes on the first/last child).

It's a simple enough guideline, but it's also an easy one to sin against, not in the least because component visualization tools (StoryBook and the like) give few indications of a component's factual boundaries. One thing that helped me tremendously was to include crop marks (the red crosses in the image below). They are relatively unobtrusive, yet a quick glance will reveal if unwanted spacing exists.

Conclusion

And that's all there is to it really. As long as you make sure that components don't bear excess spacing and that a space can be changed from a single value in the CSS, there's not a lot that can go wrong. Working with a robust component visualization tool (rather than working directly on templates) will provide extra protection against mishaps, but let's focus on prevention first.

With all the tools we have, it's a little embarrassing to have to face clients about something as basic and prevalent as spacing. There really is no excuse to have this be a problem in 2023, but all too often I come across projects that hide a convoluted layout mess, so there is clearly a need to address this. With a little care and focus, I'm sure we can make this a problem of the past.