Forem: Joe Purnell

TIL: VSCode snippets can transform inputs

Joe Purnell — Mon, 02 Aug 2021 16:26:16 +0000

I'm on a quest to make my development tooling more efficient for my personal wants and needs. This lead me to adding some snippets to VSCode.

I added a snippet for creating a usage of React's useState hook and found my first rendition subpar:

//...
"reush": {
    "prefix": "React useState hook",
    "body": "const [${1:variable}, set${1:variable}] = useState<${2:type}>(${3:default});$0"
}
//...

When I used this snippet first I'd put the variable name isEnabled which would also populate the setter which was handy.

const [isEnabled, setisEnabled] = useState<boolean>(false);

Unfortunately, it would populate the setter with the exact same input so the setter would be left as setisEnabled so I'd have to go back and edit this entry.

Finding this I then made a discover from a quick web search: VSCode can transform the input!

A quick update to the snippet shows this in action:

"reush": {
    "prefix": "React useState hook",
    "body": "const [${1:variable}, set${1/(.*)/${1:/capitalize}/}] = useState<${2:type}>(${3:default});$0"
}

Now, the same snippet transforms the input! I type in the variable name isEnabled which gets duplicated to the setter. When I hit tab to move to the next type field, the setter transforms to be capitalised leaving:

const [isEnabled, setIsEnabled] = useState<boolean>(false);

Wonderful!

Other transforms include upcase, downcase, camelcase, pascalcase. Read more about it in the VSCode documentation.

Dipping toes into Kafka and Node

Joe Purnell — Wed, 23 Jun 2021 21:37:30 +0000

Some upcoming work is on the horizon which I need to work with something I've not had the pleasure before - Kafka.

I thought it best to try out Kafka on my own terms using technologies I'm comfortable with before going into the real world and breaking something in production.

Two thoughts knocked around:

I wasn't concerned with configuring Kafka itself
I wanted to use Node to communicate with Kafka

As I wasn't too concerned with the configuration of Kafka itself I decided to use this handy blog post from baeldung.com where I was walked through the steps needed to get an instance of Kafka running locally via docker.

Task one was done ✅

With that out the way it was time to start communicating with the Kafka instance. Kafka is a framework for streaming data - messages are posted to Kafka grouped under topics. Different applications can subscribe to topics, these applications are called consumers. When a message comes into Kafka - it will forward these messages to the consumer for processing at their pleasure.

This is what I wanted to try out today.

First lets get a consumer up and running, I spun up a cheeky Node app using our friendly command npm init -y and when this was done I installed our only dependency, KafkaJS using npm install kafkajs.

Now the project was setup I created a new file index.js and added the familiar script "start": "node index.js",

Let's see the code for the consumer:

const { Kafka } = require('kafkajs')

async function run() {
    const kafka = new Kafka({
        clientId: 'marvel-consumer',
        brokers: ['localhost:29092']
    })

    const consumer = kafka.consumer({ groupId: 'marvel-consumers' })

    await consumer.connect()

    await consumer.subscribe({ topic: 'marvel' })

    await consumer.run({
        eachMessage: async ({ topic, partition, message }) => {
            console.log('marvel-consumer', {
                topic,
                partition,
                key: message.key.toString(),
                value: message.value.toString(),
                headers: message.headers,
            })
        },
    })
};

run();

The intention here was to encapsulate a consumer into its own simple application, this application listens for messages on the topic marvel and writes the published message to the console.

In order to achieve this first I needed to connect to my local running Kafka instance, I also needed to give my consumer a group id - this is used by Kafka to group consumers together. When consumers are grouped not every consumer will be posted each message as Kafka will use round robin to forward messages on. This last point led to some head scratching for a few moments when I decided to use multiple consumers.

Grouping is there for us to setup multiple instances of the same consumers for resilience.

Following this I then give the topic the consumer is interested in - for this consumer it was the topic 'marvel'.

I then wanted to try out multiple consumers in order to see how they function, to do this I simply copy pasted the code already defined for this first consumer. I made sure to update the group ids to ensure each consumer gets all the messages for the topics they're interested in.

In one of these extra consumers I subscribed just to the topic 'dc' and in the other I subscribed to both 'marvel' and 'dc' topics using the below code:

const { Kafka } = require('kafkajs')

async function run() {
    const kafka = new Kafka({
        clientId: 'superhero-consumer',
        brokers: ['localhost:29092']
    })

    const consumer = kafka.consumer({ groupId: 'superhero-consumers' })

    await consumer.connect()

    await consumer.subscribe({ topic: 'marvel' })

    await consumer.subscribe({ topic: 'dc' })

    await consumer.run({
        eachMessage: async ({ topic, partition, message }) => {
            console.log('superhero-consumer', {
                topic,
                partition,
                key: message.key.toString(),
                value: message.value.toString(),
                headers: message.headers,
            })
        },
    })
};

run();

After running npm start for each of these defined consumers and I was ready to process messages, so I needed to create a producer (or two).

To do this I made a new directory for my producers /producers and ran through the same steps to create a new node project as we did for the consumers. But this time the index.js saw some different code:

const { Kafka } = require('kafkajs')

async function run() {
    const kafka = new Kafka({
        clientId: 'dc-producer',
        brokers: ['localhost:29092']
    })

    const topic = 'dc'

    const producer = kafka.producer()

    await producer.connect()

    await producer.send({
        topic,
        messages: [
            { key: 'batman', value: 'bruce wayne' },
        ],
    })

    process.exit(0);
}

run();

Here I run through the same setup as before, I connect to Kafka and then define a producer instead of a consumer. I then use the producer to send messages to Kafka for the given topic (in this instance that's 'dc').

Running this code above with our trusty npm start command I then saw messages pop into the superheroes and the 'dc' consumers at the same time.

I officially produced and consumed messages via Kafka! Task two was done ✅

I then duplicated my producer coder to see some marvel messages and was happy.

Hope you find something useful here - I was concerned before starting off that this might lead down some complicated paths but it certainly seems like more intelligent people got here first and made it a lot simpler to get started with Kafka and Node.

References:

To achieve this I used the above mentioned blog post for running docker and the rest of my code was pieced together using the KafkaJS docs.

You can find all the code I produced here.

Git Stash - A Personal Reminder

Joe Purnell — Wed, 16 Sep 2020 21:40:13 +0000

I got Déjà vu again - I was searching on a popular search engine for a command to help me stash my changes in a certain way, I felt like I had been here before. Google confirmed this by displaying a familiar purple text colour showing me I had indeed visited this page before.

So I decided to make a quick note to myself (and for any others who may stumble upon this post), at least I'll be giving myself post views when I inevitably forgot these commands and need to look them up again.

This is not meant to be an in-depth analysis or rundown of the full git stash CLI, you can find that here.

This is simply to serve as a reminder of those commands I find myself needing from time to time.

Simple and classic - Stash your changes

git stash

Add a message to your stash

git stash --save "Super descriptive message goes here"

You can include untracked files

git stash --include-untracked

# Or a bit shorter
git stash -u

When you want to stash everything apart from staged changes

git stash --keep-index

# Save those keys

git stash -k

Have a look at your stashes

git stash list

Apply the last stashed change and remove it from your stash list

git stash pop

Apply the last stash change but keep it in the list as a stash (for some reason)

git stash apply

Clear up after yourself and remove all stashes

git stash clear

Testing XState with React Testing Library

Joe Purnell — Thu, 27 Aug 2020 17:03:43 +0000

Recently, I needed some state-heavy logic within this new application, so following from my previous research, I went with XState.

The implementation of the logic went smoothly, within no time I had our new State Machine in place and functioning correctly.

Then came testing.

I got a bit stuck when it came to writing the unit tests. In an ideal world, I wouldn't be relying so much on unit testing. However, as many companies do, mine prefers to align with the Testing Pyramid rather than the Testing Trophy. Unit testing is a must for us. So I hit the docs.

So what is model-based testing anyway?

The first thing to wrap my head around was the lack of actual unit tests. Model-based testing allows us to give information about our State Machine and instructions on how to perform small steps within the logic to transition between states.

We take this information and generate end to end paths through our logic. Finally, we use these paths to base the generation of our unit tests. It'll look something like this:

// State machine test

describe('StateMachine', () => {
  const testPlans = stateMachineModel.getShortestPathPlans();

  testPlans.forEach((plan) => {
    describe(plan.description, () => {
      afterEach(cleanup);
      plan.paths.forEach((path) => {
        it(path.description, async () => {
          await path.test(render(<TestComponent />));
        });
      });
    });
  });
});

First, we need a component to test.

Typically, State Machines used with visual components, interacting with these visuals causes transitions through our logic. We don't want to be tied to production visuals for our testing here, just in case the visuals change and the logic doesn't. Also, creating a component purely for testing allows us to simplify how we trigger our transitions.

// State machine test

const TestComponent = () => {
  const [state, publish] = useMachine(stateMachine, {
    actions: {
      loadingEntryAction,
      userSubmitAction,
    },
  });

  return (
    <div>
      <p data-testid="current_state">{state.value}</p>
      <button
        onClick={() => {
          publish('SUBMIT');
        }}
      >
        SUBMIT
      </button>
      <button
        onClick={() => {
          publish('SUCCESS');
        }}
      >
        SUCCESS
      </button>
      <button
        onClick={() => {
          publish('FAILURE');
        }}
      >
        FAILURE
      </button>
    </div>
  );
};

So here's our simple component, we display the current state and have buttons for each type of transition we support. We also import and use our State Machine as you would in a normal React Component.

Asserting we're right.

Looking at the documentation, we see examples like this one:

// XState Test Docs

const toggleMachine = Machine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: {
        /* ... */
      },
      meta: {
        test: async page => {
          await page.waitFor('input:checked');
        }
      }
    },
        /* ... */
});

I'm not a fan of this as it looks like we're hardcoding our testing logic into our production code. I prefer to keep these two worlds apart.

So let's take our State Machine initialisation:

// State machine

import { Machine } from 'xstate';

export const stateMachine = Machine({
  id: 'statemachine',
  initial: 'IDLE',
  states: {
    IDLE: {
      on: { SUBMIT: { target: 'LOADING', actions: ['userSubmitAction'] } },
    },
    LOADING: {
      entry: ['loadingEntryAction'],
      on: {
        SUCCESS: 'SUCCESS',
        FAILURE: 'FAILURE',
      },
    },
    SUCCESS: {},
    FAILURE: {
      SUBMIT: { target: 'LOADING', actions: ['userSubmitAction'] },
    },
  },
});

We'll change this to separately export the declaration of logic for our State Machine alongside the export of the State Machine itself.

// State machine

import { Machine } from 'xstate';

export const machineDeclaration = {
  id: 'statemachine',
  initial: 'IDLE',
  states: {
    IDLE: {
      on: { SUBMIT: { target: 'LOADING', actions: ['userSubmitAction'] } },
    },
    LOADING: {
      entry: ['loadingEntryAction'],
      on: {
        SUCCESS: 'SUCCESS',
        FAILURE: 'FAILURE',
      },
    },
    SUCCESS: {},
    FAILURE: {
      SUBMIT: { target: 'LOADING', actions: ['userSubmitAction'] },
    },
  },
};

export const stateMachine = Machine(machineDeclaration);

We can then take this and within our test, add logic allowing us to assert we're in the right state by looking at the current_state we implemented in our Test Component.

// State machine test

machineDeclaration.states.idle.meta = {
  test: async ({ getByTestId }) => {
    expect(getByTestId('current_state')).toHaveTextContent('idle');
  },
};

machineDeclaration.states.loading.meta = {
  test: async ({ getByTestId }) => {
    expect(getByTestId('current_state')).toHaveTextContent('loading');
    expect(loadingEntryAction).toHaveBeenCalled();
  },
};

machineDeclaration.states.success.meta = {
  test: async ({ getByTestId }) => {
    expect(getByTestId('current_state')).toHaveTextContent('success');
  },
};

machineDeclaration.states.failure.meta = {
  test: async ({ getByTestId }) => {
    expect(getByTestId('current_state')).toHaveTextContent('failure');
  },
};

Forming our machine model

Let's create a new model using our machineDeclaration and some events. These events are the actions which trigger state transitions within our Testing Component, in our case that's clicking buttons, we use React Testing Library's FireEvent to do this.

// State machine test

const stateMachineModel = 
    createModel(xstate.createMachine(machineDeclaration)).withEvents({
      SUBMIT: {
        exec: ({ getByText }) => {
          fireEvent.click(getByText('SUBMIT'));
          expect(userSubmitAction).toHaveBeenCalled();
        },
      },
      SUCCESS: {
        exec: ({ getByText }) => {
          fireEvent.click(getByText('SUCCESS'));
        },
      },
      FAILURE: {
        exec: ({ getByText }) => {
          fireEvent.click(getByText('FAILURE'));
        },
      },
    });

Asserting Actions

We use a typical way of triggering events in our state machine - actions. You can see we use actions twice, once when we enter a state and another to accompany a transition. We saw our assertions for these before but, let's have a focused look:

Firstly, we created mock functions to assert against then we pass those to XState when we initialise our State Machine in Test Component.

// State machine test
//...

const loadingEntryAction = jest.fn();
const userSubmitAction = jest.fn();

const TestComponent = () => {
  const [state, publish] = useMachine(stateMachine, {
    actions: {
      loadingEntryAction,
      userSubmitAction,
    },
  });

//...

We can then use these functions within the assertions we pass to XState to assert a function is called upon entry.

// State machine test

machineDeclaration.states.loading.meta = {
  test: async ({ getByTestId }) => {
    expect(getByTestId('current_state')).toHaveTextContent('loading');
    expect(loadingEntryAction).toHaveBeenCalled();
  },
};

To assert that a function is called during a transition, we can add an assertion in our testing model, as we do here for userSubmitAction.

// State machine test

const stateMachineModel = 
    createModel(xstate.createMachine(machineDeclaration)).withEvents({
      SUBMIT: {
        exec: ({ getByText }) => {
          fireEvent.click(getByText('SUBMIT'));
          expect(userSubmitAction).toHaveBeenCalled();
        },
      },
      //...
    });

Finally

Tying all this together took a little time for me, so I wanted to write it down to remind myself and hopefully help anybody else looking to unit test their XState State Machines. The key for me was to understand each of these small parts and using them with a combination of Jest and React Testing Library, rather than Puppeteer.

You can see this example in its entirety here.

As always, this is just the way I found to achieve this goal. If you have any thoughts or opinions then please reach out.

A Shortcut to Data

Joe Purnell — Thu, 04 Jun 2020 22:40:02 +0000

I've been wanting to learn data visualisation since I listened to React podcast episode 15 'Data Visualization with Shirley Wu' which got me excited about trying out D3.

Recently, I got the chance to dip my toes into this framework as I was fortunate enough to be given a subscription to Frontend Masters with which I dived straight onto the learning path for Data Visualisation.

Ultimately, I tested my new skills visualising data from the dialogue of the Lord of the Rings films. Check it out here.

Here are a few things I learnt whilst dipping my toes into data visualisation for the first time:

Starting with a course is a great boost
When I first checked out the documentation for D3, I was a bit overwhelmed with the amount I needed to pick up straight away. Going back and kicking off my learning with a D3 course gave me a great base understanding so I could better pick up what the documentation was describing.
If you can, I would very much recommend Shirley Wu's courses on Frontend Masters as a great place to start.

SVG is just as important as D3
It quickly became apparent that understanding SVG can improve your game, helping to display data in interesting ways. This is why the next course I'm looking to take on is an SVG.

Leave D3 to update DOM elements
As a predominantly React developer, I decided to combine React and D3 for this project. After trying different ways to combine the two I found that leaving the visualisation updates to D3 led to cleaner code and better performance.

D3 Force can lead to infinite loops
I got caught out a few times when using D3's force as I would get caught in infinite loops while processing the visuals for my data. As I was coding on CodeSandbox this caused my browser session to crash. To reopen I had to use the URL parameter runonclick=1 to get past the crashing server to fix the problem.

Clean your data before you use it
At first, I was trying to clean the data to visualise in my component code which led down confusing code structures. This was until I realised the data wasn't dynamic so I could preprocess all of my data and store it in simple arrays already sorted ready to render. Perfect.

Mess around
I ended up learning the most and finalising ideas by messing around and trying different visualisations. CodeSandbox is great for this giving a quick platform for trying ideas out.

Optional bottom navigation using feature flags, and why it didn't work

Joe Purnell — Tue, 10 Mar 2020 16:41:51 +0000

Disclaimer: At the time of writing there is an open feature request for React Navigation for hiding tabs, find it here: https://react-navigation.canny.io/feature-requests/p/hiding-tab-from-the-tabbar.

Disclaimer 2: the title wasn't lying, the following solution didn't work - but I do go into why.

So I was asked to add a tab hidden behind a feature flag, easy peasy (in theory). The issue here was that the apps navigation library didn't support this feature.

My first instinct was to add a classic && in the routeConfigMap of the bottomTabNavigator function, like:

export const Tabs = createBottomTabNavigator(
    {
        StackNavigatorOne,
        StackNavigatorTwo,
        StackNavigatorThree,
        StackNavigatorFour: featureFlag && StackNavigatorFour,
    },
    tabConfig,
);

The problem I found here was that StackNavigatorFour was always being created so when the flag pointed to false StackNavigatorFour had the value of false. Fast forward to running the app and the Bottom Tab Navigator will throw an error as it's expecting a valid React Component (sigh).

Instead of walking you through the typical motions of searching the web and staring at my screen in a pit of despair, I'll fast forward to my simple solution.

Create a tab constructor:

const optionalTabs = () => {
    const tabs =
        StackNavigatorOne,
        StackNavigatorTwo,
        StackNavigatorThree,
    };

    if (featureFlag) {
        tabs.StackNavigatorFour = StackNavigatorFour;
    }

    return tabs;
};

export const Tabs = createBottomTabNavigator(
    optionalTabs(),
    tabConfig,
);

Here I created a function which returned a list of tabs and used it in the createBottomTabNavigator constructor. Fun times!

This failed.

So I found the solution worked through our complete development and e2e environments - we saw no errors, failures, or problems. We went live.

The issue came when we saw no traffic hitting our new page, we even checked the turned on the right feature flag. We persevered and continued debugging - by opening the app manually. What we (didn't) see surprised us, there was no new tab in the navigator.

What happened for us was that the feature flags get downloaded once the app is opened. Then the app re-renders considering the remote config it is given, in this case, that would've added a new tab. But the navigation bar doesn't re-render so we couldn't see the new tab added. This had gone unnoticed, during all levels of testing our feature flags were mocked and provided when the app opens so the config is used straight away, no re-render required.

We're always told that sometimes mocking calls can lead to confusion. This was one of those times for me.

We don't usually see failure stories being posted up, but there are a couple takeaways here I hope you appreciate and will hopefully help you in the future.

Oh! The final solution for us was to move the old content to the same bottom navigation and then re-render the content shown on the tab click according to the feature flag.

Create your own State Machine

Joe Purnell — Thu, 20 Feb 2020 11:57:24 +0000

As a (mostly) self-taught software engineer, there are times where I feel like are gaps in my understanding. Especially around computer science topics. So when I noticed more talk about state machines (namely XState), I chose to learn what they are.

What better way to learn state machines than to try and build one, so let's give it a shot.

If you fancy coding along, check out this codesandbox where you'll find the solution I went towards, and a starting point to implement your own.

What are we doing?

For this exercise, I wanted to take a component has a bit of state logic and updates, and change it to use a state machine. I decided on a simple text input which checks if an email is available (like you see in a sign-up form).

So, we have our state which tells the component whether to show loading, error, or success messages. We also have an onClick and simulated server communication that changes the state.

So what is a state machine?

If you start reading up about state machines you'll probably hit Wikipedia first (I mean, why not). There you'll start reading about computational models and such. After getting my head around the concept, it seems that you can break it down quick nicely:

An app (or component) that can only be in one of a finite number of statuses at a time is a state machine.

Our email checker shouldn't have more than one status. We shouldn't be in both 'loading' and 'success' states. But we need to be able to transition between states. If we make our transitions via a rigid structure, we can better control the state changes reducing possible bugs and errors.

Creating states

Getting started, let's look at the state we use:

    const [showError, setShowError] = useState(false);
    const [errorMessage, setErrorMessage] = useState("");
    const [showSuccess, setShowSuccess] = useState(false);
    const [loading, setLoading] = useState(false);
    const [inputValue, setInputValue] = useState("");

As this is a somewhat simple component we're creating, our state types reflect that:

    const states = {
      IDLE: "IDLE",
      CHECKING_EMAIL: "CHECKING_EMAIL",
      SUCCESS: "SUCCESS",
      FAILURE: "FAILURE"
    };

Now we have our state types defined, we can reduce our state declaration:

    const [appState, transition] = useReducer(stateMachine,
        {
            state: states.IDLE,
            message: ""
        }
    );
    const [inputValue, setInputValue] = useState("");

We've removed the multiple values used to manage our element and replaced it with a single object that holds our state along with any related information (such as error messages).

With our state types defined, we can adjust our returned component to read from our new singular state:

    if (appState.state === states.SUCCESS) {
        return (
          <div className="App">
            <div className="container successContainer">
              <p className="messagetext successtext">Success! Email free to use.</p>
              <button
                className="button"
                onClick={() => {
                  transition({ type: states.IDLE });
                  setInputValue("");
                }}
              >
                Reset
              </button>
            </div>
          </div>
        );
      }

      return (
        <div className="App">
          <div className="container">
            {appState.state === states.FAILURE && (
              <p className="messagetext errortext">{appState.message}</p>
            )}
            {appState.state === states.CHECKING_EMAIL && (
              <p className="messagetext">Checking email...</p>
            )}
            <input
              className="input"
              placeholder="User Email"
              disabled={
                appState.state !== states.IDLE && appState.state !== states.FAILURE
              }
              value={inputValue}
              onChange={onInputChange}
            />
            <button
              className="button"
              disabled={
                appState.state !== states.IDLE && appState.state !== states.FAILURE
              }
              onClick={() => {
                checkEmail(inputValue);
              }}
            >
              Check Email
            </button>
          </div>
        </div>
      );

The biggest change here is the reduction of multiple checks. Such as no longer needing to check we're still loading when we have an error and want to show the error message.

Transitioning between states

So now we have our new state types, we also have somewhere to house our state, and we have improved our rendering to use the singular state. It's time to get into the meat of our state machine: the transitioning logic.

The transition logic of a state machine has a straight forward pattern which follows this structure:

If I am in status X and I need to transition to status Y I need to perform Z

For example: if I am 'IDLE' and I need to transition to 'CHECKING_EMAIL' all I need to do is set the status to 'CHECKING_EMAIL'.

We then implement this in code like so:

    switch (currentState) {
      case states.IDLE:
        switch (event.nextState) {
          case states.CHECKING_EMAIL:
            nextState = states.CHECKING_EMAIL;
            return nextState;
          default:
            return currentState;
        }
      default:
        return currentState;
    }

Nothing too complicated, just a couple of switch statements is all we need. It also looks like a reducer (if you've had prior experience with Redux or useReducer), this is why it makes sense to use it with the useReducer hook as we saw earlier.

    const [appState, transition] = useReducer(stateMachine, {
      state: states.IDLE,
      message: "",
    });

So how do we handle this second piece of state - the message? Let's look at what happens when we have an error while checking an email address:

    switch (currentState) {
      ...
      case states.CHECKING_EMAIL:
        switch (event.nextState) {
          ...
          case states.FAILURE:
            nextState.message = event.payload.errorMessage;
            nextState.state = states.FAILURE;
            return nextState;
          ...
        }
      ...
      case states.FAILURE:
        switch (nextState) {
          ...
          case states.CHECKING_EMAIL:
            nextState.message = "";
            nextState.state = states.CHECKING_EMAIL;
            return nextState;
          ...
        }
      ...
    }

When we transition from a 'CHECKING_EMAIL' state into 'FAILURE', we can tell our state machine to post the given payload into the state of the component. The reverse is here too - we know when we transition from a 'FAILURE' state back to 'CHECK_EMAIL', we should reset the message field which is what we do.

By protecting our state by only updating through our state machine, we reduce updates and potential bugs that can occur. We also can better trust we only display the correct fields when they're needed.

Triggering state changes

Now we have declared our states and handled transitions we need to look at triggering state changes. Thanks to the previous work we've already done, triggering state changes are super simple. Let's create an onClick handler for our email checking logic. Remember how we declared our state machine using the useReducer hook?

    export default function App() {
      ...
      const [appState, transition] = useReducer(stateMachine, {
        state: states.IDLE,
        message: ""
      });
      ...
    }

We can now call the dispatch return from our useReducer declaration whenever we want to trigger a state transition. These dispatch calls can even include any extra data we might need, such as error messages.

    // Plain state change
    transition({ type: NEW_STATE });

    // State change with a message
    transition({
      type: NEW_STATE,
      payload: { errorMessage: ERROR_MESSAGE }
    });

We can see this in action in our onClick handler for the 'Check Email' button:

    const checkEmail = async email => {
        // transition to checking state
        transition({ type: states.CHECKING_EMAIL });

        // simulate a (slow) call to a server
        await setTimeout(() => {
          if (email.toLowerCase().includes("joe")) {
            // transition to error state
            transition({
              type: states.FAILURE,
              payload: { errorMessage: "Joe is not allowed an account" }
            });
          } else {
            // transition to success state
            transition({ type: states.SUCCESS });
          }
        }, 3000);
      };

Our first step is to transition into a checking state then we simulate a server call. Depending on the result of the call, (in this case the presence of the word 'joe'), we get an error or success response that we can then reflect in our state by triggering another transition.

Can we handle side effects in our state machine?

Long story short - heck yeah! The previous example of handling the logic and transition in an external handler function is purely the design path I took. Nothing is stopping you doing plucking the processing logic from our email handler and popping it into the state machine reducer.

Then, when you declare a move to a new state, like success or failure, the state machine can call itself with the updated data and return the result.

There is one problem that stops us using a useReducer with this method: since we can only have one return per function, we can't update the state twice (once for loading and again for result).

To counter this, we'd have to extract our state machine from the useReducer hook to a standard function utilising useState to update the component. We should end up with something like the following:

    const stateMachine = (appState, event) => {
      const nextState = { ...appState };

      switch (appState.state) {
        case states.IDLE:
          switch (event.type) {
            case states.CHECKING_EMAIL:
              // transition to loading state
              nextState.state = states.CHECKING_EMAIL;
              setState(nextState); // external state setting

              await setTimeout(() => {
                if (event.payload.email.toLowerCase().includes("joe")) {
                  // transition to error state
                  nextState = stateMachine(nextState, {
                    type: states.FAILURE,
                    payload: { errorMessage: "Joe is not allowed an account" }
                  });
                  setState(nextState); // external state setting
                } else {
                  // transition to success state
                  nextState = stateMachine(nextState, { type: states.SUCCESS });
                  setState(nextState); // external state setting
                }
              }, 3000);

              return;
            default:
              setState(nextState); // external state setting
              return;
          }
        ...
      }
    };

All done

So that's it, we've taken a component and converted it to use a custom (albeit basic) state machine. Now loaded with the knowledge on what it takes to create a state machine, we can comfortably use some of the amazing frameworks, like XState, which takes this logic and makes it simpler and more robust to use.

I hope you enjoyed this custom state machine walkthrough. It ended up longer than expected. I constructed this purely from my understanding so if I'm wrong, get in touch and we can learn together.

Notes from working technology agnostic

Joe Purnell — Tue, 11 Feb 2020 08:18:23 +0000

I can now say I've worked in 3 types of environments:

"You can only work in these specific versions else everything will implode".
"Yeah, we're pretty 'flexible', but we prefer you stick to these technologies...".
"We're 'easy' baby! Work with whatever technology you want but remember you have to support it".

While each of these outlooks on technology may have a long list of pros and cons, I'm purely going to focus on my experience working in a technology-agnostic environment. So, without further ado - notes from my technology-agnostic life.

Great for recruiting.
Without a technology structure, communities need to become flexible - this isn't always a bad thing. But it can lead to the formation of splinter-groups hyper-focused on specific areas.

Communities will form, and drift, and form again.
Without a strict technology structure, communities are also forced to become flexible - this isn't always a bad thing. But it does lead to the formation of splinter-groups hyper-focused on specific areas.

Support doesn't just mean customers
A big thing I've found from the agnostic world is the importance of supporting other developers. Where we have the pleasure of selecting the technologies we use, we automatically become the 'experts' in using them. Also, when other people come along who need to integrate with our part of the system, we need to be prepared (and have the headroom) to support them in their integration. Without this, we can end up becoming the blocker we fear.

Documentation is king.
Continuing the previous point: documentation is a great resource for supporting both our own and other teams (plus those who come after us). Having reliable (and up-to-date) documentation can remove the need to support others in a 'hands-on' manner. It will also speed up any time on-boarding new team members into your team. Unfortunately, developers are notorious for not wanting to document their work.

Get ready to repeat yourself, to repeat yourself.
If you have to make a change across multiple areas of your business, be ready to re-write your changes in every technology being used. Get ready to change that button colour in three different technologies.

The paralysis of choice.
Having all of the incredible technologies to take your pick from can have a paralysing effect when you need to make a choice which can impact the future of your work, your team, your company, and even the world. Every decision becomes a spike of research so you can be sure you're doing the right thing.

Technological Happiness
More excitement about the technology used makes happy developers of those making the choices. But it also makes unhappy develops of left to support afterwards.

Being a flexible host is tough.
Something we've noticed is the slow down of infrastructure based work, where the paths are varying it seems like more of a chore to open our systems up for traffic from other sources. If everything was housed together, cross-system communication would be a lot smoother to orchestrate. A centralised infrastructure team of experts goes a long way to avoid this.

Sharing and caring.
I like finding ways to share my code, be it UI components or logic modules. Being agnostic sometimes restricts how often code can be reused, which can lead to more overhead.

Don't count the pennies
If you're worried about how much your system is costing each month this way of working might not be for you. Being flexible requires a flexible budget as different teams need different tools to keep the lights on. This can all mount up.

My takeaway.
While I enjoy having the freedom to export all the technologies I like sometimes it's better to be boring and keep somewhat aligned with my peers. I find this makes integration between systems easier, I can ask more questions, and I'm able to share my code and knowledge. That's not to say we shouldn't innovate and try new things. I just think we should consider what we do and try not to use new technologies just because we can.

That's it really. As always if you fancy reaching out, please do.

Programmatically positioning elements with React Hooks

Joe Purnell — Tue, 07 Jan 2020 00:31:59 +0000

Let's look at how we can use React Hooks to tell a component where on our page it should render.

Imagine your favourite search engine - when we type in our search term we'd presumably see an autocompletion box appear beneath our search input: let's create that floating element.

TLDR;

Find a full example of the problem and the solution in this codesandbox.

So let's get cracking. Without too much detail right now, in the example, you'll find the go-to solution where we show an element if we have content to display. You'll also see this go-to shifts all the elements following downwards when shown. Not too great.

Making it Dynamic

First, let's add a quick piece of styling for our container so it floats above our other elements:

.searchresultsfloat {
  position: absolute;
  z-index: 1;
}

useRef

Now in our tale, we need to know which element we're trying to link our position too, this is where useRef steps in. We can use useRef to create a reference which we can then tie to a DOM element.

// Create our reference
const searchBarReference = React.useRef(null);

// Other React Pizzazz...

// Attach it to the element we want to judge our position against
<div ref={searchBarReference} className="box blue searchcontainer">

When our new referenced element renders, it will populate our reference with information about itself in the .current variable. We can then call the function getBoundingClientRect() on that reference to learn the positioning of the element.

Let's perform this inside a useEffect hook, so we know the page is rendered when we learn the position of our referenced element.

React.useEffect(() => {
  if (searchBarReference.current) {
    setSearchResultTop(searchBarReference.current.getBoundingClientRect().bottom);
  }
}, []);

Perfect! But not quite: we now have our element rendering where it should. But when we resize the screen you'll see our results element is in the wrong position:

useLayoutEffect

This is where the useLayoutEffect hook can step in. This hook looks the same as our standard useEffect hook with the only difference being it triggers after all DOM mutation. We can use this to our advantage:

React.useLayoutEffect(() => {
  function updatePosition() {
    setSearchResultTop(searchBarReference.current.getBoundingClientRect().bottom);
  }
  window.addEventListener('resize', updatePosition);
  updatePosition();
  return () => window.removeEventListener('resize', updatePosition);
}, []);

Here we create a listener waiting for resize events. When one occurs, we reassert the boundaries of our referenced element so we can update our results to display where we want them to. So when we resize the screen, we see our results where they should be.

Be sure to return a function to remove your listener so when the page unmounts we don't leave our listener waiting for more events. And Voilà:

That's it really.

So we used useRef to know where our element is and we used useLayoutEffect to update on DOM mutations. Everyone's happy!

As always: this isn't the only solution, just one I found. If you'd like to reach out, please do!

Another way to share UI components between React and React Native

Joe Purnell — Mon, 09 Dec 2019 09:54:03 +0000

Before moving on, this is a written version of a talk I gave about the same subject, you can see the presentation and full code example here: https://github.com/joepurnell1/sharing-components-talk

You're about to see I've made some assumptions on technologies used, this is made from part preference and part problem solving. For this blog post I'm assuming you love Styled-Components, React, and React-Native.

Part 1: Atomic Design

So starting at the top, Atomic Design. This is a great design methodology created by the infamous Brad Frost. You can read about it more in-depth at his great blog here: https://bradfrost.com/blog/post/atomic-web-design/

The biggest take away we use here is the component structure, Brad breaks down UI structures into 5 layers:

Atoms

Your lowest level, dumb components - think your basic image component which can be used repeatedly:

    ...

    export const Image = ({ source, height, width, ...props }) => (
      <ImageElement src={source} height={height} width={width} {...props} />
    );

Molecules

This is where we start pulling our Atoms together to form a bit of a structure, here we can take our image component, pair it with a text component to make this song listing component:

    import { Image } from "../../atoms/image";
    import { Title } from "../../atoms/typography";

    ...

    export const SongListing = ({ imageSrc, songTitle, onPress }) => {

      const handlePress = () => {
        onPress(songTitle);
      }

      return (
        <ClearButton margin="16px 32px 0 32px;" width="80%" onPress={handlePress}>
          <Container>
            {imageSrc && <Image source={imageSrc} height="48px" width="48px" />}
            <SongTitle>{stringShortener(`${songTitle}`, 30)}</SongTitle>
          </Container>
        </ClearButton>
      );
    };

Organisms

Here is where it starts getting interesting, we can pull our Atoms and Molecules together in larger components for our pages, still in a reusable way. You can consider a form component, or this handy album list component:

    import { Title } from '../../atoms/typography';
    import { SongListing } from '../../molecules/songlisting';

    ...

    export const AlbumList = ({ albumArt, songList = [], artist, onSongPress }) => {
      return (
        <Container>
          {
            songList.map(songTitle => <SongListing key={songTitle} imageSrc={albumArt} songTitle={`${songTitle} - ${artist}`} onPress={onSongPress} />)
          }
          <Title>no more songs in album</Text>
        </Container>
      );
    }

Templates

So now we've defined the elements of our pages, templates define the overall structure of your page without any defining state management or event handling.

This is where a combination of components come together to form the look and feel of a page.

You can think of this like a blog post structure without the real words on the page and replaced with placeholders (or nothing).

Pages

This is where our structure comes to life. We can now implement our controlling handlers and state management. So in short, Pages provide the thought behind the UI.

Part 2: Molecular Bonds

Molecular Bonds (or Covalent Bonds) are chemical bonds which hold atoms together (pretty fancy).

Here we can consider our container components (our sections, divs, pages etc) as our molecular bonds. So why not define our layout components:

    export const horizontalView = styled.div`
      display: inline-flex;
      align-items: center;
      justify-content: center;
    `;

This would then give our components a slightly different structure, if we consider our molecule structure with it's own defined layout component, it would look something like this:

The simple change here is that the div get's replaced with our new horizontalView component, this may seem like a small or insignificant change to point out, but we get a big benefit for sharing components as you will see later on.

You're probably thinking we're going to end up with loads of different or even quite complicated layout components. In a way, you're correct. But that isn't such a bad thing, defining the behaviour of your layout components will help keep a consistent layout styles across your site as you can define spacing. We can also consider the use of props to limit the number of duplicated layout components.

Part 3: Build Orchestration

There are two parts to this we need to look at?

What builds our web project?

In short, Webpack. Luckily for us, our needed functionality comes for free out the box: Webpack looks for javascript files containing our code. If it doesn't find a valid file we hit a bit of a snag and the build fails.

Webpack will import all of the appropriate files to use for the web during bundling so our albumList component will look like this for web:

What builds our native project?

Metro Bundler steps in here, it gathers our javascript resources together and serves them to the application. The process Metro Bundler uses to find files is what's interesting here:

Metro Bundler will look for a platform specific file for a component (i.e. index.ios.js)
Failing that, it will look for a valid cross platform file (index.native.js)
If both cannot be found it will result to looking for any compatible for a component (index.js)

So, using the same albumList component with our abstracted atoms and bonds, we will see a structure like this for iOS as metro bundler kicks in and bundles our component together for us:

Our component looks remarkably similar, but we can see our atoms and layout components have been chosen using the platform specific file types.

Part 4: Why Styled-Components?

With all this sharing of components we want to keep the language of our components clear and reusable. Styled-Components (with it's web and native support) is perfect for this task. Let's have a look at our typography component:

    // typography/index.js

    import styled from 'styled-components';

    export const Title = styled.p`
      font-size: 16px;
      font-family: sans-serif;
      font-weight: 600;
    `;

Here we create a simple web component, Title, and we apply some styling to it. Now if we wanted to define the same component for React Native using styled-components we would end up with this:

    // typography/index.native.js

    import styled from 'styled-components/native'; // different import

    export const Title = styled.Text`
      font-size: 12; {/* different font-size */}
      font-family: sans-serif;
      font-weight: 600;
    `;

They're looking pretty similar right? The structure is the same, the only real differences are the font-sizes (which we could make more flexible using theming) and the import statement.

This shared use of a similar styling language is handy as this allows us to simplify our development experience, we also get the added bonus of being able to expand on base styling in higher up components as we're about to see.

Part 5: Sharing Code

We've seen how the bundlers pick up our file types for use across platforms but by structuring our UI components to abstract away as much as possible we can then share components at a higher level all from a single file.

Let's look again at our Title component from above, if we were to then go ahead and make a new component (fancyComponent) we can define a single file:

    // fancyComponent/index.js

    import { Title } from './typography'

    const RedTitle = styled(Title)`
        color: red;
    `;

This new fancy component, between it's builder and styled-components, would work on both React Native and React web projects since we've defined its children for both native and web and our builders will select their appropriate file type.

On top of that, we would see the same color: red; styling take effect on all platforms as we're using styled-components across both platforms. So our component will look like this:

Finale

So there we have it, we've managed to define a component and use a single file across React and React Native, without the need for anything super fancy. Now all we need to do is add this component into our component library module and use it for our different platforms.

It's important to note a few things:

Just because we can share code, doesn't mean we always should
This method of development expects there to be many components, and thats ok! Just reuse when you can or consider making a component more adaptable before making a new one (maybe our RedTitle component could've been a colour prop added to the base level Title component)
This way of working work works better when the same dev/team are making changes across all platforms

Well, that's it from me. If you want to reach out, please do. As always, this isn't the only way to do this kind of work, just the way that I have.

How I'm testing my custom React Hook with Enzyme and Jest

Joe Purnell — Sun, 17 Nov 2019 13:07:33 +0000

I've been messing around with React Hooks for a good while in personal projects, the joy of personal projects is there's not too much need to fulfill testing requirements.

Then came along a shiny greenfield project at work. Not going into detail about that here but there is one detail you can probably guess, we used Hooks.

Disclaimer: I'm assuming you're all good with React, Hooks, Enzyme, and Javascript.

Disclaimer #2: Also, I'm not saying this is the number one best way to test custom hooks, just that this is how I found I can do it in the project I had.

So we have a tasty custom hook:

export const usePanda = () => {
  const [loading, setLoading] = React.useState(false);
  const [panda, setPanda] = React.useState(undefined);

  const getNewPanda = async () => {
    setLoading(true);

    setPanda(await new Promise(resolve => {
      setTimeout(() => {
        resolve(`/assets/${Math.ceil(Math.random() * 5)}.jpeg`);
      }, 500);
    }));

    setLoading(false);
  };

  return {
    getNewPanda,
    loading,
    panda
  };
};

Pretty simple really, we're pretending to be an API call to get a random Panda image, cause who doesn't love Pandas? So in our component, we can use our hook in our useEffect:

const { loading, panda, getNewPanda } = usePanda();

useEffect(() => {
  async function fetchData() {
    await getNewPanda();
  }
  fetchData();
}, []);

Here we've opted to implement our hook and perform our getNewPanda() call on the first mount.

So we have our hook in place and working, but how do we test our custom hook to safeguard any future unwanted changed? Let's have a gander...

The first run testing a custom hook didn't end too well. I got his with this message:

Invalid hook call. Hooks can only be called inside of the body of a function component.
- Jest

This happened as I tried to implement my hook like any other function in any other unit test:

it('failing test', () => {
  const { getNewPanda, loading, panda } = usePanda(); // Error thrown on first line
  getNewPanda();
  expect(panda).not.toEqual(undefined);
});

I hit the paths of Google looking for a solution, first result? The React docs. (hindsight - should've gone straight there)

You can only call Hooks while React is rendering a function component
- https://reactjs.org/warnings/invalid-hook-call-warning.html

So our problem was that we weren't calling our new panda hook in a real React function component.

This spurred me on to write a component in order to mount this panda hook. I hit despair - I could mount a component and our hook but then I couldn't get the mount to update with new values when the hook function was called. That was annoying.

That's when I stumbled across this Kent C Dodds video.

The above is a great video, I would recommend a watch. The biggest take away here was the difference in mounting components. Where Kent passes the hook as a child and initialises it, I was passing it as a prop which while mounted the hook, it didn't update the state as well (maybe I was doing something else wrong).

Minor niggle: The project I was working in wasn't using react-testing-library, we were using Enzyme.

So, I took the help from Kent and went about adjusting the mounting component which ended up like this:

export const mountReactHook = hook => {
  const Component = ({ children }) => children(hook());
  const componentHook = {};
  let componentMount;

  act(() => {
    componentMount = Enzyme.shallow(
      <Component>
        {hookValues => {
          Object.assign(componentHook, hookValues);
          return null;
        }}
      </Component>
    );
  });
  return { componentMount, componentHook };
};

Yes, this is remarkably similar to Kent's solution, just mount in a different way. That's why I'm here not taking credit for this overall solution.

So what we're doing here is accepting a hook, passing it as a child to a component which is mounted by Enzyme. When the mount occurs: Enzyme populates return values from the hook and mount.

Now we can call our hook within a nice controlled component in our tests:

describe("usePanda Hook", () => {
  let setupComponent;
  let hook;

  beforeEach(() => {
    setupComponent = mountReactHook(usePanda); // Mount a Component with our hook
    hook = setupComponent.componentHook;
  });

  it("sets loading to true before getting a new panda image", async () => {
    expect(hook.loading).toEqual(false);

    await act(async () => { // perform changes within our component
      hook.getNewPanda();
    });

    expect(hook.loading).toEqual(true); // assert the values change correctly

    await act(async () => {
      await wait(); // wait for the promise to resolve and next mount
    });

    expect(hook.loading).toEqual(false); // reassert against our values
  });

  it("sets a new panda image", async () => {
    expect(hook.panda).toEqual(undefined);

    await act(async () => {
      hook.getNewPanda();
      await wait();
    });

    expect(hook.panda).not.toEqual(undefined);
  });
});

The biggest takeaways from here are to remember to wrap our calls in 'acts' as we're essentially changing the component we need to tell the DOM that something's changing.

There we have it! A mounted custom React Hook in a testable way using Enzyme and Jest. I hope this helps you with your testing journey.