React Js

CHAPTER-3

Components & Servers

Introduction

In the last chapter, we used a methodology to construct a React app. State management of timers takes place in the top-level component TimersDashboard. As in all React apps, data flows from the top down through the component tree to leaf components. Leaf components communicate events to state managers by calling prop-functions.

At the moment, TimersDashboard has a hard-coded initial state. Any mutations to the state will only live as long as the browser window is open. That’s because all state changes are happening in-memory inside of React. We need our React app to communicate with a server. The server will be in charge of persisting the data. In this app, data persistence happens inside of a file, data.json.

EditableTimer and ToggleableTimerForm also have hard-coded initial state. But because this state is just whether or not their forms are open, we don’t need to communicate these state changes to the server. We’re OK with the forms starting off closed every time the app boots.

Preparation

To help you get familiar with the API for this project and working with APIs in general, we have a short section where we make requests to the API outside of React.

curl

server.js

Included in the root of your project folder is a file called server.js. This is a Node.js server specifically designed for our time-tracking app.

You don’t have to know anything about Node.js or about servers in general to work with the server we’ve supplied. We’ll provide the guidance that you need.

server.js uses the file data.json as its “store.” The server will read and write to this file to persist data. You can take a look at that file to see the initial state of the store that we’ve provided.

server.js will return the contents of data.json when asked for all items. When notified, the server will reflect any updates, deletes, or timer stops and starts in data.json. This is how data will be persisted even if the browser is reloaded or closed.

Before we start working with the server, let’s briefly cover its API. Again, don’t be concerned if this outline is a bit perplexing. It will hopefully become clearer as we start writing some code.

The Server API

Our ultimate goal in this chapter is to replicate state changes on the server. We’re not going to move all state management exclusively to the server. Instead, the server will maintain its state (in data.json) and React will maintain its state (in this case, within this.state in TimersDashboard). We’ll demonstrate later why keeping state in both places is desirable.

TimersDashboard communicates with the server

If we perform an operation on the React (“client”) state that we want to be persisted, then we also need to notify the server of that state change. This will keep the two states in sync. We’ll consider these our “write” operations. The write operations we want to send to the server are:

• A timer is created
• A timer is updated
• A timer is deleted
• A timer is started
• A timer is stopped

We’ll have just one read operation: requesting all of the timers from the server.

HTTP APIs

This section assumes a little familiarity with HTTP APIs. If you’re not familiar with HTTP APIs, you may want to read up on them³⁸ at some
point.

However, don’t be deterred from continuing with this chapter for the time being. Essentially what we’re doing is making a “call” from our browser out to a local server and conforming to a specified format.

text/html endpoint

GET /

This entire time, server.js has actually been responsible for serving the app. When your browser requests localhost:3000/, the server returns the file index.html. index.html loads in all of our JavaScript/React code.

Note that React never makes a request to the server at this path. This is just used by the browser to load the app. React only communicates with the JSON endpoints.

JSON endpoints

data.json is a JSON document. As touched on in the last chapter, JSON is a format for storing human-readable data objects. We can serialize JavaScript objects into JSON. This enables JavaScript objects to be stored in text files and transported over the network.

data.json contains an array of objects. While not strictly JavaScript, the data in this array can be readily loaded into JavaScript.

In server.js, we see lines like this:

fs.readFile(DATA_FILE, function(err, data) {
  const timers = JSON.parse(data);
  // ...
});

data is a string, the JSON. JSON.parse() converts this string into an actual JavaScript array of objects.

GET /api/timers

Returns a list of all timers.

POST /api/timers

Accepts a JSON body with title, project, and id attributes. Will insert a new timer object into its store.

POST /api/timers/start

Accepts a JSON body with the attribute id and start (a timestamp). Hunts through its store and finds the timer with the matching id. Sets its runningSince to start.

POST /api/timers/stop

Accepts a JSON body with the attribute id and stop (a timestamp). Hunts through its store and finds the timer with the matching id. Updates elapsed according to how long the timer has been running (stop – runningSince). Sets runningSince to null.

PUT /api/timers

Accepts a JSON body with the attributes id and title and/or project. Hunts through its store and finds the timer with the matching id. Updates title and/or project to new attributes.

DELETE /api/timers

Accepts a JSON body with the attribute id. Hunts through its store and deletes the timer with the matching id.

Playing with the API

npm start

You can visit the endpoint /api/timers endpoint in your browser and see the JSON response (localhost:3000/api/timers). When you visit a new URL in your browser, your browser makes a GET request. So our browser calls GET /api/timers and the server returns all of the timers:

Note that the server stripped all of the extraneous whitespace in data.json, including newlines, to keep the payload as small as possible. Those only exist in data.json to make it human-readable.

We can use a Chrome extension like JSONView³⁹ to “humanize” the raw JSON. JSONView takes these raw JSON chunks and adds back in the whitespace for readability:

Visiting the endpoint after installing JSONView

We can only easily use the browser to make GET requests. For writing data — like starting and stopping timers — we’ll have to make POST, PUT, or DELETE requests. We’ll use curl to play around with writing data.

$ curl -X GET localhost:3000/api/timers

The -X flag specifies which HTTP method to use. It should return a response that looks a bit like this:

[{"title":"Mow the lawn","project":"House Chores","elapsed":5456099,"id\
":"0a4a79cb-b06d-4cb1-883d-549a1e3b66d7"},{"title":"Clear paper jam","p\
roject":"Office Chores","elapsed":1273998,"id":"a73c1d19-f32d-4aff-b470\
-cea4e792406a"},{"title":"Ponder origins of universe","project":"Life C\
hores","id":"2c43306e-5b44-4ff8-8753-33c35adbd06f","elapsed":11750,"run\
ningSince":"1456225941911"}]

You can start one of the timers by issuing a PUT request to the /api/timers/start endpoint. We need to send along the id of one of the timers and a start timestamp:

$ curl -X POST \
-H 'Content-Type: application/json' \
-d '{"start":1456468632194,"id":"a73c1d19-f32d-4aff-b470-cea4e792406a"}\
' \
localhost:3000/api/timers/start

The -H flag sets a header for our HTTP request, Content-Type. We’re informing the server that the body of the request is JSON.

The -d flag sets the body of our request. Inside of single-quotes ” is the JSON data.

When you press enter, curl will quickly return without any output. The server doesn’t return anything on success for this endpoint. If you open up data.json, you will see that the timer you specified now has a runningSince property, set to the value we specified as start in our request.

If you’d like, you can play around with the other endpoints to get a feel for how they work. Just be sure to set the appropriate method with -X and to pass along the JSON Content-Type for the write endpoints.

We’ve written a small library, client, to aid you in interfacing with the API in JavaScript.

Note that the backslash \ above is only used to break the command out over multiple lines for readability. This only works on macOS and Linux. Windows users can just type it out as one long string.

Tool tip: jq

macOS and Linux users: If you want to parse and process JSON on the command line, we highly recommend the tool “jq.”

You can pipe curl responses directly into jq to have the response pretty-formatted:

curl -X GET localhost:3000/api/timers | jq '.'

You can also do some powerful manipulation of JSON, like iterating over all objects in the response and returning a particular field. In this example, we extract just the id property of every object in an array:

curl -X GET localhost:3000/api/timers | jq '.[] | { id }'

You can download jq here: https://stedolan.github.io/jq/.

Loading state from the server

Right now, we set initial state in TimersDashboard by hardcoding a JavaScript object, an array of timers. Let’s modify this function to load data from the server instead.

We’ve written the client library that your React app will use to interact with the server, client. The library is defined in public/js/client.js. We’ll use it first and then take a look at how it works in the next section.

The GET /api/timers endpoint provides a list of all timers, as represented in data.json. We can use client.getTimers() to call this endpoint from our React app. We’ll do this to “hydrate” the state kept by TimersDashboard.

// Wrong
// `getTimers()` does not return the list of timers
const timers = client.getTimers();

Instead, we can pass getTimers() a success function. getTimers() will invoke that function after it hears back from the server if the server successfully returned a result. getTimers() will invoke the function with a single argument, the list of timers returned by the server:

// Passing `getTimers()` a success function
client.getTimers((serverTimers) => (
// do something with the array of timers, `serverTimers`
));

client.getTimers() uses the Fetch API, which we cover in the next section. For our purposes, the important thing to know is that when getTimers() is invoked, it fires off the request to the server and then returns control flow immediately. The execution of our program does not wait for the server’s response. This is why getTimers() is called an asynchronous function.

The success function we pass to getTimers() is called a callback. We’re saying: “When you finally hear back from the server, if it’s a successful response, invoke this function.” This asynchronous paradigm ensures that execution of our JavaScript is not blocked by I/O.

We’ll initialize our component’s state with the timers property set to a blank array. This will allow all components to mount and perform their initial render. Then, we can populate the app by making a request to the server and setting the state:

class TimersDashboard extends React.Component {
  state = {
    timers: [],
  };
  
  componentDidMount() {
    this.loadTimersFromServer();
    setInterval(this.loadTimersFromServer, 5000);
 }
 
 loadTimersFromServer = () => {
   client.getTimers((serverTimers) => (
       this.setState({ timers: serverTimers })
     )
  );
};
// ...

A timeline is the best medium for illustrating what happens:

<div id='timers'>
</div>

Try it out

Let’s have fun with this now. Save app.js and reload the app. You should see a whole new list of timers, driven by data.json. Any action you take will be wiped out within five seconds. Every five seconds, state is restored from the server. For instance, try deleting a timer and witness it resiliently spring back unscathed. Because we’re not telling the server about these actions, its state remains unchanged.

On the flip-side, you can try modifying data.json. Notice how any modifications to data.json will be propagated to your app in under five seconds. Neat.

We’re loading the initial state from the server. We have an interval function in place to ensure the client app’s state does not drift from the server’s in a multi-instance scenario.

We’ll need to inform our server of the rest of our state changes: creates, updates (including starts and stops), and deletes. But first, let’s pop open the logic behind client to see how it works.

While it is indeed neat that changes to our server data is seamlessly propagated to our view, in certain applications — like messaging — five
seconds is almost an eternity. We’ll cover the concept of long-polling in a future app. Long-polling enables changes to be pushed to clients near instantly.

client

If you open up client.js, the first method defined in the library is getTimers():

function getTimers(success) {
  return fetch('/api/timers', {
    headers: {
      Accept: 'application/json',
    },
}).then(checkStatus)
  .then(parseJSON)
  .then(success);
}

We are using the new Fetch API to perform all of our HTTP requests. Fetch’s interface should look relatively familiar if you’ve ever used XMLHttpRequest or jQuery’s ajax().

Fetch

Until Fetch, JavaScript developers had two options for making web requests: Use XMLHttpRequest which is supported natively in all browsers or import a library that provides a wrapper around it (like jQuery’s ajax()). Fetch provides a better interface than XMLHttpRequest. And while Fetch is still undergoing standardization, it is already supported by a few major browsers. At the time of writing, Fetch is turned on by default in Firefox 39 and above and Chrome 42 and above.

Until Fetch is more widely adopted by browsers, it’s a good idea to include the library just in case. We’ve already done so inside index.html:

<!-- inside `head` tags index.html -->
<script src="vendor/fetch.js"></script>

As we can see in client.getTimers(), fetch() accepts two arguments:

• The path to the resource we want to fetch
• An object of request parameters

By default, Fetch makes a GET request, so we’re telling Fetch to make a GET request to /api/timers. We also pass along one parameter: headers, the HTTP headers in our request. We’re telling the server we’ll accept only a JSON response.

Attached to the end of our call to fetch(), we have a chain of .then() statements:

}).then(checkStatus)
  .then(parseJSON)
  .then(success);

To understand how this works, let’s first review the functions that we pass to each .then() statement:

• checkStatus(): This function is defined inside of client.js. It checks if the server returned an error. If the server returned an error, checkStatus() logs the error to the console.
• parseJSON(): This function is also defined inside of client.js. It takes the response object emitted by fetch() and returns a JavaScript object.
• success(): This is the function we pass as an argument to getTimers(). getTimers() will invoke this function if the server successfully returned a response.

Fetch returns a promise. While we won’t go into detail about promises, as you can see here a promise allows you to chain .then() statements. We pass each .then() statement a function. What we’re essentially saying here is: “Fetching the timers from /api/timers then check the status code returned by the server. Then, extract the JavaScript object from the response. Then, pass that object to the success function.”

At each stage of the pipeline, the result of the previous statement is passed as the argument to the next one:

1. When checkStatus() is invoked, it’s passed a Fetch response object that fetch() returns.
2. checkStatus(), after verifying the response, returns the same response object.
3. parseJSON() is invoked and passed the response object returned by checkStatus().
4. parseJSON() returns the JavaScript array of timers returned by the server.
5. success() is invoked with the array of timers returned by parseJSON().

We could attach an infinite number of .then() statements to our pipeline. This pattern enables us to chain multiple function calls together in an easy-to-read format that supports asynchronous functions like fetch().

It’s OK if you’re still uncomfortable with the concept of promises. We’ve written all the client code for this chapter for you, so you won’t have trouble completing this chapter. You can come back afterwards to play around with client.js and get a feel for how it works.

You can read more about JavaScript’s Fetch here⁴⁰ and promises here⁴¹.

Looking at the rest of the functions in client.js, you’ll note the methods contain much of the same boilerplate with small differences based on the endpoint of the API we are calling.

We just looked at getTimers() which demonstrates reading from the server. We’ll look at one more function, one that writes to the server.

startTimer() makes a POST request to the /api/timers/start endpoint. The server needs the id of the timer and the start time. That request method looks like:

function startTimer(data) {
  return fetch('/api/timers/start', {
    method: 'post',
    body: JSON.stringify(data),
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
  }).then(checkStatus);
}

In addition to headers, the request parameters object that we pass to fetch() has two more properties:

method: 'post',
body: JSON.stringify(data),

startTimer() expects an argument, data. This is the object that will be sent along in the body of our request. It contains the properties id and start. An invocation of startTimer() might look like this:

// Example invocation of `startTimer()`
startTimer(
  {
    id: "bc5ea63b-9a21-4233-8a76-f4bca9d0a042",
    start: 1455584369113,
  }
);

In this example, the body of our request to the server will look like this:

{
  "id": "bc5ea63b-9a21-4233-8a76-f4bca9d0a042",
  "start": 1455584369113
}

The server will extract the id and start timestamp from the body and “start” the timer.
We don’t pass startTimers() a success function. Our app does not need data from the server for this request and indeed our server will not return anything besides an “OK” anyway.
getTimers() is our only read operation and therefore the only one we’ll pass a success function. The rest of our calls to the server are writes. Let’s implement those now.

Sending starts and stops to the server

We can use the methods startTimer() and stopTimer() on client to make calls to the appropriate endpoints on the server. We just need to pass in an object that includes the id of the timer as well as the time it was started/stopped:

// Inside TimersDashboard
// ...
startTimer = (timerId) => {
  const now = Date.now();

  this.setState({
    timers: this.state.timers.map((timer) => {
      if (timer.id === timerId) {
        return Object.assign({}, timer, {
          runningSince: now,
        });
      } else {
        return timer;
      }
    }),
  });

  client.startTimer(
    { id: timerId, start: now }
  );
};

stopTimer = (timerId) => {
  const now = Date.now();

  this.setState({
    timers: this.state.timers.map((timer) => {
      if (timer.id === timerId) {
        const lastElapsed = now - timer.runningSince;
        return Object.assign({}, timer, {
          elapsed: timer.elapsed + lastElapsed,
          runningSince: null,
        });
      } else {
        return timer;

      }
    }),
  });

  client.stopTimer(
    { id: timerId, stop: now }
  );
};

render() {

You might ask: Why do we still manually make the state change within React? Can’t we just inform the server of the action taken and then update state based on the server, the source of truth? Indeed, the following implementation is valid:

startTimer: function (timerId) {
  const now = Date.now();

  client.startTimer(
    { id: timerId, start: now }
  ).then(loadTimersFromServer);
},

We can chain a .then() to startTimer() as that function returns our original promise object. The last stage of the startTimer() pipeline would then be invoking the function loadTimersFromServer(). So immediately after the server processes our start timer request, we would make a subsequent request asking for the latest list of timers. This response would contain the now-running timer. React’s state updates and the running timer would then be reflected in the UI.

Again, this is valid. However, the user experience will leave something to be desired. Right now, clicking the start/stop button gives instantaneous feedback because the state changes locally and React immediately re-renders. If we waited to hear back from the server, there might be a noticeable delay between the action (mouse click) and the response (timer starts running). You can try it yourself locally, but the delay would be most noticeable if the request had to go out over the internet.

What we’re doing here is called optimistic updating. We’re updating the client locally before waiting to hear from the server. This duplicates our state update efforts, as we perform updates on both the client and the server. But it makes our app as responsive as possible.

The “optimism” we have here is that the request will succeed and not fail with an error.

Using the same pattern as we did with starts and stops, see if you can implement creates, updates, and deletes on your own. Come back and compare your work with the next section.

Optimistic updating: Validations

Whenever we optimistic update, we always try to replicate whatever restrictions the server would have. This way, our client state changes under the same conditions as our server state.

For example, imagine if our server enforced that a timer’s title cannot contain symbols. But the client did not enforce such a restriction. What would happen?

A user has a timer named Gardening. He feels a bit cheeky and renames it Gardening :P. The UI immediately reflects his changes, displaying Gardening as the new name of the timer. Satisfied, the user is about to get up and grab his shears. But wait! His timer’s name suddenly snaps back to Gardening.

To successfully pull off eager updating, we must diligently replicate the code that manages state changes on both the client and the server. Furthermore, in a production app we should surface any errors the request to the server returns in the event that there is an inconsistency in the code or a fluke (the server is down).

Sending creates, updates, and deletes to the server

// Inside TimersDashboard
// ...
createTimer = (timer) => {
  const t = helpers.newTimer(timer);
  this.setState({
    timers: this.state.timers.concat(t),
  });

  client.createTimer(t);
};

updateTimer = (attrs) => {
  this.setState({
    timers: this.state.timers.map((timer) => {
      if (timer.id === attrs.id) {
        return Object.assign({}, timer, {
          title: attrs.title,
          project: attrs.project,
        });
      } else {
        return timer;
      }
    }),
  });

  client.updateTimer(attrs);
};

  deleteTimer = (timerId) => {
    this.setState({
      timers: this.state.timers.filter(t => t.id !== timerId),
    });

    client.deleteTimer(
      { id: timerId }

   );
};

startTimer = (timerId) => {

Recall that, in createTimer() and updateTimer() respectively, the timer and attrs objects contain an id property, as required by the server.

For creates, we need to send a full timer object. It should have an id, a title, and a project. For updates, we can send an id along with just whatever attributes are being updated. Right now, we always send along title and project regardless of what has changed. But it’s worth noting this difference as it’s reflected in the variable names that we are using (timer vs attrs).

Give it a spin

We are now sending all of our state changes to the server. Save app.js and reload the app. Add some timers, start some timers, and refresh and note that everything is persisted. You can even make changes to your app in one browser tab and see the changes propagate to another tab.

Next up

We’ve worked through a reusable methodology for building React apps and now have an understanding of how we connect a React app to a web server. Armed with these concepts, you’re already equipped to build a variety of dynamic web applications.

In imminent chapters, we’ll cover a variety of different component types that you encounter across the web (like forms and date pickers). We’ll also explore state management paradigms for more complex applications.