Forem: Matt Thorning

Using React Hooks with Class Components

Matt Thorning — Tue, 05 Nov 2019 23:00:00 +0000

Writing custom hooks is fun and they're a great way of creating reusable chunks of logic which can be easily used across multiple components. The only downside to them is that they only work with functional components. If you have a codebase which was written before hooks then either you opt to rewrite all of your components as functions (this might not make you very popular!) or you need to be able to make any hooks you write work with all of your components.

In this post I would like to share a couple of techniques which can be used to inject the data and methods from a hook into a class, they are known as "render props" and "higher order components".

Render Props

"Render props" is the name given to a technique where a function is passed as a prop to a component (typically called 'render', hence the name) which is called with some state that is then accessible to the components returned by the function. Here's a quick example to make things clearer than whatever that sentence meant:

function SayHello(props) {
  const helloTo = 'Code';
  return props.render(helloTo);
}

function Greet() {
  return (
    <SayHello render={helloTo => (
      <p>Hello {helloTo}</p>
    )} />
  );
}

The SayHello component has a function passed to it which returns a <p> tag with the innerHTML set to "Hello Code". Using the technique this way has always felt a bit strange to me though, and since you can use any prop you like (it doesn't have to be render), I usually opt to use the children prop which allows us to rewrite the above like this:

function Greet() {
  return (
    <SayHello> 
      {helloTo => (
        <p>Hello {helloTo}</p>
      )} 
    <SayHello />
  );
}

Now the SayHello component opens and closes around the other markup and I feel a little bit happier! It's entirely a matter of preference which method you choose though, no way is more right than the other.

Let's now make use of this technique to use the state from a hook in a class component. First I'll write the component as I would like to have used it; this won't work!

class ShowApiData extends React.Component {
  render() {
    // This doesn't work:
    const [data, error, loading] = useApiData('/api/results');

    if(loading) {
      return <Spinner />;
    }

    if(error) {
      return <ErrorPage error={error} />
    }

    return <Table data={data} />;
  }
}

Instead we need to create a new component which can use our hook and then use that in the ShowApiData component:

function ProvideApiData({ children }) {
    const [data, error, loading] = useApiData('/api/results');
    return children({ data, error, loading });
}

class ShowApiData extends React.Component {
  render() {
    return (
      <ProvideApiData>
        {({ data, error, loading }) => {
          if(loading) {
            return <Spinner />;
          }

          if(error) {
            return <ErrorPage error={error} />
          }

          return <Table data={data} />;
        }}
      </ProvideApiData>
    ); 
  }
}

This works in the same as way as our examples above. By including the new ProvideApiData component and passing a function which returns the logic we were first attempting to return from render, we can now provide the state that we want from the useApiData hook.

I like to leave the new component in situ above the original component for readability but if you need to use it in a lot of places then it probably makes more sense to keep it with the hook itself as a named export.

Higher Order Components

The main problem with the render props method is that everything needs to happen in the render method of your class. This can be a bit limiting if, say, you want something to happen when a button is pressed or in one of the lifecycle hooks. Higher Order Components are more flexible than render props, they are described as an advanced React technique but I think this makes them sound more confusing than they actually are.

A Higher Order Component (HOC for short) is a just a function which you call with a component as an argument. This function returns a new component which wraps the component you passed in; your original component is now the child of the new component. The new component can perform some functionality, hold some state or own some methods which can all be passed to the original component as props. Let's start with a simple one again before using it with a hook:

function withHello(Component) {
  return function() {
    const helloTo = 'Code';
    return <Component helloTo={helloTo} />;
  }
}

function Greet({ helloTo }) {
  return (
      <p>Hello {helloTo}</p>
  );
}

export default withHello(Greet);

This time I have included the export in the example because this is normally where I would wrap the component. The Greet component is passed to withHello which returns a new component with Greet as it's child and the helloTo variable passed down to it as a prop.

Let's use this with a hook. First we'll set up a component as a class so that it's clear what we're aiming for.

This is just a simple counter component. It displays a value and two buttons; one button increments the value and the other resets it. The Counter component has an initialCount prop so that it can be set to start at any number, when the reset button is pressed it should reset the value back to this number. If the initialCount prop is not set then it will default to zero.

class Counter extends React.Component {
  constructor(props) {
    super(props);
    this.initialCount = props.initialCount || 0;
    this.state = {
      count: this.initialCount
    }
  }

  increment() {
    this.setState({ count: this.state.count + 1 })
  }

  reset() {
    this.setState({ count: this.initialCount})
  }

  render() {
    const { count } = this.state;
    return (
      <>
        <button onClick={this.increment.bind(this)}>+1</button>
        <button onClick={this.reset.bind(this)}>Reset</button>
        <p>Count: {count}</p>
      </>
    );
  }
}

function App() {
  return (
    <Counter initialCount={3}/>
  );
}

It's worth noting how many lines of code we need to get this functionality working. There's the render method, we need to add a constructor because we want to set the initial state to a prop and then there are two other methods which are called on the click of the buttons which need to be bound to the context of the component.

Now we'll create a custom hook which can instead handle the logic for the component's state:

function useCount(initialCount = 0) {
  const [count, setCount] = React.useState(initialCount);
  const increment = () => setCount(count + 1);
  const reset = () => setCount(initialCount);
  return [count, increment, reset];
}

We've managed to condense the logic from the component into just four lines, this is what I really like about hooks, everything you need to know about the state logic for our component is in one place and it's completely reusable.

Just for the sake of completeness, this is how we could use the hook in a functional component:

function Counter({ initialCount }) {
  const [count, increment, reset] = useCount(initialCount);
  return (
      <>
        <button onClick={increment}>+1</button>
        <button onClick={reset}>Reset</button>
        <p>Count: {count}</p>
      </>
    );
  }

function App() {
  return (
    <Counter initialCount={3}/>
  );
}

Again, this is very concise and clean. Now the important bit. Let's use a HOC to allow us to use the useCount hook with our class. First we'll refactor the class so that it uses the hook's state instead of its own:

class Counter extends React.Component {
  render() {
    const { count, increment, reset } = this.props;
    return (
      <>
        <button onClick={increment}>+1</button>
        <button onClick={reset}>Reset</button>
        <p>Count: {count}</p>
      </>
    );
  }
}

This vastly simplifies the class, we no longer need to include the constructor method or worry about binding this to anything. The HOC itself only requires a few lines of code:

function withUseCount(Component) {
  return function({ initialCount }) {
    const [count, increment, reset] = useCount(initialCount);
    return <Component {...{ count, increment, reset }} />;
  };
}

This function is called with a Component (this will be the Counter component) and returns a new component that uses the hook. The new component takes the initialCount prop and calls the hook with it. The state from hook is then passed into the Counter component.

Lastly, all we need to do is to replace Counter with CounterWithHook and use it in exactly the same way as we did before:

const CounterWithHook = withUseCount(Counter);

function App() {
  return <CounterWithHook initialCount={3} />;
}

That's it, we are now able to use our custom hook with both functional and class components. Here's the code in one piece so that you can see how it fits together or copy it into an editor to try it out for yourself:

function useCount(initialCount = 0) {
  const [count, setCount] = React.useState(initialCount);
  const increment = () => setCount(count + 1);
  const reset = () => setCount(initialCount);
  return [count, increment, reset];
}

class Counter extends React.Component {
  render() {
    const { count, increment, reset } = this.props;
    return (
      <>
        <button onClick={increment}>+1</button>
        <button onClick={reset}>Reset</button>
        <p>Count: {count}</p>
      </>
    );
  }
}

function withUseCount(Component) {
  return function({ initialCount }) {
    const [count, increment, reset] = useCount(initialCount);
    return <Component {...{ count, increment, reset }} />;
  };
}

const CounterWithHook = withUseCount(Counter);

function App() {
  return <CounterWithHook initialCount={3} />;
}

ReactDOM.render(<App />, document.getElementById("root"));

I hope you've found this post helpful, thanks for reading. 😃

Please check out my other posts at hellocode.dev

Have you used React Object Components?

Matt Thorning — Wed, 14 Aug 2019 21:00:00 +0000

With the release of React Hooks I have seen a lot of posts comparing class components to functional components. Functional components are nothing new in React, however it was not possible before version 16.8.0 to create a stateful component with access to lifecycle hooks using only a function. Or was it?

Call me a pedant (many people already do!) but when we talk about class components we are technically talking about components created by functions. In this post I would like to use React to demonstrate what is actually happening when we write a class in JavaScript.

Classes vs Functions

First, I would like to very briefly show how, what are commonly referred to as functional and class components, relate to one another. Here's a simple component written as a class:

class Hello extends React.Component {
  render() {
    return <p>Hello!</p>
  }
}

And here it is written as a function:

function Hello() {
  return <p>Hello!</p>
}

Notice that the Functional component is just a render method. Because of this, these components were never able to hold their own state or perform any side effects at points during their lifecycle. Since React 16.8.0 it has been possible to create stateful functional components thanks to hooks, meaning that we can turn a component like this:

class Hello extends React.Component {

  state = {
    sayHello: false
  }

  componentDidMount = () => {
    fetch('greet')
      .then(response => response.json())
      .then(data => this.setState({ sayHello: data.sayHello });
  }

  render = () => {
    const { sayHello } = this.state;
    const { name } = this.props;

    return sayHello ? <p>{`Hello ${name}!`}</p> : null;
  }
}

Into a functional component like this:

function Hello({ name }) {

  const [sayHello, setSayHello] = useState(false);

  useEffect(() => {
    fetch('greet')
      .then(response => response.json())
      .then(data => setSayHello(data.sayHello));
  }, []);

  return sayHello ? <p>{`Hello ${name}!`}</p> : null;
}

The purpose of this article isn't to get into arguing that one is better than the other, there are hundreds of posts on that topic already! The reason for showing the two components above is so that we can be clear about what React actually does with them.

In the case of the class component, React creates an instance of the class using the new keyword:

const instance = new Component(props);

This instance is an object; when we say a component is a class, what we actually mean is that it is an object. This new object component can have its own state and methods, some of which can be lifecycle methods (render, componentDidMount, etc.) which React will call at the appropriate points during the app's lifetime.

With a functional component, React just calls it like an ordinary function (because it is an ordinary function!) and it returns either HTML or more React components. Methods with which to handle component state and trigger effects at points during the component's lifecycle now need to be imported if they are required. These work entirely based on the order in which they are called by each component which uses them, they do not know which component has called them; this is why you can only call hooks at the top level of the component and they can't be called conditionally.

The Constructor Function

JavaScript doesn't have classes. I know it looks like it has classes, we've just written two! But under the hood JavaScript is not a class-based language, it is prototype-based. Classes were added with the ECMAScript 2015 specification (also referred to as ES6) and are just a cleaner syntax for existing functionality.

Let's have a go at rewriting a React class component without using the class syntax. Here is the component which we are going to recreate:

class Counter extends React.Component {

  constructor(props) {
    super(props);
    this.state = {
      count: 0
    }
    this.handleClick = this.handleClick.bind(this);
  }

  handleClick() {
    const { count } = this.state;
    this.setState({ count: count + 1 });
  }

  render() {
    const { count } = this.state;
    return (
      <>
        <button onClick={this.handleClick}>+1</button>
        <p>{count}</p>
      </>
    );
  }

}

This renders a button which increments a counter when clicked, it's a classic! The first thing we need to create is the constructor function, this will perform the same actions that the constructor method in our class performs apart from the call to super because that's a class-only thing.

function Counter(props) {
  this.state = {
    count: 0
  }
  this.handleClick = this.handleClick.bind(this);
}

This is the function which React will call with the new keyword. When a function is called with new it is treated as a constructor function; a new object is created, the this variable is pointed to it and the function is executed with the new object being used wherever this is mentioned.

Next, we need to find a home for the render and handleClick methods and for that we need to talk about the prototype chain.

The Prototype Chain

JavaScript allows inheritance of properties and methods between objects through something known as the prototype chain. Well, I say inheritence, but I actually mean delegation. Unlike in other languages with classes, where properties are copied from a class to its instances, JavaScript objects have an internal protoype link which points to another object. When you call a method or attempt to access a property on an object, JavaScript first checks for the property on the object itself, if it can't find it there then it checks the object's prototype (the link to the other object), if it still can't find it then it checks the prototype's prototype and so on up the chain until it either finds it or runs out of prototypes to check.

Generally speaking, all objects in JavaScript have Object at the top of their prototype chain; this is how you have access to methods such as toString and hasOwnProperty on all objects. The chain ends when an object is reached with null as its prototype, this is normally at Object.

Let's try to make things clearer with an example.

const parentObject = { name: 'parent' };
const childObject = Object.create(parentObject, { name: { value: 'child' } });
console.log(childObject);

First we create parentObject. Because we've used the object literal syntax this object will be linked to Object. Next we use Object.create to create a new object using parentObject as its prototype.

Now, when we use console.log to print our childObject we should see:

The object has two properties, there is the name property which we just set and the __proto___ property. __proto__ isn't an actual property like name, it is an accessor property to the internal prototype of the object. We can expand these to see our prototype chain:

The first __proto___ contains the contents of parentObject which has its own __proto___ containing the contents of Object. These are all of the properties and methods that are available to childObject.

It can be quite confusing that the prototypes are found on a property called __proto__! It's important to realise that __proto__ is only a reference to the linked object. If you use Object.create like we have above, the linked object can be anything you choose, if you use the new keyword to call a constructor function then this linking happens automatically to the constructor function's prototype property.

Ok, back to our component. Since React calls our function with the new keyword, we now know that to make the methods available in our component's prototype chain we just need to add them to the prototype property of the constructor function, like this:

Counter.prototype.render = function() {
  const { count } = this.state;
  return (
    <>
      <button onClick={this.handleClick}>+1</button>
      <p>{count}</p>
    </>
  );
},

Counter.prototype.handleClick = function () {
  const { count } = this.state;
  this.setState({ count: count + 1 });
}

Static Methods

This seems like a good time to mention static methods. Sometimes you might want to create a function which performs some action that pertains to the instances you are creating but it doesn't really make sense for the function to be available on each object's this. When used with classes they are called Static Methods, I'm not sure if they have a name when not used with classes! We haven't used any static methods in our example but React does have a few static lifecycle methods and we did use one earlier with Object.create. It's easy to declare a static method on a class, you just need to prefix the method with the static keyword:

class Example {
  static staticMethod() {
    console.log('this is a static method');
  }
}

And it's equally easy to add one to a constructor function:

function Example() {}
Example.staticMethod = function() { 
  console.log('this is a static method');
}

In both cases you call the function like this:

Example.staticMethod()

Extending React.Component

Our component is almost ready, there are just two problems left to fix. The first problem is that React needs to be able to work out whether our function is a constructor function or just a regular function because it needs to know whether to call it with the new keyword or not. Dan Abramov wrote a great blog post about this, but to cut a long story short, React looks for a property on the component called isReactComponent. We could get around this by adding isReactComponent: {} to Counter.prototype (I know, you would expect it to be a boolean but isReactComponent's value is an empty object, you'll have to read his article if you want to know why!) but that would only be cheating the system and it wouldn't solve problem number two.

In the handleClick method we make a call to this.setState. This method is not on our component, it is "inherited" from React.Component along with isReactComponent. If you remember the prototype chain section from earlier, we want our component instance to first inherit the methods on Counter.prototype and then the methods from React.Component. This means that we want to link the properties on React.Component.prototype to Counter.prototype. __proto__. Fortunately there's a method on Object which can help us with this:

Object.setPrototypeOf(Counter.prototype, React.Component.prototype);

It Works!

That's everything we need to do to get this component working with React without using the class syntax. Here's the code for the component in one place if you would like to copy it and try it out for yourself:

function Counter(props) {
  this.state = {
    count: 0
  };
  this.handleClick = this.handleClick.bind(this);
}

Counter.prototype.render = function() {
  const { count } = this.state;
  return (
    <>
      <button onClick={this.handleClick}>+1</button>
      <p>{count}</p>
    </>
  );
}

Counter.prototype.handleClick = function() {
  const { count } = this.state;
  this.setState({ count: count + 1 });
}

Object.setPrototypeOf(Counter.prototype, React.Component.prototype);

As you can see, it's not as nice to look at as before! In addtion to making JavaScript more accessible to developers who are used to working with traditional class-based languages, the class syntax also makes the code a lot more readable. I'm not suggesting that you should start writing your React components in this way (in fact, I would actively discourage it!), I only thought it would be an interesting exercise which would provide some insight into how JavaScript inheritence works.

Although you don't need to understand this stuff to write React components, it certainly can't hurt and I expect there will be occassions when you are fixing a tricky bug where understanding how prototypal inheritence works will make all the difference. I hope you have found this article interesting and/or enjoyable, if you have any thoughts on the subject then please let me know. 😃

Ownership with Rust

Matt Thorning — Mon, 15 Jul 2019 21:00:00 +0000

I've recently started learning the Rust programming language, I'm still very much a novice but thought it would be beneficial to attempt to explain some of its features here.

Ownership is one of the key features of Rust. Unlike other languages, Rust does not free unused memory with the use of a garbage collector or require the programmer to manage it manually. Instead, Rust uses a system of ownership to manage its values with rules which the compiler checks at compile time, meaning that you get the best of both worlds as your program is not slowed down at runtime by a garbage collector and you are not required to manage the memory usage yourself.

The basic idea of ownership is a simple one; every value is owned by a variable, it can only be owned by one variable at a time and when the variable goes out of scope, the value is dropped from memory.

Stack or Heap?

First, it's probably a good idea to talk about the two types of values that Rust deals with. Some values have a fixed size which is known at compile time and which will not change throughout the life of the program, for example u32. These values can be be stored on the stack and can be passed around freely without needing to worry about ownership. The other type of value is dynamic, it has a size which is not known at compile time and which could change whilst the program is running, such as a String. This second type is stored on the heap and a pointer to its location in memory is stored on the stack instead. The data on the heap can change size but its pointer will always remain the same size.

Ownership exists because of these dynamic values. Other languages encounter problems when pointers are left in the stack which reference memory that has already been reallocated; Rust does not have this problem. When a variable owns a value on the heap, no other variable can own it. It is possible to create pointers which reference the variable that owns the value and ownership can be moved to a different variable. When the variable that owns the value goes out of scope, the value is removed from the heap so that the memory can be reallocated.

To illustrate this, please take a look at the two examples below, the first uses &str (size known at compile time) and the second String (size not known at compile time).

With &str

fn main() {
    let hello = "hello";
    println!("{} from the main function", hello);
    other(&hello);
    println!("{} again from the main function", hello);
}

fn other(greeting: &str) {
    println!("{} from the other function", greeting);
}

hello from the main function hello from the other function hello again from the main function

With String

fn main() {
    let hello = String::from("hello");
    println!("{} from the main function", hello);
    other(hello);
    println!("{} again from the main function", hello);
}

fn other(greeting: String) {
    println!("{} from the other function", greeting);
}

error[E0382]: borrow of moved value: hello --> src/main.rs:5:49 | 2 | let hello = String::from("hello"); | ----- move occurs because hello has type std::string::String, which does not implement the Copy trait 3 | println!("{} from the main function", hello); 4 | other(hello); | ----- value moved here 5 | println!("{} again from the main function", hello); | ^^^^^ value borrowed here after move

The compiler has told us that we've moved ownership of the value from the hello variable in the main function to the greeting variable in the other function and therefore it cannot be used again by the main function at line 5. The message also says "move occurs because hello has type std::string::String, which does not implement the Copy trait". I'll probably do a post about traits at some point so I won't go into them here but what the compiler is saying is that this is not a type that can be copied, hence why it has been moved. All types that can be stored on the stack can be copied, this is why the ownership rules do not apply to them; because their size is known, the performance cost of copying the values is not worth worrying about so that is what happens.

Cloning

This doesn't mean that we can't copy values on the heap though, cloning the value is one way we can make our code compile:

fn main() {
    let hello = String::from("hello");
    println!("{} from the main function", hello);
    other(hello.clone());
    println!("{} again from the main function", hello);
}

fn other(greeting: String) {
    println!("{} from the other function", greeting);
}

hello from the main function hello from the other function hello again from the main function

Can you spot the difference? Now, on line 4, we call the other function with a clone of the value held by the hello variable. Obviously this is not the most efficient way to write your program, and it can be risky if you don't know the size of the values which are going to be getting cloned. Also, if your functions mutate the value in some way then this is not a good solution:

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");

    one(hello_from.clone());
    two(hello_from.clone());

    println!("hello from {:?}", hello_from)
}

fn one(mut hello_from: Vec<&str>) {
    hello_from.push("one");
}

fn two(mut hello_from: Vec<&str>) {
    hello_from.push("two");
}

hello from ["main"]

Here, we're creating a Vector in which we want to collect the names of the functions which it has been passed to. Because we are using clone, each function is getting its own copy of the value which it is mutating, meaning that when we print the vector it only contains "main".

Moving

The first solution you might arrive at is to return the variable each time:

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");
    hello_from = one(hello_from);
    hello_from = two(hello_from);
    println!("hello from {:?}", hello_from)
}

fn one(mut hello_from: Vec<&str>) -> Vec<&str> {
    hello_from.push("one");
    hello_from
}

fn two(mut hello_from: Vec<&str>) -> Vec<&str> {
    hello_from.push("two");
    hello_from
}

hello from ["main", "one", "two"]

In this example we are moving the ownership of the value to a new variable in each function scope. This is perfectly valid but in my opinion it has its downsides. First, it requires more code to be written, the one and two functions both now need to declare a return type and we need to overload the hello_from variable in the main function each time the value is returned (lines 4 & 5). Secondly, I think it's easier to understand code when the owner of values stays in one scope; this is made possible with borrowing.

Borrowing

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");

    let hello_ref = &mut hello_from;
    one(hello_ref);
    two(hello_ref);

    println!("hello from {:?}", hello_from)
}

fn one(hello_from: &mut Vec<&str>) {
    hello_from.push("one");
}

fn two(hello_from: &mut Vec<&str>) {
    hello_from.push("two");
}

hello from ["main", "one", "two"]

Here we create a mutable reference to our variable and pass that to the functions instead. Because it is a mutable reference we can push the values and they will be added to vector as if we had passed the vector itself, however the ownership of the value never leaves the hello_from variable in the main function.

Some Caveats

As well as ensuring memory safety, Rust also protects us from race conditions with some rules around references. You can create as many immutable references as you wish, but you are not allowed to create more than one mutable reference at a time:

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");

    let hello_ref1 = &mut hello_from;
    let hello_ref2 = &mut hello_from;
    one(hello_ref1);
    two(hello_ref2);

    println!("hello from {:?}", hello_from)
}

fn one(hello_from: &mut Vec<&str>) {
    hello_from.push("one");
}

fn two(hello_from: &mut Vec<&str>) {
    hello_from.push("two");
}

error[E0499]: cannot borrow hello_from as mutable more than once at a time --> src/main.rs:6:26 | 5 | let hello_ref1 = &mut hello_from; | --------------- first mutable borrow occurs here 6 | let hello_ref2 = &mut hello_from; | ^^^^^^^^^^^^^^^ second mutable borrow occurs here 7 | one(hello_ref1); | -------------- first borrow later used here

You are also not allowed to create a mutable reference whilst there are already one or more immutable references:

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");

    let display_ref = &hello_from;
    let hello_ref = &mut hello_from;
    one(hello_ref);
    two(hello_ref);

    display(display_ref)
}

fn one(hello_from: &mut Vec<&str>) {
    hello_from.push("one");
}

fn two(hello_from: &mut Vec<&str>) {
    hello_from.push("two");
}

fn display(hello_from: &Vec<&str>) {
    println!("hello from {:?}", hello_from)
}

error[E0502]: cannot borrow hello_from as mutable because it is also borrowed as immutable --> src/main.rs:6:25 | 5 | let display_ref = &hello_from; | ----------- immutable borrow occurs here 6 | let hello_ref = &mut hello_from; | ^^^^^^^^^^^^^^^ mutable borrow occurs here ... 10 | display(display_ref) | --------------- immutable borrow later used here

But the compiler can tell when no further changes can be made via a mutable reference and allows you to start creating immutable references again!

fn main() {
    let mut hello_from = Vec::new();
    hello_from.push("main");

    let hello_ref = &mut hello_from;
    one(hello_ref);
    two(hello_ref);

    let display_ref = &hello_from;
    display(display_ref)
}

fn one(hello_from: &mut Vec<&str>) {
    hello_from.push("one");
}

fn two(hello_from: &mut Vec<&str>) {
    hello_from.push("two");
}

fn display(hello_from: &Vec<&str>) {
    println!("hello from {:?}", hello_from)
}

hello from ["main", "one", "two"]

So that's my first post on Rust, I hope it was useful (and correct!), all being well I intend to write a couple of these as I find that in doing so really helps to increase my own understanding and if they can help somebody else at the same time then that's even better. If you've got any comments then let me know on Twitter. 😃

Tools for big code changes

Matt Thorning — Mon, 10 Jun 2019 10:00:00 +0000

In my team at work we currently have five apps which have been written in React. These apps were all sharing components held in a single repository. As the number of apps and components is increasing, we decided it would be a better idea to separate our shared components into their own respositories. This has been a big task as, not only did our apps need to be updated to import the components from their new locations, but a lot of the components depend on other components meaning that every split led to more places where changes needed to be made.

There have been two tools which have helped me complete this task which I am going to introduce you to now (if you haven't used them already); Tmux and Codemod.

Codemod

Codemod is a command line tool written by Facebook. You give it a Regex pattern to search for and the code you want to replace it with and it will recursively search through your directories looking for every line that contains some text which matches your pattern. When it matches a line, it shows you a diff which you can either accept, decline or alter manually:

There are a load of options you can give it and you can do all sorts of clever stuff with Regex, such as capturing part of the pattern to use in the replacement; I only needed to do something very simple for this task though, here's an example using this blog's codebase:

codemod -d src --extensions js,jsx \
"components/blog" \
"blog-components/preview"

The first line tells Codemod to search recursively through all the directories in src with the -d switch. Then the extensions option tells Codemod to search only through js or jsx files. The second line is the pattern we are searching for which we wish to replace. You can use Regex here; I'm not very good with Regex so I use a system of trial and error using sites like this! One thing to keep in mind is that Codemod is written in Python so you want to ensure that you are using the Python 'flavour' of Regex. The final line is the text which we want to replace our matched string with.

Tmux

Tmux is a 'Terminal Multiplexer' which is a fancy way of saying that it lets you open many terminals. I could write quite a long blog post about Tmux (and I may yet do that), so I'm just going to quickly list the main reasons you may want to use it:

Tmux creates sessions which can be detached from and then reattached to at a later date. This is great if you are working on a remote server or having to switch contexts frequently. You can have an environment set up with different things running, detach from it when you need to and then reattach later with everything how you left it. You can also easily switch from one session to another.
Each session can have multiple windows and each window can be split into multiple panes.
It gives you superpowers when used with ZSH and Vim.

The reason I have included Tmux in this post though is because it allows you to synchronize panes. This means I can do things like open as many panes as there are apps in a single window and run commands in all of those panes at the same time.

So I can run npm install in all five apps, or commit and tag twelve component repos or, because I use Neovim as well, I can even do things like edit multiple package.json files in the time it would take me to edit one.

I shouldn't imagine there are many clients or companies which enjoy setting aside valuable time for refactoring tasks which result in no immediately visible benefit. Thanks to these tools, the task of moving our repos took a lot less time than it otherwise would have, meaning we can now get on with the important work of writing code! If you haven't heard of either of these tools then I hope this post has proved useful as an introduction. I've been using Tmux for a while now and have lovingly been crafting my config file for it which you can find on my Github page if you're interested.

Goodbye 👋

Updating state in React with hooks

Matt Thorning — Sun, 12 May 2019 10:00:00 +0000

Very often when writing an application in React you will need to update some state from a child component. With components written as ES6 classes, the usual method was to pass a function down to the children as a prop bound to the context of the parent. React's new useState hook has made things simpler; in fact, I haven't written a class since hooks were released so I no longer need to bind functions to the context of the parent component which holds the state. Passing the setState function returned by the useState hook down to the children is still error-prone though, there is a another way which I would like to show you now.

Prop drilling

Passing props down through several levels of components to where they are needed is known as prop drilling. Here's an example:

import React, { useState } from 'react'
import ReactDOM from 'react-dom'
import InputComponent from './InputComponent'

function App() {
  const [items, setItems] = useState([])

  return (
    <>
      <InputComponent title="Add an Item:" items={items} setItems={setItems} />
      <ul>
        {items.map(item => (
          <li>{item}</li>
        ))}
      </ul>
    </>
  )
}

const rootElement = document.getElementById('root')
ReactDOM.render(<App />, rootElement)

This is our top-level component. It renders an InputComponent and an unordered list of items. Before returning the elements to render, the useState function is called, this sets up an array of items (which are rendered in the ul element) and you can see that we're passing both items and setItems to the InputComponent along with another prop called title.

It should be pretty clear what this code is going to do even without looking at the InputComponent. The user is going to be able to input the name of an item and that item will be added to the list. Still, let's take a look at the InputComponent anyway!

import React from 'react'
import InputControls from './InputControls'

export default function InputComponent({ title, items, setItems }) {
  return (
    <>
      <h3>{title}</h3>
      <InputControls items={items} setItems={setItems} />
    </>
  )
}

This is a stupidly simple component, it just displays the title prop and then renders another component called InputControls. I wouldn't recommend writing components like this in reality, I just need several layers to illustrate my point! Here's the InputControls component:

import React, { useState } from 'react'

export default function InputControls({ items, setItems }) {
  const [userInput, setUserInput] = useState('')

  function onInputChange(e) {
    setUserInput(e.target.value)
  }

  function onButtonClick() {
    setItems([...items, userInput])
    setUserInput('')
  }

  return (
    <>
      <input value={userInput} onChange={onInputChange} />
      <button onClick={onButtonClick}>Add</button>
    </>
  )
}

So this is where the user input is accepted. There's an input box which updates the local state with whatever the user types. There is also a button which, when pressed, calls the setItems function which has been passed down from the top-level component. Because we want to add the new item to the array of items(instead of just replacing what was already stored there), and state is immutable, we also need to pass that down through the layers of components to be used in the new array.

This works so what's the problem? Well, if we refactor some of our components near the top of the tree and forget to pass props down we can inadvertently break other components further down without realising. There are obviously steps you can take to prevent this from happening or to alert you if it does (think regression tests or PropTypes) but it's better to remove the possibility of it happening altogether.

Passing props through

There are a couple of tricks I want to talk about in this post. The first is one that I use quite often where I have a component that wraps another and want it to use some of its props for itself and then pass the remainder to its child component.

export default function InputComponent(props) {
  const { title, ...rest } = props
  return (
    <>
      <h3>{title}</h3>
      <InputControls {...rest} />
    </>
  )
}

By using ES6 rest parameters we can take any props which we don't need and assign them to a single variable which can then be passed to the child component as props by using destructuring. Now our InputComponent doesn't need to know about all of the props, it just takes what it needs and passes everything else through. If we refactor InputControls so that it requires more props, we do not need to change anything in InputComponent to make it work, we can just add them in App.

This is an improvement but we still need to pass the items and setItems down to InputControls as props. We can, instead, use React's context API along with the useContext hook to give us access to our state from any point in the component tree.

Context and useContext

First we'll change the top-level component to look like this:

import React, { useState } from 'react'
import ReactDOM from 'react-dom'
import InputComponent from './InputComponent'

export const ItemsContext = React.createContext()

function App() {
  const [items, setItems] = useState([])

  return (
    <div>
      <ItemsContext.Provider value={[items, setItems]}>
        <InputComponent title="Add an Item:" />
      </ItemsContext.Provider>
      <ul>
        {items.map(item => (
          <li>{item}</li>
        ))}
      </ul>
    </div>
  )
}

const rootElement = document.getElementById('root')
ReactDOM.render(<App />, rootElement)

At line 5 we have added a call to React.createContext. This returns an object which contains two components, one is a Provider and the other is a Consumer. I'm exporting the variable, ItemsContext which contains both Provider and Consumer so that I can import it into any modules that need to access it, you may want to keep this in a separate file so that it's easier to find; I'm leaving it here for simplicity.

The Provider is used at line 12 (ItemsContext.Provider) and wraps the InputComponent. The provider can wrap as many components as you want it to and all components nested within will have access to the contents of the Provider's value prop.

You may also notice that we are now only passing the title prop to the InputComponent. Because of our change where we used rest earlier, there are no further changes required to the InputComponent, we can leave it as is and if we need to get any new props to the InputControls component at a later date, we can just pass them to InputComponent and they will fall through.

Let's go to the InputControls component to see how we can get our items and setItems out of the context provider:

import React, { useState, useContext } from 'react'
import ItemsContext from './App'

function InputControls() {
  const [items, setItems] = useContext(ItemsContext)
  const [userInput, setUserInput] = useState('')

  function onInputChange(e) {
    setUserInput(e.target.value)
  }

  function onButtonClick() {
    setItems([...items, userInput])
    setUserInput('')
  }

  return (
    <>
      <input value={userInput} onChange={onInputChange} />
      <button onClick={onButtonClick}>Add</button>
    </>
  )
}

At the top of the file we need to import both the useContext hook and our ItemsContext from App. On line 5 we call useContext and pass in the ItemsContext, note that we pass the whole object in, not just the Consumer. This returns our items and setItems function which we can use exactly as we did before. Notice also that this component no longer requires any props to function, we can move it to wherever we want in the application, and as long as the Provider component is above it in the component tree, it will continue to work.

Using these techniques can make your application more robust and less likely to break when you add, remove or move components around. It's not something which is ideal for every situation but they're certainly useful methods to have at your disposal. Thanks for reading, I hope it's been helpful. 😃

GraphQL server with MongoDB and Koa

Matt Thorning — Sun, 07 Apr 2019 21:00:00 +0000

One of the things I've enjoyed most about using Gatsby is learning to use GraphQL. I've just started creating an app which needs to save calendar events to a database so I thought it would be cool to see if I could create a GraphQL server instead of using REST endpoints like I normally would. It turns out that creating a GraphQL server capable of basic CRUD is a lot easier than I was expecting, here's how I did it.

What is GraphQL

First, it's probably worth writing a few sentences about what GraphQL is. GraphQL is a query language for APIs. The specification was created by Facebook but there are many different implementations of it for different languages. Unlike REST where you have multiple endpoints, GraphQL works with types and fields; you call one endpoint (usually '/graphql') and specify the type (more on this later) and fields you want to get back from the dataset. Because you tell the API which fields you require, GraphQL is a great way of preventing 'over-fetching' of data which can have negative consequences to users who are using mobile data or are in areas with poor internet speed.

The packages

I'm writing this in JavaScript because it's the only language I really know, I have dabbled with others but unless you use a language day in and day out, it's difficult to make it stick. Besides which, JavaScript is capable of doing so much that I haven't found a good enough reason other than curiosity to move to another language yet.

Ordinarily I write Node servers with Express, this time I thought it would be fun to try Koa. Koa is made by the creators of Express and uses ansync functions instead of callbacks, it's also pretty lightweight and doesn't come with any middleware so you can add only the stuff that you need (we'll be using koa-mount which sets up the routes and koa-graphql which lets us use GraphQL). If you want to use Express instead then the below code will still work, you'll just need to use the Express GraphQL middleware instead.

I'm also using Mongoose for the database layer which allows you to create models for your data which are persisted in MongoDB.

Getting started

The first thing you need to do is set up an empty project with npm init, then install the packages mentioned above as well as the main GraphQL package which is a collection of constructor functions which we use for creating our schemas and types:

npm install koa koa-mount koa-graphql graphql mongoose

You're also going to need to have MongoDB installed and running. You can either install this on your computer directly or do like I did and run it in a Docker container. I'm not going to go into how to do that here though, if you can't work it out then let me know and I'll lend a hand.

Server.js

The first file to write is the entrypoint, I've called it server.js, but you can call it whatever you like! Here's the file in full:

const koa = require('koa');
const graphqlHTTP = require('koa-graphql');
const mount = require('koa-mount');
const schema = require('./graphql/schema');
const mongoose = require('mongoose');
const root = require('./graphql/root');

mongoose.connect(`mongodb://localhost/calendar`, {
  useNewUrlParser: true
});

const db = mongoose.connection
db.on('error', console.error.bind(console, 'connection error:'));
db.once('open', () => console.log('Database connected.'));

const app = new koa();
app.listen(9000);

app.on('error', err => {
  console.log('Server error', err);
});

app.use(
  mount(
    '/graphql',
    graphqlHTTP({
      schema,
      rootValue: root,
      graphiql: true
    })
  )
);

At the top of the file we require in all of the packages we're going to use. On Line 8 we call mongoose.connect which opens a connection to our MongoDB (make sure it's running!) and connects to a database called calendar. If the named database doesn't exist then Mongoose will create one for you automatically. Passing the option { useNewUrlParser: true } prevents you from receiving a "DeprecationWarning" message in your console.

Next, we listen for Mongoose to let us know whether the connection was successful or not; I just log the message out in either case. You can move the lines of code which initialise the database connection into a separate file to make things cleaner if you wish, I'm just going to leave them here for the purposes of this article.

On line 16 we create a new Koa app and tell it to listen on port 9000, followed by some error handling which just logs the error message again.

Finally on line 23 we add the middleware. We use koa-mount to create the route /graphql; any requests to this URL are passed to the koa-graphql middleware. The GraphQL middleware takes a schema and a rootValue, which we will write later, and we're also telling it to use graphiql (pronounced 'graphical').

Graphiql is a great tool which lets you run queries against your server whilst you are developing it and also when you are developing the frontend which uses it. Graphiql also creates documentation for you automatically, showing anyone who is using your API which types and fields are available and what each one is capable of.

The Mongoose model

Mongoose uses models which are built from schemas. We're only going to be needing one model for what we're doing but it's good practice to keep them in their own folder in case you need to add more. Here's the directory structure so far:

src
 ├── models
 │   └── event.js
 └── server.js

The new file is called event.js, here it is:

const mongoose = require('mongoose');

const EventSchema = new mongoose.Schema({
  title: String,
  start: Date,
  end: Date,
  allDay: Boolean
});

module.exports = mongoose.model('Event', EventSchema);

This should be pretty self-explanatory. First we create a schema where we declare the fields each model will have and the data types which they will hold. Mongoose then creates a model from this schema, which we export. The one thing I should explain is what the first argument to mongoose.model ( line 10 ) is for. 'Event' is the singular name of the collection that Mongoose will look for in the database. It will pluralise and lowercase it, so in this case Mongoose will look for a collection called 'events', if there is no collection of that name then it will create one for us.

Querying

GraphQL is capable of handling queries and mutations. Queries are used to get data from the API, mutations are used to add, edit or delete data. Let's start by adding a query type with a field that will return an array of all of the records in the events collection.

First we need to create a schema. This is the file that is passed to the GraphQL middleware on line 27 of server.js. I'm going to put this file in its own graphql folder:

src
  ├── graphql
  │   └── schema.js
  ├── models
  │   └── event.js
  └── server.js

const { buildSchema } = require('graphql');

module.exports = buildSchema(`
  type Event {
    id: ID,
    title: String
    allDay: Boolean
    start: String,
    end: String
  }
  type Query {
    listEvents: [Event]
  }
`);

The buildSchema function is called with a string that contains a schema written in GraphQL's own schema language. As I mentioned earlier, GraphQL is organised around types; there is a root Query type and a root Mutation type. Each of these contains fields of more types, which contain fields of more types, and so on, spreading out like the branches of a tree until a scalar type (Int, Boolean, String) is reached. The scalar types are known as the leaves because trees init.

The first type we declare in our schema is the Event type, this is the output type which will be used by our queries and mutations. Inside, we declare all of the fields that can be returned and the type of data contained in each field. Remember, it's possible to include other custom GraphQL types as well as the scalar types we've used here.

Next, on line 11, we declare our root Query type. We'll add one query, listEvents which will return an array of Event types.

Now we need to add the resolver function which will get the data from our MongoDB. I'll add another file to the graphql folder called root.js; this is the other missing file from server.js which is added to the GraphQL middleware on line 28:

src
  ├── graphql
  │   ├── root.js
  │   └── schema.js
  ├── models
  │   └── event.js
  └── server.js

const Event = require('../models/event');

module.exports = {
  listEvents() {
    return Event.find();
  },
}

So that's all we need to do to get our data! I've imported the Mongoose Event model, when a listEvents query is made we just need to call .find without any arguments to get all of the records in the collection. Let's try it out...

Head to your browser and go to 'localhost:9000/graphql' (the port and URL we set in server.js), you should see the Graphiql interface.

First I want to show you where the docs are. If you click on the link in the top-right of the screen call Docs and then on Query, you should be able to find the query we have just created. Click through until you find the fields which we listed in our Event type in the schema. This seems obvious but it took me longer than I'd like to admit to realise the docs were there!

Now that you've seen how the docs works we can query our API. Copy the following into the left-hand pane:

{
  listEvents {
    id
    title
    allDay
    start
    end
  }
}

If everything's working correctly you should see the following:

The response is in the right hand pane. At the moment the array is empty because we haven't added anything yet, so let's write a mutation so that we can add some data.

Create an Event

First we need to add the root mutation type to our schema.js and add the create field.

const { buildSchema } = require('graphql');

module.exports = buildSchema(`
  type Event {
    id: ID,
    title: String
    allDay: Boolean
    start: String,
    end: String
  }
  type Query {
    listEvents: [Event]
  }
  type Mutation {
    createEvent(title: String!, start: String, end: String, allDay: Boolean): Event
  }
`);

The new code has been added at line 14. If you look at the docs section in Graphiql again you should be able to see the new root type, Mutation, under the root Query type. If you click on it you should see that it contains the new create field.

The create field accepts the arguments which are declared in the parentheses (along with their types) and we have declared the return type after the colon; Event, which is our output type from line 4.

Now, let's add the resolver function to our root.js file:

const Event = require('../models/event');

module.exports = {
  listEvents() {
    return Event.find();
  },
  createEvent(input) {
    const newEvent = new Event(input);
    return newEvent.save();
  },
}

Our create function creates a new Event with the input which is sent in the request. Calling save() on a Mongoose model adds it to the collection in the database.

Let's add an Event! Copy this into the left-hand pane of Graphiql:

mutation {
  createEvent(title: "New event", start: "2019-01-01T12:00:00", end: "2019-01-01T14:00:00") {
    id
    title
    allDay
    start
    end
  }
}

A couple of things to mention here. After calling create with the values we want to set, we are listing the fields which we want the server to respond with from the newly created record. Because we set our return type in the schema to Event and returned the newly created Event from our resolver function, GraphQL expects us to follow our mutation with the fields we want it to respond with; if we don't then we will get an error.

You also may have noticed that we have started our request with the word mutation. When we made our query earlier, we did not need to label it because GraphQL assumes you are making a query unless you say otherwise. If you wish to make a query and a mutation in the same request then you need to label them both or else you will receive an error:

Hopefully you won't get an error though! You should get something like this:

You can see that the server has responded with the fields we requested from our newly created event. The ID was created for us by MongoDB, this is really useful because we can now use this ID to select the events that we want to update and delete.

Update & delete Events

By now you should be able to see how easy this is, I'm just going to add the update and delete methods in one hit so that we can demonstrate full CRUD. The schema needs to be updated so that it looks like this:

const { buildSchema } = require('graphql');

module.exports = buildSchema(`
  type Event {
    id: ID,
    title: String
    allDay: Boolean
    start: String,
    end: String
  }
  type Query {
    listEvents: [Event]
  }
  type Mutation {
    createEvent(title: String!, start: String, end: String, allDay: Boolean): Event
    updateEvent(id: String!, title: String, start: String, end: String, allDay: Boolean): Event
    deleteEvent(id: String!): String
  }
`);

Our two extra mutations have been added, notice that both mutations need the id of the event (the exclamation mark in the type declaration means that it cannot be null) also, the delete field returns a String.

Here's the root.js file:

const Event = require('../models/event');

module.exports = {
  listEvents() {
    return Event.find();
  },
  createEvent(input) {
    const newEvent = new Event(input);
    return newEvent.save();
  },
  updateEvent(input) {
    const { id, ...rest } = input;
    return Event.findByIdAndUpdate(id, { $set: rest }, { new: true }).catch(
      err => console.error(err)
    );
  },
  deleteEvent({ id }) {
    return Event.findByIdAndDelete(id)
      .then(event => event.remove())
      .then(() => `${id} successfully deleted`)
      .catch(err => console.error(err));
  }
};

The update resolver ( line 11 ) uses destructuring to separate the id from the fields we want to change. We then use findByIdAndUpdate to find the correct record and update it with the new data ({ $set: rest }). Passing the option { new: true } makes MongoDB return the updated record instead of the record as it was before being updated. We're also catching any errors and logging them out.

The delete resolver only needs the id so it destructures it straight away and uses findByIdAndDelete to find the record and delete it. Remember from the schema that this method returns a String? Because we have deleted the record, there is little point in returning it, instead we are responding with a confirmation message on line 20.

Let's try updating our record:

As you can see in the response, the title of our record has been correctly updated. Now let's delete it:

There's our confirmation message, great success! 👍

We've got full CRUD and hardly had to write any code! Obviously, there are still other considerations to be made before this could be considered production-ready such as security, validation and error-handling but I was pretty impressed at how easy it was to make a functioning backend using these technologies. I have one other tip as a reward for making it to the end. Graphiql is a great tool but it has its limitations. Instead, I've been using an open source application called insomnia to make my API calls; you can set up your different requests and organise them in folders which is pretty handy, check it out!

CSS in JS (part 2)

Matt Thorning — Sun, 03 Mar 2019 10:00:00 +0000

In my last blog post I wrote about how I had started using Emotion instead of Sass. Initially I was using Emotion's framework-agnostic package, but I have now switched to using the version which they created specifically for use with React because it adds some extra functionality which I liked the look of! This post is going to be about using Emotion with React, because of that, I'm going to be making the assumption that if you're reading this then you already know how to use React.

Let's get started, you can install the package with NPM:

npm install @emotion/core --save-dev

Then you will need to make some changes to your Babel setting to enable your project to work with this package.

Babel

There are two methods available for making your app work with @emotion/core. The quickest way is to import Emotion's jsx function at the top of your file and include a JSX Pragma on the line above it like so:

/** @jsx jsx */
import { jsx } from '@emotion/core'

The pragma (which is the bit in comments) tells Babel to use Emotion's jsx function in place of React's createElement. With these lines in your imports you will be able to use the css prop anywhere in your file that you may have previously used className. This is a good solution if you just want to try it out or if you don't have access to your Babel settings, it is a bit of a pain having to do this in every file though so if possible I recommend using the second method which is to add the Babel preset. This is easy to do, just install it with NPM and then include it in your .babelrc or babel.config.js:

{
  "presets": ["@emotion/babel-preset-css-prop"]
}

If you're using Gatsby (as I am for this site) there is a plugin you can use instead.

Once you've set up the Babel preset you no longer need to include the pragma or import the jsx function at the top of your files, every component in you codebase will now be able to use the css prop.

The css prop

The css prop accepts your styles in several ways which gives you some added flexibility when writing your components.

It will accept object styles:

const styles = {
  color: 'red',
  marginTop: '10px'
}

export default function HelloCode(props) {
  return <h1 css={styles}>Hello Code</h1>
}

It will also accept string styles which have been created with @emotion/core's css function:

import { css } from '@emotion/core'

const styles = css`
  color: red;
  margin-top: 10px;
`
export default function HelloCode(props) {
  return <h1 css={styles}>Hello Code</h1>
}

Unlike with the css function in the framework-agnostic version, this css function does not return a computed class name string; it returns an object which Emotion understands 'at a low level' and as such can be composed with other Emotion based styles. Therefore, it is important that you don't try to use the css function which is exported by the framework-agnostic version of Emotion.

You can also pass an array of styles to the css prop. The styles are applied left-to-right with any duplicated rules being overridden:

import { css } from '@emotion/core'

const blue = css`
  color: blue;
  margin-top: 10px;
`
const red = css`
  color: red;
`
export default function HelloCode(props) {
  return <h1 css={[blue, red]}>Hello Code</h1>
}
//Text will be red

This is great for controlling your styling through the logic of your component using its state or props. In the example below I have used a reducer with React's useReducer and useEffect hooks to add a class to the component five seconds after the component mounts:

import React, { useEffect, useReducer } from 'react'
import { baseStyle, animationStyle } from './style'

export default function HelloCode() {

  const reducer = (state, action) => {
    switch (action.type) {
      case 'addClass':
        return {
          style: [...state.style, action.payload],
        }
      default:
        return state
    }
  }

  const initialState = {
    style: [baseStyle]
  }

  const [state, dispatch] = useReducer(reducer, initialState)

  function animate() {
    setTimeout(() => {
      dispatch({
        type: 'addClass',
        payload: animationStyle,
      })
    }, 5000)
  }

  useEffect(() => {
    animate()
  }, [])

  return <h1 css={state.style}>Hello Code</h1>
}

So you can see that useEffect calls the animate function on component mount. This function uses setTimeout to dispatch the addClass action after a 5000 milliseconds delay. The payload of the action contains the reference to the animationStyle which is imported at the top of the file. The reducer matches the action type with addClass and updates the component's state with a new array containing both state.style and animationStyle from action.payload.

The Global component

I generally believe it's a good idea to keep your CSS styles scoped to your components. When writing React applications you build up from the smallest level of granularity; creating one large stylesheet which controls styling for the entire app flies in the face of this methodolgy (in my opinion). However, it's still important to maintain consistency in the way the UI looks across your application. There are two options available to help with this, here is the first.

@emotion/core provides a Global component which can be utilised to apply CSS rules globally to your site. It's used like this:

import { Global, css } from '@emotion/core'

export default function HelloCode() {
  return (
    <div>
      <Global
        styles={css`
          h1 {
            color: red;
          }
        `}
      />
      <h1>Hello Code</h1>
    </div>
  )
}

This is interesting because you can completely change the styling of your site just by rendering a Global component. One of React's strengths is that it makes conditionally rendering child components effortless, using the Global component as a child you could very easily change the entire look of your site with the push of a button:

import React, { useState } from 'react'
import { Global, css } from '@emotion/core'

const nightModeStyle = css`
  body {
    background: black;
  }
  h1 {
    color: white;
  }
`
export default function HelloCode() {
  const [nightMode, setNightMode] = useState(false)

  return (
    <div>
      {nightMode && <Global styles={nightModeStyle} />}
      <button onClick={() => setNightMode(!nightMode)}>Night Mode</button>
      <h1>Hello Code</h1>
    </div>
  )
}

Slight disclaimer with this one, I haven't tried it (yet); if you happen to try it and it doesn't work then let me know!

Theming

With theming you can create an object containing settings that you want to have access to in the css prop of any component. This is great for maintaining a consistent look and makes changing colours for branding a lot easier because you only need to change the values in one place instead of in every component.

If you want to use theming with Emotion then you wil first need to install it with NPM:

npm install emotion-theming --save-dev

emotion-theming uses React's context API, so first you need to wrap all of the components which you want to have access to the theme in the ThemeProvider. This is standard context stuff, only instead of a value prop it uses theme:

import { render } from 'react-dom'
import App from './app'
import { ThemeProvider } from 'emotion-theming'

const theme = {
  primaryTextColor: 'red'
  h1TopMargin: '10px'
}

render(
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>,
  document.getElementById('root')
)

Now, let's take an example from earlier on but this time we'll get the values from the theme:

import { css } from '@emotion/core'

const styles = theme => css`
  color: ${theme.primaryTextColor};
  margin-top: ${theme.h1TopMargin};
`
export default function HelloCode(props) {
  return <h1 css={styles}>Hello Code</h1>
}

The css prop also accepts a function which is called with the theme as an argument. When React sees this it walks back up the components tree until it finds a ThemeProvider and gets the theme object from its prop. Because this is a JavaScript object it can be passed around as you would any other object. Here's another example from earlier:

import { css } from '@emotion/core'

const blue = theme => css`
  color: blue;
  margin-top: ${theme.h1TopMargin};
`
const red = theme => css`
  color: ${theme.primaryTextColor};
`
export default function HelloCode(props) {
  return (
    <h1 css={theme => (
      [blue, red].map(style => style(theme))
    )}>
      Hello Code
    </h1>
  )
}
//Text will be red

Here we are passing the theme object to each function in the array using map. I'm sure you can see how powerful this can be; any css prop can very easily be turned into a function with access to everything in your theme object just by prepending it with theme =>!

That's covered everything I've been doing with Emotion lately. There's more in their documentation which I haven't covered but I've talked about the stuff which I've found the most useful. Still, take a look and if you see or know of anything that I've not mentioned which you think is useful then please let me know. Cheers! 👍

CSS in JS

Matt Thorning — Wed, 20 Feb 2019 20:10:00 +0000

I've looked at CSS in JS libraries before but there always seemed be trade-offs which have made them appear less attractive than Sass or even plain CSS. However, I have recently been playing around with Emotion and I'm pretty impressed so I thought I would write a quick post showing some examples of what it can do.

I've been using Emotion with React, there is a React-specific package (@emotion/core) which provides some additional features but I have just been using their framework-agnostic version. There are several different ways that you can use Emotion, the examples below use the method that works best for me, check out their documentation if you're interested in what else it can do.

Basic usage

Emotion uses tagged templates to create a CSS class which is then applied to the element. Here is the basic pattern for applying styles to a React component:

import React from 'react'
import { css } from 'emotion'

export default function TestComponent(props) {
  return (
    <div
      className={css`
        background: blue;
        border: 1px solid red;
        max-width: 300px;
      `}
    >
      Hello
    </div>
  )
}

Notice that the string passed to the tagged template is actual CSS, there are no camel-cased keys, the values do not need to be wrapped in single quotes and the lines are terminated with semi-colons. At first I was disappointed because the syntax highlighting in VS Code was messed up but I added the Babel Javascript extension which formats the CSS as if it were in a .css file so now it looks nice. 👍

If you look at the markup you can see that Emotion assigns a class to the elements with a random string appended to it.

This scopes your CSS to the element it is applied to so it won't leak to other components, making your styling component-based as opposed to document-based which fits better with the way that React apps are written. If you want to set global styles then Emotion has a Global component you can use, and there is nothing stopping you from using a global stylesheet in addition to your component-level styles.

I started off by writing my styles straight into the JSX but things began to look messy. Fortunately it's really easy to extract the rules and move them above the JSX or even into their own file:

import React from 'react'
import { css } from 'emotion'

export default function TestComponent(props) {
  const styling = css`
    background: blue;
    border: 1px solid red;
    max-width: 300px;
  `
  return (
    <div
      className={styling}
    >
      Hello
    </div>
  )
}

Just like CSS

It's possible to do nested components, pseudo-classes and media queries:

const styling = css`
  background: blue;
  border: 1px solid red;
  max-width: 300px;

  a {
    color: black;
  }
  &:hover {
    background: pink;
  }
  @media (max-width: 400px) {
    font-size: 12px;
  }
`

If you check the Emotion documentation there are some pretty clever things you can do with media queries if you have a lot of breakpoints to cater for, I won't go into it here but take a look if you're interested.

Just like JS

Because these are just strings you can do interpolation:

const baseStyle = css`
  width: 300px;
  border: 1px solid black;
`
const green = css`
  ${baseStyle}
  background: green;
  `
const blue = css`
  ${baseStyle}
  background: blue;
`
const red = css`
  ${baseStyle}
  background: red;
`
return (
  <>
    <div className={green}>Green</div>
    <div className={blue}>Blue</div>
    <div className={red}>Red</div>
  </>
)

You could take this further and use functions:

const baseStyle = css`
  width: 300px;
  border: 1px solid black;
`
function styles(color) {
  return css`
    ${baseStyle}
    background: ${color};
  `
}

return (
  <>
    <div className={styles('green')}>Green</div>
    <div className={styles('blue')}>Blue</div>
    <div className={styles('red')}>Red</div>
  </>
)

And it's not just values, any part of the string can be interpolated:

const smallScreen = '@media (max-width: 400px)'

const style = css`
  ${smallScreen} {
    font-size: 12px;
  }
`

This is great for allowing you to set up a file of constants which can be imported into all of your modules for consistency or theming.

It's also worth remembering that the css function (tagged template) returns a class so you can dynamically add styles as you would with classes:

const baseStyle = css`
  color: ${textColor};
`

function TagBlock(tagName) {
  const highlighted = tagSelected && css`
    color: ${highlightColor};
  `
  return (
    <span className={css`
      ${baseStyle}
      ${highlighted}
    `}>
      {tagName}
    </span>
  )
}

In this example the component will change the colour of the text to highlightColor when tagSelected is true.

I've only been using Emotion for a very brief time and have only scratched the surface of what it can do. Transitioning to it has been extremely easy because it offers all of the functionality of CSS but with the flexibility of JavaScript. The compositional way in which Emotion allows you to build your CSS compliments React nicely, particularly now that hooks are live. This is particularly noticeable when you reach a point where you want to extract some logic into its own component; simply cut and paste the JSX, hooks and styling out of your component and paste them into a new file.

This has just been a quick look at Emotion, I haven't tried other CSS-in-JS libraries, but I was impressed enough by my experience with it that I wanted to put together this quick post. Hopefully it's been helpful to someone!

IP addresses

Matt Thorning — Sun, 17 Feb 2019 08:00:00 +0000

As a web developer it is presumably beneficial to have a basic understanding of how the internet works! This isn't something I've known a great deal about, I've always just taken it for granted so I've decided to write some posts to further my own understanding; I thought IP addresses would be a good place to start. As always you can reach me on Twitter if you see any innacuracies or think that I have missed anything which should be included.

Every device which is connected to the internet needs an IP address. IP stands for Internet Protocol which is the set of rules that devices need to adhere to if they are going to be able to communicate with one another over the internet. When you visit a website with your web browser you are actually navigating to an IP address; fortunately for us there is a system in place which means that we don't have to remember the IP addresses of all of the websites we visit.

The Domain Name System

When you type a web address into a browser it is first translated into an IP address by the Domain Name System (DNS) which is a decentralised network of nameservers. There are four steps to a DNS query, they are:

DNS Recursors - The "Recursive Resolver" acts as a middleman between the client (web browser) and Domain Name System. It holds a cache of previously resolved queries; if the requested domain name is in the cache then the IP address can be resolved straight away, if it is not in its cache then it requests data from the following three nameservers, starting with the Root Nameserver.
Root Nameserver - The Root Nameserver will point the resolver to a relevant Top Level Domain (TLD) nameserver which maintains information on the requested domain extension (this is the .com, .co.uk, .org part of the URL).
TLD Nameserver - The TLD Nameserver holds the location of all of the authoritative nameservers which have information on websites in their top-level domain, ie. .com.
Authoritative Nameserver - Finally the resolver has the location of the Authoritative Nameserver and can request the IP address of the web address typed into the browser.

So you can see that DNS works by systematically narrowing down its search like searching for a tin of paint in an industrial estate; first you find B&Q, then you find the paint aisle, then you find the tin of paint on the shelves.

It is possible to interrogate a DNS nameserver using the Linux utility dig which will tell us the IP address of the domain and also the authoritative nameservers which provided the IP address.

Understanding the address

The most commonly used version of IP address is IPv4. This uses 32 bit addresses (4 bytes) which limits the total number of IP addresses to 2³² (approximately 4.3 billion) addresses. This seems like a lot of IP addresses but when you consider the current global population is about 7.7 billion you realise it is probably not going to be enough! Fortunately, not all devices need to be directly connected to the internet as will be explained in a minute and there is a new version of Internet Protocol (IPv6) which is 128 bits resulting in 2¹²⁸ or 340 undecillion (340 billion billion billion billion!) addresses.

IPv4 addresses are written using dotted decimal notation. There are 4 sections separated by a dot, each section is 1 byte (8 bits). In decimal, the maximum number you can reach is 255 which is 11111111 in binary.

IPv6 addresses still use dot notation but instead of decimal numbers they use hexadecimal, and instead of 8 bits per section they use 16. For comparison this means that the decimal equivalent maximum number for each dot-separated section is 65535 versus IPv4's 255. In addition to this, IPv6 uses 8 of these dot-separated sections instead IPv4's meager 4! Here's an example of an IPv6 address:

2001:0db8:0000:0000:0000:ff00:0042:8329

For convenience one or more leading zeros from a section may be removed and consecutive sections of zeros replaced with a double colon (only once per address) making our above example look like this:

2001:db8::ff00:42:8329

Not exactly memorable, I'm glad we've got DNS!

The aim of IPv6 is that every device will be able to be assigned its own unique address without any risk of exhausting the pool of addresses like is happening with IPv4.

How are we still using IPv4?

The IPv4 address exhaustion issue should have meant we ran out of IPv4 addresses a long time ago. In fact it has been anticipated since the 1980's! One of the main reasons we are still able to use IPv4 is because of private IP addresses. Like me, you probably have a lot of devices in your home which are connected to a wireless router. This is your access point to the internet and is therefore the only device in your home which needs a public IP. When a device is connected to a router, Dynamic Host Configuration Protocol (DHCP) assigns it a private IP address. These addresses are only unique within your Local Area Network (LAN) and will probably look like either 192.168.xxx.xxx or 10.xxx.xxx.xxx. When one of your devices makes a request the router replaces the private IP in the header with the public IP and records the sending device's details in a table. When the packet returns, the router looks up the saved reference in the table and forwards the packet on to the correct private IP address. The protocol which handles this is called Network Address Translation (NAT).

Ports

Another important subject related to IP adresses that I think we should touch upon is ports. Ports allow our devices to listen for many different services on the same IP address. A good way to think about how IP addresses, ports and NAT interact is with the following analogy.

I work in a building which rents offices to many different businesses. When I order a new gadget from Amazon, the postman delivers it to the reception of our building. The receptionist puts my parcel in a box with all the other parcels for my company which are then picked up by a colleague of mine who works for our company. My colleague knows which desk I work at and kindly delivers my parcel to me.

The address on my parcel contains the street address of the building I work in and the name of the company I work for. In this analogy the street address is the IP address and the company name is the port number. Notice there is nothing on the parcel to indicate which desk I work at, that information is held internally, by the kind person who brings my parcel to my desk (NAT).

There are many common port numbers (80 is HTTP, 22 is SSH, 20 is FTP, 25 is SMTP) but they can also be assigned as needed. To access a specific port you append a colon to the URL followed by the port number. If a port number is not supplied then it will default to port 80 (HTTP). When we write google.co.uk we really mean 216.58.198.227:80

That's all I want to cover for this post. There's more we could talk about such as subnets, classes, MAC addresses and ARP but I'd prefer to keep this post brief so maybe I will do a part 2 at a later date. I hope you've found this post useful, feel free to get in touch with any comments / questions, see you next time. 😃

Promises, promises

Matt Thorning — Tue, 05 Feb 2019 21:30:00 +0000

Unlike a lot of other languages, JavaScript is single-threaded which means it can only process one command at a time. We often need to get data from other sources, be it from a database, server or the user and I'm sure you can imagine how bad our applications would be if we had to pause the execution of our program each time we were waiting. Promises solve this problem for us, we request some data from wherever we're getting it from and we set the actions which we want to run once the data is returned. This leaves our single-thread free to carry on with other tasks in the meantime.

Until quite recently it was necessary to use a third-party library for promises (jQuery's Deferred was the most popular) but since ES6 they have been native to JS. Here's the basic pattern:

const promise = new Promise(resolve =>
  setTimeout(() => resolve('I waited for 2 seconds'), 2000)
)

promise.then(message => console.log(message))
// I waited for 2 seconds

First we create a new promise object from the Promise constructor. This takes a function as an argument which is called with a function to execute when you want the promise to be resolved. I have just used a setTimeout in this example to keep things simple but you would normally make calls to an API or query a database (in Node) here. After that we can use Promise's then method to execute something when the promise is resolved.

Error handling

So that's how you use promises... As long as nothing goes wrong! With the above code there isn't anything in place to handle the potential outcome of the API returning an error status. Fortunately, handling errors is pretty straightforward:

const promise = new Promise((resolve, reject) =>
  setTimeout(() => {
    const chaos = Math.random()
    if(chaos > 0.5) {
      reject('Too much chaos!')
    } else {
      resolve('I waited for 2 seconds')
    }
  }, 2000)
)

promise.then(
  message => console.log(message),
  errorMessage => console.error(errorMessage)
)

The function called in the Promise constructor is actually called with two callback functions; the second being one for rejecting the promise. In much the same way, then also accepts a second callback which executes if the promise is rejected.

Promise chaining

It is possible to chain then functions after a promise. This is also a good place to introduce you to catch. When chaining, it is usually the case that you will only use then for handling promises, a catch can be added to the end of the chain to catch an error thrown from any point preceding it.

Here we will get our promise from another source; I quite often use Axios to make HTTP requests. Their API is really simple, to make a GET request you just write axios.get('api/endpoint/url') which returns a promise that resolves when the data is returned from the server.

axios.get('api/endpoint/url')
  .then(response =>
    saveData(response)
    axios.get('api/endpoint/url2')
  )
  .then(response2 =>
    saveData(reponse2)
  )
  .catch(error =>
    handleError(error)
  )

Here we call our imaginary saveData function with the response from the first API call, then make another request to a different endpoint. If an error is thrown anywhere in this chain it will be caught by the catch function which passes the error object to another imaginary function - handleError.

Promise also has a finally method which can be added to the chain, it's pretty handy for spinners!

showSpinner()
axios.get('api/endpoint/url')
  .then(response =>
    saveData(response)
    axios.get('api/endpoint/url2')
  )
  .then(response2 =>
    saveData(reponse2)
  )
  .catch(error =>
    handleError(error)
  )
  .finally(() =>
    hideSpiner()
  )

Async/await

There is now (since ES2017) a cleaner way than chaining then functions on a promise. The above could be written using async/await like so:

async function getData() {
  const data1 = await axios.get('api/endpoint/url')
  saveData(data1)
  const data2 = await axios.get('api/endpoint/url2')
  saveData(data2)
}

We prepend the async keyword to the function declaration and then use await anywhere we want to pause execution to wait for a promise to resolve.

Unfortunately, error handling with async/await is not as clean as before and the only way (that I know of) to achieve the same level of error handling as above is to wrap everything in a try/catch block:

async function getData() {
  try {
    const data1 = await axios.get('api/endpoint/url')
    saveData(data1)
    const data2 = await axios.get('api/endpoint/url2')
    saveData(data2)
  } catch(error) {
    handleError(error)
  }
}

Asynchronous programming

The examples above work perfectly well but, unless we need to wait for the result of the first call so that we can use the data in the response to make the second call, it is a very inefficient way of programming. I can illustrate this with some code.

First, let's create a mock HTTP GET method:

function get(response, delay) {
  return new Promise(resolve => {
      setTimeout(() => resolve(response), delay * 1000)
  })
}

This function just returns the response which we set with the first argument after waiting for amount of time set with the second argument, delay. We also need to be able to time the test cases we're going to write so let's make a stopwatch:

const stopwatch = (() => {
  let start, end
  return {
    start() {
      start = Date.now()
    },
    stop() {
      end = Date.now()
      return (end - start) / 1000
    }
  }
})()

I've used a closure here, if you're not clued up on closures then you should check out my post about them here. Next, we'll recreate the functions from above:

const testCases = {

  one() {
    return new Promise(resolve => {
      const responses = []
      get('three', 3)
        .then(res => responses.push(res))
        .then(() => get('two', 2))
        .then(res => responses.push(res))
        .then(() => get('one', 1))
        .then(res => responses.push(res))
        .then(() => {
          const output =responses.join(' ')
          resolve(output)
        })
    })
  },

  two() {
    return new Promise(async resolve => {
      const first = await get('three', 3)
      const second = await get('two', 2)
      const third = await get('one', 1)
      const output = `${first} ${second} ${third}`
      resolve(output)
    })
  }
}

Hopefully you can recognise the code from earlier, only here we are making three get requests instead of two. testCases.one pushes all of the data into an array whereas testCases.two uses await to wait for the promises to resolve before assigning the data to local variables. Notice that we create a new Promise and then make the get request within which also returns a promise each time. When we have received all of our data we resolve our 'master' promise. So now, all that remains to do is add the code which runs these tests:

async function runTest(testCase) {
  let result, time;
  stopwatch.start()
  result = await testCases[testCase]()
  time = stopwatch.stop()
  console.log('Result: %s, Time: %s seconds', result, time)
}

This function is called with the name of the test we want to run, it starts the stopwatch and then runs the test. When the test's promise is resolved the stopwatch is stopped and the results are logged to the console. Let's run our tests:

runTest('one') // Result: three two one, Time: 6.003 seconds
runTest('two') // Result: three two one, Time: 6.004 seconds

So you can see that both of our functions took six seconds to run, this is because we have written our code synchronously; each line is executed in order and will wait for the previous lines to complete before running itself. We can instead play to JavaScript's strengths and write our code asynchronously. We'll add a third test to our testCases object:

three() {
    return new Promise(resolve => {
        const responses = []

      function check() {
        if(responses.length > 2) {
            resolve(responses.join(' '))
        }
      }

      get('three', 3).then(res => {
        responses.push(res)
        check()
      })
      get('two', 2).then(res => {
        responses.push(res)
        check()
      })
      get('one', 1).then(res => {
        responses.push(res)
        check()
      })
    })
  }

There's a bit more going on with this function. First we initialise our empty responses array, then we've added a function called check. Following that we make our three get requests as before, only this time we call check each time one resolves. check looks at the length of our responses array and, when our array contains the three responses, it resolves our 'master' promise. Let's see how it does:

runTest('three') // Result: one two three, Time: 3.002 seconds

Half the time, and you can see that the order of our responses has changed, our code is running asynchronously!

Promise.all()

There is a better way to write test-case number three so that we don't need the check function. We can also put our responses back into the same order as the other tests; in the real world this probably isn't important but let's do it anyway!

Time for a confession, I have forgotten to mention something very important about promises. Promises are always in one of three states. When you first create a promise it is in a "pending" state, it is then transitioned into either a "resolved" or "rejected" state. Once a promise has reached "resolved" or "rejected" it cannot go back to "pending". If you want to know which state a promise is in you can call Promise.state(), this is pretty useful when debugging as you can set a breakpoint and run this in the console (I might do a post on debugging in Chrome soon).

Here's test-case number four:

four() {
  return new Promise(resolve => {
    const responses = []
    responses.push(get('three', 3))
    responses.push(get('two', 2))
    responses.push(get('one', 1))
    Promise.all(responses)
      .then(values => {
        const output = values.join(' ')
        resolve(output)
      })
  })
}

In this function we push the returned promises from the get call into the responses array straight away. These promises are in a "pending" state and will act as placeholders, meaning that the results will be in the same order as our first two test-cases. Instead of checking the length of the responses array each time a promise resolves we can use Promise's all method, which itself returns a promise that resolves when all of the promises in the array resolve. This is much better than before because we no longer need to know how many promises we are waiting for:

runTest('four') // Result: three two one, Time: 3.003 seconds

Three seconds again and this time the results are in the correct order. Here's the running code from above if you would like to run the tests yourself:

Hopefully you found this post useful, thanks for taking the time to read to the end. If you have any comments, corrections or questions then you can contact me on Twitter. 👍

Creating a VS Code extension

Matt Thorning — Wed, 30 Jan 2019 20:00:00 +0000

Where I work we have become quite particular about making our code line up vertically in the import sections and when declaring some objects, so that it looks nice and neat! My colleague commented that it would be nice if there was an extension for VS Code that would do the alignment for us, so I made one, and I suspect that this was his plan all along!.

The full code can be found on my Github, I will explain the steps I took to create it below.

Getting started

The first step is to download Yeoman and the VS Code Extension Generator with NPM:

npm install -g yo generator-code

Running the generator scaffolds a new project ready for developing. Just type the following and answer the questions:

$ yo code

   _-----_ ╭──────────────────────────╮
  | | │ Welcome to the Visual │
  |--(o)--| │ Studio Code Extension │
   `---------´ │ generator! │
  ( _´U`_ ) ╰──────────────────────────╯
  / ___A___ \ /
   | ~ |
   __'.___.'__
 ´ ` |° ´ Y `

? What type of extension do you want to create? New Extension (TypeScript)
? What's the name of your extension? my-new-extension
? What's the identifier of your extension? my-new-extension
? What's the description of your extension? It's an extension which is mine and new.
? Enable stricter TypeScript checking in 'tsconfig.json'? No
? Setup linting using 'tslint'? No
? Initialize a git repository? (Y/n) n

Once the project has been created and the dependencies have been installed you can open the folder in VS Code to check out the project structure. Pressing F5 starts the debugger and runs your code in a new "Extension Development Host window". What the team at VS Code have done here is great because you can place breakpoints in the main editor whilst trying out the extension you are writing in a development version of VS Code.

That's all I'm going to say about getting setup, I haven't gone into great detail; if you would like a more in-depth article about getting started then I recommend taking a look at this tutorial on VS Code's website.

Adding a menu item

The first thing I knew that I wanted to do was to add an item to the context menu so that users could right-click on some highlighted text to run the extension. This can be achieved through the package.json, just add the following to the contributes section. Whilst you have this file open you should also change any references to 'helloWorld' to the name of your extension:

"contributes": {
  "commands": [
    {
      "command": "extension.alignVertically",
      "title": "Align Vertically"
    }
  ],
  "menus": {
    "editor/context": [
      {
        "command": "extension.alignVertically",
        "group": "YourGroup@1"
      }
    ]
  }
}

Coding the extension

If you chose to write your extension in JavaScript then you will have a file called extension.js which looks like this when you first open it:

If you are writing your file in TypeScript then it will look different but the logic is going to be the same for both. We need to change the activate function to register our extension, notice that "extension.alignVertically" matches up with the entries in the package.json.

function activate(context) {
  let disposable = vscode.commands.registerCommand(
    'extension.alignVertically',
    alignVertically
  )

  context.subscriptions.push(disposable)
}

The second argument passed to vscode.commands.registerCommand is our function which we will call alignVertically. This function will call the functions which handle the formatting of the text and replace it in the editor:

async function alignVertically() {
  const editor = vscode.window.activeTextEditor
  const text = editor.document.getText(editor.selection)
  if (text) {
    const keyword = await getKeywordFromUser()

Let's take a closer look at this function. On line 2 we get the activeTextEditor from the vscode object (which is required in at the top of the file). Then, on line 3 we get the text which has been highlighted by the user. The if statement on line 4 means that the rest of the program will only run if some text has acutally been selected.

Next (line 5) we prompt the user for the keyword which is going to be used to split the text. You hopefully noticed on line 1 that this function is async which means we can make it wait for some data by using the await command. We call getKeywordFromUser and the execution is paused until the result is returned. Here is the function:

function getKeywordFromUser() {
  return vscode.window.showInputBox({
    placeHolder: "Align by which word?"
  });
}

Using a method on the vscode API's window object, all we need to do is set the placeholder text which we want to be displayed by the input box. The result is returned by the API as a promise which is resolved when the user hits enter.

Back to the alignVertically function:

if (text) {
  const keyword = await getKeywordFromUser()
  const lines = getLines(text, keyword)
  const mask = getMask(lines)
  const transformedText = transform(lines, mask, getSpaces)
  const result = joinWithKeyword(transformedText, keyword)
  editor.edit(builder => builder.replace(editor.selection, result))
}

Lines 6 - 9 call the functions which I have written to transform the highlighted text. These are in another file and I will cover them in the next section. By line 10 we have our transformed text held in a variable called result and all that is left to do is to replace the highlighted text in the editor with value of this result variable.

Our editor variable from line 2 has a method called edit which calls a function with an object (named here builder) which has the method replace and it, as you can probably guess, replaces the selected text (editor.selection - previously used on line 3) with result. Phew, that felt like a lot when typing it out, it's not that bad though, hopefully it made sense to read!

The next couple of sections are about the functions which format the text. If you are only interested in how to create an extension then you should probably skip these and jump down to the last section which is about how to publish your extension to the marketplace. If, however, you're interested in how I formatted the text itself then read on!

Test Driven Development

Lines 6 - 9 use five functions which are imported from a separate file. These functions process the text by:

Splitting the text into separate blocks which I could easily work with.
Calculating the current positions of the supplied keyword in each line.
Creating a new block of the correct amount of empty space for each line.
Adding the new blocks of empty space to each line.
Rejoining the blocks of text back together.

One of the advantages of separating your logic like this is that you can write simple functions which just do one thing each. These are pure functions which do not have any side effects - based on what you put in you know exactly what you are going to get out. Because of this, the best and easiest way to develop our functions is to set up test cases where we can control the input to each function and test that the output is as expected.

The VS Code generator creates your project with Mocha already installed, however I prefer to work with Jest. You can install Jest with NPM:

npm install Jest -D

This will add Jest to the node_modules_ binaries (.bin_) folder, the easiest way to run Jest then is to add this line to the scripts section in your package.json:

"scripts": {
  "test": "jest"
}

And run the tests with the command:

npm test

Jest will search through your codebase for files with .test in the name and run the tests in those files (our functions are in a file which I, rather originally, titled functions.js and the tests are in the, equally originally named, functions.test.js file). You can also start the tests in watch mode so that the tests will re-run each time a change is made; the watch menu includes some useful options that are worth exploring:

$ npm test -- --watch

No tests found related to files changed since last commit.
Press `a` to run all tests, or run Jest with `--watchAll`.

Watch Usage
 › Press a to run all tests.
 › Press f to run only failed tests.
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.
 › Press Enter to trigger a test run.

At the top of the file I require in the functions from functions.js. The reason I put these functions in a separate file was so that I would not need to mock anything when running the tests; if I left them in extension.js then Jest would attempt to import the vscode object.

To create a test suite in Jest you use a describe block. The first argument is just a string which will be used at the start of every test and the second argument is the function within which you run each test.

const {
  getMask,
  getLines,
  transform,
  getSpaces,
  joinWithKeyword
} = require("../functions.js");

describe("The function ", () => {

  const keyword = "SPLIT";

  const text = [
    "This is some SPLIT text",
    "I want SPLIT to test",
    "Nothing to report here",
    "It SPLIT should be getting",
    "split where there SPLIT is"
  ].join("\n");

  const expectedLines = [
    ["This is some ", " text"],
    ["I want ", " to test"],
    ["Nothing to report here"],
    ["It ", " should be getting"],
    ["split where there ", " is"]
  ];

  const expectedMask = [13, 7, 0, 3, 18];

  const expectedTransformed = [
    ["This is some ", " text"],
    ["I want ", " to test"],
    ["Nothing to report here"],
    ["It ", " should be getting"],
    ["split where there ", " is"]
  ];

  const expectedResult = [
    "This is some SPLIT text",
    "I want SPLIT to test",
    "Nothing to report here",
    "It SPLIT should be getting",
    "split where there SPLIT is"
  ].join("\n");

First I set up the variables which will be used in each test. At line 11 is the imaginary keyword supplied by our user, next, at line 13 is the block of text which our user has highlighted (declared as an array joined with \n which is a newline). Each following expected output is then used both to test the function has produced the correct output and also as the input for the following function.

test("getLines returns expected", () => {
    expect(getLines(text, keyword)).toEqual(expectedLines);
  });

  test("getMask returns expected", () => {
    expect(getMask(expectedLines)).toEqual(expectedMask);
  });

  test("getSpaces returns expected", () => {
    expectedMask.forEach(index => {
      const diff = 18 - index;
      expect(getSpaces(18, index).length).toBe(diff);
    });
  });

  test("transform returns expected", () => {
    expect(transform(expectedLines, expectedMask, getSpaces)).toEqual(
      expectedTransformed
    );
  });

  test("joinWithKeyword returns expected", () => {
    expect(joinWithKeyword(expectedTransformed, keyword)).toEqual(
      expectedResult
    );
  });

If a test fails then Jest will give you a handy diff to show you why it failed:

It is possible to set up the VS Code debugger so that you can breakpoint your code as the tests run to help with debugging. I won't go into how to do that here though, maybe in another post!

This is what we're aiming to achieve, all tests passed:

Formatting the text

It's (finally!) time to take a look at the functions themselves. Here's a reminder of lines 6 - 9 from extensions.js:

const lines = getLines(text, keyword)
const mask = getMask(lines)
const transformedText = transform(lines, mask, getSpaces)
const result = joinWithKeyword(transformedText, keyword)

getLines(text, keyword)

getLines(text, keyword) {
  return text.split("\n").map(line => line.split(keyword));
}

The getLines function takes the highlighted text and keyword as arguments and uses Array's split method to split the text on the newline character (remember this is how we tested it above?), we then split each line at the keyword which result in an array where each element is a line of text which is itself an array with each element containing either the text before or after the keyword. For example, if the keyword provided was 'SPLIT', the following text:

This is some SPLIT text

It will SPLIT words by newline

Also by keyword

would output as:

[['this is some ', 'text'], ['It will ', 'words by newline'], ['Also by keyword'] ]

getMask(lines)

getMask(lines) {
  return lines.map(line => {
    if (line.length > 1) {
      return line[0].length;
    }
    return 0;
  });
}

This function creates an array with one element per line. Each element contains a number which represents the length of the block of text which precedes the keyword. If the keyword is not on a line it will put a zero in its place. The mask for the example above would be [13, 8, 0].

getSpaces(max, mask[i])

getSpaces(max, index) {
  const diff = max - index;
  return new Array(diff).fill(" ");
}

This function is used by the transform function (below). It takes the max variable (explained next) and uses it to calculate how much space needs to be added to the block of text. It returns an array of the required length and fills it with empty spaces.

transform(lines, mask, getSpaces)

transform(lines, mask, getSpaces) {
  const max = Math.max(...mask);
  return lines.map((line, i) => {
    if (mask[i]) {
      const extended = [line[0], ...getSpaces(max, mask[i])].join("");
      line.splice(0, 1, extended);
    }
    return line;
  });
}

The first thing this function does is get the max number from the mask. This is the position of the rightmost keyword in our lines of text and is where we want to move our other lines to. Next, it maps through the lines array and if the line has a corresponding number in the mask (ie. is greater than zero) then it creates an extended version of the block of text which has the extra spaces added into it.

This happens on line 5. You can see that we create a new array from our first element (line[0]) and spread the output from the above getSpaces function into it. This array would look like:

['this is some ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ']

Then we join the array, making a string with the block of spaces at the end. On line 6 we use Array's splice method to replace the first element of the line with our new extended version.

joinWithKeyword(transformedText, keyword)

joinWithKeyword(transformed, keyword) {
  return transformed.map(l => l.join(keyword)).join("\n");
}

Finally we just need to put our blocks of text back together. We map through the array output by the transform function and join each line with the keyword. Lastly we join the lines back together using the newline (\n) character again.

So that's everything that we need to do to create the extension. All that remains to do is to make it available for people to use.

Publishing the extension

I'm not going to go into a great deal of detail on this, partly because the documentation on VS Code's site tells you everything you need to know and partly because I feel like I've been prattling on for far too long already! Therefore, for a detailed guide take a look here. The short version is that you need to run:

npm install -g vsce

Then you need to get a Personal Access Token from the Azure DevOps site. You use this token to set yourself up as a publisher by running:

vsce create-publisher < publisher name >

Once vsce (which stands for Visual Studio Code Extension) is setup you can run the below to publish your extension to the marketplace:

vsce publish

If you don't want to publish your extension to the marketplace for public use then you can instead run:

vcse package

This will create a .vsix file which can be shared with whomever you choose and be easily installed with:

code --install-extension < path/to/file.vsix >

When I was figuring out how to make this basic extension I struggled a little bit to find the information I needed. I hope that if you have stumbled across this post that it has helped to fill in one or two of the blanks. If you have any comments or questions, or have spotted something that is incorrect or could have been done in a better way then please let me know on Twitter. Cheers 😄

Semantic versioning with NPM

Matt Thorning — Tue, 22 Jan 2019 20:00:00 +0000

When you release code it's a really good idea to assign a version number to it. This gives users a useful reference number they can send to you if things aren't working as expected (making it easier to track down bugs), gives you a safe point you can roll back to where you know things were working correctly and, as you can see from taking a look at the dependencies and dev-dependencies sections in a package.json, is vitally important if you are planning on building an application which pulls in code from third-party sources.

Fortunately the package.json has a "version" property (as seen above) so you can just increment that and commit to git right? Well, that would be one way of doing it but it doesn't let other people using your code know whether the changes you've made are small bug fixes or massive, sweeping changes which are going to render all of their code completely useless. It's also not going to be particularly easy to checkout an old version because you are going to have to search back through your git log to find the commit where you altered the package.json (I hope you wrote a descriptive commit message!).

Semantic versioning

How do we convey an understanding of the impact our changes will have on our users using just the version number? Semantic versioning (or semver for short) allows us to let them know which one of three categories the code we are releasing falls in to:

Major Version - These changes will break stuff! If you are updating a dependency to a new major version then you need to set aside some time to rework your code to ensure it works correctly; don't do it on a Friday afternoon!
Minor Version - These changes are backwards-compatible features which should not break any existing code, only adding additional functionality.
Patch Version - These are backwards-compatible bug fixes and should therefore be safe to use without having to make changes to any code which uses it.

The version number is in three parts, each part separated by a full stop:

MAJOR.MINOR.PATCH

If our code is at version 2.15.0 and we fix a bug, we would release the fix on version 2.15.1. If we then added a new feature which is not going to break anything then the version would be bumped to 2.16.0. Notice that the patch version goes to zero when the minor version is incremented. Next, say we decide to rewrite a large portion of our code, changing everything; the version goes to 3.0.0 because it is likely that any applications which use our code will now be broken. Again, the numbers to the right of the change are reset to zero.

It's important to understand that, aside from the numbers to the right being reset to zero, the three sections are completely independent of one another, you don't increment the major version when you hit 100 minor versions or anything like that. It's not uncommon to see version numbers like 2.256.0 because developers try to limit the number of breaking changes they release.

Git tagging

So we can now let our users know about the impact our releases are going to have through the version number in the package.json, we just need a way of clearly marking (or tagging!) a commit in our git history as a release. To do this we would need to change the version number in the package.json and then:

git add .
git commit -m "Version 0.15.0 - new useful feature"
git tag 0.15.0

To push the new commit and tag to the remote repository (if you are using one) you would follow the above with:

git push && git push --tags

If we check the git log then you should see that there is a commit which has been tagged with our version number.

If, at a later date, we need to rollback to this release then we can easily do so by typing:

git checkout 0.15.0

NPM version

This is all very useful but that's a lot to do each time you want to release something, especially when you consider that this doesn't actually release anything! Luckily for us, there is a command which will do this for us. To bump the version on the package.json, create a new commit and tag it with the version number you can use one the following commands:

npm version major -m "Version %s - Breaking Changes!"
npm version minor -m "Version %s - New stuff in this release!"
npm version patch -m "Version %s - Hopefully this fixes stuff!"

Like a commit, the string following -m will be the commit message that is displayed in the git log. The %s will be substitued for the version number as you can see below:

By default, NPM puts a v in front of the version number. I'm sure this won't bother most people but it annoys me so I turn it off! To get rid of the v (and add something else if you prefer) you can add a .npmrc file to the root of you project containing this line:

tag-version-prefix=""

Pre and post version scripts

Do you use the scripts section of the package.json? If not, you should, it's incredibly useful! A typical scripts section for me has scripts for running Webpack, Node servers, Jest (for tests) and release scripts. Here is a picture from the package.json of a chat app I made recently to give you some idea:

As you can see in the above picture, there's a script called postversion near the bottom. NPM allows you to create pre and post scripts for any script you like. I could create a "premongo" script or a "postrelease-vps" if I wanted to and NPM would run them exactly where you would expect them to be run. Here, I am using a postversion script to push the newly created tagged commit to the remote repository. If I have Eslint or Jest in a project then I run those in a "preversion" script, if either the tests or the linting fail then the version script does not run.

In this app, which is written in GatsbyJS, I use a "preversion" script to run Prettier which formats my code nicely (I don't bother using a linter in this codebase because of that) and a "postversion" script to push my git commit & tags and then run the release script which pushes my code to the server:

"format": "prettier --write \"src/**/*.js\"",
"preversion": "npm run format",
  "postversion": "git push && git push --tags && ./release.sh"

That's how I use semantic versioning with NPM to make my releases quick and painless, leaving me with more time to do the important stuff! Thanks for reading, if you have any comments, questions or corrections then feel free to send me a message on Twitter.