DEV Community: Harrison Reid

👨‍💻 4 Simple Strategies to Auto Promote Your Gatsby Blog

Harrison Reid — Thu, 02 Jul 2020 22:12:03 +0000

I've recently launched a product I've been working on for while: Ippy.io - a better resume builder. It's live on Product Hunt now, so check it out here if you're interested 😀

What you’ll learn:

How to set up an RSS feed for your Gatsby blog
How to leverage your RSS feed to automate promotion of your posts

Consistently creating content is hard enough. So when I’ve finally put the finishing touches on a post, the last thing I feel like is spending time marketing and promoting it.

I’d much rather have robots do the hard work for me.

Thankfully, if you’re using Gatsby it’s really not all that hard to set up automations to promote each of your new posts while barely lifting a finger.

1. The Secret Sauce (RSS!)

RSS? Didn’t that die out a decade back? Not quite!

Setting up an RSS feed for your blog is the simplest way to enable other third party services to check for new content - which is super handy if you want to leverage such services to run some sort of automation.

If you’re building a Gatsby site, setting up a fully functional RSS feed couldn’t be easier. In fact, assuming you’re okay with all the default settings and are using markdown, it takes literally a single line of code.

We’re going to use the offical gatsby-plugin-feed plugin for this, so you’ll want to add it to your project with:

npm install --save gatsby-plugin-feed

Next you’ll want to add the plugin to your gatsby-config.js file, which should look something like this.

module.exports = {
  siteMetadata: {
    siteUrl: `https://www.your-site-url.com`,
  },
  plugins: [
    `gatsby-plugin-feed`,
    // ...Other plugins
  ],
  // ...
};

The next time you run a production build of your site, you should be able to find your RSS feed available at your-site.com/rss.xml.

If you run into any problems, or need to customise things further, the plugin is well covered in the official Gatsby docs.

2. Auto Post to Social Media

Now that you’ve got the RSS feed set up, the world is your oyster!

The simplest integration is to utilise a tool like Zapier to automatically send updates to your social accounts when you publish a new post.

Zapier actually has a pretty generous free tier. You get 100 free Zaps per month.

So, for example, you could set it up to push your newly published article to your Twitter, Facebook and LinkedIn, and if you publish an article every day (good on you!) you’ll still end up with a few Zaps left over at the end of the month.

I won’t bother with the details of configuring this because honestly Zapier makes it pretty easy.

You’ll basically just need to select RSS feed as the trigger for the Zap, enter your URL, and then follow their walkthrough process to hook it up to whichever social account you want.

3. Cross Post Content to Dev.to

Having trouble finding an audience for your content? Cross posting can be a good solution to get some initial readers, and hopefully drive some traffic back to your own site.

Dev.to is a great option for cross posting; your content gets broadcast to a ready made technical audience who are always friendly, and eager to provide valuable feedback.

Again, RSS makes this a cinch to set up - just head to your dev.to Settings > Publish from RSS, and enter the URL of your RSS feed. Hey presto - all your new posts will pop up as drafts in your dashboard, so you can check them, make any adjustments for formatting (often not required), and publish to dev.to.

Even better, dev.to embeds a link back to your site, and will automatically include your site url as the canonical_url, which means you shouldn’t see any ‘duplucate content’ SEO penalties from Google.

4. Generate an Email Newsletter Summary

If you’re interested in allowing users to sign up for a “Newsletter”, then RSS again makes it very very easy to automatically collate your new posts into an email to send out to your subscribers.

I’m using MailChimp for this, however I’ve seen similar functionality offered by other email marketing SAAS providers.

You just need to find one that works best for you.

How To Add Custom Fields to Your Gatsby RSS Feed

Harrison Reid — Tue, 30 Jun 2020 22:12:03 +0000

I've recently launched a product I've been working on for while: Ippy.io - a better resume builder. It's live on Product Hunt now, so check it out here if you're interested 😀

What you’ll learn:

How to declare custom namespaces on your Gatsby RSS feed
How to use the namespaces to add custom elements

What you’ll build:

An RSS feed with custom data!

I’ve recently been working on adding up an RSS feed for Days of Dev using gatsby-plugin-feed.

While setting this up, I found myself facing a small roadblock; I wanted to add additional custom data to the RSS feed, and couldn’t figure out how to get it working. Specifically, I wanted to add the full text of tweets that I’d auto generate from various frontmatter fields.

This would allow me to easily post to my social accounts through Zapier without having to mess around with any complex logic to compose the tweets in Zapier itself (and importantly, let me avoid having to pay for a premium account!).

It wasn’t immediately clear to me from the Gatsby docs how to get this working, so I thought I’d post this up here in case anyone faces the same problem in the futture!

It’s worth noting it is actually documented, but it’s included under a header explaining how to add iTunes RSS blocks, which I didn’t pick up on initially.

The Key: Namespaces

If you, like me, know next to nothing about RSS, you might’ve assumed that you can just throw any XML into an RSS feed. Well, actually, you pretty much can! But there is a slight catch…

To add custom elements (with custom data), you need to namespace them.

Fortunately, this is reasonably straightforward (particularly because we’re using gatsby-plugin-feed). Basically, it means that in the output XML, you need to declare the namespace, then prefix all of your custom xml tags with the declared namespace.

For example, in the RSS feed for Days of Dev (available at daysof.dev/rss.xml), you’ll see the namespace declaration in the opening <rss> tag - xmlns:daysofdev="https://www.daysof.dev".

Then, when I’ve added custom data, the tag name is always prefixed with the namespace followed by a colon. For example, the tag containing the tweet for a given post is included as: <daysofdev:tweet>Some text...</daysofdev:tweet>

Setting up gatsby-plugin-feed

Using gatsby-plugin-feed to set up namespaces, and include custom data, is relatively straightforward.

To start with, follow the instructions in the gatsby docs to customise the RSS feed plugin.

This should leave you with a gatsby-config.js with a plugin config for gatsby-plugin-feed that looks something like the following. Note that I’ve excluded a number of the option fields here for brevity, so directly copy-pasting the whole snippet will almost certainly cause you problems.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-feed`,
      options: {
        feeds: [
          {
            serialize: ({
              query: { allMarkdownRemark },
            }) => {
              return allMarkdownRemark.edges.map((edge) => {
                return Object.assign(
                  {},
                  edge.node.frontmatter,
                  {
                    ...
                    custom_elements: [
                      { "content:encoded": edge.node.html },
                    ],
                  }
                );
              });
            },
            ...
          },
        ],
      },
    },
  ],
};

To include a custom element, we need to make two changes:

Firstly, we need to tell gatsby-plugin-feed about the namespace we wish to declare. This is achieved by adding the setup option, which extends the options with a custom_namespaces field. In this example, we’ve added yournamespace. I don’t think the URL value of the is particularly important, as long as it’s unique to your namespace.

Secondly, we include the custom element under the custom_elements field in the output of the serialize function. You can see this added in the example as:

{ "yournamespace:yourcustomfield": edge.node.fields.someField }

Note that the custom element name must use the namespace, followed by a colon.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-feed`,
      options: {
        setup: (options) => ({ ...options, custom_namespaces: { yournamespace: "https://www.yournamespace.com", }, }), feeds: [
          {
            serialize: ({
              query: { allMarkdownRemark },
            }) => {
              return allMarkdownRemark.edges.map((edge) => {
                return Object.assign(
                  {},
                  edge.node.frontmatter,
                  {
                    ...
                    custom_elements: [
                      { "content:encoded": edge.node.html },
                      { "yournamespace:yourcustomfield": edge.node.fields.someField } ],
                  }
                );
              });
            },
          },
        ],
        ...
      },
    },
  ],
};

This should be all you need to add arbitrary custom data to your RSS feed generated by gatsby-plugin-feed. When you next deploy your app, you should have the custom data available to make use of wherever your RSS feed is being consumed.

🤦‍♂️ Cartoonify Yourself!

Harrison Reid — Sat, 23 May 2020 00:03:13 +0000

Last week I wrote up a post about how I'd trained a neural network to "cartoonify" pictures of peoples faces.

🤷‍♂️ How I trained a neural network to turn you into an Archer cartoon

Harrison Reid ・ May 14 ・ 4 min read

#javascript #python #showdev #machinelearning

I also made it available as a twitter bot (so you could tweet at me and have your profile pic cartoonified). I think about 30 or 40 people ended up using it to cartoonify their profile pics, which was a lot of fun 😀

Anyhow, I'm planning to retire the twitter bot soon (because 💸) - but I've now converted the code to run entirely in the browser using tensorflow.js, and made it available online.

Check it out here.

Note: Currently doesn't seem to work reliably (or possibly at all) on mobile browsers - working on fixing this. Also, the cartoonifying effect tends to only work on relatively close up pictures of faces (presumably as thats what it was trained on). So feel free to play around with other kinds of images, but the results probably won't be great.*

🤷‍♂️ How I trained a neural network to turn you into an Archer cartoon

Harrison Reid — Thu, 14 May 2020 14:23:41 +0000

A few weeks back I decided I wanted a cartoon version of my profile picture.

Sadly, as I'm not much of an artist, drawing it myself was out of the question. So I set about on what seemed the only other logical course of action...

I trained a neural network to do it for me!

// Detect dark theme var iframe = document.getElementById('tweet-1260864003149979648-961'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1260864003149979648&theme=dark" }

Let's get this out of the way - if you'd like a cartoon version of your profile picture, here's how:

Tweet at me (@harrison_g_reid) and include "cartoonify me" somewhere in the text of the tweet.
Within a few minutes, my (hopefully?) dependable twitter bot will reply with a cartoon-ified version of your profile picture.

NOTE: Since this was posted, the twitter bot has been disabled because 💸, but I've put it online so you can try it out here

I should warn you, the results are...mixed. But it's funnier when it does a terrible job anyway, so 🤷‍♂️. Here's a GIF demo:

Read on if you want to learn how I built it...

Finding a Model (CartoonGAN):

The first thing I did after deciding that this would be a fun project was google around to see if there were any existing libraries I could use.

As usual, the open source world did not disappoint! I soon came across a tensorflow implementation of the CartoonGAN generative adversarial neural network.

mnicnc404 / CartoonGan-tensorflow

Generate your own cartoon-style images with CartoonGAN (CVPR 2018), powered by TensorFlow 2.0 Alpha.

The Github repo has some really cool examples of converting images and gifs into anime style cartoons - I recommend checking it out.

But this wasn't quite the style I was after. I wanted something a little more comic-book style - heavy black lines & flat colors. I wanted it to look like Archer!

Fortunately, the repo contains some pretty detailed instructions on how to train the network on your own training data.

So, I set about gathering a lot of images.

Gathering Data:

To train CartoonGAN, I would need two sets of images:

A large set of real life images of human faces.
An equally large set of cartoon faces (from Archer)

It was relatively easy to find a good dataset of human faces. I found the VGGFace2 face dataset, which is an enormous dataset, and far exceeded my needs.

Of course, there's no dataset of faces from Archer available, so I'd need to create my own.

Since I was aiming for a dataset of about 3500 images, there was no way I could realistically do this manually.

It took a little creativity, but I managed to mostly automate this. It basically ended up as a four stage process.

Using ffmpeg, extract a frame for every 4 seconds of video, for every episode of the first season of Archer. (If you're interested, the ffmpeg command to do this for a single video is: ffmpeg -i video.mov -r 0.25 video-images/%04d.png.)
Detect the location of all the faces in every frame using facedetect. Yes, this works surprisingly well on cartoon faces!
Crop images for each located face using Jimp.
Manually check the extracted images, and remove all weird things that had incorrectly been identified as faces.

The end result was a set of ~3700 images. Just about every face from the first season of archer:

Now we're talking.

Training the Model:

This was the easy part - it basically involved cloning the the CartoonGAN repo mentioned above, copying the images to the correct directory and running the python script as per the instructions in the repo.

It was a real workout for my computer though - it took several days running the training in the background to make it through 30 epochs of training.

Here's a gif of the training progress over the first few epochs.

Running it on Node:

If you're a JavaScript developer and you haven't tried TensorFlow.js yet, get amongst it. You don't really need to know all that much about Machine Learning to make use of existing models, and build some cool stuff.

In any case, the Node API's for TensorFlow.js let you directly load the format of model output by the CartoonGAN training process (SavedModel format).

Viola! A cartoon generating neural network running on Node.

If you're interested in how I've deployed the model as a twitter bot, stay tuned! I'll provide a walkthrough in a future post.

Note: The code for this isn't yet available on my Github, but will be made available soon.

✨ How To Start and Finish a Side Project ✨

Harrison Reid — Sun, 26 Apr 2020 17:07:50 +0000

I've been working on my side project ippy.io a fair bit recently, and have made good progress on it. I'm happy with the functionality, and it's now available online for people to use.

For me, this is a success - but I've worked on a lot of other side projects over the last few years - and none of the rest have ever reached this point. They've always either just fizzled out, or I've become distracted by some new idea and moved on.

I've been thinking about why I've had so much trouble sticking with side projects in the past, and the changes in attitude that I think have helped me overcome this.

I posted about this on twitter yesterday, in the form of a (long) tweet thread. I've unrolled it below for ease of consumption. Enjoy!

Harrison Reid

@harrison_g_reid

✨How to start and finish a side project (a twitter thread)✨

I’ve spent a lot of time over the last few years working on a whole bunch of different side projects. Precisely one (1) has reached a point that I’m happy with. My github is a graveyard where side projects go to die.

03:36 AM - 26 Apr 2020

0 0

How To Start and Finish a Side Project

I’ve spent a lot of time over the last few years working on a whole bunch of different side projects. Precisely one (1) has reached a point that I’m happy with. My GitHub is a graveyard where side projects go to die.

I suspect I’m not alone here - a lot of people seem to find finishing their side projects really hard.

So, how do you make it easier?

I’ve been thinking about this, particularly in the context of trying to build a project that makes money. These are those thoughts 🤔...

👉 Quit fetishizing ideas, embrace unoriginality!

It’s easy to get stuck before you start. You can spend months in a purgatory of ideation - dreaming up the next big thing, and the next! But if all you have are ideas, then you don't really have anything.

What’s more, a project doesn’t need the potential to be the "Uber of X", or the "AirBnB of Y" to be worthy of your time. You don't need to put a dent in the universe. It’s a perfectly valid to take something that already exists in the world and try to make it better.

Focus less on disruption, and more on distillation. Work to find the best in existing solutions, and cut away the bad. Less revolution, more refinement.

With that in mind, here’s a 3 step process to find your next side project!

Google around for products that exist in a space that you find interesting.
Find a successful product where you think - "Yeah, I could build this".
Build it!

Don’t steal the design, don’t steal the code, don’t steal the copy. But by all means begin by replicating functionality. Then, improve it. Build a more intuitive UI. Serve a different niche. Make it faster. Make it cheaper.

Being original is overrated. Google wasn't the first search engine. McDonalds wasn't the first hamburger joint. Facebook wasn't the first social network.

In reality, the original is almost never the best. So don't put so much focus on being original - focus on being the best!

👉 Take it slow.

If you believe in the 80/20 rule, then you can expect 80% of progress on a project to come from 20% of the time spent on it. I don’t know how accurate that is, but I can say for sure that productivity comes in waves.

So don’t stress the days that you feel like you’re getting nowhere. It’s okay to step away from the computer for a while. Take the day off. Take the week! If you're not feeling it, you're not feeling it. All you're likely to gain by pushing on is a bad mood.

Overwork is a sure fire way to kill off your excitement and motivation. When it does, it’s only a matter of time before some new, shiny idea pops into your head. You chase the excitement of the fresh idea. The old project is soon forgotten, and the cycle continues.

Just aim for consistent progress over time, and don’t sacrifice your sanity for the sake of a side project.

👉 Redefine what “finishing” means.

If your end goal is to create a business that generates income over the long term, then you should probably stop thinking in terms of “finishing”. In this context, being finished probably means your product failed.

Take a long view. Accept up front that you’ll be working on this project for many months. It makes it easier to step back for a while when you need a break, and to resist the pesky new ideas that pop up to distract you.

I’m not saying you can’t move on from a project if it’s just not working out. But you want to be able to look back on it with at least a little pride, knowing that you actually gave it a good shot. This requires a long term approach.

If you liked this post, follow me on twitter!. I'll be posting about my experiences building ippy.io, and my ongoing attempts to find it some users 😉

2 Examples To Help You Understand JS Closures Once And For All 🙃

Harrison Reid — Fri, 07 Feb 2020 12:33:11 +0000

If you find this post useful, you can follow me on twitter, sign up to my mailing list or check out the other posts on my blog. I've also got a couple of active side projects that you might like to check out:

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs

Closures are one of the classic “gotchas” in JavaScript. There are countless articles across the internet describing closures as something you absolutely need to understand to consider yourself a competent developer, or must know before your next job interview, etc etc.

Don’t get me wrong, understanding closures is very important. The thing is, I think there’s a reasonable chance you already understand them, but just don’t understand that you understand them 😉. But if you don’t, hopefully you will soon.

It’s just a hunch, but my guess is that a fair bit of the confusion around closures is simply due to terminology. That is, it can take some time to connect unfamiliar words like ”closure” and “lexical scope” with behaviour you’ve observed and perhaps already understand in your code.

Let’s take a look at a relatively straightforward example to test your current understanding.

1. Counter

Take a look at the code below, and try to figure out the answers to the two commented questions (without running the code).

function createCounter() {
  var count = 0
  function getNext() {
    count ++
    return count
  } 
  return getNext
}

console.log(count)
// ==> 1. What will this output?

const getNextNumber = createCounter()

const firstNumber = getNextNumber()
const secondNumber = getNextNumber()
const thirdNumber = getNextNumber()
const fourthNumber = getNextNumber()

console.log(
  firstNumber,
  secondNumber,
  thirdNumber,
  fourthNumber
)
// ==> 2. What will this output?

If you answered:

ReferenceError (or if you knew this would be some kind of error)
1, 2, 3, 4

Congratulations! You understand closures!

There are two things you need to grasp from the code above:

The count variable is not accessible anywhere outside of the createCounter() function.
The count variable is accessible to any functions that are declared within the createCounter() function (where it was initially declared).

This is all that a closure is. Using a function (in our case createCounter() ) to close over a variable.

There is no way for the count variable to be accessed or set from anywhere else in our code, except via the function that we define and return from createCounter(), the getNext() function.

As you can see, getNext() (since it was declared inside createCounter()) maintains access to the count variable, and is able to increment and return it.

Let’s take a look at a slightly more complex example.

2. Election Day

Imagine we’ve been tasked with running an election. It’s a somewhat odd election, as voters will be casting their ballots from our JavaScript console.

We want a way to:

Keep track of the votes
Allow people to cast votes
Retrieve the final results (in a secure, password protected way)

We could do something like this (but shouldn’t):

var candidateOneVoteCount = 0
var candidateTwoVoteCount = 0

function voteForCandidateOne() {
  candidateOneVoteCount ++
}

function voteForCandidateTwo() {
  candidateTwoVoteCount ++
}

function getResults(inputPassword) {
  if (inputPassword !== "password123") {
    throw new Error("Wrong password")
  }
  return {
    candidateOne: candidateOneVoteCount,
    candidateTwo: candidateTwoVoteCount
  }
}

Since the variables storing the candidates votes are defined in the global scope, anyone casting their vote could sneakily rig our election simply by running candidateTwoVoteCount = 1000000.

We need to keep our vote counts private. We only want it to be possible to change or retrieve these variables via the interface that we’ve defined. That is, via:

voteForCandidateOne()
voteForCandidateTwo()
getResults()

How can we achieve this? With a closure. Let’s refactor the code above to use a closure.

function createElection(password) {
  var candidateOneVoteCount = 0
  var candidateTwoVoteCount = 0

  function voteForCandidateOne() {
    candidateOneVoteCount ++
  }

  function voteForCandidateTwo() {
    candidateTwoVoteCount ++
  }

  function getResults(inputPassword) {
    if (inputPassword !== password) {
      throw new Error("Wrong password")
    }
    return {
      candidateOne: candidateOneVoteCount,
      candidateTwo: candidateTwoVoteCount
    }
  }

  return { 
    voteForCandidateOne, 
    voteForCandidateTwo, 
    getResults 
  }
}

const {
  voteForCandidateOne, 
  voteForCandidateTwo, 
  getResults 
} = createElection("password123")


console.log(candidateOneVoteCount)
// ReferenceError

console.log(candidateTwoVoteCount)
// ReferenceError

console.log(getResults("incorrectPassword"))
// Error: Wrong password

console.log(getResults("password123"))
// => { candidateOne: 0, candidateTwo: 0 }

voteForCandidateOne()
voteForCandidateOne()
voteForCandidateTwo()

console.log(getResults("password123"))
// => { candidateOne: 2, candidateTwo: 1 }

// Please never run a real election using code like this.

Our interface functions voteForCandidateOne(), voteForCandidateTwo() , getResults() are now declared within, and returned from createElection(). As they are declared in the same scope, they maintain access to the variables storing the vote count (candidateOneVoteCount & candidateTwoVoteCount).

It’s also worth noting that the functions also maintain access to the password argument that is provided when createElection() is called. This is later compared to the password provided in getResults() to validate access.

Let me know if anything here is unclear, and I'll do my best to explain it further! 🍻

3 Simple Snippets to Help You Understand Array .reduce()! 🥳

Harrison Reid — Tue, 04 Feb 2020 14:05:21 +0000

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs

Are you having trouble getting your head around the JS Array .reduce() method?

If so, don't worry - you're not alone. For whatever reason, the reduce method seems to take a while to click for many developers. I've been in this boat myself. Fortunately, once you break things down, it's not too complex.

My aims for this article are to:

Offer what I think is a useful mental model for thinking about .reduce().
Provide a series of usage examples to strengthen your understanding

Let's get started.

The Mental Model

Reduce is often introduced as a way of reducing an array to a single value. While this is indeed what it does, I've never found this to be particularly helpful in understanding how it works, or what I might be able to do with it.

For me, the simplest way to think about .reduce() is as a fancy case of .forEach(). The essentials are similar:

We provide a callback function
We iterate over the array, and execute the callback function once per array item.

The important differences are that with .reduce():

Each invocation of the callback is aware of the return value of the previous invocation (or on the first call, the initial value we've provided).
Once there are no more items in the array, the return value of the last callback invocation is returned as the final result of the .reduce() call.

In fact, we can implement a reduce function ourselves using a slim wrapper around .forEach():


const reduce = (array, callback, initialValue) => {
  // Originally stores the initialValue then updated
  // on each iteration with the return value of the callback.
  let previousReturnValue = initialValue

  // Iterate over the array items, updating the currentReturn value at each step.
  array.forEach((item, index) => {
    const result = callback(previousReturnValue, item, index, array)
    previousReturnValue = result;
  })

  // Return the final value once all array items have been iterated over
  return previousReturnValue
}

Let's now look at some examples of using .reduce(), and step through the execution path.

1. Adding an array of numbers

In this common example, we're adding an array of numbers to arrive at a final sum:


const initialValue = 0

const numbersToAdd = [ 1, 2, 3, 4 ]

const addFunction = (runningTotal, numberToAdd) => {
  return runningTotal + numberToAdd;
}

const sum = numbersToAdd.reduce(addFunction, initialValue)

console.log(sum)
// => 10

// =======================================================

// How was this calculated? Lets step through it:

// The addFunction callback is invoked for each array item:

// -- FIRST CALLBACK INVOCATION -- 
// Array Item => 1
// Previous return value => first invocation (so the initialValue is used)
// Callback invocation => numbersToAdd(0, 1)
// Callback return value => 1

// -- SECOND CALLBACK INVOCATION --
// Array Item => 2
// Previous return value => 1
// Callback invocation => numbersToAdd(1, 2)
// Callback return value => 3

// -- THIRD CALLBACK INVOCATION --
// Array Item => 3
// Previous return value => 3
// Callback invocation => numbersToAdd(3, 3)
// Callback return value => 6

// -- FOURTH (AND LAST) CALLBACK INVOCATION --
// Array Item => 4
// Previous return value => 6
// Callback invocation => numbersToAdd(6, 4)
// Callback return value => 10

// Final Result: 10

2. Finding the largest of an array of numbers

Here we'll use reduce to find the maximum value in an array.

This is a slightly special case, in that we haven't provided .reduce() with an initial value argument. Because of this, .reduce() skips the callback for the first array item, and instead uses it as the initial value for the callback invocation on the second array item.


const numbers = [ 10, 40, 4, 50, 101 ]

const findLarger = (currentMax, numberToCheck) => {
  if (numberToCheck > currentMax) {
    return numberToCheck;
  }
  return currentMax;
}

const largest = numbers.reduce(findLarger)

console.log(largest)
// => 101

// =======================================================

// How was this calculated? Lets step through it:

// The findLarger callback is invoked for each array item:

// -- FIRST CALLBACK INVOCATION -- 
// Array Item => 10
// Previous return value => first invocation, and no initialValue provided
// Callback invocation => Not Invoked
// Callback return value => N/A

// -- SECOND CALLBACK INVOCATION --
// Array Item => 40
// Previous return value => nothing, however first array item will be used as the initialValue
// Callback invocation => findLarger(10, 40)
// Callback return value => 40

// -- THIRD CALLBACK INVOCATION --
// Array Item => 4
// Previous return value => 40
// Callback invocation => findLarger(40, 4)
// Callback return value => 40

// -- FOURTH CALLBACK INVOCATION --
// Array Item => 50
// Previous return value => 40
// Callback invocation => findLarger(40, 50)
// Callback return value => 50

// -- FIFTH (AND LAST) CALLBACK INVOCATION --
// Array Item => 101
// Previous return value => 50
// Callback invocation => findLarger(50, 101)
// Callback return value => 101

// Final Result: 101

3. Categorising an array into even/odd numbers.

Of course, you're not restricted to returning numbers from the callback in .reduce(). You can return anything you want. In this case, we return an object that is categorising the array values into even/odd buckets.


const initialValue = { even: [], odd: [] }

const numbersToCategorise = [1, 3, 4, 8, 10]

const categorisingReducer = (categories, numberToCategorise) => {
  const isEven = numberToCategorise % 2 === 0
  if (isEven) {
    categories.even.push(numberToCategorise)
  } else {
    categories.odd.push(numberToCategorise)
  }
  return categories
}

const categories = numbersToCategorise.reduce(categorisingReducer, initialValue)

console.log(categories)

//  => { even: [4, 8, 10], odd: [1, 3] }

// =======================================================

// How was this calculated? Again, lets step through it:

// The categorisingReducer callback is invoked for each array item:

// -- FIRST CALLBACK INVOCATION -- 
// Array Item => 1
// Previous return value => first invocation (so the initialValue is used)
// Callback invocation => categorisingReducer({ even: [], odd: [] }, 1)
// Callback return value => { even: [], odd: [1] }

// -- SECOND CALLBACK INVOCATION --
// Array Item => 3
// Previous return value => { even: [], odd: [1] }
// Callback invocation => categorisingReducer({ even: [], odd: [1] }, 3)
// Callback return value => { even: [], odd: [1, 3] }

// -- THIRD CALLBACK INVOCATION --
// Array Item => 4
// Previous return value => { even: [], odd: [1, 3] }
// Callback invocation => categorisingReducer({ even: [], odd: [1, 3] }, 4)
// Callback return value => { even: [4], odd: [1, 3] }

// -- FOURTH CALLBACK INVOCATION --
// Array Item => 8
// Previous return value => { even: [4], odd: [1, 3] }
// Callback invocation => categorisingReducer({ even: [4], odd: [1, 3] }, 8)
// Callback return value => { even: [4, 8], odd: [1, 3] }

// -- FIFTH (AND LAST) CALLBACK INVOCATION --
// Array Item => 10
// Previous return value => { even: [4, 8], odd: [1, 3] }
// Callback invocation => categorisingReducer({ even: [4, 8], odd: [1, 3] }, 10)
// Callback return value => { even: [4, 8, 10], odd: [1, 3] }

// Final Result: { even: [4, 8, 10], odd: [1, 3] }

Let me know in the comments if this was useful, or if anything about the .reduce() method is still unclear to you!

👉 What the ecma is ES6 anyway?

Harrison Reid — Mon, 03 Feb 2020 18:17:07 +0000

If you find this post useful, you can sign up to my mailing list, check out the other posts on my blog, or follow me on twitter. I've also got a couple of active side projects that you might like to check out:

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs

If you're new to JavaScript development, you've likely seen the terms ES6 and ES2015 mentioned, and perhaps wondered what the **** the writer was talking about.

You might've even suspected a typo - after all, you're learning JS not ES.

Regrettably, it's not a typo - you've just entered the somewhat confusing world of JavaScript version naming. Welcome.

So… What is ES?

ES is shorthand for ECMAScript.

I know, I know, you thought you were learning JavaScript! Well, you are, but turns out you're kind of sort of also learning ECMAScript. Two for the price of one!

ECMAScript is the specification that defines the functionality that the JavaScript language is expected to implement. Technically, JavaScript is an implementation of the ECMAScript standard.

It's actually quite interesting if you want to read more about it.

If not, for the most part you can get away with mentally substituting ES => JS, and ECMAScript => JavaScript.

And What About The Numbers?

The numbers are versions.

Like all programming languages, JavaScript has developed over time. New features have been added, making our lives as programmers easier, and allowing us to more effectively author complex applications (without our code devolving into carbonara).

As these new versions are released they are named. ES6, ES2015, ES7, ES2017 - these are all versions of the ECMAScript standard.

When you see references to an ES version, the author will often be writing about particular features of JavaScript that are have become available in said version.

Unfortunately, particularly for a few years, there were multiple names flying around for the same versions.

ES6 is ES2015
ES7 is ES2016

Whats happened here is that while originally ECMAScript versions were incrementally numbered and named, with the release of ES2015 there was a transition to naming based on the year of release.

ES6 (ECMAScript version 6) was released in June of 2015, so ES6 => ES2015
ES7 (ECMAScript version 7) was released in June of 2016, so ES7 => ES2016

Kind of makes sense right?

Unfortunately we in the JavaScript community often still use ES6/ES2015 and to a lesser degree ES7/ES2016 interchangeably, so you kind of just need to remember that these are equivalent.

ES2015 and ES2016 are also versions in which some fairly substantial changes were introduced to the language spec, so you're more likely to run into discussion of these versions than others.

The Future

Thankfully, in the years since the release of ES2016, the community appears to have somewhat settled into the year based naming scheme.

While you'll still see references to ES8, ES9 and ES10, referring to them as ES2017, ES2018 and ES2019 seems to have become the more common practice.

So cheers, to a slightly less confusing future 🍻

Beginners, What Would You Most Like to Build in a JavaScript Tutorial?

Harrison Reid — Fri, 31 Jan 2020 15:45:10 +0000

In many beginner JS tutorials, the end goal is to build an app of some sort, and they are frequently of a similar type: todo lists, stopwatch timers, pared down clones of common social media apps, etc.

There's obviously good reason for this - when you don't have to expend too much mental energy understanding what you're building, it's easier to understand how. They are also limited in scope, which makes them more manageable.

However when I was working through many of this type of tutorial a few years back, I've got to admit that I sometimes found myself getting a little bored...

So I'm interested to hear from the beginners out there - ignoring any issues of difficulty or complexity - what kind of app would you want to build in a project style tutorial?

3 Weird Things You (Probably) Didn't Know You Can Do With The JavaScript Spread Operator 🥳

Harrison Reid — Thu, 30 Jan 2020 12:59:49 +0000

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs

The spread operator has been enthusiastically adopted by the JavaScript community since its inclusion in the language with ES6, with good reason! It vastly simplifies many common object and array manipulations patterns.

While the common uses are widely appreciated and utilised, it also facilitates some slightly more obscure patterns.

Such as…

👉 1) Conditionally Adding Properties to an Object

It may not be particularly common, but imagine that (for whatever reason) you want to conditionally add properties to an object. Specifically, you want to add the properties if they hold a truthy value, but exclude them if they are null, undefined, or contain a falsey value. How might you approach this?

A reasonable approach might be something like the following:

const firstName = 'Harrison'
const lastName = null
const address = '123 Street Rd'
const phoneNumber = null

const userInfo = {}

if (firstName) {
  userInfo.firstName = firstName
}

if (lastName) {
  userInfo.lastName = lastName
}

if (address) {
  userInfo.address = address
}

if (phoneNumber) {
  userInfo.phoneNumber = phoneNumber
}

console.log(userInfo)

// {
//   firstName: 'Harrison',
//   address: '123 Street Rd'
// }

There's nothing wrong with this approach - however using the spread operator, we can move the conditional logic inside the object literal.

The result is somewhat more concise, and in my opinion once you've seen it a few times is actually more readable.

Take a look:

const firstName = 'Harrison'
const lastName = null
const address = '123 Street Rd'
const phoneNumber = null

const userInfo = {
  ...firstName && { firstName },
  ...lastName && { lastName },
  ...address && { address },
  ...phoneNumber && { phoneNumber }
}

console.log(userInfo)

// {
//   firstName: 'Harrison',
//   address: '123 Street Rd'
// }

If you haven't seen this pattern before, it might take a second to grok what's going on. I'll try to explain:

Lets consider the first line inside the object literal, a case in which the property should be added to the object:

...firstName && { firstName }

Since firstName was previously assigned the truthy value 'Harrison',
the expression firstName && { firstName } will return { firstName: 'Harrison' }. Both the left and right hand side of the && evaluate as truthy, and as such the right hand side is returned.

This returned object is then spread into the userInfo object, resulting in the firstName property being successfully set.

Next, lets consider the alternate case, in which we attempt to assign a falsey value. Lets take the second line of the object literal:

...lastName && { lastName }

In this case, lastName is null. This means that the expression lastName && { lastName } short-circuits to returning the left hand side of the &&, which in this case is null.

We then attempt to spread null into the userInfo object. You might think this should result in an error, but it actually doesn't.

In fact, as far as I'm aware spreading any falsey value into an object is perfectly valid syntax, but will result in no change to the object. Try it out:

let obj = { ...null }
console.log(obj)
// {}

let obj = { ...undefined }
console.log(obj)
// {}

let obj = { ...false }
console.log(obj)
// {}

let obj = { ...'' }
console.log(obj)
// {}

let obj = { ...0 }
console.log(obj)
// {}

let obj = { ...{} }
console.log(obj)
// {}

let obj = { ...[] }
console.log(obj)
// {}

The end result of all this is that any truthy values will be added to the object, while any falsey values are left out!

To make the code more explicit we can use the same pattern, but refactor the truthy check into its own function:

const hasIfTruthy = (propertyName, property) => {
  return property && { [propertyName]: property }
}

const firstName = 'Harrison'
const lastName = null
const address = '123 Street Rd'
const phoneNumber = null

const userInfo = {
  ...hasIfTruthy('firstName', firstName),
  ...hasIfTruthy('lastName', lastName),
  ...hasIfTruthy('address', address),
  ...hasIfTruthy('phoneNumber', phoneNumber)
}

console.log(userInfo)

// {
//   firstName: 'Harrison',
//   address: '123 Street Rd'
// }

Using this pattern, you can even completely alter the condition that dictates whether a property is included or excluded - it doesn't necessarily need to be based on just truthy-ness/falsy-ness.

👉 2) Spreading an Array into an Object

So… I'm yet to think of a particularly compelling reason that you would actually do this (shout out in the comments if you have one), but you can totally spread an Array into an Object.

The result is that each array element is inserted into the object, with the key set to its respective array index.

Check it out:

const fruitsArray = ['apple', 'orange', 'banano']

const fruitsObject = { ...fruitsArray }

console.log(fruitsObject)

// {
//   0: 'apple',
//   1: 'orange',
//   2: 'banano'
// }

👉 3) Spreading a String Into an Array (or an Object)

This one is actually pretty nifty, and is probably more widely known than the others. You can spread a string into an array!

The result is an array containing the individual characters from the string.

In my opinion this allows for a more pleasant syntax than the common 'string'.split('') style.

Here it is:

const characters = [..."apple"]

console.log(characters)

// ['a', 'p', 'p', 'l', 'e']

And if you're feeling really wild, you can even spread a string into an object 🙀

const characters = {..."apple"}

console.log(characters)

// {
//   0: 'a',
//   1: 'p',
//   2: 'p',
//   3: 'l',
//   4: 'e'
// }

Stay safe out there kids.

Know any other weird or wonderful uses for the JS spread operator? Let me know in the comments 😊

3 Deep Dive Tutorials to Make You a Better JavaScript Developer Today! 😎

Harrison Reid — Sun, 26 Jan 2020 17:17:36 +0000

In the modern JavaScript world, it's possible to be a remarkably productive developer while working with a relatively basic understand of the tooling and lower level structures supporting your work.

This is not a bad thing! It's a sign that the JavaScript world has developed an ecosystem of robust tooling and frameworks with maintainers who place a high value on user friendly documentation.

Having said that, when it comes time to solving obscure bugs 🐛, and Stack Overflow isn't giving you any love, having the knowledge (and patience) to drill down a few layers can be very helpful. Nothing beats getting into the weeds! 🌿

On that note, here are three of my favourite "deep-dive" style tutorials. Give these a whirl, and you'll learn a bunch, and likely gain much respect for the devs out there that maintain the tools we use every day!

1) Build Your Own React - Rodrigo Pombo ⚛️

Do you work with React? Do you actually know how React works? Like, under the hood? If not, get stuck into this tutorial and you will soon.

2) Eloquent Javascript Chapter 12: Build a Programming Language in JS - Marijn Haverbeke 👷

It's all in the title! You'll quite literally build your own programming language. And once you're done with this chapter, go back and read the rest of the book - you won't be disappointed.

3) Babel Plugin Handbook - jamiebuilds and contributors 👍

While not strictly a tutorial (although there is quick "Writing your first babel plugin" section), a read through the Babel Plugin Handbook (and the associated Babel User Handbook will take your understanding of this commonly used tool to a whole new level.

You'll also be introduced to a bunch of other concepts (like Abstract Syntax Trees) along the way.

Do you have any other recommendations for great JS deep dive tutorials? Let me know in the comments below! 😃

If you found this post useful, you can follow me on dev.to or twitter. I've also got a couple of side projects that you might like to check out:

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs

Build Your Own JavaScript Test Framework (in TypeScript)

Harrison Reid — Fri, 24 Jan 2020 21:33:49 +0000

This is the first in a planned series of posts where I'll take some heavily used tools from the JavaScript ecosystem and attempt to build minimal versions from the ground up.

If you've worked with JavaScript for a while, you might be familiar with some of the more common test frameworks. The two that spring to mind for me are Mocha and Jest, but there are plenty of others out there with varying levels of popularity.

These are powerful libraries, with great tooling built around them. If your aim is to effectively test an application you're working on, I strongly advise against building your own - just choose your favourite of the many existing options and get going.

However if you're interested in how you could approach this challenge, keep reading!

What we'll build

We're going to use typescript to build a test framework called Pretzel Test 🥨. It'll be basic but functional, and will provide:

A test API - ie: describe blocks, before/beforeEach blocks etc…
An expectations API - ie: expect(value).toEqual(someExpectedValue)
A test reporter to output results to the terminal
CLI invocation

If you don't have time to follow along, the final code and an example using Pretzel Test are available on github.

Here's a snippet to demonstrate the API we're shooting for:

import { describe, expect } from "pretzel-test";
import { addNumbers } from "./util.js";

describe("addNumbers")
  .before(() => {
    // Before block
  })
  .after(() => {
    // After block
  })
  .beforeEach(() => {
    // Before each block
  })
  .afterEach(() => {
    // After each block
  })
  .it("should correctly add two positive numbers", () => {
    const expected = 10;
    const actual = addNumbers(2, 8);
    expect(actual).toEqual(expected)
  })
  .it("should correctly add two negative numbers", () => {
    const expected = -10;
    const actual = addNumbers(-2, -8);
    expect(actual).toEqual(expected)
  })

As you can see, Pretzel Test will use a chainable API rather than the common nested describe blocks style. This was an intentional decision; I wanted to explore alternatives to that common pattern, as I find nested describe blocks can become unwieldy and difficult to parse.

Part One: Project structure

We're going to build this in TypeScript. Let's get started. First up, create a new project in your preferred fashion. For example:

$ mkdir pretzel-test
$ cd pretzel-test
$ yarn init

Then we'll install a few dependencies:

$ yarn add typescript colors command-line-args glob lodash
$ yarn add --dev @types/colors @types/node @types/glob

In your project root, create the following directory structure:

📁pretzel-test
|- 📝tsconfig.json
|- 📁bin
   |- 📝cli.js
|- 📁src
   |- 📝describe.ts
   |- 📝expect.ts
   |- 📝main.ts
   |- 📝reporter.ts
   |- 📝runner.ts
   |- 📝types.ts

Open tsconfig.json and add the following:

{
  "compilerOptions": {
    "outDir": "./dist",
    "lib": ["es2015"]
  },
  "include": ["src"]
}

It's not a complex tsconfig.json, however it's worth taking a look at the typescript docs if you're unsure about what's going on there.

If you're coding along in TypeScript, keep in mind that you'll need to compile the code with tsc before running it from the dist folder.

Then, in src/main.ts we'll import and and export the user facing API of pretzel test. The functions we import don't exist yet, but we'll build them out.

// src/main.ts

import { describe } from "./describe";
import { expect } from "./expect";

export { describe, expect };

Part Two: src/types.ts

In types.ts we'll define the main types that are used throughout the project. Taking a read through this should help you understand how the test framework is structured. Enter the following in your types.ts file. I'll explain it further below.

// src/types.ts

import { test, before, beforeEach, after, afterEach } from "./describe";

export interface ChainableApi {
  currentTestGroup: TestGroup;
  it: typeof test;
  case: typeof test;
  before: typeof before;
  beforeEach: typeof beforeEach;
  after: typeof after;
  afterEach: typeof afterEach;
}

export interface TestGroup {
  description: string;
  tests: Test[];
  before: Function[];
  beforeEach: Function[];
  after: Function[];
  afterEach: Function[];
}

export interface Test {
  description: string;
  fn: Function;
  result: TestResult;
}

export interface Options {
  rootDir: string;
  matching: string;
}

export interface TestResult {
  passed: boolean;
  error: Error;
  beforeError: Error;
  afterError: Error;
  beforeEachError: Error;
  afterEachError: Error;
}

Let's look at the interfaces we've defined in this file:

ChainableApi

This interface represents the object that will be returned by a call to describe(). Further, any chained calls to before() beforeEach() after() afterEach() or it() will return an object implementing this same interface, which will allow users of the API to chain an arbitrary number of calls to the initial describe() function.

The ChainableApi interface also references a currentTestGroup property, which we've declared as implementing the TestGroup interface.

TestGroup

Conceptually, a test group represents a parsed set of tests that begin with a call to describe() , and encompasses any chained methods on that call.

When it comes time to run our tests, the descriptions and callbacks passed in to the describe API will be pulled out into an object implementing the TestGroup interface.

To accomodate this, we've defined a description property of type string, to contain the test description passed to the initial describe() call. We've then defined four properties - before , beforeEach , after & afterEach - which each accept an array of functions. These properties will be used to reference the callbacks functions passed to their respective methods in the ChainableApi.

Finally, we define a tests property, which accepts an array of objects implementing the Test interface.

Test

The Test interface is quite similar to TestGroup , but will store references for a single test as defined by a call to it(). it() will accept two arguments - a description, and a callback function that runs the test expectations. As such, we have another description property of type string & an fn property of type Function.

We also have a result property, of type TestResult which will be used to store the results of the individual test after it's been run.

TestResult

The TestResult interface contains a passed property that accepts a boolean, which will indicate if the test passed or failed.

The remainder of the fields on TestResult are used to keep track of any errors thrown when running the test.

Part Three: src/describe.ts

In this file we define the test API of Pretzel Test. This, combined with the expectations API are what (hypothetical) users of our framework would use to author their tests. Here's the code:

// src/describe.ts

import { ChainableApi, TestGroup } from "./types";
import { testRunner } from "./runner";

const getInitialTestGroup = (description: string): TestGroup => {
  return {
    description,
    tests: [],
    before: [],
    beforeEach: [],
    after: [],
    afterEach: []
  };
};

function before(fn: Function): ChainableApi {
  this.currentTestGroup.before.push(fn);
  return this;
}

function after(fn: Function): ChainableApi {
  this.currentTestGroup.after.push(fn);
  return this;
}

function beforeEach(fn: Function): ChainableApi {
  this.currentTestGroup.beforeEach.push(fn);
  return this;
}

function afterEach(fn: Function): ChainableApi {
  this.currentTestGroup.afterEach.push(fn);
  return this;
}

function test(description: string, fn: Function): ChainableApi {
  this.currentTestGroup.tests.push({
    description,
    fn,
    result: {
      type: null,
      error: null,
      beforeError: null,
      beforeEachError: null,
      afterError: null,
      afterEachError: null
    }
  });
  return this;
}

function describe(description: string): ChainableApi {
  const currentTestGroup: TestGroup = getInitialTestGroup(description);
  testRunner.pushTestGroup(currentTestGroup);
  return {
    currentTestGroup,
    it: test,
    case: test,
    before,
    beforeEach,
    after,
    afterEach
  };
}

export { describe, test, before, beforeEach, after, afterEach };

I'll run through the above function by function:

describe()

The entry point to the API is the describe function, which accepts a description string as its single argument. First, the function builds a currentTestGroup object (Initially the currentTestGroup object will only store the description that has been passed to describe, with all other properties set to empty arrays).

Next up, we call testRunner.pushTestGroup and pass in the current test group object. testRunner is an instance of the TestRunner class, which we haven't yet defined, however its job will be to collect and run each TestGroup - so we pass it a reference to the test group that has been created as a result of the describe call.

Finally, the describe function returns an object that implements the ChainableApi interface. It contains references to the chainable methods (before, beforeEach, after, afterEach & it) along with the current test group via the currentTestGroup property.

before(), beforeEach(), after & afterEach ()

These functions all behave in the same way. First, they push the callback that's passed as an argument into their respective property on the currentTestGroup object, and then return this.

Because these methods will always be chained to a describe() call, the this keyword in each method will refer to the parent object that the methods were called on (in this case, the object returned from the initial describe block).

As such, these methods have access to the currentTestGroup object via this.currentTestGroup. By returning this at the end of each function, we allow an arbitrary number of these methods can be chained, and each will still be able to access currentTestGroup in the same way.

it()

The it method is pretty similar to the other chainable methods in behaviour, with a couple of notable differences.

Firstly, it accepts a description argument along with a callback function. Second, rather than only pushing a callback function, it builds and pushes an object implementing the the full Test interface to the currentTestGroup.

Part Four: src/expect.ts

This is file is where we create our expectation API. For now, we'll keep this very simple, and only implement matchers for .toEqual() and .notToEqual(), however this could be extended to provide more functionality. Take a look:

// src/expect.ts

import "colors";
import * as _ from "lodash";

const getToEqual = (value: any) => {
  return (expectedValue: any) => {
    if (!_.isEqual(value, expectedValue)) {
      throw new Error(`Expected ${expectedValue} to equal ${value}`.yellow);
    }
  };
};

const getNotToEqual = (value: any) => {
  return (expectedValue: any) => {
    if (_.isEqual(value, expectedValue)) {
      throw new Error(`Expected ${expectedValue} not to equal ${value}`.yellow);
    }
  };
};

export function expect(value: any) {
  return {
    toEqual: getToEqual(value),
    notToEqual: getNotToEqual(value)
  };
}

The expect() function accepts a value of any type, returning an object with our toEqual() and notToEqual() expectation functions. If the expectations fail, they throw a error (which is caught and recorded by the testRunner.

We're cheating a little here and using Lodash's isEqual() method to perform the actual equality comparison, as it provides a deep equality check that's a bit tricky to code manually.

Part Five: src/runner.ts

The TestRunner class has a few responsibilities:

It serves as the entry point to Pretzel Test. When we later implement the cli script to start the test run, it will do so with a call to testRunner.run().
It initiates an instance of the Reporter class (which will be responsible for logging the test results to the console.
It locates and imports test files matching the glob pattern passed through as options.
It collects the test groups from the imported files, then loops over them and invokes the actual test functions, recording the results.

Here's the code:

// src/runner.ts

import * as glob from "glob";
import { Reporter } from "./reporter";
import { TestGroup, Test, Options } from "./types";
import { EventEmitter } from "events";

export class TestRunner extends EventEmitter {
  static events = {
    testRunStarted: "TEST_RUN_STARTED",
    testRunCompleted: "TEST_RUN_COMPLETED",
    afterBlockError: "AFTER_BLOCK_ERROR",
    testGroupStarted: "TEST_GROUP_STARTED",
    testGroupCompleted: "TEST_GROUP_COMPLETED",
    singleTestCompleted: "SINGLE_TEST_COMPLETED"
  };

  suite: TestGroup[];

  constructor(Reporter) {
    super();
    new Reporter(this);
    this.suite = [];
  }

  pushTestGroup(testGroup: TestGroup) {
    this.suite.push(testGroup);
  }

  buildSuite(options: Options) {
    const testFilePaths = glob.sync(options.matching, {
      root: options.rootDir,
      absolute: true
    });
    testFilePaths.forEach(require);
  }

  async runBeforeEachBlocks(test: Test, testGroup: TestGroup) {
    try {
      for (const fn of testGroup.beforeEach) await fn();
    } catch (error) {
      test.result.beforeEachError = error;
    }
  }

  async runTestFn(test: Test) {
    try {
      await test.fn();
      test.result.passed = true;
    } catch (error) {
      test.result.passed = false;
      test.result.error = error;
    }
  }

  async runAfterEachBlocks(test: Test, testGroup: TestGroup) {
    try {
      for (const fn of testGroup.afterEach) await fn();
    } catch (error) {
      test.result.afterEachError = error;
    }
  }

  async runTests(testGroup: TestGroup) {
    for (const test of testGroup.tests) {
      await this.runBeforeEachBlocks(test, testGroup);
      await this.runTestFn(test);
      await this.runAfterEachBlocks(test, testGroup);
      this.emit(TestRunner.events.singleTestCompleted, test);
    }
  }

  async runBefore(testGroup: TestGroup) {
    try {
      for (const fn of testGroup.before) await fn();
    } catch (error) {
      testGroup.tests.forEach(test => {
        test.result.beforeError = error;
      });
    }
  }

  async runAfter(testGroup: TestGroup) {
    try {
      for (const fn of testGroup.after) await fn();
    } catch (error) {
      this.emit(TestRunner.events.afterBlockError, error);
      testGroup.tests.forEach(test => {
        test.result.beforeError = error;
      });
    }
  }

  async runTestGroup(testGroup: TestGroup) {
    this.emit(TestRunner.events.testGroupStarted, testGroup);
    await this.runBefore(testGroup);
    await this.runTests(testGroup);
    await this.runAfter(testGroup);
    this.emit(TestRunner.events.testGroupCompleted, testGroup);
  }

  async run(options: Options) {
    this.buildSuite(options);
    this.emit(TestRunner.events.testRunStarted);
    for (const testGroup of this.suite) await this.runTestGroup(testGroup);
    this.emit(TestRunner.events.testRunCompleted);
  }
}

export const testRunner = new TestRunner(Reporter);

I won't go through this file function by function (or you'll be here all day), however there is one thing I'd like to point out. You'll see that the TestRunner class extends Nodes inbuilt EventEmitter. This gives us access to emit() and on(), which you'll see being used above, and in reporter.ts. This is how the testRunner communicates with the reporter, and triggers the reporter to log output to the console.

Part Five: src/reporter.ts

As you've hopefully seen above, the Reporter class is imported and initialised by the testRunner, with the testRunner passing itself as an argument to the Reporter constructor. The Reporter constructor then initialises a set of event listeners on the testRunner (using the EventEmitter .on() function, which in turn trigger callbacks that console.log the various testRunner events (passing test, failing test, etc).

We're also using the colors npm package to make the console output a little more interesting.

Here's the code:

// src/reporter.ts

import "colors";
import { TestRunner } from "./runner";
import { Test, TestGroup } from "./types";

const indent: string = "  ";

export class Reporter {
  testRunner: TestRunner;

  constructor(testRunner) {
    this.testRunner = testRunner;
    this.initEventListeners();
  }

  printSummary = () => {
    let totalCount: number = 0;
    let passedCount: number = 0;
    let failedCount: number = 0;
    this.testRunner.suite.forEach(testGroup => {
      totalCount += testGroup.tests.length;
      testGroup.tests.forEach(test => {
        if (test.result.passed) passedCount += 1;
        else {
          console.log(`\n ○ ${testGroup.description}. ${test.description}`.red);
          console.log(`\n${test.result.error.stack}`);
          failedCount += 1;
        }
      });
    });
    console.log(`\n Total tests run: ${totalCount}`.yellow);
    console.log(` Passing tests: ${passedCount}`.green);
    console.log(` Failing tests: ${failedCount}\n`.red);
  };

  handleTestGroupStarted = (testGroup: TestGroup) => {
    console.log(`\n ${testGroup.description}`.grey);
  };

  handleTestGroupCompleted = () => {};

  handleTestRunStarted = () => {
    console.log("\n [Pretzel 🥨]: Starting test run...".yellow);
  };

  handleTestRunCompleted = () => {
    console.log("\n [Pretzel 🥨]: Test run completed.\n".yellow);
    console.log("\n Summary:".yellow);
    this.printSummary();
  };

  handleAfterBlockError = error => {
    console.log("There was an error in an after block...");
  };

  handleSingleTestCompleted = (test: Test) => {
    if (test.result.passed) {
      console.log(`   ○ ${test.description} ✓`.grey);
    } else {
      console.log(`   ○ ${test.description} ✖`.red);
    }
  };

  initEventListeners() {
    const {
      testRunStarted,
      testRunCompleted,
      afterBlockError,
      singleTestCompleted,
      testGroupStarted,
      testGroupCompleted
    } = TestRunner.events;
    this.testRunner.on(testRunStarted, this.handleTestRunStarted);
    this.testRunner.on(testRunCompleted, this.handleTestRunCompleted);
    this.testRunner.on(afterBlockError, this.handleAfterBlockError);
    this.testRunner.on(testGroupStarted, this.handleTestGroupStarted);
    this.testRunner.on(testGroupCompleted, this.handleTestGroupCompleted);
    this.testRunner.on(singleTestCompleted, this.handleSingleTestCompleted);
  }
}

Part Seven: bin/cli.js

The final piece of the pretzel! This script, when combined with a little config in package.json, will allow our test framework to be invoked from the command line by users who have installed our package.

In this script, we use the command-line-args npm package to collect some required configuration options from the user:

--rootDir sets the root tests directory
--matching accepts a glob pattern to match test files (ie. **/*.test.js

If these options aren't provided, then we through an error.

Then, we import the testRunner (importantly, this is being imported from dist/, not src/), and initiate the test run by calling testRunner.run(options) with the provided user options.

#!/usr/bin/env node

const commandLineArgs = require("command-line-args");

const optionDefinitions = [
  { name: "rootDir", alias: "r", type: String },
  { name: "matching", alias: "m", type: String }
];

const options = commandLineArgs(optionDefinitions);

if (!options.rootDir) throw new Error("rootDir is a required argument");
if (!options.matching) throw new Error("matching is a required argument");

const { testRunner } = require("../dist/runner.js");

testRunner.run(options);

To allow this script to be invoked from the command line, we need to register it. We also need to point the package.json to the entry point (dist/main.js)Add the following to package.json:

{
  "name": "pretzel-test",
  "main": "dist/main.js",
  ...
  "bin": {
    "pretzel-test": "./bin/cli.js"
  }
}

And thats it! We're done!

Almost...

In order to use this package to run some tests on your machine, you'll need to npm link it (since pretzel-test isn't actually available on npm). From your pretzel-test project root run npm link.

Then from the root of the package you want to run pretzel-test in, run npm link pretzel-test. You should now be able to require('pretzel-test') as normal from within this package.

Alternatively, you can clone the Pretzel Test Example Repo that I've created, which provides an example of using the framework and how to set it up. Take a look at the readme for further instructions.

If you found this post useful, you can follow me on dev.to or twitter. I've also got a couple of side projects that you might like to check out:

ippy.io - An app for creating beautiful resumes
many.tools - A collection of useful utilities for designers and devs