I wanted a way to synchronize my personal calendar to my work calendar, but not reveal any of the details. Fortunately, I found a Google Apps script that started as an inspiration point. I've added to it and included more thorough instructions to make it more friendly to people unfamiliar with code.

Enjoy!

Google Apps script to copy personal events and block those times in your work calendar.

Google Apps script to copy personal events and block those times in your work calendar. - calendarCopy.js

262588213843476Gist

I've done this so many times, and I keep forgetting what exactly needs to be done. So I decided to write it down. Enjoy!

You have a few files to update:

• .ruby-version -- tells various systems (e.g. rvm) which ruby version to use automatically
• Gemfile -- update the ruby line toward the top of the file

Once that's done, you'll need to reinstall stuff. Start by installing the new ruby version in rvm:

$ rvm install "ruby-2.6.6"

Then you'll need to install the bundler for the new ruby version. Grab the bundler version from the Gemfile.lock, search for BUNDLED WITH. At the time of writing, that was 2.1.4. Then you install it:

$ gem install bundler:2.1.4

Once that's done, run bundler to install all your gems for the newly installed ruby version:

$ ruby -v
# should be the one you just installed, e.g. 2.6.6
# if not, reload your shell

$ bundle

Lastly, you'll want to quit and re-open RubyMine to let it work its magic with indexing the new ruby SDK and its gems. Your settings should now point to the new SDK:

And with that, you're done!

  def index
    @users = User.all

    respond_to do |format|
      format.csv { send_data @users.to_csv, filename: "users-#{Date.today}.csv" }
    end
  end

And then wonder how you can test the contents as well as the filename, and the fact that it's supposed to be a download?

To check the filename, look at response.headers['Content-Disposition'].

expect(response.headers['Content-Disposition'])
  .to eq 'attachment; filename=users-2020-10-23.csv'

To check the contents, look at response.body:

expect(response.body).to eq <<~CSV
  First Name,Last Name
  Andrew,Smith
CSV

A quick story in the importance of database-level validations...

At Transparent Classroom, teachers are allowed to react to photos uploaded by parents with either a Heart or a Thumbs Up.

Much like Facebook, you can only have reaction for a post. If you click Heart and then Thumbs Up, it will change your reaction rather than create a new one.

A simple solution to this on the server side could look like:

def create
  if (reaction = @post.reactions.find_by user: current_user)
    reaction.update! code: params[:reaction]
  else
    @post.reactions.create! user: current_user, code: params[:reaction]
  end
  # ...
end

A pretty common pattern, but there's a sneaky race condition in this code. Can you find it?

Our users were able to find it. Turns out that a combination of clicking different reactions in rapid succession, combined with the database occasionally being slightly slower, means that the system can break.

If a sleep 3 was added before @post.reactions.create! it's easy to trigger. On the first request, the DB is checked for the presence of a reaction, finds none, and then starts the (artificially slow) process of creating a reaction. Meanwhile, a second request comes in, similarly doesn't (yet) find a reaction in the DB, and also starts to create a different reaction for the same post.

🤦‍♂️

Luckily, we had put a Rails model validation on our Reaction:

class Reaction
  validates :user_id, presence: true, uniqueness: { scope: :post_id }
  # ...
end

What could've led to bad data in the system instead simply triggered a 500 that we could detect and recover from.

Remember kids: latency is the root of many system errors. Even a simple system like ours (no distributed systems, simple lookup, a couple lines of code, etc.) can have edge cases that are easy to miss but likely to encounter.

Latency is exceptionally hard to account for correctly, and it takes a lot of extra time and careful design. We generally don't have the luxury of going slowly and meticulously designing every new feature or system. We move fast, so a decent middle ground is to add validations to protect against bad data and then to fix bugs due to latency when they're triggered in the real world.

You get your first custom hook working, everything looks good in prod. Then, like the responsible developer you are, you write a simple test for it and run it.

Damn.

"Invariant Violation: Hooks can only be called inside the body of a function component." But... you ARE!

A likely culprit is that you have multiple copies of React in your system. Rather than hunting through yarn.lock files, you can most reliably confirm this with some simple debugging logs:

// Add this in node_modules/react-dom/index.js
window.React1 = require('react');

// Add this in your component file
require('react-dom');
window.React2 = require('react');
console.log(window.React1 === window.React2);

Most people focus on forcing the same react package using Yarn resolutions. However, if you're only getting this error in your tests, the most likely culprit is a different version of react-test-renderer. You can fix it by adding these lines to your package.json file if you're using Yarn:

"resolutions": {
    "react-test-renderer": "your.reaction.version"
  }

Hope that helps!

Primarily I solve problems in Ruby or JavaScript, my two primary languages at the moment. For funsies and a little bit of a challenge, I decided to take on a couple easy katas in a different language. Apparently, because I'm a glutton for punishment, I chose to solve it in Java.

The challenge was straightforward: take a string of words, and print the words in reverse; so Hello I like Ruby becomes Ruby like I Hello.

Easy enough, I thought. In Ruby it's the most terse:

str.split(' ').reverse.join(' ')

JavaScript is not far behind. Unfortunately, its Array#reverse method is destructive, reversing the elements in place, but whatever JS you made some poor choices back in the day, we all learned better since then.

str.split(' ').reverse().join(' ')

Then, I took on Java. Boy, was I in for a surprise. I thought it would be very similar, pretty straightforward.

1. Turn your string into an array of strings.

Is it str.split(" ")? Nope. Missing a semicolon. Okay fine, how about return str.split(" ");? Sure, that gives us String[] but it turns out that's a comically under-featured abstraction. Want to do something like a reversal? Good luck doing that with Anything[] in a declarative way. You want a List, which you get with Arrays.asList(thing), and also requires an import. Great! I have a solution!

import java.util.*;

public class ReverseWords {
    public static String reverseWords(String str) {
        return Arrays.asList(str.split(" ")).reverse().join(" ");
    }
}

Nope. Hold on cowboy. You want a reverse method on List? What kind of craziness is that? You need the Collections framework, which gives you Collections.reverse(list).

Okay, fine, whatever, here we go:

import java.util.*;

public class ReverseWords {
    public static String reverseWords(String str) {
        Collections.reverse(Arrays.asList(str.split(" "))).join(" ");
    }
}

Still nope?! It turns out Collections.reverse doesn't return anything which is not intuitive and only does the reversal in place.

And guess what? List doesn't have a join method either. Want to join a list back into a string? Why, that would be on the String class, of course. Why? Because Java. Doesn't. Make. Sense.

import java.util.*;

public class ReverseWords {
    public static String reverseWords(String str) {
        List words = Arrays.asList(str.split(" "));
        Collections.reverse(words);
        return String.join(" ", words);
    }
}

And there you have a working solution. This solution also happens to be highest ranked for cleverness and best practices in Codewars. This is the best that can be done in Java? Yep, and what's more, it can get a lot worse:

public class ReverseWords{
   public static String reverseWords(String str){
       String[] str2 = str.split(" ");
       String fin = "";
       for(int i=str2.length-1;i>=0;i--){
           fin += str2[i];
           if(i>0)fin+=" ";
       }
       return fin;
   }
}

There is no way you could, at a glance while squinting, understand what this code is doing (without reading the method name). I like to ask myself: does my code pass the "squint test"? (It's often used in reference to parsing graphs, but I think it applies to software as well.) I focus on writing code that can be skimmed so that later, when I've lost all context about the code I wrote, I don't get annoyed with past Andrew.

I remember being similarly frustrated by the limitations of Java when I was working on the backend of Kinesis Analytics at AWS. Doing a basic operation such as mapping across an array ( arr.map { |x| doSomething(x) } in Ruby or arr.map(x => doSomething(x)) in JS) in Java requires a baffling amount of verbosity:

arr.stream().map(e -> doSomething(e)).collect(Collectors.toList());

Moments like these make me appreciate how languages like Ruby were so revolutionary, in focusing on using human-readable syntax and favoring declarative over imperative coding. The Java solution reveals so many more implementation details and requires far more constructs ( String, String[], List<String>, Collections).

It's not about brevity or fewest keystrokes (though I do enjoy a clever solution in katas), it's about expressiveness. I value the ability to express in abstract, high-level terms about something I want to accomplish. That's the point of declarative programming: focus on what kinds of transformations you want to perform on your data, rather than how to perform those transformations.

We do TDD for most development at Transparent Classroom, including our frontend business logic written in Redux. Doing TDD for Redux revealed certain frustrating aspects of structuring and testing Redux. I set out to make it better. This post offers a slightly different structure for your reducers to make them more testable and easier to statically type (for Flow or TypeScript). Let's dive in.

(Note: we also use Flow for type checking, which adds additional motivation for what we did. Where appropriate, I'll be adding Flow typing for discussion purposes, otherwise I'll strip it.)

The Status Quo

In the offical docs, reducers are structured using a switch statement, and then the branches of the reducer are tested using actions:

it('should handle ADD_TODO', () => {
  expect(reducer(initialState, addTodo('Run the tests'))) .toEqual([
    {
      text: 'Run the tests',
      completed: false,
      id: 0
    }
  ])
})

There were a couple issues that didn't sit right with me:

1. Navigation was a pain. We couldn't navigate directly to that part of the reducer from the spec by going into a function definition. At best, we'd have to look for usages of the constant, then find it that way.
2. Tests didn't read naturally, with all the extra setup for the reducer, action object, etc. We wanted to write functions, because functions are easy to test.
3. We're also testing the action creators, which are a separate concern; not a big deal, but also not my favorite.
4. Type checking with Flow was a miserable experience based on what was recommended by the official Flow docs. We were essentially creating the same type definition in multiple places, getting obtuse errors, and finding little benefit. (That's saying a lot for being one of the maintainers of flow-typed.)

Finding a Better Way: Handlers -- Take 1

An alternative to using a switch statement is to have a "handlers object," mapping action types to handlers, like so:

export const todos = createReducer([], {
  [ActionTypes.ADD_TODO]: (state, action) => {
    const text = action.text.trim()
    return [...state, text]
  }
})

(Amusingly, I thought of this idea on my own after ruminating on how to improve on the switch statement, then discovered it was already discussed in the Redux docs. Turns out coming up with original ideas is hard.)

It was a nice start, but not enough. It didn't allow for easy navigation between implementation and test, and the dynamic key object syntax felt a bit weird and limiting.

This approach can be taken one step further to something that is truly useful, however. The functions on that "handlers object" can be pulled out and exported. At last, we have a solution where we're testing functions rather than a system. I call these exported functions handlers:

// reducer.js
export const addTodo = ({ todo }, state) => /* ... */

// reducer_spec.js
describe('#addTodo', () => {
  it('should add a todo to the state', () => {
    expect(addTodo({ todo: 'Hello' }, [])).toEqual(['Hello'])
  })
})

The need for an action object to be passed in was still dissatisfying and not natural to write. Consider a handler that takes a bunch of pieces of data that are necessary, i.e. an action object with many keys:

it('should do a thing', () => {
  const action = {
    thing1: 'foo',
    thing2: 'bar',
    thing3: 'baz',
    thing4: 'qux',
  }
  const state = myHandler(action, defaultState)
  /* ... */
})

it('should do another thing', () => {
  const action = {
      thing1: 'argh',
      thing2: 'whyMustI',
      thing3: 'keepWritingOut',
      thing4: 'theseDarnKeys',
    }
})

Finding a Better Way: Handlers -- Take 2

I wanted something that reads more naturally, like an ordinary function that has multiple parameters:

myHandler('foo', 'bar', 'baz', 'qux', state)

In its current form, the handlers were just an extraction of the internals of how Redux and reducers work, and I wasn't interested in being beholden to those details. I wanted to extract the arguments from the action object and just give them to the handler. Turns out, you can do just that.

// Let's say you have an action object...
const actionObject = { type: 'ADD_TODO', title: 'Write a cool blog post about reducers', description: 'It better be good...' }

// ...you can safely extract the values and pass them in as parameters to a handler 
const { type, ...payload } = actionObject
const newState = myHandler(...Object.values(payload), state)

A brief disclaimer about Object.values and object iteration order, before you flip a table...

I thought using Object.values in this way would be dangerous: we always hear about how the iteration order of an object's keys is not guaranteed. I tried a couple alternatives, including having the action creators generate Maps rather than objects (where the order is guaranteed). Using Maps were unpleasant to debug and it bothered me to step further away from how Redux is normally structured (i.e. using plain objects).

ES6, however, introduced a spec for the iteration order of object keys. For objects with string (non-Symbol) keys that can't be parsed as integers, the iteration order is simply the insertion order.

Object.values({ foo: 1, bar: 2 })
// [1, 2]

Adding keys that are symbols ({ [Symbol('first')]: true }) or ones that can be parsed as integers ({ '10': true }) behave differently and make the picture more complex, but that doesn't matter for our purposes, because we want the string keys on the object to generally reflect parameter names, which cannot be integers or Symbols. Put another way, we have no need for Symbols or strings that can be parsed as integers to be used as keys on our action objects.

Assuming consistent iteration order for object keys is totally safe given the above restrictions, which I think are reasonable. We've been doing it in our production code for almost a year without issue. Even older browsers seem fine, because Object#values is polyfilled by our Babel setup, so we can safely rely on the newer standard for how it behaves. (No promises though.)

Now then, disclaimer aside...

With this new pattern to extract the values off the action object and apply them to a handler function, we could easily translate handler functions into a reducer that fits with Redux. Remember, a reducer is a function that takes a state and an action object and returns a state:

export const addTodo = (title, description, state) => { /* ... */ }
export const removeTodo = (id, state) => { /* ... */ }

const handlers = {
  [ADD_TODO]: addTodo,
  [REMOVE_TODO]: removeTodo,
}

const reducer = (state = defaultState, { type, ...args }) => {
  const handler = handlers[type]
  if (!handler) return state
  return handler(...Object.values(args), state)
}
export default reducer

With all this in place, we could test our reducers as a series of functions, easily navigate from its usage in the test to the implementation, and have a bunch of other handy IDE intellisense features (e.g. easily seeing code structure, auto-imports, etc.).

// actions.js
export const addTodo = (title, description) => ({ type: ADD_TODO, title, description })

// reducer.js
export const addTodo = (title, description, state) => { /* ... */ }

// reducer_spec.js
it('should do a thing', () => {
  const state = addTodo('My First Todo', 'I feel so proud!', defaultState)
  /* ... */
})

Ah, the sweet smell of victory.

A bit on the nose, but worth reminding: the parameter names of the addTodo handler do not have to match the key names of the action object; only the order of them matters. We use the same names for convenience. If you had something like this:

// actions.js
export const addTodo = (title, description) => ({ type: ADD_TODO, description, title }) // <-- notice the order

// reducer.js
export const addTodo = (title, description, state) => { /* ... */ } // <-- vs. here

... you've got a bug. That translation does feel brittle, and also it hasn't come up yet as a problem. We're talking about other possible solutions such as using ducks to co-locate our action creators and reducers, or even auto-generate our action creates based on our reducers, for an even better developer experience.

Wiring the Handlers to the Reducer

The tricky part then became how to tell the reducer to actually use these handlers. You saw one above, where I created the handlers object, and just before the reducer I associated handlers to their action types. I didn't like it that much; it wasn't obvious when a handler was actually being registered with the reducer. After running through a few different approaches, I settled on the concept of "registering" a handler on the handlers object, then giving the object to the reducer. I'm going to omit the actual helper code for now and focus on its usage:

// reducer.js

const handlers = {}
const registerHandler = setupRegistration(handlers)

export const addTodo = (title, description, state) => { /* ... */ }
registerHandler(ADD_TODO, addTodo)

export const removeTodo = (id, state) => { /* ... */ }
registerHandler(REMOVE_TODO, removeTodo)

const initialState = { /* ... */ }
export default createReducerWithHandlers(handlers, initialState)

This approach made it clear which handlers were actually employed by the reducer (rather than helpers) and colocated the action type with the handler. Super handy for navigation and reasoning about whether a handler was being used directly to respond to an action type.

Wait, Why is the State a Parameter at the End?

I structured the handlers to take the state object at the end rather than at the beginning (like in the actual reducer). Answering the question of "why" requires diving into a bit of functional programming.

I made this design choice to reflect a common principle of functional programming: put the intended recipient of the operation at the end of the parameter list. So, if you were to write a standalone map function:

// do this
map(someFn, xs)

// not this
map(xs, someFn)

This principle is useful because you can make that concept of "map someFn" into another abstraction:

const addOne = x => x + 1
// this is the abstraction
const incrementList = map(addOne) // this assumes `map` is curried
// which can be applied to various lists
const list1 = incrementList([1, 2, 3])
const list2 = incrementList([4, 5, 6])

Trying to do it the other way around is... really hard to do. So, to reiterate, in FP you often want to structure your functions such that the most commonly changing parameter comes at the end, so you can create more useful abstractions on the parameters that come before it.

(By the way, if const incrementList = map(addOne) throws you and you don't know about currying, I strongly recommend you check out one of the many excellent blog posts out there that explains this concept. The basic idea of currying is that it allows you to take a function and incrementally call it with arguments until all the parameters are provided, and then the function is called. So, for example, add(1, 2) === add(1)(2).)

Anyway. I moved the state to the end to make piping state from one handler to the next a breeze. If you curry your handlers, the tests become wonderfully simple and expressive, piping results from one handler into another one.

A brief aside on piping

pipe takes any number of functions, takes the last parameter given to it and gives it to the first fn, which then pipes the output into the second one, and so on. FPers call it "left-to-right composition." If you have something like pipe(f1, f2, f3, x), this translates to f3(f2(f1(x))). Or, in an imprecise graphical sort of way, f1(x) -> f2 -> f3.

I strongly recommend using Ramda to give you an insanely powerful FP toolkit for Javascript. I hope to write more about Ramda some other day.

So, with pipe, we can easily build up a state through a sequence of handler uses.

const state = pipe(
  addTodo('First Todo', 'This was my first todo!'),
  addTodo('Make TDD better', 'Focus first on reducers'),
)(defaultState)

Compare this with the alternative, where state is the first parameter:

const state = pipe(
  x => addTodo(x, 'First Todo', 'This was my first todo!'),
  x => addTodo(x, 'Make TDD better', 'Focus first on reducers'),
)(defaultState)

It's not terrible, but I vastly prefer the flexibility of the former. Also, the handlers can then be used to create other abstractions, in the same way as incrementList was created:

const someComplicatedHandler = curry((arg1, arg2, arg3, arg4, arg5, state) => { /* ... */ })
const mostlyFigureOutHandler = someComplicatedHandler(1, 2, 3, 4)

With all this setup, you can at last achieve TDD nirvana and test the various parts of your reducer functionality like they were functions that are composable and modular. (Yes, you functional programmers out there can be all 🙌 here.)

it('#completeTodo should mark a todo at an index as completed', () => {
  const state = pipe(
    addTodo('A'),
    addTodo('B'),
    addTodo('C'),
    completeTodo(1),
  )(defaultState)

  expect(state.map(x => x.completed)).toEqual([false, true, false])
})

Static Typing for Reducers

Using this approach of exporting handlers and registering them on the reducer provides the added benefit of dramatically simplifying the type checking for reducers. I'll discuss it using Flow, but I'm sure TypeScript would be similar.

Setting up type checking based off the Flow docs is a mouthful, requiring a lot of extra typing:

// types.js
type FooAction = { type: "FOO", foo: number }
type BarAction = { type: "BAR", bar: boolean }

type Action =
  | FooAction
  | BarAction

// actions.js
const fooAction: FooAction = (foo: number) => ({ type: 'FOO', foo })
const barAction: BarAction = (bar: boolean) => ({ type: 'BAR', bar})

// reducer.js
function reducer(state: State, action: Action): State {
  switch (action.type) { /* ... */ }
}

It works, but not perfectly. Flow sometimes behaves strangely with disjoint unions because it's not a perfect system. It's also hard to understand, requiring a deeper knowledge of Flow and typing. Finally, inside the reducer, you don't actually know your types at the various branches of your switch statement; you have to refer to a different file entirely to figure out the types of the action object for that branch.

Fortunately, using handlers circumvents all these issues, because the handlers are simply functions whose parameters can be easily typed. The inputs to the function are explicitly typed right with the definition, making it a breeze to read.

const addTodo = (title: string, description: string, state: TodosStateT): TodosStateT => { /* ... */ }

(We append type names with T to avoid naming conflicts, which has worked out really well for us.)

We don't bother typing our actions because it hasn't served any utility. There's a temptation to "Type All The Things" with Flow, but we've decided to be more strategic around what we type to maximize benefit and not waste time.

TL;DR

To recap: you can write your reducers as a collection of handlers that are registered to the reducer. Structuring them this way keeps with the patterns of Redux while improving testability, navigation, and general developer experience. Here's the code in a nutshell, including the helper functions extracted into a separate file:

// reducer_helpers.js

// this mutates the handler object! That's okay though.
export const setupRegistration = (handlers) => (actionType, handler) => {
  handlers[actionType] = handler
}

export const createReducerWithHandlers = (handlers, defaultState, state, { type, ...args }) => {
  const handler = handlers[type]

  if (!handler) return state || defaultState

  // This is safe for empty args arrays, the spread will still come out to be [state], not [null, state]
  return handler(...Object.values(args), state)
}

// reducer.js

const handlers = {}
const registerHandler = setupRegistration(handlers)

export const addTodo = (title, description, state) => { /* ... */ }
registerHandler(ADD_TODO, addTodo)

export const removeTodo = (id, state) => { /* ... */ }
registerHandler(REMOVE_TODO, removeTodo)

const initialState = { /* ... */ }
export default createReducerWithHandlers(handlers, initialState)

I hope you will give it a try and see if you get similar benefits. I'd love to hear your thoughts and how it works out in your projects.

Are you using Ramda and Webpack? Then you probably want to read this, because chances are good you're importing more of the Ramda library than you might think...

We're all big on reducing bundle sizes for the web. When leveraging larger utility libraries such as Ramda, we are encouraged to only import the functions we need:

import R from 'ramda' // bad times
import { identity } from 'ramda' // good times

At Transparent Classroom, we dutifully do as such, yet recently I was struck with an unfortunate reality: the whole Ramda library was still being imported.

So, I started to do some investigating, and began with a simple test file:

import { identity } from 'ramda'

identity()

Running webpack on that, it yielded this result, which felt like a horrible betrayal.

The expected contract was broken: when you extract your imports, you don't get the whole darn library. Based on several discussions (here, here, and here), most fingers point to webpack being the culprit. There was a thorough exploration of webpack and its tree shaking abilities WRT Ramda done here. It turns out your options are limited if you're just using webpack:

1. Manually cherry pick: do import identity from 'ramda/es/identity' -- ugh, no thank you.
2. Use ModuleConcatenationPlugin -- helps improve the tree shaking algorithm, though it's still a bit experimental.

Fortunately, if you use babel, there's a handy plugin that can manually turn your general imports into cherrypicked imports:

import R, {map} from 'ramda';

map(R.add(1), [1, 2, 3]);

becomes

import add from 'ramda/src/add';
import map from 'ramda/src/map';

map(add(1), [1, 2, 3]);

With this plugin in place, justice is restored:

Doing this on our app reduced the Ramda library import by 60%, from 75.5KB to 29.8KB.

However, I still like to include the whole Ramda library and set it on window in my dev environment for debugging purposes, i.e. window.R = require('ramda'). Turns out the plugin doesn't like that, discussed here. The easy solution is to only enable the plugin in dev. Here's my .babelrc file, shortened to the relevant part:

{
  ...
  "env": { "production": { "plugins": ["ramda"] } }
}

Next up: dropping use of lodash. Oh the joys of working on apps that have lived through many eras of web development (that is to say, is ~5 years old).

I've put together my first screencast demonstrating deployment of a Node.js app with a PostgreSQL backend to AWS using Elastic Beanstalk and Travis as a continuous integration server. I had a lot of fun putting it together, and owe many thanks to Kevin Whinnery who put together the repo I used for demo purposes. He taught a course on Frontend Masters about (among other things) running a Node app in production on AWS. Based on what I learned there, I expanded with setting up Travis CI as well as providing some of my own tips on a more secure setup (using a slightly different configuration for security groups and the database). I hope you enjoy, feedback is most welcome!

Repo to get started. Most of the instructions are in the README, with the screencast providing a clearer visual walkthrough along with explanations of core concepts in AWS.

I'm a huge fan of JavaScript, but sometimes I'm left flabberghasted by some of its most basic reasoning.

// This sort of makes sense... 
1 > null  // true

// ...what?
-1 > null  // false

I would get it if any number was larger than null, but apparently in the land of JavaScript only positive numbers are larger.

In case you haven't seen it, I highly recommend the Wat talk by Gary Bernhardt. Super funny, and reveals a lot of quirks of different languages.

I recently took a couple hours to read through the Flow docs, which was an informative and valuable use of time. Here are a bunch of notes on useful and slightly intuitive aspects of Flow. Many of these code blocks are pulled from the docs.

Setting up Flow.

The Flow official page has decent installation instructions. If you're using Webpack and it's already working with Babel, all you need is to install the packages and edit your .babelrc file as they mention.

Setting up with Webstorm / Rubymine

This article provides a thorough explanation, but here's the basic takeaway:

1. Go to Preferences | Languages & Frameworks | JavaScript in WebStorm and set language version to Flow.
2. Specify the Flow executable to something similar to this path, replacing /path/to with your directory structure: /path/to/TransparentClassroom/node_modules/flow-bin/vendor/flow

Using Flow.

This page is a good place to get the basic understanding what what's going on, and then read here for all the information on different types, and it's good to start at the beginning and read through, it has a good linear progression. Most of them are pretty obvious or easy to find in the documentation (e.g. arrays, objects, functions). Here are a few that are less obvious, but very useful:

Union type

Allows you to specify more than one possible type.

function stringifyBasicValue(value: string | number | boolean) {
  return '' + value;
}

Can also be written with leading vertical bar:

type Foo =
  | Type1
  | Type2

Read-only properties

You can make properties of an object read-only, which can be super useful in helping enforce immutability. More here.

type Foo = { +bar: string }
const a: Foo = { bar: 'hello' }
a.bar = 'new' // Error: Flow: object type. Covariant property `bar` incompatible with contravariant use in assignment of property `bar` 

Disjoint union

Useful for when you know that the type will have certain properties dependent on a specific property, e.g. whether a server call was successful. Read more.

// @flow
type Success = { success: true, value: boolean };
type Failed  = { success: false, error: string };

type Response = Success | Failed;

function handleResponse(response: Response) {
  if (response.success) {
    var value: boolean = response.value; // Works!
  } else {
    var error: string = response.error; // Works!
  }
}

Mixed type

When the type is unknown.

function getTypeOf(value: mixed): string {
  return typeof value;
}

Important! Don't confuse with any, which effectively disables type checking and can leak to other parts of the system.

$Keys

Useful for enums with values you want to access at runtime. More here.

// @flow
const countries = {
  US: "United States",
  IT: "Italy",
  FR: "France"
};

type Country = $Keys<typeof countries>;

const italy: Country = 'IT';
const nope: Country = 'nope'; // 'nope' is not a Country

Maybe types vs. optional parameters

A maybe type is that type, undefined, or null. It's a ? in front of the type, e.g. ?number

// @flow
function acceptsMaybeNumber(value: ?number) {
  // ...
}

acceptsMaybeNumber(42);        // Works!
acceptsMaybeNumber();          // Works!
acceptsMaybeNumber(undefined); // Works!
acceptsMaybeNumber(null);      // Works!
acceptsMaybeNumber("42");      // Error!

An optional parameter is specified with a ? after the variable name. It means the parameter is either specified or undefined, but not null.

// @flow
function acceptsObject(value: { optionalProp?: string }) {
  // ...
}

acceptsObject({ foo: "bar" });     // Works!
acceptsObject({ foo: undefined }); // Works!
// $ExpectError
acceptsObject({ foo: null });      // Error!
acceptsObject({});                 // Works!

Using Flow with Redux.

The Redux GitHub repo has a nice starter example of using Flow with Redux. Noteworthy points:

• Defining types in a separate folder, and using them everywhere for consistency
• Making Actions and other state variables read-only through the use of covariant properties
• Using same properties that define state as properties on React components. Now it's much easier to keep React component types in sync with state. Whoo!

Digging deeper.

There's much more to explore, and this page offers a good starting point. Happy digging.

At Transparent Classroom, we use both Mocha/Chai to test our modules and Redux code and Jest to test our React components. Mocha/Chai and Jest are very similar in syntax, except for this annoying difference in that the matchers are different, e.g. to.eq(1) vs toEqual(1). We liked the natural assertion style of Chai, which is also similar to RSpec (which we use extensively for our Rails backend), so we wanted to use Chai-style assertions in our Jest tests. This post explains how to make that possible, still take advantage of some neat new features of Jest's assertion library, and learn something about Object.defineProperty.

Getting Started.

The setup was originally inspired by this post by Ruben Oostinga. You should read through that post for context. The key takeaway is to do two things:

1. Create a setup-test-framework-script.js.

Create setup-test-framework-script.js and place it in your root directory.

const chai = require('chai')

// Make sure chai and jasmine ".not" play nice together
const originalNot = Object.getOwnPropertyDescriptor(chai.Assertion.prototype, 'not').get
Object.defineProperty(chai.Assertion.prototype, 'not', {
  get() {
    Object.assign(this, this.assignedNot)
    return originalNot.apply(this)
  },
  set(newNot) {
    this.assignedNot = newNot
    return newNot
  },
})

// Combine both jest and chai matchers on expect
const originalExpect = global.expect

global.expect = (actual) => {
  const originalMatchers = originalExpect(actual)
  const chaiMatchers = chai.expect(actual)
  const combinedMatchers = Object.assign(chaiMatchers, originalMatchers)
  return combinedMatchers
}

2. Add the script to your Jest configuration.

Inside package.json, under your "jest" configuration:

  "jest": {
    ...
    "setupTestFrameworkScriptFile": "<rootDir>/setup-test-framework-script.js",
  }

Huzzah, We're Done! Well, Not Quite...

This worked great, for a long while. We could happily write expect(1).to.eq(1) in our Jest tests and everyone was happy.

UNTIL.

I came across a neat feature of Jest, where you can assert the number of assertions that should be made. This is useful when you're testing async actions, and want to make sure your assertions are actually fired. Otherwise, if you have a test like this:

it('should work', () => {
  return somethingAsyncAndReject().then(() => {
    expect(1).to.eq(2)
  })
})

and somethingAsync() rejects its promise, this test would silently pass because the .then block was never reached. Sad times. Jest fixes the issue by allowing you to specify that assertions should be made:

it('should work', () => {
  expect.assertions(1)
  return somethingAsyncAndReject().then(() => {
    expect(1).to.eq(2)
  })
})

Then you can get output like this to the console:

expect.assertions(1)

Expected: one assertion
Received: zero assertions
Expected :1
Actual   :0

At least, that's how it works in theory. Using the super-charged, monkey-patched global.expect object in our setup, we get an error:

TypeError: expect.assertions is not a function

This was because in our setup, we set global.expect to only be a function. Recall this snippet:

global.expect = (actual) => {
  ...
}

There ain't no .assertions function on that! We've blindly overridden some useful functionality of expect that Jest provided us. Fortunately, you can give those methods back to the object:

global.expect = (actual) => {
  ...
}
Object.keys(originalExpect).forEach(key => (global.expect[key] = originalExpect[key]))

This allows us to set an expectation around the number of assertions that will be made, but my code was still mysteriously failing, even with this simple example:

it('should work', () => {
  expect.assertions(1)
  expect(1).to.eq(1)
})

I was still receiving an error saying that 1 assertion was expected, but none were made.

Any guesses as to why?

I didn't have any either, and it took me the better part of an hour to figure out.

expect#assertions isn't actually magic, which should come as no surprise. The implementation of it is quite simple, it sets a state variable of the number of expected assertions. After some digging around, I figured out that the variable tracking the number of assertions made was also on that state, called assertionsMade. This variable would be incremented when assertions are made using Jest matchers, but obviously Chai would not do the same, hence the discrepancy. If I had written expect(1).toEqual(1) it would have worked fine, but then I miss out on my original goal of enjoying the natural syntax of Chai and not remembering yet another syntax.

I needed a way to tell the Chai matchers to also increment that value whenever I used it. I knew how to increment the value using this handy method:

originalExpect.setState({ assertionsMade: assertionsMade + 1 })

Telling Chai to run this statement whenever its matchers were accessed was a trickier matter. In comes Object.defineProperty to the rescue! It allows us, among other things, to do something specific whenever that a property is accessed on an object. Essentially it works like this:

const myObj = {}
Object.defineProperty(myObj, 'foo', {
  get() {
    console.log('hello!')
    return 42
  }
})
myObj.foo // logs "hello!", returns 42

This setup allows us to effectively create middleware on an object's properties, with potential use cases like logging the number of times it was accessed. While I don't recommend using it regularly in practice, since Object.defineProperty is clever, it does exactly what we need in this case where we're hacking some functionality together.

With Chai, we always end up using .to in our assertions, so it seemed like a reasonable place to stick our little "middleware." Here's the final code:

global.expect = (actual) => {
  const originalMatchers = originalExpect(actual)
  const chaiMatchers = chai.expect(actual)

  // Add middleware to Chai matchers to increment Jest assertions made
  const { assertionsMade } = originalExpect.getState()
  Object.defineProperty(chaiMatchers, 'to', {
    get() {
      originalExpect.setState({ assertionsMade: assertionsMade + 1 })
      return chai.expect(actual)
    },
  })

  const combinedMatchers = Object.assign(chaiMatchers, originalMatchers)
  return combinedMatchers
}
Object.keys(originalExpect).forEach(key => (global.expect[key] = originalExpect[key]))

Note that we return chai.expect(actual), i.e. the original intended value. We can't return chaiMatchers.to because that creates an infinite loop (whee!).

With this in your setup file, you have everything needed to make assertions about how many assertions should be made while still using the Chai syntax in your Jest tests.

I hope you enjoyed this article and learned something interesting in the process! Feedback is always welcome.

We use Sentry at TransparentClassroom to monitor errors in our front-end application. It's an excellent tool and has proven very useful, but for the longest time we could not get source maps to work correctly. As a consequence, we'd get woefully useless errors like these:

This article quickly covers how we set up source maps using Webpack and got them working correctly on Sentry, using some fixes that were not obvious and not covered by the Sentry documentation. It took me the better part of a day running into dead ends and chasing my tail before it was working end to end; hopefully this post saves you similar pain.

Setting up source maps using Webpack.

Webpack is an incredible tool, and a pain to understand. Fortunately, getting source maps to work on Webpack "should" only require one line to magically work:

config.devtool = /* your source map compilation setting goes here */

I followed an excellent post by SurviveJS to get my source maps working. It turns out source maps can be generated through many different means, which vary in speed and quality. The post covers the different kinds here. For our setup, we do the following:

var production = process.env.NODE_ENV === 'production';

var config = {
  ...
}

if (production) {
  config.devtool = 'source-map';
} else {
  config.devtool = 'eval-source-map';
}

Checking that it works.

If you're like us and use eval-source-map for development, you will not be outputting an actual .map file. See the (edited) output of our webpack:

Version: webpack 1.14.0
                                            Asset       Size  Chunks             Chunk Names
                                application.en.js    5.18 MB       0  [emitted]  application.en
                                    manifest.json    3.71 kB          [emitted]

But, happily, it still works magically in the browser:

Notice the correct stack trace when you click on the error, and how it points to the correct file and line number in boom.js.

In production, the output should look something like this:

Version: webpack 1.14.0
                                                Asset       Size  Chunks             Chunk Names
               application.en-c763e9250b27a905d9e7.js     761 kB       2  [emitted]  application.en
           application.en-c763e9250b27a905d9e7.js.map    4.44 MB       2  [emitted]  application.en
                                        manifest.json    5.04 kB          [emitted]

Gotchas.

Remember to restart your Webpack.

Not doing what you expected? Make sure you restart webpack, before digging in further.

Don't listen to Sentry's setup for source maps.

Some tutorials for setting up source maps, such as this one from Sentry, tell you to manually configure the source map output, like so:

module.exports = {
    // ... other config above ...
    output: {
      path: path.join(__dirname, 'dist'),
      filename: "[name].js",
      source mapFilename: "[name].js.map",
    }
};

My suggestion: do not do this, it will only end in tears.

Watch out for UglifyJS optimization.

You may be optimizing your UglifyJS plugin for production, in which case you'll need to specify that you still want source maps. We do it at the end in a specific segment of code that adds configuration specific to production, but you can place it wherever you actually set up the plugin:

if (production) {
  config.plugins.push(
    new webpack.optimize.UglifyJsPlugin({
      compressor: { warnings: false },
      source map: true // <-- this is what you need
    }),
  );
}

Setting up Sentry to use your source maps.

TransparentClassroom is served through a Rails server running on a Heroku deployment. Based on the source map setup documentation for Sentry, our source maps should've started working magically, but sadly they weren't. Sentry would report a cryptic error when we looked at the details on a user-generated error (note we use a Cloudfront distribution, but hitting www.transparentclassroom.com had the same effect):

Source file was not 'utf8' encoding: https://d2ps218qravhxv.cloudfront.net/webpack/application.en-c763e9250b27a905d9e7.js.map

It turns out that Sentry does not automatically assume source maps are UTF-8 encoded (even though Webpack does this for us). This is because, at least with our Rails server, the .map files had a Content-Type that did not specify UTF-8 encoding:

$ curl -I https://d2ps218qravhxv.cloudfront.net/webpack/application.en-c5ebd83387db86032a23.js.map
HTTP/1.1 200 OK
...snip...
Content-Type: text/plain  # <-- :-(

While some setups have artifacts served from S3 via Cloudfront, we choose to have Cloudfront capture artifacts on a cache miss; so the first time it will hit our server, after which point it will be cached in CF. This meant we needed to change the Content-Type for our .map files, which turned out to be relatively easy with Rails:

# config/initializers/mime_types.rb

Rack::Mime::MIME_TYPES[".map"] = "text/plain; charset=utf-8"

Now when we hit the server, we get the correct Content-Type:

$ curl -I https://d2ps218qravhxv.cloudfront.net/webpack/application.en-c5ebd83387db86032a23.js.map
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8  # :-)

Making this change FINALLY got souremaps working for us in Sentry:

Wrapping up.

Configuring source maps to work correctly in Sentry has been so valuable to us in our debugging process, as it's decidedly unpleasant to dig into minified, webpacked code and attempt to figure out it's corresponding location in your codebase. Hopefully this article has served you well! Let me know your thoughts or if you have any other insights to share!

I recently ran a small exercise to demonstrate the power, limitations, and workarounds of Node. In the process, I gained a deeper understanding of asynchronous operations, multi-threading, and forking. Many thanks to my mentor, Anoakie, for his valuable help in walking along with me for this exploration.

• What Node does really well
• What Node does not so well
• What Node does pretty well
• Conclusion

What Node does really well

Node was built from the ground up with asynchronicity in mind, leveraging the event loop of JavaScript. It can handle a lot of requests quickly by not waiting around for the request when there are certain kinds of work being done for the request, such as database requests.

Imagine you have a database operation that takes 10 seconds to complete, represented by a setTimeout:

router.route('/api/delayed')
  .get(function(req, res) {
    setTimeout(function() {
      res.end('foo');
    }, 10000);
  });

router.route('/api/immediate')
  .get(function(req, res) {
    res.end('bar');
  });

For a back end framework that does not support asynchronous execution, this situation is an anti-pattern: the server will hang as it waits for the database operation to complete and then fulfill the request. In Node, it fires off the operation and then returns to be ready to field the next incoming request. Once the operation finishes, it will be handled in an upcoming cycle of the event loop and the request gets fulfilled.

(In case the & in the bash command throws you, it's essentially a way to tell bash to do two things in parallel.)

# In a synchronous world...
curl http://localhost:3000/api/delayed & curl http://localhost:3000/api/immediate
# this returns 'foo' after 10s and 'bar' right after

# In an asynchronous world...
curl http://localhost:3000/api/delayed & curl http://localhost:3000/api/immediate
# this returns 'bar' right away, and 'foo' 10s later

As long as we only write non-blocking code, our Node server will perform better than other backend languages, right? Right?...

What Node does not so well

JavaScript is a single-threaded scripting language. Compared with other languages where you can spin off multiple threads to do concurrent processing, JavaScript performs work in a single thread.

Node, written in JavaScript, exhibits (suffers?) the same behavior. Some people like single-threaded because it keeps life simple, but it no longer leverages the power of ubiquitous multi-core processors.

Say you have a simple operation inside the Node server which operates on data. It could be simulated with a basic for loop:

router.route('/api/delayed')
  .get(function(req, res) {
    for (var i = 0; i < 1000000000; i++) {}
    res.end('foo');
  });

router.route('/api/immediate')
  .get(function(req, res) {
    res.end('bar');
  });

In this example, asynchronocity will not save you. Run this in a server and it'll take ~2s to process. Imagine your receiving hundreds of concurrent requests for that same operation and you have a major problem on your hands.

curl http://localhost:3000/api/delayed & curl http://localhost:3000/api/immediate
# Returns 'foo' after 2s and 'bar' immediately after

Back end languages like PHP try to address the problem by creating multiple threads in which work can be done. While multi-threading opens up a different can of worms, at least it wouldn't hang in this situation. As a bonus, PHP tries to handle much of the multi-threading for you. (This is based off a very limited understanding of PHP, so corrections here are welcome.)

# Assuming the server is equivalently written in PHP...
curl http://localhost:3000/api/delayed & curl http://localhost:3000/api/immediate
# Returns 'bar' immediately and 'foo' 2s after.

Huh. That's a bummer. Node doesn't handle a commonplace situation nearly as well as PHP. It's beginning to look like a Node production server will need a separate "crunch" cluster to run numbers. Perhaps that separation of concerns (request handling vs. number crunching) is a good idea anyway, but right now it seems like an unfortunate limitation. What can be done about it?

What Node does pretty well

Node provides an easy way to fork multiple instances of Node, creating a cluster. There's an excellent tutorial on the topic. Here's the key bit of code, slightly modified for simplicity:

var cluster = require("cluster");
var numForks = 4;

if (cluster.isMaster) {
  for (var i = 0; i < numForks; i++) {
    cluster.fork();
  }

  cluster.on("exit", function(worker, code, signal) {
    cluster.fork();
  });
} else {
  // Server creation code here
}

With this surprisingly small amount of code, you can create multiple forks. A fork is completely isolated, unlike threads; its in-memory store is not shared. Using this setup, the number-crunching code that originally caused the Node server to hang is now gracefully managed by sending subsequent requests off to forks that are available for doing work.

curl http://localhost:3000/api/delayed & curl http://localhost:3000/api/immediate
# Returns 'bar' immediately and 'foo' 2s after.

With the cluster npm module, Node is back in the game and able to handle intensive data operations, much like PHP.

It's worth reiterating that these two approaches (forking vs. threading) are fundamentally different. With forking, you cannot use multiple cores to speed up the processing of a particular operation. But, it can be used to handle multiple request concurrently when they are blocking operations. With threading, multiple cores can, in theory, be used to speed up the operations on a single request. [EDIT] Forking creates its own process with access to its own memory. Threading, by contrast, preserves access to the same memory (which is both a feature and a source of consternation). However, forking can still be used to speed up the work of a single request. Forked processes can communicate with each other through the child_process.fork() API. It's a similar model to web workers -- create an isolated environment to do some work, do the work, and return the results. Additionally, the cluster module allows for socket sharing across forks. [/EDIT -- thanks to John Jarvis for the tip.]

Conclusion

It's hard to beat Node at asynchronous operations; while other languages like Ruby and Python support it, Node was structured expressly to optimize asynchronocity.

Meanwhile, the cluster module helps Node handle multiple requests with blocking operations concurrently through forks.

As is the case in much of software engineering, choosing one language/framework/technology/data structure or another is about a balance of tradeoffs. Node does some things really well, others not so much. Hopefully this post gave some insight into the balance of forces in Node.