DEV Community: Rohan Faiyaz Khan

How to Make an Accesible Auto Suggest with vanilla Javascript

Rohan Faiyaz Khan — Fri, 22 May 2020 17:47:27 +0000

What is an Auto Suggest?

Autosuggest, also referred to semantically as a Combobox, is a web component we are all familiar with. It is comprised of an input where a user can type, and a dropdown menu with suggestions that the user can select. Depending on the use case, there may be some extra caveats. Some components will autofill the user's response based on the suggests, some will require that the user select something, some will fire a network request and so on.

A component such as this is pervasive in the modern web, search boxes, form inputs, and so many things utilize a variation of this component. It is a wonder that there isn't a standard HTML element to handle them.

The datalist way

Well to be fair, there is one. The easiest way to go about making your own autosuggest would be to use HTML5's <datalist> element which is now widely supported across all browsers. The example from MDN shows how simple it is.

<label for="ice-cream-choice">Choose a flavor:</label>
<input list="ice-cream-flavors" id="ice-cream-choice" name="ice-cream-choice" />

<datalist id="ice-cream-flavors">
  <option value="Chocolate"> </option>
  <option value="Coconut"> </option>
  <option value="Mint"> </option>
  <option value="Strawberry"> </option>
  <option value="Vanilla"> </option>
</datalist>

However datalist comes with its own set of problems. The datalist behaviour isn't consistent across every browser and you are limited to a single line of text for displaying the options. Focus management is inconsistent and any sort of custom behaviour you want is going to cause more pain than you might expect. Feel free to try this out but the results might not be what you want.

If this is all you need then great. If not, let's look at a custom albeit harder way.

The combobox way

So if <datalist> doesn't work you will have to devise your own solution using a combination of an input and a list that can be shown and hidden using CSS. Seems simple right? Well there is still a problem we need to consider and that is accessibility. When we use a <select> element the browser implements accessibility features out of the box, the user than scroll up and down using the arrow keys, and use keyboard controls to open and close the dropdown. Assistive software for users with disabilities know how to announce that the element has a dropdown, and whether or not the dropdown is open.

Using a simple <input type="text"> tag followed by a <ul> list will not give us these benefits out of the box, and so we need to code them in ourselves. The WAI-ARIA widget for an autosuggest is called a combobox and the official WAI-ARIA guidelines outline how to implement it while still maintaining accessiblity.

Note that you could perhaps use a library to implement this and that could work but a library might not have every feature you want or have features you don't want. Some of them are also not completely accessible. Even if you are using a library that you like, it is good to learn how it works on the inside.

Accessibility Requirements

Using the official WAI-ARIA guidelines as reference, we can identify some features that our component needs to have to ensure it is accessible. Ignoring some optional cases or ones that are not applicable to our use case, we can list the requirements as follows.

1. Aria roles, states and properties

The container needs to have role="combobox"
The input field inside the combobox needs to have role="textbox"
Combobox element contains or owns an element that has role listbox, tree, grid, or dialog. For our use case, we will be using a listbox
The textbox element has aria-controls set to a value that refers to the combobox popup element.
When the combobox popup is not visible, the element with role combobox has aria-expanded="false". When the popup element is visible, aria-expanded="true".
When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has aria-activedescendant set to a value that refers to the focused element within the popup.
When a suggested value is visually indicated as the currently selected value, the option containing that value has aria-selected set to true.
If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labelling element.

2. Keyboard interaction

When focus is on the textbox:
- Down Arrow: If the popup is available, moves focus into the popup
- Escape: Dismisses the popup if it is visible
When focus is on the listbox:
- Enter: Accepts the focused option in the listbox by closing the popup and placing the accepted value in the textbox with the input cursor at the end of the value.
- Escape: Closes the popup and returns focus to the textbox.
- Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right. If the input cursor is on the right-most character, the cursor does not move.
- Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left. If the input cursor is on the left-most character, the cursor does not move.
- Any printable character: Returns the focus to the textbox without closing the popup and types the character.
- Down Arrow: Moves focus to and selects the next option. If focus is on the last option, either returns focus to the textbox or does nothing.
- Up Arrow: Moves focus to and selects the previous option. If focus is on the first option, either returns focus to the textbox or does nothing.
- Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right. If the input cursor is on the right-most character, the cursor does not move.
- Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left. If the input cursor is on the left-most character, the cursor does not move.
- Any printable character: Returns the focus to the textbox without closing the popup and types the character.

Implementation

Now that we have our requirements out of the way let us implement this. As I do with all my blog posts, I have implemented this in Codesandbox which you can view here if you are the type to dive straight into the code.

Markup and styles

First of all let's set the markup. Of course the specifics of the markup will depend entirely on you as long as fulfill the accessibility requirements listed above. Here is my implementation. I am using a container div as my combobox container which contains an input that serves the role of textbox and an empty ul with a role of listbox. There is also a button containing an svg arrow for toggling the list.

<label for="autocomplete-input" id="autocomplete-label">'
   Type a name of your favorite color
</label>

<!-- Combobox container -->
<div
  class="autocomplete__container"
  role="combobox"
  aria-labelledby="autocomplete-label"
>
  <input
    role="textbox"
    aria-expanded="false"
    aria-controls="autocomplete-results"
    id="autocomplete-input"
    class="autocomplete__input"
  />
  <!-- Arrow for toggling the dropdown -->
  <button aria-label="toggle dropdown" class="autocomplete__dropdown-arrow">
    <svg width="10" height="5" viewBox="0 0 10 5" fill-rule="evenodd">
      <title>Open drop down</title>
      <path d="M10 0L5 5 0 0z"></path>
    </svg>
  </button>
  <ul
    role="listbox"
    id="autocomplete-results"
    class="autocomplete__results"
  >
     <!-- This is where we will be inserting our list items -->
  </ul>
</div>

The children of the listbox which we will dynamically enter will look like this. The tabindex="0" enables this element to be focused.

<li class="autocomplete-item" id="autocomplete-item-index" role="listitem" tabindex="0">
   <!-- content -->
</li>

Here are the styles that make this work. Notice that I use the visible class on the list and the expanded class on the dropdown as state indicators.

.autocomplete__container {
  position: relative;
  margin-top: "0.8rem";
  width: 100%;
  max-width: 350px;
}

.autocomplete__results.visible {
  visibility: visible;
}

.autocomplete__input {
  display: block;
  width: 100%;
  padding: 0.4rem 0rem 0.4rem 1rem;
  border: 2px solid hsl(212, 10%, 80%);
  border-radius: 5px;
}

.autocomplete__input:focus {
  border-color: hsl(221, 61%, 40%);
}

.autocomplete__dropdown-arrow {
  position: absolute;
  right: 0;
  top: 0;
  background: transparent;
  border: none;
  cursor: pointer;
  height: 100%;
  transition: transform 0.2s linear;
}

.autocomplete__dropdown-arrow.expanded {
  transform: rotate(-180deg);
}

.autocomplete__results {
  visibility: hidden;
  position: absolute;
  top: 100%;
  margin-top: 0;
  width: 100%;
  overflow-y: auto;
  border: 1px solid #999;
  padding: 0;
  max-height: 200px;
}

.autocomplete__results > li {
  list-style: none;
  padding: 0.4rem 1rem;
  cursor: pointer;
}

.autocomplete__results > li:hover {
  background: hsl(212, 10%, 60%);
}

.autocomplete__results > li:focus {
  background: hsl(212, 10%, 70%);
}

Toggling the listbox

Getting started with the javascript, let's first handle opening and closing of the listbox. There are several triggers for this such as clicking on the input, focusing on the input and pressing the down arrow, and clicking the toggle dropdown arrow. There are also several triggers for closing, clicking outside the listbox, pressing the escape key while the input is focused and selecting an option in the listbox. It is best if we encapsulate the logic for opening and closing so we can reuse it.

// Extracting the relevant DOM nodes
const input = document.getElementById("autocomplete-input");
const resultsList = document.getElementById("autocomplete-results");
const dropdownArrow = document.querySelector(".autocomplete__dropdown-arrow");
const comboBox = document.querySelector(".autocomplete__container");

// Boolean used for signalling
let isDropDownOpen = false;

// Signals which list item is focused, useful for updown keyboard navigation
let currentListItemFocused = -1;

function openDropdown(){
  isDropDownOpen = true;
  resultsList.classList.add("visible");
  dropdownArrow.classList.add("expanded");
  comboBox.setAttribute("aria-expanded", "true");
}

function closeDropdown() {
  isDropDownOpen = false;
  resultsList.classList.remove("visible");
  dropdownArrow.classList.remove("expanded");
  comboBox.setAttribute("aria-expanded", "false");
  input.setAttribute("aria-activedescendant", "");
}

Populating the list with data

For the sake of this example I will be populating my list with static data. This can easily be modified to take in data from an API if you wish so.


const colors = [
  "Red",
  "Orange",
  "Yellow",
  "Green",
  "Blue",
  "Cyan",
  "Violet",
  "Black",
  "White"
];


// Take an input array of string values and insert them into the list
function setResults(results) {
  if (Array.isArray(results) && results.length > 0) {

    // Transform array of strings to a list of HTML ul elements
    const innerListItems = results
      .map(
        (item, index) =>
          `<li class="autocomplete-item" 
             id="autocomplete-item-${index}" 
             role="listitem" 
             tabindex="0"
            >
                ${item}
           </li>`
      )
      .join("");

    resultsList.innerHTML = innerListItems;

    // Reset focus when list changes
    currentListItemFocused = -1;
  }
}

setResults(colors);

Handling focusing and selecting a list item

Focusing and selecting is a simple process but you do need to ensure the appropriate ARIA properties are set as per our requirements.

Note that for certain use cases you may want to disable the input on selection as well and add a button (or Backspace key) to clear it.

function focusListItem(listItemNode) {
  const id = listItemNode.id;
  input.setAttribute("aria-activedescendant", id);
  listItemNode.focus();
}

function selectValue(listItemNode) {
  const value = listItemNode.innerText;
  input.value = value;
  listItemNode.setAttribute("aria-selected", "true");
  input.removeAttribute("aria-activedescendant");
  input.focus();
  closeDropdown();
}

Adding click handlers

We need click handlers for three things:

Clicking the input opens the listbox
Clicking outside closes it
Clicking the arrow toggles the listbox
Clickung an option from the list selects it

input.addEventListener("click", openDropdown);

dropdownArrow.addEventListener("click", event => {
  event.preventDefault();
  if (!isDropDownOpen) {
    openDropdown();
  } else {
    closeDropdown();
  }
});

document.addEventListener("click", () => {
  const dropdownClicked = [
    input,
    dropdownArrow,
    ...resultsList.childNodes
  ].includes(event.target);

  if (!dropdownClicked) {
    closeDropdown();
  }
);

resultsList.addEventListener("click", event => {
  if ([...resultsList.childNodes].includes(event.target)) {
    selectValue(event.target);
  }
});

Adding keyboard controls

Keyboard controls are a bit complicated as we need to make sure our list is completely navigable by keyboard and follows the conditions in the accessibility requirements.

One thing that might trip up people is scrolling. If you have a long list you will want to allow scrolling, but pressing up and down in a scrollable view will cause the view to scroll. As we want to use up and down arrow keys for navigation we need to prevent this with an event.preventDefault(). Then simply focusing each element as we navigate to it will cause said element to scroll into view.


function handleKeyboardEvents(event) {
  const listItems = resultsList.childNodes;
  let itemToFocus = null;

  switch (event.key) {
    case "ArrowDown":
      event.preventDefault();
      if (currentListItemFocused < listItems.length - 1) {
        if (!isDropDownOpen) {
          openDropdown();
        }
        currentListItemFocused = currentListItemFocused + 1;
        itemToFocus = listItems.item(currentListItemFocused);
        focusListItem(itemToFocus);
      }
      break;
    case "ArrowUp":
      event.preventDefault();
      if (currentListItemFocused > 0) {
        currentListItemFocused = currentListItemFocused - 1;
        itemToFocus = listItems.item(currentListItemFocused);
        focusListItem(itemToFocus);
      }
      break;
    case "Home":
      if (currentListItemFocused > 0) {
        currentListItemFocused = 0;
        itemToFocus = listItems.item(currentListItemFocused);
        focusListItem(itemToFocus);
      }
      break;
    case "End":
      if (currentListItemFocused < listItems.length - 1) {
        currentListItemFocused = listItems.length - 1;
        itemToFocus = listItems.item(currentListItemFocused);
        focusListItem(itemToFocus);
      }
      break;
    case "Enter":
      event.preventDefault();
      if (!isDropDownOpen) {
        openDropdown();
      } else {
        if (listItems[currentListItemFocused].innerText) {
          selectValue(listItems[currentListItemFocused]);
        }
      }
      break;
    case "Escape":
      if (isDropDownOpen) {
        closeDropdown();
      }
      break;
    default:
       if (event.target !== input) {

        // Check if list is focused and user presses an alphanumeric key, or left or right
        if (/([a-zA-Z0-9_]|ArrowLeft|ArrowRight)/.test(event.key)) {

          // Focus on the input instead
          input.focus();
        }
      }     
      break;
  }
}

input.addEventListener("keydown", handleKeyboardEvents);
resultsList.addEventListener("keydown", handleKeyboardEvents);

Notice the default case which fulfills the last three conditions for keyboard controls in the accessibility requirements. If the user presses left, right or any printable key we need to return focus to the input field. We can use a simple regular expression to test for this and focus the input if needed. Simply focusing on the input will cause the characters to be printed on the input instead.

Deboucing input (optional)

We have covered almost everything except filtering the list results when we type. Before we do this though I want to briefly cover debouncing which you will certainly want if you are either:

Sending network requests with each input
Performing an expensive filter function

What a debouncer does is wait until your input has stopped changing for a set timeout before launching the callback, thus reducing unnecessary calls to it. If you don't need a debounce feel free to skip this.

let bounce = undefined;
function debounce(callback) {
  clearTimeout(bounce);
  bounce = setTimeout(() => {
    callback();
  }, [500]);
}

Filtering input

Finally once all our bases have been covered we can write our filter function that gets called when the user types. This function will vary completely based on your requirements. I will demonstrate a very simple example using a very simple regular expression that checks if the word starts with the input string entered by the user.

function filter(value) {
  if (value) {
    const regexToFilterBy = new RegExp(`^${value}.*`, "gi");
    filteredResults = colors.filter(color => regexToFilterBy.test(color));
  } else {
    filteredResults = [...colors];
  }
  setResults(filteredResults);
}

input.addEventListener("input", event => {
  const value = event.target.value;

  debounce(() => {
    filter(value);
    if (!isDropDownOpen) {
      openDropdown();
    }
  });
});

Conclusion

With that our implementation should be off and working. You can test it in the aforementioned Codesandbox which you can view here before implementing yourself.

I should add however that while I have tried my best to adhere to the official WAI-ARIA guidelines, screen-readers widely vary in terms of what they announce to the user. As I am still new to learning about accessibility it is entirely possible that I have missed something. Please feel free to suggest improvements to this code either via a comment or a pull request to the repository.

Turning your React Component into a Finite State Machine With useReducer

Rohan Faiyaz Khan — Mon, 27 Jan 2020 14:21:03 +0000

Photo by Stéphane Mingot. This post was originally shared on my blog

Why state machines are relevant to frontend development

A finite state machine is not a new concept in the world of computing or mathematics. It is a mathematical model that be in one a few finite states. Transition to a new state could depend on the previous state and a set of external factors.

This model has become more relevant recently in the field of UI development because we have shifted a lot of the state management to the frontend now. Being a React developer one of the first things I learned was how to manage state inside a component and how to manage global state with Redux. The naive approach I usually used was to have booleans such as isLoading and isError and render my component based on that.

const MyComponent = () => {
   const [state, setState] = useState({ isLoading: false, isError: false })

   const clickHandler = (e) => {
      setState({ isLoading: true })
      sendNetworkRequest()
         .then(() => setState({ isLoading: false }))
         .catch(() => setState({ isError: true, isLoading: false })
   }

   return (
       <div>
          <button onClick={clickHandler}>Send request</button> 
          { state.isLoading? "Loading" : state.isError ? "There has been an error" : "Success!" }
       </div>
   )

}

This is fine for the most part. The code above is very easy to skim through and it is easy to tell what conditions in state is doing what, Problem is though this approach scales horribly. In real life scenarios there are more factors that could change the loading and error states, and there might also be a success or failure state or even an idle state, and state transition may depend on the previous state. What starts innocently as a simple boolean state management system turns into a nightmare plate of spaghetti.

const MyComponent = (props) => {
   const [state, setState] = useState({ 
      isLoading: false, 
      isError: false,
      isSuccess: false,
      isIdle: true
   })

   const clickHandler = (e) => {
      setState({ isLoading: true })
      sendNetworkRequest()
         .then((result) => {
             if(/* some arbritrary condition */){
                setState({ isLoading: false, isIdle: false, isSuccess: true }))
             }else if(/* some other arbitrary condition */){
                setState({ isIdle: false, isSuccess: true }))
             }
         }
         .catch(() => setState({ isSuccess: false, isError: true, isLoading: false })
   }

   return (
       <div>
          { state.isIdle ? "Click to send request"
                         : state.isLoading ? "Loading" 
                         : state.isError ? "There has been an error" : "Success!" }
       </div>
   )

}

I can tell you from personal experience that an example like this is very much possible and an absolute nightmare to deal with. We have so many conditional checks that its very hard to debug exactly what is happening. There is also several bugs, for example, when sending a request we do not set isIdle to false and since that is the first check in the return statement, the loading state never gets shown. These kind of bugs are very hard to spot and fix, and even harder to test.

While there are many ways to fix this component, the method that I prefer is to turn it into a finite state machine. Notice that the states we have are all mutually exclusive, i.e. our component can only exist in one possible state at one time- either idle, success, failure or loading. If we limit ourselves to these possibilities, then we can limit the possible transitions as well.

The state-reducer pattern

The object state pattern is something I have discussed in detail before and is likely familiar with anyone that has used redux. Its a pattern for changing state using an action and the existing state as inputs, Using it, we can limit our states and our actions which limits the number of possibilities we will have to deal with to the below.

const ComponentStates = Object.freeze({
   Idle: "IDLE",
   Loading: "LOADING",
   Success: "SUCCESS",
   Failure: "FAILURE"
})   

const ActionTypes = Object.freeze({
   RequestSent: "REQUEST_SENT",
   RequestSuccess: "REQUEST_SUCCESS",
   RequestFailure: "REQUEST_FAILURE"
})

This is very helpful for a number of reasons. If we know there are only going to be three possible actions we only have to account for three possible mutations to state. This of course becomes exponentially more complicated if we also account for current state but even so it is better than what we had before. Furthermore we don not have to juggle multiple conditional checks, we only have to keep track of what condition dispatch which actions, and what actions lead to what state change. This in my experience is a far easier mental debt.

function reducer(state, action){
   switch(action.type){
      case ActionTypes.RequestSent:
         return ComponentStates.Loading
      case ActionTypes.RequestSuccess:
         return ComponentStates.Success
      case ActionTypes.RequestFailure:
         return ComponentStates.Failure      
      default:
         return ComponentStates.Idle
      }
}

The useReducer hook

Finally we will use useReducer which is one of the base hooks provided by React. It is basically an extension of useState except that it takes a reducer function and initial state as arguments and returns a dispatch function along with state.

For those unfamiliar with redux, the dispatch function is used to dispatch an action, which includes a type (one of our action types) and an optional payload. The action is then reduced by our reducer function, resulting in a new state. With this knowledge we can complete our state machine.

const MyComponent = (props) => {
   const initialState = ComponentStates.Idle
   const [state, dispatch] = useReducer(reducer, initialState)

   const clickHandler = (e) => {
      dispatch({ type: ActionTypes.RequestSent })
      sendNetworkRequest()
         .then((result) => {
             if(/* some arbritrary condition */){
                dispatch({ type: ActionTypes.RequestSuccess }) 
             }
         }
         .catch(() => {
             dispatch({ type: ActionTypes,RequestFailed })
         })
   }

   return (
       <div>
          { state === ComponentStates.Idle ? "Click to send request"
                         : state === ComponentStates.Loading ? "Loading" 
                         : state === ComponentStates.Failure ? "There has been an error" 
                         : "Success!" }
       </div>
   )

}

You can implement this however you like

This is simply my solution to a complex problem and your problem domain may not match with mine. However I hope this gives some inspiration as to how you could implement a state management solution yourself. Thank you for reading and I hope this helps!

Recreating the material design ripple effect in React

Rohan Faiyaz Khan — Wed, 18 Dec 2019 13:44:29 +0000

Cover image by Linus Nylund on Unsplash

Link to original post my blog

Rippling in React

We have all seen the ripple effect animation which was part of the material design recommendation. It presents itself as a circle that appears at the point of a click and then enlarges and fades away. As a UI tool, it is a fantastic and familiar way to let the user know that there has been a click interaction.

While the ripple effect is perfectly doable in Vanilla JS, I wanted a way to integrate it with my React components. The easiest way would be to use Material-UI which is a popular UI library. This is a very good idea in general if you want a solid UI library that generates UI out of the box. However for a small project it makes little sense to learn to work with a large library just to achieve one effect. I figured there had to be a way to do without a UI library.

I looked through a lot of projects implementing something similar this over Github, Codepen and Codesandbox and took inspiration from some of the best ones. The ripple effect is possible on any web framework because it is achieved through a clever bit of CSS.

For advanced readers who want to go straight to the code and skip the explanation behind it, feel free to browse it in this Code Sandbox.

This is my implementation of the CSS for this effect.



<button class="parent">
  <div class="ripple-container">
    <span class="ripple"></span>
  </div>
</button>



.parent {
  overflow: hidden;
  position: relative;
}

.parent .ripple-container {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}

.parent .ripple-container span {
  position: absolute;
  top: ...
  right: ...
  height: ...
  width: ...
  transform: scale(0);
  border-radius: 100%;
  opacity: 0.75;
  background-color: #fff;
  animation-name: ripple;
  animation-duration: 850ms;
}

@keyframes ripple {
  to {
    opacity: 0;
    transform: scale(2);
  }
}

The overflow: hidden property prevents the ripple from rippling out of the container. The ripple is a circie (border-radius: 100%) which starts at a small size and grows large as it fades out. The growing and fade out animations are achieved by manipulating transform: scale and opacity in our ripple animation.

We will however need to dynamically provide a few styles using Javascript. We need to find the positional coordinates i.e. top and left, which are based on where the user clicked, and the actual height and width, which depend on the size of the container.

So here's what our component will need to do.

Render an array of ripples (spans) in the container <div>
On mouse down, append a new ripple to the array and calculate the ripple's position and size
After a delay, clear the ripple array to not clutter up the DOM with old ripples
Optionally take in the ripple duration and color. We want to be able to customize the ripple's behaviour if needed.

Let's get started

I am using styled-components for my styles as I am comfortable with it but feel free to use whatever styling option you prefer. The first thing we will do is include the above CSS in our components.



import React from 'react'
import styled from 'styled-components'

const RippleContainer = styled.div`
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;

  span {
    transform: scale(0);
    border-radius: 100%;
    position: absolute;
    opacity: 0.75;
    background-color: ${props => props.color};
    animation-name: ripple;
    animation-duration: ${props => props.duration}ms;
  }

  @keyframes ripple {
    to {
      opacity: 0;
      transform: scale(2);
    }
  }
`;

Notice that I left the background-color and animation-duration to be fetched from props. This is so that we can dynamically set these values later in our props. Let's define those now:



import React from 'react'
import styled from 'styled-components'
import PropTypes from 'prop-types'

...

const Ripple = ({ duration = 850, color = "#fff" }) => {

  ...

}

Ripple.propTypes = {
  duration: PropTypes.number,
  color: PropTypes.string
}

export default Ripple

Next up we want to define an array for our ripples and create a function for adding ripples. Each element of the array will be an object with x, y and size properties, which are information needed to style the ripple. In order to calculate those values, we will fetch them from a mousedown event.




const Ripple = ({ duration = 850, color = "#fff" }) => {
  const [rippleArray, setRippleArray] = useState([]);

  const addRipple = (event) => {

    const rippleContainer = event.currentTarget.getBoundingClientRect();
    const size = rippleContainer.width > rippleContainer.height
                  ? rippleContainer.width
                  : rippleContainer.height;

    const x = 
      event.pageX - rippleContainer.x - rippleContainer.width / 2;
    const y = 
      event.pageY - rippleContainer.y - rippleContainer.width / 2;
    const newRipple = {
      x,
      y,
      size
    };

    setRippleArray((prevState) => [ ...prevState, newRipple]);
  }

The above code uses a bit of the Browser DOM API. getBoundClientRect() allows us to get the longest edge of the container, and the x and y coordinates relative to the document. This along with MouseEvent.pageX and MouseEvent.pageY allows us to calculate the x and y coordinates of the mouse relative to the container. If you want to learn more about how these work, there are much more detailed explanations for getBoundClientRect, MouseEvent.pageX and MouseEvent.pageY at the wonderful MDN Web Docs.

Using this, we can now render our array of ripples.



return (
    <RippleContainer duration={duration} color={color} onMouseDown={addRipple}>
      {
        rippleArray.length > 0 &&
        rippleArray.map((ripple, index) => {
          return (
            <span
              key={"ripple_" + index}
              style={{
                top: ripple.y,
                left: ripple.x,
                width: ripple.size,
                height: ripple.size
              }}
            />
          );
        })}
    </RippleContainer>
  );

RippleContainer is our styled component that takes in the duration and color as props along with our newly created addRipple as a onMouseDown event handler. Inside it we will map over all our ripples and assign our calculated parameters to their corresponding top, left, width and height styles.

With this we are done adding a ripple effect! However, there is one more small thing we will need to do with this component and that is clean the ripples after they are done animating. This is to prevent stale elements from cluttering up the DOM.

We can do this by implementing a debouncer inside a custom effect hook. I will opt for useLayoutEffect over useEffect for this. While the differences between the two merit an entire blog post of its own, it is suffice to know that useEffect fires after render and repaint while useLayoutEffectfires after render but before repaint. This is important here as we are doing something that has an immediate impact on the DOM. You can read more about this here.

Below is our custom hook's implementation and usage where we pass a callback to clear the ripple array. We use a timeout that we can reset in order to create a simple debouncer. Essentially everytime we create a new ripple, the timer will reset. Notice that the timeout duration is much bigger than our ripple duration.



import React, { useState, useLayoutEffect } from "react";

...

const useDebouncedRippleCleanUp = (rippleCount, duration, cleanUpFunction) => {
  useLayoutEffect(() => {
    let bounce = null;
    if (rippleCount > 0) {
      clearTimeout(bounce);

      bounce = setTimeout(() => {
        cleanUpFunction();
        clearTimeout(bounce);
      }, duration * 4);
    }

    return () => clearTimeout(bounce);
  }, [rippleCount, duration, cleanUpFunction]);
};

const Ripple = ({ duration = 850, color = "#fff" }) => {
  const [rippleArray, setRippleArray] = useState([]);

  useDebouncedRippleCleanUp(rippleArray.length, duration, () => {
    setRippleArray([]);
  });

  ...

Now we are done with our Ripple component. Let's build a button to consume it.



import React from "react";

import Ripple from "./Ripple";

import styled from "styled-components";

const Button = styled.button

  overflow: hidden;

  position: relative;

  cursor: pointer;

  background: tomato;

  padding: 5px 30px;

  color: #fff;

  font-size: 20px;

  border-radius: 20px;

  border: 1px solid #fff;

  text-align: center;

  box-shadow: 0 0 5px rgba(0, 0, 0, 0.4);

;

function App() {

  return (

    <div className="App">

      <Button>

        Let it rip!

        <Ripple />

      </Button>

      <Button>

        Its now yellow!

        <Ripple color="yellow" />

      </Button>

      <Button>

        Its now slowwwww

        <Ripple duration={3000} />

      </Button>

    </div>

  );

}

And that's it

We now have ripples in all shades and speeds! Better yet our ripple component can reused in pretty much any container as long as they have overflow: hidden and position: relative in their styles. Perhaps to remove this dependency, you could improve on my component by creating another button that already has these styles applied. Feel free to have fun and play around with this!

React Custom Hooks: What, Why and How

Rohan Faiyaz Khan — Wed, 09 Oct 2019 18:04:46 +0000

Photo by chuttersnap on Unsplash

Now that its been a year since React hooks has been released, I can safely say that I absolutely love them and cannot imagine writing React components without them anymore.

However hooks come with some of their own limitations, one of the biggest being that they must be used in a React functional component. This is by design, because we would like our stateful logic to be tied to the component where they are needed and not just any function. However we do sometimes want to reuse our stateful logic between components. Before hooks, this was only possible through higher-order components and render props, a pattern common in libraries such as Redux with its connect(Component) or React Router's withRouter(Component). I personally don't prefer writing higher-order components cause they are a slightly difficult abstraction that come with their set of gotchas. Thankfully, hooks provide a much easier way to share stateful logic without requiring you learn a difficult abstraction, and that way is custom hooks,

Custom hooks are simply a wrapper function surrounding our existing hooks. That's it! The only catch is that in order for React to recognize that a function is a custom hook, its name must start with use. The same rules for using hooks also apply to custom hooks, for instance they cannot to nested in a condition or a loop and also cannot be called outside a functional component or yet another hook.

Note that custom hooks require you to be familiar with hooks themselves, atleast useState and useEffect. If you haven't used I'd really recommend looking into them first cause they are the core building blocks of every custom hook you could make.

Let's do a quick example to see we write custom hooks. Suppose we have an imaginary app where once users login we fetch make an API request to fetch a list of their friends. Using functional components and hooks our component would look like this.


import React, {useState, useEffect} from 'react'

function Dashboard(props){
    const [friends, setFriends] = useState([])
    const [error, setError] = useState({})
    ussEffect(() => {
        if(props.user.loggedIn){
            fetch(`/api/${props.user.id}/friends`).then(response => {
                response.json().then( friends => setFriends(friends))
            })
            .catch(error => setError(error)
        }
    }, [props.user.isLoggedIn, props.user.id])

    return <div>
        { friends.length > 0 ? 
            friends.map(friend => <div key={friend.id}>{friend.name}</div> 
            : error.message
        </div>
}

export default Dashboard

Suppose we would like to replicate this behaviour in another component, such as a chatbox that displays friends that are online. Our stateful logic would mostly be the same. Instead of copying our code over, a better approach to the problem would be to extract out this logic into a custom hook. We'll call our custom hook useFriendList.

// useFriendList.js

export default function useFriendList(user){
    const [friends, setFriends] = useState([])
    const [error, setError] = useState({})
    ussEffect(() => {
        if(user.loggedIn){
            fetch(`/api/${user.id}/friends`).then(response => {
                response.json().then( friends => setFriends(friends))
            })
            .catch(error => setError(error)
        }
    }, [user.id, user.isLoggedIn])

    return [friends, error]
}

Now we can simply refactor our previous component as such.

import React from 'react'
import useFriendList from './useFriendList'

function Dashboard(props){
    const [friends, error] = useFriendList(props.user)

    return <div>
        { friends.length > 0 ? friends.map(friend => <div key={friend.id}>{friend.name}</div> 
            : error.message
        </div>
}

export default Dashboard

And that's really all there is to it. Not only does our component look a lot cleaner, but any time we need to reuse this logic in a component, we just call our custom hook.

Personally I like this pattern a lot more than higher-order components because unlike HOC, custom hooks do not require you to think any differently than just using hooks normally. All you have to do is throw your existing logic in a wrapper function. This makes concepts such as component composition a lot more accessible and easier to get started with. If you found custom hooks to be a difficult concept I hope this post makes you want to give it a try.

Sharing state like Redux with React's Context API

Rohan Faiyaz Khan — Sun, 15 Sep 2019 09:03:08 +0000

The pains of growing state

In learning React, one of the first challenges I faced was figuring out state management. State is a vital part of any application that has more complexity than a simple blog or brochure site. React has a fantastic toolset to manage component level state both in the case of functional components with hooks, and class based components. However global state is a bit of a different story.

Almost every advanced feature such as authentication, shopping carts, bookmarks etc. heavily rely on state that multiple components need to be aware of. This can be done by passing state through props but as an application grows this gets complicated very fast. We end up having to pipe state through intermediary components and any change in the shape of the state needs to reflected in all of these components. We also end up with a bunch of code unrelated to the concern of the intermediary component, so we learn to ignore it. And if Uncle Bob taught me anything, the code we ignore is where the bugs hide.

The solution: Redux

Redux was born out of the problem of global state handling. Built by Dan Abramov and his team, Redux provided a global store independant of local state that individual components could access. Furthermore it comes with some high level abstractons for dealing with state, such as the state reducer pattern.

Wait, slow down, the state reducer what now?

Yes I hear you, for this was my exact reaction when I heard of these words put together for the first time. The reducer pattern is a popular pattern even outside of Redux, and implements a way to change state. A reducer function is a pure function (i.e. has no external state or side effects) that simply takes in the previous state and an action, and returns the new state. It looks like this below.

function reducer(state, action){
    switch(action){
        case "increment":
            return state + 1
        case "decrement":
            return state - 1
        default:
            return state
    }
}

This pattern allows us to alter state predictably which is important because we need to how our application might react to changes in state. Under the pattern, mutating state directly is heavily discouraged.

Redux also provides us with the action creator pattern, which is simply a way to organise how we dispatch our actions. Combined with the state reducer pattern, this gives us great tools to organize our global state management.

Sounds good, so what's the problem?

While redux is great and I personally am a big fan of it, it has its fair share of detractors.

The first problem a lot of people have is that it is very boilerplate-y. This is especially apparent when you have an app that initially doesn't need global state, and then later on you realize you do and then *BOOM* 200+ lines added in one commit. And every time global state has to be pulled in for a component, this extra boilerplate has to added in.
Redux is opinionated and imposes limitations. Your state has to be represented as objects and arrays. Your logic for changing states have to be pure functions. These are limitations that most apps could do without.
Redux has a learning curve of its own. This true for me personally, because React seemed very fun as a beginner until I hit the wall of Redux. These advanced high level patterns are something a beginner is not likely to appreciate or understand.
Using Redux means adding about an extra 10kb to the bundle size, which is something we would all like to avoid if possible.

Several other state management libraries have propped up such as MobX to solve the shortcomings of Redux, but each have their own trade-offs. Furthermore, all of them are still external dependencies that would bulk up the bundle size.

But surely something this important has a native implementation? Right?

Well there wasn't, until...

All hail the magical context!

To be fair, the Context API has been around for a while, but it has gone through significant changes and alterations before it became what it is today. The best part about it is that it does not require any npm install or yarn install, it's built in with React, I personally have found the current iteration of the Context API to be just as powerful as Redux, especially when combined with hooks.

But there was a roadblock to learning, that being the official React documentation is terrible at explaining how powerful the Context API is. As a result, I dug through it and implemented a simple login system so that you don't have to.

Enough talk, show me how this works already

All we will be doing is logging in (using a fake authentication method wrapped in a Promise), and changing the title with the username of the logged in user. If you'd rather skip all the explanantion and just look at the code, feel free to do so.

The first thing we need to do to use context is React.createContext(defaultValue). This is a function that returns an object with two components:

myContext.Provider - A component that provides the context to all its child elements. If you have used Redux before, this does the exact same thing as the Provider component in the react-redux package
myContext.Consumer - A component that is used to consume a context. As we shall soon see however, this will not be needed when we use the useContext hook

Lets use this knowledge to create a store for our state.

// store.js

import React from 'react';

const authContext = React.createContext({});

export const Provider = authContext.Provider;
export const Consumer = authContext.Consumer;
export default authContext;

Notice below that the defaultValue parameter passed to createContext is an empty object. This is because this parameter is optional, and is only read when a Provider is not used.

Next we have to wrap our application in the Provider so that we can use this global state. Provider needs a prop called value which is the value of the state being shared. We can then use the useContext hook in the child component to retrieve this value.

function App(){
    return (
        <Provider value={someValue}>
            <ChildComponent />
        </Provider>
    )
}

function ChildComponent(){
    const contextValue = useContext(myContext)
    return <div>{contextValue}</div>
}

However you might notice a problem with this method. We can only change the value of the state in the component containing the Provider. What if we want to trigger a state change from our child component?

Well remember the reducer state pattern I talked about above? We can use it here! React provides a handy useReducer hook which takes in a reducer function and an initialState value and returns the current state and a dispatch method. If you have used redux before, this is the exact same reducer pattern we would observe there. Then we have pass the return value of the useReducer hook as the value inside <Provider>.

Lets define a reducer.

// reducers/authReducer

export const initialAuthState = {
    isLoggedIn: false,
    username: '',
    error: ''
};

export const authReducer = (state, action) => {
    switch (action.type) {
        case 'LOGIN':
            return {
                isLoggedIn: true,
                username: action.payload.username,
                error: ''
            };
        case 'LOGIN_ERROR':
            return {
                isLoggedIn: false,
                username: '',
                error: action.payload.error
            };
        case 'LOGOUT':
            return {
                isLoggedIn: false,
                username: '',
                error: ''
            };
        default:
            return state;
    }
};

Now we can use our reducer in our <Provider>.

// App.js 

import React, { useReducer } from 'react';
import Router from './components/Router';
import { Provider } from './store';
import { authReducer, initialAuthState } from './reducers/authReducer';

function App() {
    const useAuthState = useReducer(authReducer, initialAuthState);
    return (
        <Provider value={useAuthState}>
            <Router />
        </Provider>
    );
}

export default App;

Now all components in our application will have access to the state and the dispatch method returned by useReducer. We can now use this dispatch method in our login form component. First we will grab the state from our context so we can check if the user is logged in so we can redirect them or if we need to render an error. Next we will attempt to login (using our fake authentication method) and dispatch an action based on either authentication is successful or not.

// components/LoginForm.jsx

import React, { useState, useContext, Fragment } from 'react';
import { Link, Redirect } from 'react-router-dom';
import authContext from '../store';
import attemptLogin from '../auth/fakeAuth';

const LoginForm = () => {
    const [ state, dispatch ] = useContext(authContext);
        const { isLoggedIn, error } = state;

    const [ fakeFormData, setFormData ] = useState({
            username: "Rohan", 
            password: "rohan123"
        });

    function onSubmit(event) {
        event.preventDefault();
        attemptLogin(fakeFormData)
            .then((username) => {
                dispatch({
                    type: 'LOGIN',
                    payload: {
                        username
                    }
                });
            })
            .catch((error) => {
                dispatch({
                    type: 'LOGIN_ERROR',
                    payload: {
                        error
                    }
                });
            })
            .finally(() => {
                setLoading(false);
            });
    }

    return (
        <Fragment>
            {isLoggedIn ? (
                <Redirect to="/" />
            ) : (
                <Fragment>
                    {error && <p className="error">{error}</p>}
                    <form onSubmit={onSubmit}>
                        <button type="submit">Log In</button>
                    </form>
                </Fragment>
            )}
        </Fragment>
    );
};

export default LoginForm;

Finally we will wrap up the landing component to show the logged in user's username. We will also toggle the welcome message to prompt a login or logout based on whether the user is already logged in or not, and will create a method to dispatch a logout.

// components/Hello.jsx

import React, { Fragment, useContext } from 'react';
import { Link } from 'react-router-dom';
import Header from './Header';
import authContext from '../store';

const Hello = () => {
    const [ { isLoggedIn, username }, dispatch ] = useContext(authContext);
    const logOut = () => {
        dispatch({
            type: 'LOGOUT'
        });
    };
    return (
        <Fragment>
            <Header>{`Well hello there, ${isLoggedIn ? username : 'stranger'}`}</Header>
            {isLoggedIn ? (
                <p>
                    Click <Link to="/" onClick={logOut}>here</Link> to logout
                </p>
            ) : (
                <p>
                    Click <Link to="/login">here</Link> to login
                </p>
            )}
        </Fragment>
    );
};

export default Hello;

And there you have it

We now have a fully functioning context-based state management system. To summarize the steps needed to create it:

We created a store using React.createContext()
We created a reducer using the useReducer hook
We wrapped our application in a Provider and used the reducer as the value
We used the useContext to retrieve the state and dispatched actions when necessary

You might be asking now whether this can completely replace Redux. Well, maybe. You might notice that we had to implement our own abstractions and structure when using the Context API. If your team is already used to the Redux way of doing things, then I don't see a lot of value in switching. But if you or your team does want to break away from Redux I would certainly recommend giving this a try.

Thank you for reading, and I hope you found this post useful.

Efficiency in the Editor: How I overcame my fear of Vim

Rohan Faiyaz Khan — Sat, 31 Aug 2019 13:13:18 +0000

A colleague at my previous job was once looking at my screen and mentioned that he was impressed with how quickly I was moving around within my code editor. Granted he was not a developer and came from a non-technical background, but his comment surprised me as speed apart from that of typing was not something that I had given much thought before. Navigating through my workspace using a combination of arrow keys, find, go-to-line and the navigation keys such as Home and End were things I had learned simply through practice.

But it made sense. We, programmers, tend to spend some time writing code and a lot more time reading code, jumping between different points in our codebase, and tweaking minor things here and there. A significant chunk of our time is spent navigating, referencing and refactoring. Simply typing code faster is not enough to boost my productivity, I had to navigate and traverse my code faster.

"Hey, did you try Vim?"

For the uninitiated Vim is a CLI based text editor that relies on short and expressive keyboard commands to do pretty much everything. Proponents of Vim argue that it is extremely inefficient to be constantly switching between your keyboard and mouse while typing, and your keyboard should really be able to do everything you need.

Vim was something recommended by a friend and I had seen several Youtubers use it. I noticed that watching a skilled Vim user at his job looked nothing short of wizardry. It seemed as if they could bend the text editor to their will at the tap of a few keystrokes. Above all it seemed so... intimidating.

All this editor kung fu that ditches the mouse seems way too complex for my meager self, and besides I rely on waaaay too many things on my VS Code setup. No way I am ditching that. Or at least, so I thought.

First thing I learned was VS Code had a fantastic extension that emulates Vim, which let me leverage the full force of my Prettier and ESLint setup while also using Vim. So there went one of my excuses. Second thing I learned was that Vim was not very difficult to get started in. One of my favorite web dev Youtubers Ben Awad is an avid Vim advocate and he recommend to start with vimtutor and then go cold turkey, i.e. use Vim for everything.

Vimtutor is a fantastic interactive tutorial that comes out of the box when you install Vim. It takes roughly 30 minutes to complete and taught me all I need to get started with Vim. I wondered why a lot of the Vim tutorials I would find online were for a bit more advanced users till I realized it was beause Vimtutor pretty much covered everything a beginner needs to know, and it did a lot better than a blog post ever could. After completing it, I went the cold turkey route and have been using nothing but Vim (inside VS Code of course) for the past month and here is what I learned from it.

It is intimidating for a reason

There is a learning curve associated with Vim, there is no doubt about that. For the first few days I was fumbling about blindly, needing to look up references for every little thing. Habits such as using the arrow keys for movement and backspace for correcting mistakes were so ingrained in my muscle meomry that they were really hard to let go of. And I was really slow, way slower than before, which made me seriously question whether this endeavour was even worth it.

However, within a few days I was learning how to be productive in Vim. I had to think less between actions and it was becoming more akin to muscle memory. After a week I had already caught to my old pace and after two weeks I had surpassed it.

Turns out people were right, there is infact a lot of efficiency to be gained from not dragging your hand to the mouse for every little motion you need to make. However, that is only a small part of what makes Vim so powerful, another major selling point is...

Vim is extremely expressive

Vim works using motions and commands. Motions annotate where the cursor should move and commands annotate the verb the action will perform.

The generic motion controls in Vim for left, down, up, right are h, j, k and l respectively, but that is boring and nothing your arrow keys couldn't already do. More interesting motions include word, back, and end which jump to the next word, previous word or end of current word respectively. These motions can also be modified, for instance 3w jumps forwards by 3 words and 5b jumps backward by 5 words. You can already see how this would allow you to quickly move around in your file.

Commands are verbs such as change, yank, delete and paste. But here's the fun part, the verbs do nothing unless combined with a motion. For instance, d2w will delete the next two words, yy will yank (or copy) the entire line and cj will allow you to change all contents upto the line below.

This is where the expressiveness of Vim comes into play. Because of the wild number of combinations possible, you can be very creative about how you choose to get your work done. As a result of this, you can very quickly go from thinking about doing an action and doing it, i.e. there is very little lag between thinking and doing.

Already with this knowledge I was productive and having fun but then I discovered perhaps the best part about Vim.

Macros for days!

Learning macros is where I realized I was never going to be able to go back to not using Vim. Macros allow you to repeat similar tasks. The most simplest form of this is the . (dot command), which repeats the last change. This is easier to explain with an example. Consider the HTML below.command.

<div class="image-container">
    <img src="image.jpg>
    <img src="image2.jpg>
    <img src="image3.jpg>
</div>

Suppose are using a lazy loading library and need to add a class with the name "lazy" at each image tag. We can do this in Vim by using /src (to find the first src attribute), i (to insert text) and then type class="lazy". From there on, we can hit n a few times to go to the next instance of src. and hit . to repeat the command.

However we might want to repeat tasks that involve more than one change. Worry not, for custom macros are here to the rescue. Custom macros can be recorded by pressing q followed up by the key you want to store the macro in. Pressing q again stops the recording. This is also easier to show rather than tell.

const array = [
    item_one,
    item_two,
    item_three,
    item_four,
    item_five
]

Suppose I copied this array for another file and the variables are written in snake case. However I have written the rest of my code in camel case and would like to convert these variables to camel case as well (itemOne). To do this, we can go to the top of the file and press j to go down a line. Next we start recording the macro with qe. To convert to camel case we can use f_ to move the cursor to the first underscore, and then x to delete it. Now our cursor will be on the "o", which we can capitalize by pressing ~. Finally we move to the start of the line with 0, and down once with j and end the recording with q.

To repeat the macro we can just hit @e and Vim will repeat the entire sequence of commands. We can also do 4@e and it will repeat the commands for all four of the remaining lines. Here you can see it in action.

Very efficient, right?

Yes, Vim has indeed increased my efficiency significantly to the point where I use it for absolutely everything including writing this blog post. It can significantly help you speed up for workflow and as a result possibly get more work done or have more free time to enjoy. If you are like me and you haven't touched Vim yet cause you found it intimidating or were on the fence about it, I do hope this post can convince to give it a try cause it is certainly a lot of fun.

NestJS GraphQL API with TypeORM and Postgres

Rohan Faiyaz Khan — Tue, 13 Aug 2019 06:45:51 +0000

Disclaimer: This was originally posted on my blog

In a previous post, I covered how to make a NestJS REST API using TypeORM and Postgres. While it is a relatively simple process to set up a REST API in NestJS, we still are left with the limitations of a REST API. REST depends on our endpoints being clearly defined and this is usually done using the frontend as a guide, cause obviously we want to provide the exact data the frontend needs.

But this is a problem. What if the frontend requirements change and we need an extra data field that is only available through a separate endpoint? Now we have to make two HTTP requests and we will have extra data which is wasteful for mobile internet usage. The other solution is to create a new endpoint on the backend, which is expensive.

Essentially, a REST api is too low level. We need something that offers a higher level of abstraction and that is GraphQL.

GraphQL is a query language specification created originally by Facebook as a solution to the problems described above. GraphQL offers a way for frontends to describe the exact data needed and the shape of the data. The data is defined on the backend as a GraphQL schema. A GraphQL request (known as a Query) looks like this:

{
    pokemon(id: 4) {
        name,
        types
    }
}

This returns a JSON response that looks like this:

{
    "data": {
        "pokemon": {
            "name": "Charmander",
            "types": ["Fire"]
        }
    }
}

You might notice that the data sent back follows the exact shape of the query. What about adding data though? We do that using GraphQL Mutations which look like this:

mutation{
    addPokemon(name: "Scorbunny", types: "Fire") {
        id,
        name,
        types
    }
}

This will give a response that looks something like this:

{
    "data": {
        "pokemon": {
            "id": 912,
            "name": "Scorbunny",
            "types": ["Fire"]
        }
    }
}

Of course there is a lot more to GraphQL than just that. If you want a more in depth look into what GraphQL is capable, there is no better place to start than the official documentation. The rest of this post will focus on creating a GraphQL API on the server side using NestJS and TypeORM.

Setting up the project

We will first install NestJS (if you don't already have it installed) using NPM and use the Nest CLI to scaffold a new Nest project

$ npm i -g @nestjs/cli 
$ nest new nest-app

The database I will choose to integrate with is Postgres although you can use any database of your choice. We will be using TypeORM as our ORM (Object Relation Mapping) which essentially removes the burden of writing raw SQL, as our ORM will handle communication with the database.

If you do not have Postgres installed, follow the steps to install Postgres on your OS. For instance you can use the official installer for Windows, use Homebrew on MacOS or apt on Ubuntu. Once postgres is installed, we will create a new database using the Postgres CLI. On Linux and MacOS the steps will be as follows:

$ sudo -u postgres psql
postgres=# createdb rohan
postgres=# \q
$ psql
rohan=# \password
rohan=# Enter new password:
rohan=# Retype new password:

Setting up dependencies and config

Firstly we will install the necessary dependencies. TypeORM is the suggested ORM and is very good for connecting with Postgres. NestJS also has its own way of configuring GraphQL which uses apollo-server under the hood.

yarn add pg typeorm @nestjs/typeorm @nestjs/graphql apollo-server-express graphql-tools type-graphql graphql

Next we will create a config file at the root of our project and call it ormconfig.json. This file is automatically pulled in by TypeORM.

// ormconfig.json
{
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "rohan",
    "password": "password",
    "database": "rohan",
    "entities": ["dist/**/*.entity.js"],
    "synchronize": true,
    "logging": true
}

In NestJS each component has its own module where we encapsulate everything associated to the module, including providers, controllers and other modules. The root module file is app.module.ts, and it is here that we will specify external modules our entire app will have access to, which are GraphQL and TypeORM. We will use it to set up a schema for a pokemon componenent which we will soon define.

// src/app.module.ts

import { Module } from '@nestjs/common'
import { AppController } from './app.controller'
import { TypeOrmModule } from '@nestjs/typeorm'
import { AppService } from './app.service'
import { GraphQLModule } from '@nestjs/graphql'
import { PokemonModule } from './pokemon/pokemon.module'
@Module({
    imports: [
        TypeOrmModule.forRoot(),
        GraphQLModule.forRoot({
            autoSchemaFile: 'schema.gpl'
        }),
        PokemonModule
    ],
    controllers: [ AppController ],
    providers: [ AppService ]
})
export class AppModule {}

Setting up GraphQL endpoint

We will have a singular entity called pokemon. Make a directory inside the src folder and call it pokemon. Inside it we will make a pokemon.entity.ts.

// src/pokemon/pokemon.entity.ts

import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm'

@Entity('pokemon')
export class PokemonEntity {
    @PrimaryGeneratedColumn('uuid') id: string

    @Column('varchar', { length: 500, unique: true })
    name: string

    @Column('varchar', { length: 500 })
    type: string

    @Column('numeric') pokedex: number
}

Now that we have our entity we can inject it into our pokemon module. Next we will create a DTO (Data Transfer Object), which is a model that defines the shape of the data we are expecting to be sent. Make a folder inside pokemon called dto and create a file called add-pokemon.dto.ts.

// stc/pokemon/dto/create-pokemon.dto.ts

import { Field, ObjectType} from 'type-graphql'

@ObjectType()
export class CreatePokemonDto {
    @Field() readonly id?: string
    @Field() readonly name: string
    @Field() readonly type: string
    @Field() readonly pokedex: number
}

Similarly we will set up a input object, which will define the shape of the input parameters to our mutation query. In an input folder create pokemon.input.ts.

// src/pokemon/input/pokemon.input.ts

import { Field, InputType } from 'type-graphql'

@InputType()
export class inputPokemon {
    @Field() readonly name: string
    @Field() readonly type: string
    @Field() readonly pokedex: number
}

Next we will set up our Pokemon service class. Services are a type of provider, and they are a fundamental part in NestJS because they handle the task of injecting dependencies. We can create service directly using Nest CLI.

$ nest generate service pokemon

All providers are preceded by the @Injectable decorator. Services are usually where we inject our data repository from our ORM, and set up interactions with our data. In our case we will create two methods, createPokemon and getPokemon.

// src/pokemon/pokemon.service.ts

import { Injectable } from '@nestjs/common'
import { InjectRepository } from '@nestjs/typeorm'
import { PokemonEntity } from './pokemon.entity'
import { Repository } from 'typeorm'
import { CreatePokemonDto } from './dto/create-pokemon.dto'

@Injectable()
export class PokemonService {
    constructor (@InjectRepository(PokemonEntity) private readonly PokemonRepository: Repository<PokemonEntity>) {}

    async createPokemon (data: CreatePokemonDto): Promise<PokemonEntity> {
        let pokemon = new PokemonEntity()
        pokemon.name = data.name
        pokemon.pokedex = data.pokedex
        pokemon.type = data.type

        await this.PokemonRepository.save(pokemon)

        return pokemon
    }

    async getPokemons () {
        return await this.PokemonRepository.find()
    }
}

Next we will make a resolver class. Resolvers are what resolves a GraphQL request to a function. While there are many ways to make a GraphQL resolver, we will use the @Resolver decorator from the NestJS GraphQL library. In our resolver class, we will map our Query and Mutation to the functions created in our service class.

// src/pokemon/pokemon.resolver.ts

import { Resolver, Query, Mutation, Args } from '@nestjs/graphql'
import { PokemonEntity } from './pokemon.entity'
import { CreatePokemonDto } from './dto/create-pokemon.dto'
import { PokemonService } from './pokemon.service'
import { inputPokemon } from './inputs/pokemon.input'

@Resolver((of) => PokemonEntity)
export class PokemonResolver {
    constructor (private readonly pokemonService: PokemonService) {}

    @Query(() => [ CreatePokemonDto ])
    async pokemon () {
        return this.pokemonService.getPokemon()
    }

    @Mutation(() => CreatePokemonDto)
    async createPokemon (@Args('data') data: inputPokemon) {
        return this.pokemonService.createPokemon(data)
    }
}

Finally we will encapsulate everything inside our Pokemon module.

// src/pokemon/pokemon.module.ts

import { PokemonResolver } from './pokemon.resolver'
import { Module } from '@nestjs/common'
import { PokemonService } from './pokemon.service'
import { TypeOrmModule } from '@nestjs/typeorm'
import { PokemonEntity } from './pokemon.entity'

@Module({
    imports: [ TypeOrmModule.forFeature([ PokemonEntity ]) ],
    providers: [ PokemonResolver, PokemonService ]
})
export class PokemonModule {}

Testing the endpoint in playground

And that's it! We can test our app by using yarn start:dev and our app will be hosted by default on port 3000. We can navigate to localhost.com:3000 to see a "Hello World" message, but if we navigate to localhost.com:3000.graphql we will be greeted with GraphQL playground (the default testing GUI tool used by NestJS). We can test our mutation and query here.

NestJS CRUD with Postgres and TypeORM

Rohan Faiyaz Khan — Fri, 09 Aug 2019 12:38:46 +0000

Disclaimer: This was originally posted on my blog

NestJS is a fantastic framework for writing robust web backends. According to the docs:

Nest (or NestJS) is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with and fully supports TypeScript (yet still enables developers to code in pure JavaScript) and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming) Under the hood, Nest makes use of robust HTTP Server frameworks like Express (the default) and optionally can be configured to use Fastify as well!

Essentially Nest takes inspiration from enterprise level frameworks such as the .NET Framework while also offering the simplicity and flexibility of building a simple Node.js server with Express. Nest is inspired heavily from Angular and seeks to provide similar abstractions to the backend.

That's all fine and good, but why should you use Nest?

Well let me preface this by first saying that if have a preferred backend of choice in another language such as Django, Laravel or .NET, Nest won't offer any new tools or tricks. However if you have been building Node servers before you might have experienced the frustration of setting up the same application over and over again. Or you might have had difficulties maintaining the app as scale grew. Nest offers so many advantages over starting a project from scratch that I believe it will soon become a default for Node CRUD applications and APIs. Over this article I will try my best to show what those advantages are.

First of all there is TypeScript support and an application structure right out of the box. You don't have waste time setting up your application and straight away jump into creating your endpoints. In addition Nest comes with its own command line that lets scaffold the application and add components very quickly. Nest is also very platform agnostic and you can use any database or any frontend with it, For instance, it has TypeORM integration that can easily be set up with an MySQL, Postgres, SQL Server or even MongoDB database.

I will go through how to build a REST API capable of CRUD operations to demonstrate how easy it is to get started with Nest.

Get started with Nest

We will first install NestJS (if you don't already have it installed) using NPM and set up a new Nest project

$ npm i -g @nestjs/cli
$ nest new nest-app

This will scaffold the application and ask you which package manager you prefer, npm or yarn. I used yarn for this example but feel free to use npm if you like. After installing we can test the server.

We can test the installation by using yarn start. This will start the app by default on port 3000. We can navigate over to see a "Hello world" message.

Setting up Postgres

This part will assume you have Postgres installed. If not, install Postgres on OS, for instance you can use the official installer for Windows, use Homebrew on MacOS or apt on Ubuntu.

Once we have Postgres installed, we will want to create a database. We can do this using a GUI tool such as PGAdmin or simply using Postgres CLI. I am using Linux so I will use sudo to switch to the postgres user, which is the default superuser. We need the super user in order to call the the createdb command.

$ sudo -u postgres psql
postgres=# createdb rohan
postgres=# \q

The command psql opens the Postgres CLI. \q quits the Postgres CLI. We can set a password to our local user so we can securely access the local database.

$ psql
rohan=# \password
rohan=# Enter new password:
rohan=# Retype new password

Connecting our app to our Database

Firstly we will install the necessary dependencies. TypeORM is the suggested ORM and is very good for connecting with Postgres.

yarn add pg typeorm @nestjs/typeorm @nestjsx/crud

Next we will create a config file at the root of our project and call it ormconfig.json.

{
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "rohan",
    "password": "password",
    "database": "rohan",
    "entities": ["dist/**/*.entity.js"],
    "synchronize": true,
    "logging": true
}

Nest uses an application structure similar to Angular in the sense that there are controllers, modules and providers (or services) for each component. The root of the project contains an app.module and an app.controller. In order to include our TypeORM module, we must import in our app.module. Doing so makes the module available all over our application without needing to import it anywhere else. In the app.module.ts file inside the src directory, type:

import { Module } from '@nestjs/common'
import { AppController } from './app.controller'
import { AppService } from './app.service'
import { TypeOrmModule } from '@nestjs/typeorm'
import { PokemonModule } from './pokemon/pokemon.module'

@Module({
    imports: [ TypeOrmModule.forRoot(), PokemonModule],
    controllers: [ AppController ],
    providers: [ AppService ]
})
export class AppModule {}

Don't worry about the Pokemon module, we will be creating it soon. You might notice here that the module is what connects the different parts of the component. We will include the TypeOrmModule's forRoot module with empty parameters. By default it will the configuration in our ormconfig.json as its parameters.

Creating an entity

Next let's create an entity. We will make an entity for pokemon! Make a new directory called pokemon and inside it create a file called pokemon.entity.ts.


import { Entity, Column, PrimaryGeneratedColumn} from 'typeorm'

@Entity('pokemon')
export class PokemonEntity {
    @PrimaryGeneratedColumn('uuid') id: string

    @Column('varchar', { length: 500, unique: true})
    name: string

    @Column('varchar', { length: 500 })
    type: string

    @Column('numeric')
    pokedex: number
}

Setting up CRUD

Before setting up our CRUD operactions we have to import the entity created in our model. We can generate a model using the Nest CLI.

nest generate module pokemon

This will auto generate a module for us called pokemon.module.ts.

import { Module } from '@nestjs/common'
import { PokemonService } from './pokemon.service'
import { PokemonController } from './pokemon.controller'
import { PokemonEntity } from './pokemon.entity'
import { TypeOrmModule } from '@nestjs/typeorm'

@Module({
    imports: [ TypeOrmModule.forFeature([ PokemonEntity ]) ],
    controllers: [ PokemonController ],
    providers: [ PokemonService ]
})
export class PokemonModule {}

Next the service.

nest generate service pokemon

Inside the newly created pokemon.service.ts file we will inject our CRUD service.

import { Injectable } from '@nestjs/common'
import { InjectRepository } from '@nestjs/typeorm'
import { TypeOrmCrudService } from '@nestjsx/crud-typeorm'
import { PokemonEntity } from './pokemon.entity'

@Injectable()
export class PokemonService extends TypeOrmCrudService<PokemonEntity> {
    constructor (@InjectRepository(PokemonEntity) repo) {
        super(repo)
    }
}

Finally in our pokemon controller we will set up our CRUD endpoints using the @nestjsx/crud package. This really demonstrates an area where NestJS shines. While it is possible to make all our endpoints manually (using @Get, @post, @Put, @Patch and @Delete decorators in our controller), the CRUD package allows us to set up all of this effortlessly in a few lines of code.

import { Controller} from '@nestjs/common'
import { Crud } from '@nestjsx/crud'
import { PokemonService } from './pokemon.service'
import { PokemonEntity } from './pokemon.entity'
@Crud({
    model: {
        type: PokemonEntity
    },
    params: {
        id: {
            field: 'id',
            type: 'uuid',
            primary: true
        }
    }
})
@Controller('pokemon')
export class PokemonController {
    constructor (public service: PokemonService) {}
}

ANd with that CRUD automatically sets up the following endpoints:

GET /pokemon Get all
GET /pokemon/:id Get one by id
POST /pokemon Add one
POST /pokemon/bulk Add many
PUT /pokemon/:id Replace one
PATCH /pokemon/:id Update one

You can test out the new endpoints in Postman or curl.

That's it!

I don't know about you but when I first learned to make a REST API there was a lot more boilerplate code to figure out. Nest offers just the right amount of high level abstractions to make building APIs a fun process again because you will be focus on what really matters- the endpoints and the entities, Furthermore, NestJS's official docs has comprehensive recipes on integrating with GraphQL (a post on that coming soon) and others. If you are a NodeJS developer, NestJS is something very exciting to keep your eye on.

Building your first Hugo site

Rohan Faiyaz Khan — Mon, 05 Aug 2019 19:14:28 +0000

Disclaimer: This was originally posted on my blog

If you are unfamiliar with the concept of static site generators, they allow you to take your content (either as markdown or as input from a CMS) and output a static version of your website.

There are several advantages of static sites.

They are extremely fast because there is no need to dynamically fetch content.
There is next to no cost of hosting them as they can be served up for free (for instance my personal Hugo site is being hosted on Netlify)
They are inherently more secure

Need any more reasons? Well how about this, it is possible to create something that is more than just a simple website. Using custom APIs (or a variety of available 3rd party ones) you can make a full fledged web app! This stack is being referred to these days as the JAMStack (JAvascript, Markup and API) and is a fantastic option for the modern web. For instance, once could have a static site and use Auth0 for authentication, Algolia for search, Cloudinary for images and Shopify for payments. The possiblities are endless so I will leave all the delicious JAM goodness for another post. This post will just cover how to get up and start with a simple static website.

While you can use any static site generator of choice such as Jekyll or Middleman if you prefer Ruby, Next.js or Gatsby if you prefer React, or Nust.js or Vue Press if you prefer Vue, this post will focus on Hugo, which is one of the more popular ones to choose from with over 36k stars on Github. I personally like Hugo because it very easy to use, is very fast to build thanks to it being built in Go and it has a large community providing pre-built themes.

Getting set up

First make sure to install Hugo. There are multiple ways to do this depending on your current platform so use the official official docs for reference.

Next setup a hugo project using the command line.

hugo new site hugo-starter

This sets up the following file structure.

├── archetypes
│   └── default.md
├── config.toml
├── content
├── layouts
│   └── partials
│       ├── footer_custom.html
│       └── head_custom.html
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static
└── themes

Installing a theme

Next up we will be setting up a theme. Themes are the cornerstone of hugo sites cause they define how your content is to be displayed. It is possible to create a custom theme but for the sake of quickly setting things up we will choose one of the many community built themes available to us.

For this example we will be using Cocoa-Eh. To install a theme we need to copy the theme into our themes directory. We can do this manually or via git using the commands:

git init
git clone https://github.com/mtn/cocoa-eh-hugo-theme.git themes/cocoa-eh
cp -r ./themes/cocoa-eh/exampleSite/* ./

After cloning we set up a few sample pages using the contents of the theme's example site folder. One last thing we will have to do is set the theme in the config.toml file by setting the following line:

theme="cocoa-eh"

Finally we just run hugo server in development mode which builds our app and sets up a local web server where we can preview our site. Hugo server by default uses live reload so any changes will almost instantly be updated (yes, Hugo builds that fast).

hugo server -D

And that's it! We can view our site by navigating to localhost:1313.

Customizing you content

So obviously we want to customize our content. Let's start with the meta-data which is contained in our config.toml. Set the following values to your name and whatever you want the title to be. You can also use a custom image as your logo by pasting it into the static/img directory.

author = "Rohan Faiyaz Khan"
title = "My fancy new website!"

logofile="/img/new-logo.png

Hugo like other static site generators uses markdown as a source of content. It is also possible, and quite simple, to set this up using a CMS such as Wordpress, Forestry, Contentful, Netlify CMS or Sanity. Using a CMS allows to use a GUI to edit content and is ideal if you are building a website for somebody. I will cover connecting to a CMS in a separate but for now markdown will do just fine. If you have never used markdown before, here is a handy guide on what you can do in markdown.

In order to edit our welcome message we will change our home.md file inside our content directory.

+++
title = "Home"
+++

Hello there. Welcome to my site where I talk about __cat facts__. Feel free to purr through the posts below.

The top portion is what is referred to in static site generators as frontmatter. This section contains meta data about your content such as title, author and date. +++ indicates the frontmatter is in toml format. Another commonly seen case is --- which indicates frontmatter in yaml format. Next we can make a new post either by pasting it into our content/blog directory or just by using the hugo new command.

hugo new blog/catnip.md

We can edit our new post about catnip however we wish!

+++
title= "Catnip"
date= 2019-08-04T11:37:13+06:00
author= "Rohan Faiyaz Khan"
+++

Ever wonder why catnip lulls felines into a trance? The herb contains several chemical compounds, including one called nepetalactone, which a cat detects with receptors in its nose and mouth. The compounds trigger the typical odd behaviors you associate with the wacky kitty weed, including sniffing, head shaking, head rubbing, and rolling around on the ground.

And that's it! We can see our edits in the live preview.

That's all?

Yeah! That's all you need to get your site set up. You can play around however you please. And the best part is we have only scratch the surface of what Hugo is capable of! In future posts we will be covering templates, custom themes and more!